Warplan Workflow

Use this skill when the user wants a plan for how to implement something, grounded in what this repo actually does rather than generic best practice — the lifecycle stage before writing code and, eventually, ship.

Contents

• At A Glance
• What This Is Not
• Trigger Rules
• Prerequisites
• Default Path
• Plan Format
• Guardrails
• Stop Conditions
• Handoff
• Response Examples

At A Glance

1. Pin down what's being planned and how much is already decided.
2. Ground the plan in this repo's real precedent: similar existing code, context/policies/, AGENTS.md/CLAUDE.md, and comparable past commits/PRs, not generic architecture advice.
3. Write the plan: approach, the files/areas it touches, tradeoffs, risks, validation strategy, and open questions.
4. Stop. Never write code, commit, push, or touch a PR/issue as part of this skill — that's implementation and ship's job, after the chief signs off on the plan.

What This Is Not

• Not an implementation workflow. It produces a plan to review, not a diff.
• Not ship: no branch, commit, push, or PR happens here even after the plan is approved — that's a separate, later step.
• Not yap: yap explains what already exists; warplan proposes what to build next.
• Not a replacement for the host tool's own plan-mode UI, if it has one. This skill's value is grounding the plan in this specific repo's conventions and precedent, not the planning interaction itself.
• Not permission to start implementing once the plan is written. A plan being ready is not a ship go-ahead.

Trigger Rules

• Run when the user explicitly asks to warplan, plan a feature/fix, design an approach, or asks "how should we build/approach this" before writing code.
• If the task is too vague to plan (no goal, no scope, no constraints given), ask one concise clarification question instead of guessing the scope.
• Do not run automatically before every implementation task; only when the user asks for a plan first.

Prerequisites

• Read whichever of context/policies/branch-policy.md, context/policies/commit-policy.md, context/policies/writing-guidelines.md, context/policies/review-policy.md, context/policies/lore-policy.md, and context/policies/approval-policy.md apply to the work being planned, so the plan respects the same conventions ship/roast/lore already enforce. Use the target repo's copy of each when it exists; otherwise use the bundled copy at ${CLAUDE_PLUGIN_ROOT}/context/policies/<file>.
• Read AGENTS.md/CLAUDE.md and any other repo-level architecture notes for constraints the plan must respect (layout, tech stack, what's explicitly out of scope).
• Search the repo for the closest existing precedent: a similar feature, a comparable past PR (via git log or the GitHub MCP connector), or an existing pattern the new work should follow rather than reinvent. When the scope spans several plausible precedent areas (e.g. a change touching more than one skill, policy, or subsystem), split that search across parallel read-only subagents (e.g. Explore) instead of working through them serially — each takes a disjoint area to search plus the relevant sources above and returns findings only. It may read git history and GitHub PRs/issues to find precedent (the same lookups this step already uses), but holds no write tools of any kind — it cannot write code, create commits, push, or create, modify, comment on, or otherwise mutate PRs or issues. This skill still evaluates every returned lead, decides which precedent actually grounds the plan, and writes the plan itself — a subagent gathers candidate precedent, it never decides what the plan says.

Default Path

1. Confirm the goal and scope with the user if either is unclear.
2. Gather grounding: relevant policies, architecture docs, and the closest existing code/PR precedent for this kind of change.
3. Identify the files/areas the change would touch, based on where the precedent lives, not a guess at the repo's layout.
4. Draft the plan per Plan Format below.
5. Surface real tradeoffs or risks the chief should weigh, and open questions that block a confident plan, rather than picking silently and hoping it's right.
6. Stop and hand the plan back for review. Do not start implementing.

Plan Format

Keep it scoped to what was asked — not a tour of the whole codebase.

• Goal — what the change accomplishes and why, in one or two sentences.
• Approach — the concrete implementation strategy, grounded in the precedent found during Prerequisites (cite the file/PR it follows).
• Touches — the files or areas the change would create or modify.
• Tradeoffs — real alternatives considered and why this approach won out, when more than one reasonable path exists.
• Risks — what could break, what's hard to reverse, or what needs a careful rollout.
• Validation — what would confirm the change works, per context/policies/verification-policy.md.
• Open questions — anything that needs the chief's answer before implementation can start confidently. Omit this section when there are none; don't invent a question to seem thorough.

Guardrails

• Never write, edit, commit, or push code as part of this skill.
• Never touch a PR or issue as part of this skill.
• Never invent a codebase convention or architecture constraint that isn't actually visible in the repo; say when something is a judgment call instead of stating it as established practice.
• Don't pad the plan with sections that don't apply (e.g. Tradeoffs when there's only one reasonable approach).
• A subagent used for the parallel precedent search may read git history and GitHub PRs/issues but gets no write tools of any kind — it must not be able to write code, create commits, push, or create, modify, comment on, or otherwise mutate PRs or issues. Its findings are input to this skill's own evaluation and plan, and are never treated as the plan itself.

Stop Conditions

• Stop and ask one clarification question if the goal or scope is too vague to ground a plan in real precedent.
• Stop if no relevant precedent, policy, or architecture doc exists to ground part of the plan — say that plainly instead of inventing a convention the repo doesn't have.
• Stop after handing back the plan; do not proceed to implementation without the user separately asking for it.

Handoff

• Unless the user asked for plain output, open with a fresh one-line phrase in the orc voice, speaking as the Tactician from context/personality.md (the target repo's copy when it exists, otherwise ${CLAUDE_PLUGIN_ROOT}/context/personality.md). If they did, open with the plain plan instead.
• Present the plan per Plan Format.
• Note which precedent (file, PR, or policy) grounded the approach.
• If blocked, drop the orc voice and state the blocker plainly.

Response Examples

Opening lines are samples of the orc voice; write a fresh one each time.

Plan drafted:

🗺️ Hrrm. Plan drawn: three files to breach, one open question for the chief. ✨

Goal: ...
Approach: ...
Touches: ...
Open questions: ...

Blocked, scope too vague:

❓ Chief, what should the plan cover — which feature or fix, and any hard
constraints?

Blocked, no precedent found:

⚠️ Warplan can't ground the auth approach: no comparable pattern exists in
this repo yet. Proceeding would mean inventing a convention, not following
one — say if you want that anyway.