@specforge/mcp 3.0.7 → 3.1.1

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

@@ -0,0 +1,61 @@
+/**
+ * SF-Init Command Template
+ *
+ * Template for initializing SpecForge specification for implementation work.
+ */
+
+export const SF_INIT_CONTENT = `# Initialize Ticket System (SpecForge)
+
+Initialize a SpecForge specification for implementation work.
+
+## Arguments
+- \`$ARGUMENTS\` - Optional: Specification ID to initialize
+
+## Task
+
+### 1. Get or Set Working Context
+
+**MCP Calls:**
+\`\`\`typescript
+// Get current context
+get_working_context()
+
+// If $ARGUMENTS provided, set specification
+set_working_context({
+  specificationId: "$ARGUMENTS"
+})
+\`\`\`
+
+### 2. Load Specification Details
+
+**MCP Calls:**
+\`\`\`typescript
+get_specification(specificationId)
+list_epics({ specificationId })
+list_tickets({ specificationId })
+\`\`\`
+
+### 3. Display Initialization Summary
+
+**Output:**
+\`\`\`
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+SPECFORGE INITIALIZED
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Specification: {title}
+Status:        {status}
+Epics:         {epicCount}
+Tickets:       {ticketCount}
+
+Progress:      {done}/{total} ({percentage}%)
+Ready:         {readyCount} tickets available
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Next: Run /sf-next to start the next ready ticket
+\`\`\`
+
+## Notes
+- Context persists across commands
+- Use /sf-status for detailed view
+- Use /sf-next to start implementation
+`;

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

@@ -0,0 +1,67 @@
+/**
+ * SF-Next Command Template
+ *
+ * Template for quick starting the next ready ticket.
+ */
+
+export const SF_NEXT_CONTENT = `# Quick Start Next Ticket (SpecForge)
+
+Automatically find and start the next ready ticket for implementation.
+
+## Task
+
+### 1. Find Next Ready Ticket
+
+**MCP Calls:**
+\`\`\`typescript
+get_working_context()
+list_tickets({
+  specificationId,
+  status: 'ready',
+  sortBy: 'priority'
+})
+\`\`\`
+
+### 2. Set Ticket Context
+
+**MCP Calls:**
+\`\`\`typescript
+set_working_context({
+  ticketId: nextTicket.id
+})
+update_ticket({
+  ticketId: nextTicket.id,
+  status: 'in_progress'
+})
+\`\`\`
+
+### 3. Display Ticket Details
+
+**Output:**
+\`\`\`
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+STARTING: E{n}-T{m}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Title:        {title}
+Priority:     {priority}
+Epic:         E{n} - {epicTitle}
+Dependencies: {depCount} completed
+
+DESCRIPTION
+─────────────────────────────────────────────────────────────────
+{description}
+
+ACCEPTANCE CRITERIA
+─────────────────────────────────────────────────────────────────
+□ {criterion1}
+□ {criterion2}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Ready to implement!
+\`\`\`
+
+## Notes
+- Automatically selects highest priority ready ticket
+- Updates ticket status to in_progress
+- Sets working context to selected ticket
+`;

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

@@ -0,0 +1,78 @@
+/**
+ * SF-Reset Command Template
+ *
+ * Template for resetting ticket statuses with dependency awareness.
+ */
+
+export const SF_RESET_CONTENT = `# Reset Ticket Statuses (SpecForge)
+
+Reset ticket statuses to ready state with dependency awareness.
+
+## Arguments
+- \`$ARGUMENTS\` - Optional: Specification ID or ticket ID to reset
+
+## Task
+
+### 1. Get Reset Scope
+
+**MCP Calls:**
+\`\`\`typescript
+get_working_context()
+
+if ($ARGUMENTS.match(/E\d+-T\d+/)) {
+  // Single ticket reset
+  get_ticket($ARGUMENTS)
+} else {
+  // Full specification reset
+  if ($ARGUMENTS) {
+    set_working_context({ specificationId: "$ARGUMENTS" })
+  }
+  list_tickets({ specificationId })
+}
+\`\`\`
+
+### 2. Reset Tickets
+
+**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'
+  })
+}
+\`\`\`
+
+### 3. Display Reset Results
+
+**Output:**
+\`\`\`
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+TICKET RESET COMPLETE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Scope: {scope}
+
+RESET SUMMARY
+─────────────────────────────────────────────────────────────────
+Ready:   {readyCount} tickets
+Blocked: {blockedCount} tickets
+Done:    {doneCount} tickets (unchanged)
+
+RESET TICKETS
+─────────────────────────────────────────────────────────────────
+E{n}-T{m} │ {oldStatus} → {newStatus}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+\`\`\`
+
+## Notes
+- Respects dependency constraints
+- Can reset single ticket or entire specification
+- Completed tickets remain unchanged by default
+`;

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

