IF A SKILL APPLIES TO YOUR TASK, YOU DO NOT HAVE A CHOICE. YOU MUST USE IT.
This is not negotiable. This is not optional. You cannot rationalize your way out of this.
Planning WorkflowYou have skills. You MUST use them. Not "should." Not "when convenient." MUST.
Invoke relevant skills BEFORE any response or action. Even a 1% chance a skill might apply means you invoke it. If an invoked skill turns out to be wrong for the situation, you don't need to follow it. But you must check.
The One Rule
When an implementation choice exists, never write code until the human has reviewed and approved a written plan. Exact mechanical changes may use the exception below.
The plan may be inline in the conversation or backed by persisted spec artifacts. Select the mode before invoking an artifact-producing skill, state the choice with one brief reason, and let the human override it.
Planning Modes
Inline Plan (default)
Use for bounded, well-understood work, including ordinary features, bug fixes, refactors,
configuration changes, and multi-file changes. Route to spec-plan with Inline mode
explicitly selected. It presents a concise plan in conversation, creates no planning artifacts
or tracker entries, and stops for approval. After approval, implement the plan directly; do
not invoke spec-implement, spec-finish, or code-subagents.
Direct Inline implementation must:
- Avoid main/master unless the human explicitly permits it
- Stay within the approved scope and files
- Run every validation item in the approved plan
- Review the final diff for unintended changes
- Do not commit, push, or open a PR without explicit human instruction
When in doubt, choose Inline Plan. File count and estimated duration alone do not make work spec-worthy.
Spec-backed Plan
Use when at least one concrete signal exists:
- The human explicitly requests a spec or durable planning artifacts
- Requirements or boundaries need discovery before planning
- The work materially changes architecture, public contracts, data models, or cross-system behavior
- Multiple dependent subsystems need decomposition and dependency tracking
- The plan must survive the conversation for handoff, audit, or multi-person coordination
Route through spec-brainstorm. This mode produces:
design.md ← spec-brainstorm (requirements + research + architecture)
plan.json ← spec-plan (tasks, dependencies)
Do not infer substantial work from size alone. If no concrete signal applies, use Inline Plan.
Skill Routing
spec-orchestrator → Select and announce planning mode
spec-brainstorm → Spec-backed discovery + design → design.md
spec-plan → Inline Plan or Spec-backed Plan → approval
spec-implement → Execute approved Spec-backed Plans; track tasks
spec-finish → Post-implementation validation for Spec-backed Plans
code-subagents → Parallel dispatch for Spec-backed Plan tasks
Ordinary bounded work
spec-plan (Inline mode) → approval → implement directly
Substantial work or explicit spec request
spec-brainstorm → spec-plan (Spec-backed Plan) → approval → spec-implement → spec-finish
Truly mechanical change
A typo or exact single-line replacement may skip planning when there is no implementation choice to review. If any choice exists, use an Inline Plan.
Hard Transitions
| After completing... | Next step |
|---|---|
| spec-brainstorm | spec-plan in Spec-backed mode |
| approved Inline Plan | implement the approved plan directly |
| approved Spec-backed Plan | spec-implement in Spec-backed mode |
| spec-implement | spec-finish |
Do not begin implementation without an approved written plan. Spec-backed work must not jump from research to implementation.
Iteration Patterns
The workflow is not purely linear. Expect backflows:
Research → Research (discovery loop)
- Brainstorm reveals new requirements → loop back to discovery phase
- Human adds new scope mid-brainstorm → continue discovery
Plan → Research (design flaw)
- Planning reveals design assumptions are wrong → back to brainstorm
- Tasks can't be decomposed without more context → back to brainstorm
Implement → Plan (missing tasks)
- Implementation reveals missing work → revise the active plan and get approval
- Spec-backed work is blocked on an unplanned dependency → update plan.json
Implement → Research (fundamental issue)
- Inline planning or implementation develops substantial needs → ask the human whether to switch to a Spec-backed Plan
- Implementation reveals spec-backed design is fundamentally wrong → back to brainstorm
Finish → Implement (bugs found)
- Validation finds bugs → back to implement
- Tests failing → back to implement
When to escalate
If you loop 2+ times on the same issue, stop and ask the human:
"We've looped on [issue] twice. Should we reconsider the approach?"
Red Flags — You Are Rationalizing
| What you're thinking | Why it's wrong |
|---|---|
| "This is too simple for a persisted spec" | Use an Inline Plan instead |
| "I already know how to do this" | Knowing how ≠ having the human's approval for how |
| "The human seems impatient" | Wasting time on wrong code is worse than planning |
| "I'll just do a quick prototype" | Prototypes become production. Plan it. |
| "I need to explore the code first" | Gather enough context for an Inline Plan; use brainstorm only when discovery is substantial |
| "Let me just fix this one thing" | One thing becomes three. Plan it. |
| "I can plan in my head" | Plans in your head can't be reviewed or annotated |
| "This is just a refactor" | Refactors still need at least an Inline Plan |
| "I'll write the plan after" | Post-hoc plans are fiction. Plan before. |
| "I need more context first" | Skills tell you HOW to gather context. Check first. |
| "The spec workflow is overkill" | It may be. Default to an Inline Plan unless substantial-work signals exist. |
| "I know what that skill says" | Skills evolve. Read current version. Invoke it. |
| "This feels productive" | Undisciplined action wastes time. Skills prevent this. |
Skill Types
Process skills (spec-brainstorm, spec-plan, spec-implement, spec-finish): Follow exactly. Don't adapt away discipline.
Knowledge skills (oracle-grill-me, oracle-domain-modelling): Adapt principles to context. These inform decisions within the workflow.
Discipline skills (oracle-debug): Strict methodology that must be followed exactly — no adaptation that bypasses root-cause investigation.
Process skills come first. Knowledge skills get invoked by process skills when needed.
User Instructions
"Add X" or "Fix Y" doesn't mean skip workflows. Instructions say WHAT, not HOW. The skills define HOW.