plankit-cli 1.0.0 → 1.2.0

package/README.md

@@ -1,71 +1,118 @@
 # `plankit` — AI Coding Agent Workflow Command Suite
 
-> [!IMPORTANT]
-> **PlanKit CLI** is a lightweight, zero-dependency command-line tool that installs the **PlanKit Command Suite** (`plankit.plan`, `plankit.clarify`, `plankit.implement`, `plankit.review`) into any project. Works seamlessly with **Google Antigravity**, **OpenCode**, **Codex**, **Cursor**, and **Claude Code**.
+PlanKit is a lightweight, zero-dependency CLI that installs and manages a multi-phase feature workflow for AI coding assistants.
 
----
+It creates a predictable artifact structure, agent instruction files, phase specs, phase output reports, and archive records.
 
-## Quick Start (Usage without installation)
-
-Run in any project directory:
+## Quick start
 
 ```bash
 npx plankit-cli init
+npx plankit-cli plan my-feature "Add configurable templates"
 ```
 
-This single command sets up all required configuration files and folders:
-- `artifacts/current/` & `artifacts/archived/`
-- `artifacts/PLANKIT.md` (Specification)
-- `.gemini/instructions.md` (Antigravity binding)
-- `.opencode/commands/*.md` (OpenCode Markdown custom commands)
-- `.cursorrules` (Cursor rules)
-- `AGENTS.md` (Codex / Claude Code universal instructions)
-
----
-
-## Global Installation (Optional)
-
-Install globally using `npm`:
+If installed globally:
 
 ```bash
 npm install -g plankit-cli
+plankit init
+plankit plan my-feature
+```
+
+## Commands
+
+| Command | Action |
+|---|---|
+| `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 status [--json]` | List active and archived features. |
+| `plankit archive <feature>` | Move a feature to archived without running verification. |
+
+## 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`).
+
+```json
+{
+  "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
+}
 ```
 
