/flight-plan

Mission Header

Opt-out: If the target project's CLAUDE.md contains the line Reaper: disable ASCII art, output nothing — skip the header entirely.

Render-once directive: Render this header immediately as the first user-visible output of the command, before any tool calls or information gathering. Do not re-render it at any later point in the same session.

  REAPER // FLIGHT PLAN
  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  analyzing mission scope

User Communication Contract

Speak about work outcomes and progress — never about internal machinery, tool names, or implementation steps.

Forbidden Terms

Do not use any of the following in user-facing messages, status cards, or progress output:

Abstract operation names — replace with plain language:

Forbidden	Use instead
FETCH_ISSUE	"retrieving task details" or "looking up the issue"
CREATE_ISSUE	"creating a task" or "logging the issue"
UPDATE_ISSUE	"updating the task" or "recording progress"
ADD_DEPENDENCY	"linking a dependency"
LIST_CHILDREN	"listing subtasks"
QUERY_DEPENDENCY_TREE	"checking dependencies"
CLOSE_ISSUE	"marking the task complete"

Internal state variables — omit or rephrase:

Forbidden	Use instead
TASK_SYSTEM / markdown_only	"your project's task tracking setup"
PLAN_CONTEXT	"the task requirements" or "the plan"
CODEBASE CONTEXT	"the codebase"

Internal file sentinels — never surface raw filenames:

RESULTS.md, REVIEW.md, SECURITY.md, FAULT.md, TASK.md

Tool names — never expose tool internals as user language:

Forbidden	Use instead
TaskCreate	"tracking progress" or "updating the work plan"
TaskUpdate	"recording progress"

Architecture terms — omit entirely:

platform skill routing, behavioral contract, skill routing table, gate classification internals

Tone Rule

Describe what is happening for the user ("running tests", "planning the feature", "reviewing security") — not what the system is doing internally ("routing to skill", "resolving TASK_SYSTEM", "invoking TaskCreate").

Visual Vocabulary

Opt-out: If the project's CLAUDE.md contains the line Reaper: disable ASCII art, emit plain text status labels only. No gauge bars, no box-drawing, no card templates. Use the functional context behavior regardless of the context parameter.

Rendering constraint: One line, one direction, no column alignment. Every visual element must be renderable in a single horizontal pass. No multi-line box-drawing that requires vertical alignment across columns. Exception: The start context uses box-drawing for its welcome screen cards, which are rendered once as orientation content rather than repeated status displays.

Gauge States

Six semantic states expressed as fixed-width 10-block bars. Use these consistently across all commands to communicate work status.

  ██████████  LANDED       complete, healthy
  ████████░░  ON APPROACH  coding done, quality gates running
  ██████░░░░  IN FLIGHT    work in progress
  ███░░░░░░░  TAKING OFF   deploying, about to execute
  ░░░░░░░░░░  TAXIING     waiting, not started
  ░░░░!!░░░░  FAULT        failed, needs attention

Gauge usage rules:

• Always use exactly 10 blocks per bar (full-width = 10 filled, empty = 10 unfilled).
• The exclamation marks in the FAULT bar replace two blocks at the center to signal breakage.
• Pair each bar with its label and a short gloss on the same line.

Quality Gate Statuses

Five inspection verdicts for quality gate results. Gate statuses are inspection verdicts, not work lifecycle states. Use gauge states for work unit progress, gate statuses for quality inspection results.

Status	Meaning
PASS	gate passed all checks
FAIL	gate found blocking issues
RUNNING	gate currently executing
PENDING	gate not yet started
SKIP	gate not applicable to this work type

Briefing Card

Render before work begins, after the flight briefing summary in Phase 3. Shows the plan parameters the user is about to approve.

  BRIEFING
  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Plan:       [plan title or description]
  Units:      [N work units]
  Parallel:   [M% parallelizable]
  ░░░░░░░░░░  AWAITING CLEARANCE

Filed Card

Render after issue creation completes in Phase 7. Shows the result summary only — next steps appear below the card as plain text.

  FLIGHT PLAN
  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Plan:       [plan title]
  Issues:     [N issues created]
  ██████████  FILED

Filed card rules:

• Show the plan title on the Plan row.
• Show the total count of issues created on the Issues row.
• Use the FILED gauge — the plan has been filed, ready for takeoff.
• Do not include a Next row in the card — the takeoff instructions appear below it.

Do not use EnterPlanMode or ExitPlanMode tools. This command manages its own planning workflow and presents the plan in-conversation.

---

Autonomous Execution Planner

Task: [ARGUMENTS]

Generate an execution plan with parent/child issue structure for autonomous execution. After user approval, create issues in the detected task system.

