specsmd 0.0.0-dev.6 → 0.0.0-dev.61

package/flows/fire/agents/orchestrator/skills/project-init/templates/testing-standards.md.hbs

@@ -0,0 +1,94 @@
+# Testing Standards
+
+## Overview
+
+{{overview}}
+
+## Testing Framework
+
+**Framework**: {{framework}}
+**Runner**: {{runner}}
+
+## Test Types
+
+| Type | Tool | Location | When to Use |
+|------|------|----------|-------------|
+{{#each test_types}}
+| {{this.type}} | {{this.tool}} | `{{this.location}}` | {{this.when}} |
+{{/each}}
+
+## Coverage Requirements
+
+**Target**: {{coverage_target}}%
+**Enforcement**: {{coverage_enforcement}}
+
+**Critical paths that MUST have coverage:**
+{{#each critical_paths}}
+- {{this}}
+{{/each}}
+
+## Test Naming
+
+**Pattern**: `{{naming_pattern}}`
+
+**Examples**:
+{{#each naming_examples}}
+- `{{this.name}}` — {{this.description}}
+{{/each}}
+
+## Test Structure
+
+```{{language}}
+{{test_structure}}
+```
+
+## Mock Strategy
+
+**Approach**: {{mock_approach}}
+
+**Guidelines**:
+{{#each mock_guidelines}}
+- {{this}}
+{{/each}}
+
+## Test Data
+
+**Strategy**: {{test_data_strategy}}
+
+**Guidelines**:
+{{#each test_data_guidelines}}
+- {{this}}
+{{/each}}
+
+## Running Tests
+
+```bash
+# Run all tests
+{{run_all_command}}
+
+# Run with coverage
+{{run_coverage_command}}
+
+# Run specific test file
+{{run_single_command}}
+
+# Run in watch mode
+{{run_watch_command}}
+```
+
+## CI/CD Integration
+
+{{#if ci_enabled}}
+**Pipeline**: {{ci_pipeline}}
+**Trigger**: {{ci_trigger}}
+
+**Required gates**:
+{{#each ci_gates}}
+- {{this}}
+{{/each}}
+{{else}}
+CI/CD integration not configured.
+{{/if}}
+
+---
+*Generated by FIRE project-init*

package/flows/fire/agents/orchestrator/skills/route/SKILL.md

@@ -0,0 +1,123 @@
+# Skill: Route
+
+Analyze project state and route user to the appropriate agent.
+
+---
+
+## Trigger
+
+- User runs `/fire` on initialized project
+- After any agent completes its task
+
+---
+
+## Workflow
+
+```xml
+<skill name="route">
+
+  <step n="1" title="Discover and Read State">
+    <action>Read .specs-fire/state.yaml</action>
+    <action>Scan .specs-fire/intents/ for briefs not in state</action>
+    <action>Scan .specs-fire/intents/*/work-items/ for items not in state</action>
+    <action>Reconcile: add discovered items to state as pending</action>
+    <action>Parse current project state</action>
+  </step>
+
+  <step n="2" title="Check Active Run">
+    <check if="active_run exists and status == in_progress">
+      <output>
+        Resuming active run: {active_run.id}
+        Scope: {active_run.scope}
+        Current item: {active_run.current_item}
+        Progress: {completed_count}/{total_count} items
+      </output>
+      <route-to>builder-agent (run-execute)</route-to>
+      <stop/>
+    </check>
+  </step>
+
+  <step n="3" title="Check Pending Work Items">
+    <action>Find work items with status == pending across all intents</action>
+    <check if="pending work items exist">
+      <output>
+        **{pending_count} pending work items** found across {intent_count} intent(s).
+
+        Plan run scope and start execution? [Y/n]
+      </output>
+      <check if="response == y">
+        <route-to>builder-agent (run-plan)</route-to>
+      </check>
+      <stop/>
+    </check>
+  </step>
+
+  <step n="4" title="Check Active Intent">
+    <action>Find intents with status == in_progress</action>
+    <check if="active intent has no work items">
+      <output>
+        Intent "{intent.title}" needs decomposition.
+        Routing to Planner to create work items.
+      </output>
+      <route-to>planner-agent (work-item-decompose)</route-to>
+      <stop/>
+    </check>
+    <check if="all work items completed">
+      <action>Mark intent as completed</action>
+      <output>
+        Intent "{intent.title}" completed!
+
+        Work items delivered:
+        {list completed work items}
+
+        Ready for next intent? [Y/n]
+      </output>
+    </check>
+  </step>
+
+  <step n="5" title="No Active Work">
+    <output>
+      No active work. Ready for a new intent.
+
+      What do you want to build?
+    </output>
+    <route-to>planner-agent (intent-capture)</route-to>
+  </step>
+
+</skill>
+```
+
+---
+
+## Routing Decision Tree
+
+```
+state.yaml + file system scan
+    │
+    ├── active_run? ──────────────> Builder (run-execute, resume)
+    │
+    ├── pending work items? ──────> Builder (run-plan, then execute)
+    │
+    ├── intent without work items? > Planner (work-item-decompose)
+    │
+    └── no active intents ────────> Planner (intent-capture)
+```
+
+---
+
+## Context Passed to Agents
+
+**To Planner:**
+```yaml
+context:
+  action: intent-capture | work-item-decompose
+  intent_id: {if decomposing}
+```
+
+**To Builder:**
+```yaml
+context:
+  action: run-plan | run-execute | resume
+  pending_items: [{list of pending work items}]  # for run-plan
+  run_id: {if resuming}
+```

package/flows/fire/agents/orchestrator/skills/status/SKILL.md

@@ -0,0 +1,99 @@
+# Skill: Status
+
+Display current FIRE project status.
+
+---
+
+## Trigger
+
+- User runs `/fire status`
+- User asks "what's the status?"
+
+---
+
+## Workflow
+
+```xml
+<skill name="status">
+
+  <step n="1" title="Read State">
+    <action>Read .specs-fire/state.yaml</action>
+  </step>
+
+  <step n="2" title="Display Status">
+    <output>
+      # FIRE Status
+
+      **Project**: {project.name}
+      **Workspace**: {workspace.type} / {workspace.structure}
+      **Autonomy**: {workspace.autonomy_bias}
+
+      ## Intents
+
+      {for each intent}
+      ### {intent.title} [{intent.status}]
+
+      | Work Item | Status | Complexity | Mode |
+      |-----------|--------|------------|------|
+      {for each work_item}
+      | {title} | {status} | {complexity} | {mode} |
+      {/for}
+
+      {/for}
+
+      ## Active Run
+
+      {if active_run}
+      - **Run**: {active_run.id}
+      - **Work Item**: {active_run.work_item}
+      - **Started**: {active_run.started}
+      - **Mode**: {active_run.mode}
+      {else}
+      No active run.
+      {/if}
+
+      ## Quick Stats
+
+      - Intents: {total_intents} ({completed_intents} completed)
+      - Work Items: {total_work_items} ({completed_work_items} completed)
+      - Runs: {total_runs}
+    </output>
+  </step>
+
+</skill>
+```
+
+---
+
+## Example Output
+
+```
+# FIRE Status
+
+**Project**: my-saas-app
+**Workspace**: brownfield / monolith
+**Autonomy**: balanced
+
+## Intents
+
+### User Authentication [in_progress]
+
+| Work Item | Status | Complexity | Mode |
+|-----------|--------|------------|------|
+| login-endpoint | completed | medium | confirm |
+| session-management | in_progress | medium | confirm |
+| password-reset | pending | high | validate |
+
+## Active Run
+
+- **Run**: run-002
+- **Work Item**: session-management
+- **Started**: 2026-01-19T10:30:00Z
+- **Mode**: confirm
+
+## Quick Stats
+
+- Intents: 1 (0 completed)
+- Work Items: 3 (1 completed)
+- Runs: 2
+```

package/flows/fire/agents/planner/agent.md

@@ -0,0 +1,122 @@
+# FIRE Planner Agent
+
+You are the **Planner Agent** for FIRE (Fast Intent-Run Engineering).
+
+---
+
+## Persona
+
+- **Role**: Intent Architect & Work Item Designer
+- **Communication**: Conversational during capture, structured during output.
+- **Principle**: Capture the "what" and "why" through dialogue. Never assume requirements.
+
+---
+
+## On Activation
+
+When routed from Orchestrator or user invokes this agent:
+
+1. Read `.specs-fire/state.yaml` for current state
+2. Determine mode:
+   - **No active intent** → Execute `intent-capture` skill
+   - **Intent without work items** → Execute `work-item-decompose` skill
+   - **High-complexity work item** → Execute `design-doc-generate` skill
+
+---
+
+## Skills
+
+| Command | Skill | Description |
+|---------|-------|-------------|
+| `capture`, `intent` | `skills/intent-capture/SKILL.md` | Capture new intent through conversation |
+| `decompose`, `plan` | `skills/work-item-decompose/SKILL.md` | Break intent into work items |
+| `design` | `skills/design-doc-generate/SKILL.md` | Generate design doc (Validate mode) |
+
+---
+
+## Intent Capture Flow
+
+```text
+[1] Ask: "What do you want to build?"
+[2] Elicit context through follow-up questions:
+    - Who is this for?
+    - What problem does it solve?
+    - Any constraints or preferences?
+[3] Summarize understanding
+[4] Generate intent brief
+[5] Save to .specs-fire/intents/{id}/brief.md
+[6] Update state.yaml
+```
+
+**CRITICAL**: Use HIGH degrees of freedom. Explore openly, don't constrain prematurely.
+
+---
+
+## Work Item Decomposition Flow
+
+```text
+[1] Read intent brief
+[2] Identify discrete deliverables
+[3] For each work item:
+    - Assign complexity (low/medium/high)
+    - Suggest execution mode (autopilot/confirm/validate)
+    - Define acceptance criteria
+[4] Validate dependencies
+[5] Save work items to .specs-fire/intents/{id}/work-items/
+[6] Update state.yaml with work items list
+```
+
+**CRITICAL**: Use MEDIUM degrees of freedom. Follow patterns but adapt to context.
+
+---
+
+## Design Document Flow (Validate Mode Only)
+
+For high-complexity work items requiring Validate mode:
+
+```text
+[1] Analyze work item requirements
+[2] Identify key decisions needed
+[3] Draft:
+    - Key decisions table (decision, choice, rationale)
+    - Domain model (if applicable)
+    - Technical approach (component diagram, API contracts)
+    - Risks and mitigations
+    - Implementation checklist
+[4] Present to user for review (Checkpoint 1)
+[5] Incorporate feedback
+[6] Save design doc
+```
+
+---
+
+## Output Artifacts
+
+| Artifact | Location | Template |
+|----------|----------|----------|
+| Intent Brief | `.specs-fire/intents/{id}/brief.md` | `templates/intents/brief.md.hbs` |
+| Work Item | `.specs-fire/intents/{id}/work-items/{id}.md` | `templates/intents/work-item.md.hbs` |
+| Design Doc | `.specs-fire/intents/{id}/work-items/{id}-design.md` | `templates/intents/design-doc.md.hbs` |
+
+---
+
+## Handoff to Builder
+
+When planning is complete:
+
+```
+Planning complete for intent "{intent-title}".
+
+Work items ready for execution:
+1. {work-item-1} (low, autopilot)
+2. {work-item-2} (medium, confirm)
+3. {work-item-3} (high, validate)
+
+Route to Builder Agent to begin execution? [Y/n]
+```
+
+---
+
+## Begin
+
+Read `.specs-fire/state.yaml` and determine which planning skill to execute based on current state.

package/flows/fire/agents/planner/skills/design-doc-generate/SKILL.md

@@ -0,0 +1,213 @@
+# Skill: Design Doc Generate
+
+Generate design documents for Validate mode work items (Checkpoint 1).
+
+---
+
+## Trigger
+
+- Work item has complexity: high
+- Work item has mode: validate
+- Design review required before implementation
+
+---
+
+## Degrees of Freedom
+
+**LOW** — Follow the design doc structure precisely. Decisions must have rationale.
+
+---
+
+## Workflow
+
+```xml
+<skill name="design-doc-generate">
+
+  <mandate>
+    Design doc MUST be approved before implementation.
+    Document DECISIONS with RATIONALE, not just choices.
+    Keep concise - enough detail to implement, no more.
+    Include risks upfront - don't hide complexity.
+  </mandate>
+
+  <step n="1" title="Analyze Work Item">
+    <action>Read work item from .specs-fire/intents/{intent-id}/work-items/{id}.md</action>
+    <action>Identify key design decisions needed</action>
+    <action>Assess domain modeling needs</action>
+    <action>Identify integration points</action>
+  </step>
+
+  <step n="2" title="Gather Context">
+    <action>Review project standards (.specs-fire/standards/)</action>
+    <action>Check existing codebase patterns</action>
+    <action>Identify similar implementations to reference</action>
+  </step>
+
+  <step n="3" title="Draft Key Decisions">
+    <action>For each decision point:</action>
+    <substep>Identify options considered</substep>
+    <substep>Evaluate trade-offs</substep>
+    <substep>Select recommended choice</substep>
+    <substep>Document rationale</substep>
+
+    <output-format>
+      | Decision | Choice | Rationale |
+      |----------|--------|-----------|
+      | ... | ... | ... |
+    </output-format>
+  </step>
+
+  <step n="4" title="Define Domain Model" if="has_domain_complexity">
+    <action>Identify entities (things with identity)</action>
+    <action>Identify value objects (immutable values)</action>
+    <action>Identify domain events (if event-driven)</action>
+    <action>Map relationships</action>
+  </step>
+
+  <step n="5" title="Design Technical Approach">
+    <action>Create component diagram (ASCII)</action>
+    <action>Define API contracts (if applicable)</action>
+    <action>Specify database changes (if applicable)</action>
+    <action>Document data flow</action>
+  </step>
+
+  <step n="6" title="Identify Risks">
+    <action>List potential risks</action>
+    <action>Assess impact (high/medium/low)</action>
+    <action>Propose mitigations</action>
+
+    <output-format>
+      | Risk | Impact | Mitigation |
+      |------|--------|------------|
+      | ... | ... | ... |
+    </output-format>
+  </step>
+
+  <step n="7" title="Create Implementation Checklist">
+    <action>Break down into implementation steps</action>
+    <action>Order by dependency</action>
+    <action>Keep granular but not excessive</action>
+  </step>
+
+  <step n="8" title="Present Design Doc">
+    <checkpoint message="Design document ready for review">
+      <output>
+        # Design: {work-item-title}
+
+        ## Summary
+        {brief description}
+
+        ## Key Decisions
+        {decisions table}
+
+        ## Technical Approach
+        {component diagram, API contracts}
+
+        ## Risks
+        {risks table}
+
+        ## Implementation Checklist
+        {ordered steps}
+
+        ---
+        This is Checkpoint 1 of Validate mode.
+
+        Approve design? [Y/n/edit]
+      </output>
+    </checkpoint>
+  </step>
+
+  <step n="9" title="Handle Response">
+    <check if="response == y">
+      <action>Generate design doc using template: templates/design.md.hbs</action>
+      <action>Save to: .specs-fire/intents/{intent-id}/work-items/{id}-design.md</action>
+      <action>Mark checkpoint 1 as passed</action>
+      <output>
+        Design approved. Ready for implementation planning.
+
+        Route to Builder for Checkpoint 2 (implementation plan)? [Y/n]
+      </output>
+    </check>
+    <check if="response == edit">
+      <ask>What changes are needed?</ask>
+      <action>Incorporate feedback</action>
+      <goto step="8"/>
+    </check>
+    <check if="response == n">
+      <output>Design rejected. What concerns need to be addressed?</output>
+      <action>Gather feedback, revise approach</action>
+      <goto step="3"/>
+    </check>
+  </step>
+
+</skill>
+```
+
+---
+
+## Output
+
+**Design Doc** (`.specs-fire/intents/{intent-id}/work-items/{id}-design.md`):
+
+```markdown
+---
+work_item: {work-item-id}
+intent: {intent-id}
+created: {timestamp}
+mode: validate
+checkpoint_1: approved
+---
+
+# Design: {title}
+
+## Summary
+
+{Brief description of what will be built and why}
+
+## Key Decisions
+
+| Decision | Choice | Rationale |
+|----------|--------|-----------|
+| {decision} | {choice} | {why} |
+
+## Domain Model
+
+### Entities
+- **{Name}**: {description}
+
+### Value Objects
+- **{Name}**: {description}
+
+## Technical Approach
+
+### Component Diagram
+
+```
+[ASCII diagram]
+```
+
+### API Endpoints
+
+- `POST /api/...` - {description}
+
+### Database Changes
+
+```sql
+CREATE TABLE ...
+```
+
+## Risks & Mitigations
+
+| Risk | Impact | Mitigation |
+|------|--------|------------|
+| {risk} | {impact} | {mitigation} |
+
+## Implementation Checklist
+
+- [ ] {step 1}
+- [ ] {step 2}
+- [ ] {step 3}
+
+---
+*Checkpoint 1 approved: {timestamp}*
+```