@axis-bootstrap/cli 0.1.0

package/src/commands/spdd.js

@@ -0,0 +1,139 @@
+import { intro, outro, text, log, note, confirm } from '@clack/prompts';
+import pc from 'picocolors';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { findTarget, exists, read, write, TEMPLATES, ensureDir } from '../lib/paths.js';
+
+const STEPS = {
+  story: {
+    skill: 'story-decompose',
+    fills: 'R (Requirements)',
+    desc: 'Break a large requirement into INVEST stories with G/W/T ACs.',
+  },
+  align: {
+    skill: 'alignment',
+    fills: 'O scope + N (Norms) + S₂ (Safeguards)',
+    desc: 'Lock intent, scope, engineering norms, and non-negotiable invariants.',
+  },
+  design: {
+    skill: 'abstraction-first',
+    fills: 'E (Entities) + A (Approach) + S₁ (System structure)',
+    desc: 'Design objects, layer boundaries, and variation points before code.',
+  },
+  review: {
+    skill: 'iterative-review',
+    fills: 'Canvas ⇄ code drift',
+    desc: 'Two-track review: logic correction (spec → code) or refactor sync (code → spec).',
+  },
+  sync: {
+    skill: 'iterative-review',
+    fills: 'Canvas ⇄ code (Track B)',
+    desc: 'Sync Canvas back to code after a refactor (no behavior change).',
+  },
+};
+
+export async function spdd(argv) {
+  const sub = argv[0];
+  const rest = argv.slice(1);
+
+  if (!sub || sub === 'help' || sub === '--help') {
+    printSpddHelp();
+    return;
+  }
+
+  if (sub === 'canvas') {
+    await scaffoldCanvas(rest);
+    return;
+  }
+
+  if (!STEPS[sub]) {
+    log.error(`Unknown SPDD step: ${pc.red(sub)}`);
+    printSpddHelp();
+    process.exit(1);
+  }
+
+  await invokeSkill(sub, rest);
+}
+
+function printSpddHelp() {
+  console.log();
+  console.log(pc.bold('SPDD pipeline') + pc.dim(' — produces a REASONS Canvas, then code'));
+  console.log();
+  console.log(`  ${pc.cyan('axis spdd story')}     ${pc.dim('→ R')}        Decompose into INVEST stories`);
+  console.log(`  ${pc.cyan('axis spdd align')}     ${pc.dim('→ O+N+S₂')}   Lock scope, norms, safeguards`);
+  console.log(`  ${pc.cyan('axis spdd design')}    ${pc.dim('→ E+A+S₁')}   Entities, approach, structure`);
+  console.log(`  ${pc.cyan('axis spdd canvas')}    ${pc.dim('<slug>')}     Scaffold a new Canvas file`);
+  console.log(`  ${pc.cyan('axis spdd review')}    ${pc.dim('Track A/B')}  Iterative review after code gen`);
+  console.log(`  ${pc.cyan('axis spdd sync')}      ${pc.dim('Track B')}    Sync Canvas after refactor`);
+  console.log();
+  console.log(pc.dim('Each step prints the trigger phrase to paste into your AI tool (Claude Code, Cursor, etc.).'));
+  console.log();
+}
+
+async function scaffoldCanvas(rest) {
+  intro(pc.bgBlue(pc.white(' axis spdd canvas ')));
+  const target = findTarget();
+  let slug = rest[0];
+  if (!slug) {
+    slug = await text({
+      message: 'Canvas slug (kebab-case)?',
+      placeholder: 'pricing-quote',
+      validate: (v) => (/^[a-z0-9-]+$/.test(v) ? undefined : 'kebab-case only: a-z, 0-9, -'),
+    });
+  }
+
+  const dest = path.join(target, '.ai', 'docs', 'canvases', `${slug}.md`);
+  if (exists(dest)) {
+    const overwrite = await confirm({ message: `${slug}.md exists. Overwrite?`, initialValue: false });
+    if (!overwrite || typeof overwrite === 'symbol') {
+      outro(pc.yellow('Aborted.'));
+      return;
+    }
+  }
+
+  ensureDir(path.dirname(dest));
+  const tpl = read(path.join(TEMPLATES, 'CANVAS.md')).replace(/{{SLUG}}/g, slug);
+  write(dest, tpl);
+
+  note(
+    [
+      `${pc.green('✓')} Scaffolded ${pc.cyan(path.relative(target, dest))}`,
+      '',
+      `${pc.bold('Next steps (in order):')}`,
+      `  1. ${pc.cyan('axis spdd story')}   — fill R`,
+      `  2. ${pc.cyan('axis spdd align')}   — fill O + N + S₂`,
+      `  3. ${pc.cyan('axis spdd design')}  — fill E + A + S₁`,
+      `  4. Generate code (your AI tool, using O as prompt)`,
+      `  5. ${pc.cyan('axis spdd review')}  — verify diff against Canvas`,
+    ].join('\n'),
+    'Canvas created'
+  );
+  outro(pc.green('done'));
+}
+
+async function invokeSkill(step, rest) {
+  const meta = STEPS[step];
+  intro(pc.bgBlue(pc.white(` axis spdd ${step} `)));
+
+  const target = findTarget();
+  const skillPath = path.join(target, '.ai', 'skills', meta.skill, 'SKILL.md');
+  const hasSkill = exists(skillPath);
+
+  note(
+    [
+      `${pc.bold('Skill:')}     ${pc.cyan(meta.skill)} ${hasSkill ? pc.green('(installed)') : pc.yellow('(not installed in this project)')}`,
+      `${pc.bold('Fills:')}     ${meta.fills}`,
+      `${pc.bold('Purpose:')}   ${pc.dim(meta.desc)}`,
+    ].join('\n'),
+    `SPDD step: ${step}`
+  );
+
+  if (!hasSkill) {
+    log.warn(`Skill ${meta.skill} not present in .ai/skills/. Add it from the AXIS framework repo or copy SKILL.md.`);
+  }
+
+  const trigger = `Load the ${meta.skill} skill and apply it. Update the active Canvas at .ai/docs/canvases/<slug>.md.`;
+
+  note(pc.cyan(trigger), 'Paste this into your AI tool');
+  outro(pc.green('done'));
+}

