Create an implementation roadmap with ak:plan

Use ak:plan to turn an accepted outcome into an implementation roadmap that another workflow can execute. The Skill inspects the current project, challenges unnecessary scope, records dependencies and file ownership, and verifies the plan before offering implementation.

Choose ak:plan when the delivery needs a roadmap

Use ak:plan when

• A feature, refactor, bug repair, or architecture change needs multiple phases.
• The implementation must coordinate files, interfaces, tests, or dependencies.
• Unknown technology or an unfamiliar codebase requires research before design.
• You want a durable plan that can be validated, red-teamed, or handed to ak:cook.

Choose another workflow when

• The outcome or approach is still unclear. Use ak:brainstorm first.
• You only need a bounded codebase map. Use ak:scout.
• The task is a direct, low-risk edit with accepted requirements. Use ak:cook if a separate plan adds no value.
• You want implementation rather than planning. ak:plan does not change product code.

Run a feature-delivery workflow

Use ak:plan as the decision boundary in a longer chain, not as a command that automatically starts implementation. A reliable feature workflow has seven separate, reviewable stages:

Pass a compact contract to every next stage:

Goal:
Approved scope and non-goals:
Evidence and decisions:
Artifacts produced:
Acceptance criteria:
Open risks or blockers:
Authority granted for this stage:

If a stage fails, resume from that stage with the new evidence. Do not restart the whole chain unless the chosen direction or acceptance criteria changed. Use ak:handoff before switching session, runtime, or Kit.

Prepare the project and runtime

Before you start:

• Complete Onboarding, confirm Engineer Kit is installed, and make the ak CLI available for plan scaffolding and phase-state operations.
• Open the project to plan. Project scope writes under <project>/<plans-dir>/<timestamp>-<slug>/. A project-relative paths.plans value in .agentkit/config.yaml selects <plans-dir>; otherwise it defaults to plans/.
• Provide an accepted outcome, constraints, non-goals, and acceptance criteria.
• Preserve unfinished plan files and identify any known overlapping work.
• Ensure any optional GitHub or AgentWiki projection has the required client, authentication, repository visibility, and publication authority.

Run the Skill

/ak:plan "Add offline draft recovery to the editor. Preserve the current document format, avoid a new service, and cover crash plus reload recovery." --hard --tdd

/ak:plan "Add offline draft recovery to the editor. Preserve the current document format, avoid a new service, and cover crash plus reload recovery." --hard --tdd

$ak:plan "Add offline draft recovery to the editor. Preserve the current document format, avoid a new service, and cover crash plus reload recovery." --hard --tdd

With no clear task, the Skill asks whether to create a plan or run one of its maintenance operations:

Choose planning depth deliberately

The default is --auto, which selects a mode from scope and uncertainty.

Composable options change the artifact or handoff:

Use --global only when you explicitly want the configured global plans root or no project context exists. Confirm exact plan CLI syntax from live ak plan --help; the Skill does not treat remembered subcommands as authority.

The V1 CLI boundary accepts only a safe project-relative paths.plans value. If the value is missing, malformed, absolute, points outside the project or inside .agentkit, or cannot be followed safely, ak plan, journals, and the dashboard fall back to <project>/plans/. An absolute path may still be visible to the Skill, so confirm the CLI-resolved location before scaffolding instead of assuming every plan surface uses that external directory.

Describe the plan clearly

A strong request names:

• Delivery contract: outcome, constraints, non-goals, and acceptance criteria.
• Affected surface: likely modules, public contracts, data, runtime, and deployment boundaries.
• Known risks: compatibility, security, performance, migration, or rollback concerns.
• Load-bearing assumptions: premises the design fails without, which ones current evidence can resolve, and which may break during delivery.
• Evidence: prior research, scout reports, incidents, or existing plans.
• Authority: whether external research, GitHub issue creation, private sharing, or public publication is allowed.

For the draft-recovery example, specify the states that must survive, current format compatibility, storage limits, recovery timing, test expectations, and that no new service or deployment belongs in scope.

Understand what happens during a run

