Agent skill

run-execute

Execute work items based on their assigned mode (autopilot, confirm, validate). Supports single-item and multi-item (batch/wide) runs.

View SKILL.md on GitHub Repository
Stars 99
Forks 9

Install this agent skill to your Project

npx add-skill https://github.com/fabriqaai/specs.md/tree/main/src/flows/fire/agents/builder/skills/run-execute

SKILL.md

<progress_display> Show current position in workflow:

text
### Run Progress
- [ ] Run initialized (init-run.cjs)
- [ ] Context loaded
- [ ] Plan generated  ← {current_step}
- [ ] Implementation
- [ ] Tests passing
- [ ] Code review
- [ ] Run completed (complete-run.cjs)
- [ ] Walkthrough generated

Update markers as you progress: [x] = done, ← current = active step </progress_display>

Package Purpose Install Command
yaml Parse/stringify state.yaml npm install yaml

<resume_detection critical="true"> Before starting execution, check if resuming an interrupted run:

<check if="runs.active is empty">
  <goto step="1">No active run, start fresh</goto>
</check>

<check if="runs.active has entries">
  <action>Load active run from state.yaml runs.active[0]</action>
  <action>Read scope (single/batch/wide) and work_items array</action>

  <substep n="0a" title="Enumerate Work Item Status">
    <action>For EACH work item in runs.active[0].work_items, classify by status:</action>
    <action>Build status summary from state.yaml (NOT from artifact files):</action>
    <format>
      [DONE] {item-id} — completed
      [WORKING] {item-id} (phase: {current_phase}) — in_progress
      [PENDING] {item-id} — pending
    </format>
    <action>Count: completed={X}, in_progress={Y}, pending={Z}</action>
  </substep>

  <substep n="0b" title="Determine Resume Point for Current Item">
    <action>Get current_item from state.yaml</action>
    <action>Read current_phase from the current item's entry in work_items</action>

    <determine_resume_point>
      Use current_phase from state.yaml to determine resume point:

      | current_phase | Resume At |
      |---------------|-----------|
      | plan (or unset) | Step 3 (Generate Plan) |
      | execute | Step 5 (Implementation) |
      | test | Step 6 (Run Tests) |
      | review | Step 6b (Code Review) |
    </determine_resume_point>
  </substep>

  <llm critical="true">
    <mandate>NEVER call --complete-item for items with status "completed" — they are already done</mandate>
    <mandate>NEVER re-execute steps (plan, implement, test) for completed items</mandate>
    <mandate>ONLY work on the current_item identified in state.yaml</mandate>
    <mandate>Use current_phase from state.yaml — do NOT infer phase from artifact file existence</mandate>
  </llm>

  <output>
    Resuming run {run-id} ({scope}) for work item {current_item}.
    Mode: {mode}
    Phase: {current_phase}
    Status: {completed_count} done, {in_progress_count} working, {pending_count} pending
    Resuming at: Step {step_number}
  </output>
</check>

<degrees_of_freedom> Varies by mode:

  • Autopilot: LOW — Execute standard patterns decisively
  • Confirm: MEDIUM — Present plan, adjust based on feedback
  • Validate: LOW — Follow approved design precisely </degrees_of_freedom>

<artifact_timing critical="true"> Artifacts MUST be created at these points:

Artifact When Created Created By
run.md Start of run init-run.cjs script
plan.md BEFORE implementation (Step 4) Agent using template
test-report.md AFTER tests pass (Step 6) Agent using template
review-report.md AFTER test report (Step 6b) code-review skill
walkthrough.md After run completes (Step 8) walkthrough-generate skill

For batch runs: Append each work item's section to plan.md and test-report.md. </artifact_timing>

<action>Prepare work items JSON array:</action>
<code>
  # For single item:
  node scripts/init-run.cjs {rootPath} {workItemId} {intentId} {mode}

  # For batch/wide (multiple items):
  node scripts/init-run.cjs {rootPath} --batch '[
    {"id": "item-1", "intent": "intent-1", "mode": "autopilot"},
    {"id": "item-2", "intent": "intent-1", "mode": "confirm"}
  ]' --scope=batch
</code>

<action>Parse script output for runId and runPath</action>
<action>Verify run.md was created in .specs-fire/runs/{run-id}/</action>