package/src/commands/state.js

@@ -0,0 +1,21 @@
+import { log } from '@clack/prompts';
+import pc from 'picocolors';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { findTarget, exists } from '../lib/paths.js';
+
+export async function state(argv) {
+  const target = path.resolve(argv[0] || findTarget());
+  const p = path.join(target, '.ai', 'docs', 'STATE.md');
+
+  if (!exists(p)) {
+    log.error(`Not found: ${pc.red(p)}\nRun \`axis init\` first.`);
+    process.exit(1);
+  }
+
+  const editor = process.env.EDITOR || process.env.VISUAL || 'vi';
+  log.info(`Opening ${pc.cyan(p)} in ${pc.bold(editor)}`);
+
+  const child = spawn(editor, [p], { stdio: 'inherit' });
+  child.on('exit', (code) => process.exit(code || 0));
+}

package/src/index.js

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+import { intro, outro, log } from '@clack/prompts';
+import pc from 'picocolors';
+import { init } from './commands/init.js';
+import { doctor } from './commands/doctor.js';
+import { link } from './commands/link.js';
+import { audit } from './commands/audit.js';
+import { state } from './commands/state.js';
+import { spdd } from './commands/spdd.js';
+import { cleanup } from './commands/cleanup.js';
+
+const VERSION = '0.1.0';
+
+const BANNER = `
+${pc.cyan('  █████╗ ██╗  ██╗██╗███████╗')}
+${pc.cyan(' ██╔══██╗╚██╗██╔╝██║██╔════╝')}
+${pc.cyan(' ███████║ ╚███╔╝ ██║███████╗')}
+${pc.cyan(' ██╔══██║ ██╔██╗ ██║╚════██║')}
+${pc.cyan(' ██║  ██║██╔╝ ██╗██║███████║')}
+${pc.cyan(' ╚═╝  ╚═╝╚═╝  ╚═╝╚═╝╚══════╝')}
+${pc.dim('  Harness · Spec · Memory · v' + VERSION)}
+`;
+
+const HELP = `
+${pc.bold('axis')} ${pc.dim('— Harness-first AI project framework')}
+
+${pc.bold('Usage:')}
+  ${pc.cyan('axis')} ${pc.yellow('<command>')} ${pc.dim('[options]')}
+
+${pc.bold('Commands:')}
+  ${pc.yellow('init')}              Bootstrap (auto-detects new vs existing project, asks PT/EN)
+  ${pc.yellow('audit')}             Audit existing project for AXIS gaps
+  ${pc.yellow('doctor')}            Validate limits, symlinks, and recursiveness contract
+  ${pc.yellow('link')}              Run setup-ide-links.sh (idempotent symlink installer)
+  ${pc.yellow('state')}             Open .ai/docs/STATE.md in $EDITOR
+  ${pc.yellow('spdd')} <step>       Run SPDD pipeline step (story | align | design | canvas | review | sync)
+  ${pc.yellow('cleanup')}           Remove the axis-bootstrap meta-skill after AI-driven init completes
+  ${pc.yellow('help')}              Show this help
+  ${pc.yellow('version')}           Print version
+
+${pc.bold('SPDD pipeline:')}
+  ${pc.cyan('axis spdd story')}     Decompose requirement → INVEST stories ${pc.dim('(fills R)')}
+  ${pc.cyan('axis spdd align')}     Lock O scope, Norms, Safeguards         ${pc.dim('(fills O + N + S₂)')}
+  ${pc.cyan('axis spdd design')}    Entities, Approach, System structure    ${pc.dim('(fills E + A + S₁)')}
+  ${pc.cyan('axis spdd canvas')}    Scaffold a new REASONS Canvas
+  ${pc.cyan('axis spdd review')}    Iterative review (Track A or B)
+  ${pc.cyan('axis spdd sync')}      Sync Canvas ⇄ code after refactor
+
+${pc.bold('Examples:')}
+  ${pc.dim('$')} axis init
+  ${pc.dim('$')} axis doctor
+  ${pc.dim('$')} axis spdd canvas pricing-quote
+  ${pc.dim('$')} axis audit ./my-project
+
+${pc.dim('Docs:')} ${pc.underline('https://github.com/axis-framework')}
+`;
+
+const args = process.argv.slice(2);
+const cmd = args[0];
+
+async function main() {
+  if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') {
+    console.log(BANNER);
+    console.log(HELP);
+    return;
+  }
+  if (cmd === 'version' || cmd === '--version' || cmd === '-v') {
+    console.log(VERSION);
+    return;
+  }
+
+  console.log(BANNER);
+
+  const rest = args.slice(1);
+  switch (cmd) {
+    case 'init':
+      intro(pc.bgCyan(pc.black(' axis init ')));
+      await init(rest);
+      outro(pc.green('done'));
+      break;
+    case 'audit':
+      intro(pc.bgYellow(pc.black(' axis audit ')));
+      await audit(rest);
+      break;
+    case 'doctor':
+      intro(pc.bgGreen(pc.black(' axis doctor ')));
+      await doctor(rest);
+      break;
+    case 'link':
+      intro(pc.bgMagenta(pc.black(' axis link ')));
+      await link(rest);
+      break;
+    case 'state':
+      await state(rest);
+      break;
+    case 'spdd':
+      await spdd(rest);
+      break;
+    case 'cleanup':
+      await cleanup(rest);
+      break;
+    default:
+      log.error(`Unknown command: ${pc.red(cmd)}`);
+      console.log(HELP);
+      process.exit(1);
+  }
+}
+
+main().catch((err) => {
+  log.error(pc.red(err.message));
+  if (process.env.AXIS_DEBUG) console.error(err.stack);
+  process.exit(1);
+});