---

Phase 1: Input Processing & Behavioral Contract

Detect Input Type

Task System Operations

Detection

Active task system: !${CLAUDE_PLUGIN_ROOT}/scripts/config-get.sh tracker.system --fallback-script ${CLAUDE_PLUGIN_ROOT}/scripts/detect-task-system.sh

Output variable: TASK_SYSTEM — set this to the detected value above.

Possible values: GitHub, Beads, Jira, Linear, markdown_only, unknown

If the detected value is unknown: ask the user which task system they're using before proceeding. Once confirmed, set TASK_SYSTEM to the user's answer and continue.

If the detected value is markdown_only: inform the user that no task tracker was detected and the plan file will be the primary deliverable.

Platform Skill Routing

After detection, immediately invoke the Skill tool with the corresponding skill name before doing anything else. This is mandatory — do not attempt to use abstract operations without loading the skill first.

TASK_SYSTEM	Skill to invoke
Beads	reaper:issue-tracker-beads
GitHub	reaper:issue-tracker-github
Jira	reaper:issue-tracker-jira
Linear	reaper:issue-tracker-linear
markdown_only	reaper:issue-tracker-planfile

Example: If TASK_SYSTEM = Beads, call: Skill(skill: "reaper:issue-tracker-beads")

The skill returns the exact CLI commands for every abstract operation below. Do not guess CLI syntax — the skill is the single source of truth for platform-specific commands.

Abstract Operations

The operations below are abstract. Their concrete implementations come exclusively from the loaded skill. Never fabricate commands — invoke the skill, read its output, and follow the mappings it provides.

Operation	Purpose
FETCH_ISSUE	Retrieve a single issue by ID (title, description, status, acceptance criteria)
LIST_CHILDREN	List direct child issues of a parent (one level deep)
CREATE_ISSUE	Create a new issue with title, description, and optional parent (the parent parameter is the sole mechanism for establishing parent-child hierarchy)
UPDATE_ISSUE	Modify an existing issue (status, description, assignee)
ADD_DEPENDENCY	Create a blocks or related dependency between two sibling issues (never for hierarchy)
QUERY_DEPENDENCY_TREE	Recursively retrieve the full dependency graph from a root issue
CLOSE_ISSUE	Mark an issue as completed/closed

Dependency Type Semantics

ADD_DEPENDENCY supports two recommended dependency types for execution planning:

• blocks: Sequential constraint (task A must complete before task B can start)
• related: Informational link (tasks share context but no execution dependency)

Hierarchy preference: Use the parent parameter on CREATE_ISSUE for parent-child relationships. While some task systems support a parent-child dependency type via ADD_DEPENDENCY, the parent parameter on CREATE_ISSUE produces cleaner tracking and consistent child ID patterns. Prefer parent on create; reserve ADD_DEPENDENCY for sibling-to-sibling execution constraints and informational links.

Platform Skill Loading

After detecting TASK_SYSTEM, load the corresponding skill from the Platform Skill Routing table above. The loaded skill provides platform-specific command mappings for all abstract operations used in this command (FETCH_ISSUE, CREATE_ISSUE, UPDATE_ISSUE, ADD_DEPENDENCY, LIST_CHILDREN, QUERY_DEPENDENCY_TREE).

Classify the input (ARGUMENTS) as one of:

• Existing parent issue ID (e.g., PROJ-123 or repo-a3f): Use FETCH_ISSUE to retrieve issue details. Validate the issue has no existing children via LIST_CHILDREN -- if children exist, stop and report the conflict.
• New description: Detect the available task system using the detection heuristics above. Store the description as the planning request.

Markdown-Only Mode Detection

When no task system is detected, inform the user the plan file will be the primary deliverable. Update behavioral contract todo #2 to: "Finalize plan file as deliverable (no task system)".

Validation

• Existing parent issue: Must have no children (empty)
• New description: Minimum 20 characters
• Ambiguous system: Ask user preference if both available

Behavioral Contract

After detecting task system, create three core tasks via TaskCreate with blocking dependencies:

1. TaskCreate: "Show plan for user approval" → set in_progress
2. TaskCreate: "Create issues in [Beads|Jira|Markdown]" (dynamic system name)
3. TaskCreate: "Run workflow-planner-verification skill to verify issues"

Then establish blockers via TaskUpdate:

• Task #2 addBlockedBy: [#1] — cannot create issues until plan is approved
• Task #3 addBlockedBy: [#2] — cannot verify issues until they exist

Sub-breakdowns are allowed. No task should mention worktrees, implementation, coding, testing, or deploying. These 3 tasks define your complete scope -- when all complete, STOP.

