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

package/flows/fire/agents/planner/skills/work-item-decompose/SKILL.md

@@ -0,0 +1,165 @@
+---
+name: work-item-decompose
+description: Break an intent into discrete, executable work items with complexity assessment and dependency validation.
+version: 1.0.0
+---
+
+<objective>
+Break an intent into discrete, executable work items.
+</objective>
+
+<triggers>
+  - Intent exists without work items
+  - User wants to plan execution
+</triggers>
+
+<degrees_of_freedom>
+  **MEDIUM** — Follow decomposition patterns but adapt to the specific intent.
+</degrees_of_freedom>
+
+<llm critical="true">
+  <mandate>Each work item MUST be completable in a single run</mandate>
+  <mandate>Each work item MUST have clear acceptance criteria</mandate>
+  <mandate>Dependencies MUST be explicit and validated</mandate>
+</llm>
+
+<flow>
+  <step n="1" title="Load Intent">
+    <action>Read intent brief from .specs-fire/intents/{intent-id}/brief.md</action>
+    <action>Understand goal, users, success criteria</action>
+  </step>
+
+  <step n="2" title="Identify Deliverables">
+    <action>Break intent into discrete deliverables</action>
+    <action>Each deliverable should be independently valuable</action>
+
+    <guidelines>
+      - Prefer vertical slices over horizontal layers
+      - Start with foundation pieces (models, schemas)
+      - End with integration pieces (API, UI)
+      - Keep each item focused on ONE concern
+    </guidelines>
+  </step>
+
+  <step n="3" title="Assess Complexity">
+    <action>For each work item, assess RAW complexity:</action>
+
+    <complexity level="low">
+      - Single file or few files
+      - Well-understood pattern
+      - No external dependencies
+      - Examples: bug fix, config change, simple utility
+    </complexity>
+
+    <complexity level="medium">
+      - Multiple files
+      - Standard patterns with some decisions
+      - May touch existing code
+      - Examples: new endpoint, new component, feature addition
+    </complexity>
+
+    <complexity level="high">
+      - Architectural decisions required
+      - Security or data implications
+      - Core system changes
+      - Examples: auth system, payment flow, database migration
+    </complexity>
+  </step>
+
+  <step n="3b" title="Apply Autonomy Bias">
+    <action>Read workspace.autonomy_bias from state.yaml</action>
+    <action>Apply bias to determine final execution mode:</action>
+
+    <bias_table>
+      | Raw Complexity | autonomous | balanced | controlled |
+      |----------------|------------|----------|------------|
+      | low            | autopilot  | autopilot| confirm    |
+      | medium         | autopilot  | confirm  | validate   |
+      | high           | confirm    | validate | validate   |
+    </bias_table>
+
+    <note>
+      This allows user preference to shift thresholds:
+      - autonomous: trusts AI more, fewer checkpoints
+      - balanced: standard behavior (default)
+      - controlled: more human oversight
+    </note>
+  </step>
+
+  <step n="4" title="Define Acceptance Criteria">
+    <action>For each work item, define:</action>
+    <substep>What must be true when complete</substep>
+    <substep>How to verify it works</substep>
+    <substep>Any edge cases to handle</substep>
+  </step>
+
+  <step n="5" title="Validate Dependencies">
+    <action>Check for circular dependencies</action>
+    <action>Ensure dependencies exist or will be created first</action>
+    <action>Order work items by dependency</action>
+
+    <check if="circular dependency detected">
+      <output>
+        Warning: Circular dependency detected between {item-a} and {item-b}.
+        Suggest splitting into smaller items or reordering.
+      </output>
+    </check>
+  </step>
+
+  <step n="6" title="Present Plan">
+    <output>
+      ## Work Items for "{intent-title}"
+
+      **Total**: {count} work items
+      **Estimated**: {low} autopilot, {medium} confirm, {high} validate
+
+      **Work Item Details**:
+
+      {for each item}
+      {n}. **{title}** ({mode}) — {description}
+      {/for}
+
+      ---
+
+      Approve this plan? [Y/n/edit]
+    </output>
+  </step>
+
+  <step n="7" title="Save Work Items">
+    <check if="approved">
+      <action>Create .specs-fire/intents/{intent-id}/work-items/</action>
+      <action>For each work item, generate using template: templates/work-item.md.hbs</action>
+      <action>Save each to: .specs-fire/intents/{intent-id}/work-items/{work-item-id}.md</action>
+      <action>Update state.yaml with work items list</action>
+    </check>
+  </step>
+
+  <step n="8" title="Transition">
+    <output>
+      **{count} work items created** for "{intent-title}".
+
+      ---
+
+      Ready to plan execution scope? [Y/n]
+    </output>
+    <check if="response == y">
+      <route_to>builder-agent (run-plan)</route_to>
+    </check>
+  </step>
+</flow>
+
+<output_artifacts>
+  | Artifact | Location | Template |
+  |----------|----------|----------|
+  | Work Item | `.specs-fire/intents/{intent-id}/work-items/{id}.md` | `./templates/work-item.md.hbs` |
+</output_artifacts>
+
+<success_criteria>
+  <criterion>Intent decomposed into discrete work items</criterion>
+  <criterion>Each work item has clear acceptance criteria</criterion>
+  <criterion>Complexity assessed for each item</criterion>
+  <criterion>Autonomy bias applied to determine modes</criterion>
+  <criterion>Dependencies validated (no circular dependencies)</criterion>
+  <criterion>Work items saved to correct locations</criterion>
+  <criterion>State.yaml updated with work items list</criterion>
+</success_criteria>

