specsmd 0.0.0-dev.7 → 0.0.0-dev.71

package/flows/fire/agents/orchestrator/skills/project-init/templates/system-architecture.md.hbs

@@ -0,0 +1,101 @@
+# System Architecture
+
+## Overview
+
+{{overview}}
+
+## System Context
+
+{{system_context}}
+
+### Context Diagram
+
+```
+{{context_diagram}}
+```
+
+### Users
+
+{{#each users}}
+- **{{this.name}}**: {{this.description}}
+{{/each}}
+
+### External Systems
+
+{{#each external_systems}}
+- **{{this.name}}**: {{this.purpose}}
+{{/each}}
+
+## Architecture Pattern
+
+**Pattern**: {{architecture_pattern}}
+**Rationale**: {{architecture_rationale}}
+
+## Component Architecture
+
+### Components
+
+{{#each components}}
+#### {{this.name}}
+
+- **Purpose**: {{this.purpose}}
+- **Responsibilities**: {{this.responsibilities}}
+- **Dependencies**: {{this.dependencies}}
+{{/each}}
+
+### Component Diagram
+
+```
+{{component_diagram}}
+```
+
+## Data Flow
+
+{{data_flow_description}}
+
+```
+{{data_flow_diagram}}
+```
+
+## Technology Stack
+
+| Layer | Technology | Purpose |
+|-------|------------|---------|
+{{#each tech_stack}}
+| {{this.layer}} | {{this.technology}} | {{this.purpose}} |
+{{/each}}
+
+## Non-Functional Requirements
+
+### Performance
+
+{{#each nfr_performance}}
+- **{{this.metric}}**: {{this.target}}
+{{/each}}
+
+### Security
+
+{{#each nfr_security}}
+- {{this}}
+{{/each}}
+
+### Scalability
+
+{{scalability_approach}}
+
+## Constraints
+
+{{#each constraints}}
+- {{this}}
+{{/each}}
+
+## Key Decisions
+
+| Decision | Choice | Rationale |
+|----------|--------|-----------|
+{{#each key_decisions}}
+| {{this.decision}} | {{this.choice}} | {{this.rationale}} |
+{{/each}}
+
+---
+*Generated by specs.md - fabriqa.ai FIRE Flow*

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/project-migrate/SKILL.md

@@ -0,0 +1,234 @@
+---
+name: project-migrate
+description: Migrate existing FIRE project to latest version. Adds constitution.md, updates schema, and optionally detects monorepo modules.
+version: 1.0.0
+---
+
+<objective>
+Upgrade an existing FIRE project to the latest version, adding new features
+(constitution.md, hierarchical standards) while preserving all existing work.
+</objective>
+
+<triggers>
+  - User runs `/fire-migrate`
+  - Orchestrator detects outdated project version
+</triggers>
+
+<principles critical="true">
+  <principle>NEVER delete or modify existing intents/work-items/runs</principle>
+  <principle>Create backup before any changes</principle>
+  <principle>Migration is idempotent — safe to run multiple times</principle>
+  <principle>Show changes before applying</principle>
+</principles>
+
+<flow>
+  <step n="1" title="Detect Current Version">
+    <action>Check if .specs-fire/ exists</action>
+    <check if="no .specs-fire/">
+      <output>Not a FIRE project. Use /fire to initialize.</output>
+      <exit/>
+    </check>
+
+    <action>Read .specs-fire/state.yaml</action>
+    <action>Check project.fire_version field</action>
+    <action>Read FIRE flow version from memory-bank.yaml</action>
+
+    <version_detection>
+      | Check | Meaning |
+      |-------|---------|
+      | project.fire_version missing | Pre-0.1.8 project |
+      | project.fire_version < current | Needs migration |
+      | project.fire_version == current | Up to date |
+
+      Also check for feature indicators:
+      | Missing Feature | Added In |
+      |-----------------|----------|
+      | constitution.md | 0.1.8 |
+      | workspace.structure | 0.1.8 |
+    </version_detection>
+
+    <check if="already up to date">
+      <output>Project is already at the latest version ({current_version}). No migration needed.</output>
+      <exit/>
+    </check>
+
+    <output>
+      Current version: {project_fire_version or "pre-0.1.8"}
+      Latest version: {fire_flow_version}
+      Migration required.
+    </output>
+  </step>
+
+  <step n="2" title="Analyze Migration Scope">
+    <action>Determine what needs to be migrated:</action>
+
+    <check_constitution>
+      Does .specs-fire/standards/constitution.md exist?
+      If no → needs_constitution = true
+    </check_constitution>
+
+    <check_schema>
+      Does state.yaml have workspace.structure field?
+      If no → needs_schema_update = true
+    </check_schema>
+
+    <check_monorepo>
+      Is this actually a monorepo? Check for:
+      - nx.json, turbo.json, pnpm-workspace.yaml, lerna.json
+      - package.json with "workspaces"
+      - Multiple package/dependency manifests
+      If detected → is_monorepo = true
+    </check_monorepo>
+
+    <output>
+      Migration Plan:
+      ┌─────────────────────────────────────────────────────┐
+      │ Changes to be made:                                 │
+      {{#if needs_constitution}}
+      │ ✓ Create constitution.md (universal policies)      │
+      {{/if}}
+      {{#if needs_schema_update}}
+      │ ✓ Update state.yaml schema                         │
+      {{/if}}
+      {{#if is_monorepo}}
+      │ ? Monorepo detected — offer module standards       │
+      {{/if}}
+      │                                                     │
+      │ Will NOT change:                                    │
+      │ • Existing intents and work items                   │
+      │ • Existing runs and logs                            │
+      │ • Existing standards (only add new ones)            │
+      └─────────────────────────────────────────────────────┘
+    </output>
+  </step>
+
+  <step n="3" title="Create Backup">
+    <action>Create backup: cp -r .specs-fire .specs-fire-backup-{timestamp}</action>
+    <output>Backup created: .specs-fire-backup-{timestamp}</output>
+  </step>
+
+  <step n="4" title="Confirm Migration">
+    <ask>
+      Ready to migrate. Backup saved.
+
+      Proceed with migration? [Y/n]
+    </ask>
+  </step>
+
+  <step n="5" title="Add Constitution" if="needs_constitution">
+    <ask>
+      How should I create constitution.md?
+
+      [a] Auto-generate — analyze project (git, CI, existing patterns)
+      [d] Default — use standard template
+      [c] Custom — I'll provide the content
+    </ask>
+
+    <check if="response == a">
+      <action>Analyze project for constitution content:</action>
+      <substep>Check .gitignore, CI config for workflow hints</substep>
+      <substep>Check existing PR templates, CONTRIBUTING.md</substep>
+      <substep>Infer commit style from git log</substep>
+      <action>Generate constitution.md from findings</action>
+    </check>
+
+    <check if="response == d">
+      <action>Create constitution.md from default template</action>
+    </check>
+
+    <check if="response == c">
+      <ask>Please describe your key policies (git workflow, PR process, security).</ask>
+      <action>Generate constitution.md from input</action>
+    </check>
+
+    <action>Write to .specs-fire/standards/constitution.md</action>
+    <output>Created: .specs-fire/standards/constitution.md</output>
+  </step>
+
+  <step n="6" title="Update State Schema" if="needs_schema_update">
+    <action>Read current state.yaml</action>
+    <action>Add missing fields with defaults:</action>
+    <substep>project.fire_version: "{current_fire_flow_version}"</substep>
+    <substep>workspace.structure: "monolith" (or "monorepo" if detected)</substep>
+    <action>Write updated state.yaml (preserve all existing data)</action>
+    <output>Updated: .specs-fire/state.yaml</output>
+  </step>
+
+  <step n="7" title="Monorepo Module Setup" if="is_monorepo" optional="true">
+    <action>Discover modules (same as project-init):</action>
+    <substep>Check workspace config for project list</substep>
+    <substep>Scan packages/*, apps/*, services/*, libs/*</substep>
+    <substep>Analyze each module's tech stack</substep>
+
+    <ask>
+      This appears to be a monorepo. Found {{module_count}} modules:
+
+      {{#each modules}}
+      • {{path}} ({{language}})
+      {{/each}}
+
+      Create module-specific standards?
+      [y] Yes — create for all modules
+      [s] Select — choose which modules
+      [n] No — skip for now
+    </ask>
+
+    <check if="response == y or response == s">
+      <action>For each selected module:</action>
+      <substep>Create {module}/.specs-fire/standards/</substep>
+      <substep>Generate tech-stack.md with detected settings</substep>
+    </check>
+  </step>
+
+  <step n="8" title="Verify Migration">
+    <action>Verify migration completed:</action>
+    <substep>Read state.yaml — valid YAML?</substep>
+    <substep>Check new files exist</substep>
+    <substep>Ensure no existing files corrupted</substep>
+
+    <check if="verification fails">
+      <output>Migration failed. Restoring from backup...</output>
+      <action>rm -rf .specs-fire && mv .specs-fire-backup-{timestamp} .specs-fire</action>
+      <output>Restored. Please report this issue.</output>
+      <exit status="error"/>
+    </check>
+  </step>
+
+  <step n="9" title="Report">
+    <output>
+      Migration complete!
+
+      Changes made:
+      {{#each changes_made}}
+      ✓ {{description}}
+      {{/each}}
+
+      Backup preserved at: .specs-fire-backup-{timestamp}
+      (Delete once you've verified everything works)
+
+      New features available:
+      • Constitution: Universal policies in constitution.md
+      {{#if is_monorepo}}
+      • Monorepo: Module-specific standards supported
+      {{/if}}
+    </output>
+  </step>
+</flow>
+
+<safety_guarantees>
+  <guarantee>Backup created before any changes</guarantee>
+  <guarantee>Idempotent — running twice is safe</guarantee>
+  <guarantee>Verify after — validates migration succeeded</guarantee>
+  <guarantee>Restore on failure — automatic rollback</guarantee>
+  <guarantee>Never deletes — only adds, never removes</guarantee>
+</safety_guarantees>
+
+<success_criteria>
+  <criterion>Current version detected correctly</criterion>
+  <criterion>Backup created before changes</criterion>
+  <criterion>constitution.md added if missing</criterion>
+  <criterion>state.yaml schema updated if needed</criterion>
+  <criterion>Monorepo modules detected and offered (if applicable)</criterion>
+  <criterion>Migration verified successfully</criterion>
+  <criterion>No existing data lost or corrupted</criterion>
+</success_criteria>

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

@@ -0,0 +1,141 @@
+---
+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>
+
+    <file_system_scan critical="true">
+      Use these EXACT glob patterns:
+
+      <pattern purpose="Find intent briefs">
+        .specs-fire/intents/*/brief.md
+      </pattern>
+
+      <pattern purpose="Find work items">
+        .specs-fire/intents/*/work-items/*.md
+      </pattern>
+
+      Work items are {work-item-id}.md files directly in work-items/ folder.
+    </file_system_scan>
+
+    <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>