ak-plan

name	ak:plan
description	Plan implementations, design architectures, create technical roadmaps with detailed phases. Use for feature planning, system design, solution architecture, implementation strategy, phase documentation, editorial self-contained HTML plan artifacts with --html, and AgentWiki publishing with --wiki.
user-invocable	true
when_to_use	Invoke when work needs phases, architecture, or a roadmap.
category	utilities
keywords	["planning","architecture","phases","roadmap","html","github","wiki","agentwiki","publish"]
argument-hint	[task] [--fast|--hard|--deep|--parallel|--two] [--tdd|--no-tasks] [--html] [--github] [--wiki] OR [archive|red-team|validate]
license	MIT
metadata	{"author":"agentkit","version":"1.1.0"}

Planning

Create detailed technical implementation plans through research, codebase analysis, solution design, and comprehensive documentation.

Prerequisites

• AgentKit CLI required: This skill requires the ak CLI for plan operations. Install AgentKit before using CLI-managed plan scaffolding or status updates.

CLI Integration

This skill orchestrates planning, but AgentKit CLI owns plan file scaffolding and phase state mutations whenever ak is available.

Use these commands instead of hand-editing CLI-managed plan structure:

ak plan create "{plan title}" --basedir /absolute/path/to/plans
ak plan add-phase /absolute/path/to/plan-dir "Implement"
ak plan add-phase /absolute/path/to/plan-dir "Test"
ak plan check /absolute/path/to/plan-dir/phase-01-start.md
ak plan uncheck /absolute/path/to/plan-dir/phase-01-start.md
ak plan status /absolute/path/to/plan-dir
ak config start --port 3456 --no-open

Rules:

• Use ak plan create to scaffold plan.md and the starter phase-*.md when the CLI is available.
• When --html is present, the final user-facing plan artifact is plan.html. Use ak plan create only when a plan directory, active-plan metadata, or a --github companion plan.md index is needed. Do not duplicate the full plan body across Markdown and HTML.
• Default scope is project-local (./plans/ under the current project).
• Global scope is conditional: use the configured global plans root only when the user asks for global planning or no project context exists.
• Use ak plan check / ak plan uncheck for phase status changes.
• Do not hand-edit the phases table for status toggles or structural updates when CLI commands are available.
• Use the dashboard at http://localhost:3456/plans for visual plan management.
• Generated-file write guard: ak plan create and ak plan add-phase create existing plan.md and phase-XX-*.md stub files. Before composing long replacement content, run a read pass over plan.md and every generated phase stub. A directory listing is not enough. Claude Code enforces Read-before-Write on existing files; skipping any stub read causes that file's Write to be rejected after wasting the full Write payload. The stubs are tiny, so read them all first, then fill them.