mjmorales/task

Task Lifecycle: $ARGUMENTS

Dispatch on the first token of $ARGUMENTS. Remaining tokens are the slug/note for that subcommand.

Routing Table

| Subcommand | Purpose | Extra args | |------------|---------|------------| | handoff | Write .prove/handoff.md from current context | optional note | | pickup | Resume work from .prove/handoff.md | none | | progress | Read-only status across active orchestrator runs | none | | complete | Merge orchestrator/<slug> to main + archive + cleanup | <slug> (optional) | | cleanup | Archive artifacts + remove working files (no merge) | <slug> (optional) | | (none) | Print this routing table and exit | — |

If $ARGUMENTS is empty or the first token is not one of the five subcommands, print the routing table above and stop — do not guess a subcommand from free-form text.

All paths below are relative to the project root. Orchestrator run artifacts live at .prove/runs/<branch>/<slug>/; state.json is the single source of truth, rendered on demand by scripts/prove-run show.

---

handoff — Serialize Session Context

Create .prove/handoff.md so a fresh session picks up where this one left off.

Rules

• Reference files by path, do not inline content. Target ~100-200 lines total.
• Each handoff is a fresh snapshot. Do not append to or reference prior handoffs.
• Do not ask the user questions. Use the extra args and conversation context.
• Cap: max 50 files in "Files Modified", max 7 in "Files to Read First".

Phase 1: Gather Context

claude-prove handoff gather --project-root "$PROJECT_ROOT" --plugin-dir "$PLUGIN_DIR"

Capture the full output — this becomes the body of the handoff file. If an extra note was passed after handoff, treat it as additional context for Phase 2.

Phase 2: Pickup Note

Generate a 3-5 sentence pickup note — the only LLM-generated part. Answer:

1. Next action — immediate work for the new agent
2. Blockers/gotchas — non-obvious issues that would trip up a fresh agent
3. Key decisions — choices made during the handed-off work that are not captured in artifacts

Conditional additions:

• Active run (state.json + plan.json under .prove/runs/<branch>/<slug>/): reference the specific step id from scripts/prove-run show state
• .prove/decisions/ has entries: mention the most recent decision
• No prove artifacts: summarize from git state
• Extra note provided: incorporate it

Be concrete: "Fix the failing test in auth/middleware.test.ts caused by the new token format" over "Continue working on auth."

Phase 3: Agent Recommendation

If agents/ exists, read .md files and parse frontmatter description. Match against the pickup note's work domain:

• Match found: claude --agent agents/<name>.md --prompt-file .prove/handoff.md
• No match, specialized work: suggest /prove:create --type agent first
• No agents dir or general work: claude --prompt-file .prove/handoff.md

Phase 4: Write & Output

Write .prove/handoff.md:

# Handoff Context
<!-- Auto-generated by /prove:task handoff. Safe to delete after use. -->

## Pickup Note
<from Phase 2>

<gathered context from Phase 1 — State, Files Modified, Prove Artifacts, Discovery>

## Files to Read First
<3-7 files, priority-ordered with one-line rationale.
 Priority: task plan > modified files > decision records > config>

## Instructions
1. Read the files listed in "Files to Read First" before starting
2. <specific resume point from the pickup note>
3. Run validation before committing: <validator commands from .claude/.prove.json>
4. When done, delete: `rm .prove/handoff.md`

Output to the user: confirm file written, show the recommended command, explain agent match if applicable.

---

pickup — Resume From Handoff

Step 1: Locate

Read .prove/handoff.md. If missing, tell the user to run /prove:task handoff first, then stop.

Step 2: Load Context

1. Read the handoff file completely
2. Read each file listed in "Files to Read First" in order
3. Read referenced prove artifacts: scripts/prove-run show state / show plan / show prd for the active run, plus decision records

Step 3: Confirm and Clean Up

Tell the user: what you picked up, what you will work on, which branch you are on.

Delete the handoff file:

rm .prove/handoff.md

Step 4: Begin Work

Follow the "Instructions" section from the handoff file. Start immediately — do not ask the user to repeat the task.

Rules

• Load all referenced files before making changes
• Delete the handoff file after loading — it is ephemeral
• The handoff file tells you what to do — do not ask the user to repeat it
• If the handoff recommends a specific agent, inform the user: "This handoff targets the <agent> agent. Consider: claude --agent agents/<name>.md --prompt-file .prove/handoff.md"

---

progress — Orchestrator Status (Read-Only)

Read-only status check across active orchestrator runs. Never modify files.

Steps

1. List active runs:

   scripts/prove-run ls
   

   If empty: "No active orchestrator run. Start one with /prove:orchestrator or /prove:orchestrator --full."

2. For each run, render the full state view (joined with the plan for titles):

   cd <worktree for slug>   # or rely on PROVE_RUN_SLUG / marker
   scripts/prove-run show state
   

   state.json is the source of truth. Markdown is rendered JIT — never persisted.