@@ -0,0 +1,67 @@
+/**
+ * SF-Review Command Template
+ *
+ * Template for reviewing accomplishments and progress analysis.
+ */
+
+export const SF_REVIEW_CONTENT = `# Review Accomplishments (SpecForge)
+
+Comprehensive review of implementation progress and accomplishments.
+
+## Arguments
+- \`$ARGUMENTS\` - Optional: Specification ID to review
+
+## Task
+
+### 1. Get Specification Context
+
+**MCP Calls:**
+\`\`\`typescript
+get_working_context()
+
+if ($ARGUMENTS) {
+  set_working_context({ specificationId: "$ARGUMENTS" })
+}
+
+get_specification(specificationId)
+\`\`\`
+
+### 2. Load Implementation Data
+
+**MCP Calls:**
+\`\`\`typescript
+list_epics({ specificationId })
+list_tickets({ specificationId })
+\`\`\`
+
+### 3. Display Review Summary
+
+**Output:**
+\`\`\`
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+IMPLEMENTATION REVIEW
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Specification: {title}
+Overall:       {done}/{total} ({percentage}%)
+
+PROGRESS BY EPIC
+─────────────────────────────────────────────────────────────────
+E{n} │ {title} │ {ticketsDone}/{ticketsTotal} ({pct}%)
+
+RECENTLY COMPLETED
+─────────────────────────────────────────────────────────────────
+✓ E{n}-T{m} │ {title} │ {completedDate}
+
+VELOCITY
+─────────────────────────────────────────────────────────────────
+Last 7 days:  {ticketsCompleted} tickets
+Average:      {avgPerDay} tickets/day
+Remaining:    ~{estimatedDays} days
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+\`\`\`
+
+## Notes
+- Shows completed tickets and velocity metrics
+- Provides estimated completion timeline
+- Use /sf-status for current state
+`;

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

@@ -0,0 +1,64 @@
+/**
+ * SF-Search Command Template
+ *
+ * Template for searching tickets by text, tags, or filters.
+ */
+
+export const SF_SEARCH_CONTENT = `# Search Tickets (SpecForge)
+
+Search tickets by text, tags, status, or other filters.
+
+## Arguments
+- \`$ARGUMENTS\` - Required: Search query
+
+## Task
+
+### 1. Parse Search Query
+
+**Logic:**
+- Extract search terms
+- Parse filters (status:, epic:, tag:)
+- Identify text search vs filter search
+
+### 2. Search Tickets
+
+**MCP Calls:**
+\`\`\`typescript
+get_working_context()
+
+list_tickets({
+  specificationId,
+  search: extractedTerms,
+  status: extractedStatus,
+  epicId: extractedEpicId,
+  tags: extractedTags
+})
+\`\`\`
+
+### 3. Display Search Results
+
+**Output:**
+\`\`\`
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+SEARCH RESULTS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Query: {query}
+Found: {resultCount} tickets
+
+RESULTS
+─────────────────────────────────────────────────────────────────
+E{n}-T{m} │ {title} │ {status}
+  {matchedText}...
+
+E{n}-T{m} │ {title} │ {status}
+  {matchedText}...
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Tip: Use filters like status:ready or epic:E1
+\`\`\`
+
+## Notes
+- Supports text search and filters
+- Filters: status:, epic:, tag:, priority:
+- Can combine multiple filters
+`;

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

