plankit-cli 1.0.1 → 1.2.0

package/README.md

@@ -23,7 +23,7 @@ plankit plan my-feature
 
 | Command | Action |
 |---|---|
-| `plankit init` | Create PlanKit config, artifact folders, spec, and selected agent bindings. |
+| `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`. |
@@ -33,17 +33,14 @@ plankit plan my-feature
 
 ## Customization
 
-`plankit init` creates `plankit.config.json`:
+`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": {
-    "codex": true,
-    "cursor": true,
-    "opencode": true,
-    "gemini": true
+    "default": "opencode"
   },
   "defaultPhases": [
     {
@@ -64,7 +61,8 @@ plankit plan my-feature
 Useful options:
 
 ```bash
-plankit init --agents codex,opencode
+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"
@@ -73,6 +71,25 @@ plankit review my-feature --skip-build
 plankit status --json
 ```
 
+### Agent selection
+
+`plankit init` installs **only** the folders/commands for the agent you select. Supported agents:
+
+| Agent | What is copied |
+|---|---|
+| `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:

package/bin/plankit.js

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

package/package.json

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

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;
+}

package/src/cli.js

@@ -10,12 +10,15 @@ import {
   loadConfig,
   normalizePhases,
   parsePhaseFlag,
+  resolveConfiguredAgent,
   safeJoin,
   writeManagedFile
 } from './config.js';
-import { renderList, renderTemplate } from './templates.js';
+import { renderList, renderTemplate, packageRoot } from './templates.js';
+import { DEFAULT_AGENT, GEMINI_SKILL_ENTRIES, getAgent, listAgents, validAgentNames } from './agents.js';
+import { bundleEntry, bundleSourceExists } from './commandBundles.js';
 