---

Phase 1.5: Codebase Research (On-Demand Exploration)

Explore agents are a fallback for when context is genuinely missing — not a routine step. Default to skipping this phase and proceeding directly to Phase 2.

When to Skip (Default)

Skip research entirely when:

• The current session already contains relevant file paths, architecture context, or a detailed task description
• The user provided a spec, plan file, or task file with sufficient detail
• The request is a new standalone project, pure documentation, or configuration change
• The affected files and integration points are obvious from the description

When in doubt, skip and plan with what you have. Assumptions can be noted in the plan and corrected during Phase 4 refinement.

When to Research (Exception)

Spawn an Explore agent only when all of the following are true:

• The change touches existing code (not a greenfield project)
• The affected files or integration points are genuinely unclear
• No sufficient context exists in the current session

Spawn a Focused Explore Agent

When research is needed, spawn a single Explore agent targeting only the information required to define work unit scope:

Task --subagent_type Explore \
  --prompt "PLANNING RESEARCH for: '$PLANNING_REQUEST'

  Return only what is needed to scope the work units:
  1. Which files are most likely to be modified?
  2. Are there existing implementations of similar functionality to follow or extend?
  3. What are the key integration points (shared utilities, APIs, or modules) that touch this area?

  Be concise. Output: JSON with { affected_files: [...], existing_patterns: [...], integration_points: [...] }"

Use Research in Phase 2

If research was run, use the findings to inform work unit scope, affected files, and dependency ordering. If research was skipped, proceed with context from the current session and note any assumptions.

---

Phase 2: Quick Analysis (Minimal Questions)

Question Philosophy

Bias toward action, not interrogation.

• Generate a first-pass plan immediately based on available context
• Only ask clarifying questions if input is truly ambiguous (rare)
• Maximum 0-2 upfront questions, asked together (never more)
• When in doubt, make reasonable assumptions and note them in the plan

When Questions Are Appropriate

Ask upfront ONLY if:

• The request could mean two fundamentally different things (scope ambiguity)
• A critical constraint is completely unknown and uninferable
• The wrong assumption would waste significant effort

Do NOT ask about:

• Implementation details (resolve during planning)
• Nice-to-have clarifications (make assumptions, note them)
• Things discoverable from codebase exploration
• Preferences that can be refined later

Question Format (When Necessary)

If you must ask (rare): briefly restate the plan, ask the question, and offer a "proceed with assumptions" escape hatch. Never present more than 2 questions.

Work Analysis

Using research from Phase 1.5, identify:

1. Parent Issue Definition: Title, goal, scope boundaries, success criteria (only needed when the plan contains multiple child work items)
2. Work Units: Discrete issues following constraints below
3. Parallel Opportunities: Units with no file overlap or dependencies
4. Dependencies: Blocking relationships and critical path
5. User Intervention: Tasks requiring manual action (assign to user)

Work Unit Constraints

Constraint	Limit
Files per unit	≤5
LOC per unit	~500
Estimated time	1-2 hours
Responsibility	Single testable outcome
TDD methodology	Tests BEFORE implementation

TDD Requirement: Each work unit MUST follow Red-Green-Blue cycle internally:

1. RED: Write failing tests that define expected behavior
2. GREEN: Implement minimal code to pass tests
3. BLUE: Refactor while keeping tests green

All three phases complete within the same work unit. Every work unit must leave all tests green upon completion — quality gates run at each work unit boundary.

Anti-pattern warning: Never split TDD phases across work units. Neither "implement feature" + "add tests" NOR "write failing tests" + "implement to pass" are valid decompositions. TDD is an internal workflow within a single work unit, not a decomposition strategy across work units.

User Intervention Markers

Mark units as Assignee: user when they require:

• Physical device testing
• Vendor/third-party coordination
• Approval workflows
• Production console configuration
• License/purchase acquisition

ADR Detection

After completing work analysis, evaluate whether any decisions made during research and planning meet the ADR bar.

ADR-worthy decisions share these characteristics — a candidate must meet at least one:

1. Non-obvious: The reasoning will not be apparent from reading the code alone. A future developer would wonder "why was this done this way?"
2. Consequential: The decision meaningfully shapes how the feature works or constrains how future code in this area will be written.
3. Deliberate: A choice was made between two or more valid approaches with meaningfully different trade-offs, and the reasoning for the selection would not be obvious to a future developer.
4. Convention-establishing: The work creates or changes a pattern that future developers will follow across the codebase.

Not ADR-worthy: routine implementation choices within an established pattern, obvious bug fixes, minor refactors, decisions fully explained by the task description.

