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

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

@@ -0,0 +1,76 @@
+---
+work_item: {{work_item_id}}
+intent: {{intent_id}}
+created: {{created}}
+mode: validate
+checkpoint_1: {{checkpoint_status}}
+---
+
+# Design: {{title}}
+
+## Summary
+
+{{summary}}
+
+## Key Decisions
+
+| Decision | Choice | Rationale |
+|----------|--------|-----------|
+{{#each decisions}}
+| {{this.decision}} | {{this.choice}} | {{this.rationale}} |
+{{/each}}
+
+{{#if domain_model}}
+## Domain Model
+
+### Entities
+{{#each domain_model.entities}}
+- **{{this.name}}**: {{this.description}}
+{{/each}}
+
+### Value Objects
+{{#each domain_model.value_objects}}
+- **{{this.name}}**: {{this.description}}
+{{/each}}
+{{/if}}
+
+## Technical Approach
+
+### Component Diagram
+
+```
+{{component_diagram}}
+```
+
+{{#if api_endpoints}}
+### API Endpoints
+
+{{#each api_endpoints}}
+- `{{this.method}} {{this.path}}` - {{this.description}}
+{{/each}}
+{{/if}}
+
+{{#if database_changes}}
+### Database Changes
+
+```sql
+{{database_changes}}
+```
+{{/if}}
+
+## Risks & Mitigations
+
+| Risk | Impact | Mitigation |
+|------|--------|------------|
+{{#each risks}}
+| {{this.risk}} | {{this.impact}} | {{this.mitigation}} |
+{{/each}}
+
+## Implementation Checklist
+
+{{#each checklist}}
+- [ ] {{this}}
+{{/each}}
+
+---
+*Checkpoint 1 approved: {{approved_at}}*

package/flows/fire/agents/planner/skills/intent-capture/SKILL.md

@@ -0,0 +1,155 @@
+# Skill: Intent Capture
+
+Capture user intent through guided conversation.
+
+---
+
+## Trigger
+
+- No active intent exists
+- User wants to start something new
+
+---
+
+## Degrees of Freedom
+
+**HIGH** — This is a creative, exploratory phase. Ask open-ended questions. Don't constrain prematurely.
+
+---
+
+## Workflow
+
+```xml
+<skill name="intent-capture">
+
+  <mandate>
+    NEVER assume requirements. ALWAYS ask clarifying questions.
+    Capture the "what" and "why" - leave the "how" for decomposition.
+  </mandate>
+
+  <step n="1" title="Initial Question">
+    <ask>What do you want to build?</ask>
+    <listen>Let user describe freely. Don't interrupt.</listen>
+  </step>
+
+  <step n="2" title="Elicit Context">
+    <action>Based on response, ask follow-up questions:</action>
+
+    <question if="unclear who benefits">
+      Who is this for? Who will use this feature?
+    </question>
+
+    <question if="unclear problem">
+      What problem does this solve? What's painful today?
+    </question>
+
+    <question if="unclear scope">
+      What's the minimum that would be valuable? What can wait?
+    </question>
+
+    <question if="unclear constraints">
+      Any technical constraints? Existing systems to integrate with?
+    </question>
+
+    <question if="unclear success">
+      How will you know this is working? What does success look like?
+    </question>
+  </step>
+
+  <step n="3" title="Summarize Understanding">
+    <output>
+      Let me make sure I understand:
+
+      **Goal**: {summarized goal}
+
+      **Users**: {who benefits}
+
+      **Problem**: {what pain this solves}
+
+      **Success Criteria**:
+      - {criterion 1}
+      - {criterion 2}
+      - {criterion 3}
+
+      **Constraints**:
+      - {constraint 1}
+      - {constraint 2}
+
+      Is this accurate? [Y/n/edit]
+    </output>
+    <check if="response == n or edit">
+      <action>Ask specific clarifying questions</action>
+      <goto step="3"/>
+    </check>
+  </step>
+
+  <step n="4" title="Generate Intent Brief">
+    <action>Create intent ID from title (kebab-case)</action>
+    <action>Generate intent brief using template: templates/brief.md.hbs</action>
+    <action>Create directory: .specs-fire/intents/{intent-id}/</action>
+    <action>Save: .specs-fire/intents/{intent-id}/brief.md</action>
+  </step>
+
+  <step n="5" title="Update State">
+    <action>Add intent to state.yaml</action>
+    <action>Set intent status to "in_progress"</action>
+  </step>
+
+  <step n="6" title="Transition">
+    <output>
+      **Intent captured**: "{intent-title}"
+
+      Saved to: .specs-fire/intents/{intent-id}/brief.md
+
+      ---
+
+      Ready to break this into work items? [Y/n]
+    </output>
+    <check if="response == y">
+      <invoke-skill>work-item-decompose</invoke-skill>
+    </check>
+  </step>
+
+</skill>
+```
+
+---
+
+## Output
+
+**Intent Brief** (`.specs-fire/intents/{id}/brief.md`):
+
+```markdown
+---
+id: {intent-id}
+title: {title}
+status: in_progress
+created: {timestamp}
+---
+
+# Intent: {title}
+
+## Goal
+
+{What we're building and why}
+
+## Users
+
+{Who benefits from this}
+
+## Problem
+
+{What pain this solves}
+
+## Success Criteria
+
+- {How we know it's working}
+
+## Constraints
+
+- {Any limitations or requirements}
+
+## Notes
+
+{Additional context}
+```

package/flows/fire/agents/planner/skills/intent-capture/templates/brief.md.hbs

@@ -0,0 +1,40 @@
+---
+id: {{id}}
+title: {{title}}
+status: {{status}}
+created: {{created}}
+---
+
+# Intent: {{title}}
+
+## Goal
+
+{{goal}}
+
+## Users
+
+{{users}}
+
+## Problem
+
+{{problem}}
+
+## Success Criteria
+
+{{#each success_criteria}}
+- {{this}}
+{{/each}}
+
+## Constraints
+
+{{#each constraints}}
+- {{this}}
+{{/each}}
+
+## Notes
+
+{{#if notes}}
+{{notes}}
+{{else}}
+(none)
+{{/if}}

package/flows/fire/agents/planner/skills/work-item-decompose/SKILL.md

@@ -0,0 +1,194 @@
+# Skill: Work Item Decompose
+
+Break an intent into discrete, executable work items.
+
+---
+
+## Trigger
+
+- Intent exists without work items
+- User wants to plan execution
+
+---
+
+## Degrees of Freedom
+
+**MEDIUM** — Follow decomposition patterns but adapt to the specific intent.
+
+---
+
+## Workflow
+
+```xml
+<skill name="work-item-decompose">
+
+  <mandate>
+    Each work item MUST be completable in a single run.
+    Each work item MUST have clear acceptance criteria.
+    Dependencies MUST be explicit and validated.
+  </mandate>
+
+  <step n="1" title="Load Intent">
+    <action>Read intent brief from .specs-fire/intents/{intent-id}/brief.md</action>
+    <action>Understand goal, users, success criteria</action>
+  </step>
+
+  <step n="2" title="Identify Deliverables">
+    <action>Break intent into discrete deliverables</action>
+    <action>Each deliverable should be independently valuable</action>
+
+    <guidelines>
+      - Prefer vertical slices over horizontal layers
+      - Start with foundation pieces (models, schemas)
+      - End with integration pieces (API, UI)
+      - Keep each item focused on ONE concern
+    </guidelines>
+  </step>
+
+  <step n="3" title="Assess Complexity">
+    <action>For each work item, assess RAW complexity:</action>
+
+    <complexity level="low">
+      - Single file or few files
+      - Well-understood pattern
+      - No external dependencies
+      - Examples: bug fix, config change, simple utility
+    </complexity>
+
+    <complexity level="medium">
+      - Multiple files
+      - Standard patterns with some decisions
+      - May touch existing code
+      - Examples: new endpoint, new component, feature addition
+    </complexity>
+
+    <complexity level="high">
+      - Architectural decisions required
+      - Security or data implications
+      - Core system changes
+      - Examples: auth system, payment flow, database migration
+    </complexity>
+  </step>
+
+  <step n="3b" title="Apply Autonomy Bias">
+    <action>Read workspace.autonomy_bias from state.yaml</action>
+    <action>Apply bias to determine final execution mode:</action>
+
+    <bias-table>
+      | Raw Complexity | autonomous | balanced | controlled |
+      |----------------|------------|----------|------------|
+      | low            | autopilot  | autopilot| confirm    |
+      | medium         | autopilot  | confirm  | validate   |
+      | high           | confirm    | validate | validate   |
+    </bias-table>
+
+    <note>
+      This allows user preference to shift thresholds:
+      - autonomous: trusts AI more, fewer checkpoints
+      - balanced: standard behavior (default)
+      - controlled: more human oversight
+    </note>
+  </step>
+
+  <step n="4" title="Define Acceptance Criteria">
+    <action>For each work item, define:</action>
+    <substep>What must be true when complete</substep>
+    <substep>How to verify it works</substep>
+    <substep>Any edge cases to handle</substep>
+  </step>
+
+  <step n="5" title="Validate Dependencies">
+    <action>Check for circular dependencies</action>
+    <action>Ensure dependencies exist or will be created first</action>
+    <action>Order work items by dependency</action>
+
+    <check if="circular dependency detected">
+      <output>
+        Warning: Circular dependency detected between {item-a} and {item-b}.
+        Suggest splitting into smaller items or reordering.
+      </output>
+    </check>
+  </step>
+
+  <step n="6" title="Present Plan">
+    <output>
+      ## Work Items for "{intent-title}"
+
+      **Total**: {count} work items
+      **Estimated**: {low} autopilot, {medium} confirm, {high} validate
+
+      **Work Item Details**:
+
+      {for each item}
+      {n}. **{title}** ({mode}) — {description}
+      {/for}
+
+      ---
+
+      Approve this plan? [Y/n/edit]
+    </output>
+  </step>
+
+  <step n="7" title="Save Work Items">
+    <check if="approved">
+      <action>Create .specs-fire/intents/{intent-id}/work-items/</action>
+      <action>For each work item, generate using template: templates/work-item.md.hbs</action>
+      <action>Save each to: .specs-fire/intents/{intent-id}/work-items/{work-item-id}.md</action>
+      <action>Update state.yaml with work items list</action>
+    </check>
+  </step>
+
+  <step n="8" title="Transition">
+    <output>
+      **{count} work items created** for "{intent-title}".
+
+      ---
+
+      Ready to plan execution scope? [Y/n]
+    </output>
+    <check if="response == y">
+      <route-to>builder-agent (run-plan)</route-to>
+    </check>
+  </step>
+
+</skill>
+```
+
+---
+
+## Output
+
+**Work Item** (`.specs-fire/intents/{intent-id}/work-items/{id}.md`):
+
+```markdown
+---
+id: {work-item-id}
+title: {title}
+intent: {intent-id}
+complexity: low | medium | high
+mode: autopilot | confirm | validate
+status: pending
+depends_on: [{dependency-ids}]
+created: {timestamp}
+---
+
+# Work Item: {title}
+
+## Description
+
+{What this work item delivers}
+
+## Acceptance Criteria
+
+- [ ] {criterion-1}
+- [ ] {criterion-2}
+- [ ] {criterion-3}
+
+## Technical Notes
+
+{Any implementation hints or constraints}
+
+## Dependencies
+
+{List of work items this depends on}
+```

package/flows/fire/agents/planner/skills/work-item-decompose/templates/work-item.md.hbs

@@ -0,0 +1,40 @@
+---
+id: {{id}}
+title: {{title}}
+intent: {{intent}}
+complexity: {{complexity}}
+mode: {{mode}}
+status: {{status}}
+depends_on: [{{#each depends_on}}{{this}}{{#unless @last}}, {{/unless}}{{/each}}]
+created: {{created}}
+---
+
+# Work Item: {{title}}
+
+## Description
+
+{{description}}
+
+## Acceptance Criteria
+
+{{#each acceptance_criteria}}
+- [ ] {{this}}
+{{/each}}
+
+## Technical Notes
+
+{{#if technical_notes}}
+{{technical_notes}}
+{{else}}
+(none)
+{{/if}}
+
+## Dependencies
+
+{{#if depends_on}}
+{{#each depends_on}}
+- {{this}}
+{{/each}}
+{{else}}
+(none)
+{{/if}}

package/flows/fire/commands/fire-builder.md

@@ -0,0 +1,56 @@
+---
+description: FIRE Builder Agent - executes work items and generates walkthroughs
+---
+
+# Activate FIRE Builder
+
+**Command**: `/specsmd-fire-builder`
+
+---
+
+## Activation
+
+You are now the **FIRE Builder Agent** for specsmd.
+
+**IMMEDIATELY** read and adopt the persona from:
+→ `.specsmd/fire/agents/builder/agent.md`
+
+---
+
+## Critical First Steps
+
+1. **Read Config**: `.specsmd/fire/fire-config.yaml`
+2. **Read State**: `.specs-fire/state.yaml`
+3. **Determine Mode**:
+   - Active run exists → Resume execution
+   - Pending work items → Start next work item
+   - No work items → Route back to Planner
+
+---
+
+## Your Skills
+
+- **Run Execute**: `.specsmd/fire/agents/builder/skills/run-execute/SKILL.md` → Execute work item
+- **Walkthrough Generate**: `.specsmd/fire/agents/builder/skills/walkthrough-generate/SKILL.md` → Generate walkthrough
+- **Run Status**: `.specsmd/fire/agents/builder/skills/run-status/SKILL.md` → Show run status
+
+---
+
+## Execution Modes
+
+- **Autopilot**: 0 checkpoints (low complexity)
+- **Confirm**: 1 checkpoint (medium complexity)
+- **Validate**: 2 checkpoints (high complexity)
+
+---
+
+## Routing Targets
+
+- **Back to Orchestrator**: `/specsmd-fire`
+- **To Planner**: `/specsmd-fire-planner`
+
+---
+
+## Begin
+
+Activate now. Read your agent definition and start building.

package/flows/fire/commands/fire-planner.md

@@ -0,0 +1,48 @@
+---
+description: FIRE Planner Agent - captures intents and decomposes into work items
+---
+
+# Activate FIRE Planner
+
+**Command**: `/specsmd-fire-planner`
+
+---
+
+## Activation
+
+You are now the **FIRE Planner Agent** for specsmd.
+
+**IMMEDIATELY** read and adopt the persona from:
+→ `.specsmd/fire/agents/planner/agent.md`
+
+---
+
+## Critical First Steps
+
+1. **Read Config**: `.specsmd/fire/fire-config.yaml`
+2. **Read State**: `.specs-fire/state.yaml`
+3. **Determine Mode**:
+   - No active intent → `intent-capture` skill
+   - Intent without work items → `work-item-decompose` skill
+   - High-complexity work item → `design-doc-generate` skill
+
+---
+
+## Your Skills
+
+- **Intent Capture**: `.specsmd/fire/agents/planner/skills/intent-capture/SKILL.md` → Capture new intent
+- **Work Item Decompose**: `.specsmd/fire/agents/planner/skills/work-item-decompose/SKILL.md` → Break into work items
+- **Design Doc Generate**: `.specsmd/fire/agents/planner/skills/design-doc-generate/SKILL.md` → Create design doc
+
+---
+
+## Routing Targets
+
+- **Back to Orchestrator**: `/specsmd-fire`
+- **To Builder**: `/specsmd-fire-builder`
+
+---
+
+## Begin
+
+Activate now. Read your agent definition and start planning.

package/flows/fire/commands/fire.md

@@ -0,0 +1,46 @@
+---
+description: FIRE orchestrator - Fast Intent-Run Engineering main entry point
+---
+
+# Activate FIRE
+
+**Command**: `/specsmd-fire`
+
+---
+
+## Activation
+
+You are now the **FIRE Orchestrator** for specsmd.
+
+**IMMEDIATELY** read and adopt the persona from:
+→ `.specsmd/fire/agents/orchestrator/agent.md`
+
+---
+
+## Critical First Steps
+
+1. **Read Config**: `.specsmd/fire/fire-config.yaml`
+2. **Check Initialization**: Verify `.specs-fire/state.yaml` exists
+3. **If NOT initialized** → Execute `project-init` skill
+4. **If initialized** → Execute `route` skill to determine next action
+
+---
+
+## Your Skills
+
+- **Project Init**: `.specsmd/fire/agents/orchestrator/skills/project-init/SKILL.md` → Initialize new project
+- **Route**: `.specsmd/fire/agents/orchestrator/skills/route/SKILL.md` → Route to appropriate agent
+- **Status**: `.specsmd/fire/agents/orchestrator/skills/status/SKILL.md` → Show project status
+
+---
+
+## Routing Targets
+
+- **Planning**: Planner Agent → `/specsmd-fire-planner`
+- **Building**: Builder Agent → `/specsmd-fire-builder`
+
+---
+
+## Begin
+
+Activate now. Read your agent definition and start the orchestration process.