plankit-cli 1.3.0 → 1.3.1

package/README.md

@@ -1,17 +1,26 @@
-# `plankit` — AI Coding Agent Workflow Command Suite
+# PlanKit CLI — AI Coding Agent Workflow Command Suite
 
-PlanKit is a lightweight, zero-dependency CLI that installs and manages a multi-phase feature workflow for AI coding assistants.
+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.
 
-It creates a predictable artifact structure, agent instruction files, phase specs, phase output reports, and archive records.
+```
+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
+```
 
-## Quick start
+---
+
+## Install
+
+Use it without installing (latest published version):
 
 ```bash
 npx plankit-cli init
 npx plankit-cli plan my-feature "Add configurable templates"
 ```
 
-If installed globally:
+Or install globally once:
 
 ```bash
 npm install -g plankit-cli
@@ -19,6 +28,32 @@ plankit init
 plankit plan my-feature
 ```
 
+> **Check your version** — if behavior ever looks "old", run `plankit --version` first (see [Troubleshooting](#troubleshooting)).
+
+---
+
+## Quick start
+
+```bash
+# 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 |
@@ -26,10 +61,41 @@ plankit plan my-feature
 | `plankit init [--agent <name>]` | Create PlanKit config, artifact folders, spec, and the **selected agent's** folders/commands. Prompts for the agent when none is specified. |
 | `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 and prepare `outputs/phase-N-output.md`. |
-| `plankit review <feature>` | Run verification commands, mark the README archived, and move the feature to `artifacts/archived/`. |
+| `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 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`; default `opencode`). |
+
+### 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
 
@@ -58,51 +124,80 @@ plankit plan my-feature
 }
 ```
 
-Useful options:
+| 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. |
 
-```bash
-plankit init --agent opencode
-plankit init --agent gemini --global-gemini-skills
-plankit init --force
-plankit plan my-feature --phases 4
-plankit plan my-feature --phases "Design,Build,Test"
-plankit review my-feature --test-command "pnpm test" --build-command "pnpm build"
-plankit review my-feature --skip-build
-plankit status --json
-```
+---
 
-### Agent selection
+## Agent selection
 
 `plankit init` installs **only** the folders/commands for the agent you select. Supported agents:
 
-| Agent | What is copied |
+| Agent | What gets installed |
 |---|---|
-| `opencode` (default) | Slash commands under `.opencode/commands/` |
-| `gemini` / `antigravity` | `.gemini/instructions.md` + `angular-*` skills (plus `--global-gemini-skills` under your profile) |
-| `codex` | `AGENTS.md` + Angular commands under `.codex/commands/` |
-| `cursor` | `.cursorrules` + Angular command rules under `.cursor/rules/` |
+| `opencode` (default) | Slash commands under `.opencode/commands/` (`plankit-*.md` + `angular-*.md`). |
+| `gemini` / `antigravity` | `.gemini/instructions.md` + `angular-*` skills. `--global-gemini-skills` also installs skills under `~/.gemini/skills/`. |
+| `codex` | `AGENTS.md` + Angular commands under `.codex/`. |
+| `cursor` | `.cursorrules` + Angular command rules under `.cursor/rules/`. |
+
+Selection order during `init`:
 
-Selection order:
 1. `--agent <name>` flag (non-interactive / CI).
 2. A previously configured `agents.default` in `plankit.config.json`.
 3. An interactive numbered menu (when run in a terminal).
-4. The `opencode` default — announced explicitly so the behavior is never silent.
+4. The `opencode` default — **announced explicitly** so the behavior is never silent.
+
+```bash
+plankit init --agent opencode
+plankit init --agent gemini --global-gemini-skills
+plankit init --agent codex
+plankit init --agent cursor
+```
 
-### Angular command suite
+---
 
-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:
+## Angular command suite
 
-`component-from`, `feature`, `clone-pattern`, `design-match`, `page-from-api`, `form-from-model`, `table-from-model`, `wire-api`, `signalize`, `extract-component`, `split-component`, `extract-store`, `modernize`, `responsive`, `generate-tests`, `fixtures` — plus a shared `angular-project-discovery` reference.
+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:
 
-Every command ships with the exact per-agent binding, so only your selected agent's folder/commands are copied. To include Angular command templates in a custom `templatesDir`, mirror the `templates/angular-commands/` and `templates/angular-skills/` folder layout.
+| 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).
+
+Only your **selected agent's** folder/commands are copied. To customize the Angular command templates in your own `templatesDir`, mirror the `templates/angular-commands/` and `templates/angular-skills/` folder layout from the package.
+
+---
 
 ## Template overrides
 
-Default templates live in the package `templates/` directory. To override them in a project:
+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:
+3. Add files matching the built-in template names. For example:
 
 ```text
 .plankit/templates/
@@ -114,7 +209,57 @@ Default templates live in the package `templates/` directory. To override them i
     plankit-plan.md
 ```
 
-Supported placeholders use `{{name}}` syntax.
+Custom template directories mirror the package `templates/` layout, including `angular-commands/` and `angular-skills/`. Supported placeholders use `{{name}}` syntax (e.g. `{{artifactsDir}}`).
+
+---
+
+## Development
+
+```bash
+# 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`](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:
+
+```bash
+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:
+
+```bash
+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:
+
+```bash
+# 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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plankit-cli",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "description": "PlanKit Command Suite CLI for AI Coding Assistants (Antigravity, OpenCode, Codex, Cursor)",
   "main": "src/cli.js",
   "bin": {

package/src/cli.js

@@ -47,6 +47,11 @@ export async function runCli(args, context = {}) {
       case 'archive':
         archiveFeature(parsed, io);
         break;
+      case 'version':
+      case '--version':
+      case '-v':
+        showVersion(io);
+        break;
       case 'help':
       case '--help':
       case '-h':
@@ -632,6 +637,7 @@ Commands:
   review <feature>                  Run verification and archive a completed feature
   status [--json]                   Show active and archived features
   archive <feature>                 Move a feature to archived without running verification
+  version                          Show the installed PlankKit CLI version
   help                              Show this help message
 
 Options:
@@ -649,3 +655,17 @@ Options:
   --skip-build                      Skip review build command
 `);
 }
+
+function showVersion(io) {
+  const version = readPackageVersion();
+  io.stdout(`plankit-cli v${version}`);
+}
+
+function readPackageVersion() {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf8'));
+    return pkg.version || 'unknown';
+  } catch {
+    return 'unknown';
+  }
+}