For each ADR candidate detected:

1. Check docs/adr/ to determine the next sequential number (e.g., if the last is 0012-*.md, the next is 0013). If the directory does not exist or contains no ADRs, start at 0001.

2. Draft a proposed ADR entry in the plan file under ## Proposed ADRs:

   ### ADR-NNNN: [Short decision title]
   **Why this warrants an ADR**: [Name the specific characteristic — non-obvious / consequential /
   convention-establishing — and explain in 1-2 sentences how this decision meets it.]
   **Context**: [What problem or constraint forced this decision]
   **Decision**: [What was chosen]
   **Alternatives rejected**: [What was considered and why it was passed over]
   

3. Add a Write ADR-NNNN work unit to the plan (type docs, unblocked):

   • Title: Write ADR-NNNN: [decision title]
   • Description: finalize and commit the proposed ADR document to docs/adr/
   • No TDD required — this is a documentation task

If no ADR candidates are detected, leave ## Proposed ADRs empty with the placeholder text and do not add any write-ADR work units.

---

Phase 3: Present Flight Briefing

Present a flight briefing to the user that summarizes the plan in-conversation before asking for approval. Include:

1. Parent issue title and goal (one-liner; omit if plan has only a single work item with no parent)
2. Work units summary — for each unit: number, title, type, estimated hours, and whether it runs in parallel
3. Critical path — which units are sequential blockers
4. Parallelization — percentage of work that can run concurrently
5. Key assumptions — list assumptions the user might want to correct

Then prompt for approval using AskUserQuestion. Select the variant based on TASK_SYSTEM detected in Phase 1:

If TASK_SYSTEM is Beads, Jira, or GitHub:

{
  "questions": [{
    "question": "Flight plan filed: N work units, M% parallelizable. Ready for issue creation in [Beads|Jira|GitHub]?",
    "header": "Flight Plan",
    "options": [
      {"label": "Cleared for takeoff", "description": "Create all issues and dependencies in [Beads|Jira|GitHub] as shown in the plan above"},
      {"label": "Revise flight plan", "description": "Circle back to the hangar — request changes to work units, scope, or dependencies before creating issues"}
    ],
    "multiSelect": false
  }]
}

If TASK_SYSTEM is markdown_only:

{
  "questions": [{
    "question": "Flight plan filed: N work units, M% parallelizable. Finalize the plan file as your deliverable?",
    "header": "Flight Plan",
    "options": [
      {"label": "Cleared for takeoff", "description": "Lock in the plan file as the final deliverable — ready for manual task creation or direct /reaper:takeoff execution"},
      {"label": "Revise flight plan", "description": "Circle back to the hangar — request changes to work units, scope, or dependencies before finalizing"}
    ],
    "multiSelect": false
  }]
}

Replace N with the work unit count and M with the parallelization percentage. AskUserQuestion automatically includes an "Other" option that lets the user type freeform feedback (use it to request changes) — see Phase 4 for response handling.

---

Phase 4: Iterative Refinement (In-Conversation)

Handling AskUserQuestion Responses

Map the user's AskUserQuestion selection:

Selection	Action
Cleared for takeoff	Proceed to Phase 5
Revise flight plan	Ask the user what they want to change, then apply feedback and re-prompt (same as "Other" path)
Other (freeform text)	Treat as feedback — revise the plan in-conversation and re-prompt

Refinement Process

When the user selects "Other" or "Revise flight plan" and provides feedback:

1. Apply changes in-conversation based on the user's feedback.
2. Summarize changes to the user, then call AskUserQuestion again with the same structure as Phase 3. Update N (work unit count) and M (parallelization percentage) in the question text if work units changed. Use the task-system or markdown-only variant matching the detected TASK_SYSTEM.

Refinement Guidelines

• Keep cycles fast -- revise in-conversation, not through file edits
• Track corrected assumptions explicitly in the updated briefing
• After major feedback, may re-run targeted Explore agents
• The flow should feel like a conversation, not an interview

---

Phase 5: Create Issues (After Approval)

Update todo #2 to in_progress.

Issue Creation

Delegate all issue creation to the loaded platform skill. The skill maps abstract operations to platform-specific commands.

For each work unit in the approved plan:

1. Parent issue (create or update):

   • Plans with only one issue do not need a parent issue. Skip this step if the plan contains exactly one work item.
   • If an existing parent issue was provided as input: UPDATE_ISSUE to refine its description
   • Otherwise (multiple work items): CREATE_ISSUE with title from plan, description from plan Input section

