Track artifacts in recap

[acreeger]

Summary

Add an artifacts array to the recap schema to track things created during a loom session (comments, issues, PRs, etc.). This enables:

• Quick reference links in the recap panel (filter by type for display)
• Audit trail of what got created during the session
• Foundation for future reset capability

Schema Addition

{
  "filePath": "...",
  "goal": null,
  "entries": [...],
  "artifacts": [
    {
      "id": "IC_kwDON...",
      "type": "comment",
      "primaryUrl": "https://github.com/owner/repo/issues/123#issuecomment-...",
      "urls": {},
      "description": "Progress update: completed API integration",
      "timestamp": "2025-12-15T10:23:45Z"
    },
    {
      "id": "349",
      "type": "issue",
      "primaryUrl": "https://github.com/owner/repo/issues/349",
      "urls": {
        "api": "https://api.github.com/repos/owner/repo/issues/349"
      },
      "description": "Follow-up: Add retry logic to API client",
      "timestamp": "2025-12-15T11:45:00Z"
    }
  ]
}

Artifact Types

• comment - Issue or PR comment
• issue - New issue created
• pr - Pull request created
• (extensible for future types)

URL Structure

• primaryUrl - Main URL for display/navigation (required)
• urls - Object with optional named URL variants (can be empty {}):
  • web - Browser URL (if different from primaryUrl)
  • api - API endpoint
  • (extensible for other contexts)

Implementation

