@axis-bootstrap/cli 0.1.0

package/README.md

@@ -0,0 +1,90 @@
+# @axis-bootstrap/cli
+
+> CLI for the [AXIS framework](../FRAMEWORK.md) — bootstrap AI-augmented projects with Spec + Harness + Memory.
+
+## Install
+
+```bash
+# one-shot, no install
+npx @axis-bootstrap/cli init
+
+# or install globally
+npm i -g @axis-bootstrap/cli
+axis init
+```
+
+> Binary command stays short: `axis`. Package name is scoped: `@axis-bootstrap/cli`.
+
+## How it works
+
+`axis init` **auto-detects** your context and asks in **PT or EN** based on `$LANG`:
+
+| Detected | Default mode | What happens |
+| -------- | ------------ | ------------ |
+| Empty directory | **Quick scaffold** | Interactive prompts → fills templates with your answers (no AI needed) |
+| Existing project (has `package.json`, etc.) | **AI-driven** | Installs the `axis-bootstrap` skill bundle. You then ask your AI tool (Claude Code / Cursor / Copilot) to "execute axis-bootstrap" — the agent reads your code, runs 5 phases with gates, and generates customized `.ai/` skills/rules/docs |
+| Already has `.ai/` | Asks before overwriting | — |
+
+You can override: pick **Quick**, **AI-driven**, or **Audit-only** at the prompt.
+
+## After AI-driven init
+
+The agent finishes Phase 5 → you run:
+
+```bash
+axis cleanup
+```
+
+This removes `.ai/skills/axis-bootstrap/` (it has done its job). Your project keeps:
+
+- `.ai/INSTRUCTIONS.md` (custom for your project)
+- `.ai/skills/<your-domains>/` (generated based on your code)
+- `.ai/rules/`, `.ai/docs/`, `.ai/docs/STATE.md`
+- `.claude/settings.json`, symlinks
+
+→ **Fully self-sufficient.** No dependency on `@axis-bootstrap/cli` after this. You can `npm uninstall -g @axis-bootstrap/cli` if you want.
+
+(Optional: keep it around for `axis doctor` / `axis spdd canvas` per-feature workflow.)
+
+## Commands
+
+| Command | Locale | What it does |
+| ------- | ------ | ------------ |
+| `axis init` | PT/EN | Interactive bootstrap (auto-detects new vs existing) |
+| `axis audit` | EN | Reports what AXIS layers are missing |
+| `axis doctor` | EN | Validates limits (INSTRUCTIONS 100-180, SKILL ≤60), symlinks, settings |
+| `axis link` | EN | Runs `setup-ide-links.sh` (idempotent) |
+| `axis state` | EN | Opens `.ai/docs/STATE.md` in `$EDITOR` |
+| `axis spdd <step>` | EN | Per-feature SPDD pipeline step |
+| `axis cleanup` | PT/EN | Removes axis-bootstrap meta-skill after AI-driven init |
+
+## SPDD pipeline (per feature)
+
+Each step prints the trigger phrase to paste into your AI tool:
+
+```bash
+axis spdd canvas pricing-quote   # scaffold .ai/docs/canvases/pricing-quote.md
+axis spdd story                  # → AI fills R section
+axis spdd align                  # → AI fills O + N + S₂
+axis spdd design                 # → AI fills E + A + S₁
+# … generate code in your AI tool …
+axis spdd review                 # AI verifies diff against Canvas
+```
+
+## Removing AXIS entirely
+
+```bash
+rm -rf .ai .claude .cursor .agents AGENTS.md CLAUDE.md setup-ide-links.sh
+```
+
+That's it. No leftover config, no `node_modules` pollution, no entries in `package.json`.
+
+## Tech
+
+- Node 18+, ESM
+- `@clack/prompts` (TUI), `picocolors` (ANSI)
+- Zero other deps. Single file per command under `src/commands/`.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@axis-bootstrap/cli",
+  "version": "0.1.0",
+  "description": "AXIS — Harness-first scaffolding & SPDD pipeline CLI for AI-augmented projects",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "axis": "src/index.js"
+  },
+  "files": [
+    "src",
+    "templates",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "start": "node src/index.js",
+    "test": "node src/index.js --help",
+    "pack:dry": "npm pack --dry-run",
+    "pack:tarball": "npm pack",
+    "prepublishOnly": "node src/index.js --help"
+  },
+  "keywords": [
+    "axis",
+    "spdd",
+    "ai",
+    "harness",
+    "spec-driven",
+    "claude-code",
+    "cursor",
+    "scaffolding"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@clack/prompts": "^0.7.0",
+    "picocolors": "^1.0.1"
+  }
+}

