plankit-cli 1.0.0

package/README.md

@@ -0,0 +1,71 @@
+# `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**.
+
+---
+
+## Quick Start (Usage without installation)
+
+Run in any project directory:
+
+```bash
+npx plankit-cli init
+```
+
+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`:
+
+```bash
+npm install -g plankit-cli
+```
+
+Then run anywhere:
+
+```bash
+plankit init
+plankit plan <feature-name>
+plankit status
+plankit archive <feature-name>
+```
+
+---
+
+## Commands Summary
+
+| Command | Action |
+|---|---|
+| `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
+   ```

package/bin/plankit.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { runCli } from '../src/cli.js';
+
+runCli(process.argv.slice(2));

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "plankit-cli",
+  "version": "1.0.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",
+  "scripts": {
+    "start": "node bin/plankit.js",
+    "test": "node --test"
+  },
+  "keywords": [
+    "plankit",
+    "ai-agent",
+    "antigravity",
+    "opencode",
+    "codex",
+    "cursor",
+    "workflow",
+    "cli"
+  ],
+  "author": "",
+  "license": "MIT"
+}

package/src/cli.js

@@ -0,0 +1,235 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import {
+  AGENTS_MD_TEMPLATE,
+  CURSORRULES_TEMPLATE,
+  GEMINI_INSTRUCTIONS_TEMPLATE,
+  OPENCODE_COMMAND_PLAN,
+  OPENCODE_COMMAND_CLARIFY,
+  OPENCODE_COMMAND_IMPLEMENT,
+  OPENCODE_COMMAND_REVIEW,
+  OPENCODE_COMMAND_MASTER,
+  PLANKIT_SPEC_TEMPLATE
+} from './templates.js';
+
+export function runCli(args) {
+  const command = args[0];
+  const target = args[1];
+
+  switch (command) {
+    case 'init':
+      initProject();
+      break;
+    case 'plan':
+      if (!target) {
+        console.error('Error: Please specify a feature name. Example: npx plankit plan my-feature');
+        process.exit(1);
+      }
+      planFeature(target);
+      break;
+    case 'status':
+      showStatus();
+      break;
+    case 'archive':
+      if (!target) {
+        console.error('Error: Please specify a feature name. Example: npx plankit archive my-feature');
+        process.exit(1);
+      }
+      archiveFeature(target);
+      break;
+    case 'help':
+    case '--help':
+    case '-h':
+    default:
+      showHelp();
+      break;
+  }
+}
+
+function ensureDir(dirPath) {
+  if (!fs.existsSync(dirPath)) {
+    fs.mkdirSync(dirPath, { recursive: true });
+  }
+}
+
+function writeFile(filePath, content) {
+  ensureDir(path.dirname(filePath));
+  fs.writeFileSync(filePath, content, 'utf8');
+}
+
+function initProject() {
+  console.log('🚀 Initializing PlanKit Command Suite in project...');
+
+  const cwd = process.cwd();
+
+  // 1. Artifacts directories & spec files
+  ensureDir(path.join(cwd, 'artifacts', 'current'));
+  ensureDir(path.join(cwd, 'artifacts', 'archived'));
+  writeFile(path.join(cwd, 'artifacts', 'PLANKIT.md'), PLANKIT_SPEC_TEMPLATE);
+  writeFile(path.join(cwd, 'artifacts', 'current', '.gitkeep'), '');
+  writeFile(path.join(cwd, 'artifacts', 'archived', '.gitkeep'), '');
+
+  // 2. Gemini / Antigravity instructions
+  writeFile(path.join(cwd, '.gemini', 'instructions.md'), GEMINI_INSTRUCTIONS_TEMPLATE);
+
+  // 3. Cursor rules
+  writeFile(path.join(cwd, '.cursorrules'), CURSORRULES_TEMPLATE);
+
+  // 4. AGENTS.md
+  writeFile(path.join(cwd, 'AGENTS.md'), AGENTS_MD_TEMPLATE);
+
+  // 5. OpenCode command markdown files
+  const opencodeDir = path.join(cwd, '.opencode', 'commands');
+  writeFile(path.join(opencodeDir, 'plankit-plan.md'), OPENCODE_COMMAND_PLAN);
+  writeFile(path.join(opencodeDir, 'plankit-clarify.md'), OPENCODE_COMMAND_CLARIFY);
+  writeFile(path.join(opencodeDir, 'plankit-implement.md'), OPENCODE_COMMAND_IMPLEMENT);
+  writeFile(path.join(opencodeDir, 'plankit-review.md'), OPENCODE_COMMAND_REVIEW);
+  writeFile(path.join(opencodeDir, 'plankit.md'), OPENCODE_COMMAND_MASTER);
+
+  // 6. Global Gemini Skills setup
+  try {
+    const userHome = os.homedir();
+    const globalSkillsDir = path.join(userHome, '.gemini', 'skills');
+
+    const skillsToCreate = [
+      { name: 'plankit', desc: 'PlanKit Command Suite master skill.' },
+      { name: 'plankit-plan', desc: 'Initialize feature under artifacts/current/<feature-name>/.' },
+      { name: 'plankit-clarify', desc: 'Analyze requirements and ask targeted clarifying questions.' },
+      { name: 'plankit-implement', desc: 'Execute Phase N reading spec and previous outputs.' },
+      { name: 'plankit-review', desc: 'Run test & build verification, validate DoD, and archive feature.' }
+    ];
+
+    for (const skill of skillsToCreate) {
+      const skillPath = path.join(globalSkillsDir, skill.name, 'SKILL.md');
+      const skillContent = `---\nname: ${skill.name}\ndescription: ${skill.desc}\n---\n\n# ${skill.name}\n${skill.desc}\n`;
+      writeFile(skillPath, skillContent);
+    }
+    console.log('  ✓ Installed global Gemini skills in ~/.gemini/skills/');
+  } catch (e) {
+    // Ignore global home dir write errors if restricted
+  }
+
+  console.log('\n✅ PlanKit successfully initialized!');
+  console.log('\nCreated / Updated configuration files:');
+  console.log('  - artifacts/PLANKIT.md');
+  console.log('  - .gemini/instructions.md');
+  console.log('  - .cursorrules');
+  console.log('  - AGENTS.md');
+  console.log('  - .opencode/commands/*.md');
+  console.log('\nNext steps:');
+  console.log('  Run "npx plankit plan <feature-name>" to start a new feature.');
+}
+
+function planFeature(featureName) {
+  const cwd = process.cwd();
+  const featureDir = path.join(cwd, 'artifacts', 'current', featureName);
+
+  if (fs.existsSync(featureDir)) {
+    console.log(`⚠️ Feature folder "${featureName}" already exists at artifacts/current/${featureName}`);
+    return;
+  }
+
+  console.log(`🚀 Creating new feature workspace for "${featureName}"...`);
+
+  ensureDir(path.join(featureDir, 'phases'));
+  ensureDir(path.join(featureDir, 'outputs'));
+
+  const readmeContent = `# Feature: ${featureName}
+
+## Overview
+Detailed description of the feature goal and scope.
+
+## Phase Breakdown & Progress Status
+
+- [ ] Phase 1: Foundation & Setup — ([Spec](phases/phase-1-foundation.md))
+- [ ] Phase 2: Core Implementation
+- [ ] Phase 3: Testing & Verification
+
+## Phase Execution Matrix
+
+| Phase # | Phase Title | Spec Path | Output Path | Status |
+|---|---|---|---|---|
+| Phase 1 | Foundation & Setup | \`phases/phase-1-foundation.md\` | \`outputs/phase-1-output.md\` | **PENDING** |
+`;
+
+  const phase1Spec = `# Phase 1: Foundation & Setup
+
+## 1. Objective
+Establish base structure and foundational dependencies for ${featureName}.
+
+## 2. Tasks
+- [ ] Initial setup
+- [ ] Basic implementation
+`;
+
+  writeFile(path.join(featureDir, 'README.md'), readmeContent);
+  writeFile(path.join(featureDir, 'phases', 'phase-1-foundation.md'), phase1Spec);
+  writeFile(path.join(featureDir, 'outputs', '.gitkeep'), '');
+
+  console.log(`\n✅ Feature "${featureName}" initialized successfully!`);
+  console.log(`  - Spec: artifacts/current/${featureName}/phases/phase-1-foundation.md`);
+  console.log(`  - Overview: artifacts/current/${featureName}/README.md`);
+}
+
+function showStatus() {
+  const cwd = process.cwd();
+  const currentDir = path.join(cwd, 'artifacts', 'current');
+  const archivedDir = path.join(cwd, 'artifacts', 'archived');
+
+  console.log('📊 PlanKit Feature Status Summary:\n');
+
+  if (fs.existsSync(currentDir)) {
+    const currentFeatures = fs.readdirSync(currentDir).filter(f => !f.startsWith('.'));
+    console.log('📌 ACTIVE FEATURES (artifacts/current/):');
+    if (currentFeatures.length === 0) {
+      console.log('  (none)');
+    } else {
+      currentFeatures.forEach(f => console.log(`  - 🟡 ${f}`));
+    }
+  }
+
+  console.log('');
+
+  if (fs.existsSync(archivedDir)) {
+    const archivedFeatures = fs.readdirSync(archivedDir).filter(f => !f.startsWith('.'));
+    console.log('📦 ARCHIVED FEATURES (artifacts/archived/):');
+    if (archivedFeatures.length === 0) {
+      console.log('  (none)');
+    } else {
+      archivedFeatures.forEach(f => console.log(`  - 🟢 ${f}`));
+    }
+  }
+}
+
+function archiveFeature(featureName) {
+  const cwd = process.cwd();
+  const sourceDir = path.join(cwd, 'artifacts', 'current', featureName);
+  const targetDir = path.join(cwd, 'artifacts', 'archived', featureName);
+
+  if (!fs.existsSync(sourceDir)) {
+    console.error(`Error: Active feature "${featureName}" not found in artifacts/current/`);
+    process.exit(1);
+  }
+
+  ensureDir(path.dirname(targetDir));
+  fs.renameSync(sourceDir, targetDir);
+
+  console.log(`✅ Archived feature "${featureName}" -> artifacts/archived/${featureName}`);
+}
+
+function showHelp() {
+  console.log(`
+PlanKit CLI — Command Suite for AI Coding Assistants
+
+Usage:
+  npx plankit <command> [options]
+
+Commands:
+  init                     Initialize PlanKit rules & commands in the current project
+  plan <feature-name>      Create a new feature workspace under artifacts/current/<feature-name>/
+  status                   Show status of all active and archived features
+  archive <feature-name>   Move a completed feature to artifacts/archived/<feature-name>/
+  help                     Show this help message
+`);
+}

