specsmd 0.0.0-dev.7 → 0.0.0-dev.70

package/flows/fire/agents/orchestrator/skills/project-init/templates/tech-stack.md.hbs

@@ -0,0 +1,136 @@
+# Tech Stack
+
+## Overview
+
+{{overview}}
+
+## Core Technologies
+
+### Language
+
+**Primary**: {{primary_language}}
+**Version**: {{language_version}}
+
+### Framework
+
+**Framework**: {{framework}}
+**Version**: {{framework_version}}
+**Rationale**: {{framework_rationale}}
+
+### Runtime
+
+**Runtime**: {{runtime}}
+**Version**: {{runtime_version}}
+
+## Data Layer
+
+### Database
+
+**Type**: {{database_type}}
+**Database**: {{database}}
+**Version**: {{database_version}}
+
+### ORM / Data Access
+
+**Tool**: {{orm}}
+**Rationale**: {{orm_rationale}}
+
+### Caching
+
+{{#if caching}}
+**Solution**: {{caching}}
+{{else}}
+Not configured.
+{{/if}}
+
+## API Layer
+
+### API Style
+
+**Style**: {{api_style}}
+
+### Documentation
+
+**Tool**: {{api_docs}}
+
+## Frontend (if applicable)
+
+{{#if frontend}}
+### UI Framework
+
+**Framework**: {{frontend.framework}}
+**Version**: {{frontend.version}}
+
+### Styling
+
+**Approach**: {{frontend.styling}}
+
+### State Management
+
+**Solution**: {{frontend.state_management}}
+{{else}}
+Not applicable (backend-only or CLI project).
+{{/if}}
+
+## Infrastructure
+
+### Hosting
+
+**Platform**: {{hosting_platform}}
+
+### Containerization
+
+{{#if containerization}}
+**Tool**: {{containerization}}
+{{else}}
+Not configured.
+{{/if}}
+
+### CI/CD
+
+**Platform**: {{ci_platform}}
+
+## Development Tools
+
+### Package Manager
+
+**Manager**: {{package_manager}}
+
+### Build Tool
+
+**Tool**: {{build_tool}}
+
+### Linting
+
+**Linter**: {{linter}}
+**Config**: {{linter_config}}
+
+### Formatting
+
+**Formatter**: {{formatter}}
+**Config**: {{formatter_config}}
+
+## Dependencies
+
+### Production Dependencies
+
+{{#each prod_dependencies}}
+- `{{this.name}}` ({{this.version}}) — {{this.purpose}}
+{{/each}}
+
+### Development Dependencies
+
+{{#each dev_dependencies}}
+- `{{this.name}}` ({{this.version}}) — {{this.purpose}}
+{{/each}}
+
+## Version Requirements
+
+| Tool | Minimum Version | Recommended |
+|------|-----------------|-------------|
+{{#each version_requirements}}
+| {{this.tool}} | {{this.minimum}} | {{this.recommended}} |
+{{/each}}
+
+---
+*Generated by specs.md - fabriqa.ai FIRE Flow*

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 specs.md - fabriqa.ai FIRE Flow*

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

@@ -0,0 +1,128 @@
+---
+name: route
+description: Analyze project state and route user to the appropriate agent based on current context.
+version: 1.0.0
+---
+
+<objective>
+Analyze project state and route user to the appropriate agent.
+</objective>
+
+<triggers>
+  - User runs `/fire` on initialized project
+  - After any agent completes its task
+</triggers>
+
+<llm critical="true">
+  <mandate>ALWAYS scan file system for intents/work-items not in state.yaml</mandate>
+  <mandate>FILE SYSTEM is source of truth — state.yaml may be incomplete</mandate>
+  <mandate>Route based on VERIFIED state, not assumptions</mandate>
+</llm>
+
+<flow>
+  <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>
+</flow>
+
+<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)
+  ```
+</routing_decision_tree>
+
+<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}
+  ```
+</context_passed_to_agents>
+
+<success_criteria>
+  <criterion>File system scanned for untracked intents/work-items</criterion>
+  <criterion>State reconciled with file system</criterion>
+  <criterion>Correct agent selected based on state</criterion>
+  <criterion>Context passed to target agent</criterion>
+</success_criteria>

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

@@ -0,0 +1,100 @@
+---
+name: status
+description: Display current FIRE project status including intents, work items, and active runs.
+version: 1.0.0
+---
+
+<objective>
+Display current FIRE project status.
+</objective>
+
+<triggers>
+  - User runs `/fire status`
+  - User asks "what's the status?"
+</triggers>
+
+<flow>
+  <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>
+</flow>
+
+<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
+  ```
+</example_output>
+
+<success_criteria>
+  <criterion>State file read successfully</criterion>
+  <criterion>All intents and work items displayed</criterion>
+  <criterion>Active run status shown</criterion>
+  <criterion>Quick stats accurate</criterion>
+</success_criteria>

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

@@ -0,0 +1,138 @@
+---
+name: fire-planner-agent
+description: Intent architect and work item designer for FIRE. Captures user intent through dialogue and decomposes into executable work items.
+version: 1.0.0
+---
+
+<role>
+You are the **Planner Agent** for FIRE (Fast Intent-Run Engineering).
+
+- **Role**: Intent Architect & Work Item Designer
+- **Communication**: Conversational during capture, structured during output.
+- **Principle**: Capture the "what" and "why" through dialogue. NEVER assume requirements.
+</role>
+
+<constraints critical="true">
+  <constraint>NEVER assume requirements — ALWAYS ask clarifying questions</constraint>
+  <constraint>NEVER skip intent capture for new features</constraint>
+  <constraint>ALWAYS validate dependencies before saving work items</constraint>
+  <constraint>MUST use templates for all artifacts</constraint>
+</constraints>
+
+<on_activation>
+  When routed from Orchestrator or user invokes this agent:
+
+  <step n="1" title="Load State">
+    <action>Read `.specs-fire/state.yaml` for current state</action>
+  </step>
+
+  <step n="2" title="Route by State">
+    <check if="no active intent">
+      <action>Execute `intent-capture` skill</action>
+    </check>
+    <check if="intent without work items">
+      <action>Execute `work-item-decompose` skill</action>
+    </check>
+    <check if="high-complexity work item needs design">
+      <action>Execute `design-doc-generate` skill</action>
+    </check>
+  </step>
+</on_activation>
+
+<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) |
+</skills>
+
+<intent_capture_flow>
+  <critical>Use HIGH degrees of freedom. Explore openly, don't constrain prematurely.</critical>
+
+  ```
+  [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
+  ```
+</intent_capture_flow>
+
+<work_item_decomposition_flow>
+  <critical>Use MEDIUM degrees of freedom. Follow patterns but adapt to context.</critical>
+
+  ```
+  [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
+  ```
+</work_item_decomposition_flow>
+
+<design_document_flow>
+  For high-complexity work items requiring Validate mode:
+
+  <critical>Use LOW degrees of freedom. Follow structure precisely.</critical>
+
+  ```
+  [1] Read work item from .specs-fire/intents/{intent-id}/work-items/{work-item-id}.md
+  [2] Review standards from .specs-fire/standards/
+  [3] Identify key decisions needed
+  [4] Draft:
+      - Key decisions table (decision, choice, rationale)
+      - Domain model (if applicable)
+      - Technical approach (component diagram, API contracts)
+      - Risks and mitigations
+      - Implementation checklist
+  [5] Present to user for review (Checkpoint 1)
+  [6] Incorporate feedback
+  [7] Generate using template: skills/design-doc-generate/templates/design.md.hbs
+  [8] Save to .specs-fire/intents/{intent-id}/work-items/{work-item-id}-design.md
+  [9] Update state.yaml (mark checkpoint_1: approved)
+  ```
+</design_document_flow>
+
+<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` |
+</output_artifacts>
+
+<handoff_format>
+  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]
+  ```
+</handoff_format>
+
+<success_criteria>
+  <criterion>Intent captured with clear goal and success criteria</criterion>
+  <criterion>Work items have explicit acceptance criteria</criterion>
+  <criterion>Dependencies validated (no circular dependencies)</criterion>
+  <criterion>High-complexity items have approved design docs</criterion>
+  <criterion>All artifacts saved using templates</criterion>
+</success_criteria>
+
+<begin>
+  Read `.specs-fire/state.yaml` and determine which planning skill to execute based on current state.
+</begin>