@specforge/mcp 3.0.7 → 3.1.0

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

@@ -0,0 +1,78 @@
+/**
+ * SF-Commit Command Template
+ *
+ * Template for committing changes with SpecForge ticket metadata.
+ */
+
+export const SF_COMMIT_CONTENT = `# Commit Changes (SpecForge)
+
+Create a git commit with SpecForge ticket metadata.
+
+## Arguments
+- \`$ARGUMENTS\` - Optional: Ticket ID (uses context if not provided)
+
+## Task
+
+### 1. Get Ticket Context
+
+**MCP Calls:**
+\`\`\`typescript
+if ($ARGUMENTS) {
+  get_ticket($ARGUMENTS)
+} else {
+  get_working_context()
+  get_ticket(context.ticketId)
+}
+\`\`\`
+
+### 2. Generate Commit Message
+
+**Logic:**
+- Format: \`feat(scope): description (TICKET-ID)\`
+- Extract scope from epic
+- Use ticket title as description
+- Add ticket ID reference
+
+### 3. Create Commit
+
+**Shell:**
+\`\`\`bash
+git add .
+git commit -m "{type}({scope}): {description} ({ticketId})"
+\`\`\`
+
+### 4. Update Ticket Status
+
+**MCP Calls:**
+\`\`\`typescript
+update_ticket({
+  ticketId: ticket.id,
+  status: 'done',
+  completedAt: new Date().toISOString()
+})
+\`\`\`
+
+### 5. Display Commit Result
+
+**Output:**
+\`\`\`
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+COMMIT CREATED
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Ticket:  E{n}-T{m}
+Message: {commitMessage}
+Hash:    {commitHash}
+
+TICKET COMPLETED
+─────────────────────────────────────────────────────────────────
+✓ E{n}-T{m} marked as done
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Next: Run /sf-next for the next ticket
+\`\`\`
+
+## Notes
+- Automatically marks ticket as done
+- Uses conventional commit format
+- Includes ticket ID for traceability
+`;

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

@@ -0,0 +1,64 @@
+/**
+ * SF-Context Command Template
+ *
+ * Template for viewing or switching working context.
+ */
+
+export const SF_CONTEXT_CONTENT = `# Working Context (SpecForge)
+
+Quickly view or switch the current working context.
+
+## Arguments
+- \`$ARGUMENTS\` - Optional: Project or Specification ID to switch to
+
+## Task
+
+### 1. If No Arguments - Show Current Context
+
+**MCP Calls:**
+\`\`\`typescript
+get_working_context()
+\`\`\`
+
+**Output:**
+\`\`\`
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+WORKING CONTEXT
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Project:       {project.name}
+Specification: {spec.title}
+Epic:          {epic.title} (if set)
+Ticket:        E{n}-T{m} {title} (if set)
+
+Session:       {active/none}
+Progress:      {done}/{total} ({pct}%)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+\`\`\`
+
+### 2. If Arguments - Switch Context
+
+**MCP Calls:**
+\`\`\`typescript
+// Try as specification first
+get_specification($ARGUMENTS)
+
+// If not found, try as project
+get_project($ARGUMENTS)
+
+// Set context
+set_working_context({
+  projectId: project.id,
+  specificationId: spec?.id
+})
+\`\`\`
+
+**Output:**
+\`\`\`
+✓ Switched to: {name}
+\`\`\`
+
+## Notes
+- No argument = show current context
+- With argument = switch context
+- Auto-detects if ID is project or specification
+`;

package/src/cli/templates/content/sf-create-epics.ts