package/src/lib/copy.js

@@ -0,0 +1,19 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+/** Recursively copy a directory. Skips if src missing. */
+export function copyDir(src, dest) {
+  if (!fs.existsSync(src)) return;
+  fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const s = path.join(src, entry.name);
+    const d = path.join(dest, entry.name);
+    if (entry.isDirectory()) copyDir(s, d);
+    else fs.copyFileSync(s, d);
+  }
+}
+
+export function rmDir(p) {
+  if (!fs.existsSync(p)) return;
+  fs.rmSync(p, { recursive: true, force: true });
+}

package/src/lib/detect.js

@@ -0,0 +1,70 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+const IGNORED = new Set(['.git', '.DS_Store', 'node_modules', '.idea', '.vscode', 'dist', 'build', '.next']);
+
+const PROJECT_MARKERS = {
+  software: [
+    'package.json',
+    'pyproject.toml',
+    'setup.py',
+    'requirements.txt',
+    'Cargo.toml',
+    'go.mod',
+    'pom.xml',
+    'build.gradle',
+    'build.gradle.kts',
+    'composer.json',
+    'Gemfile',
+    'mix.exs',
+    'pubspec.yaml',
+    'Package.swift',
+    'CMakeLists.txt',
+    'Makefile',
+    'Dockerfile',
+  ],
+  // Non-software heuristics
+  content: ['_config.yml', 'mkdocs.yml', 'hugo.toml', 'astro.config.mjs', 'next.config.js'],
+};
+
+/**
+ * @param {string} target absolute path
+ * @returns {{ state: 'empty'|'existing-software'|'existing-other'|'already-bootstrapped',
+ *            stackHints: string[], topFiles: string[] }}
+ */
+export function detectProject(target) {
+  if (fs.existsSync(path.join(target, '.ai', 'INSTRUCTIONS.md'))) {
+    return { state: 'already-bootstrapped', stackHints: [], topFiles: [] };
+  }
+
+  let entries;
+  try {
+    entries = fs.readdirSync(target).filter((e) => !IGNORED.has(e));
+  } catch {
+    return { state: 'empty', stackHints: [], topFiles: [] };
+  }
+
+  if (entries.length === 0) {
+    return { state: 'empty', stackHints: [], topFiles: [] };
+  }
+
+  const stackHints = [];
+  for (const marker of PROJECT_MARKERS.software) {
+    if (fs.existsSync(path.join(target, marker))) {
+      stackHints.push(marker);
+    }
+  }
+
+  const topFiles = entries.slice(0, 12);
+
+  if (stackHints.length > 0) {
+    return { state: 'existing-software', stackHints, topFiles };
+  }
+
+  // Has files but no software markers — might be content/research/business
+  if (entries.length > 0) {
+    return { state: 'existing-other', stackHints: [], topFiles };
+  }
+
+  return { state: 'empty', stackHints: [], topFiles: [] };
+}