package/src/commands/audit.js

@@ -0,0 +1,53 @@
+import { outro, note, log } from '@clack/prompts';
+import pc from 'picocolors';
+import path from 'node:path';
+import { findTarget, exists } from '../lib/paths.js';
+
+export async function audit(argv) {
+  const target = path.resolve(argv[0] || findTarget());
+  log.info(`Target: ${pc.cyan(target)}`);
+
+  const layers = {
+    Spec: [
+      ['.ai/INSTRUCTIONS.md', 'Entry point for AI'],
+      ['.ai/skills/', 'Domain skills'],
+      ['.ai/rules/', 'Behavior rules (optional)'],
+      ['.ai/docs/', 'Reference docs (architecture, schema, glossary)'],
+    ],
+    Harness: [
+      ['.claude/settings.json', 'Versioned permissions/hooks'],
+      ['setup-ide-links.sh', 'Idempotent symlink installer'],
+      ['AGENTS.md', 'Symlink to INSTRUCTIONS'],
+      ['CLAUDE.md', 'Symlink to INSTRUCTIONS'],
+    ],
+    Memory: [
+      ['.ai/CONVENTIONS.md', 'Maintenance protocol'],
+      ['.ai/docs/STATE.md', 'Curated playbook'],
+      ['.ai/docs/canvases/', 'REASONS Canvases (per feature)'],
+    ],
+  };
+
+  for (const [layer, items] of Object.entries(layers)) {
+    const lines = items.map(([file, purpose]) => {
+      const p = path.join(target, file);
+      const ok = exists(p);
+      return `${ok ? pc.green('✓') : pc.red('✗')} ${pc.bold(file.padEnd(28))} ${pc.dim(purpose)}`;
+    });
+    note(lines.join('\n'), `${layer} Layer`);
+  }
+
+  const missing = Object.values(layers)
+    .flat()
+    .filter(([file]) => !exists(path.join(target, file)));
+
+  if (missing.length === 0) {
+    outro(pc.green('✓ All AXIS layers present.'));
+  } else {
+    outro(
+      pc.yellow(
+        `${missing.length} item(s) missing. Run ${pc.cyan('axis init')} to scaffold, or fix individually.`
+      )
+    );
+    process.exitCode = 1;
+  }
+}

package/src/commands/cleanup.js

@@ -0,0 +1,42 @@
+import { confirm, intro, outro, isCancel, cancel, log, note } from '@clack/prompts';
+import pc from 'picocolors';
+import path from 'node:path';
+import { findTarget, exists } from '../lib/paths.js';
+import { rmDir } from '../lib/copy.js';
+import { detectLocale, t } from '../lib/i18n.js';
+
+export async function cleanup(argv) {
+  const target = path.resolve(argv[0] || findTarget());
+  const locale = detectLocale();
+  const T = (k) => t(locale, k);
+
+  intro(pc.bgRed(pc.white(' axis cleanup ')));
+
+  const skill = path.join(target, '.ai', 'skills', 'axis-bootstrap');
+  if (!exists(skill)) {
+    log.info(T('cleanupNotFound'));
+    return outro(pc.dim(T('done')));
+  }
+
+  note(
+    [
+      pc.dim(T('target') + ': ' + target),
+      '',
+      pc.bold(pc.red('Will remove:')),
+      `  ${pc.red('-')} .ai/skills/axis-bootstrap/`,
+      '',
+      pc.bold(pc.green('Will keep:')),
+      `  ${pc.green('+')} .ai/INSTRUCTIONS.md, CONVENTIONS.md`,
+      `  ${pc.green('+')} .ai/skills/* (your generated skills)`,
+      `  ${pc.green('+')} .ai/rules/, .ai/docs/, STATE.md`,
+      `  ${pc.green('+')} .claude/settings.json, symlinks`,
+    ].join('\n'),
+    'Cleanup plan'
+  );
+
+  const ok = await confirm({ message: T('cleanupConfirm'), initialValue: true });
+  if (isCancel(ok) || !ok) return cancel(T('cleanupAborted'));
+
+  rmDir(skill);
+  outro(pc.green('✓ ' + T('cleanupRemoved')));
+}

