@ydtb/specsmd 0.1.22

package/flows/fire/agents/builder/skills/walkthrough-generate/SKILL.md

@@ -0,0 +1,181 @@
+---
+name: walkthrough-generate
+description: Generate implementation walkthrough for human review after run completion. Documents decisions, changes, and verification steps.
+version: 1.0.0
+---
+
+<objective>
+Generate implementation walkthrough for human review after run completion.
+</objective>
+
+<triggers>
+  - Run completed successfully
+  - Invoked by run-execute skill
+</triggers>
+
+<degrees_of_freedom>
+  **LOW** — Follow walkthrough structure precisely. Be thorough but concise.
+</degrees_of_freedom>
+
+<llm critical="true">
+  <mandate>ALWAYS generate walkthrough after run completion</mandate>
+  <mandate>Document DECISIONS, not just changes</mandate>
+  <mandate>Include verification steps — how to test this works</mandate>
+  <mandate>Track DEVIATIONS from plan — compare to original work item</mandate>
+  <mandate>List ALL new dependencies added during implementation</mandate>
+  <mandate>Capture developer notes — gotchas save future debugging time</mandate>
+</llm>
+
+<flow>
+  <step n="1" title="Gather Implementation Data">
+    <action>Read run log from .specs-fire/runs/{run-id}/run.md</action>
+    <action>Read work item plan from .specs-fire/intents/{intent}/work-items/{work-item}/</action>
+    <action>Collect:</action>
+    <substep>Work item details (id, title, intent)</substep>
+    <substep>Files created during implementation</substep>
+    <substep>Files modified during implementation</substep>
+    <substep>Decisions made during execution</substep>
+    <substep>Tests added and coverage</substep>
+    <substep>Dependencies added (new packages in package.json, requirements.txt, etc.)</substep>
+    <substep>Deviations from the original work item plan</substep>
+  </step>
+
+  <step n="2" title="Analyze Implementation">
+    <action>For each file created/modified:</action>
+    <substep>Identify purpose of the file</substep>
+    <substep>Summarize key changes</substep>
+    <substep>Note patterns or approaches used</substep>
+    <action>Document structure overview:</action>
+    <substep>How the pieces fit together architecturally</substep>
+    <substep>Data flow or component relationships</substep>
+    <substep>Keep high-level, NO CODE</substep>
+  </step>
+
+  <step n="3" title="Document Key Details">
+    <action>Extract implementation highlights:</action>
+    <substep>Main flow/algorithm implemented</substep>
+    <substep>Security considerations (if applicable)</substep>
+    <substep>Performance considerations (if applicable)</substep>
+    <substep>Integration points with existing code</substep>
+    <action>Document deviations from plan:</action>
+    <substep>Compare implementation to original work item plan</substep>
+    <substep>Note any changes and explain WHY they were made</substep>
+    <substep>If no deviations, state "None"</substep>
+    <action>Capture developer notes:</action>
+    <substep>Gotchas or non-obvious behaviors</substep>
+    <substep>Tips for future developers</substep>
+    <substep>Context that would save debugging time</substep>
+  </step>
+
+  <step n="4" title="Create Verification Steps">
+    <action>Generate how-to-verify section:</action>
+    <substep>Commands to run the feature</substep>
+    <substep>Expected behavior/output</substep>
+    <substep>Manual test scenarios</substep>
+  </step>
+
+  <step n="5" title="Generate Walkthrough">
+    <action>Generate walkthrough using template: templates/walkthrough.md.hbs</action>
+    <action>Save to: .specs-fire/runs/{run-id}/walkthrough.md</action>
+    <output>
+      Walkthrough generated: .specs-fire/runs/{run-id}/walkthrough.md
+    </output>
+  </step>
+</flow>
+
+<output_template>
+  **Walkthrough** (`.specs-fire/runs/{run-id}/walkthrough.md`):
+
+  ```markdown
+  ---
+  run: {run-id}
+  work_item: {work-item-id}
+  intent: {intent-id}
+  generated: {timestamp}
+  mode: {mode}
+  ---
+
+  # Implementation Walkthrough: {title}
+
+  ## Summary
+
+  {2-3 sentences describing what was implemented}
+
+  ## Structure Overview
+
+  {High-level description of how pieces fit together - NO CODE}
+
+  ## Files Changed
+
+  ### Created
+
+  | File | Purpose |
+  |------|---------|
+  | `{path}` | {purpose} |
+
+  ### Modified
+
+  | File | Changes |
+  |------|---------|
+  | `{path}` | {changes} |
+
+  ## Key Implementation Details
+
+  ### 1. {Detail Title}
+
+  {description of implementation approach}
+
+  ## Decisions Made
+
+  | Decision | Choice | Rationale |
+  |----------|--------|-----------|
+  | {decision} | {choice} | {rationale} |
+
+  ## Deviations from Plan
+
+  {Changes from work item plan and why, or "None"}
+
+  ## Dependencies Added
+
+  | Package | Why Needed |
+  |---------|------------|
+  | `{package}` | {reason} |
+
+  ## How to Verify
+
+  1. **{Step Title}**
+     ```bash
+     {command}
+     ```
+     Expected: {expected output}
+
+  2. **{Step Title}**
+     {manual verification steps}
+
+  ## Test Coverage
+
+  - Tests added: {count}
+  - Coverage: {percentage}%
+  - Status: {passing/failing}
+
+  ## Developer Notes
+
+  {Gotchas, tips, or context for future work - keep brief}
+
+  ---
+  *Generated by specs.md - fabriqa.ai FIRE Flow Run {run-id}*
+  ```
+
+</output_template>
+
+<success_criteria>
+  <criterion>Walkthrough generated with all sections</criterion>
+  <criterion>Structure overview explains architecture (NO CODE)</criterion>
+  <criterion>Files changed documented with purposes</criterion>
+  <criterion>Decisions recorded with rationale</criterion>
+  <criterion>Deviations from plan documented (or "None")</criterion>
+  <criterion>Dependencies added listed with reasons</criterion>
+  <criterion>Verification steps included</criterion>
+  <criterion>Developer notes capture gotchas and tips</criterion>
+  <criterion>Saved to run folder</criterion>
+</success_criteria>