-Then run anywhere:
+Useful options:
 
 ```bash
-plankit init
-plankit plan <feature-name>
-plankit status
-plankit archive <feature-name>
+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
 
-## Commands Summary
+`plankit init` installs **only** the folders/commands for the agent you select. Supported agents:
 
-| Command | Action |
+| Agent | What is copied |
 |---|---|
-| `plankit init` | Scaffolds PlanKit configs & folders in the current directory. |
-| `plankit plan <feature>` | Scaffolds a new feature workspace under `artifacts/current/<feature>/`. |
-| `plankit status` | Lists all active and archived features. |
-| `plankit archive <feature>` | Moves a completed feature to `artifacts/archived/<feature>/`. |
-
----
-
-## Publishing to NPM
-
-To publish this package to the official NPM registry so anyone in the world can run `npx plankit init`:
-
-1. Log in to your NPM account:
-   ```bash
-   npm login
-   ```
-2. Navigate to the `packages/plankit` directory:
-   ```bash
-   cd packages/plankit
-   ```
-3. Publish to NPM:
-   ```bash
-   npm publish --access public
-   ```
+| `opencode` (default) | `AGENTS.md`-style slash commands under `.opencode/commands/` |
+| `gemini` / `antigravity` | `.gemini/instructions.md` (plus `--global-gemini-skills` under your profile) |
+| `codex` | `AGENTS.md` |
+| `cursor` | `.cursorrules` |
+
+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.
+
+When the Angular command/skill library ships, each agent's `commandBundles` entry installs that agent's `commands/`/`skills/` folder automatically with no CLI changes.
+
+## Template overrides
+
+Default templates live in the package `templates/` directory. 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:
+
+```text
+.plankit/templates/
+  AGENTS.md
+  PLANKIT.md
+  feature-readme.md
+  phase-spec.md
+  opencode/
+    plankit-plan.md
+```
+
+Supported placeholders use `{{name}}` syntax.
+
+## Verification
+
+```bash
+npm test
+npm pack --dry-run
+```

package/bin/plankit.js

@@ -3,3 +3,4 @@
 import { runCli } from '../src/cli.js';
 
 runCli(process.argv.slice(2));
+

package/package.json

@@ -1,12 +1,21 @@
 {
   "name": "plankit-cli",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "PlanKit Command Suite CLI for AI Coding Assistants (Antigravity, OpenCode, Codex, Cursor)",
   "main": "src/cli.js",
   "bin": {
     "plankit": "bin/plankit.js"
   },
   "type": "module",
+  "files": [
+    "bin",
+    "src",
+    "templates",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
   "scripts": {
     "start": "node bin/plankit.js",
     "test": "node --test"

package/src/agents.js

@@ -0,0 +1,98 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const DEFAULT_AGENT = 'opencode';
+
+export const AGENT_ORDER = ['opencode', 'gemini', 'codex', 'cursor'];
+
+export const GEMINI_SKILL_ENTRIES = [
+  ['plankit', 'PlanKit Command Suite master skill.'],
+  ['plankit-plan', 'Initialize a feature workspace.'],
+  ['plankit-clarify', 'Analyze requirements and ask targeted clarifying questions.'],
+  ['plankit-implement', 'Prepare phase implementation context and output artifacts.'],
+  ['plankit-review', 'Run verification and archive completed features.']
+];
+
+export const AGENT_DESCRIPTIONS = {
+  codex: 'Copies the PlanKit Command Suite into AGENTS.md (Codex reads AGENTS.md).',
+  cursor: 'Copies the PlanKit rules into .cursorrules for Cursor AI.',
+  opencode: 'Installs the PlanKit slash commands into .opencode/commands/ for OpenCode.',
+  gemini: 'Installs .gemini/instructions.md and optional global Gemini skills (Antigravity alias).'
+};
+
+export const AGENTS = {
+  opencode: {
+    id: 'opencode',
+    label: 'OpenCode',
+    description: AGENT_DESCRIPTIONS.opencode,
+    aliases: [],
+    bindings: [
+      { template: 'opencode/plankit.md', dest: ['.opencode', 'commands', 'plankit.md'] },
+      { template: 'opencode/plankit-plan.md', dest: ['.opencode', 'commands', 'plankit-plan.md'] },
+      { template: 'opencode/plankit-clarify.md', dest: ['.opencode', 'commands', 'plankit-clarify.md'] },
+      { template: 'opencode/plankit-implement.md', dest: ['.opencode', 'commands', 'plankit-implement.md'] },
+      { template: 'opencode/plankit-review.md', dest: ['.opencode', 'commands', 'plankit-review.md'] }
+    ],
+    commandBundles: ['opencode-angular'],
+    globalSkillEntries: null
+  },
+  gemini: {
+    id: 'gemini',
+    label: 'Antigravity / Gemini',
+    description: AGENT_DESCRIPTIONS.gemini,
+    aliases: ['antigravity'],
+    bindings: [
+      { template: 'gemini-instructions.md', dest: ['.gemini', 'instructions.md'] }
+    ],
+    commandBundles: ['gemini-angular'],
+    globalSkillEntries: GEMINI_SKILL_ENTRIES
+  },
+  codex: {
+    id: 'codex',
+    label: 'Codex',
+    description: AGENT_DESCRIPTIONS.codex,
+    aliases: [],
+    bindings: [
+      { template: 'AGENTS.md', dest: ['AGENTS.md'] }
+    ],
+    commandBundles: ['codex-angular'],
+    globalSkillEntries: null
+  },
+  cursor: {
+    id: 'cursor',
+    label: 'Cursor',
+    description: AGENT_DESCRIPTIONS.cursor,
+    aliases: [],
+    bindings: [
+      { template: 'cursorrules', dest: ['.cursorrules'] }
+    ],
+    commandBundles: ['cursor-angular'],
+    globalSkillEntries: null
+  }
+};
+
+export function listAgents() {
+  return AGENT_ORDER.map((id) => AGENTS[id]);
+}
+
+export function validAgentNames() {
+  return AGENT_ORDER.map((id) => AGENTS[id].aliases.concat(id)).flat().join(', ');
+}
+
+export function getAgent(input) {
+  const name = String(input).trim().toLowerCase();
+  if (!name) {
+    return null;
+  }
+  for (const id of AGENT_ORDER) {
+    const agent = AGENTS[id];
+    if (id === name || agent.aliases.includes(name)) {
+      return agent;
+    }
+  }
+  throw new Error(`Unknown agent "${input}". Valid agents: ${validAgentNames()}.`);
+}
+
+export function agentBindingsExist(agent) {
+  return Array.isArray(agent.bindings) && agent.bindings.length > 0;
+}