Quick Ref / Command

Engineer Kit

/ak:plan

Create implementation plans

Create implementation plans with researched phases, files-first Markdown plans, optional authoritative HTML, GitHub issue projection, private AgentWiki sharing, validation/red-team gates, and handoff-ready context.

01

Pre-create and cross-plan scan

02

Challenge scope

03

Select mode

04

Research and analyze

Rule 01

Plan files are durable; CLI and GitHub are projections or indexes

Rule 02

Do not implement code while planning

Rule 03

Plan the full requested scope unless --yagni explicitly cuts unneeded work

Rule 04

Read generated stubs before writing them

Rule 05

Whole-plan consistency matters more than a polished single phase

Execution Map

Core lanes from input to output, aligned with the command's real execution path.

01

Start

Input, scope, route

  1. 1 Pre-create and cross-plan scan Check active/suggested plan context, scope roots, unfinished plans, overlapping files, shared dependencies, and blockedBy/blocks relationships.
  2. 2 Challenge scope Run scope questions unless the task is trivial; --fast changes depth only, while --yagni is the opt-in that cuts unneeded scope.
  3. 3 Select mode Auto-detect by default or honor exactly one explicit mode flag: --auto, --fast, --hard, --deep, --parallel, --two, --debate, or --ultra.
02

Work

Agent / skill execution

  1. 4 Research and analyze Spawn researchers unless fast mode or reports are already provided, then analyze the codebase and scout when needed.
  2. 5 Scaffold plan files Use live CLI scaffolding when available, then read plan.md and every generated phase stub before writing long content.
  3. 6 Write phases Create files-first plan.md and phase files with overview, requirements, architecture, related files, steps, success criteria, and risk assessment.
03

Verify

Gate, review, validation

  1. 7 Run gates Run red-team, verification, validation, and whole-plan consistency sweeps when required by mode, subcommand, or gate edits.
  2. 8 Produce artifacts If requested, activate frontend-design for authoritative plan.html, then project reviewed plans to GitHub or share through AgentWiki without replacing plan files.
  3. 9 Hydrate and hand off Mirror phases into live task tracking unless skipped, present boundary next-step options, and journal unless --skip-journal or preferences opt out.

Syntax, arguments, subcommands

How to invoke the skill: syntax, positional arguments, shared options, then each subcommand with its own syntax and outcome.

Syntax

/ak:plan [task] [--fast|--hard|--deep|--parallel|--two|--debate|--ultra] [--tdd|--no-tasks] [--html] [--github] [--wiki] [--advice] [--yagni] [--skip-journal] [--no-antv|--no-diagram-design|--no-editorial-visuals]

or

/ak:plan <archive|red-team|validate> <plan.md>

Arguments

[task]

Work to plan

Optional natural-language outcome, constraints, and acceptance criteria. With no clear task, the Skill asks whether to create a new plan or run archive, red-team, or validate.

/ak:plan Add webhook replay protection to payments

Shared options

--auto

Auto-detect mode

Default. Picks one planning mode from scope and uncertainty. Never selects --debate or --ultra.

--fast

Fast

Skip research, red-team, and validation. For small, already-understood work. Does not cut requested scope.

--hard

Hard

Focused research plus red-team; validation optional.

--deep

Deep

Deeper research, per-phase scouts, red-team, and validation for large refactors.

--parallel

Parallel

Exclusive file ownership and a dependency graph for genuinely independent workstreams.

--two

Two approaches

Produce two researched approaches, then review the selected one.

--debate

Debate

Explicit opt-in only. Three independent planners, then synthesis. Never auto-selected.

--ultra

Ultra

Explicit opt-in only. Five candidate plans; a verifier picks one unchanged or rejects all.

--tdd

Tests-first phases

Adds tests-before, refactor, tests-after, and regression gates to relevant phases. Does not implement or run tests.

--no-tasks

Skip live tasks

Do not mirror phases into a live task view. Plan files stay authoritative.

--advice

Advisory supervision

Kongming counsel at phase, stuck, and high-stakes checkpoints. Advice cannot edit or replace plan gates.

--yagni

Cut unneeded scope

Challenge and cut requested work not needed for the stated outcome. Pass the flag downstream.

--skip-journal

Skip journal

Skip the automatic journal step only.

--no-antv

No AntV visuals

Disable optional AntV infographic layers on --html output.

--no-diagram-design

No diagram-design layer

Disable optional editorial workflow-diagram generation on --html output.

--no-editorial-visuals

No editorial visuals

Disable the remaining optional HTML visual layers for this run.

Subcommands

archive Archive
/ak:plan archive

Close plan visibility in the local plan index while keeping Markdown plan files.

Outcome: Index visibility changes; plan.md and phase files are not deleted.

/ak:plan archive
red-team Red-team
/ak:plan red-team <plan.md>

Adversarial review of an existing plan with codebase evidence, then a whole-plan consistency sweep for accepted findings.

<plan.md>
Existing plan.md to review.

Outcome: Findings table with accept/reject dispositions and updated plan files when findings are applied.

/ak:plan red-team plans/checkout-redesign/plan.md
validate Validate
/ak:plan validate <plan.md>

Critical-questions interview of assumptions and acceptance criteria; propagate accepted answers across the whole plan.

<plan.md>
Existing plan.md to validate.

Outcome: Updated plan plus a validation log. Do not recommend cook while contradictions remain.

/ak:plan validate plans/checkout-redesign/plan.md

Output / publish flags

Only flags that change the artifact or publish it. Not the full option set.

--html

HTML plan

Write self-contained plan.html as the authoritative user-facing artifact, with inline workflow diagrams and UI mockups when relevant.

Example

/ak:plan redesign onboarding flow --html
--github

GitHub projection