2. Child issues (one per work unit):

   • If a parent issue was created: CREATE_ISSUE with title, parent=PARENT_ISSUE_ID, and the TDD-structured description below
   • If no parent issue (single work item): CREATE_ISSUE with title and the TDD-structured description below (no parent)
   • For user intervention tasks: set assignee=user
   • The parent=PARENT_ISSUE_ID parameter on CREATE_ISSUE establishes parent-child hierarchy. Do NOT use ADD_DEPENDENCY for this purpose.

3. Dependencies (from plan's dependency graph):
   • ADD_DEPENDENCY with type=blocks for execution order constraints
   • ADD_DEPENDENCY with type=related for informational links

TDD-Structured Issue Description Template

Each child issue description must follow this structure:

## Objective
[What needs to be done]

## TDD Approach
Follow Red-Green-Blue cycle:
1. RED: Write failing tests that define expected behavior
2. GREEN: Implement minimal code to pass tests
3. BLUE: Refactor while keeping tests green

## Acceptance Criteria
- [ ] [criterion from plan]
- [ ] All tests pass
- [ ] Code coverage meets threshold

## Scope
Files: [estimated files from plan]

ID Generation: Task IDs are automatically generated by the task system upon creation. Never specify IDs manually -- capture the returned ID for use in subsequent operations.

---

Phase 6: Issue Quality Review (Isolated Subagent Verification)

Note: This phase is skipped when TASK_SYSTEM is markdown_only.

Update todo #3 to in_progress.

Dispatch Verification Subagent

Deploy reaper:workflow-planner as an isolated Task subagent with MODE: VERIFICATION. The subagent will internally load and run the reaper:workflow-planner-verification skill via its Skill tool.

Task(
  subagent_type: "reaper:workflow-planner",
  prompt: "MODE: VERIFICATION
PARENT_ISSUE_ID: $PARENT_ISSUE_ID (omit if plan has only one work item)
TASK_SYSTEM: $TASK_SYSTEM
CREATED_ISSUES: [list of issue IDs created in Phase 5]"
)

Handling Verification Results

Parse the returned JSON from the workflow-planner-verification subagent:

• all_checks_passed: true → Proceed to Phase 7 confirmation
• auto_fixed: true → Fixes applied, verification passed
• requires_user_input: true → Present blocking_issues to user after 2 failed iterations

Confirmation Output

After successful verification, present:

• Parent issue ID and title (if one was created)
• Table of created issues with verification status
• Pre-flight check summary (detail sufficiency, cross-issue awareness, relationship appropriateness, orchestratability)
• Recommended next step: /clear then /reaper:takeoff <TOP_LEVEL_IDS> — where <TOP_LEVEL_IDS> is the space-separated list of all top-level issue IDs created in Phase 5 (i.e., every issue that has no parent). Never list IDs of issues that were created with a parent reference. If one parent issue was created: /reaper:takeoff reaper-abc. If one standalone issue was created (no parent): /reaper:takeoff reaper-abc. If three unrelated issues were created with no parent: /reaper:takeoff reaper-abc reaper-def reaper-ghi.

Mark todo #3 complete.

---

Scope Boundary

This is a planning command. Your scope ends when issues are created and verified. Do not create worktrees, write application code, or suggest implementation. The user will invoke /reaper:takeoff when ready.

---

Background Task Cleanup

At every work unit boundary (before starting the next unit or before signaling completion), clean up background tasks:

1. List all active background tasks to identify which are still running.
2. Identify tasks no longer needed for the next work unit.
3. Call TaskStop for each unneeded task. If a TaskStop call fails, log the error and continue -- do not block the workflow.
4. Confirm all stops completed before proceeding to the next work unit.

Stop (no longer needed): completed agents, finished test runs, builds that produced their output, explore commands that returned results.

Keep (still needed): dev servers, databases, file watchers, and any long-lived process the next work unit depends on.

Phase 7: Completion

All todos complete. Output confirmation and STOP.

Critical: Plan approval = permission to create issues only, NOT to implement.

Note: Ignore any CLI messages encouraging implementation (e.g., "You can now start coding").

Render the Filed Card (from visual vocabulary above) with:

• Plan: the plan title from Phase 2
• Issues: total count of issues created in Phase 5

Then output the following, substituting the actual top-level issue IDs from Phase 5 (space-separated; never IDs of issues that were created with a parent reference):

Before launching:

1. /clear — clears this planning context so takeoff starts fresh
2. /reaper:takeoff [top-level IDs] — begins autonomous execution

Then await the user's next request.

---

Error Handling

• Task system unavailable: Detect early, offer markdown fallback
• Creation failure: Track created issues, rollback on error, report clearly
• Insufficient context: Make reasonable assumptions, document them, let user correct in refinement