package/src/commands/doctor.js

@@ -0,0 +1,137 @@
+import { outro, log, note } from '@clack/prompts';
+import pc from 'picocolors';
+import path from 'node:path';
+import fs from 'node:fs';
+import { findTarget, exists, countLines, read } from '../lib/paths.js';
+import { ok, fail, warn } from '../lib/ui.js';
+
+export async function doctor(argv) {
+  const target = path.resolve(argv[0] || findTarget());
+  log.info(`Target: ${pc.cyan(target)}`);
+
+  const checks = [];
+
+  // .ai/ exists
+  checks.push(check('.ai/ directory exists', exists(path.join(target, '.ai'))));
+
+  // INSTRUCTIONS.md size
+  const instr = path.join(target, '.ai', 'INSTRUCTIONS.md');
+  if (exists(instr)) {
+    const lines = countLines(instr);
+    const inRange = lines >= 100 && lines <= 180;
+    checks.push(
+      check(
+        `INSTRUCTIONS.md size (${lines} lines, target 100-180)`,
+        inRange,
+        lines < 100 ? 'too short — likely superficial' : lines > 180 ? 'too long — loses focus' : null
+      )
+    );
+  } else {
+    checks.push(check('INSTRUCTIONS.md exists', false));
+  }
+
+  // SKILL.md sizes
+  const skillsDir = path.join(target, '.ai', 'skills');
+  if (exists(skillsDir)) {
+    const skills = fs.readdirSync(skillsDir, { withFileTypes: true }).filter((d) => d.isDirectory());
+    if (skills.length === 0) {
+      checks.push(check('skills/ has at least one skill', false, 'add skills with axis spdd ...'));
+    }
+    for (const s of skills) {
+      const p = path.join(skillsDir, s.name, 'SKILL.md');
+      if (!exists(p)) {
+        checks.push(check(`${s.name}/SKILL.md exists`, false));
+        continue;
+      }
+      const lines = countLines(p);
+      const okSize = lines <= 60;
+      checks.push(check(`${s.name}/SKILL.md ≤ 60 lines (${lines})`, okSize, okSize ? null : 'move details to references/'));
+
+      // description quality: pass if multi-line OR ≥ 150 chars (substantial single line)
+      const head = read(p).split('---')[1] || '';
+      const descLine = (head.match(/description:\s*([\s\S]*?)(?:\n[a-z_]+:|$)/) || [])[1] || '';
+      const trimmed = descLine.trim();
+      const descLineCount = trimmed.split('\n').length;
+      const descLen = trimmed.length;
+      const goodDesc = descLineCount >= 2 || descLen >= 150;
+      checks.push(
+        check(
+          `${s.name} description quality (${descLineCount}L/${descLen}c)`,
+          goodDesc,
+          goodDesc ? null : 'too short — agent may ignore the skill (target: ≥2 lines or ≥150 chars)'
+        )
+      );
+    }
+  } else {
+    checks.push(check('.ai/skills/ exists', false));
+  }
+
+  // STATE.md
+  const stateP = path.join(target, '.ai', 'docs', 'STATE.md');
+  if (exists(stateP)) {
+    const lines = countLines(stateP);
+    checks.push(check(`STATE.md ≤ 80 lines (${lines})`, lines <= 80, lines > 80 ? 'curate — remove resolved entries' : null));
+  } else {
+    checks.push(check('STATE.md exists', false, 'memory layer missing'));
+  }
+
+  // CONVENTIONS.md
+  checks.push(check('CONVENTIONS.md exists', exists(path.join(target, '.ai', 'CONVENTIONS.md'))));
+
+  // Symlinks
+  const symlinks = [
+    ['AGENTS.md', '.ai/INSTRUCTIONS.md'],
+    ['CLAUDE.md', '.ai/INSTRUCTIONS.md'],
+  ];
+  for (const [link] of symlinks) {
+    const p = path.join(target, link);
+    let resolves = false;
+    try {
+      const stat = fs.lstatSync(p);
+      if (stat.isSymbolicLink()) {
+        const realP = fs.realpathSync(p);
+        resolves = exists(realP);
+      }
+    } catch {
+      resolves = false;
+    }
+    checks.push(check(`${link} symlink resolves`, resolves));
+  }
+
+  // Settings
+  const settings = path.join(target, '.claude', 'settings.json');
+  if (exists(settings)) {
+    try {
+      const json = JSON.parse(read(settings));
+      const hasAllow = Array.isArray(json?.permissions?.allow) && json.permissions.allow.length > 0;
+      const hasDeny = Array.isArray(json?.permissions?.deny) && json.permissions.deny.length > 0;
+      checks.push(check('.claude/settings.json has allow + deny', hasAllow && hasDeny));
+    } catch (e) {
+      checks.push(check('.claude/settings.json valid JSON', false, e.message));
+    }
+  } else {
+    checks.push(check('.claude/settings.json exists', false, 'harness layer incomplete'));
+  }
+
+  // Print
+  console.log();
+  for (const c of checks) {
+    if (c.pass) ok(c.label);
+    else if (c.warn) warn(`${c.label} — ${c.detail || ''}`);
+    else fail(`${c.label}${c.detail ? ' — ' + c.detail : ''}`);
+  }
+
+  const passed = checks.filter((c) => c.pass).length;
+  const failed = checks.filter((c) => !c.pass).length;
+  console.log();
+  if (failed === 0) {
+    outro(pc.green(`✓ All ${passed} checks passed. Recursiveness contract upheld.`));
+  } else {
+    outro(pc.yellow(`${passed} passed, ${pc.red(failed)} failed. Run \`axis init\` or fix above.`));
+    process.exitCode = 1;
+  }
+}
+
+function check(label, pass, detail = null) {
+  return { label, pass, detail };
+}

