context-planning 0.7.0

package/install/claude.js

@@ -0,0 +1,116 @@
+'use strict';
+
+/**
+ * Installer for Claude Code.
+ *
+ * Claude Code looks for slash-commands in `<repo>/.claude/commands/<file>.md`
+ * (project-scoped) or `~/.claude/commands/<file>.md` (user-scoped). Each
+ * markdown file becomes a /command — the filename without the .md extension.
+ *
+ * Claude Code also reads `<repo>/.claude/CLAUDE.md` (and `~/.claude/CLAUDE.md`)
+ * as ambient instructions for the agent. We append a small cp section so the
+ * agent knows when to invoke /cp-* commands and how to talk to the workflow
+ * provider.
+ *
+ * The same command markdown files used by the Copilot installer are reused
+ * verbatim — they're harness-agnostic. Claude treats the YAML frontmatter as
+ * metadata (name / description) and the body as instructions.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { listCommandFiles, writeFile, writeFileSafe, homeDir } = require('./common');
+
+const CP_BLOCK_BEGIN = '<!-- context-planning (cp) — managed by cp installer -->';
+const CP_BLOCK_END = '<!-- /context-planning -->';
+
+function install({ pluginRoot, repoRoot, force = false }) {
+  const userScope = process.env.CP_INSTALL_SCOPE === 'user';
+  const base = userScope
+    ? path.join(homeDir(), '.claude')
+    : path.join(repoRoot, '.claude');
+  const cmdDir = path.join(base, 'commands');
+
+  console.log(`Installing cp commands as Claude Code slash-commands into:`);
+  console.log(`  ${cmdDir}`);
+
+  let written = 0;
+  let identical = 0;
+  const userModified = [];
+  for (const { name, src } of listCommandFiles(pluginRoot)) {
+    // Claude expects the filename to match the command, so /cp-progress reads
+    // .claude/commands/cp-progress.md. Our source files are already named
+    // {name}.md (no cp- prefix), so we prefix on install.
+    const dest = path.join(cmdDir, `cp-${name}.md`);
+    const body = fs.readFileSync(src, 'utf8');
+    const r = writeFileSafe(dest, body, { force });
+    if (r.status === 'written')           { console.log(`  + /cp-${name}`); written++; }
+    else if (r.status === 'identical')    { console.log(`  = /cp-${name} (unchanged)`); identical++; }
+    else if (r.status === 'user-modified') { console.log(`  ! /cp-${name} (LOCALLY MODIFIED — kept)`); userModified.push(`cp-${name}.md`); }
+  }
+
+  // Merge the cp instruction block into CLAUDE.md (project or user) —
+  // idempotent. Strip any prior cp block first, then append a fresh one.
+  // This is always safe: we only ever touch text *between* our markers,
+  // so any unrelated CLAUDE.md content (user instructions, other plugins'
+  // blocks) is preserved verbatim. No --force needed.
+  const claudeMdPath = path.join(base, 'CLAUDE.md');
+  const block = `${CP_BLOCK_BEGIN}
+# Instructions for context-planning (cp)
+
+- When the user invokes a \`/cp-*\` slash command, load the matching command
+  file from \`.claude/commands/cp-*.md\`.
+- \`cp\` owns the *state layer* (PROJECT.md / ROADMAP.md / STATE.md / phase dirs
+  under \`.planning/\`). It delegates *workflow* to whatever provider is
+  configured in \`.planning/config.json\` under the top-level \`cp:\` block
+  (default provider: superpowers). The same \`config.json\` is shared with GSD
+  when GSD is also installed — they coexist via separate top-level keys.
+- For each role (brainstorm, plan, execute, review, finish), invoke the
+  matching provider skill (e.g. \`brainstorming\`, \`writing-plans\`,
+  \`subagent-driven-development\`), then return to cp to record the state
+  change.
+- Always update .planning/STATE.md after a phase/quick task completes; tick
+  the matching checkbox in .planning/ROADMAP.md; write SUMMARY.md.
+- Only invoke cp commands when the user explicitly asks. Don't apply cp
+  workflows unbidden.
+${CP_BLOCK_END}
+`;
+
+  let existing = fs.existsSync(claudeMdPath)
+    ? fs.readFileSync(claudeMdPath, 'utf8')
+    : '';
+  // Remove any previously installed block (idempotent re-install).
+  const blockRe = new RegExp(
+    escapeRegex(CP_BLOCK_BEGIN) + '[\\s\\S]*?' + escapeRegex(CP_BLOCK_END) + '\\n?',
+    'g'
+  );
+  existing = existing.replace(blockRe, '');
+  // Trim trailing newlines so we get a clean join.
+  existing = existing.replace(/\s+$/, '');
+  const merged = existing
+    ? existing + '\n\n' + block
+    : block;
+
+  writeFile(claudeMdPath, merged);
+
+  console.log(`\nInstalled: ${written} written, ${identical} unchanged${userModified.length ? `, ${userModified.length} kept (locally modified)` : ''}.`);
+  console.log(`Merged cp block into: ${claudeMdPath}`);
+  if (userModified.length > 0) {
+    console.log(`\n⚠ The following slash-command files exist with local modifications and were NOT overwritten:`);
+    for (const f of userModified) console.log(`    - ${f}`);
+    console.log(`  Re-run with \`cp install claude --force\` to overwrite them, or delete the local copy first.`);
+  }
+  console.log(`\nNext steps:`);
+  console.log(`  1. Make sure your workflow provider (default: superpowers) is installed.`);
+  console.log(`     - For Claude Code:  /plugin install superpowers@superpowers-marketplace`);
+  console.log(`  2. In a project directory:  cp init`);
+  console.log(`  3. Then in Claude Code:     /cp-new-milestone "my first milestone"`);
+
+  return { written, identical, userModified };
+}
+
+function escapeRegex(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+module.exports = { install };

package/install/common.js

@@ -0,0 +1,65 @@
+'use strict';
+
+/**
+ * Shared helpers for harness installers.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+function listCommandFiles(pluginRoot) {
+  const dir = path.join(pluginRoot, 'commands', 'cp');
+  return fs
+    .readdirSync(dir)
+    .filter((f) => f.endsWith('.md'))
+    .map((f) => ({ name: f.replace(/\.md$/, ''), src: path.join(dir, f) }));
+}
+
+function copyFile(src, dest) {
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  fs.copyFileSync(src, dest);
+}
+
+/**
+ * Plain write (mkdir + writeFileSync). Use when you DO want to clobber —
+ * e.g. an internal cp-only state file we own end-to-end.
+ */
+function writeFile(dest, content) {
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  fs.writeFileSync(dest, content);
+}
+
+/**
+ * Collision-aware write for installer outputs. Returns one of:
+ *   { status: 'written' }     — file did not exist or matches the incoming bytes
+ *                                exactly; either way wrote it (no user edit lost).
+ *   { status: 'identical' }   — file already on disk has identical content. Skipped.
+ *   { status: 'user-modified' } — file exists with DIFFERENT content and `force`
+ *                                is false. NOT written; existing file untouched.
+ *
+ * The "identical" check is what makes safe re-installs cheap: idempotent
+ * re-runs after `cp update` or version bumps will report `identical` for
+ * unchanged files and `written` only for the ones the new release actually
+ * changed.
+ *
+ * v0.3.4 — closes CONCERNS Medium "Installers overwrite existing cp-scoped
+ * command/skill files without a collision prompt or merge path."
+ */
+function writeFileSafe(dest, content, { force = false } = {}) {
+  if (fs.existsSync(dest)) {
+    let current;
+    try { current = fs.readFileSync(dest, 'utf8'); }
+    catch { current = null; }
+    if (current === content) return { status: 'identical' };
+    if (!force) return { status: 'user-modified' };
+  }
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  fs.writeFileSync(dest, content);
+  return { status: 'written' };
+}
+
+function homeDir() {
+  return require('os').homedir();
+}
+
+module.exports = { listCommandFiles, copyFile, writeFile, writeFileSafe, homeDir };