package/src/lib/i18n.js

@@ -0,0 +1,147 @@
+/**
+ * Minimal i18n. Detects locale from env; user can override.
+ */
+
+export function detectLocale() {
+  const lang = (process.env.LANG || process.env.LC_ALL || process.env.LC_MESSAGES || '').toLowerCase();
+  if (lang.startsWith('pt')) return 'pt';
+  return 'en';
+}
+
+const STRINGS = {
+  en: {
+    // language picker
+    pickLang: 'Language / Idioma?',
+    langEN: 'English',
+    langPT: 'Português',
+
+    // detection messages
+    detectingProject: 'Inspecting target directory…',
+    detectedEmpty: 'Empty directory detected — new project flow.',
+    detectedExisting: 'Existing project detected. AXIS will let an AI agent analyze it before generating skills.',
+    detectedAlreadyBootstrapped: '.ai/INSTRUCTIONS.md already exists.',
+
+    // mode picker
+    pickMode: 'How do you want to bootstrap?',
+    modeQuick: 'Quick scaffold (no AI) — good for new projects, fills templates from your answers',
+    modeAI: 'AI-driven bootstrap (recommended for existing projects) — installs the axis-bootstrap skill so an AI agent reads your code and generates customized skills/rules/docs',
+    modeAudit: 'Audit only — report what is missing without writing',
+
+    // project meta
+    askName: 'Project name?',
+    askPurpose: 'One-sentence purpose of the project?',
+    askPurposeHint: 'e.g. "Pricing engine for marketplace plans"',
+    askPurposeShort: 'Please write at least one sentence',
+    askStack: 'Stack / tools (comma-separated)?',
+    askStackHint: 'e.g. "TypeScript, Node 20, PostgreSQL" — leave empty for non-software',
+    askIDEs: 'Which IDEs / agents will read this project?',
+    askSpdd: 'Which SPDD skills should be installed?',
+    askSpddHint: 'These power the per-feature workflow: story → align → design → review',
+
+    // ai-driven flow
+    aiInstalling: 'Installing axis-bootstrap skill bundle…',
+    aiNextSteps: 'Next steps',
+    aiOpenAgent: '1. Open this project in Claude Code, Cursor, Windsurf, or any IDE with AI',
+    aiTrigger: '2. Send this prompt to the agent:',
+    aiTriggerText:
+      'Load the axis-bootstrap skill (.ai/skills/axis-bootstrap/SKILL.md) and execute it on this project. Read the codebase first, then run all 5 phases with gates. Stop and ask between phases.',
+    aiCleanup: '3. After the agent finishes Phase 5, run `axis cleanup` to remove the bootstrap skill (it is no longer needed — your project is now self-sufficient).',
+
+    // quick flow
+    quickScaffolding: 'Scaffolding .ai/ structure',
+    quickSpecReady: 'Spec layer ready',
+    quickHarnessReady: 'Harness layer ready',
+    quickInstallerReady: 'Symlink installer ready',
+    quickSymlinksInstalled: 'Symlinks installed',
+    quickDoneScaffolding: 'Scaffolding done (symlinks not auto-installed)',
+    quickRunLink: 'Run `axis link` manually after reviewing setup-ide-links.sh',
+    quickCreated: 'Created',
+    quickNext1: 'Open .ai/INSTRUCTIONS.md and refine the architecture table',
+    quickNext2: 'Add your first skill: $EDITOR .ai/skills/<name>/SKILL.md',
+    quickNext3: 'Run `axis doctor` to verify limits and symlinks',
+    quickNext4: 'Per feature: `axis spdd canvas <slug>` → fill REASONS Canvas',
+
+    // cleanup
+    cleanupConfirm:
+      'This will remove .ai/skills/axis-bootstrap/ (the meta bootstrap skill). Your generated skills, rules, docs, and STATE.md stay intact. Continue?',
+    cleanupRemoved: 'Bootstrap skill removed. Project is fully self-sufficient now.',
+    cleanupNotFound: 'No axis-bootstrap skill found in .ai/skills/. Nothing to remove.',
+    cleanupAborted: 'Aborted — no changes made.',
+
+    // common
+    abortedAlready: 'Aborted. Run `axis audit` to inspect existing structure instead.',
+    overwrite: 'Overwrite?',
+    aborted: 'Aborted.',
+    done: 'done',
+    bootstrapPlan: 'Bootstrap plan',
+    target: 'Target',
+  },
+  pt: {
+    pickLang: 'Idioma / Language?',
+    langEN: 'English',
+    langPT: 'Português',
+
+    detectingProject: 'Inspecionando o diretório-alvo…',
+    detectedEmpty: 'Diretório vazio detectado — fluxo de projeto novo.',
+    detectedExisting:
+      'Projeto existente detectado. O AXIS vai deixar um agente de IA analisar o código antes de gerar skills.',
+    detectedAlreadyBootstrapped: '.ai/INSTRUCTIONS.md já existe.',
+
+    pickMode: 'Como deseja inicializar?',
+    modeQuick:
+      'Scaffold rápido (sem IA) — bom para projetos novos; preenche templates com suas respostas',
+    modeAI:
+      'Bootstrap guiado por IA (recomendado para projetos existentes) — instala a skill axis-bootstrap para que um agente leia seu código e gere skills/rules/docs customizadas',
+    modeAudit: 'Apenas auditar — relata o que falta sem escrever',
+
+    askName: 'Nome do projeto?',
+    askPurpose: 'Em uma frase: para que serve o projeto?',
+    askPurposeHint: 'ex.: "Motor de preços para planos de marketplace"',
+    askPurposeShort: 'Escreva ao menos uma frase',
+    askStack: 'Stack / ferramentas (separadas por vírgula)?',
+    askStackHint: 'ex.: "TypeScript, Node 20, PostgreSQL" — deixe vazio se não for software',
+    askIDEs: 'Quais IDEs / agentes vão ler este projeto?',
+    askSpdd: 'Quais skills SPDD instalar?',
+    askSpddHint: 'Compõem o pipeline por feature: story → align → design → review',
+
+    aiInstalling: 'Instalando bundle da skill axis-bootstrap…',
+    aiNextSteps: 'Próximos passos',
+    aiOpenAgent:
+      '1. Abra este projeto no Claude Code, Cursor, Windsurf ou qualquer IDE com IA',
+    aiTrigger: '2. Envie este prompt para o agente:',
+    aiTriggerText:
+      'Carregue a skill axis-bootstrap (.ai/skills/axis-bootstrap/SKILL.md) e execute neste projeto. Leia o código primeiro, depois rode as 5 fases com gates. Pause e pergunte entre cada fase.',
+    aiCleanup:
+      '3. Quando o agente terminar a Phase 5, rode `axis cleanup` para remover a skill bootstrap (não é mais necessária — seu projeto agora é autossuficiente).',
+
+    quickScaffolding: 'Criando estrutura .ai/',
+    quickSpecReady: 'Spec layer pronta',
+    quickHarnessReady: 'Harness layer pronta',
+    quickInstallerReady: 'Instalador de symlinks pronto',
+    quickSymlinksInstalled: 'Symlinks instalados',
+    quickDoneScaffolding: 'Scaffold concluído (symlinks não foram instalados)',
+    quickRunLink: 'Rode `axis link` manualmente após revisar setup-ide-links.sh',
+    quickCreated: 'Criado',
+    quickNext1: 'Abra .ai/INSTRUCTIONS.md e refine a tabela de arquitetura',
+    quickNext2: 'Adicione sua primeira skill: $EDITOR .ai/skills/<nome>/SKILL.md',
+    quickNext3: 'Rode `axis doctor` para validar limites e symlinks',
+    quickNext4: 'Por feature: `axis spdd canvas <slug>` → preencha o Canvas REASONS',
+
+    cleanupConfirm:
+      'Isso remove .ai/skills/axis-bootstrap/ (a meta-skill do bootstrap). Suas skills, rules, docs e STATE.md geradas permanecem. Continuar?',
+    cleanupRemoved: 'Skill bootstrap removida. O projeto agora é autossuficiente.',
+    cleanupNotFound: 'Nenhuma skill axis-bootstrap encontrada em .ai/skills/. Nada a remover.',
+    cleanupAborted: 'Cancelado — nada foi alterado.',
+
+    abortedAlready: 'Cancelado. Rode `axis audit` para inspecionar a estrutura existente.',
+    overwrite: 'Sobrescrever?',
+    aborted: 'Cancelado.',
+    done: 'concluído',
+    bootstrapPlan: 'Plano de bootstrap',
+    target: 'Destino',
+  },
+};
+
+export function t(locale, key) {
+  return (STRINGS[locale] && STRINGS[locale][key]) || STRINGS.en[key] || key;
+}