@@ -0,0 +1,67 @@
+/**
+ * SF-Status Command Template
+ *
+ * Template for displaying implementation status with consolidated tools.
+ */
+
+export const SF_STATUS_CONTENT = `# Implementation Status (SpecForge)
+
+Display comprehensive implementation status with consolidated progress view.
+
+## Arguments
+- \`$ARGUMENTS\` - Optional: Specification ID to view status for
+
+## Task
+
+### 1. Get Working Context
+
+**MCP Calls:**
+\`\`\`typescript
+get_working_context()
+
+// If $ARGUMENTS provided, switch context
+if ($ARGUMENTS) {
+  set_working_context({ specificationId: "$ARGUMENTS" })
+}
+\`\`\`
+
+### 2. Load Implementation Data
+
+**MCP Calls:**
+\`\`\`typescript
+get_specification(specificationId)
+list_epics({ specificationId })
+list_tickets({ specificationId })
+\`\`\`
+
+### 3. Display Status Overview
+
+**Output:**
+\`\`\`
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+IMPLEMENTATION STATUS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Specification: {title}
+Progress:      {done}/{total} ({percentage}%)
+
+EPICS
+─────────────────────────────────────────────────────────────────
+E{n} │ {title} │ {progress}% │ {status}
+
+READY TICKETS
+─────────────────────────────────────────────────────────────────
+E{n}-T{m} │ {title} │ {priority}
+
+BLOCKED TICKETS
+─────────────────────────────────────────────────────────────────
+E{n}-T{m} │ {title} │ Blocked by: {dependencies}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Next: Run /sf-next to start implementation
+\`\`\`
+
+## Notes
+- Shows overall progress and epic breakdown
+- Lists ready and blocked tickets
+- Use /sf-validate for system health check
+`;

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

@@ -0,0 +1,76 @@
+/**
+ * SF-Ticket-Implementation Command Template
+ *
+ * Template for implementing a specific ticket with streamlined workflow.
+ */
+
+export const SF_TICKET_IMPLEMENTATION_CONTENT = `# Implement Ticket (SpecForge)
+
+Implement a specific ticket with full context and streamlined workflow.
+
+## Arguments
+- \`$ARGUMENTS\` - Optional: Ticket ID to implement (e.g., E1-T3)
+
+## Task
+
+### 1. Select Ticket
+
+**MCP Calls:**
+\`\`\`typescript
+// If no arguments, prompt user
+if (!$ARGUMENTS) {
+  list_tickets({
+    specificationId,
+    status: 'ready'
+  })
+  // Display selection menu
+}
+
+// Get ticket details
+get_ticket($ARGUMENTS || selectedId)
+\`\`\`
+
+### 2. Verify Dependencies
+
+**MCP Calls:**
+\`\`\`typescript
+// Check all dependencies are completed
+for (const depId of ticket.dependencies) {
+  get_ticket(depId)
+  // Verify status is 'done'
+}
+\`\`\`
+
+### 3. Set Context and Start
+
+**MCP Calls:**
+\`\`\`typescript
+set_working_context({ ticketId: ticket.id })
+update_ticket({
+  ticketId: ticket.id,
+  status: 'in_progress'
+})
+\`\`\`
+
+### 4. Display Implementation View
+
+**Output:**
+\`\`\`
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+IMPLEMENTING: E{n}-T{m}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+{title}
+
+{fullDescription}
+{implementationGuidance}
+{acceptanceCriteria}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Begin implementation
+\`\`\`
+
+## Notes
+- Verifies all dependencies are completed
+- Provides full ticket context for implementation
+- Use /sf-commit when complete
+`;

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

@@ -0,0 +1,78 @@
+/**
+ * SF-Validate Command Template
+ *
+ * Template for validating ticket system health.
+ */
+
+export const SF_VALIDATE_CONTENT = `# Validate Ticket System (SpecForge)
+
+Run comprehensive health checks on the ticket system.
+
+## Arguments
+- \`$ARGUMENTS\` - Optional: Specification ID to validate
+
+## Task
+
+### 1. Get Specification Context
+
+**MCP Calls:**
+\`\`\`typescript
+get_working_context()
+
+if ($ARGUMENTS) {
+  set_working_context({ specificationId: "$ARGUMENTS" })
+}
+
+get_specification(specificationId)
+\`\`\`
+
+### 2. Load and Validate Data
+
+**MCP Calls:**
+\`\`\`typescript
+list_epics({ specificationId })
+list_tickets({ specificationId })
+
+// Validate each ticket
+for (const ticket of tickets) {
+  get_ticket(ticket.id)
+  // Check dependencies, status, fields
+}
+\`\`\`
+
+### 3. Display Validation Results
+
+**Output:**
+\`\`\`
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+SYSTEM VALIDATION
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Specification: {title}
+
+CHECKS
+─────────────────────────────────────────────────────────────────
+✓ All epics have valid structure
+✓ All tickets have required fields
+✓ Dependency graph is acyclic
+✓ Status transitions are valid
+✓ No orphaned tickets
+
+WARNINGS
+─────────────────────────────────────────────────────────────────
+⚠ E{n}-T{m}: Missing acceptance criteria
+⚠ E{n}-T{m}: Long dependency chain (depth {n})
+
+ERRORS
+─────────────────────────────────────────────────────────────────
+✗ E{n}-T{m}: Circular dependency detected
+✗ E{n}-T{m}: Invalid dependency reference
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Status: {errors ? 'FAILED' : 'PASSED'}
+\`\`\`
+
+## Notes
+- Checks dependency graph integrity
+- Validates ticket structure and fields
+- Reports warnings and errors
+`;

