specsmd 0.0.0-dev.9 → 0.0.0-dev.90

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

@@ -0,0 +1,267 @@
+---
+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>
+    <action>Identify architecture pattern (if multi-component):</action>
+    <substep>Pattern used (Repository, Service Layer, MVC, Clean Architecture, etc.)</substep>
+    <substep>Layer structure diagram (ASCII) if applicable</substep>
+    <action>Document domain model (if entities/models created):</action>
+    <substep>Entities with properties and business rules</substep>
+    <substep>Value objects with constraints</substep>
+  </step>
+
+  <step n="3" title="Document Key Details">
+    <action>Extract implementation highlights:</action>
+    <substep>Main flow/algorithm implemented</substep>
+    <substep>Integration points with existing code</substep>
+    <action>Document security considerations (if applicable):</action>
+    <substep>Authentication/authorization approach</substep>
+    <substep>Input validation strategy</substep>
+    <substep>Data protection measures</substep>
+    <substep>Format as table: Concern | Approach</substep>
+    <action>Document performance considerations (if applicable):</action>
+    <substep>Optimization strategies used</substep>
+    <substep>Caching, indexing, or query optimization</substep>
+    <substep>Scalability approach</substep>
+    <substep>Format as table: Requirement | Implementation</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="Assess Ready for Review">
+    <action>Evaluate implementation completeness:</action>
+    <substep>All acceptance criteria met?</substep>
+    <substep>Tests passing?</substep>
+    <substep>No critical issues remaining?</substep>
+    <substep>Documentation updated (if applicable)?</substep>
+    <substep>Developer notes captured?</substep>
+    <action>Generate checklist with [x] for met, [ ] for unmet</action>
+  </step>
+
+  <step n="6" title="Generate Walkthrough">
+    <action>Generate walkthrough using template: templates/walkthrough.md.hbs</action>
+    <action>Include all sections (conditional sections only if data exists):</action>
+    <substep>Architecture — only if multi-component with clear pattern</substep>
+    <substep>Domain Model — only if entities/value objects created</substep>
+    <substep>Security Considerations — only if security-relevant changes</substep>
+    <substep>Performance Considerations — only if performance-relevant changes</substep>
+    <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}
+
+  ## Architecture (if multi-component)
+
+  ### Pattern Used
+  {Pattern and rationale - e.g., Repository pattern for data access abstraction}
+
+  ### Layer Structure
+  ```text
+  ┌─────────────────────────────┐
+  │      Presentation           │
+  ├─────────────────────────────┤
+  │      Application            │
+  ├─────────────────────────────┤
+  │        Domain               │
+  ├─────────────────────────────┤
+  │     Infrastructure          │
+  └─────────────────────────────┘
+  ```
+
+## Files Changed
+
+### Created
+
+  | File | Purpose |
+  |------|---------|
+  | `{path}` | {purpose} |
+
+### Modified
+
+  | File | Changes |
+  |------|---------|
+  | `{path}` | {changes} |
+
+## Domain Model (if entities created)
+
+### Entities
+
+  | Entity | Properties | Business Rules |
+  |--------|------------|----------------|
+  | {name} | {props} | {rules} |
+
+### Value Objects
+
+  | Value Object | Properties | Constraints |
+  |--------------|------------|-------------|
+  | {name} | {props} | {constraints} |
+
+## Key Implementation Details
+
+### 1. {Detail Title}
+
+  {description of implementation approach}
+
+## Security Considerations (if applicable)
+
+  | Concern | Approach |
+  |---------|----------|
+  | {concern} | {approach} |
+
+## Performance Considerations (if applicable)
+
+  | Requirement | Implementation |
+  |-------------|----------------|
+  | {requirement} | {implementation} |
+
+## 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}
+
+## Test Coverage
+
+- Tests added: {count}
+- Coverage: {percentage}%
+- Status: {passing/failing}
+
+## Ready for Review
+
+- [x] All acceptance criteria met
+- [x] Tests passing
+- [x] No critical issues
+- [ ] Documentation updated (if applicable)
+- [x] Developer notes captured
+
+## 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 applicable sections</criterion>
+  <criterion>Structure overview explains architecture (NO CODE)</criterion>
+  <criterion>Architecture pattern documented (if multi-component)</criterion>
+  <criterion>Domain model documented (if entities created)</criterion>
+  <criterion>Files changed documented with purposes</criterion>
+  <criterion>Security considerations documented (if security-relevant)</criterion>
+  <criterion>Performance considerations documented (if performance-relevant)</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>Ready for Review checklist completed</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,176 @@
+---
+run: {{run_id}}
+work_item: {{work_item_id}}
+intent: {{intent_id}}
+generated: {{generated}}
+mode: {{mode}}
+---
+
+# Implementation Walkthrough: {{title}}
+
+## Summary
+
+{{summary}}
+
+## Structure Overview
+
+{{structure_overview}}
+
+{{#if architecture}}
+## Architecture
+
+### Pattern Used
+
+{{architecture.pattern}}
+
+{{#if architecture.layer_diagram}}
+### Layer Structure
+
+```text
+{{architecture.layer_diagram}}
+```
+{{/if}}
+{{/if}}
+
+## 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}}
+
+{{#if domain_model}}
+## Domain Model
+
+{{#if domain_model.entities}}
+### Entities
+
+| Entity | Properties | Business Rules |
+|--------|------------|----------------|
+{{#each domain_model.entities}}
+| {{this.name}} | {{this.properties}} | {{this.rules}} |
+{{/each}}
+{{/if}}
+
+{{#if domain_model.value_objects}}
+### Value Objects
+
+| Value Object | Properties | Constraints |
+|--------------|------------|-------------|
+{{#each domain_model.value_objects}}
+| {{this.name}} | {{this.properties}} | {{this.constraints}} |
+{{/each}}
+{{/if}}
+{{/if}}
+
+## Key Implementation Details
+
+{{#each implementation_details}}
+### {{@index}}. {{this.title}}
+
+{{this.description}}
+
+{{/each}}
+
+{{#if security_considerations}}
+## Security Considerations
+
+| Concern | Approach |
+|---------|----------|
+{{#each security_considerations}}
+| {{this.concern}} | {{this.approach}} |
+{{/each}}
+{{/if}}
+
+{{#if performance_considerations}}
+## Performance Considerations
+
+| Requirement | Implementation |
+|-------------|----------------|
+{{#each performance_considerations}}
+| {{this.requirement}} | {{this.implementation}} |
+{{/each}}
+{{/if}}
+
+## 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}}
+
+## Ready for Review
+
+- [{{#if ready.acceptance_met}}x{{else}} {{/if}}] All acceptance criteria met
+- [{{#if ready.tests_passing}}x{{else}} {{/if}}] Tests passing
+- [{{#if ready.no_critical_issues}}x{{else}} {{/if}}] No critical issues
+- [{{#if ready.docs_updated}}x{{else}} {{/if}}] Documentation updated (if applicable)
+- [{{#if ready.notes_captured}}x{{else}} {{/if}}] Developer notes captured
+
+## 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-fabriqa-2026-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>