package/src/lib/paths.js

@@ -0,0 +1,45 @@
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+import fs from 'node:fs';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+export const CLI_ROOT = path.resolve(__dirname, '..', '..');
+export const TEMPLATES = path.join(CLI_ROOT, 'templates');
+
+/** AXIS framework repo (where this CLI lives — for fallback templates). */
+export const FRAMEWORK_ROOT = path.resolve(CLI_ROOT, '..');
+
+/** Look up the target project from CWD upward (where .ai/ exists or will be created). */
+export function findTarget(start = process.cwd()) {
+  let dir = path.resolve(start);
+  while (true) {
+    if (fs.existsSync(path.join(dir, '.ai'))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) return path.resolve(start); // not found, default to cwd
+    dir = parent;
+  }
+}
+
+export function ensureDir(p) {
+  fs.mkdirSync(p, { recursive: true });
+}
+
+export function exists(p) {
+  return fs.existsSync(p);
+}
+
+export function read(p) {
+  return fs.readFileSync(p, 'utf8');
+}
+
+export function write(p, content) {
+  ensureDir(path.dirname(p));
+  fs.writeFileSync(p, content);
+}
+
+export function countLines(p) {
+  if (!exists(p)) return 0;
+  return read(p).split('\n').length;
+}

package/src/lib/ui.js

