PlanKit CLI — AI Coding Agent Workflow Command Suite

PlanKit is a lightweight, zero-dependency CLI (Node ≥ 18) that installs and manages a multi-phase feature workflow for AI coding assistants (OpenCode, Gemini/Antigravity, Codex, Cursor). It creates a predictable artifact structure, installs the selected agent's command/skill bindings, generates phase specs and output reports, and archive records — and ships with a per-agent Angular command library so your AI agent can run deterministic, repository-aware Angular workflows.

plankit init          → installs ONE agent's folders/commands + artifact scaffold
plankit plan          → creates artifacts/current/<feature>/ workspace
plankit implement     → executes a phase against spec + prior outputs
plankit review        → verifies, validates Definition of Done, archives

Install

Use it without installing (latest published version):

npx plankit-cli init
npx plankit-cli plan my-feature "Add configurable templates"

Or install globally once:

npm install -g plankit-cli
plankit init
plankit plan my-feature

Check your version — if behavior ever looks "old", run plankit --version first (see Troubleshooting).

Quick start

# 1. Initialize the workspace for your agent (you'll be prompted which one)
plankit init

# 2. Plan a feature (non-interactive agent selection, no prompt)
plankit init --agent opencode

# 3. Create a feature workspace under artifacts/current/<feature>/
plankit plan my-feature "Add configurable templates"

# 4. Prepare Phase 1, execute, then move to Phase 2...
plankit implement my-feature 1
plankit implement my-feature 2

# 5. Review, verify, and archive when done
plankit review my-feature

Commands

| Command | Action | |---|---| | plankit init [--agent <name>] [--framework <name>] | Create PlanKit config, artifact folders, spec, and the selected agent's folders/commands. Prompts for the agent and framework suite(s) when run interactively. | | plankit plan <feature> [requirements] | Create artifacts/current/<feature>/ with README, phase specs, outputs folder, and state metadata. | | plankit clarify <feature> [phase] | Create a clarification artifact for requirements and design decisions. | | plankit implement <feature> <phase> | Validate phase context (spec + prior outputs) and prepare outputs/phase-N-output.md. | | plankit review <feature> | Run verification commands, mark README archived, and move the feature to artifacts/archived/. | | plankit status [--json] | List active and archived features. | | plankit scan [dir] [--json] [--threshold <n>] | Run zero-dependency static analysis, audit health (0-100), extract design tokens, and generate artifacts/.plankit-index.json. | | plankit ui [--no-tui] | Launch interactive terminal feature progress matrix & action dashboard. | | plankit archive <feature> | Move a feature to archived without running verification. | | plankit version / --version / -v | Print the installed version (plankit-cli vX.Y.Z). | | plankit help / --help / -h | Show usage. |

Global options

| Option | Description | |---|---| | --force | Overwrite generated files where safe. | | --dry-run | Show intended actions without writing anything. | | --agent <name> | Select your coding agent during init (opencode, gemini, codex, cursor, all; default opencode). | | --agents <list> | Comma-separated list of coding agents (e.g. opencode,gemini or all). | | --framework <name> | Select framework command suite during init (angular, angular-rescue, vue, dotnet, none, all; default none). | | --frameworks <list> | Comma-separated list of framework command suites (e.g. angular,angular-rescue or vue,dotnet). | | --threshold <score> | Fail scan command with exit code 1 if health score is below threshold (CI quality gate). | | --json | Output scan or status as machine-readable JSON. | | --no-tui | Render static ASCII table instead of interactive dashboard for ui command. |

Plan options

| Option | Description | |---|---| | --phases 3 | Generate N default phases. | | --phases "Design,Build,Test" | Generate named phases. | | --requirements "text" | Set feature requirements. |

Review options

| Option | Description | |---|---| | --test-command "cmd" | Override the review test command. | | --build-command "cmd" | Override the review build command. | | --skip-test | Skip the review test command. | | --skip-build | Skip the review build command. |

Customization

