kairn-cli 1.8.0 → 1.9.0

package/dist/cli.js

@@ -338,7 +338,7 @@ var initCommand = new Command("init").description("Set up Kairn with your API ke
 
 // src/commands/describe.ts
 import { Command as Command2 } from "commander";
-import { input, confirm } from "@inquirer/prompts";
+import { input, confirm, select as select2 } from "@inquirer/prompts";
 import chalk5 from "chalk";
 import ora from "ora";
 
@@ -614,6 +614,19 @@ When generating for Hermes runtime, the same EnvironmentSpec JSON is produced. T
 
 The LLM output format does not change. Adapter-level conversion happens post-compilation.
 
+## Autonomy Levels
+
+The user may specify an autonomy level (1-4). This affects CLAUDE.md content:
+
+- **Level 1 (Guided):** Add a "Workflow" section showing recommended command flow (e.g., spec \u2192 sprint \u2192 plan \u2192 code \u2192 prove \u2192 grill \u2192 commit) and a "When to Use What" reference table.
+- **Level 2 (Assisted):** Level 1 content + mention /project:loop in the workflow section and @pm in the agents section of CLAUDE.md.
+- **Level 3 (Autonomous):** Level 2 content + mention /project:auto and worktree-based PR delivery workflow.
+- **Level 4 (Full Auto):** Level 3 content + add a prominent warning section about autonomous operation.
+
+The autonomy-specific commands, agents, and hooks are injected post-compilation. Focus on tailoring the CLAUDE.md content and workflow guidance for the selected level.
+
+If no autonomy level is specified, assume Level 1 (Guided).
+
 ## Output Schema
 
 Return ONLY valid JSON matching this structure:
@@ -884,7 +897,8 @@ async function compile(intent, onProgress) {
     id: `env_${crypto.randomUUID()}`,
     intent,
     created_at: (/* @__PURE__ */ new Date()).toISOString(),
-    ...parsed
+    ...parsed,
+    autonomy_level: parsed.autonomy_level ?? 1
   };
   validateSpec(spec, onProgress);
   await ensureDirs();
@@ -919,6 +933,290 @@ async function generateClarifications(intent, onProgress) {
 // src/adapter/claude-code.ts
 import fs5 from "fs/promises";
 import path5 from "path";
+
+// src/autonomy.ts
+var AUTONOMY_LABELS = {
+  1: "Guided",
+  2: "Assisted",
+  3: "Autonomous",
+  4: "Full Auto"
+};
+var WELCOME_HOOK = {
+  matcher: "",
+  hooks: [{
+    type: "command",
+    command: "if [ ! -f .claude/.toured ]; then echo '\\n  Welcome to your Kairn environment!\\n  Type /project:tour for a walkthrough, or /project:help for a quick reference.\\n'; fi"
+  }]
+};
+var TOUR_COMMAND = `# Environment Tour
+
+Welcome! Let me show you around this Kairn environment.
+
+## Your Commands
+Read .claude/commands/ and list each one with a one-line description.
+Group them by workflow phase:
+
+  PLAN:    /project:spec, /project:sprint, /project:plan
+  BUILD:   (just start coding \u2014 Claude reads CLAUDE.md automatically)
+  VERIFY:  /project:prove, /project:grill, /project:test
+  SHIP:    /project:commit, /project:review
+  MANAGE:  /project:status, /project:tasks, /project:reset
+
+## Your Agents
+Read .claude/agents/ and explain each one with how to invoke it.
+
+## Your MCP Tools
+!claude mcp list 2>/dev/null || echo "Run /mcp in Claude Code to see active tools"
+
+## Workflow
+For this project, the recommended flow is:
+  spec \u2192 sprint \u2192 plan \u2192 code \u2192 prove \u2192 grill \u2192 commit
+
+## Tips
+- Type / to see all commands
+- Type @ to invoke an agent
+- Paste raw errors \u2014 don't summarize them
+- Use subagents for deep investigation
+- Say "update CLAUDE.md" after any correction
+
+After showing the tour, create .claude/.toured to suppress the welcome message:
+!touch .claude/.toured
+
+Ready to start? Try /project:spec to define your first feature.`;
+function buildQuickstart(spec) {
+  const commands = Object.keys(spec.harness.commands || {});
+  const agents = Object.keys(spec.harness.agents || {});
+  const commandList = commands.map((c) => `- \`/project:${c}\``).join("\n");
+  const agentList = agents.length > 0 ? agents.map((a) => `- \`@${a}\``).join("\n") : "- (none configured)";
+  return `# Quick Start Guide
+
+This environment was generated by Kairn. Here's how to use it.
+
+## First Time
+1. Open terminal in this directory
+2. Run \`claude\`
+3. Type \`/project:tour\` for a guided walkthrough
+
+## Daily Workflow
+1. \`/project:status\` \u2014 see where things stand
+2. \`/project:spec\` \u2014 define what to build (Claude will interview you)
+3. Start coding \u2014 Claude follows CLAUDE.md automatically
+4. \`/project:prove\` \u2014 verify your work
+5. \`/project:commit\` \u2014 ship it
+
+## Commands
+${commandList}
+
+## Agents
+${agentList}
+
+## Need Help?
+Type \`/project:help\` in Claude Code for a quick reference.
+`;
+}
+var LOOP_COMMAND_CODE = `# Development Loop
+
+Run an assisted development cycle for the next feature.
+
+## Phase 1: SPEC
+Review docs/TODO.md and docs/SPRINT.md.
+If no sprint is defined, run /project:spec to interview the user.
+Wait for user approval of the spec.
+
+## Phase 2: PLAN
+Read the approved spec in docs/SPRINT.md.
+Plan the implementation: files to change, tests to write, approach.
+Write plan to docs/DECISIONS.md.
+Wait for user approval of the plan.
+
+## Phase 3: IMPLEMENT
+Follow the plan. Implement the feature.
+Run tests after each change.
+Commit each logical unit: "feat: description"
+
+## Phase 4: VERIFY
+Run /project:prove to verify the implementation.
+If confidence is LOW or MEDIUM, fix issues and re-verify.
+
+## Phase 5: REVIEW
+Run /project:grill for adversarial review.
+Fix any BLOCKERs.
+
+## Phase 6: SHIP
+Run /project:commit.
+Report what was built and what's next from docs/TODO.md.
+
+Then ask: "Continue to next feature?"
+If yes, return to Phase 1.`;
+var LOOP_COMMAND_RESEARCH = `# Research Loop
+
+Run an assisted research cycle.
+
+## Phase 1: QUESTION
+Review docs/TODO.md for the next research question.
+If none, ask the user what to investigate.
+
+## Phase 2: RESEARCH
+Search, extract, and analyze sources.
+Log findings to docs/SOURCES.md and docs/LEARNINGS.md.
+
+## Phase 3: SYNTHESIZE
+Review all findings. Write structured summary to docs/SUMMARY.md.
+Cite all sources.
+
+## Phase 4: REVIEW
+Present the summary. Ask the user for feedback.
+Revise based on feedback.
+
+## Phase 5: NEXT
+Update docs/TODO.md \u2014 mark question as done, identify follow-ups.
+Ask: "Continue to next question?"`;
+var PM_AGENT = `---
+name: pm
+description: Project manager agent. Maintains roadmap, specs features, prioritizes work.
+model: opus
+---
+
+You are a project manager for this codebase.
+
+Your responsibilities:
+1. Maintain docs/TODO.md \u2014 keep it prioritized and current
+2. Write specs to docs/SPRINT.md when asked
+3. Review completed work and suggest what's next
+4. Track decisions in docs/DECISIONS.md
+5. Track learnings in docs/LEARNINGS.md
+
+When invoked:
+- Read all docs/ files to understand current state
+- Read recent git log for what changed
+- Suggest the highest-priority next task
+- If asked to spec something, interview the user (5-8 questions)
+
+You do NOT write code. You plan, spec, and prioritize.`;
+var AUTO_COMMAND = `# Autonomous Development
+
+PM-driven development loop with PR delivery.
+
+## Phase 1: PLAN (@pm)
+Use @pm to:
+- Read docs/TODO.md and docs/SPRINT.md
+- Select the highest-priority unfinished task
+- Write a spec to docs/SPRINT.md
+- Present the spec for approval
+
+Wait for user approval. If approved, proceed.
+
+## Phase 2: BRANCH
+Create an isolated worktree:
+  git worktree add ../project-feat-{name} -b feat/{name}
+All implementation happens in the worktree.
+
+## Phase 3: IMPLEMENT
+In the worktree directory:
+- Follow the spec in docs/SPRINT.md
+- Build, test, commit after each change
+
+## Phase 4: VERIFY
+Run verification:
+- Static analysis (linting, type checks)
+- Run functional tests
+- If NEEDS FIXES: fix and re-verify
+
+## Phase 5: PR
+Create a pull request:
+  gh pr create --title "feat: {name}" --body "{spec + QA report}"
+
+## Phase 6: NEXT
+Report:
+  "PR #{N} ready for review: {link}
+   Next priority from TODO.md: {next task}
+   Continue? (y/n)"
+
+If yes, return to Phase 1 with next task.`;
+var AUTOPILOT_COMMAND = `# Autopilot Mode
+
+Continuous autonomous development. The PM plans, the loop executes,
+PRs are opened automatically. You review when ready.
+
+## Configuration
+- Max features per session: 5 (prevent runaway)
+- Stop on: test failure, build error, or blocked dependency
+- All work in isolated worktrees
+- Every feature = one PR
+
+## The Loop
+Repeat until max features reached or stopped:
+1. @pm selects next priority from docs/TODO.md
+2. Create worktree + branch
+3. Implement the feature
+4. Run verification (build, test, lint)
+5. Open PR via gh
+6. Report status
+7. Move to next feature
+
+## Stop Conditions
+- Max 5 features per autopilot session
+- Any BLOCKER from verification
+- Build failure that can't be resolved in 3 attempts
+- User presses Escape`;
+var AUTOPILOT_WARNING = `
+## Autopilot Mode Active
+This environment is configured for autonomous operation.
+The @pm agent plans features and /project:autopilot executes them.
+All changes are delivered as PRs \u2014 review before merging.
+Stop conditions: max 5 features, test failure, or Escape.`;
+function isResearchProject(spec) {
+  const commands = spec.harness.commands ?? {};
+  return "research" in commands || "summarize" in commands;
+}
+function applyAutonomyLevel(spec) {
+  const level = spec.autonomy_level ?? 1;
+  const commands = spec.harness.commands ?? {};
+  const agents = spec.harness.agents ?? {};
+  const docs = spec.harness.docs ?? {};
+  const settings = spec.harness.settings ?? {};
+  if (level >= 1) {
+    if (!("tour" in commands)) {
+      commands.tour = TOUR_COMMAND;
+    }
+    docs.QUICKSTART = buildQuickstart(spec);
+    const hooks = settings.hooks ?? {};
+    const sessionStart = hooks.SessionStart ?? [];
+    sessionStart.push(WELCOME_HOOK);
+    hooks.SessionStart = sessionStart;
+    settings.hooks = hooks;
+  }
+  if (level >= 2) {
+    if (!("loop" in commands)) {
+      commands.loop = isResearchProject(spec) ? LOOP_COMMAND_RESEARCH : LOOP_COMMAND_CODE;
+    }
+    if (!("pm" in agents)) {
+      agents.pm = PM_AGENT;
+    }
+  }
+  if (level >= 3) {
+    if (!("auto" in commands)) {
+      commands.auto = AUTO_COMMAND;
+    }
+  }
+  if (level >= 4) {
+    if (!("autopilot" in commands)) {
+      commands.autopilot = AUTOPILOT_COMMAND;
+    }
+    if (spec.harness.claude_md && !spec.harness.claude_md.includes("Autopilot Mode")) {
+      spec.harness.claude_md += "\n" + AUTOPILOT_WARNING;
+    }
+  }
+  spec.harness.commands = commands;
+  spec.harness.agents = agents;
+  spec.harness.docs = docs;
+  spec.harness.settings = settings;
+}
+function autonomyLabel(level) {
+  return AUTONOMY_LABELS[level];
+}
+
+// src/adapter/claude-code.ts
 var STATUS_LINE = {
   command: `printf '%s | %s tasks' "$(git branch --show-current 2>/dev/null || echo 'no-git')" "$(grep -c '\\- \\[ \\]' docs/TODO.md 2>/dev/null || echo 0)"`
 };
@@ -954,6 +1252,7 @@ async function writeFile(filePath, content) {
   await fs5.writeFile(filePath, content, "utf-8");
 }
 function buildFileMap(spec, options) {
+  applyAutonomyLevel(spec);
   const files = /* @__PURE__ */ new Map();
   if (spec.harness.claude_md) {
     files.set(".claude/CLAUDE.md", spec.harness.claude_md);
@@ -996,6 +1295,7 @@ function buildFileMap(spec, options) {
   return files;
 }
 async function writeEnvironment(spec, targetDir, options) {
+  applyAutonomyLevel(spec);
   const claudeDir = path5.join(targetDir, ".claude");
   const written = [];
   if (spec.harness.claude_md) {
@@ -1360,6 +1660,23 @@ Clarifications:
 ${clarificationLines}`;
     }
   }
+  let autonomyLevel = 1;
+  if (!options.quick) {
+    console.log(ui.section("Autonomy"));
+    autonomyLevel = await select2({
+      message: "Autonomy level",
+      choices: [
+        { name: "1. Guided \u2014 orientation + commands, you drive", value: 1 },
+        { name: "2. Assisted \u2014 workflow loop, you approve phases", value: 2 },
+        { name: "3. Autonomous \u2014 PM plans, loop executes, you review PRs", value: 3 },
+        { name: "4. Full Auto \u2014 continuous execution (\u26A0 advanced)", value: 4 }
+      ],
+      default: 1
+    });
+    finalIntent += `
+
+Autonomy level: ${autonomyLevel} (${autonomyLabel(autonomyLevel)})`;
+  }
   console.log(ui.section("Compilation"));
   const spinner = ora({ text: "Loading tool registry...", indent: 2 }).start();
   let spec;
@@ -1367,6 +1684,7 @@ ${clarificationLines}`;
     spec = await compile(finalIntent, (msg) => {
       spinner.text = msg;
     });
+    spec.autonomy_level = autonomyLevel;
     spinner.succeed("Environment compiled");
   } catch (err) {
     spinner.fail("Compilation failed");
@@ -1381,6 +1699,7 @@ ${clarificationLines}`;
   console.log("");
   console.log(ui.kv("Name:", spec.name));
   console.log(ui.kv("Description:", spec.description));
+  console.log(ui.kv("Autonomy:", `Level ${spec.autonomy_level} (${autonomyLabel(spec.autonomy_level)})`));
   console.log(ui.kv("Tools:", String(summary.toolCount)));
   console.log(ui.kv("Commands:", String(summary.commandCount)));
   console.log(ui.kv("Rules:", String(summary.ruleCount)));
@@ -2274,7 +2593,7 @@ var doctorCommand = new Command7("doctor").description(
 // src/commands/registry.ts
 import { Command as Command8 } from "commander";
 import chalk11 from "chalk";
-import { input as input2, select as select2 } from "@inquirer/prompts";
+import { input as input2, select as select3 } from "@inquirer/prompts";
 var listCommand2 = new Command8("list").description("List tools in the registry").option("--category <cat>", "Filter by category").option("--user-only", "Show only user-defined tools").action(async (options) => {
   printCompactBanner();
   let all;
@@ -2344,7 +2663,7 @@ var addCommand = new Command8("add").description("Add a tool to the user registr
     });
     const name = await input2({ message: "Display name" });
     const description = await input2({ message: "Description" });
-    const category = await select2({
+    const category = await select3({
       message: "Category",
       choices: [
         { value: "universal" },
@@ -2358,7 +2677,7 @@ var addCommand = new Command8("add").description("Add a tool to the user registr
         { value: "sandbox" }
       ]
     });
-    const tier = await select2({
+    const tier = await select3({
       message: "Tier",
       choices: [
         { name: "1 \u2014 Universal", value: 1 },
@@ -2366,7 +2685,7 @@ var addCommand = new Command8("add").description("Add a tool to the user registr
         { name: "3 \u2014 Specialized", value: 3 }
       ]
     });
-    const type = await select2({
+    const type = await select3({
       message: "Type",
       choices: [
         { value: "mcp_server" },
@@ -2374,7 +2693,7 @@ var addCommand = new Command8("add").description("Add a tool to the user registr
         { value: "hook" }
       ]
     });
-    const auth = await select2({
+    const auth = await select3({
       message: "Auth",
       choices: [
         { value: "none" },
@@ -2390,7 +2709,7 @@ var addCommand = new Command8("add").description("Add a tool to the user registr
         const varName = await input2({ message: "Env var name" });
         const varDesc = await input2({ message: "Env var description" });
         env_vars.push({ name: varName, description: varDesc });
-        const another = await select2({
+        const another = await select3({
           message: "Add another env var?",
           choices: [
             { name: "No", value: false },
@@ -2654,7 +2973,7 @@ var keysCommand = new Command10("keys").description("Add or update API keys for
 var program = new Command11();
 program.name("kairn").description(
   "Compile natural language intent into optimized Claude Code environments"
-).version("1.8.0").option("--no-color", "Disable colored output");
+).version("1.9.0").option("--no-color", "Disable colored output");
 program.addCommand(initCommand);
 program.addCommand(describeCommand);
 program.addCommand(optimizeCommand);