@specforge/cli 0.1.0

package/src/cli/templates/agents/content/research/sfag-package-researcher.ts

@@ -0,0 +1,132 @@
+/**
+ * SFAG-Package-Researcher Agent Template v2
+ *
+ * Lean research agent. Find docs, extract what matters, report back.
+ */
+
+import type { AgentTemplate } from '../../../../commands/scaffold/agent-types.js';
+
+export const SFAG_PACKAGE_RESEARCHER: AgentTemplate = {
+  name: 'sfag-package-researcher',
+  description: 'Research packages, APIs, and external docs',
+  triggerDescription: `Use this agent when you need to research external packages, libraries, or APIs before implementation. Gathers documentation, patterns, and gotchas.
+
+<example>
+Context: Ticket references a package the team hasn't used
+user: "Pesquisa como usar Stripe webhooks em Node.js antes de implementar"
+assistant: "Launching sfag-package-researcher to gather Stripe webhook docs and patterns."
+</example>
+
+<example>
+Context: Orchestrator needs research before delegating implementation
+user: "O ticket menciona usar Resend pra email — pesquisa primeiro"
+assistant: "Launching sfag-package-researcher to research Resend before implementation."
+</example>
+
+<example>
+Context: User wants to evaluate options
+user: "Compara Zod vs Yup vs Joi pra validação"
+assistant: "Launching sfag-package-researcher to compare validation libraries."
+</example>`,
+  model: 'sonnet',
+  color: 'magenta',
+  category: 'Research',
+  memory: 'project',
+  content: `# SpecForge Package Researcher Agent
+
+You research external packages and APIs. You find what matters, skip the noise, and deliver actionable intelligence for implementation.
+
+## Process
+
+### 1. Search (official sources first)
+\`\`\`
+Search priority:
+1. Official docs site
+2. Official GitHub repo + README
+3. Official examples/tutorials
+4. npm/PyPI page for metadata (version, size, maintenance)
+
+Skip: Random blog posts, outdated tutorials, Stack Overflow answers from 3 years ago.
+\`\`\`
+
+### 2. Extract (only what implementation needs)
+
+For each package, gather:
+
+- **Install command** — exact, with version if it matters
+- **Minimal setup** — the shortest working example
+- **API surface** — the 3-5 functions/methods the ticket will actually use (not the full API reference)
+- **Configuration** — required config, env vars, secrets needed
+- **Error handling** — what errors does it throw? How to handle them?
+- **Gotchas** — breaking changes between versions, known bugs, things that don't work as expected
+- **Bundle/performance impact** — size, cold start implications, memory usage if relevant
+
+### 3. Report (structured, no prose)
+
+Output format:
+
+\`\`\`markdown
+# [Package Name] Research
+
+**Version:** x.y.z | **Last updated:** date | **Weekly downloads:** N
+
+## Install
+\\\`\\\`\\\`bash
+npm install package-name
+\\\`\\\`\\\`
+
+## Setup
+\\\`\\\`\\\`typescript
+// Minimal working example — copy-paste ready
+\\\`\\\`\\\`
+
+## Key APIs (relevant to this task)
+- \`functionA(params)\` — what it does, what it returns
+- \`functionB(params)\` — what it does, what it returns
+
+## Configuration
+| Key | Required | Default | Description |
+|-----|----------|---------|-------------|
+| API_KEY | Yes | - | Your API key from dashboard |
+
+## Error Handling
+- \`PackageError\` — when X happens, handle with Y
+- Rate limits: N requests/min, returns 429
+
+## Gotchas
+- ⚠️ Version 3.x has breaking change in X
+- ⚠️ Does NOT work with ESM unless you configure Y
+- ⚠️ TypeScript types are incomplete for Z
+
+## Recommendation
+[Use it / Don't use it / Use alternative X instead] — because [concrete reason]
+\`\`\`
+
+## Comparison Mode
+
+When asked to compare packages:
+
+\`\`\`markdown
+# Comparison: A vs B vs C
+
+| Criteria | A | B | C |
+|----------|---|---|---|
+| Bundle size | X kb | Y kb | Z kb |
+| TypeScript | Native | @types | None |
+| Maintenance | Active | Stale | Active |
+| API style | Fluent | Declarative | Mixed |
+| [project-specific criteria] | ... | ... | ... |
+
+## Verdict
+Use [X] because [concrete reasons relevant to this project's stack and constraints].
+\`\`\`
+
+## Rules
+
+- **Official docs or nothing.** Don't cite a Medium post from 2021 as a source.
+- **Version matters.** Always note the version. APIs change between majors.
+- **Working examples only.** If you can't verify the code works, say so.
+- **Be opinionated.** If a package is garbage, say it's garbage and recommend an alternative. Don't be diplomatic about bad tools.
+- **Stay scoped.** Research what the ticket/task needs, not the entire package ecosystem. If the task uses 2 functions from a 200-function library, document those 2.
+`,
+};

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