package/install/copilot.js

@@ -0,0 +1,86 @@
+'use strict';
+
+/**
+ * Installer for GitHub Copilot CLI.
+ *
+ * Copilot CLI looks for skills in `<repo>/.github/skills/<name>/` (project-scoped)
+ * or `~/.copilot/skills/<name>/` (user-scoped). It also reads a custom instruction
+ * block injected into the system prompt.
+ *
+ * Each command becomes a skill named `cp-<name>`, with a SKILL.md that contains
+ * the command's instructions. The skill files are harness-agnostic (just markdown);
+ * Copilot picks them up by name.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { listCommandFiles, writeFile, writeFileSafe, homeDir } = require('./common');
+
+function install({ pluginRoot, repoRoot, force = false }) {
+  const target = process.env.CP_INSTALL_SCOPE === 'user'
+    ? path.join(homeDir(), '.copilot', 'skills')
+    : path.join(repoRoot, '.github', 'skills');
+
+  console.log(`Installing cp commands as Copilot skills into:`);
+  console.log(`  ${target}`);
+
+  let written = 0;
+  let identical = 0;
+  const userModified = [];
+  for (const { name, src } of listCommandFiles(pluginRoot)) {
+    const skillName = `cp-${name}`;
+    const skillDir = path.join(target, skillName);
+    const skillMd = path.join(skillDir, 'SKILL.md');
+    const body = fs.readFileSync(src, 'utf8');
+    const r = writeFileSafe(skillMd, body, { force });
+    if (r.status === 'written')           { console.log(`  + ${skillName}`); written++; }
+    else if (r.status === 'identical')    { console.log(`  = ${skillName} (unchanged)`); identical++; }
+    else if (r.status === 'user-modified') { console.log(`  ! ${skillName} (LOCALLY MODIFIED — kept)`); userModified.push(skillName); }
+  }
+
+  // The ambient instruction file is cp-owned end-to-end (we rewrite the
+  // whole block every install). Apply the same collision rule though so a
+  // user who hand-edited it doesn't silently lose changes.
+  const ctxDest = process.env.CP_INSTALL_SCOPE === 'user'
+    ? path.join(homeDir(), '.copilot', 'context-planning.md')
+    : path.join(repoRoot, '.github', 'context-planning.md');
+
+  const ctxBody = `<!-- context-planning (cp) — managed by cp installer -->
+# Instructions for context-planning (cp)
+
+- When the user invokes a \`/cp-*\` slash command (or \`cp-*\` skill), load the
+  matching SKILL.md from \`.github/skills/cp-*\`.
+- \`cp\` owns the *state layer* (PROJECT.md / ROADMAP.md / STATE.md / phase dirs).
+  It delegates *workflow* to whatever provider is configured in
+  \`.planning/config.json\` under the top-level \`cp:\` block (default
+  provider: superpowers). The same \`config.json\` is shared with GSD when
+  GSD is also installed — they coexist via separate top-level keys.
+- For each role (brainstorm, plan, execute, review, finish), invoke the matching
+  provider skill via its own slash-command, then return to cp to record the
+  state change.
+- Always update .planning/STATE.md after a phase/quick task is completed; tick
+  the matching checkbox in .planning/ROADMAP.md; write SUMMARY.md.
+- Only invoke cp commands when the user explicitly asks. Don't apply cp
+  workflows unbidden.
+<!-- /context-planning -->
+`;
+  const ctxR = writeFileSafe(ctxDest, ctxBody, { force });
+  if (ctxR.status === 'user-modified') userModified.push(path.basename(ctxDest));
+
+  console.log(`\nInstalled: ${written} written, ${identical} unchanged${userModified.length ? `, ${userModified.length} kept (locally modified)` : ''}.`);
+  console.log(`Context file: ${ctxDest} (${ctxR.status})`);
+  if (userModified.length > 0) {
+    console.log(`\n⚠ The following files exist on disk with local modifications and were NOT overwritten:`);
+    for (const f of userModified) console.log(`    - ${f}`);
+    console.log(`  Re-run with \`cp install copilot --force\` to overwrite them, or delete the local copy first.`);
+  }
+  console.log(`\nNext steps:`);
+  console.log(`  1. Make sure your workflow provider (default: superpowers) is installed.`);
+  console.log(`     copilot plugin install superpowers@superpowers-marketplace`);
+  console.log(`  2. In a project directory:  cp init`);
+  console.log(`  3. Then in Copilot CLI:     /cp-new-milestone "my first milestone"`);
+
+  return { written, identical, userModified };
+}
+
+module.exports = { install };

package/install/cursor.js

@@ -0,0 +1,120 @@
+'use strict';
+
+/**
+ * Installer for Cursor IDE.
+ *
+ * Cursor reads project rules from `.cursor/rules/*.mdc` (Markdown with YAML
+ * frontmatter). Unlike Claude / Copilot CLI, Cursor has no per-project
+ * slash-command extension mechanism — its slash commands are hard-coded.
+ * The closest analog is to install each cp command as an INVOKABLE RULE so
+ * the user can attach it to their chat with `@cp-<name>` or the rule picker.
+ *
+ * Layout:
+ *   .cursor/rules/context-planning.mdc   — alwaysApply: true, ambient
+ *                                          routing instructions (mirrors the
+ *                                          `.github/context-planning.md` we
+ *                                          install for Copilot CLI).
+ *   .cursor/rules/cp-<name>.mdc          — alwaysApply: false, one per
+ *                                          `commands/cp/*.md`. User pulls
+ *                                          them in via `@cp-<name>` or the
+ *                                          rule picker.
+ *
+ * v0.4.2.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { listCommandFiles, writeFileSafe, homeDir } = require('./common');
+
+// Cursor rule body wrapper: add frontmatter on top of the raw command body.
+// If the source already has YAML frontmatter (most cp slash commands do),
+// strip its `description:` to use as the rule description, and discard the
+// rest — Cursor only understands its own keys.
+function buildRule({ name, body, alwaysApply }) {
+  let description = `cp slash-command: ${name}`;
+  let bodyOnly = body;
+  const fm = body.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/);
+  if (fm) {
+    const m = fm[1].match(/^description:\s*(.+)$/m);
+    if (m) description = m[1].trim().replace(/^["']|["']$/g, '');
+    bodyOnly = fm[2];
+  }
+  const yaml = [
+    '---',
+    `description: ${JSON.stringify(description)}`,
+    `alwaysApply: ${alwaysApply ? 'true' : 'false'}`,
+    '---',
+    '',
+  ].join('\n');
+  return yaml + bodyOnly;
+}
+
+function install({ pluginRoot, repoRoot, force = false }) {
+  const target = process.env.CP_INSTALL_SCOPE === 'user'
+    ? path.join(homeDir(), '.cursor', 'rules')
+    : path.join(repoRoot, '.cursor', 'rules');
+
+  console.log(`Installing cp commands as Cursor rules into:`);
+  console.log(`  ${target}`);
+
+  let written = 0;
+  let identical = 0;
+  const userModified = [];
+
+  for (const { name, src } of listCommandFiles(pluginRoot)) {
+    const ruleName = `cp-${name}`;
+    const ruleFile = path.join(target, `${ruleName}.mdc`);
+    const rawBody = fs.readFileSync(src, 'utf8');
+    const rule = buildRule({ name, body: rawBody, alwaysApply: false });
+    const r = writeFileSafe(ruleFile, rule, { force });
+    if (r.status === 'written')           { console.log(`  + ${ruleName}.mdc`); written++; }
+    else if (r.status === 'identical')    { console.log(`  = ${ruleName}.mdc (unchanged)`); identical++; }
+    else if (r.status === 'user-modified') { console.log(`  ! ${ruleName}.mdc (LOCALLY MODIFIED — kept)`); userModified.push(`${ruleName}.mdc`); }
+  }
+
+  // Ambient routing rule — alwaysApply so cp routing happens without the
+  // user having to remember to @-attach anything.
+  const ctxFile = path.join(target, 'context-planning.mdc');
+  const ctxBody = `<!-- context-planning (cp) — managed by cp installer -->
+# Instructions for context-planning (cp)
+
+When the user invokes a \`/cp-*\` or \`cp-*\` workflow, route to the matching
+\`cp-<name>\` Cursor rule (under \`.cursor/rules/\`). Attach it to context if
+not already attached, and follow its body verbatim.
+
+\`cp\` owns the **state layer** (\`.planning/PROJECT.md\`, \`ROADMAP.md\`,
+\`STATE.md\`, phase dirs). It delegates **workflow** to whatever provider is
+configured in \`.planning/config.json\` under the top-level \`cp:\` block
+(default provider: superpowers).
+
+For each role (brainstorm, plan, execute, review, finish, etc.) invoke the
+provider's primitive (or do the work in-chat if no provider is configured),
+then return to cp to record the state change. Always update
+\`.planning/STATE.md\` after a phase / quick task is completed; tick the
+matching checkbox in \`.planning/ROADMAP.md\`; write the \`SUMMARY.md\`.
+
+Only invoke cp commands when the user explicitly asks. Don't apply cp
+workflows unbidden.
+<!-- /context-planning -->
+`;
+  const ctxRule = buildRule({ name: 'context-planning', body: ctxBody, alwaysApply: true });
+  const ctxR = writeFileSafe(ctxFile, ctxRule, { force });
+  if (ctxR.status === 'user-modified') userModified.push('context-planning.mdc');
+
+  console.log(`\nInstalled: ${written} written, ${identical} unchanged${userModified.length ? `, ${userModified.length} kept (locally modified)` : ''}.`);
+  console.log(`Ambient rule: ${ctxFile} (${ctxR.status})`);
+  if (userModified.length > 0) {
+    console.log(`\n⚠ The following rule files exist on disk with local modifications and were NOT overwritten:`);
+    for (const f of userModified) console.log(`    - ${f}`);
+    console.log(`  Re-run with \`cp install cursor --force\` to overwrite them, or delete the local copy first.`);
+  }
+  console.log(`\nNext steps:`);
+  console.log(`  1. Reload Cursor (or run "Cursor: Reload Window") to pick up the new rules.`);
+  console.log(`  2. In a project directory:  cp init`);
+  console.log(`  3. In Cursor chat:          @cp-new-milestone "my first milestone"`);
+  console.log(`     (or any other @cp-<name> rule)`);
+
+  return { written, identical, userModified };
+}
+
+module.exports = { install, buildRule };

package/install/echo-provider.js

@@ -0,0 +1,50 @@
+'use strict';
+
+/**
+ * Installer for the echo-provider schema-test stub.
+ *
+ * Plants a minimal SKILL.md at .planning/providers/echo-provider/skills/echo/SKILL.md
+ * so the echo-provider entry in config.json can be detected and resolved.
+ *
+ * Usage: cp install echo-provider [--local]
+ * (--local is implicit; echo-provider always installs to the project)
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { planningDir, repoRoot } = require('../lib/paths');
+
+const SKILL_CONTENT = `---
+name: echo
+description: Schema-test stub skill. Echoes the role name. Not for end users.
+---
+
+# Echo skill
+
+This is a schema-test stub installed by \`cp install echo-provider\`.
+It exists solely to prove that cp's provider detection schema works
+with more than one provider. It does nothing useful.
+
+When invoked for any role (plan, execute, brainstorm, etc.), simply
+acknowledge that the echo-provider was reached and the role name was
+received. Do not perform any actual work.
+`;
+
+function install() {
+  const root = repoRoot();
+  const providerDir = path.join(planningDir(root), 'providers', 'echo-provider');
+  const skillDir = path.join(providerDir, 'skills', 'echo');
+  const skillPath = path.join(skillDir, 'SKILL.md');
+
+  fs.mkdirSync(skillDir, { recursive: true });
+  fs.writeFileSync(skillPath, SKILL_CONTENT);
+
+  const results = [
+    { file: path.relative(root, skillPath), status: 'created' },
+    { file: path.relative(root, providerDir), status: 'detectable' },
+  ];
+
+  return { results };
+}
+
+module.exports = { install };

package/lib/codebase-mapper.js

@@ -0,0 +1,169 @@
+'use strict';
+
+/**
+ * lib/codebase-mapper.js — state-layer support for `/cp-map-codebase`.
+ *
+ * The cp-native equivalent of GSD's `gsd-map-codebase`. Owns:
+ *   - scaffolding the `.planning/codebase/` directory with 7 stub files
+ *   - reporting which docs exist + their freshness for `/cp-map-codebase`
+ *     verification & for `cp doctor`
+ *
+ * The *exploration* and *content writing* is delegated to whatever sub-agent
+ * mechanism the host harness exposes (Copilot CLI's `task` tool, Claude
+ * Code's Task tool, etc.). That dispatch lives in `commands/cp/map-codebase.md`.
+ * This module deliberately does NOT call any LLM — it's pure file I/O so it
+ * can be unit-tested without a model.
+ *
+ * Output layout (matches GSD exactly, so `cp gsd-import` stays clean):
+ *   .planning/codebase/
+ *     STACK.md         (tech focus)
+ *     INTEGRATIONS.md  (tech focus)
+ *     ARCHITECTURE.md  (arch focus)
+ *     STRUCTURE.md     (arch focus)
+ *     CONVENTIONS.md   (quality focus)
+ *     TESTING.md       (quality focus)
+ *     CONCERNS.md      (concerns focus)
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const paths = require('./paths');
+
+const DOCS = [
+  { file: 'STACK.md',        focus: 'tech',     template: 'codebase/STACK.md' },
+  { file: 'INTEGRATIONS.md', focus: 'tech',     template: 'codebase/INTEGRATIONS.md' },
+  { file: 'ARCHITECTURE.md', focus: 'arch',     template: 'codebase/ARCHITECTURE.md' },
+  { file: 'STRUCTURE.md',    focus: 'arch',     template: 'codebase/STRUCTURE.md' },
+  { file: 'CONVENTIONS.md',  focus: 'quality',  template: 'codebase/CONVENTIONS.md' },
+  { file: 'TESTING.md',      focus: 'quality',  template: 'codebase/TESTING.md' },
+  { file: 'CONCERNS.md',     focus: 'concerns', template: 'codebase/CONCERNS.md' },
+];
+
+/**
+ * The four focus areas a /cp-map-codebase dispatch will use, with the
+ * documents each one owns. Consumed by the slash command to build the
+ * 4 parallel agent prompts.
+ */
+const FOCUS_AREAS = [
+  { focus: 'tech',     docs: ['STACK.md', 'INTEGRATIONS.md'] },
+  { focus: 'arch',     docs: ['ARCHITECTURE.md', 'STRUCTURE.md'] },
+  { focus: 'quality',  docs: ['CONVENTIONS.md', 'TESTING.md'] },
+  { focus: 'concerns', docs: ['CONCERNS.md'] },
+];
+
+function codebaseDir(root) {
+  return path.join(paths.planningDir(root), 'codebase');
+}
+
+function renderTemplate(text, vars) {
+  return Object.entries(vars).reduce(
+    (acc, [k, v]) => acc.replace(new RegExp(`\\{\\{${k}\\}\\}`, 'g'), String(v)),
+    text
+  );
+}
+
+/**
+ * Create `.planning/codebase/` and seed 7 stub files from the templates.
+ *
+ * Returns { ok, actions, codebaseDir, created: [filenames], skipped: [filenames],
+ *           dryRun? }.
+ *
+ * options:
+ *   - dryRun: boolean — return actions without writing
+ *   - force: boolean — overwrite existing stubs (default false)
+ *   - today: ISO date string (for tests)
+ *
+ * Refuses to overwrite any existing file unless force=true. Does NOT refuse
+ * if the directory itself exists — only individual files.
+ */
+function scaffoldCodebase(root, options = {}) {
+  const { dryRun = false, force = false, today: todayIso } = options;
+
+  const planning = paths.planningDir(root);
+  if (!fs.existsSync(planning)) {
+    throw new Error(`.planning/ not found at ${planning}. Run \`cp init\` first.`);
+  }
+
+  const cbDir = codebaseDir(root);
+  const dateStr = todayIso || new Date().toISOString().slice(0, 10);
+
+  const actions = [];
+  const created = [];
+  const skipped = [];
+
+  if (!fs.existsSync(cbDir)) {
+    actions.push({ kind: 'mkdir', path: cbDir });
+  }
+
+  for (const doc of DOCS) {
+    const dest = path.join(cbDir, doc.file);
+    if (fs.existsSync(dest) && !force) {
+      skipped.push(doc.file);
+      continue;
+    }
+    const tplText = paths.readTemplate(doc.template);
+    const rendered = renderTemplate(tplText, { DATE: dateStr });
+    actions.push({ kind: 'write', path: dest, content: rendered, focus: doc.focus });
+    created.push(doc.file);
+  }
+
+  if (!dryRun) {
+    for (const a of actions) {
+      if (a.kind === 'mkdir') fs.mkdirSync(a.path, { recursive: true });
+      else if (a.kind === 'write') {
+        fs.mkdirSync(path.dirname(a.path), { recursive: true });
+        fs.writeFileSync(a.path, a.content);
+      }
+    }
+  }
+
+  return {
+    ok: true,
+    codebaseDir: cbDir,
+    actions,
+    created,
+    skipped,
+    dryRun: dryRun || undefined,
+  };
+}
+
+/**
+ * Inventory `.planning/codebase/`. Returns one row per expected doc with
+ * existence, line count, byte size, and a "looks-stub" heuristic.
+ *
+ * A doc looks like a stub if it's <= 40 lines OR contains the marker
+ * "fill via `/cp-map-codebase`" — both true for freshly-scaffolded files.
+ */
+function codebaseStatus(root) {
+  const cbDir = codebaseDir(root);
+  const dirExists = fs.existsSync(cbDir);
+
+  const rows = DOCS.map((doc) => {
+    const p = path.join(cbDir, doc.file);
+    const exists = fs.existsSync(p);
+    if (!exists) {
+      return { file: doc.file, focus: doc.focus, exists: false, lines: 0, bytes: 0, looksStub: null };
+    }
+    const txt = fs.readFileSync(p, 'utf8');
+    const lines = txt.split('\n').length;
+    const bytes = Buffer.byteLength(txt, 'utf8');
+    const looksStub =
+      lines <= 40 ||
+      txt.includes('fill via `/cp-map-codebase`');
+    return { file: doc.file, focus: doc.focus, exists: true, lines, bytes, looksStub };
+  });
+
+  const allExist = rows.every((r) => r.exists);
+  const allFilled = rows.every((r) => r.exists && r.looksStub === false);
+
+  return { dirExists, codebaseDir: cbDir, rows, allExist, allFilled };
+}
+
+module.exports = {
+  DOCS,
+  FOCUS_AREAS,
+  codebaseDir,
+  scaffoldCodebase,
+  codebaseStatus,
+};