specsmd 0.0.0-dev.40 → 0.0.0-dev.42

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

@@ -0,0 +1,211 @@
+# 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/modify]
+      </output>
+    </checkpoint>
+  </step>
+
+  <step n="9" title="Handle Response">
+    <check if="response == y">
+      <action>Save design doc 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)?
+      </output>
+    </check>
+    <check if="response == modify">
+      <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}*
+```

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

@@ -0,0 +1,142 @@
+# 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**: {how to measure}
+
+      Is this accurate? [Y/n/clarify]
+    </output>
+    <check if="response == clarify">
+      <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</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/work-item-decompose/SKILL.md

@@ -0,0 +1,174 @@
+# 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 complexity:</action>
+
+    <complexity level="low">
+      - Single file or few files
+      - Well-understood pattern
+      - No external dependencies
+      - Examples: bug fix, config change, simple utility
+      → Mode: autopilot
+    </complexity>
+
+    <complexity level="medium">
+      - Multiple files
+      - Standard patterns with some decisions
+      - May touch existing code
+      - Examples: new endpoint, new component, feature addition
+      → Mode: confirm
+    </complexity>
+
+    <complexity level="high">
+      - Architectural decisions required
+      - Security or data implications
+      - Core system changes
+      - Examples: auth system, payment flow, database migration
+      → Mode: validate
+    </complexity>
+  </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}"
+
+      | # | Work Item | Complexity | Mode | Depends On |
+      |---|-----------|------------|------|------------|
+      {for each item}
+      | {n} | {title} | {complexity} | {mode} | {dependencies} |
+      {/for}
+
+      Total: {count} work items
+      Estimated: {low} autopilot, {medium} confirm, {high} validate
+
+      Approve this plan? [Y/n/modify]
+    </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, save to {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}".
+
+      First work item: {first-item.title} ({first-item.mode})
+
+      Start execution? [Y/n]
+    </output>
+    <check if="response == y">
+      <route-to>builder-agent</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/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.