package/src/templates.js

@@ -0,0 +1,149 @@
+export const AGENTS_MD_TEMPLATE = `# AGENTS.md — PlanKit Command Suite for AI Agents
+
+All AI coding assistants (Codex, Claude Code, OpenCode, Antigravity, Cursor) interacting with this codebase must follow the **PlanKit Command Suite**:
+
+## Commands
+
+1. \`plankit.plan\` (or \`/plankit-plan\`): Initialize feature under \`artifacts/current/<feature-name>/\`, create \`README.md\` progress matrix, and write \`phases/phase-N-*.md\` specs.
+2. \`plankit.clarify\` (or \`/plankit-clarify\`): Analyze requirements and ask targeted clarifying questions before executing code edits.
+3. \`plankit.implement\` (or \`/plankit-implement\`): Execute Phase N by reading \`phases/phase-N.md\` **AND all previous outputs** (\`outputs/phase-1..N-1-output.md\`), writing \`outputs/phase-N-output.md\`, and updating \`README.md\`.
+4. \`plankit.review\` (or \`/plankit-review\`): Run test & build verification, validate DoD, and move feature folder to \`artifacts/archived/<feature-name>\`.
+
+Canonical Specification: \`artifacts/PLANKIT.md\`
+`;
+
+export const CURSORRULES_TEMPLATE = `# Cursor AI Rules — PlanKit Command Suite
+
+You MUST follow the PlanKit multi-phase feature development standard defined in \`artifacts/PLANKIT.md\`.
+
+## Recognized PlanKit Commands
+
+- **plankit.plan**: Create \`artifacts/current/<feature-name>/\`, master \`README.md\`, and \`phases/phase-N-*.md\` specs.
+- **plankit.clarify**: Inspect codebase & specs, then ask structured clarifying questions before editing code.
+- **plankit.implement**: Read target spec AND \`outputs/phase-1..N-1-output.md\`, execute changes, write \`outputs/phase-N-output.md\`, and mark Phase N \`[x]\` in \`README.md\`.
+- **plankit.review**: Run \`npm run test\` & \`npm run build\`, validate DoD checklist, and move folder to \`artifacts/archived/<feature-name>\`.
+`;
+
+export const GEMINI_INSTRUCTIONS_TEMPLATE = `# Antigravity Workspace Rules — PlanKit Integration
+
+Whenever working in this workspace, strictly adhere to the **PlanKit Command Suite** defined in \`artifacts/PLANKIT.md\`.
+
+## Recognized PlanKit Commands
+
+### 1. \`plankit.plan\` [feature-description]
+- Create \`artifacts/current/<feature-name>/\`.
+- Create \`README.md\` with overview, progress table, and \`[ ]\` checkboxes.
+- Create phase specs in \`phases/phase-N-*.md\`.
+- Present Phase 1 implementation plan.
+
+### 2. \`plankit.clarify\`
+- Read \`artifacts/current/<feature-name>/README.md\` and target spec in \`phases/\`.
+- Inspect codebase and present structured clarifying questions to user before modifying code.
+
+### 3. \`plankit.implement\` [Phase N]
+- Read \`phases/phase-N-*.md\` **AND all previous outputs** (\`outputs/phase-1..N-1-output.md\`).
+- Execute changes, run tests, write \`outputs/phase-N-output.md\`, and update \`README.md\` (\`[x]\`).
+
+### 4. \`plankit.review\`
+- Run \`npm run test\` and \`npm run build\`.
+- Validate DoD checklist.
+- Move completed feature folder from \`artifacts/current/<feature-name>\` to \`artifacts/archived/<feature-name>\`.
+`;
+
+export const OPENCODE_COMMAND_PLAN = `---
+description: Initialize a new feature under artifacts/current/<feature-name>/, create README.md progress matrix, and write phases/phase-N-*.md specs.
+---
+
+Initialize a new feature in the workspace according to PlanKit SOP.
+
+Requirements: $ARG
+
+Steps:
+1. Create directory \`artifacts/current/$ARG/\` (or determine feature name from prompt).
+2. Create \`artifacts/current/<feature-name>/README.md\` containing feature overview, architecture summary, DoD checklist, and progress status matrix.
+3. Write phase specification files under \`artifacts/current/<feature-name>/phases/phase-N-<step-name>.md\`.
+4. Generate the detailed Phase 1 implementation plan artifact and request user approval.
+`;
+
+export const OPENCODE_COMMAND_CLARIFY = `---
+description: Analyze requirements and codebase to ask targeted clarifying questions before executing code edits.
+---
+
+Analyze requirements and clarify design decisions according to PlanKit SOP.
+
+1. Read \`artifacts/current/<feature-name>/README.md\` and target spec in \`phases/\`.
+2. Inspect relevant codebase files to identify existing patterns, schemas, or potential breaking changes.
+3. Formulate and present structured clarifying questions for the user regarding design choices, API contracts, or edge cases.
+4. Do NOT make code changes until the user responds.
+`;
+
+export const OPENCODE_COMMAND_IMPLEMENT = `---
+description: Execute Phase N by reading phases/phase-N.md AND all previous outputs, writing outputs/phase-N-output.md, and updating README.md.
+---
+
+Execute a feature phase according to PlanKit SOP.
+
+Phase to implement: $ARG
+
+1. Read target phase spec: \`artifacts/current/<feature-name>/phases/phase-N-*.md\`.
+2. **Mandatory Context Load**: Read **ALL** previous output reports: \`outputs/phase-1-output.md\` through \`outputs/phase-(N-1)-output.md\`.
+3. Execute code and configuration modifications.
+4. Run automated tests or build verification commands.
+5. Write execution report to \`artifacts/current/<feature-name>/outputs/phase-N-output.md\`.
+6. Update \`artifacts/current/<feature-name>/README.md\`: mark Phase N as \`[x]\` and update status matrix.
+`;
+
+export const OPENCODE_COMMAND_REVIEW = `---
+description: Run test & build verification, validate DoD, and move feature folder to artifacts/archived/<feature-name>.
+---
+
+Verify a completed feature and archive it according to PlanKit SOP.
+
+1. Run full test suite (\`npm run test\`) and production build (\`npm run build\`).
+2. Validate all Definition of Done checklist items in \`artifacts/current/<feature-name>/README.md\`.
+3. Update \`README.md\` header title to \`# Feature: <Feature Name> [ARCHIVED]\`.
+4. Move \`artifacts/current/<feature-name>\` directory to \`artifacts/archived/<feature-name>\`.
+5. Present final completion summary report to user.
+`;
+
+export const OPENCODE_COMMAND_MASTER = `---
+description: PlanKit Command Suite master command. Evaluate sub-action (plan, clarify, implement, review).
+---
+
+PlanKit Command Suite master command.
+
+Sub-action / Arguments: $ARG
+
+Evaluate the sub-action:
+- \`plan\`: Initialize feature under \`artifacts/current/<feature-name>/\`, create \`README.md\` matrix, and write \`phases/phase-N-*.md\` specs.
+- \`clarify\`: Inspect codebase and specs, then ask structured clarifying questions before implementing code.
+- \`implement\`: Read target spec AND all previous outputs (\`outputs/phase-1..N-1-output.md\`), execute changes, write \`outputs/phase-N-output.md\`, and update \`README.md\`.
+- \`review\`: Run \`npm run test\` & \`npm run build\`, validate DoD checklist, and archive completed feature to \`artifacts/archived/<feature-name>\`.
+`;
+
+export const PLANKIT_SPEC_TEMPLATE = `# PlanKit Command Suite Specification
+
+> [!IMPORTANT]
+> **PlanKit Standard**: PlanKit is a standardized, tool-agnostic command framework for AI coding assistants. It organizes multi-phase feature development into distinct, predictable steps with context-aware execution and automated progress tracking.
+
+---
+
+## The 4 Core Commands
+
+### 1. \`plankit.plan\` [feature-name] [requirements]
+- **Purpose**: Initializes a new feature task.
+- **Actions**:
+  1. Creates feature directory: \`artifacts/current/<feature-name>/\`.
+  2. Creates master overview & status tracking table in \`artifacts/current/<feature-name>/README.md\`.
+  3. Creates phase specification files: \`artifacts/current/<feature-name>/phases/phase-1-<name>.md\`, \`phase-2-<name>.md\`, etc.
+  4. Generates initial Phase 1 implementation plan artifact and requests user approval.
+
+### 2. \`plankit.clarify\`
+- **Purpose**: Conducts a structured design alignment and requirements interview.
+
+### 3. \`plankit.implement\` [Phase N]
+- **Purpose**: Executes a single phase with context continuity. Reads \`phases/phase-N.md\` AND all previous outputs (\`outputs/phase-1..N-1-output.md\`).
+
+### 4. \`plankit.review\`
+- **Purpose**: Verifies Definition of Done (DoD) and archives completed features to \`artifacts/archived/\`.
+`;