specsmd 0.0.0-dev.6 → 0.0.0-dev.60

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

@@ -0,0 +1,77 @@
+---
+run: {{run_id}}
+work_item: {{work_item_id}}
+intent: {{intent_id}}
+generated: {{generated}}
+mode: {{mode}}
+---
+
+# Implementation Walkthrough: {{title}}
+
+## Summary
+
+{{summary}}
+
+## 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}}
+
+## 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}}
+
+---
+*Generated by FIRE Run {{run_id}}*

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

@@ -0,0 +1,113 @@
+# FIRE Orchestrator Agent
+
+You are the **Orchestrator Agent** for FIRE (Fast Intent-Run Engineering).
+
+---
+
+## Persona
+
+- **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.
+
+---
+
+## On Activation
+
+When user invokes this agent:
+
+1. Read `.specsmd/fire/fire-config.yaml` for schema
+2. Check if `.specs-fire/state.yaml` exists
+3. **If NOT initialized** (new project):
+   - Execute `project-init` skill to set up workspace
+4. **If initialized**:
+   - Read `.specs-fire/state.yaml` for current state
+   - Execute `route` skill to determine next action
+
+---
+
+## 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 |
+
+---
+
+## Routing Logic
+
+```text
+[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)
+```
+
+---
+
+## State Management
+
+The orchestrator is responsible for maintaining `state.yaml`:
+
+```yaml
+project:
+  name: "project-name"
+  framework: fire-v1
+
+workspace:
+  type: brownfield
+  structure: monolith
+  default_mode: confirm
+
+intents:
+  - id: user-auth
+    status: in_progress
+    work_items:
+      - id: login-endpoint
+        status: completed
+      - id: session-management
+        status: pending
+
+active_run: null  # or { id: run-001, work_item: session-management }
+```
+
+---
+
+## Handoff Protocol
+
+When routing to another agent, provide context:
+
+**To Planner:**
+```
+Routing to Planner Agent.
+Context: No active intent. Ready for new intent capture.
+```
+
+**To Builder:**
+```
+Routing to Builder Agent.
+Context: Work item "session-management" ready for execution.
+Mode: confirm (1 checkpoint)
+```
+
+---
+
+## Begin
+
+Read `.specs-fire/state.yaml` and execute the `route` skill to determine the user's next action.

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

@@ -0,0 +1,150 @@
+# Skill: Project Init
+
+Initialize a new FIRE project by detecting workspace type and setting up standards.
+
+---
+
+## Trigger
+
+- User runs `/fire` on uninitialized project
+- No `.specs-fire/state.yaml` exists
+
+---
+
+## Workflow
+
+```xml
+<skill name="project-init">
+
+  <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>
+    <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="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)</action>
+    <action>Generate standards using templates:</action>
+    <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>
+  </step>
+
+  <step n="6" title="Complete">
+    <output>
+      FIRE initialized!
+
+      Structure created:
+      ```
+      .specs-fire/
+      ├── state.yaml
+      ├── intents/
+      ├── runs/
+      └── standards/
+          ├── tech-stack.md
+          ├── coding-standards.md
+          ├── testing-standards.md
+          └── system-architecture.md
+      ```
+
+      Ready to capture your first intent.
+      What do you want to build?
+    </output>
+    <route-to>planner-agent (intent-capture)</route-to>
+  </step>
+
+</skill>
+```
+
+---
+
+## Output
+
+| Artifact | Location | Template |
+|----------|----------|----------|
+| State | `.specs-fire/state.yaml` | — |
+| 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` |

package/flows/fire/agents/orchestrator/skills/project-init/templates/coding-standards.md.hbs

@@ -0,0 +1,149 @@
+# Coding Standards
+
+## Overview
+
+{{overview}}
+
+## Code Formatting
+
+**Tool**: {{formatter}}
+**Config**: {{formatter_config}}
+**Enforcement**: {{formatter_enforcement}}
+
+### Key Settings
+
+{{#each formatter_settings}}
+- **{{this.setting}}**: {{this.value}}
+{{/each}}
+
+## Linting
+
+**Tool**: {{linter}}
+**Base Config**: {{linter_base}}
+**Strictness**: {{linter_strictness}}
+
+### Key Rules
+
+{{#each linter_rules}}
+- `{{this.rule}}`: {{this.setting}} — {{this.rationale}}
+{{/each}}
+
+## Naming Conventions
+
+### Variables and Functions
+
+| Element | Convention | Example |
+|---------|------------|---------|
+{{#each naming_conventions}}
+| {{this.element}} | {{this.convention}} | `{{this.example}}` |
+{{/each}}
+
+### Files and Folders
+
+{{#each file_naming}}
+- **{{this.type}}**: {{this.convention}} (e.g., `{{this.example}}`)
+{{/each}}
+
+## File Organization
+
+### Project Structure
+
+```
+{{project_structure}}
+```
+
+### Conventions
+
+{{#each organization_conventions}}
+- **{{this.item}}**: {{this.convention}}
+{{/each}}
+
+## Import Order
+
+```{{language}}
+{{import_order_example}}
+```
+
+**Rules**:
+{{#each import_rules}}
+- {{this}}
+{{/each}}
+
+## Error Handling
+
+### Pattern
+
+**Approach**: {{error_pattern}}
+
+### Guidelines
+
+{{#each error_guidelines}}
+- {{this}}
+{{/each}}
+
+### Example
+
+```{{language}}
+{{error_example}}
+```
+
+## Logging
+
+**Tool**: {{logging_tool}}
+**Format**: {{logging_format}}
+
+### Log Levels
+
+| Level | Usage |
+|-------|-------|
+{{#each log_levels}}
+| {{this.level}} | {{this.usage}} |
+{{/each}}
+
+### Guidelines
+
+**Always log**:
+{{#each log_always}}
+- {{this}}
+{{/each}}
+
+**Never log**:
+{{#each log_never}}
+- {{this}}
+{{/each}}
+
+## Comments and Documentation
+
+### When to Comment
+
+{{#each comment_guidelines}}
+- {{this}}
+{{/each}}
+
+### Documentation Format
+
+**Functions**: {{doc_format_functions}}
+**Classes**: {{doc_format_classes}}
+
+## Code Patterns
+
+### Preferred Patterns
+
+{{#each preferred_patterns}}
+#### {{this.name}}
+
+{{this.description}}
+
+```{{../language}}
+{{this.example}}
+```
+{{/each}}
+
+### Anti-Patterns to Avoid
+
+{{#each anti_patterns}}
+- **{{this.name}}**: {{this.why}}
+{{/each}}
+
+---
+*Generated by FIRE project-init*

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 FIRE project-init*

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 FIRE project-init*