Create or update a GitHub issue after review gates, include repo-relative plan links, and apply ready to review when gh/auth are available.

Example

/ak:plan payment webhook retry design --github
--wiki

AgentWiki share

Share final reviewed plan docs privately by default; public document/site publishing requires an explicit request and available AgentWiki CLI or MCP.

Example

/ak:plan mobile release roadmap --wiki

Composable flags

How options work together on one invocation. This does not replace the option cards above.

--tdd adds tests-first phase structure.

--no-tasks skips runtime hydration.

--html writes authoritative self-contained plan.html.

--github creates/updates a ready-to-review issue.

--wiki privately shares final reviewed docs by default.

--advice adds kongming supervision.

--yagni cuts unnecessary scope.

--skip-journal disables the automatic journal step.

--no-antv, --no-diagram-design, and --no-editorial-visuals disable optional HTML visual layers.

Modes / Routes

--auto

Auto-detect: analyze task complexity and choose one workflow mode.

Research:
follows mode
Review:
follows mode
Validate:
follows mode
--fast

Fast plan: skip research and red-team for small, understood work.

Research:
skip
Review:
skip
Validate:
skip
--hard

Hard plan: two researchers plus red-team, validation optional.

Research:
2 researchers
Review:
yes
Validate:
optional
--deep

Deep plan: 2-3 researchers, per-phase scouts, red-team, and validation.

Research:
2-3 + scouts
Review:
yes
Validate:
yes
--parallel

Parallel plan: design work that can hand off to parallel implementation.

Research:
2 researchers
Review:
yes
Validate:
optional
--two

Two approaches: compare alternatives before selecting the final plan.

Research:
2+
Review:
after selection
Validate:
after selection
--debate

Debate: three independent planners synthesize a plan; explicit opt-in only.

Research:
2 + shared packet
Review:
yes
Validate:
optional
--ultra

Ultra: five candidate plans and strongest-model verifier selects one unchanged or rejects all; explicit opt-in only.

Research:
2 + shared packet
Review:
yes
Validate:
optional

Special Operations

archive

Archive plans and write journal entries.

red-team

Run adversarial review against an existing plan.

validate

Run critical-questions validation interview for a plan.

Sample Prompt

Concrete invocations for each flag, subcommand, mode, or route available in the live workflow.

Default plan Recommended
/ak:plan Add webhook replay protection to payments
Use when:
Use when work needs phases, architecture, or a roadmap.
Expected:
Plan folder with files-first plan.md, phase files, pre-creation/cross-plan scan, mode-selected gates, task hydration, and handoff options.
Fast plan
/ak:plan Rename settings route --fast
Use when:
Use for small, low-risk, already-understood changes.
Expected:
A compact plan.md and phase files with research, red-team, and validation skipped; still includes codebase analysis and no implementation code.
Deep HTML plan
/ak:plan Rebuild checkout architecture --deep --html
Use when:
Use for complex work that benefits from research, validation, and a visual plan artifact.
Expected:
Deep-mode researchers, per-phase scouts, red-team, validation, and final authoritative plan.html with inline diagrams or UI mockups.
Validate existing plan
/ak:plan validate plans/checkout-redesign/plan.md
Use when:
Use before implementation when assumptions or acceptance criteria may be thin.
Expected:
Critical-questions validation interview, plan-file edits when needed, and a whole-plan consistency sweep before any cook recommendation.
Auto mode
/ak:plan Add rate limiting to public APIs --auto
Use when:
You want the planner to pick one mutually exclusive workflow mode from task complexity.
Expected:
Inspects live ak plan help, selects one mode, writes files-first plan.md and phase stubs, and does not implement code.
Hard plan
/ak:plan Migrate sessions to a durable store --hard
Use when:
The work is risky enough for two researchers plus red-team.
Expected:
Runs two researchers and red-team, writes the plan files, and hard-stops if contradictory mode flags are combined.
Parallel phases
/ak:plan Split search indexing from query API --parallel
Use when:
Independent plan slices can be researched in parallel.
Expected:
Assigns non-overlapping phase ownership, researches those slices in parallel, and still writes one files-first plan tree.
Two approaches
/ak:plan Compare queue versus cron for digest mail --two
Use when:
You need two researched approaches before choosing.
Expected:
Produces two approach sections with trade-offs, keeps one recommended path, and writes plan files without implementing either option.
Debate mode
/ak:plan Choose monolith versus service split for billing --debate
Use when:
A contested architecture choice needs an explicit debate pass.
Expected:
Runs the debate workflow, records competing positions and a decision, and writes the plan without code changes.
Ultra verifier
/ak:plan Design webhook retry semantics --ultra
Use when:
Plan selection is high-stakes and should use a verifier pass.
Expected:
Builds one evidence packet, fans read-only plan candidates, lets a verifier pick one unchanged, and writes that plan to disk.
Archive plan
/ak:plan archive plans/checkout-redesign/plan.md
Use when:
A finished plan should move to the archive without further edits.
Expected:
Moves the completed plan into the archive location and reports the archived path without editing implementation code.
Red-team plan
/ak:plan red-team plans/checkout-redesign/plan.md
Use when:
An existing plan needs an adversarial review before cook.
Expected:
Runs the red-team interview against the live plan files, records findings, and refuses cook while accepted findings remain.

Handled Scope

  • Pre-create and cross-plan scan
  • Challenge scope
  • Select mode
  • Research and analyze
  • Scaffold plan files
  • Write phases

Artifacts Produced

Plan Output

Pattern

<plans-root>/<timestamp>-<slug>/plan.md + phase-NN-*.md; optional plan.html / GitHub issue / AgentWiki URL

The response returns file paths, summary, gate results, optional publish URLs, and next-step options without implementing code.

Related skills

Next