@specforge/mcp 3.0.7 → 3.1.1

package/src/cli/templates/agents/content/task-type/sfag-test-writer.ts

@@ -0,0 +1,171 @@
+/**
+ * SFAG-Test-Writer Agent Template
+ *
+ * Specialized agent for writing comprehensive tests.
+ */
+
+import type { AgentTemplate } from '../../../../commands/scaffold/agent-types.js';
+
+export const SFAG_TEST_WRITER: AgentTemplate = {
+  name: 'sfag-test-writer',
+  description: 'Unit, integration, e2e tests',
+  triggerDescription: `Use this agent for writing unit tests, integration tests, and end-to-end tests.
+
+<example>
+Context: User implemented a new feature and needs tests
+user: "Write tests for the new authentication service"
+assistant: "I'll use the sfag-test-writer agent to write comprehensive tests for the authentication service."
+</example>
+
+<example>
+Context: User wants to add e2e tests
+user: "Add Playwright tests for the checkout flow"
+assistant: "Let me use the sfag-test-writer agent to create e2e tests for the checkout flow."
+</example>`,
+  model: 'haiku',
+  color: 'yellow',
+  category: 'TaskType',
+  content: `# SpecForge Test Writer Agent
+
+You are the SpecForge Test Writer - an expert at writing comprehensive, maintainable tests.
+
+## Role
+
+Your primary responsibilities:
+1. **Analyze** - Understand what needs to be tested
+2. **Design** - Plan test cases for comprehensive coverage
+3. **Write** - Create clear, maintainable tests
+4. **Verify** - Ensure tests are reliable and not flaky
+5. **Document** - Write clear test descriptions
+
+## Testing Principles
+
+### Test Pyramid
+- Many unit tests (fast, isolated)
+- Some integration tests (components together)
+- Few e2e tests (full system)
+
+### Good Test Properties
+- **Fast** - Tests should run quickly
+- **Isolated** - No dependencies between tests
+- **Repeatable** - Same result every time
+- **Self-validating** - Pass or fail, no manual checking
+- **Timely** - Written close to the code
+
+## Unit Tests
+
+\`\`\`typescript
+import { describe, it, expect, vi } from 'vitest';
+import { calculateTotal } from './cart';
+
+describe('calculateTotal', () => {
+  it('returns 0 for empty cart', () => {
+    expect(calculateTotal([])).toBe(0);
+  });
+
+  it('sums item prices correctly', () => {
+    const items = [
+      { price: 10, quantity: 2 },
+      { price: 5, quantity: 1 },
+    ];
+    expect(calculateTotal(items)).toBe(25);
+  });
+
+  it('applies discount when provided', () => {
+    const items = [{ price: 100, quantity: 1 }];
+    expect(calculateTotal(items, 0.1)).toBe(90);
+  });
+});
+\`\`\`
+
+## Integration Tests
+
+\`\`\`typescript
+describe('UserService', () => {
+  let db: Database;
+  let userService: UserService;
+
+  beforeEach(async () => {
+    db = await createTestDatabase();
+    userService = new UserService(db);
+  });
+
+  afterEach(async () => {
+    await db.close();
+  });
+
+  it('creates user and stores in database', async () => {
+    const user = await userService.create({
+      email: 'test@example.com',
+      name: 'Test User',
+    });
+
+    const stored = await db.users.findById(user.id);
+    expect(stored).toMatchObject({
+      email: 'test@example.com',
+      name: 'Test User',
+    });
+  });
+});
+\`\`\`
+
+## E2E Tests
+
+\`\`\`typescript
+import { test, expect } from '@playwright/test';
+
+test('user can complete checkout', async ({ page }) => {
+  await page.goto('/products');
+
+  // Add item to cart
+  await page.click('[data-testid="add-to-cart"]');
+
+  // Go to checkout
+  await page.click('[data-testid="checkout-button"]');
+
+  // Fill shipping info
+  await page.fill('[name="address"]', '123 Test St');
+  await page.fill('[name="city"]', 'Test City');
+
+  // Complete purchase
+  await page.click('[data-testid="place-order"]');
+
+  // Verify success
+  await expect(page.locator('.order-confirmation')).toBeVisible();
+});
+\`\`\`
+
+## Mocking Strategies
+
+\`\`\`typescript
+// Mock functions
+const mockFetch = vi.fn().mockResolvedValue({ data: [] });
+
+// Mock modules
+vi.mock('./api', () => ({
+  fetchUsers: vi.fn().mockResolvedValue([]),
+}));
+
+// Spy on methods
+const spy = vi.spyOn(service, 'send');
+\`\`\`
+
+## Test Coverage
+
+Focus on:
+- Happy path (normal usage)
+- Edge cases (boundaries, empty, null)
+- Error cases (invalid input, failures)
+- Security cases (auth, permissions)
+
+## Guidelines
+
+- Write descriptive test names
+- One assertion per test (when practical)
+- Test behavior, not implementation
+- Don't test third-party code
+- Keep tests DRY but readable
+- Avoid flaky tests
+- Run tests before committing
+`,
+};