package/src/cli/templates/index.ts

@@ -0,0 +1,16 @@
+/**
+ * Templates Module
+ *
+ * Exports all template functions for command and agent scaffolding.
+ */
+
+// Command templates
+export { getCommandTemplates, getCommandTemplate, getCommandsByCategory } from './commands.js';
+
+// Agent templates
+export {
+  getAgentTemplates,
+  getAgentTemplate,
+  getAgentsByCategory,
+  getAgentNames,
+} from './agents/index.js';

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

@@ -0,0 +1,109 @@
+# {{PROJECT_NAME}} — Coding Conventions
+
+Project-specific coding standards for SpecForge Agent Teams workers. Workers follow these conventions when implementing tickets.
+
+## Language & Framework
+
+- **Language:** {{LANGUAGE}}
+- **Framework:** {{FRAMEWORK}}
+- **Runtime:** {{RUNTIME}}
+
+## Naming Conventions
+
+### Files
+- Components: `PascalCase.tsx` (e.g., `UserProfile.tsx`)
+- Utilities/helpers: `kebab-case.ts` (e.g., `date-utils.ts`)
+- Tests: `{filename}.test.ts` or `{filename}.spec.ts`
+- Styles: `{ComponentName}.module.css` or co-located
+
+### Code
+- Functions: `camelCase` (e.g., `getUserById`)
+- Interfaces/Types: `PascalCase` (e.g., `UserProfile`, `CreateUserInput`)
+- Constants: `UPPER_SNAKE_CASE` (e.g., `MAX_RETRIES`)
+- Enums: `PascalCase` with `PascalCase` members
+- Boolean variables: prefix with `is`, `has`, `should`, `can` (e.g., `isLoading`)
+
+## Import Style
+
+```
+// 1. External packages
+import React from 'react';
+import { useState } from 'react';
+
+// 2. Internal aliases (@/ paths)
+import { Button } from '@/components/ui/Button';
+import { useAuth } from '@/lib/hooks/useAuth';
+
+// 3. Relative imports
+import { helper } from './utils';
+import type { Props } from './types';
+
+// 4. Type-only imports (separate)
+import type { User } from '@/lib/types';
+```
+
+## Error Handling
+
+```
+// Use try/catch for async operations
+try {
+  const result = await apiCall();
+  return result;
+} catch (error) {
+  // Log with context
+  console.error('Failed to fetch user:', error);
+  // Re-throw or return error state — don't swallow errors silently
+  throw error;
+}
+```
+
+- Use typed error handling where possible
+- Return error states from hooks/functions rather than throwing in UI code
+- Log errors with context (what operation failed, relevant IDs)
+
+## Test Patterns
+
+- **Test framework:** {{TEST_FRAMEWORK}}
+- **Location:** Co-located `__tests__/` directories or `*.test.ts` files
+- **Pattern:** Arrange-Act-Assert
+
+```
+describe('functionName', () => {
+  it('should handle the expected case', () => {
+    // Arrange
+    const input = createTestInput();
+
+    // Act
+    const result = functionName(input);
+
+    // Assert
+    expect(result).toEqual(expectedOutput);
+  });
+});
+```
+
+## State Management
+
+- {{STATE_PATTERN}}
+- Keep state as close to where it's used as possible
+- Avoid prop drilling beyond 2 levels — use context or state management
+
+## API Patterns
+
+- {{API_PATTERN}}
+- Use consistent response shapes
+- Handle loading, error, and success states
+
+## Monorepo Rules
+
+_(Remove this section for single-app projects)_
+
+- **Workspace tool:** {{WORKSPACE_TOOL}}
+- Workers must stay within their assigned workspace
+- Shared packages go in `packages/` directory
+- Cross-workspace imports use package names, not relative paths
+- Run commands scoped to the workspace: `cd {workspace} && {command}`
+
+## Project-Specific Notes
+
+_(Add any project-specific conventions here)_