mk-plan

# Planning Create detailed technical implementation plans through research, codebase analysis, solution design, and comprehensive documentation. ## Prerequisites - **MyKit CLI optional:** plan scaffolding uses the `mk` CLI when it is installed. Probe **once** with `command -v mk`; if absent, skip every `mk plan` command below and scaffold the plan files directly with your file tools (same structure, same frontmatter — see `references/plan-organization.md`). Never retry a missing-CLI command. ## CLI Integration This skill orchestrates planning. MyKit CLI owns the plan file scaffolding and phase state mutations whenever `mk` is available. Use these commands instead of hand-editing CLI-managed plan structure: ```bash mk plan create \ --title "{plan title}" \ --phases "{Research},{Implement},{Test}" \ --dir {plan-dir} \ --source skill mk plan create \ --global \ --title "{plan title}" \ --phases "{Research},{Implement},{Test}" \ --dir {plan-dir} \ --source skill cd /absolute/path/to/plan-dir && mk plan check <phase-id> --start cd /absolute/path/to/plan-dir && mk plan check <phase-id> cd /absolute/path/to/plan-dir && mk plan uncheck <phase-id> mk plan status /absolute/path/to/plan.md mk config ui --port 3456 ``` Rules: - Use `mk plan create` to scaffold `plan.md` and `phase-*.md` when the CLI is available. - When `--html` is present, the final user-facing plan artifact is `plan.html`. Use `mk 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 `mk plan create --global ...` or fall back to global scope only when no project context exists. - Use `mk plan check` / `mk 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:** `mk plan create` creates 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. ### Mandatory Generated-File Read Pass After `mk plan create` and before the first long Write/Edit to any generated plan file: 1. Enumerate generated files: `plan.md` plus all `phase-*.md`. 2. Read `plan.md`. 3. Read every generated `phase-*.md` stub, including future phases you have not drafted yet. 4. Only after the read pass, write or edit the full content for `plan.md` and each phase. Do not draft or submit a full phase body for a generated stub that has not been read in the current session. ### Canonical Phase File Template Use this structure when filling each `phase-XX-*.md`. Loaded once with the skill — no per-file Read needed to learn it. Frontmatter fields match the CLI's phase schema; section headers match `documentation-management.md` so phase files stay consistent across plans. ````markdown --- phase: <N> title: "<Phase Name>" status: pending # pending | in-progress | completed priority: P2 # P1 | P2 | P3 dependencies: [] # phase IDs this blocks on --- # Phase <id>: <Name> ## Overview <1-2 sentences describing what this phase delivers> ## Requirements - Functional: ... - Non-functional: ... ## Architecture <Design, data flow, component interactions> ## Related Code Files - Create: `path/...` - Modify: `path/...` - Delete: `path/...` ## Implementation Steps 1. ... 2. ... ## Success Criteria - [ ] ... ## Risk Assessment <Risks + mitigations> ```` **IMPORTANT:** Before you start, scan unfinished plans in the active scope first: - Project scope: `./plans/` - Global scope: the configured global plans root - Default when unset: `~/.claude/plans/` If there are relevant plans overlapping your upcoming plan, update them as well. If you're unsure or need more clarifications, use `AskUserQuestion` tool to ask the user. ### Scope Selection - **Project scope** is the default whenever the current working tree has project context. - **Global scope** is allowed only when: - the user explicitly asks for it via `--global`, or - there is no project context to anchor a local plan. - **No project context** means no `.git`, `package.json`, or `CLAUDE.md` was found in the ancestor chain. - Keep scope honest in prose and examples: the skill describes CLI-owned behavior, it does not implement scope resolution itself. ### Cross-Plan Dependency Detection During the pre-creation scan, detect and mark blocking relationships between plans: 1. **Scan** — Read `plan.md` frontmatter of each unfinished plan (status != `completed`/`cancelled`) 2. **Compare scope** — Check overlapping files, shared dependencies, same feature area 3. **Classify relationship:** - New plan needs output of existing plan → new plan `blockedBy: [existing-plan-dir]` - New plan changes something existing plan depends on → existing plan `blockedBy: [new-plan-dir]`, new plan `blocks: [existing-plan-dir]` - Cross-scope dependency → use `global:` or `project:` prefixes - Mutual dependency → both plans reference each other in `blockedBy`/`blocks` 4. **Bidirectional update** — When relationship detected, update BOTH `plan.md` files' frontmatter 5. **Ambiguous?** → Use `AskUserQuestion` with header "Plan Dependency", present detected overlap, ask user to confirm relationship type (blocks/blockedBy/none) **Frontmatter fields**: ```yaml blockedBy: [260301-1200-auth-system] # Same-scope dependency blockedBy: [global:260301-1200-auth-system] # Cross-scope dependency blocks: [project:260228-0900-user-dashboard] # Explicit project-scope dependency ``` **Status interaction:** `mk plan status` is the authoritative inspection surface. Same-scope bare refs stay in the current scope; prefixed refs resolve against the explicit project/global root. Missing refs should warn and show `not found`, not hard-fail the plan. ## Default (No Arguments) If invoked with a task description, proceed with planning workflow. If invoked WITHOUT arguments or with unclear intent, use `AskUserQuestion` to present available operations: | Operation | Description | |-----------|-------------| | `(default)` | Create implementation plan for a task | | `archive` | Write journal entry & archive plans | | `red-team` | Adversarial plan review | | `validate` | Critical questions interview | Present as options via `AskUserQuestion` with header "Planning Operation", question "What would you like to do?". ## Workflow Modes Default: auto-detect planning mode (analyze task complexity and pick mode). | Flag | Mode | Research | Red Team | Validation | Cook Flag | |------|------|----------|----------|------------|-----------| | `--auto` | Auto-detect | Follows mode | Follows mode | Follows mode | Follows mode | | `--fast` | Fast | Skip | Skip | Skip | (none) | | `--hard` | Hard | 2 researchers | Yes | Optional | (none) | | `--deep` | Deep | 2-3 researchers + per-phase scout | Yes | Yes | (none) | | `--parallel` | Parallel | 2 researchers | Yes | Optional | `--parallel` | | `--two` | Two approaches | 2+ researchers | After selection | After selection | (none) | **Composable flags** (combine with any mode): | Flag | Effect | |------|--------| | `--tdd` | Add tests-first structure to each phase for regression-safe refactors | | `--no-tasks` | Skip task hydration | | `--html` | Output a self-contained editorial interactive HTML plan with visible phase outlines, markdown detail modals, and optional generated watercolor technical sketch imagery | | `--github` | Create or update a GitHub issue after plan validation with branch, summary, plan links, open questions, and `ready to review` | | `--wiki` | Publish the final reviewed plan docs or HTML artifact to AgentWiki via CLI or MCP when available | | `--advice` | Run under `kongming` advisory supervision (see Advisory Supervision Mode) | ### Advisory Supervision Mode (`--advice`) When `--advice` is present, run this skill under `kongming` supervision. `kongming` is an advisory-only supervisor: it returns counsel, never code, and the main agent stays responsible for every decision, edit, and gate. Spawn `kongming` at these checkpoints: - **After each planning phase, gate, or major analysis completes** (research, solution design, red-team, validation) - pass the goal, what was concluded, and the evidence; ask for a go/no-go and the next risk to watch. - **When stuck** - repeated failures, a blocked step, or contradictory evidence; pass everything already tried and the exact obstacle. - **Before a high-stakes decision** - a design fork, a public-contract or security-sensitive change, or an irreversible action; get counsel first. Invoke with the runtime's live agent-delegation capability using `subagent_type="kongming"` and a prompt containing the task, evidence, approaches tried, and the exact question. Give it enough context to answer in one reply; it does not interview. **When the workflow reaches implementation** through a downstream `/mk-cook` or `/mk-fix` handoff, pass `--advice` to the downstream skill so supervision persists. If the workflow later reaches a PR, watch and fix CI until every required check is green, then spawn `kongming` to review the whole implementation and post its assessment plus concrete next steps as a comment directly on the PR and the source issue when one exists. `--advice` adds supervision; it never bypasses this skill's approval gates, red-team/validation gates, or security policy. ### HTML Output Mode (`--html`) When `--html` is present, activate `/mk-frontend-design` before composing the HTML artifact. If `mk-frontend-design` requires design intelligence, follow its `mk-ui-ux-pro-max` activation rule before styling. **Artifact rules:** - Write the primary output as `plan.html` in the selected plan directory. - The HTML file must be self-contained: inline CSS and JavaScript, no build step, no network-required assets. - If generated image assets are used, embed selected images as data URIs so `plan.html` remains portable; keep source images under `{plan-dir}/assets/` for review only. - Generate `plan.html` after red-team and validation gates so the HTML reflects the final reviewed plan. Markdown files produced for CLI scaffolding or gate compatibility are not the user-facing deliverable in this mode. - If another workflow requires `plan.md` (for example `--github`), keep `plan.md` as a concise index that points to `plan.html`; do not duplicate the full plan body unless a downstream `/mk-cook` handoff explicitly needs it. - Include accessible responsive UI, keyboard-friendly controls, and reduced motion handling. **Content requirements:** - Plan overview and phase roadmap. - Main page must show a concise outline summary for every phase: title, status, priority, dependencies, objective, 3-6 key bullets, related files, success criteria highlights, and test/validation gate when known. - Each phase outline must open a detail modal rendering the full phase markdown: headings, lists, checkboxes, tables, fenced code, inline code, blockquotes, links, horizontal rules, and frontmatter metadata. Escape raw HTML unless a trusted sanitizer is bundled inline. - User flows. - Diagrams and charts rendered directly in HTML/CSS/SVG/Canvas. - Interactive affordances such as tabs, filters, expandable risks, or chart toggles when useful. - Citations as visible URLs for external sources, GitHub issues, docs, and any web references used. - Open questions section; write "None" when there are no unresolved questions. **Generated illustration requirements:** - For architecture, sequence, or data-flow figures, prefer the `archify` skill: author a typed JSON spec and deliver a validated standalone HTML/SVG diagram (`node .claude/skills/archify/bin/archify.mjs deliver ...`), then link or embed it beside the plan. Deterministic and reviewable — use it before reaching for generated raster imagery. - If `imagegen`, built-in `image_gen`, or `create_image` is available, generate 1-3 raster illustrations for the HTML. - Prompt style: technical sketch, watercolor wash, hand-drawn engineering notebook, ink linework, warm paper, muted red/gold accents, no text, no logo, no watermark. - If image generation is unavailable or fails, continue with typographic diagrams / CSS-only structure and state the limitation in the final response. **Design direction:** - Use the editorial magazine style contract from the user's supplied guideline when present; otherwise use this built-in contract. - Use warm paper `#faf7f2`, paper panels `#f0ebe1`, ink `#0a0a0a`, muted `#6b6258`, accent red `#b8232c`, hairline dividers, serif display, mono labels, and restrained sans body. - Use print-editorial structure: cover section, running mono slide tags/folios, generous whitespace, asymmetric grids, rule lines, pull quotes, stat bands, and fixed nav dots when useful. - Avoid gradients, drop shadows, rounded cards, pure white backgrounds, generic SaaS styling, decorative bokeh/orbs, emoji icons, and hidden instructions. - Use accent only for italic serif emphasis, eyebrows, active states, left rules, and small data highlights. Include subtle CSS paper grain. - Keep typography readable on mobile and desktop; no horizontal scrolling. ### GitHub Issue Mode (`--github`) When `--github` is present, create or update a GitHub issue after validation and red-team gates finish and before implementation handoff. **Required issue fields:** - Branch name from `git branch --show-current`. - Plan summary. - Repo-relative link to `plan.md`. - Repo-relative link to `plan.html` when `--html` is present. - Repo-relative link to the brainstorm report when one exists; otherwise state `Brainstorm report: None found`. - Open questions when present; otherwise state `Open questions: None`. - Acceptance criteria from the validated plan. **Required label:** `ready to review`. **Issue creation rules:** ```bash gh label list --json name --jq '.[].name' | grep -Fx "ready to review" >/dev/null \ || gh label create "ready to review" --color "0E8A16" --description "Plan ready for human review" gh issue create --title "<plan title>" --body-file "<body.md>" --label "ready to review" ``` - If an issue already exists for the same plan or branch, update/comment on it instead of creating a duplicate. - All links posted to GitHub must be repo-relative. Do not post absolute local filesystem paths. - Redact secrets, env values, tokens, customer data, private logs, and local machine-specific details before writing issue bodies or comments. - If `gh` cannot create labels or issues, stop and report the exact error. ### Combined `--html --github` `plan.html` is the authoritative plan. Create a short companion `plan.md` index only to satisfy the GitHub issue's stable `plan.md` link requirement. The issue must include both relative links. ### AgentWiki Publish Mode (`--wiki`) When `--wiki` is present, publish the final reviewed plan artifact to AgentWiki after validation/red-team gates and after `plan.html` generation when `--html` is also present. **Availability check:** 1. Prefer AgentWiki CLI when `command -v agentwiki` succeeds and `agentwiki whoami` confirms auth. 2. If CLI is unavailable, use AgentWiki MCP tools when exposed in the session for document create/update, file upload, share links, or static site upload. 3. If neither is available or auth fails, do not block plan creation. Report "AgentWiki publish skipped" with the exact missing capability. **Markdown/document publish:** - Publish a reviewed Markdown artifact. If the plan spans `phase-*.md` files, create `{plan-dir}/wiki-publish.md` as a concise combined document or index before uploading. - CLI path: ```bash agentwiki doc upload "{publish-md}" \ --title "{plan title}" \ --description "{short summary}" \