package/src/cli/templates/agents/index.ts

@@ -0,0 +1,74 @@
+/**
+ * Agent Templates Module
+ *
+ * Defines all SpecForge agent templates for scaffolding to AI CLI tools.
+ */
+
+import type { AgentTemplate, AgentCategory } from '../../commands/scaffold/agent-types.js';
+
+// Import core agents
+import { SFAG_ORCHESTRATOR } from './content/core/sfag-orchestrator.js';
+import { SFAG_IMPLEMENTER } from './content/core/sfag-implementer.js';
+import { SFAG_SPEC_CREATOR } from './content/core/sfag-spec-creator.js';
+import { SFAG_TICKET_IMPLEMENTER } from './content/core/sfag-ticket-implementer.js';
+
+// Import task-type agents
+import { SFAG_API_IMPLEMENTER } from './content/task-type/sfag-api-implementer.js';
+import { SFAG_SCHEMA_DESIGNER } from './content/task-type/sfag-schema-designer.js';
+import { SFAG_FRONTEND_BUILDER } from './content/task-type/sfag-frontend-builder.js';
+import { SFAG_INFRA_ARCHITECT } from './content/task-type/sfag-infra-architect.js';
+import { SFAG_TEST_WRITER } from './content/task-type/sfag-test-writer.js';
+import { SFAG_DOCS_WRITER } from './content/task-type/sfag-docs-writer.js';
+
+// Import research agents
+import { SFAG_PACKAGE_RESEARCHER } from './content/research/sfag-package-researcher.js';
+
+/**
+ * All agent templates
+ */
+const AGENT_TEMPLATES: AgentTemplate[] = [
+  // Core agents
+  SFAG_ORCHESTRATOR,
+  SFAG_IMPLEMENTER,
+  SFAG_SPEC_CREATOR,
+  SFAG_TICKET_IMPLEMENTER,
+
+  // Task-type agents
+  SFAG_API_IMPLEMENTER,
+  SFAG_SCHEMA_DESIGNER,
+  SFAG_FRONTEND_BUILDER,
+  SFAG_INFRA_ARCHITECT,
+  SFAG_TEST_WRITER,
+  SFAG_DOCS_WRITER,
+
+  // Research agents
+  SFAG_PACKAGE_RESEARCHER,
+];
+
+/**
+ * Get all agent templates
+ */
+export function getAgentTemplates(): AgentTemplate[] {
+  return AGENT_TEMPLATES;
+}
+
+/**
+ * Get a specific agent template by name
+ */
+export function getAgentTemplate(name: string): AgentTemplate | undefined {
+  return AGENT_TEMPLATES.find(t => t.name === name);
+}
+
+/**
+ * Get agent templates by category
+ */
+export function getAgentsByCategory(category: AgentCategory): AgentTemplate[] {
+  return AGENT_TEMPLATES.filter(t => t.category === category);
+}
+
+/**
+ * Get all agent template names
+ */
+export function getAgentNames(): string[] {
+  return AGENT_TEMPLATES.map(t => t.name);
+}

package/src/cli/templates/commands.ts

@@ -0,0 +1,179 @@
+/**
+ * Command Templates Module
+ *
+ * Defines all SpecForge slash commands with their full markdown content
+ * for scaffolding to AI CLI tools.
+ */
+
+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',
+      argumentHint: '[specification-id]',
+      content: SF_INIT_CONTENT,
+      category: 'Setup',
+    },
+    {
+      name: 'sf-context',
+      description: 'View or switch working context',
+      argumentHint: '[project-or-spec-id]',
+      content: SF_CONTEXT_CONTENT,
+      category: 'Setup',
+    },
+    // Status
+    {
+      name: 'sf-status',
+      description: 'Display implementation status with consolidated tools',
+      argumentHint: '[specification-id]',
+      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',
+      argumentHint: '<query>',
+      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',
+      argumentHint: '[specification-id]',
+      content: SF_RESET_CONTENT,
+      category: 'Utilities',
+    },
+    {
+      name: 'sf-commit',
+      description: 'Commit changes with SpecForge ticket metadata',
+      argumentHint: '[ticket-id]',
+      content: SF_COMMIT_CONTENT,
+      category: 'Utilities',
+    },
+    {
+      name: 'sf-help',
+      description: 'Quick reference for all SpecForge commands',
+      content: SF_HELP_CONTENT,
+      category: 'Utilities',
+    },
+  ];
+}
+
+/**
+ * Get a specific command template by name
+ */
+export function getCommandTemplate(name: string): CommandTemplate | undefined {
+  return getCommandTemplates().find(t => t.name === name);
+}
+
+/**
+ * Get command templates by category
+ */
+export function getCommandsByCategory(category: string): CommandTemplate[] {
+  return getCommandTemplates().filter(t => t.category === category);
+}

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