package/flows/fire/agents/builder/skills/walkthrough-generate/templates/walkthrough.md.hbs

@@ -0,0 +1,108 @@
+---
+run: {{run_id}}
+work_item: {{work_item_id}}
+intent: {{intent_id}}
+generated: {{generated}}
+mode: {{mode}}
+---
+
+# Implementation Walkthrough: {{title}}
+
+## Summary
+
+{{summary}}
+
+## Structure Overview
+
+{{structure_overview}}
+
+## Files Changed
+
+### Created
+
+| File | Purpose |
+|------|---------|
+{{#each files_created}}
+| `{{this.path}}` | {{this.purpose}} |
+{{/each}}
+{{#unless files_created}}
+| (none) | |
+{{/unless}}
+
+### Modified
+
+| File | Changes |
+|------|---------|
+{{#each files_modified}}
+| `{{this.path}}` | {{this.changes}} |
+{{/each}}
+{{#unless files_modified}}
+| (none) | |
+{{/unless}}
+
+## Key Implementation Details
+
+{{#each implementation_details}}
+### {{@index}}. {{this.title}}
+
+{{this.description}}
+
+{{/each}}
+
+## Decisions Made
+
+| Decision | Choice | Rationale |
+|----------|--------|-----------|
+{{#each decisions}}
+| {{this.decision}} | {{this.choice}} | {{this.rationale}} |
+{{/each}}
+{{#unless decisions}}
+| (none) | | |
+{{/unless}}
+
+## Deviations from Plan
+
+{{#if deviations}}
+{{deviations}}
+{{else}}
+None
+{{/if}}
+
+## Dependencies Added
+
+| Package | Why Needed |
+|---------|------------|
+{{#each dependencies_added}}
+| `{{this.package}}` | {{this.reason}} |
+{{/each}}
+{{#unless dependencies_added}}
+| (none) | |
+{{/unless}}
+
+## How to Verify
+
+{{#each verification_steps}}
+{{@index}}. **{{this.title}}**
+   ```bash
+   {{this.command}}
+   ```
+   Expected: {{this.expected}}
+
+{{/each}}
+
+## Test Coverage
+
+- Tests added: {{tests_added}}
+- Coverage: {{coverage}}%
+- Status: {{test_status}}
+
+## Developer Notes
+
+{{#if developer_notes}}
+{{developer_notes}}
+{{else}}
+(none)
+{{/if}}
+
+---
+*Generated by specs.md - fabriqa.ai FIRE Flow Run {{run_id}}*

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

@@ -0,0 +1,144 @@
+---
+name: fire-orchestrator-agent
+description: FIRE flow orchestrator and session manager. Routes users to the appropriate agent based on project state.
+version: 1.0.0
+---
+
+<role>
+You are the **Orchestrator Agent** for FIRE (Fast Intent-Run Engineering).
+
+- **Role**: FIRE Flow Orchestrator & Session Manager
+- **Communication**: Direct and efficient. Route based on state, not assumptions.
+- **Principle**: Minimize friction. Get users to the right agent fast.
+</role>
+
+<constraints critical="true">
+  <constraint>ALWAYS read state.yaml before routing</constraint>
+  <constraint>NEVER assume project state — verify it</constraint>
+  <constraint>ALWAYS scan file system to discover untracked intents/work-items</constraint>
+</constraints>
+
+<on_activation>
+  When user invokes this agent:
+
+  <step n="1" title="Load Configuration">
+    <action>Read `.specsmd/fire/memory-bank.yaml` for schema</action>
+  </step>
+
+  <step n="2" title="Check Initialization">
+    <action>Check if `.specs-fire/state.yaml` exists</action>
+  </step>
+
+  <step n="3" title="Route by State">
+    <check if="NOT initialized (new project)">
+      <action>Execute `project-init` skill to set up workspace</action>
+    </check>
+    <check if="initialized">
+      <action>Read `.specs-fire/state.yaml` for current state</action>
+      <action>Execute `route` skill to determine next action</action>
+    </check>
+  </step>
+</on_activation>
+
+<skills>
+  | Command | Skill | Description |
+  |---------|-------|-------------|
+  | `init` | `skills/project-init/SKILL.md` | Initialize FIRE project |
+  | `route` | `skills/route/SKILL.md` | Route to appropriate agent |
+  | `status` | `skills/status/SKILL.md` | Show project status |
+</skills>
+
+<routing_logic>
+
+  ```
+  [1] state.yaml exists?
+      → No  → Execute project-init skill
+      → Yes → [2]
+
+  [2] Active run in progress?
+      → Yes → Route to Builder Agent (resume run)
+      → No  → [3]
+
+  [3] Pending work items exist?
+      → Yes → Route to Builder Agent (start next work item)
+      → No  → [4]
+
+  [4] Active intent with no work items?
+      → Yes → Route to Planner Agent (decompose intent)
+      → No  → [5]
+
+  [5] No active intents?
+      → Route to Planner Agent (capture new intent)
+  ```
+
+</routing_logic>
+
+<state_schema>
+  The orchestrator maintains `state.yaml`:
+
+  ```yaml
+  project:
+    name: "project-name"
+    fire_version: "0.1.8"
+
+  workspace:
+    type: brownfield
+    structure: monolith
+    autonomy_bias: balanced
+
+  intents:
+    - id: user-auth
+      title: "User Authentication"
+      status: in_progress
+      work_items:
+        - id: login-endpoint
+          status: completed
+          complexity: medium
+          mode: confirm
+        - id: session-management
+          status: pending
+          complexity: medium
+          mode: confirm
+
+  runs:
+    active: []  # List of active runs (supports multiple parallel runs)
+    completed:
+      - id: run-001
+        work_items:
+          - id: login-endpoint
+            intent: user-auth
+            mode: confirm
+            status: completed
+        completed: "2026-01-19T12:00:00Z"
+  ```
+
+</state_schema>
+
+<handoff_protocol>
+  When routing to another agent, provide context:
+
+  <handoff to="Planner">
+    ```
+    Routing to Planner Agent.
+    Context: No active intent. Ready for new intent capture.
+    ```
+  </handoff>
+
+  <handoff to="Builder">
+    ```
+    Routing to Builder Agent.
+    Context: Work item "session-management" ready for execution.
+    Mode: confirm (1 checkpoint)
+    ```
+  </handoff>
+</handoff_protocol>
+
+<success_criteria>
+  <criterion>Project state correctly identified</criterion>
+  <criterion>User routed to appropriate agent</criterion>
+  <criterion>Context passed to target agent</criterion>
+</success_criteria>
+
+<begin>
+  Read `.specs-fire/state.yaml` and execute the `route` skill to determine the user's next action.
+</begin>

package/flows/fire/agents/orchestrator/skills/project-init/SKILL.md

@@ -0,0 +1,226 @@
+---
+name: project-init
+description: Initialize a new FIRE project by detecting workspace type and setting up standards.
+version: 1.0.0
+---
+
+<objective>
+Initialize a new FIRE project by detecting workspace type and setting up standards.
+</objective>
+
+<triggers>
+  - User runs `/specsmd-fire` on uninitialized project
+  - No `.specs-fire/state.yaml` exists
+</triggers>
+
+<flow>
+  <step n="1" title="Welcome">
+    <output>
+      Welcome to FIRE (Fast Intent-Run Engineering).
+
+      Let me analyze your project to get started.
+    </output>
+  </step>
+
+  <step n="2" title="Detect Workspace">
+    <action>Analyze project root for existing code</action>
+    <check if="src/ or app/ or main entry points exist">
+      <set>workspace.type = brownfield</set>
+    </check>
+    <check if="minimal files, no source directories">
+      <set>workspace.type = greenfield</set>
+    </check>
+  </step>
+
+  <step n="3a" title="Brownfield Setup" if="workspace.type == brownfield">
+    <output>
+      Existing project detected. I'll analyze your codebase to infer standards.
+    </output>
+    <action>Detect tech stack (language, framework, database)</action>
+    <action>Detect structure (monolith, monorepo)</action>
+    <action>Infer coding patterns</action>
+
+    <monorepo_detection>
+      Check for monorepo indicators:
+      - nx.json, turbo.json, pnpm-workspace.yaml, lerna.json, rush.json
+      - package.json with "workspaces" field
+      - Cargo.toml with [workspace] section
+      - go.work file
+      - Multiple independent package/dependency manifests
+      - Common patterns: packages/*, apps/*, services/*, libs/*
+
+      If any indicator found → workspace.structure = "monorepo"
+    </monorepo_detection>
+
+    <output>
+      Here's what I found:
+
+      **Tech Stack**: {detected_tech}
+      **Structure**: {detected_structure}
+      **Patterns**: {detected_patterns}
+
+      Does this look accurate? [Y/n/edit]
+    </output>
+  </step>
+
+  <step n="3b" title="Greenfield Setup" if="workspace.type == greenfield">
+    <ask>
+      What do you want to build? Tell me about:
+      - What the project does
+      - Target users
+      - Key features
+    </ask>
+    <action>Analyze description, suggest tech stack</action>
+    <output>
+      Based on your description, I suggest:
+
+      **Language**: {suggested_language}
+      **Framework**: {suggested_framework}
+      **Database**: {suggested_database}
+
+      Accept these suggestions? [Y/n/edit]
+    </output>
+  </step>
+
+  <step n="4" title="Choose Autonomy Level">
+    <output>
+      How autonomous should FIRE be when executing work items?
+
+      **[1] Autonomous** — AI executes more freely, fewer checkpoints
+           (medium complexity → autopilot, high → confirm)
+
+      **[2] Balanced** — Standard checkpoints based on complexity (Recommended)
+           (low → autopilot, medium → confirm, high → validate)
+
+      **[3] Controlled** — More human oversight, more checkpoints
+           (low → confirm, medium/high → validate)
+
+      Choose [1/2/3]:
+    </output>
+    <check if="response == 1">
+      <set>workspace.autonomy_bias = autonomous</set>
+    </check>
+    <check if="response == 2">
+      <set>workspace.autonomy_bias = balanced</set>
+    </check>
+    <check if="response == 3">
+      <set>workspace.autonomy_bias = controlled</set>
+    </check>
+    <note>Can be changed later in .specs-fire/state.yaml</note>
+  </step>
+
+  <step n="5" title="Detect Modules" if="workspace.structure == monorepo">
+    <output>
+      Monorepo detected. Let me find and analyze the modules.
+    </output>
+
+    <action>Find module directories by exploring:</action>
+    <substep>Paths from workspace config (nx.json projects, pnpm-workspace.yaml, etc.)</substep>
+    <substep>Common patterns: packages/*, apps/*, services/*, libs/*, modules/*</substep>
+    <substep>Directories with their own dependency manifest</substep>
+
+    <action>For each discovered module, analyze (AI-driven, no hardcoded mappings):</action>
+    <substep>Primary language (from file extensions, config files)</substep>
+    <substep>Build/test commands (from CI config, package scripts, Makefile)</substep>
+    <substep>Linter/formatter (from config files in module)</substep>
+    <substep>Package manager (from lock files, manifests)</substep>
+
+    <output>
+      Found {{module_count}} modules:
+
+      | Module | Language | Test Command | Linter |
+      |--------|----------|--------------|--------|
+      {{#each modules}}
+      | {{path}} | {{language}} | {{test_cmd}} | {{linter}} |
+      {{/each}}
+
+      Create module-specific standards?
+      [c] All modules — create standards for all
+      [s] Select — choose which modules
+      [n] None — I'll create them manually later
+    </output>
+
+    <check if="response == c or response == s">
+      <action>For each selected module, create {module}/.specs-fire/standards/tech-stack.md</action>
+      <note>Only tech-stack.md by default — other standards inherit from root</note>
+    </check>
+  </step>
+
+  <step n="6" title="Create Structure">
+    <action>Create .specs-fire/ directory</action>
+    <action>Create .specs-fire/intents/</action>
+    <action>Create .specs-fire/runs/</action>
+    <action>Create .specs-fire/standards/</action>
+    <action>Generate .specs-fire/state.yaml (include autonomy_bias, workspace.structure)</action>
+    <action>Generate standards using templates:</action>
+    <substep>constitution.md — templates/constitution.md.hbs</substep>
+    <substep>tech-stack.md — templates/tech-stack.md.hbs</substep>
+    <substep>coding-standards.md — templates/coding-standards.md.hbs</substep>
+    <substep>testing-standards.md — templates/testing-standards.md.hbs</substep>
+    <substep>system-architecture.md — templates/system-architecture.md.hbs</substep>
+
+    <check if="workspace.structure == monorepo and modules_selected">
+      <action>For each selected module:</action>
+      <substep>Create {module}/.specs-fire/standards/</substep>
+      <substep>Generate {module}/.specs-fire/standards/tech-stack.md with detected settings</substep>
+    </check>
+  </step>
+
+  <step n="7" title="Complete">
+    <output>
+      FIRE initialized!
+
+      Structure created:
+      ```
+      .specs-fire/
+      ├── state.yaml
+      ├── intents/
+      ├── runs/
+      └── standards/
+          ├── constitution.md        # Universal policies (always inherited)
+          ├── tech-stack.md
+          ├── coding-standards.md
+          ├── testing-standards.md
+          └── system-architecture.md
+      {{#if modules_created}}
+
+      Module standards created:
+      {{#each modules_created}}
+      {{path}}/.specs-fire/standards/
+      └── tech-stack.md
+      {{/each}}
+      {{/if}}
+      ```
+
+      Ready to capture your first intent.
+      What do you want to build?
+    </output>
+    <route_to>planner-agent (intent-capture)</route_to>
+  </step>
+</flow>
+
+<output_artifacts>
+
+  | Artifact | Location | Template |
+  |----------|----------|----------|
+  | State | `.specs-fire/state.yaml` | — |
+  | Constitution | `.specs-fire/standards/constitution.md` | `templates/constitution.md.hbs` |
+  | Tech Stack | `.specs-fire/standards/tech-stack.md` | `templates/tech-stack.md.hbs` |
+  | Coding Standards | `.specs-fire/standards/coding-standards.md` | `templates/coding-standards.md.hbs` |
+  | Testing Standards | `.specs-fire/standards/testing-standards.md` | `templates/testing-standards.md.hbs` |
+  | System Architecture | `.specs-fire/standards/system-architecture.md` | `templates/system-architecture.md.hbs` |
+  | Module Tech Stack | `{module}/.specs-fire/standards/tech-stack.md` | AI-generated |
+</output_artifacts>
+
+<success_criteria>
+  <criterion>Workspace type correctly detected (greenfield/brownfield)</criterion>
+  <criterion>Workspace structure correctly detected (monolith/monorepo)</criterion>
+  <criterion>Tech stack identified or suggested</criterion>
+  <criterion>Autonomy level selected</criterion>
+  <criterion>.specs-fire/ directory structure created</criterion>
+  <criterion>constitution.md generated (universal policies)</criterion>
+  <criterion>Standards files generated from templates</criterion>
+  <criterion>state.yaml created with correct configuration</criterion>
+  <criterion>If monorepo: modules detected and analyzed</criterion>
+  <criterion>If monorepo: module standards created for selected modules</criterion>
+</success_criteria>