@justethales/cockpit 0.1.0

package/dist/new.js

@@ -0,0 +1,98 @@
+/**
+ * `cockpit new prompt|log --slug <kebab-id>` — copy a template, interpolate.
+ */
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { exit } from 'node:process';
+import { c, todayISO } from './shared.js';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+// Sub-templates (session-prompt, session-log, audit-brief) live at
+// templates/templates/ — the same path they end up at inside the user's
+// scaffolded cockpit/. Init copies the whole tree ; `new` reads from the
+// nested sub-dir only.
+const TEMPLATES = join(__dirname, '..', 'templates', 'templates');
+function nextLogIndex(dir) {
+    if (!existsSync(dir))
+        return '001';
+    const today = todayISO();
+    const yymmdd = today.slice(2).replace(/-/g, '-'); // YY-MM-DD
+    const todayLogs = readdirSync(dir).filter((f) => f.startsWith(yymmdd) && f.endsWith('.md'));
+    const maxNNN = todayLogs.reduce((max, f) => {
+        const m = f.match(/^\d{2}-\d{2}-\d{2}-(\d{3})/);
+        if (!m)
+            return max;
+        return Math.max(max, parseInt(m[1], 10));
+    }, 0);
+    return String(maxNNN + 1).padStart(3, '0');
+}
+function getArg(args, flag) {
+    const i = args.indexOf(flag);
+    if (i === -1)
+        return undefined;
+    return args[i + 1];
+}
+export function runNew(args) {
+    const [kind, ...rest] = args;
+    if (kind !== 'prompt' && kind !== 'log') {
+        console.error(c.red(`unknown new kind: ${kind}`));
+        console.error(c.gray('  → use `cockpit new prompt --slug X` or `cockpit new log --slug X`'));
+        exit(1);
+    }
+    const slug = getArg(rest, '--slug');
+    if (!slug) {
+        console.error(c.red('--slug <kebab-id> is required'));
+        exit(1);
+    }
+    if (!/^[a-z0-9-]+$/.test(slug)) {
+        console.error(c.red(`slug must be kebab-case (a-z, 0-9, -): got '${slug}'`));
+        exit(1);
+    }
+    const root = process.cwd();
+    const today = todayISO();
+    if (kind === 'prompt') {
+        const dir = join(root, 'docs', 'plan', 'sessions');
+        mkdirSync(dir, { recursive: true });
+        const filename = `${slug.toUpperCase().replace(/-/g, '-')}.md`;
+        const dest = join(dir, filename);
+        if (existsSync(dest)) {
+            console.error(c.red(`already exists: ${relative(root, dest)}`));
+            exit(1);
+        }
+        const src = join(TEMPLATES, 'session-prompt.md');
+        const raw = readFileSync(src, 'utf8');
+        const out = raw
+            .split('YYYY-MM-DD').join(today)
+            .split('<id>-<slug>').join(slug);
+        writeFileSync(dest, out);
+        console.log(`${c.green('write')}   ${relative(root, dest)}`);
+        console.log('');
+        console.log(c.gray('next: edit the prompt to fill the <placeholders>'));
+        console.log(c.gray('      then update cockpit/state.json next_prompt to point at this file'));
+        return;
+    }
+    if (kind === 'log') {
+        const dir = join(root, 'session-logs');
+        mkdirSync(dir, { recursive: true });
+        const yymmdd = today.slice(2);
+        const nnn = nextLogIndex(dir);
+        const filename = `${yymmdd}-${nnn}-${slug}.md`;
+        const dest = join(dir, filename);
+        if (existsSync(dest)) {
+            console.error(c.red(`already exists: ${relative(root, dest)}`));
+            exit(1);
+        }
+        const src = join(TEMPLATES, 'session-log.md');
+        const raw = readFileSync(src, 'utf8');
+        const out = raw
+            .split('YY-MM-DD-NNN').join(`${yymmdd}-${nnn}`)
+            .split('YY-MM-DD').join(yymmdd);
+        writeFileSync(dest, out);
+        console.log(`${c.green('write')}   ${relative(root, dest)}`);
+        console.log('');
+        console.log(c.gray(`session id: ${yymmdd}-${nnn}-${slug}`));
+        console.log(c.gray('next: edit the log, then update cockpit/state.json last_session_id'));
+        return;
+    }
+}