@@ -0,0 +1,129 @@
+/**
+ * SF-Create-Epics Command Template
+ *
+ * Template for creating epics with epic-level patterns from plan phases.
+ */
+
+export const SF_CREATE_EPICS_CONTENT = `# Create Epics (SpecForge)
+
+Create epics for a specification with objectives extracted from plan phases.
+
+## Arguments
+- \`$ARGUMENTS\` - Required: Specification ID
+
+## Task
+
+### 1. Get Specification
+
+**MCP Calls:**
+\`\`\`typescript
+specification({
+  operation: 'get',
+  specificationId: $ARGUMENTS,
+  include: ['epics', 'patterns']  // Get existing epics and inherited patterns
+})
+\`\`\`
+
+### 2. Read Original Plan
+
+**Logic:**
+- Locate original plan file from specification metadata
+- Parse plan phases/sections
+- Extract epic-level titles, descriptions, and objectives
+- Identify epic-specific technical details
+
+### 3. Create Epics
+
+**MCP Calls:**
+\`\`\`typescript
+// For each phase/section in plan
+for (const phase of phases) {
+  await epic({
+    operation: 'create',
+
+    // === REQUIRED ===
+    specificationId: $ARGUMENTS,
+    title: phase.title,
+    description: phase.description,
+    objective: phase.objective,     // Clear goal statement
+
+    // === CORE (recommended) ===
+    content: phase.fullContent,     // Full markdown content
+    scope: phase.scope,             // What's in/out of scope
+    priority: 'high',               // high | medium | low
+    tags: ['phase1', 'backend'],
+    estimatedHours: 40,
+
+    // === PLANNING ===
+    goals: ['Implement X', 'Enable Y'],
+    acceptanceCriteria: ['Feature X works', 'Tests pass'],
+    guardrails: ['Do NOT break existing API'],
+    constraints: ['Must be backward compatible'],
+    assumptions: ['Database schema is stable'],
+    risks: ['May require migration'],
+
+    // === TECHNICAL ===
+    architecture: 'Service layer with repository pattern',
+    fileStructure: 'src/services/\\n  user.service.ts\\n  auth.service.ts',
+    techStack: ['typescript', 'prisma'],
+    dependencies: ['zod', '@prisma/client'],
+    apiContracts: { endpoints: [{ path: '/api/users', method: 'POST' }] },
+
+    // === PATTERN OVERRIDES (override spec-level patterns) ===
+    sharedPatterns: {
+      errorHandling: 'Custom error handling for this epic',
+      validation: 'Use zod schemas'
+    },
+    additionalImports: [
+      "import { z } from 'zod'",
+      "import { PrismaClient } from '@prisma/client'"
+    ],
+    commonFiles: {
+      'types.ts': 'Shared types for this epic',
+      'utils.ts': 'Epic-specific utilities'
+    }
+  })
+}
+\`\`\`
+
+### 4. Display Creation Results
+
+**Output:**
+\`\`\`
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+EPICS CREATED
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Specification: {title}
+
+CREATED EPICS
+─────────────────────────────────────────────────────────────────
+E1  │ {title} │ {objective}
+E2  │ {title} │ {objective}
+E3  │ {title} │ {objective}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Next: Run /sf-create-tickets <epic-id> for each epic
+\`\`\`
+
+## Field Reference
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| specificationId | ✅ | Parent specification |
+| title | ✅ | Epic title |
+| description | ✅ | Epic description |
+| objective | ✅ | Clear goal statement |
+| content | | Full markdown content |
+| scope | | In/out of scope |
+| goals | | Epic-specific goals |
+| guardrails | | What NOT to do |
+| architecture | | Epic-level design |
+| sharedPatterns | | Override spec patterns |
+| additionalImports | | Extra imports for tickets |
+
+## Notes
+- specificationId, title, description, and objective are required
+- sharedPatterns override specification-level patterns
+- additionalImports are added to spec-level commonImports
+- Use /sf-create-tickets for each epic after creation
+`;

package/src/cli/templates/content/sf-create-spec.ts