<check if="run.md not found">
  <error>init-run.cjs failed to create run.md. Check script output.</error>
</check>

<action>Get current_item from state.yaml runs.active[0]</action>
<action>Load work item from .specs-fire/intents/{intent}/work-items/{id}.md</action>
<action>Read intent brief for broader context</action>
<action>Load project standards using hierarchical resolution:</action>

<standards_resolution critical="true">
  <substep n="2a" title="Discover Standards Locations">
    <action>Scan repository for: **/.specs-fire/standards/</action>
    <action>Build list sorted by path depth (root = depth 0)</action>
    <example>
      depth 0: .specs-fire/standards/
      depth 2: packages/api/.specs-fire/standards/
      depth 2: apps/mobile/.specs-fire/standards/
    </example>
  </substep>

  <substep n="2b" title="Load Constitution (Root Only)">
    <action>Load .specs-fire/standards/constitution.md from ROOT</action>
    <critical>IGNORE any constitution.md in nested directories</critical>
    <critical>Constitution is ALWAYS inherited, NEVER overridden</critical>
    <note>If constitution.md doesn't exist, skip gracefully</note>
  </substep>

  <substep n="2c" title="Resolve Module Standards">
    <action>For each discovered standards location (excluding root):</action>

    <resolution_algorithm>
      FOR each standard_file IN [tech-stack.md, coding-standards.md,
                                  testing-standards.md, system-architecture.md]:

        IF {location}/standards/{standard_file} EXISTS:
          → USE this file for scope {location.parent_path}/**
        ELSE:
          → Walk UP to find nearest ancestor with this file
          → USE ancestor's file (ultimately root if none found)
    </resolution_algorithm>
  </substep>

  <substep n="2d" title="Present Standards with Scoping">
    <action>Present loaded standards with clear path-based scoping:</action>

    <output_format>
      ## Constitution (applies to ALL files)
      [content of root constitution.md]

      ## Standards for {module_path}/** files
      When editing files under {module_path}/, apply:
      - Tech Stack: [resolved tech-stack.md for this scope]
      - Coding Standards: [resolved coding-standards.md for this scope]
      - Testing Standards: [resolved testing-standards.md for this scope]

      ## Default Standards (paths without specific scope)
      For all other files, apply root standards.
    </output_format>
  </substep>
</standards_resolution>

<action>Determine execution mode from work item</action>

<checkpoint>
  <template_output section="plan">
    ## Implementation Plan for "{title}"

    ### Approach
    {describe approach}

    ### Files to Create
    {list files}

    ### Files to Modify
    {list files}

    ### Tests
    {list test files}

    ---
    Approve plan? [Y/n/edit]
  </template_output>
</checkpoint>

<check if="response == edit">
  <ask>What changes to the plan?</ask>
  <action>Adjust plan</action>
  <action>Update plan.md with changes</action>
  <goto step="3b"/>
</check>
<action>Mark checkpoint approved:</action>
<code>node scripts/update-checkpoint.cjs {rootPath} {runId} approved --checkpoint=plan</code>
<goto step="5"/>

<checkpoint>
  <template_output section="plan">
    ## Implementation Plan for "{title}"

    Based on approved design document.

    ### Implementation Checklist
    {from design doc}

    ### Files to Create
    {list files}

    ### Files to Modify
    {list files}

    ---
    This is Checkpoint 2 of Validate mode.
    Approve implementation plan? [Y/n/edit]
  </template_output>
</checkpoint>

<check if="response == edit">
  <ask>What changes to the plan?</ask>
  <action>Adjust plan</action>
  <action>Update plan.md with changes</action>
  <goto step="3c"/>
</check>
<action>Mark checkpoint approved:</action>
<code>node scripts/update-checkpoint.cjs {rootPath} {runId} approved --checkpoint=plan</code>
<goto step="5"/>

<batch_handling critical="true">
  <check if="batch/wide run AND plan.md already exists">
    <action>Read existing plan.md content</action>
    <action>Append new section for current work item:</action>
    <format>
      ---

      ## Work Item: {work_item_id}

      ### Approach
      {describe approach for this specific work item}

      ### Files to Create
      {list files}

      ### Files to Modify
      {list files}

      ### Tests
      {list test files}
    </format>
    <action>Write updated plan.md (preserving previous sections)</action>
  </check>

  <check if="plan.md does not exist OR single run">
    <action>Generate implementation plan</action>
    <action>Save plan using template: templates/plan.md.hbs</action>
    <action>Write to: .specs-fire/runs/{run-id}/plan.md</action>
  </check>
</batch_handling>

<output>
  Plan saved to: .specs-fire/runs/{run-id}/plan.md
  (Autopilot mode - continuing without checkpoint)
</output>
<note>No checkpoint in autopilot - human can review plan.md while agent works</note>

<action>For each planned change:</action>
<substep n="5a">Implement the change</substep>
<substep n="5b">Track file operation (create/modify)</substep>
<substep n="5c">Record decisions made</substep>

<standards_application critical="true">
  When editing a file at path X:
  1. Find the LONGEST matching standards scope (most specific)
  2. Apply those standards to the file
  3. If no specific scope matches, apply root standards

  <example>
    Editing packages/api/src/handler.go
    → Apply "Standards for packages/api/**"

    Editing scripts/deploy.sh
    → Apply "Default Standards" (root)
  </example>
</standards_application>

<brownfield_rules>
  <rule>READ existing code before modifying</rule>
  <rule>MATCH existing naming conventions</rule>
  <rule>FOLLOW existing patterns in the codebase</rule>
  <rule>PRESERVE existing tests</rule>
  <rule>USE module-specific standards when editing module files</rule>
</brownfield_rules>

<action>Load testing standards from .specs-fire/standards/testing-standards.md</action>
<action>Write tests following testing standards:</action>
<substep>Unit tests for new/modified functions</substep>
<substep>Integration tests for API endpoints or workflows</substep>
<substep>Follow test naming and structure conventions</substep>

<action>Run test suite</action>
<check if="tests fail">
  <output>Tests failed. Fixing issues...</output>
  <action>Fix failing tests</action>
  <action>Re-run tests</action>
</check>

<action>Validate acceptance criteria from work item</action>

<critical>Create test report AFTER tests pass</critical>

<batch_handling critical="true">
  <check if="batch/wide run AND test-report.md already exists">
    <action>Read existing test-report.md content</action>
    <action>Append new section for current work item:</action>
    <format>
      ---

      ## Work Item: {work_item_id}

      ### Test Results
      - Passed: {passed_count}
      - Failed: {failed_count}
      - Skipped: {skipped_count}

      ### Acceptance Criteria Validation
      {validation_results}
    </format>
    <action>Write updated test-report.md (preserving previous sections)</action>
  </check>

  <check if="test-report.md does not exist OR single run">
    <action>Generate test report using template: templates/test-report.md.hbs</action>
    <action>Write to: .specs-fire/runs/{run-id}/test-report.md</action>
  </check>
</batch_handling>

<action>Include in test report:</action>
<substep>Test results summary (passed/failed/skipped)</substep>
<substep>Code coverage percentage</substep>
<substep>Acceptance criteria validation results</substep>
<substep>Any test warnings or notes</substep>
<output>Test report saved to: .specs-fire/runs/{run-id}/test-report.md</output>

<critical>ALWAYS run code review after tests pass</critical>
<output>Running code review...</output>

<action>Invoke code-review skill with context:</action>
<code>
  invoke-skill: code-review
  context:
    files_created: {files_created}
    files_modified: {files_modified}
    run_id: {run_id}
    intent_id: {intent_id}
</code>

<invoke_skill>code-review</invoke_skill>

<note>
  Code review skill will:
  1. Review all files created/modified in this work item
  2. Auto-fix no-brainer issues (unused imports, console.log, etc.)
  3. Present suggestions requiring approval
  4. Create review-report.md artifact
</note>

<check if="code-review returns suggestions">
  <note>User interaction happens within code-review skill</note>
  <action>Wait for code-review skill to complete</action>
</check>

<check if="code-review applied fixes">
  <action>Re-run tests to verify fixes didn't break anything</action>
  <check if="tests fail">
    <output>Code review fixes caused test failure. Reverting...</output>
    <action>Revert code review changes</action>
    <action>Re-run tests to confirm passing</action>
  </check>
</check>

<output>
  Code review complete.
  Review report: .specs-fire/runs/{run-id}/review-report.md
</output>

<llm critical="true">
  <mandate>BATCH RUNS: You MUST loop until ALL items are done</mandate>
  <mandate>NEVER call --complete-run until ALL items have artifacts</mandate>
  <mandate>ALWAYS check pending count BEFORE deciding which flag to use</mandate>
</llm>

<substep n="7a" title="Check Batch Status">
  <action>Read state.yaml runs.active[{runId}]</action>
  <action>Get scope value: single, batch, or wide</action>
  <action>Count work_items where status == "pending"</action>
  <action>Store pending_count for decision</action>
</substep>

<substep n="7b" title="Route Based on Batch Status">
  <check if="scope in [batch, wide] AND pending_count > 0">
    <critical>DO NOT call --complete-run yet - more items remain!</critical>
    <action>Call complete-run.cjs with --complete-item flag:</action>
    <code>
      node scripts/complete-run.cjs {rootPath} {runId} --complete-item
    </code>
    <action>Parse output JSON for nextItem and remainingItems</action>
    <output>
      Completed: {current_item}
      Next item: {nextItem}
      Remaining: {remainingItems} items
    </output>
    <goto step="2">MUST continue with next work item - loop back NOW</goto>
  </check>

  <check if="scope == single OR pending_count == 0">
    <action>All items complete - finalize the run</action>
    <action>Call complete-run.cjs with --complete-run flag:</action>
    <code>
      node scripts/complete-run.cjs {rootPath} {runId} --complete-run \
        --files-created='[{"path":"...","purpose":"..."}]' \
        --files-modified='[{"path":"...","changes":"..."}]' \
        --tests=5 --coverage=85
    </code>
    <goto step="8"/>
  </check>
</substep>

  Work items completed: {count}
  Files created: {count}
  Files modified: {count}
  Tests added: {count}

  Artifacts:
  - Run Log: .specs-fire/runs/{run-id}/run.md
  - Plan: .specs-fire/runs/{run-id}/plan.md
  - Test Report: .specs-fire/runs/{run-id}/test-report.md
  - Code Review: .specs-fire/runs/{run-id}/review-report.md
  - Walkthrough: .specs-fire/runs/{run-id}/walkthrough.md
</output>

<file_tracking_format>

yaml
files_created:
  - path: src/auth/login.ts
    purpose: Login endpoint handler

files_modified:
  - path: src/routes/index.ts
    changes: Added login route

decisions:
  - decision: Use JWT for tokens
    rationale: Stateless, works with load balancer

</file_tracking_format>

<run_folder_structure> After init-run.cjs creates a run:

.specs-fire/runs/run-fabriqa-2026-001/
├── run.md           # Created by init-run.cjs, updated by complete-run.cjs
├── plan.md          # Created BEFORE implementation (ALL modes - required)
├── test-report.md   # Created AFTER tests pass (required)
├── review-report.md # Created by code-review skill (Step 6b)
└── walkthrough.md   # Created by walkthrough-generate skill

The run.md contains:

  • All work items with their statuses
  • Current item being executed
  • Files created/modified (after completion)
  • Decisions made (after completion)
  • Summary (after completion) </run_folder_structure>

<success_criteria> Run initialized via init-run.cjs script Standards loaded with hierarchical resolution Constitution loaded from root (if exists) Module-specific standards applied to module files plan.md created BEFORE implementation All work items implemented All tests pass test-report.md created AFTER tests pass code-review skill invoked and completed review-report.md created Run completed via complete-run.cjs script walkthrough.md generated </success_criteria>

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

fabriqaai/specs.md

frontend-design

Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics.

99 9
Explore
fabriqaai/specs.md

run-status

Display current run status and progress. Shows work item, mode, duration, and files changed.

99 9
Explore
fabriqaai/specs.md

run-plan

Plan the scope of a run by discovering available work items and suggesting groupings. Invoked before run-execute.

99 9
Explore
fabriqaai/specs.md

walkthrough-generate

Generate implementation walkthrough for human review after run completion. Documents decisions, changes, and verification steps.

99 9
Explore
fabriqaai/specs.md

code-review

Review code written during a run, auto-fix no-brainer issues, and suggest improvements requiring confirmation. Invoked after tests pass.

99 9
Explore
fabriqaai/specs.md

route

Analyze project state and route user to the appropriate agent based on current context.

99 9
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results