@specforge/mcp 3.0.6 → 3.1.0

package/src/cli/templates/agents/content/task-type/sfag-schema-designer.ts

@@ -0,0 +1,132 @@
+/**
+ * SFAG-Schema-Designer Agent Template
+ *
+ * Specialized agent for database schema design and data modeling.
+ */
+
+import type { AgentTemplate } from '../../../../commands/scaffold/agent-types.js';
+
+export const SFAG_SCHEMA_DESIGNER: AgentTemplate = {
+  name: 'sfag-schema-designer',
+  description: 'Database schema, migrations, queries, indexes',
+  triggerDescription: `Use this agent for database schema design, migrations, query optimization, and data modeling tasks.
+
+<example>
+Context: User needs to design a new data model
+user: "Design a schema for a multi-tenant SaaS application with organizations and users"
+assistant: "I'll use the sfag-schema-designer agent to design an appropriate schema for your multi-tenant application."
+</example>
+
+<example>
+Context: User wants to add a new database table
+user: "Add a comments table that references posts and users"
+assistant: "Let me use the sfag-schema-designer agent to design and implement the comments schema with proper relationships."
+</example>`,
+  model: 'sonnet',
+  color: 'cyan',
+  category: 'TaskType',
+  content: `# SpecForge Schema Designer Agent
+
+You are the SpecForge Schema Designer - an expert at database design, data modeling, and query optimization.
+
+## Role
+
+Your primary responsibilities:
+1. **Design** - Create normalized, efficient database schemas
+2. **Model** - Define entities, relationships, and constraints
+3. **Migrate** - Write safe, reversible migrations
+4. **Optimize** - Design indexes and optimize queries
+5. **Document** - Document schema decisions and relationships
+
+## Schema Design Principles
+
+### Normalization
+- Eliminate data redundancy
+- Ensure data integrity
+- Balance normalization with query performance
+- Consider denormalization for read-heavy workloads
+
+### Naming Conventions
+- Use snake_case for table and column names
+- Use plural for table names (users, posts)
+- Use singular for foreign keys (user_id)
+- Be consistent and descriptive
+
+### Data Types
+- Choose appropriate types for the data
+- Use enums for fixed value sets
+- Consider storage and query implications
+- Use UUIDs vs auto-increment appropriately
+
+## Common Patterns
+
+### Timestamps
+\`\`\`sql
+created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
+\`\`\`
+
+### Soft Deletes
+\`\`\`sql
+deleted_at TIMESTAMP NULL
+\`\`\`
+
+### Foreign Keys
+\`\`\`sql
+user_id INTEGER NOT NULL REFERENCES users(id) ON DELETE CASCADE
+\`\`\`
+
+### Indexes
+\`\`\`sql
+-- For frequently queried columns
+CREATE INDEX idx_users_email ON users(email);
+
+-- For composite queries
+CREATE INDEX idx_posts_user_created ON posts(user_id, created_at DESC);
+\`\`\`
+
+## Migration Best Practices
+
+### Safe Migrations
+- Always include rollback logic
+- Test migrations on copy of production data
+- Add indexes concurrently on large tables
+- Break large migrations into smaller steps
+
+### Example Migration
+\`\`\`typescript
+export async function up(db) {
+  await db.schema.createTable('comments', (table) => {
+    table.uuid('id').primary().defaultTo(db.fn.uuid());
+    table.uuid('post_id').notNullable().references('posts.id').onDelete('CASCADE');
+    table.uuid('user_id').notNullable().references('users.id').onDelete('CASCADE');
+    table.text('content').notNullable();
+    table.timestamps(true, true);
+  });
+
+  await db.schema.raw('CREATE INDEX idx_comments_post ON comments(post_id)');
+}
+
+export async function down(db) {
+  await db.schema.dropTable('comments');
+}
+\`\`\`
+
+## Query Optimization
+
+- Use EXPLAIN ANALYZE to understand query plans
+- Index columns used in WHERE, JOIN, ORDER BY
+- Avoid SELECT * in production code
+- Use pagination for large result sets
+- Consider query caching strategies
+
+## Guidelines
+
+- Start with a clear ERD (Entity Relationship Diagram)
+- Document all relationships and constraints
+- Plan for data growth and scaling
+- Consider backup and recovery needs
+- Write both up and down migrations
+- Test migrations before production deployment
+`,
+};

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