@specforge/mcp 3.2.3 → 3.3.0

package/src/cli/templates/commands.ts

@@ -7,32 +7,17 @@
 
 import type { CommandTemplate } from '../commands/scaffold/types.js';
 
-// Import all command content
 import { SF_INIT_CONTENT } from './content/sf-init.js';
 import { SF_STATUS_CONTENT } from './content/sf-status.js';
-import { SF_NEXT_CONTENT } from './content/sf-next.js';
-import { SF_TICKET_IMPLEMENTATION_CONTENT } from './content/sf-ticket.js';
-import { SF_RUN_AUTONOMOUS_CONTENT } from './content/sf-autonomous.js';
-import { SF_REVIEW_CONTENT } from './content/sf-review.js';
-import { SF_VALIDATE_CONTENT } from './content/sf-validate.js';
 import { SF_RESET_CONTENT } from './content/sf-reset.js';
 import { SF_ANALYZE_BLOCKERS_CONTENT } from './content/sf-blockers.js';
-import { SF_IMPORT_PLAN_CONTENT } from './content/sf-import.js';
-import { SF_CREATE_SPEC_CONTENT } from './content/sf-create-spec.js';
-import { SF_CREATE_EPICS_CONTENT } from './content/sf-create-epics.js';
-import { SF_CREATE_TICKETS_CONTENT } from './content/sf-create-tickets.js';
 import { SF_CONTEXT_CONTENT } from './content/sf-context.js';
 import { SF_SEARCH_CONTENT } from './content/sf-search.js';
-import { SF_EPIC_CONTENT } from './content/sf-epic.js';
 import { SF_COMMIT_CONTENT } from './content/sf-commit.js';
 import { SF_HELP_CONTENT } from './content/sf-help.js';
 