plankit init creates plankit.config.json. By default only one agent is installed — the one you select (interactively, via --agent, or the default opencode).

{
  "artifactsDir": "artifacts",
  "overwrite": "skip",
  "agents": {
    "default": "opencode"
  },
  "defaultPhases": [
    {
      "title": "Foundation & Setup",
      "slug": "foundation",
      "objective": "Establish the base structure, constraints, and integration points.",
      "tasks": ["Confirm scope and constraints", "Prepare base structure"]
    }
  ],
  "verification": {
    "testCommand": "npm test",
    "buildCommand": "npm run build"
  },
  "templatesDir": null
}

| Config key | Type | Default | Purpose | |---|---|---|---| | artifactsDir | string | "artifacts" | Root folder for current/ and archived/ workspaces. | | overwrite | string | "skip" | "skip" or "force" for regenerated files. | | agents.default | string | "opencode" | The agent whose folders/commands init installs. | | defaultPhases | array | 3 phases | Phases used when --phases isn't given. | | verification | object | npm test / npm run build | Commands run by plankit review. | | templatesDir | string \| null | null | Custom template overrides directory. |

Agent selection

plankit init installs configuration and command bindings for your selected agent(s). You can select a single agent, multiple agents, or all agents at once. Supported agents:

| Agent | What gets installed | |---|---| | opencode (default) | Slash commands under .opencode/commands/ (plankit-*.md + framework command files). | | gemini / antigravity | .gemini/instructions.md + skills under .gemini/skills/. --global-gemini-skills also installs skills under ~/.gemini/skills/. | | codex | AGENTS.md + framework commands under .codex/. | | cursor | .cursorrules + framework command rules under .cursor/rules/. |

Selection order during init:

1. --agent <name> or --agents <list> flags (e.g. --agents opencode,gemini or --agents all).
2. Configured agents in plankit.config.json (agents.list or agents.default).
3. An interactive numbered menu supporting comma-separated numbers (e.g. 1,2) or all.
4. The opencode default — announced explicitly so the behavior is never silent.

# Single agent setup
plankit init --agent opencode
plankit init --agent gemini --global-gemini-skills
plankit init --agent cursor

# Multi-agent setup (configure multiple assistants simultaneously)
plankit init --agents opencode,gemini
plankit init --agents all

Static analysis engine (plankit scan)

PlanKit ships with an ultra-fast, zero-dependency static analyzer that audits codebase modernization health without burning LLM tokens:

# Run audit and output terminal report + save artifacts/.plankit-index.json
plankit scan

# Output machine-readable JSON metrics
plankit scan --json

# CI Quality Gate: fail if health score drops below threshold
plankit scan --threshold 80

What it checks:

• Vue SFC Architecture: Options API vs <script setup> ratio, TypeScript vs JavaScript, Pinia vs Vuex vs composables.
• Design Token Mining: Automatically detects repeated hex colors, font sizes, margins, and paddings across templates and styles.
• .NET Architecture: Target frameworks, layer dependency boundaries (Clean Architecture / Vertical Slices), and Minimal APIs vs Controllers.
• Modernization Hotspots: Flags god components (> 400 lines), deprecated deep selectors (::v-deep, /deep/), mixins, and layer boundary violations.
• Index Generation: Saves artifacts/.plankit-index.json so AI agents can query repository intelligence immediately.

Interactive feature dashboard (plankit ui)

Launch a terminal UI to visualize active features, phase completion status, and trigger development workflows with single keystrokes:

# Launch interactive TUI
plankit ui

# Non-interactive / CI ASCII table output
plankit ui --no-tui

Interactive Actions:

• [↑/↓] or [j/k]: Navigate between active features.
• [i]: Prepare and validate implementation context for the next pending phase.
• [c]: Generate a design alignment and clarification artifact.
• [r]: Review, verify DoD, and archive completed feature.
• [s]: Run the repository static scan and view live health scorecard.
• [q]: Exit dashboard.

Visual web dashboard companion (plankit serve)

Launch an interactive, local browser companion on your choice of port:

# Launch on default port 4200 (prompts if run interactively without flag)
plankit serve

# Specify custom port
plankit serve --port 5000
plankit web -p 8080

Features:

• Feature Matrix & Progress Board: Visual cards with completion percentages and modal document viewers for specs and outputs.
• Architecture Health Scorecard: Live breakdown of Vue <script setup> ratio, TypeScript ratio, Pinia stores, and .NET Clean Architecture violations.
• Design Token Palette: Interactive color swatches with one-click hex copying and rule usage counts mined across the repository.
• Hotspots Backlog: Filterable table of god components, deprecated deep selectors, mixins, and legacy code.
• Zero Dependencies: Powered by native node:http, starts in under 20ms.

Framework command suites

During plankit init, PlanKit prompts you to choose optional framework-specific command suites (or pass --framework <name> / --frameworks <names>):

• None: Installs only the core PlanKit feature planning workflow.
• Angular: Installs 17 Angular engineering workflows.
• Vue: Installs 15 Vue modernization and architectural standardization workflows.
• .NET: Installs 10 .NET clean architecture and API engineering workflows.
• All: Installs all supported framework suites.

Vue modernization suite (--framework vue)

Designed for legacy and mixed Vue codebases (JavaScript/TypeScript, Options API, Composition API, <script setup>, Vuex/Pinia) following the PlanKit Vue Modernization Specification:

| Command | Purpose | |---|---| | vue-health | Audit Vue codebase health, tech debt score, Options vs Composition ratio, and modernization risks. | | vue-pattern-map | Map architectural patterns across state, data fetching, styling, and components. | | vue-target-architecture | Define or inspect target architectural conventions (Vue 3, <script setup>, TS, Pinia). | | vue-legacy-map | Catalog legacy Vue files, mixins, filters, Options API components, and hotspots. | | vue-standardize | Refactor a component or composable to conform to the established target architecture. | | vue-migration-plan | Generate an incremental, phased migration plan for a legacy feature slice. | | js-to-ts | Convert JavaScript Vue SFCs and utility modules to TypeScript with typed props/emits. | | vue-style-audit | Audit styling patterns, global vs scoped CSS/SCSS, deep selectors, and hardcoded values. | | design-token-discover | Discover repeated color literals, typography, spacing, and shadows into token candidates. | | design-token-migrate | Migrate hardcoded styles in Vue components to standardized design tokens. | | state-strategy-audit | Audit Vuex vs Pinia vs composables; detect state duplication and reactivity leaks. | | reactivity-audit | Audit reactivity anti-patterns (destructuring props without toRefs, watcher leaks). | | component-pattern-audit | Audit SFC component design, god components, prop drilling, and emits declarations. | | vue-modernize-slice | Orchestrate an end-to-end modernization of a Vue feature slice with validation. | | vue-guardrails | Configure ESLint rules and TypeScript strict settings to prevent legacy regressions. |

.NET clean architecture suite (--framework dotnet)

Designed for ASP.NET Core and .NET solutions following Clean Architecture and Vertical Slice patterns:

| Command | Purpose | |---|---| | dotnet-health | Audit solution health: SDK versions, NuGet packages, vulnerabilities, and compiler warnings. | | dotnet-architecture-audit | Audit layer dependencies (Domain, Application, Infrastructure, API) and circular references. | | dotnet-feature | Build an end-to-end vertical slice feature (Command/Query, MediatR, FluentValidation, Endpoint). | | dotnet-endpoint-from-model | Generate ASP.NET Core Minimal API or Controller endpoints with typed results and error handling. | | dotnet-migrate-minimal-api | Migrate traditional controllers to modern Minimal API route groups. | | dotnet-ef-migration | Safe Entity Framework Core migration lifecycle: entity check, migration, SQL preview, rollback. | | dotnet-extract-service | Refactor fat services into isolated CQRS handlers or domain services. | | dotnet-generate-tests | Generate xUnit/NUnit tests with FluentAssertions and WebApplicationFactory integration tests. | | dotnet-clean-guardrails | Generate NetArchTest architectural unit tests and EditorConfig rules to guard layer boundaries. | | dotnet-modernize | Upgrade legacy C# syntax to modern C# 12+ / .NET 8+ patterns (primary constructors, collection expressions). |

