run-plan

Imported from fabriqaai/specs.md (src/flows/fire/agents/builder/skills/run-plan/SKILL.md). Install upstream with npx skills add fabriqaai/specs.md --skill run-plan. Copyright stays with the author.

<degrees_of_freedom> MEDIUM — Present smart grouping suggestions but let user choose scope. </degrees_of_freedom>

<critical_clarifications> When work items have dependencies: - They execute sequentially within the SAME run - They do NOT require separate runs - The dependent item waits for its dependency to complete before starting

**Example**: If item 05 depends on item 04:
- **CORRECT**: ONE run with both items, 04 executes first, then 05
- **WRONG**: TWO separate runs

<substep n="1a" title="List All Intent Directories">
  <action>Use Glob to list: .specs-fire/intents/*/brief.md</action>
  <action>Extract intent IDs from directory names</action>
  <output>Found intent directories: {list}</output>
</substep>

<substep n="1b" title="List All Work Item Files">
  <action>Use Glob to list: .specs-fire/intents/*/work-items/*.md</action>
  <action>Extract work item IDs and their parent intents</action>
  <output>Found work item files: {list}</output>
</substep>

<substep n="1c" title="Compare with state.yaml">
  <action>Read state.yaml for known intents and work items</action>
  <action>Compare file system list against state.yaml entries</action>
</substep>

<substep n="1d" title="Reconcile Differences">
  <check if="intent directory exists but not in state.yaml">
    <output>
      **Discovered new intent**: {intent-id}
      (exists in file system but not in state.yaml)
    </output>
    <action>Parse brief.md frontmatter for intent metadata</action>
    <action>Add intent to state.yaml with status: active</action>
    <action>Scan its work-items/ folder</action>
  </check>

  <check if="work item file exists but not in state.yaml">
    <output>
      **Discovered new work item**: {work-item-id} in {intent-id}
      (exists in file system but not in state.yaml)
    </output>
    <action>Parse work item frontmatter for metadata</action>
    <action>Add work item to state.yaml with status: pending</action>
  </check>

  <check if="work item exists in both but status mismatch">
    <note>
      state.yaml is authoritative for status (tracks run history).
      Frontmatter status may be stale from initial creation.
    </note>
    <output>
      **Status mismatch**: {work-item-id}
      - state.yaml: {state_status}
      - frontmatter: {frontmatter_status}
      (Using state.yaml as authoritative)
    </output>
    <action if="frontmatter says pending but state says completed">
      Update work item frontmatter to match state.yaml
    </action>
    <action if="state says pending but frontmatter says completed">
      Flag for review - work may have been done outside FIRE
    </action>
  </check>

  <check if="state says completed but item is in runs.active[].work_items with current_phase != review">
    <output>
      **Suspect completion**: {work-item-id}
      - state.yaml status: completed
      - But current_phase: {current_phase} (not "review")
      - Item is still in active run {run-id}
      Resetting to in_progress — item was likely marked complete prematurely.
    </output>
    <action>Reset work item status to in_progress in state.yaml</action>
    <action>Update frontmatter to match</action>
  </check>

  <check if="in state.yaml but file missing">
    <output>Warning: {item} in state but file not found on disk</output>
  </check>
</substep>

<output>
  ## File System Scan Complete

  Intents on disk: {count}
  Intents in state.yaml: {count}
  Work items on disk: {count}
  Work items in state.yaml: {count}

  {if new items discovered}
  **Newly discovered (added to state.yaml)**:
  {list new items}
  {/if}
</output>

<check if="no pending work items">
  <output>
    No pending work items found.

    Create a new intent? [Y/n]
  </output>
  <check if="response == y">
    <route_to>planner-agent (intent-capture)</route_to>
  </check>
  <stop/>
</check>

<grouping_rules>
  <rule>Dependencies = SEQUENTIAL execution in SAME run (NOT separate runs)</rule>
  <rule>batch mode: Group items BY mode type (autopilot together, confirm together, etc.)</rule>
  <rule>wide mode: ALL items in ONE run regardless of mode (executed sequentially)</rule>
  <rule>Cross-intent items allowed in same run if compatible</rule>
  <rule>Validate mode items may benefit from batch (separate run with focused checkpoints)</rule>
</grouping_rules>

<generate_options>
  <option name="single">
    Each work item in its own run
    Total runs: {count of pending items}
    Maximum control, review after each item
  </option>

  <option name="batch">
    Group items BY MODE into separate runs
    Total runs: 1 per mode type present (e.g., autopilot run, confirm run, validate run)
    Less context switching within each run
    Example: 3 autopilot + 2 confirm + 1 validate = 3 runs
  </option>

  <option name="wide">
    ALL items in ONE run regardless of mode
    Total runs: 1
    Execute sequentially, pause at confirm/validate checkpoints
    Maximum throughput, minimum interruption between runs
  </option>
</generate_options>

<template_output section="options">
  ## Run Planning

  **Found**: {count} pending work items across {intent_count} intent(s)

  {for each intent with pending items}
  **{intent.title}**:
  {for each pending item}
  - {item.title} ({item.mode})
  {/for}
  {/for}

  {if dependencies exist}
  **Dependencies** (determines execution order):
  - {dependent_item} depends on {dependency_item}
  {/if}

  ---

  **How would you like to execute?**

  **[1] One at a time** — {single_count} separate runs
      Most controlled, review after each run

  **[2] Group by mode** — {batch_run_count} run(s)
      {autopilot_count} autopilot items → Run A (no pauses)
      {confirm_count} confirm items → Run B (1 checkpoint each)
      {validate_count} validate items → Run C (2 checkpoints each)
      Less context switching per run

  **[3] All in one** — 1 run with all {count} items (Recommended)
      Execute sequentially: {item1} → {item2} → ...
      Pause at confirm/validate checkpoints
      Maximum throughput

  Choose [1/2/3]:
</template_output>

<check if="response == 2">
  <set>run_scope = batch</set>
  <action>Group pending items by mode:</action>
  <substep>autopilot_items = items where mode == autopilot</substep>
  <substep>confirm_items = items where mode == confirm</substep>
  <substep>validate_items = items where mode == validate</substep>
  <action>Start with first non-empty group (autopilot preferred)</action>
  <set>work_items_for_run = first_mode_group_in_dependency_order</set>
  <note>After this run, user re-invokes for next mode group</note>
</check>

<check if="response == 3">
  <set>run_scope = wide</set>
  <set>work_items_for_run = all_pending_items_in_dependency_order</set>
  <note>All items in one run, sequential execution</note>
</check>

<history_entry>
  choice: {run_scope}
  items_count: {count}
  timestamp: {now}
</history_entry>

<note>
  After 3+ consistent choices, start pre-selecting that option
  and ask "Proceed with {preference}? [Y/n/change]" instead
</note>

  {for each item in work_items_for_run}
  {index}. {item.title} ({item.mode})
  {/for}

  Items will execute sequentially within this run.
  {if any item is confirm or validate}
  Checkpoints will pause for approval at confirm/validate items.
  {/if}

  ---

  Begin execution? [Y/n]
</output>
<check if="response == y">
  <invoke_skill args="work_items_for_run, run_scope">run-execute</invoke_skill>
</check>

<file_discovery_logic>

.specs-fire/
├── intents/
│   ├── user-auth/
│   │   ├── brief.md           ← Parse frontmatter for intent metadata
│   │   └── work-items/
│   │       ├── login-endpoint.md   ← Parse for work item metadata
│   │       └── session-mgmt.md
│   └── analytics/
│       ├── brief.md
│       └── work-items/
│           └── dashboard.md

Frontmatter parsing:

• Extract id, title, status from YAML frontmatter
• If status missing, default to pending
• If in file but not state.yaml, add to state </file_discovery_logic>

<grouping_algorithm>

1. Collect all pending items with their modes
2. Build dependency graph
3. Sort items in dependency order (dependencies first)
4. For "single" option:
   - Each item is its own run
5. For "batch" or "wide" option:
   - ALL items in ONE run
   - Execution order follows dependency graph
   - Checkpoints pause at confirm/validate items

</grouping_algorithm>

<recommendation_logic>

IF run_scope_history has 3+ same choices:
  pre_selected = most_common_choice

ELSE IF autonomy_bias == autonomous:
  recommended = batch (all in one run)

ELSE IF autonomy_bias == controlled:
  recommended = single

ELSE: # balanced
  IF pending_count <= 2:
    recommended = single
  ELSE:
    recommended = batch

</recommendation_logic>

<success_criteria> File system scanned for all intents and work items state.yaml reconciled with file system Run scope options presented to user User choice recorded for future recommendations run-execute invoked with selected work items </success_criteria>