1. The Skill checks plan context. It scans unfinished plans, identifies overlap, and records blocking relationships in both affected plans when confirmed.
2. The Skill establishes the scope baseline. Except for trivial work, it restates the full requested scope, identifies reusable behavior, and rejects unrequested complexity before research. --fast changes planning depth only; it does not authorize scope reduction. With --yagni, the Skill also challenges and cuts requested scope that is not needed for the stated outcome.
3. The Skill selects the mode. It honors an explicit flag or chooses a depth based on uncertainty, blast radius, and independent workstreams.
4. The Skill gathers evidence. It reads repository instructions and current code, tests, contracts, and documentation. Research or scouting is added only when the mode or missing evidence requires it.
5. The Skill designs and scaffolds the plan. It compares worst plausible cases and, when a load-bearing assumption remains unresolved, favors the design that is cheapest to leave. It records the condition under which the design stops meeting its success criteria, switching cost, and lock-in. It then uses live ak plan help and CLI-managed scaffolding, reads every generated stub, and writes plan.md and detailed phase-*.md files.
6. The Skill reviews the plan. Relevant modes perform evidence-backed red team and validation passes. Red-team review targets assumptions that are both essential and breakable during the plan's life. Any accepted change triggers a whole-plan consistency sweep.
7. The Skill projects optional views. It may hydrate a live task view, generate plan.html, create a GitHub issue, or share through AgentWiki according to the requested options and available authentication.
8. The Skill prepares the handoff. It reports the authoritative artifact, unresolved questions, validation state, and an explicit choice to validate, red-team, execute, or stop.

Understand the plan artifacts

The durable source is file-first:

• In project scope, the canonical plan folder is <project>/<plans-dir>/<timestamp>-<slug>/, using the resolved directory boundary above.
• plan.md summarizes the contract, status, dependencies, and phase links.
• phase-NN-*.md records architecture, affected files, steps, success criteria, tests, risks, and dependencies for each phase. For an unresolved breakable assumption, its risk entry includes an observable failure signal and a pre-decided response: adjust within the plan or stop and replan.
• The local plan index is rebuildable from those files. If index and files drift, use the reindex operation shown by live ak plan --help.
• A live task view is a convenience projection. Plan files win when states disagree.
• With --html, plan.html is authoritative and contains visible phase outlines, detailed views, implementation flow, risks, and UI mockups when relevant.
• A GitHub issue or AgentWiki document is a visibility projection, not the canonical plan.

Keep approval and safety with you

The Skill asks before resolving ambiguous cross-plan dependencies, accepting material red-team findings, or changing a significant assumption. It should not recommend implementation while verification failures or whole-plan contradictions remain.

External effects are option-specific:

• --github can create labels, issues, or comments through GitHub. The Skill scans the content for secrets and reports an authentication or publication failure without treating the local plan as failed.
• --wiki defaults to private or workspace sharing. Public documents and hosted HTML sites require explicit authority and may use an external provider.
• --html writes a portable local artifact and can generate local image assets. Image providers may have their own availability or cost boundary.
• archive changes plan-index visibility; it does not delete, move, or erase the Markdown files.

Any commit, push, implementation, deployment, destructive removal, or acceptance of a failed verification remains a separate user decision.

Verify the result

A complete plan should provide:

• A bounded overview with requirements, non-goals, and acceptance criteria.
• Explicit phases, dependencies, priorities, and affected files.
• Architecture and implementation steps grounded in current project evidence.
• Test, security, performance, migration, and rollback considerations where relevant.
• Load-bearing assumptions, the design's stop condition, switching cost, and observable signals with adjust-or-replan responses.
• Verification results with failures or unverified claims kept visible.
• A consistency sweep showing no unresolved contradictions before execution.
• The authoritative artifact path and the status of optional GitHub, AgentWiki, HTML, or task projections.
• Unresolved questions listed last.

Treat the plan as ready for ak:cook only after you approve it, codebase verification has no blocking failure, and the whole-plan consistency sweep has no unresolved contradiction.

Troubleshoot or continue

Continue with ak:plan validate <plan-path> or ak:plan red-team <plan-path> when another gate is useful. After approval, hand the reported plan path to ak:cook. See Projects, artifacts, and checkpoints for recovery and ownership context.

Know the current limits

• Research quality depends on available project evidence, providers, network access, and authentication.
• Runtime task hydration is optional and capability-discovered; it is not guaranteed in every client.
• Cursor slash invocation is user-verified evidence, not proof of full runtime parity.