3. If multiple runs, precede with a summary table:

   | Branch/Slug | Status | Current Step | Tasks done/total | |-------------|--------|--------------|------------------|

4. For completed runs, follow the rendered state with:

   • Total duration (started_at → ended_at from state.json)
   • Review verdicts summary
   • Merge readiness (clean vs halted)

Rules

• Read-only — never invoke step/task/validator mutators
• state.json is the single source of truth; scripts/prove-run show renders views on demand
• Agents must not parse JSON directly — use scripts/prove-run summary for one-line and show for full
• State ambiguity explicitly rather than guessing
• Keep output concise

---

complete — Merge Task Branch + Cleanup

Merge a completed task branch to main and clean up artifacts.

Phase 1: Identify Task

1. Resolve the task slug:

   • Use the extra arg if provided
   • Otherwise detect from current branch (orchestrator/<slug>)
   • Otherwise scan: git branch --list 'orchestrator/*' — if multiple, AskUserQuestion to pick

2. Verify the branch exists: git branch --list 'orchestrator/<task-slug>'

   • No branch? Check for prior merge: git log --oneline main --grep="merge: "
   • Already merged → skip to Phase 3
   • No branch and no merge → halt with error

3. Show current state:

   • Commits ahead of main: git log main..orchestrator/<task-slug> --oneline
   • Artifacts found: PROJECT_ROOT="." bash "$PLUGIN_DIR/scripts/cleanup.sh" --dry-run <task-slug>

4. Confirm via AskUserQuestion (header: "Complete: <task-slug>"):

   • "Merge & Clean" — merge, archive artifacts, delete branch
   • "Merge Only" — merge, keep artifacts
   • "Clean Only" — skip merge, archive and remove artifacts
   • "Cancel"

Phase 2: Merge to Main

If user chose "Merge & Clean" or "Merge Only":

1. Halt if working tree is dirty (git status --porcelain)

2. Merge:

   git checkout main
   git pull --ff-only
   git merge --no-ff orchestrator/<task-slug> -m "merge: <task-name>"
   

3. On merge conflicts, halt immediately. Never force-merge or auto-resolve.

4. Record merge commit SHA.

Phase 3: Cleanup

If user chose "Merge & Clean" or "Clean Only":

1. Run: PROJECT_ROOT="." bash "$PLUGIN_DIR/scripts/cleanup.sh" --auto <task-slug>
2. Generate SUMMARY.md (see "SUMMARY.md Generation" below)
3. Delete merged branch: git branch -d orchestrator/<task-slug> — if -d fails (not merged), warn but do not force-delete

Phase 4: Commit & Report

1. If cleanup produced changes, delegate to the commit skill (e.g., chore(cleanup): complete and archive <task-slug>)
2. Report: merge SHA (or "skipped"/"already merged"), archived location, deleted items, skipped items

---

cleanup — Archive + Remove (No Merge)

Manual counterpart to the orchestrator's Phase 4 cleanup. Use when the merge happened elsewhere (manual merge, "Skip" at the orchestrator merge gate, or abandoning a run).

Phase 1: Dry Run

If the extra arg is provided, pass it as task-slug; otherwise use --all:

bash "$PLUGIN_DIR/scripts/cleanup.sh" --dry-run [task-slug]
bash "$PLUGIN_DIR/scripts/cleanup.sh" --dry-run --all

Present the dry-run output. AskUserQuestion, header "Cleanup", options: "Proceed" / "Cancel".

Phase 2: Execute

Run without --dry-run:

bash "$PLUGIN_DIR/scripts/cleanup.sh" [task-slug]
bash "$PLUGIN_DIR/scripts/cleanup.sh" --all

Report what was archived, removed, and skipped.

Phase 3: Generate SUMMARY.md

See "SUMMARY.md Generation" below.

Phase 4: Commit

Delegate to the commit skill. Example: chore(cleanup): archive and remove api-refactor artifacts.

---

SUMMARY.md Generation (shared by complete and cleanup)

The cleanup.sh script is ACB-aware — it archives prd.json, plan.json, state.json, and reports into .prove/archive/<YYYY-MM-DD>_<task-slug>/ before removing the working copies.

Read the archived JSON artifacts (not the md — the JSON is structured and canonical) and write SUMMARY.md in the same archive directory:

# Task Summary: <prd.json.title>

**Completed**: <YYYY-MM-DD>
**Branch**: orchestrator/<task-slug>
**Final Status**: <state.json.run_status>

## What Was Done
<from archived prd.json: context, goals>

## Tasks Completed
<from archived state.json: list tasks with review verdicts>

## Files Changed
<from archived files-changed.txt, if present>

Never regenerate SUMMARY.md from live artifacts — always from the archive.