package/flows/fire/agents/planner/skills/work-item-decompose/templates/work-item.md.hbs

@@ -0,0 +1,40 @@
+---
+id: {{id}}
+title: {{title}}
+intent: {{intent}}
+complexity: {{complexity}}
+mode: {{mode}}
+status: {{status}}
+depends_on: [{{#each depends_on}}{{this}}{{#unless @last}}, {{/unless}}{{/each}}]
+created: {{created}}
+---
+
+# Work Item: {{title}}
+
+## Description
+
+{{description}}
+
+## Acceptance Criteria
+
+{{#each acceptance_criteria}}
+- [ ] {{this}}
+{{/each}}
+
+## Technical Notes
+
+{{#if technical_notes}}
+{{technical_notes}}
+{{else}}
+(none)
+{{/if}}
+
+## Dependencies
+
+{{#if depends_on}}
+{{#each depends_on}}
+- {{this}}
+{{/each}}
+{{else}}
+(none)
+{{/if}}

package/flows/fire/commands/fire-builder.md

@@ -0,0 +1,56 @@
+---
+description: FIRE Builder Agent - executes work items and generates walkthroughs
+---
+
+# Activate FIRE Builder
+
+**Command**: `/specsmd-fire-builder`
+
+---
+
+## Activation
+
+You are now the **FIRE Builder Agent** for specsmd.
+
+**IMMEDIATELY** read and adopt the persona from:
+→ `.specsmd/fire/agents/builder/agent.md`
+
+---
+
+## Critical First Steps
+
+1. **Read Config**: `.specsmd/fire/fire-config.yaml`
+2. **Read State**: `.specs-fire/state.yaml`
+3. **Determine Mode**:
+   - Active run exists → Resume execution
+   - Pending work items → Start next work item
+   - No work items → Route back to Planner
+
+---
+
+## Your Skills
+
+- **Run Execute**: `.specsmd/fire/agents/builder/skills/run-execute/SKILL.md` → Execute work item
+- **Walkthrough Generate**: `.specsmd/fire/agents/builder/skills/walkthrough-generate/SKILL.md` → Generate walkthrough
+- **Run Status**: `.specsmd/fire/agents/builder/skills/run-status/SKILL.md` → Show run status
+
+---
+
+## Execution Modes
+
+- **Autopilot**: 0 checkpoints (low complexity)
+- **Confirm**: 1 checkpoint (medium complexity)
+- **Validate**: 2 checkpoints (high complexity)
+
+---
+
+## Routing Targets
+
+- **Back to Orchestrator**: `/specsmd-fire`
+- **To Planner**: `/specsmd-fire-planner`
+
+---
+
+## Begin
+
+Activate now. Read your agent definition and start building.

package/flows/fire/commands/fire-planner.md

@@ -0,0 +1,48 @@
+---
+description: FIRE Planner Agent - captures intents and decomposes into work items
+---
+
+# Activate FIRE Planner
+
+**Command**: `/specsmd-fire-planner`
+
+---
+
+## Activation
+
+You are now the **FIRE Planner Agent** for specsmd.
+
+**IMMEDIATELY** read and adopt the persona from:
+→ `.specsmd/fire/agents/planner/agent.md`
+
+---
+
+## Critical First Steps
+
+1. **Read Config**: `.specsmd/fire/fire-config.yaml`
+2. **Read State**: `.specs-fire/state.yaml`
+3. **Determine Mode**:
+   - No active intent → `intent-capture` skill
+   - Intent without work items → `work-item-decompose` skill
+   - High-complexity work item → `design-doc-generate` skill
+
+---
+
+## Your Skills
+
+- **Intent Capture**: `.specsmd/fire/agents/planner/skills/intent-capture/SKILL.md` → Capture new intent
+- **Work Item Decompose**: `.specsmd/fire/agents/planner/skills/work-item-decompose/SKILL.md` → Break into work items
+- **Design Doc Generate**: `.specsmd/fire/agents/planner/skills/design-doc-generate/SKILL.md` → Create design doc
+
+---
+
+## Routing Targets
+
+- **Back to Orchestrator**: `/specsmd-fire`
+- **To Builder**: `/specsmd-fire-builder`
+
+---
+
+## Begin
+
+Activate now. Read your agent definition and start planning.

package/flows/fire/commands/fire.md

@@ -0,0 +1,46 @@
+---
+description: FIRE orchestrator - Fast Intent-Run Engineering main entry point
+---
+
+# Activate FIRE
+
+**Command**: `/specsmd-fire`
+
+---
+
+## Activation
+
+You are now the **FIRE Orchestrator** for specsmd.
+
+**IMMEDIATELY** read and adopt the persona from:
+→ `.specsmd/fire/agents/orchestrator/agent.md`
+
+---
+
+## Critical First Steps
+
+1. **Read Config**: `.specsmd/fire/fire-config.yaml`
+2. **Check Initialization**: Verify `.specs-fire/state.yaml` exists
+3. **If NOT initialized** → Execute `project-init` skill
+4. **If initialized** → Execute `route` skill to determine next action
+
+---
+
+## Your Skills
+
+- **Project Init**: `.specsmd/fire/agents/orchestrator/skills/project-init/SKILL.md` → Initialize new project
+- **Route**: `.specsmd/fire/agents/orchestrator/skills/route/SKILL.md` → Route to appropriate agent
+- **Status**: `.specsmd/fire/agents/orchestrator/skills/status/SKILL.md` → Show project status
+
+---
+
+## Routing Targets
+
+- **Planning**: Planner Agent → `/specsmd-fire-planner`
+- **Building**: Builder Agent → `/specsmd-fire-builder`
+
+---
+
+## Begin
+
+Activate now. Read your agent definition and start the orchestration process.

package/flows/fire/memory-bank.yaml

@@ -0,0 +1,223 @@
+# FIRE Flow Configuration
+# Fast Intent-Run Engineering - Simplified AI-native development
+
+# FIRE Flow Version (used by migrate skill to detect outdated projects)
+version: "0.1.8"
+
+# Artifact folder (created at project initialization)
+artifact_root: ".specs-fire"
+
+# Structure created at project initialization
+structure:
+  - path: intents/
+    description: "High-level objectives that deliver user value"
+  - path: runs/
+    description: "Execution logs and walkthroughs per run"
+  - path: standards/
+    description: "Project standards (constitution, tech-stack, coding-standards, testing-standards)"
+
+# ─────────────────────────────────────────────────────────────────────────────────
+# HIERARCHICAL STANDARDS (Monorepo Support)
+# ─────────────────────────────────────────────────────────────────────────────────
+#
+# Standards can exist at root level AND at module level for monorepos.
+# Resolution rules:
+#   - constitution.md: ALWAYS from root, NEVER overridden by modules
+#   - All other standards: Override semantics (module overrides root if exists)
+#
+# Example monorepo structure:
+#   .specs-fire/standards/              <- Root standards (defaults)
+#   packages/api/.specs-fire/standards/ <- API module overrides
+#   apps/mobile/.specs-fire/standards/  <- Mobile module overrides
+#
+# The file system IS the registry - presence of .specs-fire/standards/ defines a scope.
+
+# Central state file (FIRE's source of truth)
+state:
+  path: ".specs-fire/state.yaml"
+  description: "Central state tracking for all FIRE operations"
+  sections:
+    project:
+      - name: "Project name"
+      - description: "Project description"
+      - created: "ISO 8601 timestamp"
+      - fire_version: "FIRE flow version at project init (e.g., 0.1.8)"
+    workspace:
+      - type: "greenfield | brownfield"
+      - structure: "monolith | monorepo | multi-part"
+      - autonomy_bias: "autonomous | balanced | controlled"
+      - run_scope_preference: "single | batch | wide (learned from history)"
+      - run_scope_history: "List of recent scope choices for learning"
+      - scanned_at: "ISO 8601 timestamp (brownfield)"
+      - parts: "List of project parts (monorepo)"
+    intents:
+      - id: "Intent identifier"
+      - title: "Intent title"
+      - status: "pending | in_progress | completed"
+      - work_items: "List of work items"
+    active_run:
+      - id: "Current run ID"
+      - scope: "single | batch | wide"
+      - work_items: "List of work items in this run"
+      - current_item: "Work item currently being executed"
+      - started: "ISO 8601 timestamp"
+    runs:
+      - completed: "List of completed runs with id, work_item, intent, completed timestamp"
+
+# Data Conventions
+conventions:
+  timestamps:
+    format: "ISO 8601 with time and timezone"
+    pattern: "YYYY-MM-DDTHH:MM:SSZ"
+    example: "2026-01-19T10:30:00Z"
+
+# Naming Conventions
+naming:
+  intents:
+    format: "{id}"
+    example: "user-authentication"
+    note: "Kebab-case, descriptive name"
+
+  work_items:
+    format: "{id}"
+    example: "login-endpoint"
+    note: "Kebab-case, action-oriented name"
+
+  runs:
+    format: "run-{NNN}/"
+    example: "run-001/"
+    note: "Sequential 3-digit number, folder per run"
+    contents:
+      - "plan.md"         # Approved implementation plan (confirm/validate modes)
+      - "run.md"          # Run log
+      - "test-report.md"  # Test results and coverage
+      - "walkthrough.md"  # Implementation walkthrough
+
+# Schema Definition (Source of Truth for Agents)
+schema:
+  state: ".specs-fire/state.yaml"
+  intents: ".specs-fire/intents/{intent-id}/"
+  intent-brief: ".specs-fire/intents/{intent-id}/brief.md"
+  work-items: ".specs-fire/intents/{intent-id}/work-items/"
+  work-item: ".specs-fire/intents/{intent-id}/work-items/{work-item-id}.md"
+  runs: ".specs-fire/runs/"
+  run-folder: ".specs-fire/runs/{run-id}/"
+  plan: ".specs-fire/runs/{run-id}/plan.md"
+  run-log: ".specs-fire/runs/{run-id}/run.md"
+  test-report: ".specs-fire/runs/{run-id}/test-report.md"
+  walkthrough: ".specs-fire/runs/{run-id}/walkthrough.md"
+
+  # Root Standards
+  standards: ".specs-fire/standards/"
+  constitution: ".specs-fire/standards/constitution.md"
+  tech-stack: ".specs-fire/standards/tech-stack.md"
+  coding-standards: ".specs-fire/standards/coding-standards.md"
+  testing-standards: ".specs-fire/standards/testing-standards.md"
+  system-architecture: ".specs-fire/standards/system-architecture.md"
+
+  # Module Standards (Monorepo) - paths relative to module root
+  module-standards: "{module-path}/.specs-fire/standards/"
+  module-tech-stack: "{module-path}/.specs-fire/standards/tech-stack.md"
+  module-coding-standards: "{module-path}/.specs-fire/standards/coding-standards.md"
+  module-testing-standards: "{module-path}/.specs-fire/standards/testing-standards.md"
+
+  # Agent Ownership
+  ownership:
+    orchestrator: [state]
+    planner: [intents, work-items, state]
+    builder: [runs, state]
+
+# ─────────────────────────────────────────────────────────────────────────────────
+# STANDARDS BEHAVIOR
+# ─────────────────────────────────────────────────────────────────────────────────
+
+standards_behavior:
+  constitution:
+    inheritance: always
+    override: never
+    description: |
+      Universal policies (git workflow, PR process, security).
+      ALWAYS loaded from root. Modules cannot override.
+
+  tech-stack:
+    inheritance: fallback
+    override: allowed
+    description: |
+      If module has tech-stack.md, use it.
+      Otherwise inherit from nearest ancestor (ultimately root).
+
+  coding-standards:
+    inheritance: fallback
+    override: allowed
+
+  testing-standards:
+    inheritance: fallback
+    override: allowed
+
+  system-architecture:
+    inheritance: fallback
+    override: allowed
+
+# Execution Modes
+execution_modes:
+  autopilot:
+    checkpoints: 0
+    complexity: low
+    description: "Direct execution, walkthrough generated after"
+
+  confirm:
+    checkpoints: 1
+    complexity: medium
+    description: "Plan shown, user confirms, then execution"
+
+  validate:
+    checkpoints: 2
+    complexity: high
+    description: "Design doc review, then plan confirmation, then execution"
+
+# Work Item Complexity Mapping (default, when autonomy_bias = balanced)
+complexity_modes:
+  low: autopilot
+  medium: confirm
+  high: validate
+
+# Autonomy Bias - Shifts complexity→mode thresholds
+# User preference captured at project init, stored in workspace.autonomy_bias
+autonomy_bias:
+  autonomous:
+    description: "AI executes more freely, fewer checkpoints"
+    mapping:
+      low: autopilot
+      medium: autopilot   # shifted down
+      high: confirm       # shifted down
+  balanced:
+    description: "Standard checkpoints based on complexity"
+    mapping:
+      low: autopilot
+      medium: confirm
+      high: validate
+  controlled:
+    description: "More human oversight, more checkpoints"
+    mapping:
+      low: confirm        # shifted up
+      medium: validate    # shifted up
+      high: validate
+
+# Run Scope - How many work items to execute in a single run
+# Learned from user choices, stored in workspace.run_scope_preference
+run_scope:
+  single:
+    description: "One work item per run, most controlled"
+    grouping: "Each item in its own run"
+  batch:
+    description: "Group items by mode, respect dependencies"
+    grouping: "Autopilot together, confirm together, etc."
+  wide:
+    description: "Maximum items per run, minimal interruption"
+    grouping: "All compatible items together"
+
+# Run scope history entry format
+run_scope_history_entry:
+  choice: "single | batch | wide"
+  items_count: "Number of items in the run"
+  timestamp: "ISO 8601 timestamp"