-/**
- * Get all command templates
- */
 export function getCommandTemplates(): CommandTemplate[] {
   return [
-    // Setup
     {
       name: 'sf-init',
       description: 'Initialize ticket system for a specification',
@@ -47,7 +32,6 @@ export function getCommandTemplates(): CommandTemplate[] {
       content: SF_CONTEXT_CONTENT,
       category: 'Setup',
     },
-    // Status
     {
       name: 'sf-status',
       description: 'Display implementation status with consolidated tools',
@@ -55,77 +39,12 @@ export function getCommandTemplates(): CommandTemplate[] {
       content: SF_STATUS_CONTENT,
       category: 'Status',
     },
-    {
-      name: 'sf-validate',
-      description: 'Validate ticket system health',
-      argumentHint: '[specification-id]',
-      content: SF_VALIDATE_CONTENT,
-      category: 'Status',
-    },
     {
       name: 'sf-analyze-blockers',
       description: 'Analyze blockers and dependency bottlenecks',
       content: SF_ANALYZE_BLOCKERS_CONTENT,
       category: 'Status',
     },
-    // Implementation
-    {
-      name: 'sf-next',
-      description: 'Quick start the next ready ticket',
-      content: SF_NEXT_CONTENT,
-      category: 'Implementation',
-    },
-    {
-      name: 'sf-ticket-implementation',
-      description: 'Implement a ticket with streamlined workflow',
-      argumentHint: '[ticket-id]',
-      content: SF_TICKET_IMPLEMENTATION_CONTENT,
-      category: 'Implementation',
-    },
-    {
-      name: 'sf-run-autonomous',
-      description: 'Run autonomous implementation for multiple tickets',
-      argumentHint: '[max-tickets]',
-      content: SF_RUN_AUTONOMOUS_CONTENT,
-      category: 'Implementation',
-    },
-    // Planning
-    {
-      name: 'sf-import-plan',
-      description: 'Transform a plan into a complete SpecForge specification',
-      argumentHint: '<plan-file-path>',
-      content: SF_IMPORT_PLAN_CONTENT,
-      category: 'Planning',
-    },
-    {
-      name: 'sf-create-spec',
-      description: 'Create a SpecForge specification with patterns',
-      argumentHint: '<plan-file-path>',
-      content: SF_CREATE_SPEC_CONTENT,
-      category: 'Planning',
-    },
-    {
-      name: 'sf-create-epics',
-      description: 'Create epics with epic-level patterns',
-      argumentHint: '<specification-id>',
-      content: SF_CREATE_EPICS_CONTENT,
-      category: 'Planning',
-    },
-    {
-      name: 'sf-create-tickets',
-      description: 'Create detailed tickets with full implementation context',
-      argumentHint: '<epic-id>',
-      content: SF_CREATE_TICKETS_CONTENT,
-      category: 'Planning',
-    },
-    // Review
-    {
-      name: 'sf-review',
-      description: 'Review accomplishments and progress analysis',
-      argumentHint: '[specification-id]',
-      content: SF_REVIEW_CONTENT,
-      category: 'Review',
-    },
     {
       name: 'sf-search',
       description: 'Search tickets by text, tags, or filters',
@@ -133,14 +52,6 @@ export function getCommandTemplates(): CommandTemplate[] {
       content: SF_SEARCH_CONTENT,
       category: 'Review',
     },
-    {
-      name: 'sf-epic',
-      description: 'View epic details and progress',
-      argumentHint: '<epic-id>',
-      content: SF_EPIC_CONTENT,
-      category: 'Review',
-    },
-    // Utilities
     {
       name: 'sf-reset',
       description: 'Reset ticket statuses with dependency awareness',

package/src/cli/templates/content/sf-blockers.ts

@@ -14,8 +14,11 @@ Analyze dependency bottlenecks and identify critical path tickets.
 
 **MCP Calls:**
 \`\`\`typescript
-get_working_context()
-get_specification(specificationId)
+// Read project config
+const config = readFile('.specforge.json')
+const specificationId = config.activeSpecification?.id
+
+get_specification({ specificationId })
 list_epics({ specificationId })
 list_tickets({ specificationId })
 \`\`\`

package/src/cli/templates/content/sf-commit.ts

@@ -18,10 +18,15 @@ Create a git commit with SpecForge ticket metadata.
 **MCP Calls:**
 \`\`\`typescript
 if ($ARGUMENTS) {
-  get_ticket($ARGUMENTS)
+  get_ticket({ ticketId: $ARGUMENTS })
 } else {
-  get_working_context()
-  get_ticket(context.ticketId)
+  // Read active ticket from .specforge.json or find active ticket
+  const config = readFile('.specforge.json')
+  const specificationId = config.activeSpecification?.id
+  // Find the currently active ticket
+  list_tickets({ specificationId, status: ["active"] })
+  // Use the active ticket
+  get_ticket({ ticketId: activeTicket.id })
 }
 \`\`\`
 
@@ -45,10 +50,8 @@ git commit -m "{type}({scope}): {description} ({ticketId})"
 
 **MCP Calls:**
 \`\`\`typescript
-update_ticket({
-  ticketId: ticket.id,
-  status: 'done',
-  completedAt: new Date().toISOString()
+complete_work_session({
+  ticketId: ticket.id
 })
 \`\`\`
 
@@ -72,7 +75,7 @@ Next: Run /sf-next for the next ticket
 \`\`\`
 
 ## Notes
-- Automatically marks ticket as done
+- Automatically completes the work session
 - Uses conventional commit format
 - Includes ticket ID for traceability
 `;

package/src/cli/templates/content/sf-context.ts

@@ -15,9 +15,17 @@ Quickly view or switch the current working context.
 
 ### 1. If No Arguments - Show Current Context
 
-**MCP Calls:**
+**Logic:**
 \`\`\`typescript
-get_working_context()
+// Read project config
+const config = readFile('.specforge.json')
+const projectId = config.project.id
+const specificationId = config.activeSpecification?.id
+
+// Load details
+if (specificationId) {
+  get_specification({ specificationId, include: ["status"] })
+}
 \`\`\`
 
 **Output:**
@@ -27,34 +35,27 @@ WORKING CONTEXT
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 Project:       {project.name}
 Specification: {spec.title}
-Epic:          {epic.title} (if set)
-Ticket:        E{n}-T{m} {title} (if set)
+Source:        .specforge.json
 
-Session:       {active/none}
 Progress:      {done}/{total} ({pct}%)
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 \`\`\`
 
 ### 2. If Arguments - Switch Context
 
-**MCP Calls:**
+**Logic:**
 \`\`\`typescript
 // Try as specification first
-get_specification($ARGUMENTS)
-
-// If not found, try as project
-get_project($ARGUMENTS)
+get_specification({ specificationId: $ARGUMENTS })
 
-// Set context
-set_working_context({
-  projectId: project.id,
-  specificationId: spec?.id
-})
+// Update .specforge.json activeSpecification
+// (or inform user to update manually)
 \`\`\`
 
 **Output:**
 \`\`\`
 ✓ Switched to: {name}
+  Update .specforge.json activeSpecification.id to persist.
 \`\`\`
 
 ## Notes

package/src/cli/templates/content/sf-help.ts

@@ -18,36 +18,19 @@ Display the command reference:
 ═══════════════════════════════════════════════════════════════════
 
 SETUP & CONTEXT
-─────────────────────────────────────────────────────────────────
 /sf-init [spec-id]           Initialize specification for work
 /sf-context [id]             View or switch working context
 
 STATUS & ANALYSIS
-─────────────────────────────────────────────────────────────────
 /sf-status [spec-id]         Implementation status overview
-/sf-validate [spec-id]       System health check
 /sf-analyze-blockers         Dependency bottleneck analysis
-/sf-epic <epic-id>           Epic details and progress
-/sf-search <query>           Search tickets
-
-IMPLEMENTATION
-─────────────────────────────────────────────────────────────────
-/sf-next                     Start next ready ticket
-/sf-ticket-implementation    Implement specific ticket
-/sf-run-autonomous [max]     Batch implement tickets
-/sf-commit [ticket-id]       Commit with ticket metadata
 
-PLANNING
-─────────────────────────────────────────────────────────────────
-/sf-import-plan <file>       Import plan to full spec
-/sf-create-spec <file>       Create spec from plan
-/sf-create-epics <spec>      Create epics for spec
-/sf-create-tickets <epic>    Create tickets for epic
+SEARCH
+/sf-search <query>           Search tickets
 
-MANAGEMENT
-─────────────────────────────────────────────────────────────────
-/sf-review [spec-id]         Accomplishment review
+UTILITIES
 /sf-reset [spec-id]          Reset ticket statuses
+/sf-commit [ticket-id]       Commit with ticket metadata
 
 ═══════════════════════════════════════════════════════════════════
 Tip: Use /sf-init first to set up your working context.

package/src/cli/templates/content/sf-init.ts

@@ -15,15 +15,18 @@ Initialize a SpecForge specification for implementation work.
 
 ### 1. Get or Set Working Context
 
-**MCP Calls:**
+**Logic:**
 \`\`\`typescript
-// Get current context
-get_working_context()
+// Read project config
+const config = readFile('.specforge.json')
+const projectId = config.project.id
+const specificationId = $ARGUMENTS || config.activeSpecification?.id
 
-// If $ARGUMENTS provided, set specification
-set_working_context({
-  specificationId: "$ARGUMENTS"
-})
+// If no spec found, list available specs
+if (!specificationId) {
+  list_specifications({ projectId })
+  // Let user pick
+}
 \`\`\`
 
 ### 2. Load Specification Details

package/src/cli/templates/content/sf-reset.ts

@@ -17,16 +17,15 @@ Reset ticket statuses to ready state with dependency awareness.
 
 **MCP Calls:**
 \`\`\`typescript
-get_working_context()
+// Read project config
+const config = readFile('.specforge.json')
+const specificationId = $ARGUMENTS || config.activeSpecification?.id
 
-if ($ARGUMENTS.match(/E\d+-T\d+/)) {
+if ($ARGUMENTS?.match(/E\d+-T\d+/)) {
   // Single ticket reset
-  get_ticket($ARGUMENTS)
+  get_ticket({ ticketId: $ARGUMENTS })
 } else {
   // Full specification reset
-  if ($ARGUMENTS) {
-    set_working_context({ specificationId: "$ARGUMENTS" })
-  }
   list_tickets({ specificationId })
 }
 \`\`\`
@@ -35,19 +34,11 @@ if ($ARGUMENTS.match(/E\d+-T\d+/)) {
 
 **MCP Calls:**
 \`\`\`typescript
-// For each ticket to reset
-for (const ticket of tickets) {
-  // Check dependencies
-  const allDepsCompleted = ticket.dependencies.every(
-    dep => getTicketStatus(dep) === 'done'
-  );
-
-  // Update status
-  update_ticket({
-    ticketId: ticket.id,
-    status: allDepsCompleted ? 'ready' : 'blocked'
-  })
-}
+// Reset tickets via lifecycle operation
+reset_work_session({
+  specificationId,
+  ticketId: $ARGUMENTS.match(/E\d+-T\d+/) ? $ARGUMENTS : undefined
+})
 \`\`\`
 
 ### 3. Display Reset Results

package/src/cli/templates/content/sf-search.ts

@@ -24,13 +24,14 @@ Search tickets by text, tags, status, or other filters.
 
 **MCP Calls:**
 \`\`\`typescript
-get_working_context()
+// Read project config
+const config = readFile('.specforge.json')
+const specificationId = config.activeSpecification?.id
 
-list_tickets({
+search_tickets({
   specificationId,
-  search: extractedTerms,
+  query: extractedTerms,
   status: extractedStatus,
-  epicId: extractedEpicId,
   tags: extractedTags
 })
 \`\`\`

package/src/cli/templates/content/sf-status.ts

@@ -13,16 +13,13 @@ Display comprehensive implementation status with consolidated progress view.
 
 ## Task
 
-### 1. Get Working Context
+### 1. Get Specification Context
 
-**MCP Calls:**
+**Logic:**
 \`\`\`typescript
-get_working_context()
-
-// If $ARGUMENTS provided, switch context
-if ($ARGUMENTS) {
-  set_working_context({ specificationId: "$ARGUMENTS" })
-}
+// Read project config
+const config = readFile('.specforge.json')
+const specificationId = $ARGUMENTS || config.activeSpecification?.id
 \`\`\`
 
 ### 2. Load Implementation Data

package/src/cli/templates/skills/specforge-orchestrator.md

@@ -143,7 +143,7 @@ Each worker spawned by the orchestrator MUST follow this 9-step protocol:
 
 **When a worker encounters a blocker:**
 ```
-1. Call report_discovery({ ticketId, type: "blocker", description: "description of blocker" })
+1. Call discover_work_session({ ticketId, type: "blocker", description: "description of blocker" })
 2. Call action_work_session({ ticketId, blockReason: "description of blocker" })
    → This sets the ticket to pending status
 3. Message team lead: "Blocked on E{n}-T{n}: {reason}"

package/src/cli/templates/skills/specforge-worker.md

@@ -177,12 +177,22 @@ Stage and commit your changes with a conventional commit message.
 Report completion to SpecForge and notify the team lead.
 
 ```
-1. Call: complete_work_session({
+1. Ensure all steps and AC are marked via action_work_session:
+   Call: action_work_session({
+     ticketId: "{ticketId}",
+     allStepsDone: true,
+     allACValidated: true,
+     filesCreated: ["path/to/new/file.ts", ...],
+     filesModified: ["path/to/changed/file.ts", ...],
+     testResults: [{ name: "test-file.ts", passed: true }]
+   })
+   → The completion gate requires all steps + AC to be completed first
+
+2. Call: complete_work_session({
      ticketId: "{ticketId}",
      summary: "Brief description of what was implemented and key decisions made",
      filesCreated: ["path/to/new/file.ts", ...],
      filesModified: ["path/to/changed/file.ts", ...],
-     validated: true,
      validation: {
        tests: "passed" | "failed" | "skipped" | "na",
        lint: "passed" | "failed" | "skipped" | "na",
@@ -194,7 +204,7 @@ Report completion to SpecForge and notify the team lead.
    → Transitions ticket from active → done
    → Automatically unblocks dependent tickets
 
-2. Message team lead:
+3. Message team lead:
    "Completed E{epicNumber}-T{ticketNumber}: {summary of changes}"
 ```
 
@@ -229,16 +239,26 @@ When you encounter something that prevents you from completing a ticket:
    b. External blocker: missing API, unclear requirement, infrastructure issue
    c. Technical issue: build failure, incompatible dependency, environment problem
 
-2. Report the blocker:
-   Call: update_ticket({ ticketId, blockReason: "Clear description of the blocker" })
-   → This sets the ticket status to pending
+2. Report the discovery:
+   Call: discover_work_session({
+     ticketId,
+     type: "blocker",
+     description: "Clear description of the blocker"
+   })
+
+3. Set the block on the ticket:
+   Call: action_work_session({
+     ticketId,
+     blockReason: "Clear description of the blocker"
+   })
+   → This transitions the ticket to pending status
 
-3. Notify team lead with details:
+4. Notify team lead with details:
    Message: "Blocked on E{epicNumber}-T{ticketNumber}: {blocker description}
    Type: {dependency | external | technical}
    Suggestion: {what might resolve it}"
 
-4. Move on:
+5. Move on:
    → Go to Step 9 (NEXT) to claim another ticket
    → Don't wait idle — work on what you can
 ```
@@ -250,7 +270,14 @@ When you encounter something that prevents you from completing a ticket:
 When you find unexpected issues, missing requirements, or additional work needed:
 
 ```
-1. Notify team lead:
+1. Report the discovery via MCP:
+   Call: discover_work_session({
+     ticketId,
+     type: "scope_change",  // or "blocker", "question", "improvement"
+     description: "Description of what was found and its impact"
+   })
+
+2. Notify team lead:
    Message: "Discovery while working on E{epicNumber}-T{ticketNumber}:
    {description}
    Impact: {how it affects current or future tickets}
@@ -322,7 +349,8 @@ All workers commit to the same branch (requires coordination).
 2. Verify dependencies are installed
 3. Check if a dependency from another ticket is needed
 4. If build depends on another ticket:
-   → Block the ticket: update_ticket({ ticketId, blockReason: "Depends on E{n}-T{n} for {reason}" })
+   → Report: discover_work_session({ ticketId, type: "blocker", description: "Depends on E{n}-T{n} for {reason}" })
+   → Block: action_work_session({ ticketId, blockReason: "Depends on E{n}-T{n} for {reason}" })
    → Move to next ticket
 ```
 
@@ -338,10 +366,11 @@ All workers commit to the same branch (requires coordination).
 ### Unrecoverable Error
 ```
 If you cannot complete the ticket after reasonable attempts:
-1. Call: update_ticket({ ticketId, blockReason: "Unrecoverable: {description}" })
-2. Message lead with full details:
+1. Call: discover_work_session({ ticketId, type: "blocker", description: "Unrecoverable: {description}" })
+2. Call: action_work_session({ ticketId, blockReason: "Unrecoverable: {description}" })
+3. Message lead with full details:
    "Failed E{n}-T{n}: {what was attempted, what failed, what might fix it}"
-3. Move to next ticket (Step 9)
+4. Move to next ticket (Step 9)
 ```
 
 ---
@@ -351,14 +380,16 @@ If you cannot complete the ticket after reasonable attempts:
 | Tool | When to Use |
 |------|-------------|
 | `get_next_actionable_tickets` | CLAIM — find ready tickets |
-| `start_work_session` | START — mark ticket active |
+| `start_work_session` | START — ready -> active (creates WorkSession) |
 | `get_implementation_context` | CONTEXT — load full ticket details |
 | `get_workspace_files` | CONTEXT — workspace metadata (local only) |
 | `get_patterns` | CONTEXT — code patterns with inheritance |
 | `blueprint` (get_for_ticket) | CONTEXT — load linked blueprints |
-| `complete_work_session` | REPORT — mark ticket done with summary |
-| `update_ticket` | Block a ticket (set blockReason) |
-| `pause_work_session` | Pause work without completing (back to ready) |
+| `action_work_session` | IMPLEMENT — update steps, AC, files, tests, blockers |
+| `discover_work_session` | IMPLEMENT — report discoveries/blockers |
+| `complete_work_session` | REPORT — active -> done (requires all steps + AC) |
+| `pause_work_session` | Pause work without completing (active -> ready) |
+| `resume_work_session` | Resume paused work (ready -> active) |
 
 ## Status Values
 
@@ -366,5 +397,6 @@ If you cannot complete the ticket after reasonable attempts:
 - There is no `in_review` status. Tickets go directly from `active` to `done`.
 - `pending` means dependencies are not met. `ready` means all dependencies satisfied.
 - `start_work_session` transitions `ready` → `active`.
-- `complete_work_session` transitions `active` → `done`.
-- Blocking a ticket with `update_ticket({ blockReason })` sets it to `pending`.
+- `action_work_session` tracks progress during active session.
+- `discover_work_session` + `action_work_session({ blockReason })` blocks a ticket (active → pending).
+- `complete_work_session` transitions `active` → `done` (completion gate enforced).

package/src/cli/templates/agents/content/core/sfag-implementer.ts

@@ -1,113 +0,0 @@
-/**
- * SFAG-Implementer Agent Template
- *
- * General-purpose code implementation agent for spec to code translation.
- */
-
-import type { AgentTemplate } from '../../../../commands/scaffold/agent-types.js';
-
-export const SFAG_IMPLEMENTER: AgentTemplate = {
-  name: 'sfag-implementer',
-  description: 'General-purpose spec to code translation',
-  triggerDescription: `Use this agent when you need to implement code based on technical specifications, design documents, architecture plans, or detailed feature requirements.
-
-<example>
-Context: User has created detailed technical specs for a new authentication module
-user: "I've documented the complete authentication flow in AUTH_SPEC.md. Can you implement it?"
-assistant: "I'll use the sfag-implementer agent to translate your authentication specification into working code."
-</example>
-
-<example>
-Context: After reviewing a design document for a data processing pipeline
-user: "The pipeline design looks good. Let's move forward with implementation."
-assistant: "I'm launching the sfag-implementer agent to build the data processing pipeline according to the approved design document."
-</example>
-
-<example>
-Context: User provides API contract documentation
-user: "Here's the OpenAPI spec for our new REST endpoints. Please implement the handlers."
-assistant: "I'll use the sfag-implementer agent to create the endpoint handlers that match your OpenAPI specification."
-</example>`,
-  model: 'haiku',
-  color: 'green',
-  category: 'Implementation',
-  content: `# SpecForge Implementer Agent
-
-You are the SpecForge Implementer - an expert at translating specifications into working code.
-
-## Role
-
-Your primary responsibilities:
-1. **Understand** - Thoroughly comprehend the specification or requirements
-2. **Plan** - Design the implementation approach before coding
-3. **Implement** - Write clean, maintainable, production-ready code
-4. **Verify** - Ensure the implementation matches the specification
-5. **Document** - Add appropriate inline documentation
-
-## Implementation Process
-
-### 1. Specification Analysis
-- Read and understand all provided documentation
-- Identify inputs, outputs, and expected behavior
-- Note any edge cases or error conditions
-- Clarify ambiguities before proceeding
-
-### 2. Codebase Exploration
-- Understand existing patterns and conventions
-- Identify related code and dependencies
-- Find integration points
-- Note testing patterns in use
-
-### 3. Implementation Strategy
-- Plan the order of changes
-- Identify files to create or modify
-- Consider backwards compatibility
-- Plan for testability
-
-### 4. Code Writing
-- Follow existing code style and conventions
-- Write self-documenting code
-- Handle errors appropriately
-- Keep functions focused and small
-
-### 5. Verification
-- Review against specification requirements
-- Check edge cases are handled
-- Ensure error handling is complete
-- Verify integration points work
-
-## Code Quality Standards
-
-### Naming
-- Use descriptive, meaningful names
-- Follow language conventions (camelCase, snake_case, etc.)
-- Be consistent with existing codebase
-
-### Structure
-- Keep functions small and focused
-- Use appropriate abstractions
-- Avoid deep nesting
-- Prefer composition over inheritance
-
-### Error Handling
-- Handle errors at appropriate levels
-- Provide meaningful error messages
-- Don't swallow errors silently
-- Log errors with context
-
-### Documentation
-- Add comments for non-obvious logic
-- Document public APIs
-- Include usage examples where helpful
-- Keep comments up to date with code
-
-## Guidelines
-
-- Always read the specification thoroughly before coding
-- Explore the codebase to understand existing patterns
-- Ask clarifying questions if requirements are unclear
-- Prefer simple solutions over clever ones
-- Write code that is easy to test
-- Consider the next developer who will read your code
-`,
-};