@specforge/cli 0.1.0

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

@@ -0,0 +1,65 @@
+/**
+ * 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
+// Read project config
+const config = readFile('.specforge.json')
+const specificationId = config.activeSpecification?.id
+
+search_tickets({
+  specificationId,
+  query: extractedTerms,
+  status: extractedStatus,
+  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,64 @@
+/**
+ * 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 Specification Context
+
+**Logic:**
+\`\`\`typescript
+// Read project config
+const config = readFile('.specforge.json')
+const specificationId = $ARGUMENTS || config.activeSpecification?.id
+\`\`\`
+
+### 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/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,114 @@
+---
+name: specforge-conventions
+description: Project-specific coding standards and conventions for SpecForge Agent Teams workers
+---
+
+# {{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)_

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

@@ -0,0 +1,409 @@
+---
+name: specforge-orchestrator
+description: Plan and coordinate multi-agent implementation of a SpecForge specification using Claude Code Agent Teams. Use when implementing, building, executing, or working on a specification, epic, or set of tickets from SpecForge.
+when_to_use: Trigger phrases include "implement the active SpecForge specification", "build out the [name] epic", "work on all pending tickets", "continue the SpecForge implementation".
+---
+
+# SpecForge Implementation Orchestrator
+
+You are the SpecForge Orchestrator — responsible for planning and coordinating multi-agent implementation of a specification using Claude Code Agent Teams.
+
+## When to Use
+
+Activate this skill when the user asks to "implement", "build", "execute", or "work on" a specification, epic, or set of tickets from SpecForge. This includes phrases like:
+- "Implement the active SpecForge specification"
+- "Build out the auth epic"
+- "Work on all pending tickets"
+- "Continue the SpecForge implementation"
+
+## Prerequisites
+
+Before starting, verify:
+1. `.specforge.json` exists at the project root with `activeSpecification` set
+2. SpecForge MCP server is configured and reachable
+3. Agent Teams is enabled (`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` or via Claude Code settings)
+
+Read `.specforge.json` to get:
+- `project.id` — the SpecForge project ID
+- `activeSpecification.id` — the specification to implement
+- `agentTeams` — team preferences (strategy, maxParallelTeams, validation, etc.)
+- `monorepo` — workspace structure (if applicable)
+
+---
+
+## 7-Step Workflow
+
+### Step 1: Load Specification
+
+```
+1. Read .specforge.json → get activeSpecification.id
+2. Call: get_specification({ specificationId, include: ["epics", "status"] })
+   → Returns full spec with epics, ticket counts, and completion status
+3. Present summary to user:
+   - Specification title and description
+   - Number of epics, total tickets, completed tickets
+   - Current status
+4. Ask for confirmation before proceeding
+```
+
+### Step 2: Analyze & Plan
+
+Generate the implementation plan and dependency graph:
+
+```
+1. Call: get_implementation_plan({ specificationId, strategy: "auto" })
+   → Returns resolved strategy, phases, team assignments, estimates
+2. Call: get_epic_dependency_graph({ specificationId })
+   → Returns topologically sorted phases, cross-epic dependencies, critical path
+3. For each epic in the plan:
+   a. Call: get_next_actionable_tickets({ specificationId }) → ready tickets
+   b. Call: get_blocked_tickets({ specificationId }) → blocked tickets with reasons
+4. Build execution plan:
+   - Which teams to create (one per epic, or single team)
+   - Phase ordering (which teams run in parallel vs sequenced)
+   - Worker count per team
+   - Blocked tickets that need resolution before starting
+```
+
+**Strategy Decision Matrix:**
+
+| Condition | Strategy | Description |
+|-----------|----------|-------------|
+| 1 epic, 1-3 tickets | `single-session` | No teams needed — implement sequentially in current session |
+| 1 epic, >3 tickets | `spec-as-team` | Single team with multiple self-claiming workers |
+| Multiple independent epics | `parallel` (epic-as-team) | One team per epic, all run concurrently |
+| Multiple epics with cross-dependencies | `phased` (epic-as-team) | Teams ordered by dependency phases |
+| User specified strategy in agentTeams config | Use configured strategy | Respect `.specforge.json` preference |
+
+Present the plan to the user with:
+- Strategy reasoning
+- Team→epic mapping
+- Phase ordering
+- Estimated scope (ticket count, complexity)
+- Any blocked tickets that need attention first
+
+### Step 3: Create Teams
+
+For each team in the execution plan:
+
+```
+1. Create the team using Claude Code Agent Teams API:
+   - Team name: "sf-{epicSlug}" (e.g., "sf-auth-backend")
+   - Scope: one team per epic (epic-as-team) or one team for all (spec-as-team)
+
+2. For each ticket assigned to the team:
+   - Create a task with the ticket context
+   - Set dependencies between tasks matching ticket dependencies
+   - Include the worker execution protocol in each task prompt
+
+3. Spawn workers:
+   - One worker per independent ticket cluster
+   - Max workers from agentTeams.maxWorkersPerTeam (default: 3)
+   - Each worker gets: ticket context + workspace metadata + coding conventions
+```
+
+### Step 4: Worker Execution Protocol
+
+Each worker spawned by the orchestrator MUST follow this 9-step protocol:
+
+```
+1. CLAIM:  Call get_next_actionable_tickets({ specificationId }) to find a ready ticket
+2. START:  Call start_work_session({ ticketId }) to transition ready → active
+3. CONTEXT:
+   a. Call get_implementation_context({ ticketId, depth: "full" }) → full ticket context
+   b. Call get_workspace_files({ workspacePath }) → workspace metadata (local only)
+   c. Call blueprint({ operation: "get_for_ticket", ticketId }) → linked blueprints
+   d. Call get_patterns({ ticketId }) → resolved code patterns with inheritance
+4. BRANCH: Create git branch following the configured pattern:
+   - Default: ticket/E{epicNumber}-T{ticketNumber}-{slug}
+   - Pattern from agentTeams.branchPattern in .specforge.json
+5. IMPLEMENT:
+   - Read existing files referenced by the ticket
+   - Write code following ticket implementation guide and project patterns
+   - Follow coding conventions from spec/epic patterns
+   - Only modify files within assigned workspace (monorepo rule)
+6. VALIDATE:
+   - Run test command if configured: agentTeams.validationCommands.test
+   - Run lint command if configured: agentTeams.validationCommands.lint
+   - Run typecheck command if configured: agentTeams.validationCommands.typeCheck
+7. COMMIT:
+   - Stage changed files
+   - Commit with message: "feat({scope}): {ticket.title} [SF-{ticketId}]"
+8. REPORT:
+   - Use action_work_session to mark all steps done, validate all AC, and report files:
+     action_work_session({ ticketId, allStepsDone: true, allACValidated: true,
+       filesCreated: [...], filesModified: [...], filesDeleted: [...] })
+   - Then call complete_work_session({
+       ticketId,
+       summary: "description of changes",
+       filesCreated: [...],
+       filesModified: [...],
+       filesDeleted: [...],
+       validation: { tests: "passed", lint: "passed", typeCheck: "passed" }
+     })
+   - Message team lead: "Completed E{n}-T{n}: {summary}"
+9. NEXT:
+   - Self-claim next ready ticket (go to step 1)
+   - If no more ready tickets, signal epic complete to team lead
+```
+
+**When a worker encounters a blocker:**
+```
+1. Call action_work_session({ ticketId, discovery: { description: "description of blocker", type: "blocker", severity: "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}"
+4. Move to next available ticket or wait for lead's guidance
+```
+
+**When a worker discovers additional work:**
+```
+1. Message team lead: "Discovery: {description}. Should I create a ticket?"
+2. Wait for lead's decision
+3. If approved: Call create_ticket({ epicId, title, description, ... })
+```
+
+### Step 5: Team Lead Coordination
+
+As the lead, monitor all teams continuously:
+
+```
+Every coordination cycle:
+  1. Check teammate messages (automatic delivery via Agent Teams)
+
+  2. For completed tickets:
+     - Review worker's completion summary
+     - If validation watcher is active, wait for watcher's report
+     - Verify acceptance criteria were addressed
+
+  3. For blocked tickets:
+     - Call get_blocked_tickets({ specificationId }) to see current blockers
+     - Assess if blocker can be resolved (missing dependency, external issue)
+     - Reassign or escalate to user if needed
+
+  4. For discoveries:
+     - Present to user for decision
+     - Create tickets if approved
+
+  5. Cross-epic dependency handling:
+     - When an epic's tickets complete → dependent epics may become unblocked
+     - SpecForge automatically recalculates ticket statuses on completion
+     - Notify relevant team workers of newly unblocked tickets
+
+  6. Track progress:
+     - Call get_report({ type: "implementation", scope: "specification", scopeId: specId })
+     - Report progress to user periodically
+```
+
+### Step 6: Validation (Watcher Pattern)
+
+If `agentTeams.autoValidate` is true (default), spawn a validation watcher per team:
+
+```
+Validator role:
+  - Name: "validator-{epicSlug}"
+  - After each worker reports a ticket as complete:
+    1. Pull/check the worker's changes
+    2. Run: validationCommands.test (if configured)
+    3. Run: validationCommands.lint (if configured)
+    4. Run: validationCommands.typeCheck (if configured)
+    5. Run: validationCommands.build (if configured)
+
+  - On success: Message team lead "E{n}-T{n} validated"
+  - On failure: Message the worker with specific errors for fixing
+
+  - The validator does NOT modify code — only runs checks and reports
+```
+
+### Step 7: Completion
+
+When all tickets in a team's epic are done:
+
+```
+1. Run final validation suite on the epic's workspace
+2. Call report_completion({
+     entityType: "epic",
+     entityId: epicId,
+     summary: "Epic completion summary",
+     metrics: { completedTickets, totalTickets, totalHours }
+   })
+3. Clean up the team (requestShutdown for workers)
+4. Report to user: "Epic '{title}' complete: {summary}"
+5. If more phases remain, proceed to next phase
+6. If all epics are done:
+   - Call report_completion({
+       entityType: "specification",
+       entityId: specId,
+       summary: "Specification completion summary"
+     })
+   - Present final report to user with metrics
+```
+
+---
+
+## Worker Spawn Template
+
+Use this template when spawning a worker agent:
+
+```
+You are implementing SpecForge ticket E{epicNumber}-T{ticketNumber}: {title}
+
+## Your Protocol
+Follow the 9-step worker execution protocol:
+CLAIM → START → CONTEXT → BRANCH → IMPLEMENT → VALIDATE → COMMIT → REPORT → NEXT
+
+## Ticket Details
+{ticket.description}
+
+## Implementation Guide
+{ticket.implementation}
+
+## Acceptance Criteria
+{ticket.acceptanceCriteria}
+
+## Workspace
+Path: {workspace.path}
+Framework: {workspace.framework}
+Key dependencies: {workspace.keyDependencies}
+
+## Conventions
+{patterns.naming}
+{patterns.imports}
+{patterns.errorHandling}
+
+## MCP Tools Available
+- start_work_session({ ticketId }) — mark ticket as active
+- get_implementation_context({ ticketId, depth: "full" }) — load full context
+- get_workspace_files({ workspacePath }) — workspace metadata
+- get_patterns({ ticketId }) — code patterns with inheritance
+- action_work_session({ ticketId, steps, acceptanceCriteria, filesCreated, filesModified, filesDeleted, ... }) — update checklist, files, and blockers during active session
+- complete_work_session({ ticketId, summary, filesCreated, filesModified, filesDeleted, validation }) — mark done (requires all AC/steps completed first)
+- get_next_actionable_tickets({ specificationId }) — claim next ticket
+- Note: update_ticket is locked during active sessions — use action_work_session instead
+
+## Rules
+- Only modify files within your assigned workspace unless explicitly required
+- Follow the project's coding conventions from patterns
+- Write tests for new functionality when test infrastructure exists
+- Report any blockers or discoveries to team lead immediately
+- Always start_work_session before implementing and complete_work_session when done
+```
+
+## Validation Watcher Spawn Template
+
+```
+You are the validation watcher for epic "{epic.title}".
+
+## Your Role
+After each teammate reports a ticket as complete:
+1. Check their changes
+2. Run: {validationCommands.test}
+3. Run: {validationCommands.lint}
+4. Run: {validationCommands.typeCheck}
+5. Run: {validationCommands.build}
+6. Report results to team lead
+
+## Rules
+- Do NOT modify code yourself — only run validation commands
+- If checks fail, message the worker with specific errors and file locations
+- If all checks pass, confirm to team lead: "E{n}-T{n} validated"
+- Track which tickets have been validated vs pending validation
+```
+
+---
+
+## Error Handling
+
+### Worker Failure Recovery
+```
+If a worker fails or times out:
+1. Check the ticket's current state (is it active? partially done?)
+2. Call reset_work_session({ ticketId }) to reset the session
+3. Spawn a new worker with the same ticket context
+4. Include failure context: "Previous attempt failed: {reason}. Pick up from: {lastProgress}"
+```
+
+### Blocker Escalation
+```
+If a ticket is blocked:
+1. Check if the blocker is a dependency (another ticket not done)
+   → Wait for dependency to complete (auto-unblocks)
+2. Check if the blocker is external (missing API, unclear requirement)
+   → Escalate to user with clear description of what's needed
+3. Based on agentTeams.escalationPolicy:
+   - "pause": Pause the team and wait
+   - "skip": Skip the blocked ticket, move to next
+   - "ask": Ask the user for guidance (default)
+```
+
+### Partial Completion
+```
+If a specification can't be fully completed:
+1. Complete as many tickets as possible
+2. Document what was completed and what remains
+3. Call report_completion with partial metrics
+4. Report to user with clear next steps
+```
+
+---
+
+## Monorepo Rules
+
+When `.specforge.json` has monorepo configuration:
+
+```
+1. Workspace Isolation:
+   - Workers targeting DIFFERENT workspaces can run in parallel safely
+   - Workers targeting the SAME workspace should be sequenced to avoid conflicts
+   - Include workspace path in each worker's prompt
+
+2. Worker Scoping:
+   - "You are working in {workspace.path}. Only modify files within this workspace
+     unless the ticket explicitly requires cross-workspace changes."
+   - Use get_workspace_files({ workspacePath: "apps/api" }) for workspace-specific metadata
+
+3. Cross-Workspace Dependencies:
+   - If a ticket in workspace A depends on a ticket in workspace B:
+     → Workspace B ticket must complete first
+     → The dependency graph handles this automatically
+   - Shared packages (packages/*) may need special sequencing
+
+4. Build Order:
+   - Respect the monorepo tool's build graph (turborepo, nx, etc.)
+   - After completing a shared package ticket, dependents may need rebuilding
+```
+
+---
+
+## MCP Tool Quick Reference
+
+### Lead Agent Tools
+| Tool | Purpose |
+|------|---------|
+| `get_specification` | Load spec with epics, status, patterns |
+| `get_implementation_plan` | Generate team-worker mapping |
+| `get_epic_dependency_graph` | Cross-epic dependency phases |
+| `get_next_actionable_tickets` | Find ready tickets |
+| `get_blocked_tickets` | Identify blockers |
+| `get_critical_path` | Longest dependency chain |
+| `get_report` | Implementation progress report |
+| `report_completion` | Mark epic/spec as complete |
+
+### Worker Agent Tools
+| Tool | Purpose |
+|------|---------|
+| `start_work_session` | Transition ticket ready → active |
+| `get_implementation_context` | Full ticket context with inheritance |
+| `get_workspace_files` | Workspace metadata (local only) |
+| `get_patterns` | Code patterns with inheritance |
+| `blueprint` (get_for_ticket) | Load linked blueprints |
+| `action_work_session` | Update checklist, files, and blockers during active session |
+| `complete_work_session` | Mark ticket done (requires all AC/steps completed first) |
+| `get_next_actionable_tickets` | Claim next ready ticket |
+
+### Status Values
+- **Ticket:** `pending` | `ready` | `active` | `done`
+- **Epic:** `todo` | `in_progress` | `completed`
+- **Specification:** `draft` | `planning` | `ready` | `in_progress` | `completed`
+
+Note: There is no `in_review` status. Tickets go directly from `active` to `done`.