package/src/commands/init.js

@@ -0,0 +1,297 @@
+import { text, multiselect, select, confirm, spinner, note, log, isCancel, cancel } from '@clack/prompts';
+import pc from 'picocolors';
+import path from 'node:path';
+import fs from 'node:fs';
+import { execSync } from 'node:child_process';
+import { TEMPLATES, exists, read, write, ensureDir } from '../lib/paths.js';
+import { detectLocale, t } from '../lib/i18n.js';
+import { detectProject } from '../lib/detect.js';
+import { copyDir } from '../lib/copy.js';
+
+const IDES = [
+  { value: 'claude', label: 'Claude Code', hint: '.claude/' },
+  { value: 'cursor', label: 'Cursor', hint: '.cursor/' },
+  { value: 'agents', label: 'Generic agents (Windsurf, etc.)', hint: '.agents/' },
+  { value: 'github', label: 'GitHub Copilot', hint: '.github/' },
+];
+
+const SPDD_SKILLS = [
+  { value: 'story-decompose', label: 'story-decompose', hint: 'fills R' },
+  { value: 'alignment', label: 'alignment', hint: 'fills O + N + S₂' },
+  { value: 'abstraction-first', label: 'abstraction-first', hint: 'fills E + A + S₁' },
+  { value: 'iterative-review', label: 'iterative-review', hint: 'Track A/B' },
+];
+
+export async function init(argv) {
+  const target = path.resolve(argv[0] || process.cwd());
+
+  // 1. Pick language (auto-detect, ask once)
+  const detected = detectLocale();
+  let locale = detected;
+  const langChoice = await select({
+    message: t(detected, 'pickLang'),
+    options: [
+      { value: 'en', label: t(detected, 'langEN') },
+      { value: 'pt', label: t(detected, 'langPT') },
+    ],
+    initialValue: detected,
+  });
+  if (isCancel(langChoice)) return cancel(t(detected, 'aborted'));
+  locale = langChoice;
+  const T = (k) => t(locale, k);
+
+  // 2. Detect project state
+  const detection = detectProject(target);
+  log.info(`${T('target')}: ${pc.cyan(target)}`);
+
+  if (detection.state === 'already-bootstrapped') {
+    log.warn(T('detectedAlreadyBootstrapped'));
+    const cont = await confirm({ message: T('overwrite'), initialValue: false });
+    if (isCancel(cont) || !cont) return cancel(T('abortedAlready'));
+  }
+
+  if (detection.state === 'existing-software' || detection.state === 'existing-other') {
+    const lines = [pc.bold(T('detectedExisting'))];
+    if (detection.stackHints.length) {
+      lines.push('', pc.dim(`Markers: ${detection.stackHints.join(', ')}`));
+    }
+    if (detection.topFiles.length) {
+      lines.push(pc.dim(`Top files: ${detection.topFiles.slice(0, 8).join(', ')}`));
+    }
+    note(lines.join('\n'), T('bootstrapPlan'));
+  } else {
+    note(T('detectedEmpty'), T('bootstrapPlan'));
+  }
+
+  // 3. Pick mode (default: AI for existing projects, quick for empty)
+  const defaultMode = detection.state === 'empty' ? 'quick' : 'ai';
+  const mode = await select({
+    message: T('pickMode'),
+    options: [
+      { value: 'ai', label: T('modeAI') },
+      { value: 'quick', label: T('modeQuick') },
+      { value: 'audit', label: T('modeAudit') },
+    ],
+    initialValue: defaultMode,
+  });
+  if (isCancel(mode)) return cancel(T('aborted'));
+
+  if (mode === 'audit') {
+    const { audit } = await import('./audit.js');
+    return audit([target]);
+  }
+
+  if (mode === 'ai') {
+    return aiBootstrap(target, locale);
+  }
+
+  return quickBootstrap(target, locale);
+}
+
+/**
+ * AI-driven path: copy axis-bootstrap skill bundle, print trigger phrase.
+ * The agent does the real discovery + generation.
+ */
+async function aiBootstrap(target, locale) {
+  const T = (k) => t(locale, k);
+
+  const s = spinner();
+  s.start(T('aiInstalling'));
+
+  // Create minimal scaffolding so the agent has a place to put .ai/
+  ensureDir(path.join(target, '.ai', 'skills'));
+  ensureDir(path.join(target, '.ai', 'docs'));
+
+  // Copy bootstrap skill bundle
+  copyDir(path.join(TEMPLATES, 'bootstrap-skill'), path.join(target, '.ai', 'skills', 'axis-bootstrap'));
+
+  // Drop minimal CLAUDE.md / AGENTS.md pointing the agent to the skill
+  const stub = stubInstructions(locale);
+  if (!exists(path.join(target, '.ai', 'INSTRUCTIONS.md'))) {
+    write(path.join(target, '.ai', 'INSTRUCTIONS.md'), stub);
+  }
+  // Root entry points (actual files for now — symlinks come after Phase 3 of the bootstrap)
+  if (!exists(path.join(target, 'CLAUDE.md'))) {
+    write(path.join(target, 'CLAUDE.md'), stub);
+  }
+  if (!exists(path.join(target, 'AGENTS.md'))) {
+    write(path.join(target, 'AGENTS.md'), stub);
+  }
+
+  s.stop(pc.green('✓ ' + T('aiInstalling').replace('…', ' ' + T('done'))));
+
+  note(
+    [
+      pc.bold(T('aiOpenAgent')),
+      '',
+      pc.bold(T('aiTrigger')),
+      '',
+      pc.cyan('  ' + T('aiTriggerText')),
+      '',
+      pc.bold(T('aiCleanup')),
+    ].join('\n'),
+    T('aiNextSteps')
+  );
+}
+
+function stubInstructions(locale) {
+  if (locale === 'pt') {
+    return `# Instruções para o Agente — Bootstrap pendente
+
+> Este projeto está usando o **AXIS Framework**. O scaffold mínimo já existe; o trabalho real (gerar skills, rules, docs customizados) cabe a você, agente de IA.
+
+## Sua tarefa agora
+
+1. Carregue a skill em [.ai/skills/axis-bootstrap/SKILL.md](.ai/skills/axis-bootstrap/SKILL.md)
+2. Siga o [PLANNER.md](.ai/skills/axis-bootstrap/PLANNER.md) na ordem
+3. **Antes de qualquer pergunta:** leia README, package.json (ou equivalente), e estrutura de arquivos do projeto
+4. Pause e peça confirmação entre cada Phase
+
+## Após terminar a Phase 5
+
+Avise o usuário para rodar \`axis cleanup\` — isso remove a skill axis-bootstrap (já cumpriu seu papel) e deixa o projeto autossuficiente.
+
+## Regras invioláveis
+
+- Nunca invente: se faltar informação, pergunte
+- Nunca pule fases: cada uma tem gate explícito
+- Nunca duplique conteúdo entre arquivos: use links e symlinks
+`;
+  }
+  return `# Agent Instructions — Bootstrap pending
+
+> This project is using the **AXIS Framework**. Minimal scaffolding is in place; the real work (generating customized skills, rules, docs) is your job, AI agent.
+
+## Your task now
+
+1. Load the skill at [.ai/skills/axis-bootstrap/SKILL.md](.ai/skills/axis-bootstrap/SKILL.md)
+2. Follow [PLANNER.md](.ai/skills/axis-bootstrap/PLANNER.md) in order
+3. **Before any question:** read the README, package.json (or equivalent), and the project file tree
+4. Pause for explicit confirmation between phases
+
+## After Phase 5 completes
+
+Tell the user to run \`axis cleanup\` — it removes the axis-bootstrap skill (it has done its job) and leaves the project self-sufficient.
+
+## Inviolable rules
+
+- Never fabricate: if information is missing, ask
+- Never skip phases: each has an explicit gate
+- Never duplicate content across files: use links and symlinks
+`;
+}
+
+/**
+ * Quick path: interactive scaffold without AI.
+ * Good for new projects where the user already knows the stack.
+ */
+async function quickBootstrap(target, locale) {
+  const T = (k) => t(locale, k);
+
+  const name = await text({
+    message: T('askName'),
+    placeholder: path.basename(target),
+    defaultValue: path.basename(target),
+  });
+  if (isCancel(name)) return cancel(T('aborted'));
+
+  const purpose = await text({
+    message: T('askPurpose'),
+    placeholder: T('askPurposeHint'),
+    validate: (v) => (v && v.length > 5 ? undefined : T('askPurposeShort')),
+  });
+  if (isCancel(purpose)) return cancel(T('aborted'));
+
+  const stack = await text({
+    message: T('askStack'),
+    placeholder: T('askStackHint'),
+    defaultValue: '',
+  });
+  if (isCancel(stack)) return cancel(T('aborted'));
+
+  const ides = await multiselect({
+    message: T('askIDEs'),
+    options: IDES,
+    initialValues: ['claude', 'agents'],
+    required: true,
+  });
+  if (isCancel(ides)) return cancel(T('aborted'));
+
+  const spddSkills = await multiselect({
+    message: T('askSpdd') + ' ' + pc.dim('— ' + T('askSpddHint')),
+    options: SPDD_SKILLS,
+    initialValues: SPDD_SKILLS.map((s) => s.value),
+    required: false,
+  });
+  if (isCancel(spddSkills)) return cancel(T('aborted'));
+
+  const s = spinner();
+  s.start(T('quickScaffolding'));
+
+  ensureDir(path.join(target, '.ai', 'skills'));
+  ensureDir(path.join(target, '.ai', 'rules'));
+  ensureDir(path.join(target, '.ai', 'docs', 'canvases', 'done'));
+
+  const replace = (content) =>
+    content
+      .replace(/{{PROJECT_NAME}}/g, name)
+      .replace(/{{PROJECT_PURPOSE}}/g, purpose)
+      .replace(/{{STACK}}/g, stack || (locale === 'pt' ? '(não-software)' : '(non-software)'));
+
+  write(path.join(target, '.ai', 'INSTRUCTIONS.md'), replace(read(path.join(TEMPLATES, 'INSTRUCTIONS.md'))));
+  write(path.join(target, '.ai', 'CONVENTIONS.md'), replace(read(path.join(TEMPLATES, 'CONVENTIONS.md'))));
+  write(path.join(target, '.ai', 'docs', 'STATE.md'), replace(read(path.join(TEMPLATES, 'STATE.md'))));
+  s.message(T('quickSpecReady'));
+
+  // SPDD skills
+  for (const skill of spddSkills) {
+    const skillDir = path.join(target, '.ai', 'skills', skill);
+    ensureDir(skillDir);
+    const src = path.join(TEMPLATES, 'skills', `${skill}.md`);
+    if (exists(src)) {
+      fs.copyFileSync(src, path.join(skillDir, 'SKILL.md'));
+    }
+  }
+
+  // Harness
+  if (ides.includes('claude')) {
+    ensureDir(path.join(target, '.claude'));
+    write(path.join(target, '.claude', 'settings.json'), read(path.join(TEMPLATES, 'settings.json')));
+  }
+  s.message(T('quickHarnessReady'));
+
+  // setup-ide-links.sh
+  write(path.join(target, 'setup-ide-links.sh'), read(path.join(TEMPLATES, 'setup-ide-links.sh')));
+  fs.chmodSync(path.join(target, 'setup-ide-links.sh'), 0o755);
+  s.message(T('quickInstallerReady'));
+
+  try {
+    execSync('bash setup-ide-links.sh', { cwd: target, stdio: 'pipe' });
+    s.stop(T('quickSymlinksInstalled'));
+  } catch {
+    s.stop(T('quickDoneScaffolding'));
+    log.warn(T('quickRunLink'));
+  }
+
+  const created = [
+    '.ai/INSTRUCTIONS.md',
+    '.ai/CONVENTIONS.md',
+    '.ai/docs/STATE.md',
+    `.ai/skills/ (${spddSkills.length} SPDD)`,
+    'setup-ide-links.sh',
+    ...(ides.includes('claude') ? ['.claude/settings.json'] : []),
+    'AGENTS.md → .ai/INSTRUCTIONS.md',
+    'CLAUDE.md → .ai/INSTRUCTIONS.md',
+  ];
+  note(created.map((c) => pc.green('+ ') + c).join('\n'), T('quickCreated'));
+
+  note(
+    [
+      `${pc.bold('1.')} ${T('quickNext1')}`,
+      `${pc.bold('2.')} ${T('quickNext2')}`,
+      `${pc.bold('3.')} ${T('quickNext3')}`,
+      `${pc.bold('4.')} ${T('quickNext4')}`,
+    ].join('\n'),
+    locale === 'pt' ? 'Próximos passos' : 'Next steps'
+  );
+}

package/src/commands/link.js

@@ -0,0 +1,31 @@
+import { spinner, outro, log } from '@clack/prompts';
+import pc from 'picocolors';
+import path from 'node:path';
+import { execSync } from 'node:child_process';
+import { findTarget, exists, read, write } from '../lib/paths.js';
+import { TEMPLATES } from '../lib/paths.js';
+import fs from 'node:fs';
+
+export async function link(argv) {
+  const target = path.resolve(argv[0] || findTarget());
+  const script = path.join(target, 'setup-ide-links.sh');
+
+  if (!exists(script)) {
+    log.warn('setup-ide-links.sh not found — installing from template.');
+    write(script, read(path.join(TEMPLATES, 'setup-ide-links.sh')));
+    fs.chmodSync(script, 0o755);
+  }
+
+  const s = spinner();
+  s.start('Running setup-ide-links.sh');
+  try {
+    const out = execSync('bash setup-ide-links.sh', { cwd: target }).toString();
+    s.stop('Symlinks installed');
+    if (out.trim()) console.log(pc.dim(out.trim()));
+    outro(pc.green('✓ done'));
+  } catch (e) {
+    s.stop('Failed');
+    log.error(e.message);
+    process.exit(1);
+  }
+}