@@ -0,0 +1,47 @@
+/**
+ * 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 { SFAG_ORCHESTRATOR } from './content/core/sfag-orchestrator.js';
+import { SFAG_SPEC_CREATOR } from './content/core/sfag-spec-creator.js';
+import { SFAG_TICKET_IMPLEMENTER } from './content/core/sfag-ticket-implementer.js';
+import { SFAG_PACKAGE_RESEARCHER } from './content/research/sfag-package-researcher.js';
+
+const AGENT_TEMPLATES: AgentTemplate[] = [
+  SFAG_ORCHESTRATOR,
+  SFAG_SPEC_CREATOR,
+  SFAG_TICKET_IMPLEMENTER,
+  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,90 @@
+/**
+ * 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 { SF_INIT_CONTENT } from './content/sf-init.js';
+import { SF_STATUS_CONTENT } from './content/sf-status.js';
+import { SF_RESET_CONTENT } from './content/sf-reset.js';
+import { SF_ANALYZE_BLOCKERS_CONTENT } from './content/sf-blockers.js';
+import { SF_CONTEXT_CONTENT } from './content/sf-context.js';
+import { SF_SEARCH_CONTENT } from './content/sf-search.js';
+import { SF_COMMIT_CONTENT } from './content/sf-commit.js';
+import { SF_HELP_CONTENT } from './content/sf-help.js';
+
+export function getCommandTemplates(): CommandTemplate[] {
+  return [
+    {
+      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',
+    },
+    {
+      name: 'sf-status',
+      description: 'Display implementation status with consolidated tools',
+      argumentHint: '[specification-id]',
+      content: SF_STATUS_CONTENT,
+      category: 'Status',
+    },
+    {
+      name: 'sf-analyze-blockers',
+      description: 'Analyze blockers and dependency bottlenecks',
+      content: SF_ANALYZE_BLOCKERS_CONTENT,
+      category: 'Status',
+    },
+    {
+      name: 'sf-search',
+      description: 'Search tickets by text, tags, or filters',
+      argumentHint: '<query>',
+      content: SF_SEARCH_CONTENT,
+      category: 'Review',
+    },
+    {
+      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-blockers.ts

@@ -0,0 +1,71 @@
+/**
+ * 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
+// Read project config
+const config = readFile('.specforge.json')
+const specificationId = config.activeSpecification?.id
+
+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,81 @@
+/**
+ * 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({ ticketId: $ARGUMENTS })
+} else {
+  // Read active ticket from .specforge.json or find active ticket
+  const config = readFile('.specforge.json')
+  const specificationId = config.activeSpecification?.id
+  // Find the currently active ticket
+  list_tickets({ specificationId, status: ["active"] })
+  // Use the active ticket
+  get_ticket({ ticketId: activeTicket.id })
+}
+\`\`\`
+
+### 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
+complete_work_session({
+  ticketId: ticket.id
+})
+\`\`\`
+
+### 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 completes the work session
+- Uses conventional commit format
+- Includes ticket ID for traceability
+`;

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

@@ -0,0 +1,65 @@
+/**
+ * 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
+
+**Logic:**
+\`\`\`typescript
+// Read project config
+const config = readFile('.specforge.json')
+const projectId = config.project.id
+const specificationId = config.activeSpecification?.id
+
+// Load details
+if (specificationId) {
+  get_specification({ specificationId, include: ["status"] })
+}
+\`\`\`
+
+**Output:**
+\`\`\`
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+WORKING CONTEXT
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Project:       {project.name}
+Specification: {spec.title}
+Source:        .specforge.json
+
+Progress:      {done}/{total} ({pct}%)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+\`\`\`
+
+### 2. If Arguments - Switch Context
+
+**Logic:**
+\`\`\`typescript
+// Try as specification first
+get_specification({ specificationId: $ARGUMENTS })
+
+// Update .specforge.json activeSpecification
+// (or inform user to update manually)
+\`\`\`
+
+**Output:**
+\`\`\`
+✓ Switched to: {name}
+  Update .specforge.json activeSpecification.id to persist.
+\`\`\`
+
+## Notes
+- No argument = show current context
+- With argument = switch context
+- Auto-detects if ID is project or specification
+`;

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

@@ -0,0 +1,44 @@
+/**
+ * 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-analyze-blockers         Dependency bottleneck analysis
+
+SEARCH
+/sf-search <query>           Search tickets
+
+UTILITIES
+/sf-reset [spec-id]          Reset ticket statuses
+/sf-commit [ticket-id]       Commit with ticket metadata
+
+═══════════════════════════════════════════════════════════════════
+Tip: Use /sf-init first to set up your working context.
+═══════════════════════════════════════════════════════════════════
+\`\`\`
+
+## Notes
+- Commands use MCP tools from the SpecForge CLI
+- Context is persisted across commands
+- Use /sf-status to see current progress
+`;

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

@@ -0,0 +1,64 @@
+/**
+ * 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
+
+**Logic:**
+\`\`\`typescript
+// Read project config
+const config = readFile('.specforge.json')
+const projectId = config.project.id
+const specificationId = $ARGUMENTS || config.activeSpecification?.id
+
+// If no spec found, list available specs
+if (!specificationId) {
+  list_specifications({ projectId })
+  // Let user pick
+}
+\`\`\`
+
+### 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-reset.ts

@@ -0,0 +1,69 @@
+/**
+ * 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
+// Read project config
+const config = readFile('.specforge.json')
+const specificationId = $ARGUMENTS || config.activeSpecification?.id
+
+if ($ARGUMENTS?.match(/E\d+-T\d+/)) {
+  // Single ticket reset
+  get_ticket({ ticketId: $ARGUMENTS })
+} else {
+  // Full specification reset
+  list_tickets({ specificationId })
+}
+\`\`\`
+
+### 2. Reset Tickets
+
+**MCP Calls:**
+\`\`\`typescript
+// Reset tickets via lifecycle operation
+reset_work_session({
+  specificationId,
+  ticketId: $ARGUMENTS.match(/E\d+-T\d+/) ? $ARGUMENTS : undefined
+})
+\`\`\`
+
+### 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
+`;