@@ -0,0 +1,29 @@
+import pc from 'picocolors';
+import { log } from '@clack/prompts';
+
+export const ok = (msg) => log.success(pc.green('✓ ') + msg);
+export const fail = (msg) => log.error(pc.red('✗ ') + msg);
+export const warn = (msg) => log.warn(pc.yellow('! ') + msg);
+export const info = (msg) => log.info(pc.cyan('· ') + msg);
+
+export function tag(label, color = 'cyan') {
+  return pc[color](`[${label}]`);
+}
+
+export function box(title, lines) {
+  const width = Math.max(title.length, ...lines.map((l) => stripAnsi(l).length)) + 4;
+  const top = '╭' + '─'.repeat(width - 2) + '╮';
+  const bot = '╰' + '─'.repeat(width - 2) + '╯';
+  console.log(pc.dim(top));
+  console.log(pc.dim('│ ') + pc.bold(title) + ' '.repeat(width - 4 - title.length) + pc.dim(' │'));
+  console.log(pc.dim('│' + ' '.repeat(width - 2) + '│'));
+  for (const l of lines) {
+    const pad = width - 4 - stripAnsi(l).length;
+    console.log(pc.dim('│ ') + l + ' '.repeat(Math.max(0, pad)) + pc.dim(' │'));
+  }
+  console.log(pc.dim(bot));
+}
+
+function stripAnsi(s) {
+  return s.replace(/\x1b\[[0-9;]*m/g, '');
+}

package/templates/CANVAS.md

@@ -0,0 +1,48 @@
+# Canvas — {{SLUG}}
+
+> One-page REASONS spec. If it doesn't fit, run `axis spdd story` to re-decompose.
+
+## R — Requirements
+**Story:** As a <role>, I want <capability>, so that <value>.
+**ACs (Given/When/Then):**
+- Given …, When …, Then … (concrete numeric expected value)
+- Given …, When …, Then …
+**Definition of Done:**
+- [ ] All ACs verified with automated tests
+- [ ] …
+
+## E — Entities
+- **<EntityA>** — single responsibility: …; relates to <EntityB> via …
+- **<EntityB>** — …
+
+## A — Approach (strategy)
+<1-3 sentences on the strategy chosen to satisfy R.>
+
+## S₁ — System structure
+**Layers:** Controller → Service → Repository → Domain
+**Components:**
+- `<Service>` (new/modified) — …
+- `<Strategy>` interface — …
+**File tree (closed scope):**
+```text
+src/
+└── …
+tests/
+└── …
+```
+
+## O — Operations
+- [ ] `<function or endpoint>(input) → output` — references AC #1
+- [ ] …
+
+## N — Norms
+- Naming: …
+- Logging: structured JSON with `correlationId` on every Service entry/exit
+- Errors: throw `DomainError` for business rule violations
+- Tests: AAA, no shared mutable fixtures
+
+## S₂ — Safeguards (invariants)
+- <Invariant 1>
+- <Invariant 2>
+- No PII in logs
+- DROP/TRUNCATE never executed without explicit confirmation

package/templates/CONVENTIONS.md

@@ -0,0 +1,43 @@
+# Conventions — How {{PROJECT_NAME}} Maintains Its AI Layer
+
+## Single Source of Truth
+
+All AI content lives in `.ai/`. IDE folders (`.claude/`, `.cursor/`, `.agents/`, `.github/`) contain only symlinks created by `setup-ide-links.sh`.
+
+## Progressive Disclosure
+
+| Layer | Loads | Limit |
+| ----- | ----- | ----- |
+| Discovery | Always | INSTRUCTIONS ≤ 180 lines |
+| Index | When relevant | SKILL.md ≤ 60 lines |
+| On-demand | When needed | references/*.md |
+
+## REASONS Canvas (SPDD pipeline)
+
+Every non-trivial feature has a Canvas in `.ai/docs/canvases/<slug>.md`. Filled by:
+1. `story-decompose` → R (Requirements)
+2. `alignment` → O scope + N (Norms) + S₂ (Safeguards)
+3. `abstraction-first` → E (Entities) + A (Approach) + S₁ (System structure)
+4. (code generation)
+5. `iterative-review` → keeps Canvas ⇄ code in sync
+
+## Bidirectional Spec-Code Sync
+
+| Change | Direction |
+| ------ | --------- |
+| New requirement / bug fix | spec → code (update Canvas first) |
+| Refactor (no behavior change) | code → spec (sync Canvas after) |
+
+## Knowledge Verification Chain
+
+Before asserting anything: codebase → project docs → official docs → web → mark uncertain. Never fabricate.
+
+## Adding a New IDE
+
+Add 3-4 `ln -s` lines to `setup-ide-links.sh`. Re-run script (idempotent).
+
+## Session Closing Protocol
+
+1. Update `docs/STATE.md` (curate, don't append)
+2. Identify skills/docs affected by behavioral changes
+3. Update them in the same session