From work-cycle
Use when the user gives any implementation task — bug fix, feature, refactor, or multi-phase project. Triages scope first, then brainstorms design before planning. Even small tasks get an assumption check. Larger tasks add full design exploration, planning, and review phases.
How this skill is triggered — by the user, by Claude, or both
Slash command
/work-cycle:plan-do-review-renewThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Brainstorm-plan-ship cycle with three explicit user checkpoints: plan review, PR strategy, and continuation.
Brainstorm-plan-ship cycle with three explicit user checkpoints: plan review, PR strategy, and continuation.
sync — sync local repo main to remote main (git checkout main && git pull in the main worktree). If continuing in a worktree, also sync the worktree's local main reference (git fetch origin && git merge origin/main, or rebase if preferred).
mergesync — merge the PR (gh pr merge --merge --delete-branch), then sync. Always treated as one atomic operation. Note: --delete-branch deletes the remote branch; the local worktree and branch remain until explicitly cleaned up.
Rule: update the workflow cursor before the first action of every new step. This keeps your position visible even through deep execution phases and context compression.
Use notepad_write_priority to maintain a live checklist. Format — use [x] done, [>] active, [ ] pending, [-] skipped:
WCYCLE: <task-summary> (<triage-class>, <tier>)
[>] 1-Triage [ ] 2-Brainstorm [ ] 3-Plan
[ ] 4-CP:Plan [ ] 5-Execute [ ] 6-Test
[ ] 7-Simplify [ ] 8-Docs [ ] 9-FinalVerify
[ ] 10-Commit [ ] 11-CP:PR [ ] 12-Check
[ ] 13-Continue
Add br:<branch>, wt:<worktree-path>, pr:#<number>, and issue:#<number> to the last line as they become available. Mark skipped steps [-] (e.g. small tasks may skip the plan file or simplify pass). For loops, append (Rev N) to the active step.
Multi-session only: also use state_write at durable milestones (triage done, plan approved, worktree created, PR opened, PR merged, continuation chosen) to persist across sessions. Use whichever OMC mode is active (e.g. ralph if invoked via ralph, autopilot if via autopilot). Include these fields in the state object: workflow ("work_cycle"), step, step_name, triage_class, tier, branch, worktree_path, tracking_issue, pr_number, updated_at.
Triage class describes scope; tier describes verification depth. They are orthogonal — a one-line edit to auth/session.py is small in scope but Thorough in tier.
| Tier | Use when | Minimum evidence |
|---|---|---|
| Light | <5 files, <100 changed lines, no API/security/data behavior | focused test or direct command, plus diff review |
| Standard | default for most contained changes | focused tests + relevant lint/typecheck + repo-required check before commit |
| Thorough | security/auth, schemas, migrations, data-loss risk, public APIs, broad refactors, >20 files | full relevant suite + acceptance ledger review + regression checks + peer review when available |
Pick a tier in Step 1 and record it in the cursor. Escalate when the user says "careful", "critical", "production", "security", "migration", or similar.
No-downgrade rule: Never downgrade tier when touched paths include auth, credentials, secrets, schemas, package/dependency manifests, deployment config, or migration code — even under time pressure, even for "tiny" edits. The blast radius, not the diff size, sets the floor.
When facing a bug, test failure, build failure, or unexpected behavior, do not patch symptoms first. Follow this sequence:
Three-attempt cap: if three fix attempts fail, stop and reassess the underlying design or ask the user for direction. Do not stack a fourth speculative fix on top of previous guesses. "One more try" is the symptom of the loop, not a way out.
Initialize the workflow cursor now — notepad_write_priority with the full checklist and [>] 1-Triage active. This is the most important write; all subsequent updates build on it.
Quick scope assessment (~30 seconds of exploration):
Before classifying, check whether the request has at least one concrete anchor:
If no anchor exists and the task is more than a trivial edit, do not skip ahead — gather cheap codebase facts first, then ask one focused clarification. Do not start an implementation cycle on a request like "make the auth better" without anchoring it first.
| Class | Criteria | Planning approach | Plan location |
|---|---|---|---|
| Small | 1–3 files, single package, no API changes | /omc-plan --direct (omc-team claude) — skip interview, describe approach inline | Skip plan file — approach stated in Checkpoint 1 |
| Single-session | Contained feature/fix within one package | /omc-plan --interactive (omc-team claude) — thorough interview before planning | .omc/plans/ |
| Multi-session | Cross-package, multi-phase, or architectural | /omc-plan --interactive --consensus (omc-team claude) — interview + planner/architect/critic loop | GitHub tracking issue + .omc/plans/ |
Pick the verification tier (Light / Standard / Thorough — see Verification Tiers section). Present classification and tier together with reasoning. User can override either.
Examine assumptions and explore the design space before planning implementation. Depth scales with the triage class. Even simple tasks benefit — "simple" is where unexamined assumptions waste the most work.
State three things and present them to the user for confirmation or correction:
Assumption check:
- Task: [restate]
- Approach: [describe]
- Assuming: [list]
Does this match your intent, or should I adjust?
User confirms → proceed to Step 3. User corrects → update and re-present.
If the assumption check reveals ambiguity, multiple viable approaches, or more scope than expected, re-triage upward to Single-session or Multi-session and run the full design exploration instead.
Adopts the discipline of superpowers:brainstorming inline — one question at a time, scope check, self-review — but does not invoke the skill (so no HARD GATE, no committed spec file required). Output is a conversational design brief, not an artifact on disk.
The all-classes Self-Review Checklist below covers placeholders, scope creep, ambiguity, and verification gaps before Step 3 — run it after the brief.
If the user asks for a durable artifact ("save the spec", "commit the design"), write it to .omc/plans/<task-slug>/design.md inside the task worktree. If no task worktree exists yet, run the Worktree Pre-Creation Safety checks from Step 5 first, create or enter the task worktree, and record br: / wt: in the cursor. Commit the artifact from that branch, never from an unisolated main checkout. Otherwise the brief lives in the conversation only.
Invoke superpowers:brainstorming with the overrides below. The HARD GATE applies — no implementation work begins until the spec is written, self-reviewed, and the user has approved it.
When invoking, instruct the skill explicitly:
Write the spec to
.omc/plans/specs/YYYY-MM-DD-<topic>-design.md, not the defaultdocs/superpowers/specs/path. After spec approval, return control to theplan-do-review-renewworkflow at Step 3 — do not invokewriting-plans. OMC's/omc-plan --interactive --consensusis the planner here.
The brainstorming skill will run its standard flow: explore project context → clarifying questions → 2–3 approaches → present design → write spec → self-review → user-review gate. Cover architecture implications, phase decomposition (which parts can ship independently, what order reduces risk), and cross-cutting concerns (shared types, migration paths, backwards compatibility) — these are required at this tier.
After the user approves the spec:
br: / wt: in the cursor.gh issue create --title "<topic> tracking" --label "tracking" --body-file <tracking-issue-body.md>
The body file must link to the spec path and contain the phase checklist (- [ ] per phase), dependencies, and acceptance criteria.For every Single-session and Multi-session task (and any Small task with non-trivial behavior), produce an explicit ledger:
Acceptance Criteria:
- [ ] AC1: <observable behavior> — Evidence: <test/command/manual check>
- [ ] AC2: <observable behavior> — Evidence: <test/command/manual check>
Rules:
Before proceeding to planning, run this checklist inline:
Flag any issues found. Resolve with the user before proceeding.
IMPORTANT: Always use /omc-plan for planning. Never use Claude Code's built-in plan mode (EnterPlanMode).
Pass the design brief from Step 2 (including the Acceptance Criteria Ledger) as context to /omc-plan so the planner doesn't re-ask resolved questions.
Run /omc-plan with flags determined by triage:
/omc-plan --direct (omc-team claude) with the task description and assumption check. Go to Step 4 with the generated approach. Do NOT skip Steps 4–13 — worktree, test, simplify, final verify, commit, and checkpoints still apply./omc-plan --interactive (omc-team claude) with the design brief and acceptance ledger from Step 2 as context — the planner should build on the design decisions already made, not restart the interview from scratch./omc-plan --interactive --consensus (omc-team claude) with the spec file (.omc/plans/specs/<file>.md) and acceptance criteria as context — the interview focuses on implementation details (the spec already settled the design), then planner/architect/critic deliberation loop until agreement.Offering consensus escalation: For any class, if the task touches critical paths, has multiple viable approaches, or the user seems uncertain, ask:
This could benefit from consensus planning (planner + architect + critic review loop). Want to upgrade to
--consensus?
Plans must be executable by a capable engineer with no chat history and "questionable taste" — assume they know nothing about our codebase, problem domain, or test conventions. Reject or revise the plan before Checkpoint 1 if any of these are present:
Placeholders and hand-waving:
Missing concreteness:
Granularity and consistency:
clearLayers() in Task 3 but clearFullLayers() in Task 7 is a bug — flag it)If the plan fails the gate, send it back to /omc-plan with specific feedback on what needs to be concrete.
Self-review against the spec (Multi-session only): after /omc-plan returns the plan, skim each section/requirement of the spec at .omc/plans/specs/<file>.md. Can you point to a task that implements it? List any gaps, then fix inline.
Multi-session only — artifact layout:
.omc/plans/specs/YYYY-MM-DD-<topic>-design.md (already written in Step 2)- [ ] phase checkboxes, dependencies, and acceptance criteria per phase.omc/plans/<phase-slug>.md — current phase only, references the spec for design contextPresent the Step 2 output (assumption check for small tasks, or design brief + Acceptance Criteria Ledger for larger ones) and the plan together. User options:
/peer-plan-review — delegate review to an external model (Gemini, Codex, Cursor, or Claude), then re-present options with their feedbackUpdate workflow cursor now — notepad_write_priority with [>] 5-Execute. This is the deepest phase; the cursor keeps remaining steps visible.
Signpost before proceeding:
Creating isolated worktree on branch
<branch-name>. Your main worktree stays untouched. All changes happen there.
Always use an isolated worktree unless the user explicitly says otherwise (e.g. "just do it here", "no worktree").
If Step 2 already created a task worktree for a durable spec or design artifact, reuse it here: verify git status --short, confirm the branch/base, and continue execution there instead of creating a second worktree.
Before creating the worktree, verify the destination directory is safe:
.worktrees/worktrees/CLAUDE.md / AGENTS.md.worktrees/git check-ignore -q <dir>..gitignore before creating the worktree..git/info/exclude instead.~/.claude/worktrees/<project>/<branch-slug>/.Then: EnterWorktree → execute (direct for small tasks, /team claude for single/multi-session).
Run focused tests that prove the changed behavior. This run locks behavior before any cleanup.
# Single package
cd <package> && uv run pytest tests/ -x
# Cross-package: run for each affected package
If tests fail: invoke the Debugging Gate (3-attempt cap, root-cause hypothesis required). Do not proceed with failing tests.
Check each Acceptance Criterion against this run's evidence. Mark [x] only when the criterion observably passed in this session.
Run after focused tests pass and before docs / final verify / commit. AI-written code accumulates bloat — wrappers, defensive checks, duplicated helpers, dead branches. Skip explicitly only if the change is docs-only, config-only, or generated code.
Use /oh-my-claudecode:ai-slop-cleaner <changed-files> scoped to the changed-file set. The cleaner will:
For higher-risk cleanup, follow with /oh-my-claudecode:ai-slop-cleaner <files> --review for a reviewer-only pass before continuing.
After Simplify, the focused tests from Step 6 must still pass. If cleanup changes behavior unintentionally, return to Step 6 with the Debugging Gate. Mark Step 7 [-] skipped when intentionally bypassed and record the reason in the cursor.
Update docs in the same branch when behavior, CLI flags, public APIs, data paths, setup steps, or user workflows changed:
CLAUDE.md quick reference tableCLAUDE.mdTell the user what you updated (or "no doc changes needed").
After Simplify and Docs, run fresh tier-appropriate verification:
If anything fails, return to Step 6 / Step 7 as appropriate. Do not proceed to commit on stale evidence.
Stage and commit all changes from execution, simplify, doc updates, and any final-verify fixes. The branch must be clean before Step 11.
git add <changed-files>
git commit -m "<conventional commit message>"
If there are multiple logical changes, use multiple commits.
Branch:
<branch-name>| Worktree:<path>| Tier:<tier>| Changes committed, ready to push.
Recommend an option based on task context:
push-mergesyncopen-pr-review or open-pr-peer-reviewopen-prAlways state your recommendation with a one-line rationale before presenting options. User can always override.
Present options:
open-pr — push branch, open PR, enter check loop (Step 12) (default)open-pr-review — push + PR + /review-pr, Claude reviews and fixes, then check loop (Step 12). Note: when invoked from here, /review-pr should end with done (not mergesync) — mergesync is handled by Step 12.open-pr-peer-review — push + PR + /peer-pr-review, external model reviews (ask which: 1. gemini, 2. codex, 3. cursor, 4. claude), then await completion (see below) and enter check loop (Step 12)push-mergesync — push + PR + mergesync immediately (no review, no check loop); then Step 13PR body must include the worktree path so reviewers can check out directly:
Worktree:
<absolute-worktree-path>
Awaiting peer review (option 3): after spawning the worker, poll PR comments every 30s for a ## Review Summary comment. When found (or worker signals done via SendMessage), run a check and present Step 12 options.
Update workflow cursor now — notepad_write_priority with [>] 12-Check. Update again on each loop iteration with current PR state (checks passing/failing, open comments).
"Check" = fetch ALL of:
gh pr view <number>
gh api repos/{owner}/{repo}/pulls/{number}/reviews
gh api repos/{owner}/{repo}/pulls/{number}/comments
gh pr view <number> --json commits
gh pr checks <number>
Recommend an option based on current PR state:
mergesynccheck-fix with summary of what needs attentioncheck and waitmergesyncAlways state your recommendation with a one-line rationale before presenting options. User can always override.
Present options:
check — fetch PR state, report, re-present optionscheck-fix — fetch, fix in worktree (use Debugging Gate for regressions), re-test, commit, push, re-present optionscheck-fix-mergesync — fetch, fix in worktree, re-test, commit, push, mergesync; then Step 13mergesync — mergesync now (no check); then Step 13abandon — close PR (gh pr close <number>), leave worktree intact; then Step 13Repeat options 1 or 2 until user picks option 3, 4, or 5.
Worktree:
<path>| PR: #<number>(merged or closed)
Proactive suggestion: Before presenting options, assess context and recommend a next step with rationale:
Present options:
ExitWorktree, sync, run /clean_gone to remove stale local branches. Done.ExitWorktree, sync, cleanup current worktree, create fresh one for next piece of work.Multi-session only — before stopping:
gh issue edit), add a session-notes comment (gh issue comment) covering decisions made, approaches tried and rejected, and surprising discoveries.omc/plans/Create a paste-ready handoff prompt when the user picks option 4 in Step 13, when context is getting long, or when another session should continue the work. Refresh cheap facts first (pwd, git status --short, git branch --show-current, git worktree list, recent commits, active PR/issue state) — do not invent state, mark unknowns explicitly.
Proactively offer a handoff prompt — without waiting to be asked — when any of these fire mid-cycle:
Format the proactive offer as a one-liner, not a wall of text:
Want me to draft a handoff prompt? Context is getting tight after the last compaction.
Do not spam-suggest. One offer per trigger event; if declined, do not re-suggest until a new trigger fires.
Template:
Continue this work using the `plan-do-review-renew` skill.
Repo: <repo-root>
Worktree: <absolute-worktree-path>
Branch: <branch>
Base: <base-ref>
PR: <number-or-url-or-none>
Tracking issue: <number-or-url-or-none>
Triage class: <small | single-session | multi-session>
Verification tier: <light | standard | thorough>
Current step: <step number and name>
Completed:
- <step / result>
Goal:
<one-paragraph task goal>
Approach and assumptions:
- <chosen approach>
- <important assumption or scope boundary>
Changed files:
- <path> — <what changed and why>
Simplify / deslop:
- <what was simplified, deleted, deduplicated, or why skipped>
Acceptance criteria:
- [x/ ] <criterion> — <evidence or missing evidence>
Verification:
- <command> — <result>
Known state and risks:
- <blocker, failing check, review comment, or risk>
- <unrelated dirty file or do-not-touch note>
Next actions:
1. cd <worktree-or-repo-path>
2. <exact next command or investigation>
3. <next implementation/review/test step>
Important instructions:
- Read CLAUDE.md and nearby project guidance before editing.
- Preserve unrelated changes; do not revert files you did not touch.
- Keep working in the listed worktree unless the user explicitly redirects.
- Run tier-appropriate verification before claiming completion.
If work is fully complete, still produce a handoff-style closeout when requested but set Current step to 13 - Done and make Next actions focus on optional cleanup, follow-ups, or related work.
npx claudepluginhub anaka/work-cycle --plugin work-cycleGuides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.