@justethales/cockpit 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## 0.1.0 — 2026-05-30
+
+Initial release.
+
+- `cockpit init` — scaffolds a `cockpit/` directory with `state.json`, `now.md`, `roadmap.md`, `README.md`, and the three canonical templates (`session-prompt.md`, `session-log.md`, `audit-brief.md`).
+- `cockpit check` — validator with 7 categories. Exits 1 on FAIL. ANSI output. `--quiet` flag for CI.
+- `cockpit status` — one-screen snapshot. `--plain` flag strips ANSI.
+- `cockpit new prompt --slug X` — copies the session-prompt template to `docs/plan/sessions/`.
+- `cockpit new log --slug X` — copies the session-log template to `session-logs/`.
+- Claude Code skills bundle (`skills/cockpit/`, `skills/next/`) — drop into `~/.claude/skills/` for instant `/cockpit` and `/next` slash commands.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thales (Juste Gnimavo) — ZeroSuite, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,254 @@
+# Cockpit
+
+> **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.
+
+Built by [Thales (Juste Gnimavo)](https://thalesandhisaictoclaude.com) — solo CEO running six production products with one AI engineer. The cockpit is the operating system that keeps those sessions coherent across days, weeks, and feature gaps.
+
+[Read the full story](https://thalesandhisaictoclaude.com) — the blog post that introduced this pattern explains the WHY. This README explains the HOW.
+
+---
+
+## Why this exists
+
+You finish a Claude Code session at 11pm. You ship a feature. You think you closed the cockpit cleanly.
+
+You open a fresh session at 9am. The agent reads your project's docs. It tells you "I see you shipped X yesterday — should I start Y?" You say yes.
+
+Halfway through Y, the agent realizes Y was already shipped two days ago. The cockpit pointed at the wrong next thing. You just burned 90 minutes on a duplicate.
+
+**That's drift.** It's the single most common failure mode of long-running AI coding workflows. Not bad code. Not security holes. Just the slow accumulation of "the cockpit says X but the code does Y" errors that eventually make the next session start with 30 minutes of re-orientation.
+
+The cockpit fixes drift by :
+
+1. **Centralizing session state** in one `state.json` file (machine-readable).
+2. **Validating that state** against the filesystem and git on every push (`npx cockpit check`).
+3. **Surfacing the state** in one screen for any fresh session (`npx cockpit status`).
+4. **Templating the artifacts** every session produces (prompt + log + audit brief).
+
+That's it. No tracking pixels, no SaaS, no required login. MIT license. 200 lines of TypeScript you can read in 10 minutes.
+
+---
+
+## Install
+
+### Quick start (no install)
+
+```bash
+npx @thales/cockpit init       # scaffold cockpit/ in current directory
+npx @thales/cockpit status     # one-screen snapshot
+npx @thales/cockpit check      # validate state.json against the world
+```
+
+Works in any directory. Requires Node ≥ 20.
+
+### Global install (CLI everywhere)
+
+```bash
+npm install -g @thales/cockpit
+cockpit init
+cockpit status
+cockpit check
+```
+
+### Project install (committed to package.json)
+
+```bash
+npm install --save-dev @thales/cockpit
+```
+
+Add to `package.json` scripts :
+
+```json
+{
+  "scripts": {
+    "cockpit:status": "cockpit status",
+    "cockpit:check": "cockpit check"
+  }
+}
+```
+
+Then `pnpm cockpit:status` / `pnpm cockpit:check` from any session.
+
+### Claude Code skills (slash commands)
+
+```bash
+cp -r node_modules/@thales/cockpit/skills/cockpit ~/.claude/skills/
+cp -r node_modules/@thales/cockpit/skills/next ~/.claude/skills/
+```
+
+Now type `/cockpit` or `/next` in any Claude Code session. The skills wrap the CLI with the right pre-flight, fallback paths, and execution posture.
+
+---
+
+## Quickstart
+
+```bash
+cd my-project
+npx cockpit init
+```
+
+That creates :
+
+```
+cockpit/
+├── state.json          # machine-readable session state
+├── now.md              # what's the current focus (human-readable)
+├── roadmap.md          # Next 3 to ship + phase scoreboard
+├── README.md           # the protocol for your project
+└── templates/
+    ├── session-prompt.md
+    ├── session-log.md
+    └── audit-brief.md
+```
+
+Edit `cockpit/now.md` and `cockpit/roadmap.md` to describe your project. Edit `cockpit/state.json` to set the initial `current_phase` / `next_phase` / `next_prompt`.
+
+Draft your first session prompt :
+
+```bash
+npx cockpit new prompt --slug phase-1-first-slice
+# edit docs/plan/sessions/PHASE-1-FIRST-SLICE.md
+```
+
+At session start, the agent runs :
+
+```bash
+npx cockpit status
+```
+
+…which prints the snapshot and tells the agent which prompt file to open.
+
+At session close, the agent runs (in order) :
+
+```bash
+npx cockpit new log --slug what-shipped       # write the log
+# (edit the log, the prompt's frontmatter, now.md, roadmap.md, state.json)
+npx cockpit check                              # 0 FAIL before push
+git add . && git commit && git push
+```
+
+That's the loop.
+
+---
+
+## What the validator catches
+
+```
+$ npx cockpit check
+
+cockpit:check · 22 PASS · 2 WARN · 1 FAIL
+──────────────────────────────────────────────────────────────────────
+  PASS  state.json has 'next_prompt'
+  PASS  next_prompt file exists · docs/plan/sessions/PHASE-1-AUTH.md
+  FAIL  next_prompt is already SHIPPED · docs/plan/sessions/PHASE-1-AUTH.md has status: shipped — cockpit was not bumped after that session
+        → either (a) update state.json.next_prompt to the real next slice, or (b) re-execute the shipped prompt explicitly
+  ...
+  WARN  last_commit is in history but not at HEAD · state=abc1234 HEAD=def5678
+        → bump state.last_commit to def5678
+  ...
+
+✗ 1 drift detected. Fix before push.
+```
+
+Eight check categories. The full list is in [cockpit/README.md](templates/README.md) after init. The high-value ones :
+
+- `state.json.next_prompt` points at a missing file or a `shipped` prompt.
+- `state.json.last_session_id` doesn't map to a session-log file.
+- `state.json.last_commit` not in `git log`.
+- `state.json.phases_shipped[]` has duplicates.
+- `state.json.migrations_applied[]` doesn't match the migrations directory.
+- A session prompt has `status: shipped` but no `session_log:` pointer.
+- Uncommitted changes in cockpit-area files.
+
+Each failure prints a `→ fix` hint.
+
+---
+
+## Philosophy
+
+Three opinions baked into the cockpit. Take them or fork it.
+
+### 1. **Templates are gates, not guidance.**
+
+Every session produces three artifacts : the session prompt (drafted at the end of the *previous* session), the session log (written at the end of *this* session), and the audit brief (used to spawn the post-implementation auditor). All three have an implicit shape that prior projects had to discover by mirroring earlier files. The cockpit's templates make that shape explicit. When you draft a new prompt, run `cockpit new prompt --slug X` — don't copy-paste a prior one.
+
+### 2. **Validate state, not intent.**
+
+The validator checks metadata : "does `state.json.next_prompt` point at a queued prompt, and does that prompt's frontmatter say `queued`?". It cannot check intent — whether your `now.md` paragraph accurately describes what was built. That's a humans-and-honest-self-review job. The post-implementation audit catches code-vs-spec drift ; nothing catches description-vs-reality drift. Acknowledge this and don't try to over-engineer it.
+
+### 3. **`cockpit check` is mandatory before push, no exceptions.**
+
+The 200 ms cost of the validator is negligible. The cost of drift surfacing at session-start the next day is real (10–30 minutes of confusion). Make the validator a `pre-push` gate (manually, via a hook, or via your team's discipline). The day you skip it is the day you ship a state.json that lies about what was done.
+
+---
+
+## What this is NOT
+
+- **Not a task tracker.** Use Linear, Jira, GitHub Issues. The cockpit is about *which session ships next*, not *which issues are open*.
+- **Not a project management tool.** No timelines, no story points, no burndown charts.
+- **Not a CI tool.** It runs locally. You can wire it into CI as a pre-push check, but it doesn't replace your test runner.
+- **Not opinionated about your code.** It cares about session state. Your code can be Rust, Python, TypeScript, Go, anything.
+
+---
+
+## Project structure conventions
+
+The cockpit assumes :
+
+```
+your-project/
+├── cockpit/                    # the cockpit
+│   ├── state.json
+│   ├── now.md
+│   ├── roadmap.md
+│   ├── README.md
+│   └── templates/
+├── docs/plan/sessions/         # session prompts
+│   ├── PHASE-1-AUTH.md
+│   ├── PHASE-2-PROFILE.md
+│   └── ...
+├── session-logs/               # session logs
+│   ├── 26-05-30-001-phase-1-auth.md
+│   ├── 26-05-30-002-phase-2-profile.md
+│   └── ...
+└── (your code)
+```
+
+If you use different paths, you can adjust them in `cockpit/state.json`'s `migrations_dir` field (for migration paths) and edit the templates. The validator paths are currently hardcoded ; configurability is a v0.2 thing if there's demand.
+
+---
+
+## FAQ
+
+**Q : Does this require Claude Code?**
+No. The CLI works standalone. The skills bundle (`skills/cockpit`, `skills/next`) is opt-in for Claude Code users who want the slash commands.
+
+**Q : Does this work for Cursor / Aider / Continue?**
+Yes. The CLI is just a CLI. Any agent that can run shell commands and read files can use it. The slash-command skills are Claude Code-specific, but the underlying discipline transfers.
+
+**Q : What about Python / Rust / Go projects?**
+The CLI is Node-only (TypeScript via `tsx`). You can install via `npx` without committing Node as a project dependency. If you want a binary distribution, file an issue — it's a 1-day port.
+
+**Q : Can I customize the templates?**
+Yes. After `cockpit init`, the templates live in your project at `cockpit/templates/`. Edit them freely. The CLI's `cockpit new` commands copy from your project's templates if they exist.
+
+**Q : What if my project doesn't have phases?**
+The cockpit uses "phase" as a generic word for "unit of work that ships together." You can map it to "epic," "milestone," "sprint," or "release" — same machinery.
+
+**Q : Is the cockpit data sent anywhere?**
+No. Zero network calls. Zero telemetry. The cockpit reads your filesystem and your `git`. Nothing leaves your machine.
+
+**Q : Where do I report bugs / feature requests?**
+https://github.com/justethales/cockpit-skill/issues
+
+---
+
+## License
+
+MIT. Use it, fork it, ship it.
+
+If the cockpit saves you 30 minutes a week, that's enough payback. If you want to say thanks : star the GitHub repo, share the blog post, or [say hi on X](https://x.com/JusteThales).
+
+---
+
+*Cockpit is a small thing. Most of the value is in the discipline it forces, not in the 200 lines of TypeScript. Read the [blog post](https://thalesandhisaictoclaude.com) for the full story behind the pattern.*

package/dist/check.js

@@ -0,0 +1,228 @@
+/**
+ * `cockpit check` — validate state.json against filesystem + git + prompt frontmatter.
+ *
+ * Exit code 1 on any FAIL. Use --quiet to suppress PASS lines (CI-friendly).
+ */
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { exit } from 'node:process';
+import { c, git, loadState, readFrontmatter } from './shared.js';
+const ROOT = process.cwd();
+const STATE_PATH = join(ROOT, 'cockpit', 'state.json');
+const SESSIONS_DIR = join(ROOT, 'docs', 'plan', 'sessions');
+const LOGS_DIR = join(ROOT, 'session-logs');
+export function runCheck(args) {
+    const quiet = args.includes('--quiet');
+    const noGit = args.includes('--no-git');
+    const findings = [];
+    function record(id, severity, label, detail, fix) {
+        findings.push({ id, severity, label, detail, fix });
+    }
+    if (!existsSync(STATE_PATH)) {
+        console.error(c.red('FAIL') + ` no cockpit/state.json found at ${STATE_PATH}`);
+        console.error(c.gray('       → run `npx cockpit init` first'));
+        exit(1);
+    }
+    const state = loadState(STATE_PATH);
+    if (!state) {
+        console.error(c.red('FAIL') + ' cockpit/state.json is not valid JSON');
+        exit(1);
+    }
+    /* 1. Required keys ----------------------------------------------------- */
+    const required = [
+        'updated_at',
+        'last_session_id',
+        'last_commit',
+        'current_phase',
+        'next_phase',
+        'next_prompt',
+        'phases_shipped'
+    ];
+    for (const key of required) {
+        if (state[key] === undefined || state[key] === null) {
+            record(`state.shape.${key}`, 'fail', 'state.json missing required key', `key '${key}' is missing`, `add "${key}": <value> to cockpit/state.json`);
+        }
+        else {
+            record(`state.shape.${key}`, 'pass', `state.json has '${key}'`, '');
+        }
+    }
+    /* 2. next_prompt resolves --------------------------------------------- */
+    if (state.next_prompt) {
+        const path = join(ROOT, state.next_prompt);
+        if (!existsSync(path)) {
+            record('next_prompt.exists', 'fail', 'state.json.next_prompt points at a missing file', `${state.next_prompt} does not exist`, `draft the prompt at that path (try \`npx cockpit new prompt --slug <slug>\`) OR fix state.json.next_prompt`);
+        }
+        else {
+            record('next_prompt.exists', 'pass', 'next_prompt file exists', state.next_prompt);
+            const fm = readFrontmatter(path);
+            if (!fm) {
+                record('next_prompt.frontmatter', 'fail', 'next_prompt has no frontmatter', `${state.next_prompt} should start with --- ... ---`, `add status / session_id / drafted_at frontmatter`);
+            }
+            else {
+                const status = String(fm.status ?? '');
+                if (status === 'shipped') {
+                    record('next_prompt.status', 'fail', 'next_prompt is already SHIPPED', `${state.next_prompt} has status: shipped — cockpit was not bumped after that session`, `either update state.json.next_prompt to the real next slice, or re-execute the shipped prompt explicitly`);
+                }
+                else if (status === 'queued' || status === 'in-progress') {
+                    record('next_prompt.status', 'pass', `next_prompt status is '${status}'`, state.next_prompt);
+                }
+                else {
+                    record('next_prompt.status', 'warn', 'next_prompt has unusual status', `status='${status}' — expected 'queued' or 'in-progress'`, `set status: queued in the prompt frontmatter`);
+                }
+            }
+        }
+    }
+    /* 3. last_session_id → log -------------------------------------------- */
+    if (state.last_session_id) {
+        const logPath = join(LOGS_DIR, `${state.last_session_id}.md`);
+        if (existsSync(logPath)) {
+            record('last_session.log_exists', 'pass', 'last_session_id has a matching session log', `session-logs/${state.last_session_id}.md`);
+        }
+        else {
+            record('last_session.log_exists', 'fail', 'last_session_id does not map to a session log', `expected session-logs/${state.last_session_id}.md`, `write the session log (try \`npx cockpit new log --slug <slug>\`) OR fix last_session_id`);
+        }
+    }
+    /* 4. last_commit vs git ----------------------------------------------- */
+    if (!noGit && state.last_commit && state.last_commit !== 'pending') {
+        const head = git('rev-parse --short HEAD');
+        if (!head) {
+            record('last_commit.git', 'warn', 'cannot run git', 'is this a repo?');
+        }
+        else if (head.startsWith(state.last_commit) ||
+            state.last_commit.startsWith(head)) {
+            record('last_commit.git', 'pass', 'last_commit matches HEAD', `state=${state.last_commit} HEAD=${head}`);
+        }
+        else {
+            const exists = git(`rev-parse --verify ${state.last_commit}^{commit}`);
+            if (exists) {
+                record('last_commit.git', 'warn', 'last_commit is in history but not at HEAD', `state=${state.last_commit} HEAD=${head}`, `if the new commits are uncockpitted work, bump state.last_commit to ${head}`);
+            }
+            else {
+                record('last_commit.git', 'fail', 'last_commit not found in git', `state=${state.last_commit} does not exist in this repo`, `set state.last_commit to a real SHA (HEAD = ${head})`);
+            }
+        }
+    }
+    else if (state.last_commit === 'pending') {
+        record('last_commit.git', 'warn', "last_commit is 'pending'", 'expected after first commit of session, before push', 'bump state.last_commit to the commit SHA before push');
+    }
+    /* 5. phases_shipped uniqueness ---------------------------------------- */
+    if (Array.isArray(state.phases_shipped)) {
+        const seen = new Set();
+        const dupes = [];
+        for (const p of state.phases_shipped) {
+            if (seen.has(p))
+                dupes.push(p);
+            seen.add(p);
+        }
+        if (dupes.length) {
+            record('phases_shipped.unique', 'fail', 'phases_shipped has duplicates', dupes.join(', '), 'dedupe the array');
+        }
+        else {
+            record('phases_shipped.unique', 'pass', `phases_shipped is unique (${state.phases_shipped.length} entries)`, '');
+        }
+    }
+    /* 6. migrations_applied (optional) ------------------------------------- */
+    const migrationsDir = join(ROOT, state.migrations_dir || 'drizzle');
+    if (Array.isArray(state.migrations_applied) && existsSync(migrationsDir)) {
+        const onDisk = readdirSync(migrationsDir)
+            .filter((f) => f.endsWith('.sql'))
+            .map((f) => f.replace(/\.sql$/, ''))
+            .sort();
+        const inState = [...state.migrations_applied].sort();
+        const missingFromState = onDisk.filter((m) => !inState.includes(m));
+        const missingFromDisk = inState.filter((m) => !onDisk.includes(m));
+        if (missingFromState.length || missingFromDisk.length) {
+            record('migrations.match', 'fail', `migrations_applied does not match ${state.migrations_dir || 'drizzle'}/`, `state-missing: ${missingFromState.join(', ') || '(none)'} · disk-missing: ${missingFromDisk.join(', ') || '(none)'}`, 'add missing-from-state to state.migrations_applied OR remove ghosts');
+        }
+        else if (onDisk.length > 0) {
+            record('migrations.match', 'pass', `migrations_applied matches ${state.migrations_dir || 'drizzle'}/ (${onDisk.length} files)`, '');
+        }
+    }
+    /* 7. Session prompt frontmatter --------------------------------------- */
+    const VALID_STATUS = new Set(['queued', 'in-progress', 'shipped', 'archived']);
+    if (existsSync(SESSIONS_DIR)) {
+        const prompts = readdirSync(SESSIONS_DIR)
+            .filter((f) => f.endsWith('.md'))
+            .map((f) => join(SESSIONS_DIR, f))
+            .filter((f) => statSync(f).isFile());
+        let shippedWithoutLog = 0;
+        let invalidStatusValues = [];
+        for (const p of prompts) {
+            const rel = relative(ROOT, p);
+            const fm = readFrontmatter(p);
+            if (!fm) {
+                record(`prompt.${rel}.frontmatter`, 'warn', 'prompt has no parsable frontmatter', rel);
+                continue;
+            }
+            const status = String(fm.status ?? '');
+            if (!VALID_STATUS.has(status)) {
+                invalidStatusValues.push(`${rel} status='${status}'`);
+            }
+            if (status === 'shipped') {
+                const logField = String(fm.session_log ?? '');
+                if (!logField || logField === 'pending') {
+                    shippedWithoutLog++;
+                    record(`prompt.${rel}.session_log`, 'fail', 'shipped prompt has no session_log pointer', rel, 'set session_log: session-logs/<id>.md in the frontmatter');
+                }
+                else if (!existsSync(join(ROOT, logField))) {
+                    record(`prompt.${rel}.session_log_exists`, 'fail', "shipped prompt's session_log file is missing", `${rel} -> ${logField}`, 'either write the missing log OR fix the pointer');
+                }
+            }
+        }
+        if (invalidStatusValues.length) {
+            record('prompts.status_values', 'warn', 'some prompts have non-canonical status values', invalidStatusValues.join(' · '), `use one of: ${[...VALID_STATUS].join(' | ')}`);
+        }
+        else if (prompts.length) {
+            record('prompts.status_values', 'pass', `all ${prompts.length} prompt(s) have canonical status`, '');
+        }
+        if (shippedWithoutLog === 0 && prompts.length) {
+            record('prompts.shipped_logged', 'pass', 'every shipped prompt has a session_log pointer', '');
+        }
+    }
+    /* 8. Working tree clean for cockpit + sessions + logs ----------------- */
+    if (!noGit) {
+        const dirty = git('status --porcelain cockpit docs/plan/sessions session-logs');
+        if (dirty) {
+            record('workdir.clean', 'warn', 'cockpit / sessions / logs have uncommitted changes', dirty.split('\n').slice(0, 5).join(' · '), 'commit + push before the session closes');
+        }
+        else {
+            record('workdir.clean', 'pass', 'cockpit + sessions + logs are committed', '');
+        }
+    }
+    /* Report --------------------------------------------------------------- */
+    const pass = findings.filter((f) => f.severity === 'pass').length;
+    const warn = findings.filter((f) => f.severity === 'warn').length;
+    const fail = findings.filter((f) => f.severity === 'fail').length;
+    if (!quiet || fail > 0) {
+        const head = `${c.bold('cockpit:check')} · ${pass} PASS · ${warn > 0 ? c.yellow(`${warn} WARN`) : `${warn} WARN`} · ${fail > 0 ? c.red(`${fail} FAIL`) : `${fail} FAIL`}`;
+        console.log('');
+        console.log(head);
+        console.log(c.gray('─'.repeat(70)));
+        for (const f of findings) {
+            const tag = f.severity === 'pass'
+                ? c.green('PASS')
+                : f.severity === 'warn'
+                    ? c.yellow('WARN')
+                    : c.red('FAIL');
+            if (f.severity === 'pass' && quiet)
+                continue;
+            const detail = f.detail ? c.gray(` · ${f.detail}`) : '';
+            console.log(`  ${tag}  ${f.label}${detail}`);
+            if (f.fix && f.severity !== 'pass') {
+                console.log(`        ${c.cyan('→')} ${c.gray(f.fix)}`);
+            }
+        }
+        console.log('');
+        if (fail > 0) {
+            console.log(c.red(`✗ ${fail} drift${fail > 1 ? 's' : ''} detected. Fix before push.`));
+        }
+        else if (warn > 0) {
+            console.log(c.yellow(`⚠ ${warn} warning${warn > 1 ? 's' : ''} (not blocking).`));
+        }
+        else {
+            console.log(c.green('✓ cockpit is coherent. Push when ready.'));
+        }
+        console.log('');
+    }
+    exit(fail > 0 ? 1 : 0);
+}

package/dist/cli.js

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+/**
+ * cockpit — a 200-line discipline for AI-coding sessions.
+ *
+ * https://github.com/justethales/cockpit-skill
+ * MIT License.
+ */
+import { argv, exit } from 'node:process';
+import { runInit } from './init.js';
+import { runCheck } from './check.js';
+import { runStatus } from './status.js';
+import { runNew } from './new.js';
+const VERSION = '0.1.0';
+const HELP = `
+cockpit ${VERSION} — a 200-line discipline for AI-coding sessions
+
+USAGE
+  cockpit <command> [options]
+
+COMMANDS
+  init                          Scaffold cockpit/ in the current directory
+  status                        Print one-screen snapshot (use --plain for no color)
+  check                         Validate state.json against filesystem + git
+  check --quiet                 Same, suppress output unless FAIL
+  new prompt --slug <kebab-id>  Copy session-prompt template to docs/plan/sessions/
+  new log --slug <kebab-id>     Copy session-log template to session-logs/
+
+GLOBAL
+  -h, --help                    Print this help
+  -V, --version                 Print version
+
+EXAMPLES
+  cockpit init                  # in a fresh repo
+  cockpit status                # at session start
+  cockpit check                 # before git push
+  cockpit new prompt --slug phase-2-auth-flow
+
+LEARN MORE
+  https://github.com/justethales/cockpit-skill
+  https://thalesandhisaictoclaude.com
+`;
+function main() {
+    const args = argv.slice(2);
+    if (args.length === 0 || args.includes('-h') || args.includes('--help')) {
+        console.log(HELP);
+        exit(0);
+    }
+    if (args.includes('-V') || args.includes('--version')) {
+        console.log(VERSION);
+        exit(0);
+    }
+    const [cmd, ...rest] = args;
+    switch (cmd) {
+        case 'init':
+            runInit(rest);
+            break;
+        case 'status':
+            runStatus(rest);
+            break;
+        case 'check':
+            runCheck(rest);
+            break;
+        case 'new':
+            runNew(rest);
+            break;
+        default:
+            console.error(`unknown command: ${cmd}\n`);
+            console.log(HELP);
+            exit(1);
+    }
+}
+main();

package/dist/init.js

@@ -0,0 +1,78 @@
+/**
+ * `cockpit init` — scaffold a cockpit/ directory in the current repo.
+ */
+import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, 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);
+const TEMPLATES = join(__dirname, '..', 'templates');
+function copyDir(src, dest, force) {
+    if (!existsSync(dest))
+        mkdirSync(dest, { recursive: true });
+    for (const entry of readdirSync(src)) {
+        const s = join(src, entry);
+        const d = join(dest, entry);
+        if (statSync(s).isDirectory()) {
+            copyDir(s, d, force);
+        }
+        else {
+            if (existsSync(d) && !force) {
+                console.log(`  ${c.gray('skip')}    ${relative(process.cwd(), d)} (exists)`);
+                continue;
+            }
+            copyFileSync(s, d);
+            console.log(`  ${c.green('write')}   ${relative(process.cwd(), d)}`);
+        }
+    }
+}
+function interpolate(filePath, vars) {
+    const raw = readFileSync(filePath, 'utf8');
+    let out = raw;
+    for (const [k, v] of Object.entries(vars)) {
+        out = out.split(`{{${k}}}`).join(v);
+    }
+    if (out !== raw)
+        writeFileSync(filePath, out);
+}
+export function runInit(args) {
+    const force = args.includes('--force') || args.includes('-f');
+    const root = process.cwd();
+    const target = join(root, 'cockpit');
+    if (existsSync(target) && !force) {
+        console.log(c.yellow(`cockpit/ already exists at ${target}`));
+        console.log(c.gray('use --force to overwrite, or edit the existing files'));
+        exit(0);
+    }
+    console.log(`${c.bold('cockpit init')} · scaffolding ${c.cyan(relative(root, target) || 'cockpit/')}`);
+    console.log('');
+    copyDir(TEMPLATES, target, force);
+    // Interpolate the date placeholder in scaffolded markdown.
+    const today = todayISO();
+    const interpolatables = [
+        join(target, 'now.md'),
+        join(target, 'roadmap.md'),
+        join(target, 'state.json'),
+        join(target, 'README.md')
+    ];
+    for (const f of interpolatables) {
+        if (existsSync(f))
+            interpolate(f, { TODAY: today });
+    }
+    console.log('');
+    console.log(c.green('✓ cockpit scaffolded.'));
+    console.log('');
+    console.log('Next steps :');
+    console.log(`  ${c.cyan('1.')} edit ${c.gray('cockpit/now.md')} — describe your current focus`);
+    console.log(`  ${c.cyan('2.')} edit ${c.gray('cockpit/roadmap.md')} — fill the Next 3 to ship`);
+    console.log(`  ${c.cyan('3.')} edit ${c.gray('cockpit/state.json')} — fill current_phase / next_phase / next_prompt`);
+    console.log(`  ${c.cyan('4.')} draft your first session prompt :`);
+    console.log(`     ${c.gray('npx cockpit new prompt --slug my-first-session')}`);
+    console.log(`  ${c.cyan('5.')} validate before push :`);
+    console.log(`     ${c.gray('npx cockpit check')}`);
+    console.log('');
+    console.log(c.gray('full protocol → cockpit/README.md'));
+    console.log('');
+}