1. Update recap schema - Add artifacts array with type and URL fields
2. Add MCP tool - add_artifact tool that Claude calls after creating things
3. Update prompts - Tell Claude to log artifacts after creating them (coordinate with Update prompts to use Loom Recap MCP #347)

Prompt Updates Required

The issue, PR, and branch prompts must be updated to instruct Claude to:

• Call add_artifact after creating comments via issue management MCP
• Call add_artifact after creating issues or PRs
• Include meaningful descriptions for each artifact

UI Usage

The recap panel can filter artifacts by type:

• Comments section: artifacts.filter(a => a.type === 'comment')
• Related issues: artifacts.filter(a => a.type === 'issue')

Related

• Part of the Loom Context Panel feature set
• Depends on Loom Recap MCP Server #346 (Recap MCP Server)
• Coordinate prompt updates with Update prompts to use Loom Recap MCP #347

[acreeger]

Hook Integration

The phase boundary hook (#348) should remind the orchestrator to use add_artifact whenever an agent stops working. This ensures comment URLs get captured even if the orchestrator forgets to log them inline.

Hook reminder text should include:

If you created or updated any comments during this phase, use add_artifact to record them in the recap with their URLs.

[acreeger]

Complexity Assessment

Classification: SIMPLE

Metrics:

• Estimated files affected: 7
• Estimated lines of code: 180
• Breaking changes: No
• Database migrations: No
• Cross-cutting changes: No
• File architecture quality: Good - recap-server.ts is well-structured at 225 LOC with clear separation of concerns
• Overall risk level: Low

Reasoning: This is a localized, additive enhancement to the existing recap system. The schema extension (adding artifacts array to RecapFile), MCP tool implementation (add_artifact), and prompt updates are straightforward with no architectural complexity or system-wide impact.

[acreeger]

Analysis Phase

• Fetch issue details and understand requirements
• Research existing recap schema and MCP server implementation
• Research prompt templates that need updates
• Identify all affected files with line references
• Document technical findings and dependencies

Status: Complete

---

Executive Summary

This issue adds an artifacts array to the recap schema to track items created during loom sessions (comments, issues, PRs). The implementation requires: (1) extending the RecapFile interface and RecapOutput type, (2) adding a new add_artifact MCP tool to recap-server.ts, and (3) updating 10 prompt/agent template files to instruct Claude to call add_artifact after creating comments or issues.

Impact Summary

• 3 core recap module files requiring modification
• 10 template files requiring prompt updates
• No breaking changes - additive schema extension with optional field
• Low risk - follows existing patterns (add_entry tool implementation)

---

Complete Technical Reference (click to expand for implementation details)

Problem Space Research

Problem Understanding

The recap panel captures session context (goal, decisions, insights, risks) but currently has no way to track artifacts created during the session. Users want quick-reference links to comments/issues/PRs they created, an audit trail of session output, and foundation for future reset capability.

Architectural Context

The recap system consists of:

• Type definitions in src/mcp/recap-types.ts (RecapFile, RecapEntry, RecapOutput)
• MCP server in src/mcp/recap-server.ts with tools: set_goal, add_entry, get_recap
• CLI command in src/commands/recap.ts for reading recaps
• Prompts/agents that instruct Claude when to use recap tools

Edge Cases Identified

• Empty urls object: Schema allows urls: {} which is valid and should be handled
• Duplicate artifacts: Same artifact could be added multiple times if agent retries - consider deduplication by id

Codebase Research Findings

Affected Area: Recap MCP Server

Entry Point: /Users/adam/Documents/Projects/iloom-cli/feat-issue-351__track-artifacts/src/mcp/recap-server.ts
Dependencies:

• Uses: recap-types.ts (types), MetadataManager.ts (LoomMetadata type), fs-extra, zod, MCP SDK
• Used By: Claude sessions via MCP protocol, VS Code extension via file watching

Similar Patterns Found

• /Users/adam/Documents/Projects/iloom-cli/feat-issue-351__track-artifacts/src/mcp/recap-server.ts:137-171 - add_entry tool registration pattern to follow for add_artifact

Affected Files

Core Recap Module Files

1. /Users/adam/Documents/Projects/iloom-cli/feat-issue-351__track-artifacts/src/mcp/recap-types.ts:10-48 - Add artifact types and interfaces

   • Add RecapArtifactType type union: 'comment' | 'issue' | 'pr'
   • Add RecapArtifact interface with: id, type, primaryUrl, urls, description, timestamp
   • Extend RecapFile interface (line 21-24) to include optional artifacts?: RecapArtifact[]
   • Extend RecapOutput interface (line 26-31) to include artifacts: RecapArtifact[]
   • Add AddArtifactInput interface for tool input validation
   • Add AddArtifactOutput interface for tool response

2. /Users/adam/Documents/Projects/iloom-cli/feat-issue-351__track-artifacts/src/mcp/recap-server.ts:137-209 - Add add_artifact MCP tool

   • Register new tool following add_entry pattern (lines 137-171)
   • Input schema: type (enum), primaryUrl (string), description (string), optional id (string), optional urls (object)
   • Output schema: id (string), timestamp (string)
   • Handler: read file, push to artifacts array (create if missing), write file

3. /Users/adam/Documents/Projects/iloom-cli/feat-issue-351__track-artifacts/src/commands/recap.ts:60-79 - Update CLI output to include artifacts

   • Extend RecapOutput handling to read/display artifacts array
   • Add artifacts count to human-readable output

Template Files (Prompt Updates)

All 10 template files need guidance added to instruct Claude to call add_artifact after creating comments/issues/PRs.

4. /Users/adam/Documents/Projects/iloom-cli/feat-issue-351__track-artifacts/templates/prompts/issue-prompt.txt - Add artifact logging instructions

   • After comment creation steps, add: "After creating a comment, call recap.add_artifact with type='comment', primaryUrl=[comment URL], description=[brief description]"

5. /Users/adam/Documents/Projects/iloom-cli/feat-issue-351__track-artifacts/templates/prompts/pr-prompt.txt - Add artifact logging instructions (same pattern)

6. /Users/adam/Documents/Projects/iloom-cli/feat-issue-351__track-artifacts/templates/prompts/regular-prompt.txt - Add artifact logging instructions (same pattern)

7. /Users/adam/Documents/Projects/iloom-cli/feat-issue-351__track-artifacts/templates/agents/iloom-issue-analyzer.md - Add to tools list and comment_tool_info section

   • Line 4: Add mcp__recap__add_artifact to tools list
   • After comment creation example, add artifact logging instruction

8. /Users/adam/Documents/Projects/iloom-cli/feat-issue-351__track-artifacts/templates/agents/iloom-issue-planner.md - Same pattern as analyzer

9. /Users/adam/Documents/Projects/iloom-cli/feat-issue-351__track-artifacts/templates/agents/iloom-issue-implementer.md - Same pattern

10. /Users/adam/Documents/Projects/iloom-cli/feat-issue-351__track-artifacts/templates/agents/iloom-issue-enhancer.md - Same pattern

    • Note: Does not currently have recap tools in tools list - needs them added

11. /Users/adam/Documents/Projects/iloom-cli/feat-issue-351__track-artifacts/templates/agents/iloom-issue-complexity-evaluator.md - Same pattern

12. /Users/adam/Documents/Projects/iloom-cli/feat-issue-351__track-artifacts/templates/agents/iloom-issue-analyze-and-plan.md - Same pattern

13. /Users/adam/Documents/Projects/iloom-cli/feat-issue-351__track-artifacts/templates/agents/iloom-issue-reviewer.md - Same pattern

    • Note: Does not currently have recap tools in tools list - needs them added

Integration Points

• RecapFile type flows: recap-types.ts -> recap-server.ts -> recap.ts (CLI)
• RecapOutput type flows: recap-types.ts -> recap-server.ts (get_recap response) -> CLI/VS Code extension
• Templates are copied to dist/ during build (see build process)

[acreeger]

Implementation Plan for Issue #351

Summary

Add an artifacts array to the recap schema to track items created during loom sessions (comments, issues, PRs). This involves: (1) extending RecapFile and RecapOutput types with artifact definitions, (2) adding an add_artifact MCP tool to recap-server.ts following the existing add_entry pattern, (3) updating the CLI output to display artifacts, and (4) updating 10+ prompt/template files to instruct Claude to call add_artifact after creating comments, issues, or PRs.

Questions and Key Decisions

Question	Answer	Rationale
Should duplicate artifacts be allowed?	No - replace by primaryUrl	Prevents duplicate entries when agents retry operations; primaryUrl is the canonical identifier for an artifact

High-Level Execution Phases

1. Type Definitions: Add RecapArtifact interface and artifact types to recap-types.ts
2. MCP Tool: Implement add_artifact tool in recap-server.ts following add_entry pattern (with deduplication by primaryUrl)
3. CLI Update: Extend RecapCommand to display artifacts in output
4. Prompt Updates: Add artifact logging instructions to all prompts that create comments/issues/PRs
5. Testing: Add tests for add_artifact tool and CLI output

Quick Stats

• 0 files for deletion
• 3 core files to modify (recap-types.ts, recap-server.ts, recap.ts)
• 10 template files to modify
• 1 test file to modify (recap.test.ts)
• Dependencies: None
• Estimated complexity: Simple

---

Complete Implementation Guide (click to expand for step-by-step details)

Automated Test Cases to Create

Test File: /Users/adam/Documents/Projects/iloom-cli/feat-issue-351__track-artifacts/src/commands/recap.test.ts (MODIFY)

Purpose: Add tests for artifacts array in RecapOutput

Click to expand test structure (25 lines)

describe('execute with artifacts', () => {
  it('should return artifacts array when present in recap file', async () => {
    // Mock recap with artifacts array
    // Verify artifacts are returned in RecapOutput
  })

  it('should return empty artifacts array when not present', async () => {
    // Mock recap without artifacts field
    // Verify empty array is returned
  })

  it('should print artifacts count in human-readable output', async () => {
    // Mock recap with artifacts
    // Verify console.log includes artifacts count
  })
})

describe('add_artifact deduplication', () => {
  it('should replace existing artifact with same primaryUrl', async () => {
    // Add artifact with primaryUrl X
    // Add another artifact with same primaryUrl X but different description
    // Verify only one artifact exists with the updated description
  })

  it('should add new artifact when primaryUrl is unique', async () => {
    // Add artifact with primaryUrl X
    // Add another artifact with primaryUrl Y
    // Verify both artifacts exist
  })
})

Files to Modify

1. /Users/adam/Documents/Projects/iloom-cli/feat-issue-351__track-artifacts/src/mcp/recap-types.ts:10-54

Change: Add artifact type definitions and extend RecapFile/RecapOutput interfaces

Insert after line 10 (after RecapEntryType definition):

/** Artifact types for tracking created items */
export type RecapArtifactType = 'comment' | 'issue' | 'pr'

/** Single artifact entry */
export interface RecapArtifact {
  id: string
  type: RecapArtifactType
  primaryUrl: string
  urls: Record<string, string>
  description: string
  timestamp: string
}

Modify RecapFile interface (line 21-24) to add optional artifacts:

export interface RecapFile {
  goal?: string | null
  entries?: RecapEntry[]
  artifacts?: RecapArtifact[]
}

Modify RecapOutput interface (line 26-31) to include artifacts:

export interface RecapOutput {
  filePath: string
  goal: string | null
  entries: RecapEntry[]
  artifacts: RecapArtifact[]
}

Add input/output interfaces for add_artifact tool after line 48:

/** Input for add_artifact tool */
export interface AddArtifactInput {
  type: RecapArtifactType
  primaryUrl: string
  description: string
  id?: string
  urls?: Record<string, string>
}

/** Output for add_artifact tool */
export interface AddArtifactOutput {
  id: string
  timestamp: string
  replaced: boolean  // Indicates if an existing artifact was replaced
}

2. /Users/adam/Documents/Projects/iloom-cli/feat-issue-351__track-artifacts/src/mcp/recap-server.ts:17,171-209

Change: Update import and add add_artifact MCP tool with deduplication logic

Modify line 17 to include new types:

import type { RecapFile, RecapEntry, RecapOutput, RecapArtifact } from './recap-types.js'

Insert new tool registration after line 171 (after add_entry tool, before get_recap tool):

Click to expand add_artifact tool implementation with deduplication (45 lines)

// Register add_artifact tool
server.registerTool(
  'add_artifact',
  {
    title: 'Add Artifact',
    description: 'Track an artifact (comment, issue, PR) created during the session. If an artifact with the same primaryUrl already exists, it will be replaced.',
    inputSchema: {
      type: z.enum(['comment', 'issue', 'pr']).describe('Artifact type'),
      primaryUrl: z.string().url().describe('Main URL for the artifact'),
      description: z.string().describe('Brief description of the artifact'),
      id: z.string().optional().describe('Optional artifact ID (e.g., comment ID, issue number)'),
      urls: z.record(z.string()).optional().describe('Optional additional URLs (e.g., { api: "..." })'),
    },
    outputSchema: {
      id: z.string(),
      timestamp: z.string(),
      replaced: z.boolean(),
    },
  },
  async ({ type, primaryUrl, description, id, urls }) => {
    const filePath = getRecapFilePath()
    const recap = await readRecapFile(filePath)
    
    const artifact: RecapArtifact = {
      id: id ?? randomUUID(),
      type,
      primaryUrl,
      urls: urls ?? {},
      description,
      timestamp: new Date().toISOString(),
    }
    
    recap.artifacts ??= []
    
    // Deduplication: replace existing artifact with same primaryUrl
    const existingIndex = recap.artifacts.findIndex(a => a.primaryUrl === primaryUrl)
    const replaced = existingIndex !== -1
    
    if (replaced) {
      // Preserve the original id if not explicitly provided
      artifact.id = id ?? recap.artifacts[existingIndex].id
      recap.artifacts[existingIndex] = artifact
    } else {
      recap.artifacts.push(artifact)
    }
    
    await writeRecapFile(filePath, recap)
    const result = { id: artifact.id, timestamp: artifact.timestamp, replaced }
    return {
      content: [{ type: 'text' as const, text: JSON.stringify(result) }],
      structuredContent: result,
    }
  }
)

Modify get_recap tool (lines 194-208) to include artifacts in output:

Line 199 (inside the handler):

const result: RecapOutput = {
  filePath,
  goal: recap.goal ?? defaultGoal,
  entries: recap.entries ?? [],
  artifacts: recap.artifacts ?? [],
}

Update outputSchema (lines 181-192) to include artifacts array:

outputSchema: {
  filePath: z.string(),
  goal: z.string().nullable(),
  entries: z.array(/* existing schema */),
  artifacts: z.array(
    z.object({
      id: z.string(),
      type: z.enum(['comment', 'issue', 'pr']),
      primaryUrl: z.string(),
      urls: z.record(z.string()),
      description: z.string(),
      timestamp: z.string(),
    })
  ),
},

3. /Users/adam/Documents/Projects/iloom-cli/feat-issue-351__track-artifacts/src/commands/recap.ts:60-79

Change: Update CLI output to include artifacts

Modify line 63 to read artifacts:

const artifacts = recap.artifacts ?? []
const result: RecapOutput = { filePath, goal, entries, artifacts }

Add artifacts output after line 79 (after entries loop):

// eslint-disable-next-line no-console
console.log(`Artifacts: ${artifacts.length}`)
for (const artifact of artifacts) {
  // eslint-disable-next-line no-console
  console.log(`  [${artifact.type}] ${artifact.description} - ${artifact.primaryUrl}`)
}

4-13. Template Files (Prompt Updates)

All template files that involve creating comments, issues, or PRs need artifact logging instructions added.

4. /Users/adam/Documents/Projects/iloom-cli/feat-issue-351__track-artifacts/templates/prompts/issue-prompt.txt

Change: Add artifact logging instruction after comment creation steps

Insert in the Loom Recap section (around line 36-37):

- `recap.add_artifact` - After creating/updating comments, issues, or PRs, log them with type, primaryUrl, and description. Duplicates with the same primaryUrl will be replaced.

Insert reminder after comment creation workflow sections:

**IMPORTANT**: After creating or updating any issue comment, call `recap.add_artifact` with:
- type: 'comment'
- primaryUrl: The full comment URL (e.g., https://github.com/owner/repo/issues/123#issuecomment-456)
- description: Brief description of the comment's purpose

5. /Users/adam/Documents/Projects/iloom-cli/feat-issue-351__track-artifacts/templates/prompts/pr-prompt.txt

Change: Same pattern as issue-prompt.txt - add artifact logging for comments

Insert in Loom Recap section (around line 37):

- `recap.add_artifact` - After creating/updating comments, issues, or PRs, log them with type, primaryUrl, and description. Duplicates with the same primaryUrl will be replaced.

6. /Users/adam/Documents/Projects/iloom-cli/feat-issue-351__track-artifacts/templates/prompts/regular-prompt.txt

Change: Same pattern - add artifact logging in Loom Recap section (around line 37)

7. /Users/adam/Documents/Projects/iloom-cli/feat-issue-351__track-artifacts/templates/agents/iloom-issue-analyzer.md

Change: Add mcp__recap__add_artifact to tools list and add usage guidance

Modify line 4 (tools list) - append:

, mcp__recap__add_artifact

Add to Loom Recap section (after line 24):

- `recap.add_artifact` - After creating any comment, log it with type='comment', primaryUrl, and description. Re-calling with the same primaryUrl will update the existing entry.

8. /Users/adam/Documents/Projects/iloom-cli/feat-issue-351__track-artifacts/templates/agents/iloom-issue-planner.md

Change: Add mcp__recap__add_artifact to tools list (line 4) and add usage guidance to Loom Recap section

9. /Users/adam/Documents/Projects/iloom-cli/feat-issue-351__track-artifacts/templates/agents/iloom-issue-implementer.md

Change: Add mcp__recap__add_artifact to tools list (line 4) - note this agent doesn't currently have recap tools, so add full set

Modify line 4 - append to tools list:

, mcp__recap__get_recap, mcp__recap__add_entry, mcp__recap__add_artifact

Add Loom Recap section before Core Responsibilities (around line 10):

## Loom Recap

After creating or updating any issue comment, use the Recap MCP tools:
- `recap.add_artifact` - Log comments with type='comment', primaryUrl (full URL with comment ID), and description. Re-calling with the same primaryUrl will update the existing entry.

This enables the recap panel to show quick-reference links to artifacts created during the session.

10. /Users/adam/Documents/Projects/iloom-cli/feat-issue-351__track-artifacts/templates/agents/iloom-issue-enhancer.md

Change: Add mcp__recap__add_artifact to tools list (line 4)

Modify line 4 - append:

, mcp__recap__get_recap, mcp__recap__add_entry, mcp__recap__add_artifact

Add artifact logging guidance after comment creation steps.

11. /Users/adam/Documents/Projects/iloom-cli/feat-issue-351__track-artifacts/templates/agents/iloom-issue-complexity-evaluator.md

Change: Add mcp__recap__add_artifact to tools list (line 4)

Modify line 4 - append:

, mcp__recap__get_recap, mcp__recap__add_entry, mcp__recap__add_artifact

12. /Users/adam/Documents/Projects/iloom-cli/feat-issue-351__track-artifacts/templates/agents/iloom-issue-analyze-and-plan.md

Change: Add mcp__recap__add_artifact to tools list (line 4)

Modify line 4 - append:

, mcp__recap__add_artifact

Update Loom Recap section to include artifact logging guidance.

13. /Users/adam/Documents/Projects/iloom-cli/feat-issue-351__track-artifacts/templates/agents/iloom-issue-reviewer.md

Change: Add recap tools including mcp__recap__add_artifact to tools list (line 4)

Modify line 4 - append:

, mcp__recap__get_recap, mcp__recap__add_entry, mcp__recap__add_artifact

Add Loom Recap section with artifact logging guidance.

Detailed Execution Order

Phase 1: Type Definitions

1. Edit /Users/adam/Documents/Projects/iloom-cli/feat-issue-351__track-artifacts/src/mcp/recap-types.ts - Add RecapArtifactType, RecapArtifact, extend RecapFile and RecapOutput, add AddArtifactInput/Output (with replaced field)
   • Verify: TypeScript compiles without errors

Phase 2: MCP Tool Implementation

1. Edit /Users/adam/Documents/Projects/iloom-cli/feat-issue-351__track-artifacts/src/mcp/recap-server.ts - Update import to include RecapArtifact
2. Edit recap-server.ts - Add add_artifact tool registration after add_entry (line 172) with deduplication logic:
   • Check if artifact with same primaryUrl exists using findIndex
   • If exists: replace at that index, preserve original id if not explicitly provided
   • If not exists: push new artifact
3. Edit recap-server.ts - Update get_recap outputSchema to include artifacts array
4. Edit recap-server.ts - Update get_recap handler to return artifacts
   • Verify: pnpm build succeeds

Phase 3: CLI Update

1. Edit /Users/adam/Documents/Projects/iloom-cli/feat-issue-351__track-artifacts/src/commands/recap.ts - Update result construction to include artifacts
2. Edit recap.ts - Add artifacts output in human-readable mode
   • Verify: pnpm build succeeds

Phase 4: Tests

1. Edit /Users/adam/Documents/Projects/iloom-cli/feat-issue-351__track-artifacts/src/commands/recap.test.ts - Add test cases for artifacts including deduplication tests
   • Verify: pnpm test passes

Phase 5: Template Updates

1. Update all 10 template files with mcp__recap__add_artifact in tools lists and add usage guidance (mentioning that duplicates by primaryUrl are replaced)
   • Verify: Templates are syntactically valid

Phase 6: Final Validation

1. Run pnpm build - Verify TypeScript compiles
2. Run pnpm test - Verify all tests pass
3. Run pnpm lint - Verify no lint errors

Dependencies and Configuration

None - this is an additive change using existing dependencies (zod, fs-extra, MCP SDK).

[acreeger]

Implementation Complete - Issue #351

Summary

Added artifact tracking to the recap system, enabling Claude agents to log comments, issues, and PRs created during sessions. The implementation includes a new add_artifact MCP tool with deduplication by primaryUrl, updated type definitions, CLI output for artifacts, and prompt/template updates to instruct agents to use the tool.

Changes Made

• recap-types.ts: Added RecapArtifact interface, RecapArtifactType, extended RecapFile/RecapOutput
• recap-server.ts: Implemented add_artifact MCP tool with deduplication, updated get_recap output
• recap.ts: Updated CLI to display artifacts in human-readable output
• recap.test.ts: Added tests for artifacts array and CLI output
• 10 template files: Added mcp__recap__add_artifact to tools lists and Loom Recap sections

Validation Results

• Tests: 3011 passed / 3012 total (1 skipped)
• Typecheck: Passed
• Lint: Passed

---

Detailed Changes by File (click to expand)

Files Modified

/src/mcp/recap-types.ts

Changes: Added artifact type definitions and extended interfaces

• Added RecapArtifactType union type: 'comment' | 'issue' | 'pr'
• Added RecapArtifact interface with id, type, primaryUrl, urls, description, timestamp
• Extended RecapFile with optional artifacts?: RecapArtifact[]
• Extended RecapOutput with required artifacts: RecapArtifact[]
• Added AddArtifactInput and AddArtifactOutput interfaces

/src/mcp/recap-server.ts

Changes: Implemented add_artifact MCP tool and updated get_recap

• Added add_artifact tool registration with deduplication by primaryUrl
• Updated get_recap outputSchema to include artifacts array
• Updated get_recap handler to return artifacts: recap.artifacts ?? []

/src/commands/recap.ts

Changes: Updated CLI output to include artifacts

• Added artifacts to RecapOutput construction
• Added human-readable output: "Artifacts: N" and list of artifacts

/src/commands/recap.test.ts

Changes: Added test coverage for artifacts

• Updated existing tests to verify artifacts array in output
• Added test for empty artifacts when field missing from file
• Updated console output tests to verify artifacts display

Template Files (10 files)

All templates updated to include mcp__recap__add_artifact in tools list and add artifact logging guidance:

• templates/prompts/issue-prompt.txt
• templates/prompts/pr-prompt.txt
• templates/prompts/regular-prompt.txt
• templates/agents/iloom-issue-analyzer.md
• templates/agents/iloom-issue-planner.md
• templates/agents/iloom-issue-implementer.md
• templates/agents/iloom-issue-enhancer.md
• templates/agents/iloom-issue-complexity-evaluator.md
• templates/agents/iloom-issue-analyze-and-plan.md
• templates/agents/iloom-issue-reviewer.md

Dependencies Added

None

[acreeger]

Fixing Agent Templates - add_artifact in comment_tool_info - Complete

Summary

Added add_artifact guidance to the <comment_tool_info> sections in all 7 agent templates. The guidance is now integrated into the workflow steps (step 2) and includes an updated Example Usage section showing the add_artifact call after creating comments.

Changes Made

• 7 agent templates: Added add_artifact guidance to workflow step 2 and Example Usage sections

Validation Results

• Build: Passed
• Tests: 3011 passed / 3012 total (1 skipped)

---

Detailed Changes by File (click to expand)

Files Modified

templates/agents/iloom-issue-analyzer.md

Changes: Added add_artifact guidance to step 2 of Workflow Comment Strategy and added add_artifact call to Example Usage

templates/agents/iloom-issue-planner.md

Changes: Added add_artifact guidance to step 2 of Workflow Comment Strategy and added add_artifact call to Example Usage

templates/agents/iloom-issue-implementer.md

Changes: Added add_artifact guidance to step 2 of Workflow Comment Strategy and added add_artifact call to Example Usage

templates/agents/iloom-issue-enhancer.md

Changes: Added add_artifact guidance to step 2 of Workflow Comment Strategy and added add_artifact call to Example Usage

templates/agents/iloom-issue-complexity-evaluator.md

Changes: Added add_artifact guidance to step 2 of Workflow Comment Strategy and added add_artifact call to Example Usage

templates/agents/iloom-issue-analyze-and-plan.md

Changes: Added add_artifact guidance to step 2 of Workflow Comment Strategy and added add_artifact call to Example Usage

templates/agents/iloom-issue-reviewer.md

Changes: Added add_artifact guidance to step 2 of Workflow Comment Strategy and added add_artifact call to Example Usage

Dependencies Added

None

[acreeger]

Research: Hook-Based Artifact Capture - Complete

Executive Summary

Hook-based artifact capture is technically feasible but architecturally problematic. PostToolUse hooks receive full tool_response data (including URLs returned by MCP tools), making deterministic capture possible. However, hooks cannot call MCP tools - they are external processes without access to Claude's MCP transport. The hook would need to write directly to the recap.json file, bypassing the MCP server and introducing race condition risks.

Questions and Key Decisions

Question	Answer
Can hooks access tool output (comment URLs)?	Yes - tool_response field in stdin JSON contains full MCP tool output
Can hooks call MCP tools like add_artifact?	No - hooks are external processes, cannot access Claude's MCP transport
What tools should be monitored?	mcp__issue_management__create_comment, create_issue (if added), gh pr create (Bash)
Preferred approach?	Direct file write from hook (bypasses MCP) or agent-based (current implementation)

HIGH/CRITICAL Risks

• Race conditions: Hook writing directly to recap.json while recap-server MCP is active could corrupt data
• Architectural bypass: Hooks writing to files managed by MCP servers violates separation of concerns

Impact Summary

• 2 files would need modification: templates/hooks/iloom-hook.js, recap file logic
• Would require file locking mechanism to prevent race conditions
• Alternative: Keep current agent-based approach with prompt improvements

---

Complete Technical Reference (click to expand for implementation details)

Problem Space Research

Problem Understanding

The current implementation asks agents to manually call add_artifact after creating comments. This is non-deterministic - agents may forget, especially under complex workflows. A PostToolUse hook could automatically capture artifacts whenever specific MCP tools complete successfully.

Architectural Context

• Hooks run as external Node.js processes invoked by Claude Code
• Hooks receive tool data via stdin JSON, can only provide feedback via stdout JSON
• MCP servers run as separate stdio-connected processes managed by Claude Code
• Recap file is written by recap-server MCP at ~/.config/iloom-ai/recaps/{slugified-path}.json

Edge Cases Identified

• Concurrent access: Hook and MCP server both writing to recap.json simultaneously
• Tool failures: Hook should only capture on successful tool responses (check tool_response.url exists)
• Partial data: Some tool responses may not include all expected fields

Third-Party Research Findings

Claude Code Hooks PostToolUse Event

Source: WebSearch + Claude Code Hooks Documentation
Key Findings:

1. stdin JSON schema for PostToolUse:

{
  "session_id": "abc123",
  "hook_event_name": "PostToolUse",
  "tool_name": "mcp__issue_management__create_comment",
  "tool_input": {
    "number": "351",
    "body": "comment text",
    "type": "issue"
  },
  "tool_response": {
    "id": "3663246553",
    "url": "https://github.com/owner/repo/issues/351#issuecomment-3663246553",
    "created_at": "2025-12-17T01:48:41Z"
  },
  "tool_use_id": "toolu_01ABC123...",
  "cwd": "/path/to/project"
}

2. Environment variables available:

   • CLAUDE_PROJECT_DIR: Project root
   • No RECAP_FILE_PATH - would need to compute from cwd

3. Hook output capabilities:

   • Can provide feedback with {"decision": "block", "reason": "..."}
   • Cannot call MCP tools
   • Cannot modify tool response
   • Cannot directly interact with other Claude processes

Reference: https://code.claude.com/docs/en/hooks

Known Issue with PostToolUse JSON Processing

Source: GitHub Issue #3983

• "decision": "block" is required for reason field to be visible to Claude
• Hook feedback appears as user message, not system message
• Counter-intuitive but functional

Codebase Research Findings

Existing Hook: /Users/adam/Documents/Projects/iloom-cli/feat-issue-351__track-artifacts/templates/hooks/iloom-hook.js

Current behavior: Broadcasts session status to VS Code extension via Unix sockets
Pattern:

• Reads JSON from stdin via readStdin()
• Extracts hook_event_name, tool_name, tool_input, tool_response from hookData
• Currently passes tool_name and tool_input to socket broadcast (lines 167-168)
• Does NOT use tool_response currently

Recap Server: /Users/adam/Documents/Projects/iloom-cli/feat-issue-351__track-artifacts/src/mcp/recap-server.ts

How add_artifact works (lines 174-228):

1. Gets file path from RECAP_FILE_PATH environment variable
2. Reads existing recap file (or empty object if missing)
3. Creates artifact object with id, type, primaryUrl, urls, description, timestamp
4. Deduplicates by primaryUrl (replaces existing if found)
5. Writes updated recap file with fs-extra.writeFile

Recap File Path Resolution: /Users/adam/Documents/Projects/iloom-cli/feat-issue-351__track-artifacts/src/utils/mcp.ts

Algorithm (lines 103-108):

function slugifyPath(loomPath: string): string {
  let slug = loomPath.replace(/[/\\]+$/, '')
  slug = slug.replace(/[/\\]/g, '___')
  slug = slug.replace(/[^a-zA-Z0-9_-]/g, '-')
  return `${slug}.json`
}

File stored at: ~/.config/iloom-ai/recaps/{slugified-path}.json

Issue Management MCP Tools: /Users/adam/Documents/Projects/iloom-cli/feat-issue-351__track-artifacts/src/mcp/issue-management-server.ts

Tools to monitor for artifact capture:

1. create_comment (lines 198-247)

   • Input: { number, body, type }
   • Output: { id, url, created_at }
   • Artifact type: comment

2. update_comment (lines 249-296)

   • Input: { commentId, number, body }
   • Output: { id, url, updated_at }
   • Artifact type: comment (should update existing by primaryUrl)

Not yet implemented but would need monitoring:

• create_issue (if added)
• create_pr (if added)

Bash Tools That Create Artifacts

From templates, these Bash commands create artifacts:

• gh pr create - Creates PR
• gh issue create - Creates issue (not commonly used in agents)

Would require pattern matching on tool_name: "Bash" and tool_input.command regex.

Affected Files for Hook Implementation

If implementing hook-based approach:

1. /Users/adam/Documents/Projects/iloom-cli/feat-issue-351__track-artifacts/templates/hooks/iloom-hook.js

   • Add handler for PostToolUse with tool_name matching mcp__issue_management__create_comment
   • Extract tool_response.url and write to recap file
   • Would need to compute recap file path from cwd

2. New utility or inline in hook: Recap file path computation

   • Replicate slugifyPath algorithm
   • Build path: ~/.config/iloom-ai/recaps/{slugified-cwd}.json

Medium Severity Risks

• File path computation: Hook needs to replicate slugifyPath algorithm - mismatch could write to wrong file
• File format: Hook needs to match RecapFile schema exactly or MCP server/CLI may reject file
• No deduplication without reading: Hook would need read-modify-write pattern, increasing complexity

Tradeoffs Analysis

Hook-Based Approach

Advantages:

• Deterministic capture - no agent forgetfulness
• Works even if agent prompt doesn't mention add_artifact
• Centralized logic in one place

Disadvantages:

• Cannot call MCP tools - must write file directly
• Race conditions with recap-server MCP
• Violates architectural separation (hook bypasses MCP)
• Harder to test (requires Claude Code execution)
• Must replicate file path algorithm
• Must maintain JSON schema compatibility

Agent-Based Approach (Current)

Advantages:

• Uses proper MCP channel with deduplication
• No race conditions (single writer)
• Easier to test (just MCP server tests)
• Agents can provide meaningful descriptions

Disadvantages:

• Non-deterministic - agents may forget
• Requires prompt maintenance in 10+ template files
• Description quality varies by agent

Hybrid Approach

Hook provides "reminder" feedback to Claude when it detects artifact-creating tool was used but add_artifact wasn't called:

{
  "decision": "block",
  "reason": "You created a comment at [URL]. Please call recap.add_artifact to track this artifact."
}

Advantages:

• Deterministic reminder
• Uses proper MCP channel
• No file writing from hook
• Agent can provide good description

Disadvantages:

• Adds latency to workflow
• Hook would need to track "expected" vs "actual" add_artifact calls
• Complex state management across tool calls

Integration Points

• Hook reads hookData from Claude Code via stdin
• Hook currently broadcasts to iloom-vscode via Unix sockets
• Recap MCP server connects via stdio transport
• Recap file is watched by VS Code extension for UI updates
• Hook and MCP server both have access to same recap file path (if computed correctly)

[acreeger]

Analysis Phase: Hook TypeScript Migration + MCP Client for Artifact Capture

• Fetch issue details and understand requirements
• Analyze recap MCP server structure and transport mechanism
• Research how Claude Code connects to MCP servers
• Investigate MCP SDK client library options
• Review build configuration for TypeScript compilation
• Document findings and implementation approach

Status: Complete

---

Executive Summary

The task is to migrate the existing iloom-hook.js to TypeScript and add an MCP client that calls add_artifact on PostToolUse events. The key challenge is that hooks cannot connect to Claude Code's already-running MCP servers - the stdio transport requires spawning a new server process. The solution is for the hook to spawn its own dedicated recap-server instance using the same RECAP_FILE_PATH environment variable.

Questions and Key Decisions

Question	Answer
Can hooks connect to Claude Code's existing MCP servers?	No - stdio transport spawns new processes. Hook must spawn its own server instance.
How does hook get RECAP_FILE_PATH?	Must pass via environment variable. Requires adding to iloom's environment setup (ILOOM_RECAP_FILE_PATH).
How to add hook to tsup build?	Add new entry point in tsup.config.ts for templates/hooks/iloom-hook.ts with ESM output to dist/hooks/.
MCP SDK already a dependency?	Yes - @modelcontextprotocol/sdk: ^1.0.4 already in package.json.

HIGH/CRITICAL Risks

• Concurrent file access: Both Claude's recap-server and hook's recap-server write to same recap.json file. Risk of data loss on simultaneous writes. Mitigation: atomic file operations already in place (temp file + rename).
• Hook spawn latency: Spawning MCP server + connecting + calling tool on every PostToolUse adds ~100-200ms latency. May impact Claude session responsiveness.

Impact Summary

• Phase 1: 2 files to modify (tsup.config.ts, ClaudeHookManager.ts), 1 file to migrate (iloom-hook.js -> iloom-hook.ts)
• Phase 2: Same hook file gets MCP client logic added
• New environment variable: ILOOM_RECAP_FILE_PATH passed to hook via environment
• Build output: dist/hooks/iloom-hook.js (compiled from TypeScript)

---

Complete Technical Reference (click to expand for implementation details)

Phase 1: Migrate Hook to TypeScript

Current State

• Hook location: /Users/adam/Documents/Projects/iloom-cli/feat-issue-351__track-artifacts/templates/hooks/iloom-hook.js
• Hook size: 259 lines, plain JavaScript with CommonJS requires
• Hook function: Broadcasts session status to VS Code extension via Unix sockets
• Installation: Copied to ~/.claude/hooks/iloom-hook.js by ClaudeHookManager

Build Configuration

Current tsup.config.ts structure (3 entry configs):

1. CLI build: src/cli.ts -> dist/cli.js
2. MCP servers: src/mcp/*.ts -> dist/mcp/*.js
3. Library: src/index.ts -> dist/index.js

Required change: Add 4th config for hook:

// Hook build configuration
{
  entry: ['src/hooks/iloom-hook.ts'],
  format: ['esm'],
  target: 'node16',
  outDir: 'dist/hooks',
  clean: false,
  sourcemap: true,
  dts: false,
  banner: {
    js: '#!/usr/bin/env node',
  },
  outExtension() {
    return { js: '.js' }
  },
}

File Migration

Source: /Users/adam/Documents/Projects/iloom-cli/feat-issue-351__track-artifacts/templates/hooks/iloom-hook.js
Destination: /Users/adam/Documents/Projects/iloom-cli/feat-issue-351__track-artifacts/src/hooks/iloom-hook.ts

Key conversions:

• const fs = require('fs') -> import fs from 'fs'
• const net = require('net') -> import net from 'net'
• const path = require('path') -> import path from 'path'
• Add types for hookData, status, etc.
• Keep async/await patterns (already in place)

ClaudeHookManager Update

File: /Users/adam/Documents/Projects/iloom-cli/feat-issue-351__track-artifacts/src/lib/ClaudeHookManager.ts

Change 1 (line 145-146): Update source path to compiled TypeScript output

const sourcePath = path.join(this.templateDir, 'iloom-hook.js')
// Change to:
const sourcePath = path.join(distDir, 'hooks', 'iloom-hook.js')

Change 2: Update templateDir logic to find dist/hooks instead of templates/hooks

Phase 2: Add MCP Client for Artifact Capture

MCP Client Approach

Challenge: Hooks run as separate processes without access to Claude Code's MCP transport. The StdioClientTransport spawns a new server process.

Solution: Hook spawns its own recap-server instance:

1. Hook receives ILOOM_RECAP_FILE_PATH environment variable (same as Claude's recap-server)
2. On PostToolUse for artifact-creating tools, hook spawns recap-server via StdioClientTransport
3. Hook calls add_artifact tool
4. Hook closes connection

MCP SDK Usage

Already installed: @modelcontextprotocol/sdk: ^1.0.4

Client pattern (from Context7 docs):

import { Client } from '@modelcontextprotocol/sdk/client/index.js'
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js'

const client = new Client({ name: 'iloom-hook', version: '1.0.0' })

const transport = new StdioClientTransport({
  command: 'node',
  args: ['/path/to/dist/mcp/recap-server.js'],
  env: {
    RECAP_FILE_PATH: process.env.ILOOM_RECAP_FILE_PATH,
    LOOM_METADATA_JSON: '{}' // Minimal valid JSON
  }
})

await client.connect(transport)
const result = await client.callTool({
  name: 'add_artifact',
  arguments: {
    type: 'comment',
    primaryUrl: toolResponse.url,
    description: `Created comment on issue ${toolInput.number}`
  }
})
await client.close()

Environment Variable Setup

New env var: ILOOM_RECAP_FILE_PATH

Where to set: In src/commands/ignite.ts (line 59-61):

process.env.ILOOM = '1'
// Add:
const recapFilePath = /* compute from generateRecapMcpConfig or similar */
process.env.ILOOM_RECAP_FILE_PATH = recapFilePath

Alternative: Pass via hook command in ClaudeHookManager.getHookConfig() using environment or arguments.

Tools to Monitor

PostToolUse tool_name patterns:

1. mcp__issue_management__create_comment - Artifact type: comment
2. mcp__issue_management__update_comment - Artifact type: comment (update existing)
3. Bash with command matching gh pr create - Artifact type: pr
4. Bash with command matching gh issue create - Artifact type: issue

Hook Logic Addition

// After broadcasting to VS Code sockets, check for artifact capture
if (hook_event_name === 'PostToolUse' && process.env.ILOOM_RECAP_FILE_PATH) {
  const artifactInfo = extractArtifactInfo(hookData)
  if (artifactInfo) {
    await captureArtifact(artifactInfo)
  }
}

function extractArtifactInfo(hookData: HookData): ArtifactInfo | null {
  const { tool_name, tool_input, tool_response } = hookData

  if (tool_name === 'mcp__issue_management__create_comment') {
    return {
      type: 'comment',
      primaryUrl: tool_response?.url,
      description: `Comment on ${tool_input?.type} #${tool_input?.number}`
    }
  }
  // ... other patterns

  return null
}

Affected Files Summary

Phase 1

1. /Users/adam/Documents/Projects/iloom-cli/feat-issue-351__track-artifacts/tsup.config.ts - Add hook build entry
2. /Users/adam/Documents/Projects/iloom-cli/feat-issue-351__track-artifacts/src/hooks/iloom-hook.ts - NEW: TypeScript migration
3. /Users/adam/Documents/Projects/iloom-cli/feat-issue-351__track-artifacts/src/lib/ClaudeHookManager.ts - Update source path
4. /Users/adam/Documents/Projects/iloom-cli/feat-issue-351__track-artifacts/templates/hooks/iloom-hook.js - DELETE after migration

Phase 2

1. /Users/adam/Documents/Projects/iloom-cli/feat-issue-351__track-artifacts/src/hooks/iloom-hook.ts - Add MCP client logic
2. /Users/adam/Documents/Projects/iloom-cli/feat-issue-351__track-artifacts/src/commands/ignite.ts - Add ILOOM_RECAP_FILE_PATH env var

Medium Severity Risks

• Hook timeout: MCP client spawn + connect + call may exceed Claude's hook timeout. Default is unspecified but likely 5-10s. Actual operation should complete in <500ms.
• Error swallowing: Hook currently swallows all errors silently. MCP client errors would be invisible. Consider logging to /tmp/iloom-hook.log.

Performance Considerations

MCP client spawn on every PostToolUse would be expensive. Optimizations:

1. Only spawn for specific tool_name patterns (artifact-creating tools)
2. Keep server running between calls (requires managing hook process lifecycle - complex)
3. Accept latency since artifact capture is non-blocking to Claude's operation