package/dist/shared.js

@@ -0,0 +1,63 @@
+/**
+ * Shared helpers — ANSI colors, git, frontmatter parsing.
+ */
+import { execSync } from 'node:child_process';
+import { readFileSync, existsSync } from 'node:fs';
+import { stdout } from 'node:process';
+import { parse as parseYaml } from 'yaml';
+export const COLOR_ON = stdout.isTTY && !process.env.NO_COLOR;
+export const c = {
+    red: (s) => (COLOR_ON ? `\x1b[31m${s}\x1b[0m` : s),
+    green: (s) => (COLOR_ON ? `\x1b[32m${s}\x1b[0m` : s),
+    yellow: (s) => (COLOR_ON ? `\x1b[33m${s}\x1b[0m` : s),
+    cyan: (s) => (COLOR_ON ? `\x1b[36m${s}\x1b[0m` : s),
+    gray: (s) => (COLOR_ON ? `\x1b[90m${s}\x1b[0m` : s),
+    bold: (s) => (COLOR_ON ? `\x1b[1m${s}\x1b[0m` : s)
+};
+export function setColor(on) {
+    // Used by --plain to disable colors mid-run.
+    Object.keys(c).forEach((k) => {
+        if (!on)
+            c[k] = (s) => s;
+    });
+}
+export function git(cmd, cwd = process.cwd()) {
+    try {
+        return execSync(`git ${cmd}`, {
+            cwd,
+            stdio: ['ignore', 'pipe', 'ignore']
+        })
+            .toString()
+            .trim();
+    }
+    catch {
+        return '';
+    }
+}
+export function readFrontmatter(filePath) {
+    if (!existsSync(filePath))
+        return null;
+    const raw = readFileSync(filePath, 'utf8');
+    const m = raw.match(/^---\n([\s\S]*?)\n---/);
+    if (!m)
+        return null;
+    try {
+        return parseYaml(m[1]);
+    }
+    catch {
+        return null;
+    }
+}
+export function loadState(path) {
+    if (!existsSync(path))
+        return null;
+    try {
+        return JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+export function todayISO() {
+    return new Date().toISOString().slice(0, 10);
+}

package/dist/status.js

@@ -0,0 +1,127 @@
+/**
+ * `cockpit status` — read-only one-screen snapshot.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { c, git, loadState, readFrontmatter, setColor } from './shared.js';
+const ROOT = process.cwd();
+const STATE = join(ROOT, 'cockpit', 'state.json');
+const NOW = join(ROOT, 'cockpit', 'now.md');
+const ROADMAP = join(ROOT, 'cockpit', 'roadmap.md');
+function section(label, body) {
+    console.log('');
+    console.log(c.bold(label));
+    console.log(c.gray('─'.repeat(Math.max(label.length, 40))));
+    console.log(body);
+}
+export function runStatus(args) {
+    if (args.includes('--plain'))
+        setColor(false);
+    if (!existsSync(STATE)) {
+        console.error(c.red('no cockpit/state.json found'));
+        console.error(c.gray('  → run `npx cockpit init` first'));
+        process.exit(1);
+    }
+    const state = loadState(STATE);
+    if (!state) {
+        console.error(c.red('cockpit/state.json is not valid JSON'));
+        process.exit(1);
+    }
+    const head = git('rev-parse --short HEAD') || '(no git)';
+    const branch = git('rev-parse --abbrev-ref HEAD') || '(no git)';
+    const dirty = git('status --short');
+    const ahead = git('rev-list --count @{u}..HEAD').trim();
+    const log10 = git('log --oneline -10');
+    let pkgName = 'cockpit-managed-project';
+    let pkgVersion = '';
+    const pkgPath = join(ROOT, 'package.json');
+    if (existsSync(pkgPath)) {
+        try {
+            const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+            pkgName = pkg.name ?? pkgName;
+            pkgVersion = pkg.version ? `@${pkg.version}` : '';
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    console.log('');
+    console.log(c.bold(`${pkgName}${pkgVersion}`) +
+        ` · branch ${c.cyan(branch)} · HEAD ${c.cyan(head)}`);
+    if (dirty) {
+        const lines = dirty.split('\n').length;
+        console.log(c.yellow(`  ⚠ working tree has ${lines} uncommitted file${lines > 1 ? 's' : ''}`));
+    }
+    if (ahead && ahead !== '0') {
+        console.log(c.yellow(`  ⚠ ${ahead} commit${ahead === '1' ? '' : 's'} ahead of upstream`));
+    }
+    const summary = [
+        `  current_phase    ${c.cyan(String(state.current_phase ?? '-'))}`,
+        `  next_phase       ${c.cyan(String(state.next_phase ?? '-'))}`,
+        `  next_prompt      ${c.cyan(String(state.next_prompt ?? '-'))}`,
+        `  last_session_id  ${c.gray(String(state.last_session_id ?? '-'))}`,
+        `  last_commit      ${c.gray(String(state.last_commit ?? '-'))}`
+    ].join('\n');
+    section('STATE', summary);
+    const nextPromptPath = state.next_prompt ? join(ROOT, String(state.next_prompt)) : null;
+    if (nextPromptPath && existsSync(nextPromptPath)) {
+        const fm = readFrontmatter(nextPromptPath);
+        const status = fm ? String(fm.status ?? '?') : '(no frontmatter)';
+        const sessionLog = fm ? String(fm.session_log ?? 'pending') : '?';
+        const statusColor = status === 'shipped'
+            ? c.red(status)
+            : status === 'queued'
+                ? c.green(status)
+                : c.yellow(status);
+        const body = [
+            `  path     ${c.cyan(String(state.next_prompt))}`,
+            `  status   ${statusColor}`,
+            `  log      ${c.gray(sessionLog)}`
+        ].join('\n');
+        section('NEXT PROMPT', body);
+        const raw = readFileSync(nextPromptPath, 'utf8');
+        const afterFm = raw.replace(/^---\n[\s\S]*?\n---\n/, '');
+        const lines = afterFm.split('\n').slice(0, 8);
+        for (const l of lines) {
+            if (!l.trim())
+                continue;
+            console.log(c.gray('  ' + l.slice(0, 100)));
+        }
+    }
+    else if (state.next_prompt) {
+        section('NEXT PROMPT', c.red(`  ✗ ${state.next_prompt} does not exist on disk`));
+    }
+    if (log10) {
+        section('RECENT COMMITS', log10
+            .split('\n')
+            .map((l) => `  ${l}`)
+            .join('\n'));
+    }
+    if (existsSync(NOW)) {
+        const raw = readFileSync(NOW, 'utf8');
+        const m = raw.match(/## Current focus[^\n]*\n\n([\s\S]*?)(?:\n---|\n##)/);
+        if (m) {
+            const focus = m[1].trim().split('\n').slice(0, 4).join('\n');
+            section('CURRENT FOCUS', focus
+                .split('\n')
+                .map((l) => `  ${l}`)
+                .join('\n'));
+        }
+    }
+    if (existsSync(ROADMAP)) {
+        const raw = readFileSync(ROADMAP, 'utf8');
+        const m = raw.match(/## Now — Next 3[^\n]*\n([\s\S]*?)(?:\n---|\n## )/);
+        if (m) {
+            const block = m[1]
+                .split('\n')
+                .filter((l) => l.trim().length > 0)
+                .slice(0, 8)
+                .map((l) => '  ' + l.slice(0, 140))
+                .join('\n');
+            section('NEXT 3', block);
+        }
+    }
+    console.log('');
+    console.log(c.gray('run `npx cockpit check` to validate, `npx cockpit status` to refresh'));
+    console.log('');
+}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@justethales/cockpit",
+  "version": "0.1.0",
+  "description": "A 200-line discipline for AI-coding sessions: machine-verifiable session state + drift validator + canonical templates. Works with Claude Code, Cursor, or anything that drives a repo with a session loop.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Thales (Juste Gnimavo) — ZeroSuite",
+  "homepage": "https://github.com/justethales/cockpit-skill",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/justethales/cockpit-skill.git"
+  },
+  "bugs": {
+    "url": "https://github.com/justethales/cockpit-skill/issues"
+  },
+  "keywords": [
+    "ai",
+    "claude",
+    "claude-code",
+    "cursor",
+    "workflow",
+    "developer-experience",
+    "session",
+    "cockpit"
+  ],
+  "main": "dist/cli.js",
+  "bin": {
+    "cockpit": "dist/cli.js"
+  },
+  "scripts": {
+    "cockpit": "tsx src/cli.ts",
+    "build": "tsc -p tsconfig.build.json && chmod +x dist/cli.js",
+    "smoke": "tsx src/cli.ts --version",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "yaml": "^2.7.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.4",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.3"
+  },
+  "files": [
+    "dist",
+    "templates",
+    "skills",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  }
+}

package/skills/cockpit/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: cockpit
+description: |
+  Quick KPI lookups for any cockpit-managed project. Answers "where are we?",
+  "what's next?", "did the last session close cleanly?". Reads the project's
+  cockpit/ directory if present, falls back to git + package.json + README.
+  Subcommands: where, roadmap, changelog, version, ship, stack, status, check, or
+  no args = full snapshot.
+---
+
+# /cockpit — KPI lookups
+
+You are a read-only status reporter. The user invoked `/cockpit` to get the "where am I" / "what's next" snapshot WITHOUT making you re-read the codebase. Do NOT explore beyond what the subcommand asks for.
+
+## Pre-flight (run once, in parallel)
+
+```bash
+pwd
+test -d cockpit && echo "cockpit:yes" || echo "cockpit:no"
+git rev-parse --short HEAD 2>/dev/null
+git rev-parse --abbrev-ref HEAD 2>/dev/null
+git status --short
+git log --oneline -10
+test -f package.json && jq -r '.name + "@" + (.version // "unversioned")' package.json 2>/dev/null
+```
+
+## Path A — `cockpit/` directory present
+
+Prefer the CLI : `npx cockpit status` (or `pnpm cockpit:status` / `bun cockpit:status` if the project has wired it). The CLI output is the canonical snapshot — surface it verbatim, don't paraphrase.
+
+If the CLI fails or isn't installed, fall back to reading the cockpit files directly :
+
+- `cat cockpit/state.json | jq` — machine state.
+- `cockpit/now.md` — current focus, next-actions-by-budget, don't-get-distracted.
+- `cockpit/roadmap.md` Next-3 — what ships next.
+
+## Path B — no cockpit/ directory
+
+Degraded mode :
+- `git log --oneline -10` — recent activity.
+- `cat README.md | head -30` — what the project is.
+- Suggest `npx cockpit init` to scaffold.
+
+## Subcommands
+
+| Invocation | Returns |
+|---|---|
+| `/cockpit` | Full snapshot (state + next prompt preview + last 10 commits + current focus + Next-3). Same as `npx cockpit status`. |
+| `/cockpit where` | `cockpit/now.md` — current focus + 15-min next + don't-do list. |
+| `/cockpit roadmap` | `cockpit/roadmap.md` Next-3 + in-flight + blocked. |
+| `/cockpit changelog` | `git log --oneline -20` + `git log --since='7 days ago' --oneline` count. |
+| `/cockpit version` | `pkg@version` + commit SHA + branch + unpushed count + dirty count + state.json migration count + current_phase. |
+| `/cockpit ship` | Ship-readiness card : working tree, unpushed, blockers (from roadmap), in-flight, verdict line ("safe to push" / "FAIL : <reason>"). |
+| `/cockpit stack` | `package.json` runtime deps + scripts + 1-line architecture from `cockpit/architecture.md` if present. |
+| `/cockpit status` | Synonym for `/cockpit` (no args). |
+| `/cockpit check` | Run `npx cockpit check` and surface the result. |
+
+## Rules
+
+- **Read-only.** This skill never edits files. If the user wants to edit, suggest the appropriate tool.
+- **Surface verbatim.** Don't paraphrase the CLI output. The CLI is the source of truth.
+- **No explore.** Don't grep, don't search the codebase. The cockpit gives the answer ; trust it.
+- **No re-run.** If the user just ran `/cockpit` 30 seconds ago, the state hasn't meaningfully changed. Don't burn tokens.
+- **Honor `pwd`.** Never reach for a sibling project's cockpit.
+
+## What `/cockpit` is NOT
+
+- Not `/next` — cockpit reports, next acts.
+- Not an editor — never bumps state.json or rewrites now.md.
+- Not a planner — surfaces the existing plan, doesn't propose new ones.

package/skills/next/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: next
+description: |
+  Start the next implementation session. Reads cockpit/state.json for the
+  next_prompt field, opens the named prompt file, then begins executing it
+  as the canonical instruction for the session. Works in any project with a
+  cockpit/ directory. Falls back to roadmap.md Next-3 when no next_prompt is
+  set, and to git log + open questions when no cockpit exists at all. Removes
+  the friction of having to paste the previous session's end message or
+  re-orient the agent on session start.
+---
+
+# /next — Start the next implementation session
+
+You are an **execution agent**, not a reporter. The user typed `/next` because they want work to begin. Your job is to (1) discover what the next session is, (2) load its full context, (3) start executing it. Do NOT stop and ask "shall I proceed" — proceed.
+
+This is the opposite of `/cockpit` in posture : cockpit reports, next acts.
+
+---
+
+## Pre-flight (run once, in parallel)
+
+```bash
+pwd
+test -d cockpit && echo "cockpit:yes" || echo "cockpit:no"
+git rev-parse --short HEAD 2>/dev/null
+git rev-parse --abbrev-ref HEAD 2>/dev/null
+git status --short
+git log --oneline -5
+test -f package.json && jq -r '.name + "@" + (.version // "unversioned")' package.json 2>/dev/null
+```
+
+Surface the project name + commit + branch at the top of your reply (one line).
+
+---
+
+## Validate the cockpit first
+
+```bash
+npx cockpit check --quiet 2>&1 | tail -5
+echo "exit:$?"
+```
+
+If `cockpit check` returns FAIL : **STOP.** The previous session didn't close cleanly. Surface the FAIL findings to the user and ask whether to (a) fix the drift inline first, (b) re-execute the prompt the cockpit points at, (c) start something else. Don't paper over drift by executing on top of it — that compounds the problem.
+
+If 0 FAIL : proceed.
+
+---
+
+## Decide what to execute
+
+### Path A — cockpit present and `next_prompt` set (the happy path)
+
+```bash
+test -f cockpit/state.json && jq -r '.next_prompt // "none"' cockpit/state.json
+test -f cockpit/state.json && jq -r '.current_phase, .next_phase' cockpit/state.json
+```
+
+When `next_prompt` is a real path (not `"none"`, not empty, not null) :
+
+```bash
+cat <next_prompt path>
+```
+
+The file is the canonical instruction for this session. Read it fully.
+
+**Validate before executing :**
+- Frontmatter `status:` should be `queued` (not `shipped`). The `cockpit check` ran above catches this, but verify by eye on the prompt.
+- Frontmatter `next_after:` should reference the most recent shipped work.
+- The prompt's `## CONTEXT` section should mention the most recent commit hash.
+
+**When validation passes :** announce in one sentence what you're about to do. Then **begin the work** — Build step 1, then 2, then 3. Do NOT pause to re-confirm scope ; the prompt IS the scope.
+
+### Path B — cockpit present but `next_prompt` is `none` / missing
+
+```bash
+test -f cockpit/roadmap.md && sed -n '/## Now — Next 3/,/^---$/p' cockpit/roadmap.md
+ls docs/plan/sessions/*.md 2>/dev/null | head -20
+grep -l '^status: queued' docs/plan/sessions/*.md 2>/dev/null
+```
+
+When the roadmap Next-1 names a prompt file that exists and has `status: queued`, treat that as `next_prompt` and continue with Path A.
+
+When no clear next-prompt can be derived, surface the Next-3 from `roadmap.md` and ask the user which to start. Don't guess.
+
+### Path C — no cockpit at all
+
+```bash
+test -f README.md && head -20 README.md
+test -d docs/plan/sessions && ls docs/plan/sessions/*.md 2>/dev/null
+git log --oneline -10
+```
+
+Report what you see + suggest `npx cockpit init`. The skill is degraded but useful — at least it does the inspection legwork.
+
+---
+
+## During execution
+
+- **Honor the prompt's `## DO NOT` section literally.** Scope creep guard.
+- **Honor the prompt's `## AT END OF SESSION` section literally.** In particular, the steps about session log + cockpit update + next-session prompt drafting + `cockpit check` + commit + push are non-negotiable.
+- **If the prompt's MUST list is larger than the session can realistically cover, surface the call out loud before starting.** Quote the prompt back and propose the cut.
+- **If the prompt assumes a file / env var / external state that doesn't exist, stop immediately.** Surface the missing precondition.
+
+---
+
+## When the prompt finishes
+
+The prompt's `## AT END OF SESSION` already covers commit + push + cockpit bump + next-session prompt drafting + `cockpit check`. Don't add extra ceremony.
+
+If the prompt is silent on the next-session prompt draft, draft it anyway via `npx cockpit new prompt --slug <next-slug>`.
+
+---
+
+## Rules
+
+- **Never paste a long copy of `cockpit/now.md` or the prompt body into your reply.** The user reads files themselves ; your job is to act.
+- **Never report "I've read the cockpit, what would you like me to do?"** That's the friction this skill removes. If the cockpit names a next-prompt, execute it.
+- **Never re-run `/cockpit` from inside `/next`.** Duplicates work.
+- **Always honor `pwd`.** Never reach for a sibling project's cockpit.
+- **Never modify `cockpit/state.json` until the session's work is shipping.** The skill is a starting gun, not a state-bump tool.
+
+---
+
+## Failure modes
+
+- **`pwd` is not in a git repo** : print "_not in a git repository ; `/next` needs a project root_" and stop.
+- **No `cockpit/`, no `docs/plan/sessions/`, no obvious next work** : print "_no cockpit, no session prompts ; tell me what to start_" and suggest `npx cockpit init`.
+- **`next_prompt` points at a missing file** : the cockpit-check above catches this. Surface + ask whether to draft the missing prompt or fix state.json.
+- **`next_prompt` points at a `shipped` prompt** : cockpit-check catches this. Surface + ask whether to update state.json to the real next slice OR re-execute the shipped prompt.
+- **The prompt's MUST is obviously infeasible in one session** : propose the cut to the user before starting.
+
+---
+
+## What `/next` is NOT
+
+- It is **not** `/cockpit`. Cockpit reports, next acts.
+- It is **not** a planner. The prompt file IS the plan.
+- It is **not** interactive. It begins work ; the user interrupts if redirection is needed.

package/templates/README.md

@@ -0,0 +1,107 @@
+# Cockpit
+
+> **Scaffolded** : {{TODAY}} via `npx cockpit init`.
+> **Source** : `@thales/cockpit` — https://github.com/justethales/cockpit-skill
+> **License** : MIT.
+
+This directory is the **single source of short-term truth** for this project's AI-driven engineering sessions. It costs ~3-5 k tokens to load, far less than re-reading the codebase.
+
+---
+
+## What this is
+
+Six state files + three CLI tools + three canonical templates + an explicit session-start / session-end protocol so any fresh agent session can answer "where am I?" in one screen, leave the cockpit in a coherent state on close, and have a machine-verifiable gate to catch drift before push.
+
+### State files
+
+- [now.md](now.md) — current focus (1 sentence), next action by time budget, don't-get-distracted list, active constraints. **Update at every session close.**
+- [roadmap.md](roadmap.md) — Next 3 to ship, in-flight, blocked, queued, shipped-this-week, phase scoreboard.
+- [state.json](state.json) — machine-readable single-line state. The validator (`npx cockpit check`) reads it.
+- [templates/](templates/) — canonical scaffolds for the three artifacts every session produces.
+
+### CLI tools
+
+| Command | What it does | When to run |
+|---|---|---|
+| `npx cockpit status` | Read-only one-screen snapshot. | Session start. |
+| `npx cockpit check` | Validator. Exits 1 on drift. | **Mandatory before `git push`** when the cockpit was bumped. |
+| `npx cockpit new prompt --slug X` | Scaffold a session prompt from template. | Session close (draft next session's prompt). |
+| `npx cockpit new log --slug X` | Scaffold a session log from template. | Session close. |
+
+### Templates
+
+| Path | Use case |
+|---|---|
+| [templates/session-prompt.md](templates/session-prompt.md) | The skeleton for `docs/plan/sessions/<id>-<slug>.md`. |
+| [templates/session-log.md](templates/session-log.md) | The skeleton for `session-logs/YY-MM-DD-NNN-<slug>.md`. |
+| [templates/audit-brief.md](templates/audit-brief.md) | The Explore sub-agent brief for post-implementation audits. |
+
+---
+
+## Session-start protocol
+
+```bash
+npx cockpit status
+```
+
+That covers the snapshot. Then `cat <next_prompt path>` and begin executing. Don't pause to confirm scope ; the prompt IS the scope.
+
+If `npx cockpit check` returns FAIL at session start, **STOP and reconcile.** A failed cockpit means the previous session didn't close cleanly.
+
+---
+
+## Session-close protocol
+
+In order. The order matters because the validator depends on prior steps :
+
+1. **Write the session log** — `npx cockpit new log --slug X` then fill in.
+2. **Flip this session's prompt frontmatter** — `status: queued → shipped`, `session_id:` filled, `session_log:` pointing at step 1's file.
+3. **Bump parent prompt's `progress:` block** if this was a sub-slice.
+4. **Draft the next session's prompt** — `npx cockpit new prompt --slug Y` then fill in.
+5. **`cockpit/now.md`** — overwrite the three blocks. Update the "Updated" line.
+6. **`cockpit/roadmap.md`** — move shipped item to "Shipped this week" ; promote queued ; update Phase scoreboard.
+7. **`cockpit/state.json`** — bump `last_session_id`, `last_commit`, `current_phase`, `next_phase`, `next_prompt`, append to `phases_shipped[]`, append to `migrations_applied[]` if a migration ran.
+8. **`npx cockpit check`** — must exit 0 (0 FAIL).
+9. **`git add` + `git commit` + `git push`**.
+
+---
+
+## What the validator catches
+
+Real drift, in order of severity :
+
+1. **`state.json.next_prompt` points at a missing file.**
+2. **`state.json.next_prompt` points at a `shipped` prompt.** Cockpit was never bumped after the previous session.
+3. **`state.json.last_session_id` does not map to a session-log file.**
+4. **`state.json.last_commit` not found in `git log`.**
+5. **`state.json.phases_shipped[]` has duplicates.**
+6. **`state.json.migrations_applied[]` does not match `<migrations_dir>/*.sql`.**
+7. **A session prompt has `status: shipped` but no `session_log:` pointer.**
+8. **Uncommitted changes in `cockpit/` / `docs/plan/sessions/` / `session-logs/`.**
+
+Each failure prints a `→ fix` hint so the next session can resolve without re-reading this README.
+
+---
+
+## When NOT to use the cockpit
+
+- Trivial fix (typo, dead import, one-line bug). Just do it.
+- A question scoped to a file you already know.
+- Executing a prompt that's explicitly in Next-3 and `cockpit status` shows no drift.
+
+---
+
+## Failure modes the cockpit cannot fix
+
+- A session that lies in `now.md` about what was built. The validator reads metadata, not intent.
+- A prompt frontmatter that says `status: queued` but the body describes shipped work.
+
+For each : prevention beats detection. Templates + protocol + validator are the prevention layer. Honest description + human review are the last line.
+
+---
+
+## Learn more
+
+- Source : https://github.com/justethales/cockpit-skill
+- Blog post : https://thalesandhisaictoclaude.com
+- Issues / feedback : https://github.com/justethales/cockpit-skill/issues