kairn-cli 1.12.0 → 1.13.0

package/dist/cli.js

@@ -706,6 +706,16 @@ Use subagents for deep investigation to keep main context clean.
 - Do not create abstractions for one-time operations
 - Complete the task fully \u2014 don't gold-plate, but don't leave it half-done
 - Prefer editing existing files over creating new ones
+
+## First Turn Protocol
+
+At the start of every session, before doing ANY work:
+1. Run \`pwd && ls -la && git status --short\` to orient yourself
+2. Check relevant runtimes (e.g. \`node --version\`, \`python3 --version\` \u2014 pick what fits this project)
+3. Read any task-tracking files (docs/SPRINT.md, docs/DECISIONS.md)
+4. Summarize what you see in 2-3 lines, then proceed
+
+This saves 2-5 exploratory turns. Never ask "what files are here?" \u2014 look first.
 \`\`\`
 
 Do not add generic filler. Every line must be specific to the user's workflow.
@@ -727,6 +737,7 @@ Do not add generic filler. Every line must be specific to the user's workflow.
 13. A "Debugging" section in CLAUDE.md (2 lines: paste raw errors, use subagents)
 14. A "Git Workflow" section in CLAUDE.md (3 rules: small commits, conventional format, <200 lines PR)
 15. "Engineering Standards", "Tool Usage Policy", and "Code Philosophy" sections in CLAUDE.md
+16. A "First Turn Protocol" section in CLAUDE.md (orient before working: pwd, ls, git status, check relevant runtimes, read task files)
 
 ## Shell-Integrated Commands
 
@@ -1002,6 +1013,16 @@ Use subagents for deep investigation to keep main context clean.
 - Do not create abstractions for one-time operations
 - Complete the task fully \u2014 don't gold-plate, but don't leave it half-done
 - Prefer editing existing files over creating new ones
+
+## First Turn Protocol
+
+At the start of every session, before doing ANY work:
+1. Run \`pwd && ls -la && git status --short\` to orient yourself
+2. Check relevant runtimes (e.g. \`node --version\`, \`python3 --version\` \u2014 pick what fits this project)
+3. Read any task-tracking files (docs/SPRINT.md, docs/DECISIONS.md)
+4. Summarize what you see in 2-3 lines, then proceed
+
+This saves 2-5 exploratory turns. Never ask "what files are here?" \u2014 look first.
 \`\`\`
 
 Do not add generic filler. Every line must be specific to the user's workflow.
@@ -1023,6 +1044,7 @@ Do not add generic filler. Every line must be specific to the user's workflow.
 13. A "Debugging" section in CLAUDE.md (2 lines: paste raw errors, use subagents)
 14. A "Git Workflow" section in CLAUDE.md (3 rules: small commits, conventional format, <200 lines PR)
 15. "Engineering Standards", "Tool Usage Policy", and "Code Philosophy" sections in CLAUDE.md
+16. A "First Turn Protocol" section in CLAUDE.md (orient before working: pwd, ls, git status, check relevant runtimes, read task files)
 
 ## Tool Selection Rules
 
@@ -1577,6 +1599,61 @@ ${agentList}
 Type \`/project:help\` in Claude Code for a quick reference.
 `;
 }
+var BOOTSTRAP_COMMAND = `# Environment Snapshot
+
+Run this command at the start of any session to gather runtime context.
+This saves 2-5 exploratory turns.
+
+1. Run the following compound command and read the output:
+   \`\`\`bash
+   echo '=== WORKING DIRECTORY ===' && pwd && \\
+   echo '=== PROJECT FILES ===' && ls -la && \\
+   echo '=== GIT STATUS ===' && (git status --short 2>/dev/null || echo 'not a git repo') && \\
+   echo '=== LANGUAGES ===' && \\
+   (node --version 2>&1 || true) && \\
+   (python3 --version 2>&1 || true) && \\
+   (go version 2>&1 || true) && \\
+   (rustc --version 2>&1 || true) && \\
+   echo '=== PACKAGE MANAGERS ===' && \\
+   (npm --version 2>&1 && echo "npm $(npm --version 2>&1)" || true) && \\
+   (pip3 --version 2>&1 || true) && \\
+   (cargo --version 2>&1 || true) && \\
+   echo '=== ENVIRONMENT ===' && \\
+   (cat .env 2>/dev/null | sed 's/=.*/=***/' || echo 'no .env file')
+   \`\`\`
+
+2. Summarize the environment in 3-4 lines:
+   - Runtime: [languages + versions found]
+   - Project: [framework, key deps, file count]
+   - State: [git branch, clean/dirty, .env present]
+
+3. Keep this summary in context for the rest of the session.`;
+function buildBootstrapHookCommand(spec) {
+  const checks = [
+    "echo '--- Environment Snapshot ---'",
+    "pwd",
+    "ls -la --color=never | head -20",
+    "echo '---'",
+    "git status --short 2>/dev/null || true",
+    "echo '---'"
+  ];
+  const md = (spec.harness.claude_md ?? "").toLowerCase();
+  if (md.includes("node") || md.includes("typescript") || md.includes("javascript") || md.includes("react") || md.includes("next")) {
+    checks.push("node --version 2>&1 || true");
+    checks.push("cat package.json 2>/dev/null | head -5 || true");
+  }
+  if (md.includes("python") || md.includes("django") || md.includes("flask") || md.includes("fastapi")) {
+    checks.push("python3 --version 2>&1 || true");
+  }
+  if (md.includes("rust") || md.includes("cargo")) {
+    checks.push("rustc --version 2>&1 || true");
+  }
+  if (md.includes("go ") || md.includes("golang")) {
+    checks.push("go version 2>&1 || true");
+  }
+  checks.push("cat .env 2>/dev/null | sed 's/=.*/=***/' || true");
+  return checks.join(" && ");
+}
 var LOOP_COMMAND_CODE = `# Development Loop
 
 Run an assisted development cycle for the next feature.
@@ -1750,6 +1827,9 @@ function applyAutonomyLevel(spec) {
     settings.hooks = hooks;
   }
   if (level >= 2) {
+    if (!("bootstrap" in commands)) {
+      commands.bootstrap = BOOTSTRAP_COMMAND;
+    }
     if (!("loop" in commands)) {
       commands.loop = isResearchProject(spec) ? LOOP_COMMAND_RESEARCH : LOOP_COMMAND_CODE;
     }
@@ -1761,6 +1841,18 @@ function applyAutonomyLevel(spec) {
     if (!("auto" in commands)) {
       commands.auto = AUTO_COMMAND;
     }
+    const hooks = settings.hooks ?? {};
+    const sessionStart = hooks.SessionStart ?? [];
+    const bootstrapHook = {
+      matcher: "",
+      hooks: [{
+        type: "command",
+        command: buildBootstrapHookCommand(spec)
+      }]
+    };
+    sessionStart.push(bootstrapHook);
+    hooks.SessionStart = sessionStart;
+    settings.hooks = hooks;
   }
   if (level >= 4) {
     if (!("autopilot" in commands)) {