Angular command suite (--framework angular)

Alongside the phase workflow, init installs a per-agent Angular command library that gives your AI assistant 16 deterministic Angular engineering workflows, driven by repository discovery rather than generic prompts:

| Command | Purpose | |---|---| | component-from | Generate a component from an existing one as an architectural reference. | | feature | Build a whole feature respecting existing architecture. | | clone-pattern | Clone any architectural pattern (feature/page/dialog/store/form/table/service). | | design-match | Align a generated component with the design system. | | page-from-api | Scaffold a page from a typed API method, deriving UI from the contract. | | form-from-model | Build a form from a domain model with inferred controls/validation. | | table-from-model | Build a table with semantic columns and correct formatting. | | wire-api | Replace mock data with real API calls using the dominant data-access pattern. | | signalize | Migrate state to Signals only where appropriate. | | extract-component | Extract a template region into a child component with a clean API. | | split-component | Decompose an oversized component into focused parts. | | extract-store | Move server/user state into a feature-scoped store. | | modernize | Orchestrate incremental Angular migrations (build/test between stages). | | responsive | Make a component responsive per project conventions. | | generate-tests | Write behavior-focused tests, filling coverage gaps only. | | fixtures | Generate reusable fixtures from TypeScript domain models. |

Plus a shared angular-project-discovery reference that every command leans on (Angular version, standalone vs NgModule, Signals/RxJS, state management, forms strategy, UI library, styling, testing, conventions, architecture).

Angular Rescue suite (--framework angular-rescue)

[!IMPORTANT] Independent Framework Suite: angular-rescue is an independent, behavior-preserving surgical refactoring system designed for mature, complex, or legacy Angular applications. It does not follow or bundle into --framework angular. You can install either suite individually, or both via --frameworks angular,angular-rescue.

The suite provides 33 deep rescue commands across 4 safety-gated groups following the evidence-driven surgery contract (NO BIG-BANG, contract capture first, --preserve-dom by default):

Group A: Discovery & Diagnosis (R0 Read-Only)

| Command | Risk | Purpose | |---|---|---| | angular-rescue-discover | R0 | Multi-generation architecture fingerprinting & intelligence profile. | | angular-health-map | R0 | 13-dimension health evaluation without false aggregate metrics. | | angular-hotspots | R0 | Multi-factor pressure scoring heuristic for prioritization. | | architecture-clusters | R0 | Identifies legacy, transitional, and preferred architecture patterns. | | dependency-tangle | R0 | Uncovers feature cycles, shared-folder leaks, and vendor coupling. | | component-complexity | R0 | Analyzes 13 responsibility categories before splitting components. | | component-tree-audit | R0 | Audits pass-through wrappers and deep DOM hierarchies. | | duplication-map | R0 | Maps exact, structural, and domain duplication with consumer analysis. | | state-chaos | R0 | Maps state ownership across services, stores, signals, forms, and routes. | | subscription-audit | R0 | Identifies RxJS lifecycle defect risks and unmanaged subscriptions. | | memory-risk | R0 | Analyzes observers, listeners, blob URLs, and detached DOM nodes. | | render-hotspots | R0 | Identifies template function calls, PrimeNG table issues, and nested loops. | | api-flow-audit | R0 | Traces full-stack request/response/error flows and transport leaks. | | result-pattern-audit | R0 | Deep analysis of Result<T> and PaginatedResult<T> envelopes. | | shared-folder-audit | R0 | Classifies overloaded shared folder artifacts by true ownership. | | metronic-boundary-audit | R0 | Isolates Metronic/theme code from domain application architecture. |

Group B: Behavior Protection (R0 Read-Only Gates)