@@ -0,0 +1,136 @@
+/**
+ * SF-Create-Spec Command Template
+ *
+ * Template for creating a SpecForge specification with patterns from a plan.
+ */
+
+export const SF_CREATE_SPEC_CONTENT = `# Create Specification (SpecForge)
+
+Create a SpecForge specification structure with metadata extracted from a plan document.
+
+## Arguments
+- \`$ARGUMENTS\` - Required: Path to plan markdown file
+
+## Task
+
+### 1. Read and Analyze Plan
+
+**Logic:**
+- Read file at $ARGUMENTS
+- Extract specification title and description
+- Identify priority level (high/medium/low)
+- Parse tags from plan categories/themes
+- Extract goals, requirements, and constraints
+
+### 2. Create Specification
+
+**MCP Calls:**
+\`\`\`typescript
+specification({
+  operation: 'create',
+
+  // === REQUIRED ===
+  projectId: currentProjectId,
+  title: extractedTitle,
+
+  // === CORE (recommended) ===
+  description: shortSummary,        // 2-3 sentence summary
+  content: fullMarkdownContent,     // Full markdown content
+  background: problemContext,       // Why this exists
+  scope: scopeDefinition,           // What's in/out of scope
+  priority: 'high',                 // high | medium | low
+  tags: ['feature', 'api'],
+  estimatedHours: 40,
+  targetAudience: 'developers',
+
+  // === GOALS & REQUIREMENTS ===
+  goals: ['Enable X', 'Improve Y'],
+  requirements: ['Must do A', 'Must support B'],
+  nonFunctionalRequirements: ['< 100ms latency', '99.9% uptime'],
+  acceptanceCriteria: ['Users can X', 'System handles Y'],
+  successMetrics: ['50% reduction in Z'],
+
+  // === GUARDRAILS & RISKS ===
+  guardrails: ['Do NOT modify X', 'Avoid pattern Y'],
+  constraints: ['Must use existing auth', 'Budget limit'],
+  assumptions: ['Users have Node 18+'],
+  risks: ['Third-party API may change'],
+
+  // === TECHNICAL ===
+  architecture: 'Microservices with event-driven communication',
+  fileStructure: 'src/\\n  components/\\n  services/\\n  utils/',
+  techStack: ['typescript', 'react', 'node'],
+  dependencies: ['@aws-sdk/client-s3', 'zod'],
+  apiContracts: { endpoints: [{ path: '/api/v1/users', method: 'GET' }] },
+
+  // === PATTERN INHERITANCE (for epics/tickets) ===
+  codeStandards: {
+    errorHandling: 'Use Result<T, E> pattern',
+    naming: 'camelCase for functions, PascalCase for types'
+  },
+  commonImports: [
+    "import { logger } from '@/lib/logger'",
+    "import { db } from '@/lib/db'"
+  ],
+  returnTypes: {
+    success: '{ success: true, data: T }',
+    error: '{ success: false, error: string }'
+  },
+
+  // === VALIDATION (for CI/CD) ===
+  validationCommands: {
+    test: 'npm test',
+    lint: 'npm run lint',
+    build: 'npm run build',
+    typeCheck: 'npm run typecheck'
+  },
+  workingDirectory: './src',
+  outputDirectory: './dist'
+})
+\`\`\`
+
+### 3. Display Creation Results
+
+**Output:**
+\`\`\`
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+SPECIFICATION CREATED
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Title:    {title}
+ID:       {specificationId}
+Priority: {priority}
+
+DESCRIPTION
+─────────────────────────────────────────────────────────────────
+{description}
+
+TAGS
+─────────────────────────────────────────────────────────────────
+{tags}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Next: Run /sf-create-epics {specificationId} to create epics
+\`\`\`
+
+## Field Reference
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| projectId | ✅ | Project to create spec in |
+| title | ✅ | Specification title |
+| description | | Short summary |
+| content | | Full markdown content |
+| background | | Problem context |
+| scope | | In/out of scope |
+| goals | | Business objectives |
+| requirements | | Functional requirements |
+| guardrails | | What NOT to do |
+| architecture | | System design |
+| techStack | | Technologies used |
+| codeStandards | | Inherited by epics/tickets |
+
+## Notes
+- Only projectId and title are required
+- codeStandards, commonImports, returnTypes are inherited by child epics/tickets
+- Use /sf-create-epics to add epics after creation
+`;

package/src/cli/templates/content/sf-create-tickets.ts

@@ -0,0 +1,148 @@
+/**
+ * SF-Create-Tickets Command Template
+ *
+ * Template for creating detailed tickets individually with full implementation context.
+ */
+
+export const SF_CREATE_TICKETS_CONTENT = `# Create Tickets (SpecForge)
+
+Create detailed tickets for an epic with full implementation context.
+
+## Arguments
+- \`$ARGUMENTS\` - Required: Epic ID
+
+## Task
+
+### 1. Get Epic Context
+
+**MCP Calls:**
+\`\`\`typescript
+epic({
+  operation: 'get',
+  epicId: $ARGUMENTS,
+  include: ['tickets', 'specification']  // Get existing tickets and parent spec
+})
+\`\`\`
+
+### 2. Extract Ticket Definitions
+
+**Logic:**
+- Read epic description and objective
+- Parse task breakdown from epic content
+- Determine complexity and dependencies
+- Extract acceptance criteria for each ticket
+
+### 3. Create Tickets
+
+**MCP Calls:**
+\`\`\`typescript
+// For each task in epic
+for (const task of tasks) {
+  await ticket({
+    operation: 'create',
+
+    // === REQUIRED ===
+    epicId: $ARGUMENTS,
+    title: task.title,
+
+    // === CORE (recommended) ===
+    description: task.description,
+    priority: 'high',               // high | medium | low
+    complexity: 'medium',           // small | medium | large | xlarge
+    estimatedHours: 4,
+    tags: ['feature', 'api'],
+    notes: 'Watch out for edge case X',  // Warnings, considerations
+
+    // === ACCEPTANCE CRITERIA ===
+    acceptanceCriteria: [
+      'Function returns correct result for valid input',
+      'Function throws error for invalid input',
+      'Unit tests cover all branches'
+    ],
+
+    // === IMPLEMENTATION GUIDANCE ===
+    implementation: {
+      filesToCreate: ['src/services/user.service.ts'],
+      filesToModify: ['src/index.ts'],
+      steps: [
+        'Create UserService class',
+        'Implement createUser method',
+        'Add validation with zod',
+        'Write unit tests'
+      ],
+      testing: 'Use vitest with mocked database'
+    },
+    technicalDetails: {
+      approach: 'Repository pattern with dependency injection',
+      stack: ['typescript', 'prisma', 'zod'],
+      endpoints: ['/api/users POST'],
+      databaseChanges: ['Add users table']
+    },
+
+    // === CODE REFERENCES ===
+    codeReferences: [{
+      name: 'createUser',
+      language: 'typescript',
+      code: \`async function createUser(data: CreateUserInput): Promise<User> {
+  const validated = createUserSchema.parse(data);
+  return await db.user.create({ data: validated });
+}\`
+    }],
+    typeReferences: [{
+      name: 'CreateUserInput',
+      definition: \`interface CreateUserInput {
+  email: string;
+  name: string;
+  role?: 'admin' | 'user';
+}\`
+    }],
+
+    // === DEPENDENCIES ===
+    dependsOn: ['ticket-id-1', 'ticket-id-2']  // Must complete these first
+  })
+}
+\`\`\`
+
+### 4. Display Creation Results
+
+**Output:**
+\`\`\`
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+TICKETS CREATED
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Epic: E{n} - {epicTitle}
+
+CREATED TICKETS
+─────────────────────────────────────────────────────────────────
+E{n}-T1  │ {title} │ {complexity} │ ready
+E{n}-T2  │ {title} │ {complexity} │ pending (depends on T1)
+E{n}-T3  │ {title} │ {complexity} │ ready
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Total: {ticketCount} tickets created
+
+Next: Run /sf-status to see overall progress
+\`\`\`
+
+## Field Reference
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| epicId | ✅ | Parent epic |
+| title | ✅ | Ticket title |
+| description | | What to implement |
+| complexity | | small \\| medium \\| large \\| xlarge |
+| acceptanceCriteria | | Success criteria (array of strings) |
+| implementation | | Steps, files to create/modify |
+| technicalDetails | | Approach, stack, endpoints |
+| codeReferences | | Code snippets to guide implementation |
+| typeReferences | | Type definitions to implement |
+| dependsOn | | Ticket IDs that must complete first |
+| notes | | Warnings, edge cases, considerations |
+
+## Notes
+- Only epicId and title are required
+- Tickets with dependsOn start as 'pending', others as 'ready'
+- codeReferences and typeReferences provide implementation guidance
+- Use /sf-next to start working on ready tickets
+`;

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

