autonomous-work

Autonomous Work

an end-to-end workflow for taking an idea through to shipped code with minimal check-ins. Use AFTER brainstorming (or kick off brainstorming first — see Phase 0).

When to use

• the user invokes /autonomous-work or says "go autonomous" / "run the full flow".
• The work is large enough to justify a written spec + plan (multi-step, multi-file).

Don't use for: single-edit fixes, quick reads, exploratory questions, or anything that doesn't need a plan.

Pre-flight questions (ask the user before starting)

Ask these in a single batched question round, BEFORE Phase 0:

1. Is brainstorming done? If no, offer to either (a) run brainstorming first with full reasoning for each decision, or (b) skip brainstorming and proceed straight to spec. If brainstorming is run, decisions made during it MUST be captured in both progress.md and handover.md so the user can review them later.
2. Is this a new feature? If yes, plan to produce docs/<feature-name>.md as part of the work (per your global CLAUDE.md "Feature documentation in docs/" rule). Confirm the filename.
3. Pre-release status of this repo? Check the repo's CLAUDE.md first. If it doesn't state whether the project is pre-release, ask the user and write the answer into the repo's CLAUDE.md so future sessions don't need to ask again. Pre-release status governs Phase 6 (merge to main) and the Laravel migration rule.
4. Where do progress.md and handover.md live in this repo? Default to repo root; check for existing files first, and use the existing location if there is one.

The pipeline

Phase 0 — Brainstorming (only if not already done)

• Use superpowers:brainstorming skill.
• After each decision, write a one-line rationale.
• At the end, capture all decisions in the eventual progress.md and handover.md (this is non-negotiable — the user reviews decisions through these files).

Phase 1 — Spec

• Write the spec to docs/superpowers/specs/<feature>.md.
• Self-review: re-read critically, fix gaps.
• Dispatch a general-purpose subagent to review the spec for gaps, ambiguity, missing edge cases, and security/UX boundary issues. Pass the spec path and ask for a punch list under 200 words.
• Address the feedback. Re-review only if changes were substantive.

Phase 2 — Plan

• Once the spec is approved, write the implementation plan to docs/superpowers/plans/<feature>.md.
• Dispatch a subagent for a quick plan review — focus on sequencing, missing steps, risky ordering. Under 150 words.
• Address feedback.

Phase 3 — Execute

• Count the tasks in the plan.
• More than 10 tasks → use superpowers:subagent-driven-development: one subagent per independent task, with code review between tasks.
• 10 or fewer → execute inline in this session.

Phase 4 — Track progress (during execution)

• Maintain progress.md at the agreed location.
• Append a dated entry every time a meaningful unit of work completes. Include: what was done, what was deferred, what surprised us, and any decisions taken in the moment.
• If Phase 0 brainstorming happened, brainstorming decisions go in here too.
• This is mandatory — it's how the user audits autonomous sessions afterwards.

Phase 5 — Feature doc (only if "new feature" answer was yes)

• Write docs/<feature-name>.md per the comprehensive template in your global CLAUDE.md (Overview / How it works / Architecture / Data model / API / Business rules / Security / Frontend behaviour / Operational notes / Cross-links).
• Bias toward more detail. Future agents will read this first.

Phase 6 — Handover

• Before wrapping, write a comprehensive handover.md. Overwrite the previous one. It must cover:
  • Where the work stands (which plan steps are done, which remain).
  • Decisions made this session and why (including brainstorming decisions if applicable).
  • Open questions or things the next agent needs to confirm with the user.
  • Files touched, branches/commits created, anything in flight.
  • Anything subtle that won't be obvious from the diff.
• Write it as if the next agent has zero context. Bias toward more detail.

Phase 7 — Ship

• Commit with a descriptive message. Push.
• Always include progress.md, handover.md, and any feature doc in the commit.
• Pre-release projects on a feature branch: merge the branch back to main after pushing. Skip for projects that aren't pre-release.

Project-specific notes

Laravel + pre-release

If the project is Laravel and pre-release, and the task requires schema changes, edit the existing migration files directly instead of generating new migrations. The reset path is php artisan migrate:fresh --seed. Skip this rule for projects that aren't pre-release — there, always create new migration files.

Red flags — stop and check with the user

• Spec subagent review surfaced a fundamental design question → don't paper over it, ask.
• Plan has a step that requires destructive ops (data drop, force-push, branch deletion) → confirm before executing.
• Mid-execution, a plan step turns out wrong → update the plan + progress.md rather than silently improvising.
• About to skip progress.md, handover.md, or the feature doc because "the session was small" → don't skip. They're cheap and they're the contract.
• About to merge to main without confirming pre-release status → stop and check CLAUDE.md (and ask the user if absent).

Quick reference

Phase	Output	Subagent?
0. Brainstorm (if needed)	Decisions in progress.md + handover.md	No
1. Spec	docs/superpowers/specs/<feature>.md	Yes — review
2. Plan	docs/superpowers/plans/<feature>.md	Yes — quick review
3a. Execute (>10 tasks)	Code + tests	Yes — one per task
3b. Execute (≤10 tasks)	Code + tests	No — inline
4. Progress log	progress.md (rolling, appended)	No
5. Feature doc (if new feature)	docs/<feature-name>.md	No
6. Handover	handover.md (overwritten)	No
7. Ship	commit + push (+ merge if pre-release)	No