| Command | Risk | Purpose | |---|---|---| | behavior-baseline | R0 | Captures observable features, forms, and routes in .plankit/baselines/. | | ui-baseline | R0 | Captures DOM hierarchies, PrimeNG structures, and responsive states. | | component-contract | R0 | Captures inputs, outputs, ViewChild, and DI boundaries before refactoring. | | runtime-profile | R0 | Scenario-driven profiling plans for heap, DOM nodes, and render timing. | | regression-gate | R0 | Quality gate comparing baseline vs current code before next batch. | | rescue-verify | R0 | Final certification of behavior preservation for rescued features. |

Group C: Target Architecture & Planning (R0/R1)

| Command | Risk | Purpose | |---|---|---| | target-angular-architecture | R0 | Defines repository-proven target architecture and guardrails. | | rescue-plan | R0 | Generates an ordered, dependency-aware refactoring roadmap. | | rescue-status | R0 | Tracks per-feature rescue lifecycle in .plankit/rescue-state.json. | | rescue-guardrails | R0/R1 | Enforces preventative rules on new/modified code without failing legacy. |

Group D: Safe Transformations (R1-R6 Bounded Surgery)

| Command | Risk | Purpose | |---|---|---| | safe-extract | R1-R2 | Logic extraction (constants, pure functions, mappers) with --preserve-dom. | | safe-split-component | R4-R5 | Multi-stage component decomposition enforcing contract capture first. | | safe-dedupe | R1-R4 | Consolidates proven duplication while preventing premature abstraction. | | safe-state-refactor | R3-R4 | Incremental state ownership migration with consumer analysis. | | safe-result-refactor | R3-R6 | Bounded normalization of Result<T> and API mapping. | | safe-feature-refactor | Varies | Composes safe rescue primitives for a bounded feature scope. | | angular-rescue | Varies | Flagship surgical rescue command orchestrating the audit-plan-apply cycle. |

Only your selected agent's folder/commands are copied. To customize the command templates in your own templatesDir, mirror the templates/<framework>-commands/ and templates/<framework>-skills/ folder layout from the package.

Template overrides

Default templates live inside the package at templates/. To override them in a project:

1. Create a directory such as .plankit/templates.
2. Set "templatesDir": ".plankit/templates" in plankit.config.json.
3. Add files matching the built-in template names. For example:

.plankit/templates/
  AGENTS.md
  PLANKIT.md
  feature-readme.md
  phase-spec.md
  opencode/
    plankit-plan.md

Custom template directories mirror the package templates/ layout, including angular-commands/ and angular-skills/. Supported placeholders use {{name}} syntax (e.g. {{artifactsDir}}).

Development

# Run the test suite (Node's built-in test runner)
npm test

# Inspect the exact tarball contents
npm pack --dry-run

# Build the per-agent Angular command/skill bundles from canonical sources
node scripts/generate-angular-bundles.mjs

The Angular command files are generated from the canonical definitions in scripts/generate-angular-bundles.mjs. Edit that file (or the per-command body) and re-run the generator; don't hand-edit the four generated folders.

Troubleshooting

"I ran plankit init but I still see the old all-agents behavior / no Angular commands."

Almost always a stale global install. First confirm what's really running:

plankit --version          # should be >= 1.3.1
npm view plankit-cli version   # latest published version

If plankit --version reports an old version (or an error), update:

npm install -g plankit-cli@latest

Two-competing-global-installs (Windows/macOS PATH shadowing): it's possible to have plankit-cli installed under two global locations — your npm prefix (e.g. D:\node24\...) and a separately-linked one (e.g. %APPDATA%\npm\...). If npm install -g reports success but plankit --version still shows old output, the plankit shim earlier on your PATH may point at the stale copy. Fix by installing into the location that actually resolves:

# Windows PowerShell (check your APPDATA npm location)
npm install -g --prefix "$env:APPDATA\npm" plankit-cli@latest

# Or find every copy and refresh:
where.exe plankit

Then restart your terminal so PATH refreshes and verify with plankit --version.

Verification

npm test
npm pack --dry-run