-export function runCli(args, context = {}) {
+export async function runCli(args, context = {}) {
   const io = createIo(context);
 
   try {
@@ -24,7 +27,7 @@ export function runCli(args, context = {}) {
 
     switch (command) {
       case 'init':
-        initProject(parsed, io);
+        await initProject(parsed, io);
         break;
       case 'plan':
         planFeature(parsed, io);
@@ -59,10 +62,10 @@ export function runCli(args, context = {}) {
   }
 }
 
-function initProject(parsed, io) {
-  const { config } = loadConfig(io.cwd);
+async function initProject(parsed, io) {
+  const { config, path: configPath } = loadConfig(io.cwd);
   const options = writeOptions(parsed, config);
-  const agents = selectedAgents(parsed, config);
+  const agent = await resolveAgent(parsed, config, io, configPath);
   const results = [];
   const artifactsDir = safeJoin(io.cwd, config.artifactsDir);
 
@@ -78,53 +81,98 @@ function initProject(parsed, io) {
   results.push(writeManagedFile(path.join(artifactsDir, 'archived', '.gitkeep'), '', options));
   results.push(createDefaultConfigFile(io.cwd, options));
 
-  if (agents.gemini) {
+  for (const binding of agent.bindings) {
     results.push(writeManagedFile(
-      safeJoin(io.cwd, '.gemini', 'instructions.md'),
-      renderTemplate(config, 'gemini-instructions.md', { artifactsDir: config.artifactsDir }, io.cwd),
+      safeJoin(io.cwd, ...binding.dest),
+      renderTemplate(config, binding.template, { artifactsDir: config.artifactsDir, agent: agent.id }, io.cwd),
       options
     ));
   }
 
-  if (agents.cursor) {
-    results.push(writeManagedFile(
-      safeJoin(io.cwd, '.cursorrules'),
-      renderTemplate(config, 'cursorrules', { artifactsDir: config.artifactsDir }, io.cwd),
-      options
-    ));
+  for (const bundleName of agent.commandBundles) {
+    results.push(installCommandBundle(agent, bundleName, config, options, io));
   }
 
-  if (agents.codex) {
-    results.push(writeManagedFile(
-      safeJoin(io.cwd, 'AGENTS.md'),
-      renderTemplate(config, 'AGENTS.md', { artifactsDir: config.artifactsDir }, io.cwd),
-      options
-    ));
+  if (parsed.flags['global-gemini-skills'] && agent.id === 'gemini') {
+    results.push(...installGlobalGeminiSkills(config, options));
   }
 
-  if (agents.opencode) {
-    const commandsDir = safeJoin(io.cwd, '.opencode', 'commands');
-    for (const fileName of [
-      'plankit-plan.md',
-      'plankit-clarify.md',
-      'plankit-implement.md',
-      'plankit-review.md',
-      'plankit.md'
-    ]) {
-      results.push(writeManagedFile(
-        path.join(commandsDir, fileName),
-        renderTemplate(config, path.join('opencode', fileName), { artifactsDir: config.artifactsDir }, io.cwd),
-        options
-      ));
-    }
+  io.stdout(`PlanKit initialized for agent "${agent.id}".`);
+  printResults(results, io);
+}
+
+function installCommandBundle(agent, bundleName, config, options, io) {
+  const entry = bundleEntry(bundleName);
+  if (!entry) {
+    return { action: 'info', path: bundleName, message: `unknown bundle for ${agent.id}` };
+  }
+  if (!bundleSourceExists(bundleName, io.cwd, config)) {
+    return {
+      action: 'info',
+      path: bundleName,
+      message: `${entry.label} for ${agent.id} not shipped yet`
+    };
   }
 
-  if (parsed.flags['global-gemini-skills']) {
-    results.push(...installGlobalGeminiSkills(config, options));
+  if (entry.global && options.dryRun) {
+    return { action: 'info', path: bundleName, message: 'would install to user profile (dry run)' };
   }
 
-  io.stdout('PlanKit initialized.');
-  printResults(results, io);
+  const targetRoot = entry.global
+    ? path.join(os.homedir(), ...entry.dest)
+    : safeJoin(io.cwd, ...entry.dest);
+
+  const sourceRoot = resolveBundleSource(entry.src, io.cwd, config);
+  ensureDir(targetRoot, options);
+  return copyBundleRecursive(sourceRoot, targetRoot, options);
+}
+
+function resolveBundleSource(src, cwd, config) {
+  const customPath = config.templatesDir
+    ? path.resolve(cwd, config.templatesDir, src)
+    : null;
+  if (customPath && fs.existsSync(customPath)) {
+    return customPath;
+  }
+  return path.join(packageRoot, 'templates', src);
+}
+
+function copyBundleRecursive(sourceRoot, targetRoot, options) {
+  const copyResults = [];
+  const files = collectFiles(sourceRoot);
+  for (const rel of files) {
+    const srcFile = path.join(sourceRoot, rel);
+    const destFile = path.join(targetRoot, rel);
+    const rendered = renderTemplateFromFile(srcFile);
+    copyResults.push(writeManagedFile(destFile, rendered, options));
+  }
+  const wroteAny = copyResults.some((result) => result && result.action !== 'skipped' && result.action !== 'unchanged');
+  return {
+    action: wroteAny ? 'copied' : 'unchanged',
+    path: targetRoot,
+    copies: copyResults
+  };
+}
+
+function collectFiles(dir) {
+  const results = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...collectFiles(full).map((rel) => path.join(entry.name, rel)));
+    } else {
+      results.push(entry.name);
+    }
+  }
+  return results;
+}
+
+function renderTemplateFromFile(filePath) {
+  return fs.readFileSync(filePath, 'utf8')
+    .replace(/\{\{([a-zA-Z0-9_.-]+)\}\}/g, (_, key) => {
+      const maps = { artifactsDir: 'artifacts' };
+      return key in maps ? maps[key] : '';
+    });
 }
 
 function planFeature(parsed, io) {
@@ -372,15 +420,8 @@ function runVerificationCommand(command, io) {
 
 function installGlobalGeminiSkills(config, options) {
   const globalSkillsDir = path.join(os.homedir(), '.gemini', 'skills');
-  const skills = [
-    ['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.']
-  ];
-
-  return skills.map(([name, description]) => writeManagedFile(
+
+  return GEMINI_SKILL_ENTRIES.map(([name, description]) => writeManagedFile(
     path.join(globalSkillsDir, name, 'SKILL.md'),
     `---\nname: ${name}\ndescription: ${description}\n---\n\n# ${name}\n\n${description}\n\nSpecification: ${config.artifactsDir}/PLANKIT.md\n`,
     options
@@ -427,18 +468,57 @@ function readFeatureAndPhaseArgs(parsed, options = {}) {
   return { featureName, phaseNumber };
 }
 
-function selectedAgents(parsed, config) {
-  if (!parsed.flags.agents) {
-    return config.agents;
+async function resolveAgent(parsed, config, io, configPath = null) {
+  const fromFlag = parsed.flags.agent || parsed.flags.agents;
+  if (fromFlag) {
+    const parts = String(fromFlag).split(',').map((item) => item.trim()).filter(Boolean);
+    if (parts.length > 1) {
+      throw new Error(`Select a single agent, got ${parts.length}. Use --agent <name>. Valid agents: ${validAgentNames()}.`);
+    }
+    const agent = getAgent(parts[0]);
+    io.stdout(`Using agent from --agent flag: "${agent.id}".`);
+    return agent;
   }
 
-  const requested = new Set(String(parsed.flags.agents).split(',').map((item) => item.trim()).filter(Boolean));
-  return {
-    codex: requested.has('codex'),
-    cursor: requested.has('cursor'),
-    opencode: requested.has('opencode'),
-    gemini: requested.has('gemini') || requested.has('antigravity')
-  };
+  if (configPath) {
+    const configured = resolveConfiguredAgent(config);
+    if (configured) {
+      io.stdout(`Using configured agent "${configured.id}" from plan config.`);
+      return configured;
+    }
+  }
+
+  if (io.isTTY && io.promptChoice) {
+    const agent = await promptAgent(io);
+    if (agent) {
+      io.stdout(`Selected agent: "${agent.id}".`);
+      return agent;
+    }
+  }
+
+  const agent = getAgent(DEFAULT_AGENT);
+  io.stdout(`No agent selected — using default agent "${agent.id}". Pass --agent <name> to change it.`);
+  return agent;
+}
+
+async function promptAgent(io) {
+  const agents = listAgents();
+  const header = agents.map((agent, index) => (
+    `  ${index + 1}. ${agent.label} — ${agent.description}`
+  )).join('\n');
+  const answer = await io.promptChoice(
+    `Select your coding agent:\n${header}\n\nEnter a number 1-${agents.length} or a name`,
+    agents.map((agent) => agent.id)
+  );
+  if (!answer) {
+    return null;
+  }
+  const trimmed = answer.trim().toLowerCase();
+  const num = Number.parseInt(trimmed, 10);
+  if (Number.isInteger(num) && num >= 1 && num <= agents.length) {
+    return agents[num - 1];
+  }
+  return getAgent(trimmed) || null;
 }
 
 function writeOptions(parsed, config) {
@@ -450,6 +530,17 @@ function writeOptions(parsed, config) {
 
 function printResults(results, io) {
   for (const result of results.filter(Boolean)) {
+    if (result.action === 'info') {
+      io.stdout(`  ${'info'.padEnd(9)} ${path.relative(io.cwd, result.path) || result.path} (${result.message || ''})`);
+      continue;
+    }
+    if (result.action === 'copied' && Array.isArray(result.copies)) {
+      io.stdout(`  ${'copied'.padEnd(9)} ${path.relative(io.cwd, result.path) || result.path}/`);
+      for (const copy of result.copies.filter(Boolean)) {
+        io.stdout(`  ${' '.padEnd(9)} ${path.relative(io.cwd, copy.path) || copy.path}`);
+      }
+      continue;
+    }
     io.stdout(`  ${result.action.padEnd(9)} ${path.relative(io.cwd, result.path) || result.path}`);
   }
 }
@@ -492,11 +583,41 @@ function parseArgs(args) {
 }
 
 function createIo(context) {
-  return {
+  const input = context.input || process.stdin;
+  const output = context.output || process.stdout;
+  const io = {
     cwd: context.cwd || process.cwd(),
     stdout: context.stdout || ((message) => console.log(message)),
     stderr: context.stderr || ((message) => console.error(message)),
-    exit: context.exit || ((code) => process.exit(code))
+    exit: context.exit || ((code) => process.exit(code)),
+    isTTY: context.isTTY !== undefined ? context.isTTY : Boolean(output && output.isTTY)
+  };
+
+  if (context.promptResponses !== undefined || input && input.isTTY) {
+    io.promptChoice = makePromptChoice(input, io.stdout, context.promptResponses);
+  }
+
+  return io;
+}
+
+function makePromptChoice(input, write, promptResponses) {
+  if (Array.isArray(promptResponses)) {
+    let index = 0;
+    return (prompt) => {
+      write(prompt);
+      const answer = promptResponses[index];
+      index += 1;
+      return answer === undefined ? '' : String(answer);
+    };
+  }
+
+  return async (prompt) => {
+    write(prompt);
+    const readline = (await import('node:readline/promises')).default;
+    const rl = readline.createInterface({ input, output: process.stdout });
+    const answer = await rl.question('');
+    rl.close();
+    return answer;
   };
 }
 
@@ -520,7 +641,8 @@ Commands:
 Options:
   --force                           Overwrite generated files where safe
   --dry-run                         Show intended actions without writing
-  --agents codex,cursor,opencode    Select generated agent integrations during init
+  --agent <name>                    Select your coding agent during init
+                                    (opencode, gemini, codex, cursor; default: opencode)
   --global-gemini-skills            Also install Gemini skills under the user profile
   --phases 3                        Generate N default phases during plan
   --phases "Design,Build,Test"      Generate named phases during plan

package/src/commandBundles.js

@@ -0,0 +1,51 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import fs from 'node:fs';
+
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+export const COMMAND_BUNDLES = {
+  'opencode-angular': {
+    label: 'Angular command suite',
+    src: path.join('angular-commands', 'opencode'),
+    dest: ['.opencode', 'commands'],
+    kind: 'folder'
+  },
+  'gemini-angular': {
+    label: 'Angular skill suite',
+    src: path.join('angular-skills', 'gemini'),
+    dest: ['.gemini', 'skills'],
+    kind: 'folder',
+    global: true
+  },
+  'codex-angular': {
+    label: 'Angular command suite',
+    src: path.join('angular-commands', 'codex'),
+    dest: ['.codex'],
+    kind: 'folder'
+  },
+  'cursor-angular': {
+    label: 'Angular command suite',
+    src: path.join('angular-commands', 'cursor'),
+    dest: ['.cursor'],
+    kind: 'folder'
+  }
+};
+
+export function bundleEntry(bundleName) {
+  return COMMAND_BUNDLES[bundleName] || null;
+}
+
+export function bundleSourceExists(bundleName, cwd, config) {
+  const entry = COMMAND_BUNDLES[bundleName];
+  if (!entry) {
+    return false;
+  }
+  const customPath = config.templatesDir
+    ? path.resolve(cwd, config.templatesDir, entry.src)
+    : null;
+  return Boolean(
+    customPath && fs.existsSync(customPath) &&
+    typeof customPath === 'string' && customPath.length
+  ) || fs.existsSync(path.join(packageRoot, 'templates', entry.src));
+}

package/src/config.js

@@ -1,14 +1,12 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import { AGENT_ORDER, DEFAULT_AGENT, getAgent } from './agents.js';
 
 export const DEFAULT_CONFIG = {
   artifactsDir: 'artifacts',
   overwrite: 'skip',
   agents: {
-    codex: true,
-    cursor: true,
-    opencode: true,
-    gemini: true
+    default: DEFAULT_AGENT
   },
   defaultPhases: [
     {
@@ -70,11 +68,39 @@ export function normalizeConfig(config) {
   normalized.defaultPhases = normalizePhases(normalized.defaultPhases);
   normalized.artifactsDir = normalized.artifactsDir || DEFAULT_CONFIG.artifactsDir;
   normalized.overwrite = normalized.overwrite || DEFAULT_CONFIG.overwrite;
-  normalized.agents = { ...DEFAULT_CONFIG.agents, ...(normalized.agents || {}) };
+  normalized.agents = normalizeAgents(normalized.agents);
   normalized.verification = { ...DEFAULT_CONFIG.verification, ...(normalized.verification || {}) };
   return normalized;
 }
 
+export function normalizeAgents(agents) {
+  if (!agents || typeof agents !== 'object') {
+    return { ...DEFAULT_CONFIG.agents };
+  }
+
+  const hasDefault = typeof agents.default === 'string' && agents.default.length > 0;
+  if (hasDefault) {
+    return { default: agents.default };
+  }
+
+  const legacyEnabled = AGENT_ORDER.filter((id) => agents[id] === true);
+  if (legacyEnabled.length > 0) {
+    return { default: legacyEnabled[0] };
+  }
+
+  return { ...DEFAULT_CONFIG.agents };
+}
+
+export function resolveConfiguredAgent(config) {
+  const configured = config.agents && config.agents.default;
+  try {
+    return configured ? getAgent(configured) : null;
+  } catch {
+    return null;
+  }
+}
+
+
 export function normalizePhases(phases) {
   if (!Array.isArray(phases) || phases.length === 0) {
     return DEFAULT_CONFIG.defaultPhases;

package/src/templates.js

@@ -4,6 +4,8 @@ import { fileURLToPath } from 'node:url';
 
 const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 
+export { packageRoot };
+
 export function renderTemplate(config, templateName, variables = {}, cwd = process.cwd()) {
   const customPath = config.templatesDir
     ? path.resolve(cwd, config.templatesDir, templateName)