kracked-core 1.0.0

package/src/wizard.mjs

@@ -0,0 +1,276 @@
+// Interactive prompt flow for `npx kracked-core init`.
+// Follows the wizard flow in CONTRACT.md exactly — question order matters.
+
+import readline from 'node:readline/promises';
+import { stdin, stdout } from 'node:process';
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+
+import {
+  globalMemoryExists,
+  globalMemoryDir,
+  classifyProjectDir,
+  scanExistingProject,
+  stackSummaryLine,
+} from './detect.mjs';
+import {
+  writeGlobalMemory,
+  registerProject,
+  writeProjectMemory,
+  writeLoaders,
+  writeSkills,
+} from './scaffold.mjs';
+
+/** Expand a leading ~ to the home directory. Leaves other paths untouched. */
+function expandTilde(inputPath) {
+  if (!inputPath) return inputPath;
+  if (inputPath === '~') return os.homedir();
+  if (inputPath.startsWith('~/') || inputPath.startsWith('~\\')) {
+    return path.join(os.homedir(), inputPath.slice(2));
+  }
+  return inputPath;
+}
+
+/** Format today's date as YYYY-MM-DD. */
+function isoDate() {
+  return new Date().toISOString().slice(0, 10);
+}
+
+/**
+ * Turn detected package.json scripts into a ready-to-read "how to run it" block.
+ * The scan already knows these commands — writing them into project.md is the
+ * difference between a drafted memory and an empty one full of TODOs.
+ */
+function runCommandsBlock(summary) {
+  const scripts = summary?.scripts ? Object.keys(summary.scripts) : [];
+  if (!scripts.length) return '- _(not set yet)_';
+
+  // Surface the commands people actually reach for first, then the rest.
+  const priority = ['dev', 'start', 'build', 'test', 'lint', 'typecheck'];
+  const ordered = [
+    ...priority.filter((s) => scripts.includes(s)),
+    ...scripts.filter((s) => !priority.includes(s)),
+  ];
+
+  return ordered.map((s) => `- \`${s}\` — \`npm run ${s}\``).join('\n');
+}
+
+export async function runInit() {
+  // Non-interactive stdin (e.g. piped input, CI) can't drive a wizard —
+  // fail clearly instead of hanging on a prompt that will never resolve.
+  if (!stdin.isTTY) {
+    process.stderr.write(
+      'kracked-core init needs an interactive terminal to ask setup questions.\n' +
+      'Run it directly in a terminal (not piped or in a non-interactive script).\n'
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  const rl = readline.createInterface({ input: stdin, output: stdout });
+
+  let interrupted = false;
+  const onSigint = () => {
+    interrupted = true;
+    stdout.write('\n\nCancelled. Nothing after this point was written.\n');
+    rl.close();
+    process.exit(130);
+  };
+  process.on('SIGINT', onSigint);
+
+  try {
+    await wizardFlow(rl);
+  } catch (err) {
+    // Ctrl+D (EOF) mid-question surfaces as readline's AbortError. Treat it
+    // the same as Ctrl+C — a clean cancel, not a crash with a scary stack.
+    if (err.code === 'ABORT_ERR' || /ctrl\+d/i.test(err.message || '')) {
+      stdout.write('\n\nCancelled. Nothing after this point was written.\n');
+      process.exitCode = 130;
+      return;
+    }
+    throw err;
+  } finally {
+    process.off('SIGINT', onSigint);
+    if (!interrupted) rl.close();
+  }
+}
+
+/** Ask a question with a default; Enter alone accepts the default. */
+async function ask(rl, question, defaultValue) {
+  const suffix = defaultValue ? ` [${defaultValue}]` : '';
+  const answer = (await rl.question(`${question}${suffix} `)).trim();
+  return answer === '' ? defaultValue : answer;
+}
+
+/** Ask a yes/no question. Returns boolean. Default shown as Y/n or y/N. */
+async function askYesNo(rl, question, defaultYes) {
+  const suffix = defaultYes ? '[Y/n]' : '[y/N]';
+  const answer = (await rl.question(`${question} ${suffix} `)).trim().toLowerCase();
+  if (answer === '') return defaultYes;
+  return answer === 'y' || answer === 'yes';
+}
+
+/** Prompt for how to resolve a file-already-exists conflict. */
+async function askConflict(rl, destPath) {
+  stdout.write(`\n  Already exists: ${destPath}\n`);
+  const answer = (
+    await rl.question('  skip / overwrite / write alongside as .kracked-new? [skip] ')
+  ).trim().toLowerCase();
+
+  if (answer === 'o' || answer === 'overwrite') return 'overwrite';
+  if (answer === 'a' || answer === 'alongside' || answer === 'write alongside') return 'alongside';
+  return 'skip';
+}
+
+async function wizardFlow(rl) {
+  const created = [];
+  const reporter = (entry) => created.push(entry);
+  const conflictAsk = (destPath) => askConflict(rl, destPath);
+
+  stdout.write('kracked-core — set up memory for your AI coding agent\n\n');
+
+  // 1. Agent name
+  const agentName = (await ask(rl, 'What should we call your agent?', 'KC')) || 'KC';
+
+  // 2. User name
+  const systemUser = os.userInfo().username || 'you';
+  const userName = (await ask(rl, 'Your name?', systemUser)) || systemUser;
+
+  // 3. Global memory
+  const hasGlobal = globalMemoryExists();
+  let setUpGlobal;
+  if (!hasGlobal) {
+    setUpGlobal = await askYesNo(rl, 'Set up global memory now?', true);
+  } else {
+    const reuse = await askYesNo(rl, 'Global memory found. Reuse it?', true);
+    setUpGlobal = !reuse; // if not reusing, we still (re)write it below
+  }
+
+  // 4. Project setup
+  const setUpProject = await askYesNo(rl, 'Set up this project?', true);
+
+  let projectDir = process.cwd();
+  let projectMode = null; // 'new' | 'existing'
+  let stackLine = 'unknown — not auto-detected';
+  let projectSummary = null;
+
+  if (setUpProject) {
+    const pathAnswer = await ask(rl, 'Project directory?', '.');
+    const expanded = expandTilde(pathAnswer);
+    projectDir = path.resolve(expanded === '' ? '.' : expanded);
+
+    const classification = classifyProjectDir(projectDir);
+
+    if (classification === 'existing') {
+      const modeAnswer = (
+        await ask(rl, 'New project or existing codebase? (new/existing)', 'existing')
+      ).toLowerCase();
+      projectMode = modeAnswer.startsWith('n') ? 'new' : 'existing';
+    } else {
+      const modeAnswer = (
+        await ask(rl, 'New project or existing codebase? (new/existing)', 'new')
+      ).toLowerCase();
+      projectMode = modeAnswer.startsWith('e') ? 'existing' : 'new';
+    }
+
+    if (projectMode === 'existing') {
+      if (!fs.existsSync(projectDir)) {
+        stdout.write(`\n  ${projectDir} doesn't exist yet — nothing to scan. Treating as new.\n`);
+        projectMode = 'new';
+      } else {
+        projectSummary = scanExistingProject(projectDir);
+        stackLine = stackSummaryLine(projectSummary);
+
+        stdout.write('\n  Scanned project:\n');
+        stdout.write(`    Name:   ${projectSummary.name}\n`);
+        stdout.write(`    Stack:  ${stackLine}\n`);
+        stdout.write(`    Git:    ${projectSummary.isGitRepo ? 'yes' : 'no'}\n`);
+        const scriptNames = Object.keys(projectSummary.scripts);
+        if (scriptNames.length) {
+          stdout.write(`    Scripts: ${scriptNames.join(', ')}\n`);
+        }
+        stdout.write('\n');
+
+        const confirmed = await askYesNo(rl, 'Does this look right?', true);
+        if (!confirmed) {
+          const manualStack = await ask(rl, 'Describe the stack yourself:', stackLine);
+          stackLine = manualStack;
+        }
+      }
+    }
+
+    // Ensure the target directory exists before we try to write into it.
+    try {
+      fs.mkdirSync(projectDir, { recursive: true });
+    } catch (err) {
+      throw new Error(`Can't create or write to ${projectDir}: ${err.message}`);
+    }
+  }
+
+  // 5. Editors
+  const editorAnswer = (
+    await ask(rl, 'Which editor(s) do you use? (antigravity/claude/both/other)', 'both')
+  ).toLowerCase();
+
+  let editors;
+  if (editorAnswer.startsWith('both')) {
+    editors = ['antigravity', 'claude'];
+  } else if (editorAnswer.startsWith('a')) {
+    editors = ['antigravity'];
+  } else if (editorAnswer.startsWith('c')) {
+    editors = ['claude'];
+  } else {
+    // "other" or anything unrecognized — still write both loader formats,
+    // since AGENTS.md/CLAUDE.md are cheap and cover most tools either way.
+    editors = ['antigravity', 'claude'];
+  }
+
+  // 6. Write files
+  const projectName = projectSummary?.name || (setUpProject ? path.basename(projectDir) : 'unnamed-project');
+
+  const tokens = {
+    AGENT_NAME: agentName,
+    USER_NAME: userName,
+    PROJECT_NAME: projectName,
+    PROJECT_PATH: projectDir,
+    DATE: isoDate(),
+    STACK: stackLine,
+    RUN_COMMANDS: runCommandsBlock(projectSummary),
+  };
+
+  stdout.write('\nWriting files...\n');
+
+  if (setUpGlobal) {
+    await writeGlobalMemory({ tokens, ask: conflictAsk, report: reporter });
+  }
+  // Registering the project in the global registry is independent of whether
+  // global memory was just (re)written — it should happen whenever global
+  // memory exists at all, so kracked knows about every project touched.
+  if (setUpProject && (hasGlobal || setUpGlobal)) {
+    registerProject({ tokens });
+    created.push({ path: path.join(globalMemoryDir(), 'projects.md'), action: 'updated (registry)' });
+  }
+
+  if (setUpProject) {
+    await writeProjectMemory({ projectDir, tokens, ask: conflictAsk, report: reporter });
+    await writeLoaders({ projectDir, tokens, ask: conflictAsk, report: reporter });
+    await writeSkills({ projectDir, tokens, editors, ask: conflictAsk, report: reporter });
+  }
+
+  printSummary(created, agentName, setUpProject);
+}
+
+function printSummary(created, agentName, setUpProject) {
+  stdout.write('\nDone. Files:\n');
+  for (const entry of created) {
+    stdout.write(`  ${entry.action.padEnd(32)} ${entry.path}\n`);
+  }
+
+  stdout.write('\nNext step:\n');
+  if (setUpProject) {
+    stdout.write(`  Open this project in your editor and run /kracked-boot to load ${agentName}'s memory.\n`);
+  } else {
+    stdout.write('  Run kracked-core init again inside a project directory to wire it up.\n');
+  }
+}

package/templates/global/identity.md

@@ -0,0 +1,37 @@
+# Identity — {{AGENT_NAME}}
+
+You are **{{AGENT_NAME}}**, {{USER_NAME}}'s coding agent. This file is your identity — it survives
+every project and every session restart. Load it first, every boot.
+
+## Role
+
+You write code, explain tradeoffs, and help {{USER_NAME}} ship. You are not a search engine and not
+a yes-machine — you have an opinion, and you say so when something looks wrong.
+
+## How I work
+
+- **Direct.** Answer the question first, then explain if needed. No preamble, no throat-clearing.
+- **Honest.** If something won't work, say so before writing the code, not after it fails.
+- **Admit uncertainty.** "I don't know" or "I'm not sure, here's my best guess" beats a confident wrong answer.
+- **No flattery.** Don't praise the user's ideas to be agreeable. Evaluate them on merit.
+- **Show, don't just tell.** Prefer a working example over a paragraph describing one.
+- **Ask when blocked.** If a decision needs information only {{USER_NAME}} has, ask — don't guess and
+  move on silently.
+
+## Communication style
+
+- Plain language over jargon. Explain jargon the first time it's used.
+- Short answers for short questions. Depth when the problem needs it, not by default.
+- No filler enthusiasm ("Great question!", "Absolutely!"). State what's true and move on.
+
+## Boundaries
+
+- This file is global — it does not contain anything about a specific project. Project-specific
+  conventions live in that project's `project.md`, not here.
+- Don't rename yourself or adopt a different persona mid-session. You are {{AGENT_NAME}}.
+
+## See also
+
+- `preferences.md` — how {{USER_NAME}} likes to work (fill in over time)
+- `lessons.md` — patterns learned across projects
+- `projects.md` — what {{USER_NAME}} is currently building

package/templates/global/lessons-archive.md

@@ -0,0 +1,29 @@
+# Lessons — Archive
+
+Full detail for every lesson in `lessons.md`. This file is **not** read at boot — it's opened on
+demand, when a lesson looks relevant to the problem at hand, or when {{USER_NAME}} asks to see the
+detail behind an index line. Keeping it out of the boot payload is what lets the lessons list grow
+indefinitely without slowing every session down.
+
+## Entry format
+
+```
+## [YYYY-MM-DD] <project> — <short title>
+
+**What happened:** <the situation that produced the lesson>
+**Why it matters:** <the cost of getting it wrong>
+**Going forward:** <the concrete rule to follow next time>
+```
+
+## Entries
+
+## [2026-01-15] todo-app — Destructive migration ran without a backup
+
+**What happened:** Asked to drop an unused column, {{AGENT_NAME}} generated and ran the migration
+immediately. The column turned out to still be read by a reporting script that wasn't in the repo
+{{AGENT_NAME}} could see, and the data was gone.
+**Why it matters:** Destructive schema changes are not reversible once applied, even if the code
+change itself was correct.
+**Going forward:** Before any migration that drops or alters a column/table, state what will be
+lost and ask for explicit confirmation first. Never batch a destructive migration with unrelated
+changes.

package/templates/global/lessons.md

@@ -0,0 +1,23 @@
+# Lessons — Index
+
+This is the INDEX of everything {{AGENT_NAME}} has learned across all your projects. It is read
+**every boot**, so it must stay flat — one line per lesson, no exceptions.
+
+The full story behind each lesson (what happened, why it matters, how to avoid it) lives in
+`lessons-archive.md`. That file is opened **on demand only** — when a lesson looks relevant to
+the current problem, or when {{USER_NAME}} asks for the detail. Loading it every boot would make
+the boot payload grow forever, so it doesn't happen automatically.
+
+**Rule:** new lesson → full entry appended to `lessons-archive.md` + exactly ONE line added here.
+Never paste full entries into this index.
+
+## Format
+
+```
+- [YYYY-MM-DD] <project> — <one-line summary of the lesson>
+```
+
+## Index
+
+- [2026-01-15] todo-app — Don't run destructive DB migrations without a backup step first; ask before dropping columns.
+- [2026-02-03] my-blog — Check for an existing util before writing a new date-formatting helper; duplicated logic drifted twice.

package/templates/global/preferences.md

@@ -0,0 +1,53 @@
+# Preferences — {{USER_NAME}}
+
+How {{USER_NAME}} likes to work, across every project. This file ships mostly empty — fill it in as
+you learn, or edit it directly yourself. {{AGENT_NAME}} reads this every boot, so keep it short and
+concrete: rules, not essays.
+
+## Communication style
+
+<!--
+Example:
+- Keep explanations to 2-3 sentences unless I ask for more.
+- Show me the diff before you explain it, not after.
+-->
+
+- _(not set yet — add a few bullets, or let {{AGENT_NAME}} propose some after a few sessions)_
+
+## Code style
+
+<!--
+Example:
+- Prefer early returns over nested if/else.
+- No comments that just restate the code. Comment the "why", not the "what".
+- Match the file's existing quote style / indentation instead of your default.
+-->
+
+- _(not set yet)_
+
+## Always do
+
+<!--
+Example:
+- Run the linter before saying a change is done.
+- Write a migration for any schema change.
+-->
+
+- _(not set yet)_
+
+## Never do
+
+<!--
+Example:
+- Never commit without asking first.
+- Never install a new dependency without flagging it.
+- Never touch files outside the current task's scope.
+-->
+
+- _(not set yet)_
+
+## How to fill this in
+
+At the end of a session (`/kracked-wrap`), if {{AGENT_NAME}} notices a recurring preference, it
+should propose adding a line here. {{USER_NAME}} can also edit this file directly at any time —
+it's just a text file.

package/templates/global/projects.md

@@ -0,0 +1,26 @@
+# Projects
+
+Registry of every project {{USER_NAME}} is working on. Each row points to the project's own
+`.kracked/` folder, where the real detail (stack, conventions, session state) lives. This file
+only tracks what exists and where — never project-specific truth.
+
+## Format
+
+```
+| Project | Path | Stack | Status |
+```
+
+- **Status** is one of: `active`, `paused`, `done`.
+
+## Registry
+
+| Project | Path | Stack | Status |
+|---|---|---|---|
+| todo-app | ~/code/todo-app | Next.js, Postgres | active |
+| my-blog | ~/code/my-blog | Astro, Markdown | paused |
+
+## How this fills in
+
+When `/kracked-boot` or the setup wizard runs in a new project, add a row here pointing at its
+path. Don't copy that project's stack details or conventions here beyond the one-line summary —
+that belongs in the project's own `project.md`.

package/templates/loaders/AGENTS.md

@@ -0,0 +1,67 @@
+# AGENTS.md — {{PROJECT_NAME}}
+
+This is the canonical loader. Every harness (Antigravity, Claude Code, others) reads this file
+first. If a harness has its own shim (`CLAUDE.md`, `.agents/rules/kracked.md`), that shim points
+back here — the instructions live in exactly one place, here, so they can't drift apart.
+
+## Who you are
+
+You are **{{AGENT_NAME}}**. Your identity, communication style, and how you work are defined in
+global memory at `~/.kracked/identity.md`. Read it — don't assume a different persona.
+
+## Boot sequence (run this at the start of every session)
+
+Read these files, in this exact order, before doing any work:
+
+1. `~/.kracked/identity.md` — who you are
+2. `~/.kracked/preferences.md` — how {{USER_NAME}} likes to work, across all projects
+3. `~/.kracked/lessons.md` — the lessons INDEX only (one line per lesson)
+4. `~/.kracked/projects.md` — what else {{USER_NAME}} is building
+5. `.kracked/project.md` — what THIS project is (stack, conventions, structure)
+6. `.kracked/session.md` — working memory: current state, next step, blockers
+7. `.kracked/decisions.md` — this project's decision log
+8. `.kracked/sdd/tracker.md` — story status ledger, if this project uses SDD
+
+**Important: do NOT read `~/.kracked/lessons-archive.md` at boot.** It holds the full detail
+behind each line in `lessons.md` and is opened on demand only — when a lesson looks relevant to
+the current problem, or {{USER_NAME}} asks for it. Reading it every boot would make the boot
+payload grow without bound as more lessons accumulate; the index/archive split exists specifically
+to prevent that.
+
+After reading, orient in one line before starting work: state the project, the last known state
+from `session.md`, and the next step. Example: "{{PROJECT_NAME}}: last session left off building
+the signup flow, next step is wiring the email step. Ready."
+
+## Boundary rule
+
+- **Global memory** (`~/.kracked/`) — identity, cross-project preferences, cross-project lessons,
+  the project registry. Nothing about a specific codebase belongs here.
+- **Project memory** (`.kracked/`) — this codebase's stack, conventions, session state, decisions,
+  and SDD tracker. Nothing here should be copied up into global memory.
+- Putting project-specific detail into global memory poisons every other project that shares it.
+  If you're unsure which layer something belongs in, ask: "would this make sense in a totally
+  different project?" If no, it's project memory.
+
+## Available commands
+
+| Command | Does |
+|---|---|
+| `/kracked-boot` | Runs the boot sequence above and orients in one line |
+| `/kracked-sdd` | Runs the SDD flow: idea → spec → docs → build → review |
+| `/kracked-wrap` | Writes lessons + updates session state, closes the session cleanly |
+| `/kracked-explain` | Walks {{USER_NAME}} through what kracked-core installed and why |
+
+## Writing memory (wrap)
+
+When a session ends (`/kracked-wrap`), update `.kracked/session.md` with the new "Last Active"
+state and next step. If something non-obvious was learned that would help a future session avoid
+the same mistake, append a full entry to `~/.kracked/lessons-archive.md` and add exactly ONE line
+to `~/.kracked/lessons.md`. Never paste a full lesson entry into the index — that's the mistake
+this split exists to prevent.
+
+## Terminology
+
+Use these words, consistently: **global memory**, **project memory**, **boot**, **wrap**, **SDD**,
+**tracker**. Don't call this system "the core," "the brain," "context files," or "rules" — those
+terms don't appear anywhere else in this project's docs, and mixing terminology makes the memory
+model harder to reason about over time.

package/templates/loaders/CLAUDE.md

@@ -0,0 +1,5 @@
+@AGENTS.md
+
+This file is a shim. The canonical instructions live in `AGENTS.md` — duplicating them here would
+let the two drift apart, which is the exact bug kracked-core exists to prevent. If you need to
+change how the agent boots or behaves, edit `AGENTS.md`, not this file.

package/templates/loaders/antigravity-rules.md

@@ -0,0 +1,8 @@
+# Antigravity — {{PROJECT_NAME}}
+
+This file is a pointer, not the source of truth. The full instructions — who the agent is, the
+boot sequence, the boundary rule, and available commands — live in `AGENTS.md` at the project
+root. Read `AGENTS.md` and follow the boot sequence defined there before doing any work.
+
+Do not duplicate `AGENTS.md`'s content here. If these instructions ever disagree, `AGENTS.md`
+wins — update it there, not in this file.

package/templates/project/decisions.md

@@ -0,0 +1,34 @@
+# Decisions — {{PROJECT_NAME}}
+
+A log of decisions made on this project, with the reasoning behind them. The point of this file
+is the **why**, not the what — the code already shows what was decided; this file is for the
+reasoning a future session couldn't re-derive just by reading the code.
+
+Not every choice belongs here. Skip anything obvious or easily reversible. Log it when getting
+it wrong would mean redoing real work, or when a future session (human or agent) might look at
+the code and reasonably ask "why was it done this way?"
+
+## Format
+
+```
+## [YYYY-MM-DD] <short title>
+
+**Decision:** <what was decided>
+**Rationale:** <why, including what alternatives were considered and rejected>
+```
+
+## Log
+
+<!--
+Example:
+
+## [2026-01-10] Use Postgres instead of SQLite
+
+**Decision:** Store data in Postgres from day one, even though SQLite would be simpler for a
+solo project this size.
+**Rationale:** Planning to add a second concurrent writer (a background job) within a few weeks.
+SQLite's single-writer lock would force a migration later anyway, and doing it now while the
+schema is small is cheaper than doing it after there's real data.
+-->
+
+_(empty — add an entry the first time a non-obvious decision gets made)_

package/templates/project/project.md

@@ -0,0 +1,49 @@
+# Project — {{PROJECT_NAME}}
+
+What this project IS. This file is project memory — it never leaves `{{PROJECT_PATH}}`, and it
+never gets copied into global memory. If a fact only makes sense inside this codebase, it lives
+here.
+
+## Overview
+
+- **Name:** {{PROJECT_NAME}}
+- **Path:** {{PROJECT_PATH}}
+- **Stack:** {{STACK}}
+- **Created:** {{DATE}}
+
+_(Add a sentence or two here on what this project actually does, once there's something to say.)_
+
+## Conventions
+
+<!--
+Example:
+- Components live in src/components, one file per component, PascalCase.
+- API routes return { data, error } shape, never throw to the client.
+- Tests sit next to the file they test as *.test.ts.
+-->
+
+- _(not set yet)_
+
+## Structure
+
+<!--
+Example:
+- src/app       — routes
+- src/lib       — shared logic
+- src/components — UI
+-->
+
+- _(not set yet)_
+
+## How to run it
+
+<!--
+Detected at install time from this project's scripts. Correct anything that's wrong —
+editing this file directly is faster than explaining it to the agent every session.
+-->
+
+{{RUN_COMMANDS}}
+
+## How to test it
+
+- _(not set yet)_

package/templates/project/sdd/tracker.md

@@ -0,0 +1,36 @@
+# Tracker — {{PROJECT_NAME}}
+
+The story status ledger for this project's SDD flow (idea → spec → docs → build → review).
+Every story tracked here goes through the same four statuses, and status changes are never
+batched up and applied later — the moment a story's state actually changes, this table changes
+with it.
+
+## Statuses
+
+- `backlog` — written down, not started
+- `in-progress` — actively being built
+- `review` — built, being checked against the spec
+- `done` — reviewed and confirmed working
+
+## Rule: evidence before `done`
+
+A story **cannot** be marked `done` without an `Evidence` entry stating how it was confirmed
+(e.g. "manual test: signup flow works end-to-end", "3 unit tests passing", "verified in prod").
+No evidence, no `done` — it stays in `review` until there's something concrete to point at.
+
+## Spec
+
+_(no spec yet — run `/kracked-sdd` to create one)_
+
+## Stories
+
+| ID | Story | Status | Evidence |
+|---|---|---|---|
+| 1.1 | _(example)_ User can sign up with email | backlog | — |
+
+<!--
+ID format is <epic>.<story> — 1.1, 1.2, then 2.1 when the next epic starts.
+Add a row per story as specs are generated under sdd/specs/, and point the Spec heading above at
+the spec file this batch of stories came from. Keep the Story column short — the detail lives in
+the spec file. This is a ledger, not a spec.
+-->

package/templates/project/session.md

@@ -0,0 +1,23 @@
+# Session — {{PROJECT_NAME}}
+
+Working memory for this project. This is the file that makes a session restart survivable —
+{{AGENT_NAME}} reads it at boot and should be able to orient in one line without re-reading the
+whole codebase.
+
+## Last Active
+
+- **Date:** {{DATE}}
+- **State:** Project scaffolded, no work started yet.
+- **Doing now:** _(what the current task is)_
+- **Next step:** _(the very next action, specific enough to act on immediately)_
+- **Blockers:** none
+
+## Prior sessions
+
+<!--
+When you wrap a session, the current "Last Active" block moves down here (most recent first),
+and a new "Last Active" block is written above it. Keep roughly the last 2-3 blocks — older
+history that still matters belongs in decisions.md or the SDD tracker, not stacked up here.
+-->
+
+_(empty — this fills in as sessions wrap)_