@@ -0,0 +1,69 @@
+/**
+ * SF-Epic Command Template
+ *
+ * Template for viewing epic details and progress.
+ */
+
+export const SF_EPIC_CONTENT = `# View Epic (SpecForge)
+
+View detailed information about a specific epic and its progress.
+
+## Arguments
+- \`$ARGUMENTS\` - Required: Epic ID (e.g., E1)
+
+## Task
+
+### 1. Get Epic Details
+
+**MCP Calls:**
+\`\`\`typescript
+get_epic($ARGUMENTS)
+get_specification(epic.specificationId)
+list_tickets({ epicId: $ARGUMENTS })
+\`\`\`
+
+### 2. Calculate Progress
+
+**Logic:**
+- Count tickets by status
+- Calculate completion percentage
+- Identify blockers
+- Track velocity
+
+### 3. Display Epic Overview
+
+**Output:**
+\`\`\`
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+EPIC: E{n}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+{title}
+
+Specification: {specTitle}
+Progress:      {done}/{total} ({percentage}%)
+Status:        {status}
+
+DESCRIPTION
+─────────────────────────────────────────────────────────────────
+{description}
+
+TICKETS
+─────────────────────────────────────────────────────────────────
+✓ E{n}-T{m} │ {title} │ done
+→ E{n}-T{m} │ {title} │ in_progress
+○ E{n}-T{m} │ {title} │ ready
+⊗ E{n}-T{m} │ {title} │ blocked
+
+PATTERNS
+─────────────────────────────────────────────────────────────────
+{epicPatterns}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Next: Run /sf-next to continue implementation
+\`\`\`
+
+## Notes
+- Shows all tickets in epic
+- Displays epic-level patterns
+- Use /sf-ticket-implementation <id> to work on specific ticket
+`;

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

@@ -0,0 +1,61 @@
+/**
+ * SF-Help Command Template
+ *
+ * Template for displaying SpecForge command reference.
+ */
+
+export const SF_HELP_CONTENT = `# SpecForge Command Reference
+
+Quick reference for all available SpecForge slash commands.
+
+## Task
+
+Display the command reference:
+
+\`\`\`
+═══════════════════════════════════════════════════════════════════
+                    SPECFORGE 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
+
+MANAGEMENT
+─────────────────────────────────────────────────────────────────
+/sf-review [spec-id]         Accomplishment review
+/sf-reset [spec-id]          Reset ticket statuses
+
+═══════════════════════════════════════════════════════════════════
+Tip: Use /sf-init first to set up your working context.
+═══════════════════════════════════════════════════════════════════
+\`\`\`
+
+## Notes
+- Commands use MCP tools from @specforge/mcp
+- Context is persisted across commands
+- Use /sf-status to see current progress
+`;