Merge pull request #9 from AgentWorkforce/feature/issue-7-schema-enhancements

feat: implement Agent Trace integration and Issue #7 schema enhancements

Author: khaliqgant

.trajectories/completed/2026-01/traj_cuuwpd2q5rr4.json

@@ -0,0 +1,41 @@
+{
+  "id": "traj_cuuwpd2q5rr4",
+  "version": 1,
+  "task": {
+    "title": "Implement Agent Trace integration (PR #8)"
+  },
+  "status": "completed",
+  "startedAt": "2026-01-30T11:11:11.822Z",
+  "agents": [
+    {
+      "name": "Multi-agent swarm",
+      "role": "lead",
+      "joinedAt": "2026-01-30T11:11:11.850Z"
+    }
+  ],
+  "chapters": [
+    {
+      "id": "chap_hi1s7ri5sozc",
+      "title": "Initial work",
+      "agentName": "Multi-agent swarm",
+      "startedAt": "2026-01-30T11:11:11.850Z",
+      "events": [],
+      "endedAt": "2026-01-30T11:12:26.359Z"
+    }
+  ],
+  "commits": [],
+  "filesChanged": [],
+  "projectId": "/Users/khaliqgant/Projects/agent-workforce/trajectories",
+  "tags": [],
+  "_trace": {
+    "startRef": "57465dbebfe80a229023baaa50484b8c70a14457",
+    "endRef": "9ef63dc773f6f597bd4d92340e0543e41b16528e",
+    "traceId": "trace_imxymv6f8x4b"
+  },
+  "completedAt": "2026-01-30T11:12:26.359Z",
+  "retrospective": {
+    "summary": "Implemented Agent Trace integration for PR #8. Added TraceRecord types, git state capture, trace generation logic, and CLI integration for start/complete/show commands. Updated README with Agent Trace section.",
+    "approach": "Standard approach",
+    "confidence": 0.9
+  }
+}

.trajectories/completed/2026-01/traj_cuuwpd2q5rr4.md

@@ -0,0 +1,21 @@
+# Trajectory: Implement Agent Trace integration (PR #8)
+
+> **Status:** ✅ Completed
+> **Confidence:** 90%
+> **Started:** January 30, 2026 at 12:11 PM
+> **Completed:** January 30, 2026 at 12:12 PM
+
+---
+
+## Summary
+
+Implemented Agent Trace integration for PR #8. Added TraceRecord types, git state capture, trace generation logic, and CLI integration for start/complete/show commands. Updated README with Agent Trace section.
+
+**Approach:** Standard approach
+
+---
+
+## Chapters
+
+### 1. Initial work
+*Agent: Multi-agent swarm*

.trajectories/completed/2026-01/traj_cuuwpd2q5rr4.trace.json