@@ -0,0 +1,78 @@
+/**
+ * SF-Run-Autonomous Command Template
+ *
+ * Template for running autonomous implementation for multiple tickets.
+ */
+
+export const SF_RUN_AUTONOMOUS_CONTENT = `# Run Autonomous Implementation (SpecForge)
+
+Execute autonomous batch implementation of ready tickets.
+
+## Arguments
+- \`$ARGUMENTS\` - Optional: Maximum number of tickets to implement (default: 5)
+
+## Task
+
+### 1. Get Ready Tickets
+
+**MCP Calls:**
+\`\`\`typescript
+get_working_context()
+list_tickets({
+  specificationId,
+  status: 'ready',
+  sortBy: 'priority'
+})
+\`\`\`
+
+### 2. For Each Ticket (up to max)
+
+**MCP Calls:**
+\`\`\`typescript
+// Set context
+set_working_context({ ticketId: ticket.id })
+
+// Update status
+update_ticket({
+  ticketId: ticket.id,
+  status: 'in_progress'
+})
+
+// Get full details
+get_ticket(ticket.id)
+
+// Implement ticket
+// ... implementation logic ...
+
+// Mark complete
+update_ticket({
+  ticketId: ticket.id,
+  status: 'done'
+})
+\`\`\`
+
+### 3. Display Summary
+
+**Output:**
+\`\`\`
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+AUTONOMOUS IMPLEMENTATION COMPLETE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Completed: {completedCount}/{attemptedCount}
+Duration:  {duration}
+
+COMPLETED TICKETS
+─────────────────────────────────────────────────────────────────
+✓ E{n}-T{m} │ {title}
+
+FAILED TICKETS
+─────────────────────────────────────────────────────────────────
+✗ E{n}-T{m} │ {title} │ {reason}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+\`\`\`
+
+## Notes
+- Implements tickets in priority order
+- Stops on errors or when max reached
+- Use /sf-review to see detailed results
+`;

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

@@ -0,0 +1,68 @@
+/**
+ * SF-Analyze-Blockers Command Template
+ *
+ * Template for analyzing blockers and dependency bottlenecks.
+ */
+
+export const SF_ANALYZE_BLOCKERS_CONTENT = `# Analyze Blockers (SpecForge)
+
+Analyze dependency bottlenecks and identify critical path tickets.
+
+## Task
+
+### 1. Get Implementation Data
+
+**MCP Calls:**
+\`\`\`typescript
+get_working_context()
+get_specification(specificationId)
+list_epics({ specificationId })
+list_tickets({ specificationId })
+\`\`\`
+
+### 2. Analyze Dependencies
+
+**Logic:**
+- Build dependency graph
+- Calculate blocking relationships
+- Identify critical path
+- Find bottleneck tickets
+
+### 3. Display Analysis Results
+
+**Output:**
+\`\`\`
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+BLOCKER ANALYSIS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Specification: {title}
+
+CRITICAL PATH
+─────────────────────────────────────────────────────────────────
+Length: {pathLength} tickets
+Impact: {blockedCount} tickets blocked
+
+E{n}-T{m} → E{n}-T{m} → E{n}-T{m} → ...
+
+HIGH-IMPACT BLOCKERS
+─────────────────────────────────────────────────────────────────
+E{n}-T{m} │ {title} │ Blocking {count} tickets
+  ↳ E{n}-T{m}, E{n}-T{m}, E{n}-T{m}
+
+BLOCKED TICKETS
+─────────────────────────────────────────────────────────────────
+E{n}-T{m} │ {title}
+  ⚠ Waiting on: E{n}-T{m} ({status})
+
+RECOMMENDATIONS
+─────────────────────────────────────────────────────────────────
+• Prioritize E{n}-T{m} to unblock {count} tickets
+• Review dependency chain for E{n}-T{m}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+\`\`\`
+
+## Notes
+- Identifies tickets blocking the most work
+- Shows critical path through implementation
+- Provides actionable recommendations
+`;

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
+`;