@@ -0,0 +1,26 @@
+{
+  "version": 1,
+  "id": "trace_imxymv6f8x4b",
+  "timestamp": "2026-01-30T11:12:26.413Z",
+  "trajectory": "traj_cuuwpd2q5rr4",
+  "files": [
+    {
+      "path": "README.md",
+      "conversations": [
+        {
+          "contributor": {
+            "type": "agent",
+            "model": "unknown"
+          },
+          "ranges": [
+            {
+              "start_line": 33,
+              "end_line": 62,
+              "revision": "9ef63dc773f6f597bd4d92340e0543e41b16528e"
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}

.trajectories/index.json

@@ -0,0 +1,13 @@
+{
+  "version": 1,
+  "lastUpdated": "2026-01-30T11:12:26.445Z",
+  "trajectories": {
+    "traj_cuuwpd2q5rr4": {
+      "title": "Implement Agent Trace integration (PR #8)",
+      "status": "completed",
+      "startedAt": "2026-01-30T11:11:11.822Z",
+      "completedAt": "2026-01-30T11:12:26.359Z",
+      "path": "/Users/khaliqgant/Projects/agent-workforce/trajectories/.trajectories/completed/2026-01/traj_cuuwpd2q5rr4.json"
+    }
+  }
+}

README.md

@@ -33,6 +33,30 @@ Works with any task system: Beads, Linear, Jira, GitHub Issues, or standalone. T
 ### Integration Ready
 - Complements [claude-mem](https://github.com/thedotmack/claude-mem) for observation-level memory
 - Integrates with [agent-relay](https://github.com/khaliqgant/agent-relay) for multi-agent messaging
+- **Agent Trace integration** - Automatic code attribution following [agent-trace.dev](https://agent-trace.dev) spec
+
+### Code Attribution (Agent Trace)
+
+Trajectories automatically generate [Agent Trace](https://agent-trace.dev) records that attribute code changes to AI agents:
+
+```bash
+trail start "Implement auth module"
+# ... agent writes code, makes commits ...
+trail complete --summary "Added JWT auth" --confidence 0.85
+
+# View trace attribution
+trail show traj_abc123 --trace
+```
+
+**What you get:**
+- `.trace.json` files saved alongside each trajectory
+- Line-level attribution of which code was AI-generated
+- Model identification (Claude, GPT, etc.)
+- Git revision tracking for change history
+
+**Zero configuration required** - traces are generated automatically when completing trajectories in a git repository.
+
+See the full [Agent Trace Integration Spec](./docs/specs/agent-trace-integration.md) for details.
 
 ## Use Cases
 

biome.json

@@ -28,7 +28,9 @@
       "*.md",
       ".beads",
       ".openskills",
-      ".claude"
+      ".claude",
+      ".agent-relay",
+      ".trajectories"
     ]
   }
 }

src/cli/commands/complete.ts

@@ -2,10 +2,43 @@
  * trail complete command
  */
 
+import { existsSync } from "node:fs";
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
 import type { Command } from "commander";
+import { generateTrace, getGitHead } from "../../core/trace.js";
 import { completeTrajectory } from "../../core/trajectory.js";
+import type { TraceRecord, Trajectory } from "../../core/types.js";
 import { FileStorage } from "../../storage/file.js";
 
+/**
+ * Save trace file alongside the trajectory
+ */
+async function saveTraceFile(
+  trajectory: Trajectory,
+  trace: TraceRecord,
+): Promise<void> {
+  // Determine trajectory file location based on status
+  const dataDir = process.env.TRAJECTORIES_DATA_DIR;
+  const baseDir = dataDir ? dataDir : join(process.cwd(), ".trajectories");
+  const completedDir = join(baseDir, "completed");
+
+  const date = new Date(trajectory.completedAt ?? trajectory.startedAt);
+  const monthDir = join(
+    completedDir,
+    `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, "0")}`,
+  );
+
+  // Ensure directory exists
+  if (!existsSync(monthDir)) {
+    await mkdir(monthDir, { recursive: true });
+  }
+
+  // Save trace file with .trace.json extension
+  const tracePath = join(monthDir, `${trajectory.id}.trace.json`);
+  await writeFile(tracePath, JSON.stringify(trace, null, 2), "utf-8");
+}
+
 export function registerCompleteCommand(program: Command): void {
   program
     .command("complete")
@@ -36,16 +69,43 @@ export function registerCompleteCommand(program: Command): void {
         throw new Error("Invalid confidence");
       }
 
-      const completed = completeTrajectory(active, {
+      let completed = completeTrajectory(active, {
         summary: options.summary,
         approach: options.approach || "Standard approach",
         confidence,
       });
 
+      // Generate trace if we have a start reference
+      let trace: TraceRecord | null = null;
+      if (active._trace?.startRef) {
+        trace = generateTrace(completed, active._trace.startRef);
+        if (trace) {
+          // Update trajectory with final trace reference
+          const endRef = getGitHead();
+          completed = {
+            ...completed,
+            _trace: {
+              ...completed._trace,
+              startRef: active._trace.startRef,
+              endRef: endRef ?? undefined,
+              traceId: trace.id,
+            },
+          };
+        }
+      }
+
       await storage.save(completed);
 
+      // Save trace file alongside trajectory if generated
+      if (trace) {
+        await saveTraceFile(completed, trace);
+      }
+
       console.log(`✓ Trajectory completed: ${completed.id}`);
       console.log(`  Summary: ${options.summary}`);
       console.log(`  Confidence: ${Math.round(confidence * 100)}%`);
+      if (trace) {
+        console.log(`  Trace: ${trace.id} (${trace.files.length} files)`);
+      }
     });
 }

src/cli/commands/decision.ts

@@ -30,7 +30,9 @@ export function registerDecisionCommand(program: Command): void {
       }
 
       const alternatives = options.alternatives
-        ? options.alternatives.split(",").map((s: string) => s.trim())
+        ? options.alternatives
+            .split(",")
+            .map((s: string) => ({ option: s.trim(), reason: "" }))
         : [];
 
       const reasoning = options.reasoning || "";
@@ -49,7 +51,10 @@ export function registerDecisionCommand(program: Command): void {
         console.log(`  Reasoning: ${reasoning}`);
       }
       if (alternatives.length > 0) {
-        console.log(`  Alternatives: ${alternatives.join(", ")}`);
+        const altStrings = alternatives.map(
+          (a: { option: string }) => a.option,
+        );
+        console.log(`  Alternatives: ${altStrings.join(", ")}`);
       }
     });
 }

src/cli/commands/show.ts

@@ -3,8 +3,15 @@
  */
 
 import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
 import type { Command } from "commander";
-import type { Decision, Trajectory } from "../../core/types.js";
+import type {
+  Decision,
+  TraceConversation,
+  TraceRecord,
+  Trajectory,
+} from "../../core/types.js";
 import { FileStorage, getSearchPaths } from "../../storage/file.js";
 
 /**
@@ -44,11 +51,47 @@ async function findTrajectory(id: string): Promise<Trajectory | null> {
   return null;
 }
 
+/**
+ * Find and load the trace file for a trajectory
+ */
+async function findTraceFile(id: string): Promise<TraceRecord | null> {
+  const searchPaths = getSearchPaths();
+
+  for (const searchPath of searchPaths) {
+    if (!existsSync(searchPath)) {
+      continue;
+    }
+
+    const completedDir = join(searchPath, "completed");
+    if (!existsSync(completedDir)) {
+      continue;
+    }
+
+    // Search through month directories
+    try {
+      const { readdirSync } = await import("node:fs");
+      const months = readdirSync(completedDir);
+      for (const month of months) {
+        const tracePath = join(completedDir, month, `${id}.trace.json`);
+        if (existsSync(tracePath)) {
+          const content = await readFile(tracePath, "utf-8");
+          return JSON.parse(content) as TraceRecord;
+        }
+      }
+    } catch {
+      // Continue searching
+    }
+  }
+
+  return null;
+}
+
 export function registerShowCommand(program: Command): void {
   program
     .command("show <id>")
     .description("Show trajectory details")
     .option("-d, --decisions", "Show decisions only")
+    .option("-t, --trace", "Show trace information")
     .action(async (id: string, options) => {
       const trajectory = await findTrajectory(id);
 
@@ -57,6 +100,55 @@ export function registerShowCommand(program: Command): void {
         throw new Error("Trajectory not found");
       }
 
+      if (options.trace) {
+        // Show trace information
+        console.log(`Trace for ${trajectory.task.title}:\n`);
+
+        // Show embedded trace reference
+        if (trajectory._trace) {
+          console.log("Trace Reference:");
+          console.log(`  Start Ref: ${trajectory._trace.startRef}`);
+          if (trajectory._trace.endRef) {
+            console.log(`  End Ref:   ${trajectory._trace.endRef}`);
+          }
+          if (trajectory._trace.traceId) {
+            console.log(`  Trace ID:  ${trajectory._trace.traceId}`);
+          }
+          console.log("");
+        }
+
+        // Load and display trace file
+        const trace = await findTraceFile(id);
+        if (trace) {
+          console.log("Trace Details:");
+          console.log(`  ID:        ${trace.id}`);
+          console.log(`  Timestamp: ${trace.timestamp}`);
+          console.log(`  Files:     ${trace.files.length}`);
+          console.log("");
+
+          if (trace.files.length > 0) {
+            console.log("Modified Files:");
+            for (const file of trace.files) {
+              const rangeCount = file.conversations.reduce(
+                (sum: number, conv: TraceConversation) =>
+                  sum + conv.ranges.length,
+                0,
+              );
+              const model =
+                file.conversations[0]?.contributor.model ?? "unknown";
+              console.log(`  • ${file.path}`);
+              console.log(`    Ranges: ${rangeCount}, Model: ${model}`);
+            }
+          }
+        } else if (!trajectory._trace) {
+          console.log("No trace information available");
+          console.log(
+            "Trace is captured when starting a trajectory in a git repo",
+          );
+        }
+        return;
+      }
+
       if (options.decisions) {
         // Show decisions only
         const decisions = extractDecisions(trajectory);
@@ -72,7 +164,10 @@ export function registerShowCommand(program: Command): void {
           console.log(`  Chose: ${decision.chosen}`);
           console.log(`  Reasoning: ${decision.reasoning}`);
           if (decision.alternatives.length > 0) {
-            console.log(`  Alternatives: ${decision.alternatives.join(", ")}`);
+            const altStrings = decision.alternatives.map((a) =>
+              typeof a === "string" ? a : a.option,
+            );
+            console.log(`  Alternatives: ${altStrings.join(", ")}`);
           }
           console.log("");
         }