kracked-core 1.0.0

package/templates/skills/kracked-boot/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: kracked-boot
+description: Use at the start of every session, before any other work, to load global and project memory and orient on what happened last and what's next.
+---
+
+Run this before doing anything else in the session. Do not skip steps or merge reads together.
+
+## 1. Check that memory exists
+
+Look for `~/.kracked/identity.md`. If it is missing, global memory has not been set up. Tell the
+user:
+
+> Global memory isn't set up yet. Run `npx kracked-core init` to create it, then re-run this.
+
+Stop here if memory doesn't exist. Do not fabricate identity, preferences, or project state.
+
+## 2. Load global memory, in this exact order
+
+Read each file individually — one `Read` call per file, not concatenated, not skimmed as a batch.
+Order matters: later files build on earlier ones.
+
+1. `~/.kracked/identity.md` — who you are, how you communicate
+2. `~/.kracked/preferences.md` — how the user likes to work
+3. `~/.kracked/lessons.md` — the INDEX, in full. Every line, every boot.
+4. `~/.kracked/projects.md` — registry of known projects
+
+**Never read `~/.kracked/lessons-archive.md` at boot.** It holds full lesson detail and grows
+without bound — loading it every session would make the boot payload heavier over time, which
+defeats the point of splitting index from archive. Only open it later, mid-task, if a specific
+line in `lessons.md` turns out to be relevant to what you're doing right now.
+
+## 3. Load project memory, in this exact order
+
+If the current directory has a `.kracked/` folder, read:
+
+1. `.kracked/project.md` — what this project is (stack, conventions)
+2. `.kracked/session.md` — working memory: state + next steps
+3. `.kracked/decisions.md` — why things are the way they are
+
+If there is no `.kracked/` folder here, this is a project that hasn't been set up yet. Say so
+plainly and suggest `npx kracked-core init` if the user wants project memory for it. Continue
+with global memory only — this is not a blocking error.
+
+## 4. Orient in one line
+
+After loading, produce exactly one line, no preamble, in this shape:
+
+> I'm {{AGENT_NAME}}. Last session: <what session.md says was done or in progress>. Next:
+> <what session.md says is next>. <Any active caution from lessons.md or decisions.md, if one
+> applies — omit this clause if there isn't one>.
+
+Do not repeat the full contents of the files you read. The user was there for the last session —
+they need the pointer back in, not a transcript.

package/templates/skills/kracked-explain/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: kracked-explain
+description: Use right after kracked-core init finishes, or when the user asks what kracked-core does or how memory works, to walk through what got installed in plain language.
+---
+
+Walk the user through what just got installed. Keep it conversational and short — this is likely
+their first five minutes with the tool. Don't lecture, don't dump the whole file tree at once.
+
+## 1. What got created, and where
+
+Explain in plain language, not a file listing dump:
+
+- **Global memory**, at `~/.kracked/` — this lives on the machine, not in any one project. It
+  holds who the agent is (`identity.md`), how the user likes to work (`preferences.md`), and
+  lessons learned across every project (`lessons.md` / `lessons-archive.md`), plus a registry of
+  known projects (`projects.md`).
+- **Project memory**, at `.kracked/` inside this repo — this is specific to this codebase: what
+  it is (`project.md`), what's being worked on right now (`session.md`), and why past decisions
+  were made (`decisions.md`).
+- **The loader files** — `AGENTS.md` is the one every harness reads; `CLAUDE.md` just points at
+  it (`@AGENTS.md`) so there's one source of truth instead of two files drifting apart.
+
+## 2. The boundary rule
+
+Teach it with a concrete wrong example, not just the rule stated abstractly:
+
+> The rule: global memory never contains anything specific to one project. Project memory never
+> contains anything about the user's general preferences or identity.
+>
+> Here's the mistake this prevents: say the agent learns "this project uses PostgreSQL with a
+> `snake_case` naming convention" and writes that into global `preferences.md` instead of this
+> project's `project.md`. Next week, in a completely different project that uses MongoDB, the
+> agent boots up carrying that PostgreSQL assumption with it — because global memory loads
+> everywhere. That's project detail leaking into global memory, and it poisons every other
+> project from then on.
+
+Keep the fix simple: project truth goes in `.kracked/`, everything that should follow the user
+everywhere goes in `~/.kracked/`.
+
+## 3. Why lessons split into an index and an archive
+
+Explain the reasoning, not just the mechanism:
+
+- `lessons.md` is read in full at every single boot, on every project. If every lesson's full
+  detail lived there, that file would grow every session and eventually the boot itself would get
+  slow and bloated just to load memory.
+- So `lessons.md` stays a short index — one line per lesson — and the full detail lives in
+  `lessons-archive.md`, which is only opened on demand when a specific lesson looks relevant to
+  what's being worked on right now.
+- This is the same reason project memory and global memory are split: keep what loads by default
+  small, keep the detail available but not mandatory.
+
+## 4. The three commands
+
+Introduce them as a cycle, with when to reach for each:
+
+- **`/kracked-boot`** — run this first, every session. Loads memory, orients on what happened
+  last and what's next.
+- **`/kracked-sdd`** — run this to build something. Right-sizes the work, then walks idea → spec
+  → docs → build → review depending on how big the task is.
+- **`/kracked-wrap`** — run this at the end of a session. Writes back anything worth remembering
+  before the context disappears.
+
+Boot at the start, wrap at the end, sdd for the work in between.
+
+## 5. Close
+
+End with the next concrete step: run `/kracked-boot` now to see it work. Don't add anything after
+that — let the student try it rather than reading more.

package/templates/skills/kracked-sdd/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: kracked-sdd
+description: Use when the user asks to build, add, or change a feature, to run the spec-driven flow from idea through spec, docs, build, and review.
+---
+
+Run the SDD (spec-driven) flow: idea → spec → docs → build → review. Right-size it first — most
+requests do not need the full flow.
+
+## 0. Resume check (do this before anything else)
+
+Read `.kracked/sdd/tracker.md` if it exists. If it lists a story that is not `done`, you are
+resuming mid-flow. Pick up at that story's current stage — do not restart the flow from idea, and
+do not re-ask questions already answered in its spec.
+
+## 1. Right-size the request FIRST
+
+Classify before doing any ceremony. Say the classification out loud in one line, then act on it.
+
+- **Trivial** — typo fix, one-line change, config tweak, renaming something. Skip straight to
+  build. No spec, no tracker entry. Say: "This is trivial — building it directly." Then build it.
+- **Small** — a single well-understood feature or fix with limited surface area. Light spec
+  (a few lines: what/why, acceptance criteria) → build → review. Skip the full docs breakdown if
+  there's only one story.
+- **Large or risky** — touches multiple areas, has unclear scope, affects data/migrations/auth,
+  or the user is unsure what they want. Full flow below, all five stages.
+
+Over-ceremony on a small task is a failure mode, not thoroughness. Do not write a spec file for a
+typo fix.
+
+## 2. Spec stage
+
+Write to `.kracked/sdd/specs/<short-name>.md`. Include:
+
+- **What** — the feature or change, in plain language
+- **Why** — the problem it solves, for whom
+- **Acceptance criteria** — concrete, checkable conditions for "this works"
+- **Out of scope** — explicitly list what this spec does NOT cover. This is not optional; scope
+  creep starts where this section is skipped.
+
+Confirm the spec with the user before moving on, unless the request was classified trivial/small
+and the spec is short enough that building it IS the confirmation.
+
+## 3. Docs stage
+
+Break the spec into stories. Each story must be independently shippable — a story that can't be
+merged and left in a working state on its own is too big; split it further.
+
+Add every story to `.kracked/sdd/tracker.md` with status `backlog`. Use this exact table shape —
+do not invent columns:
+
+```markdown
+| ID  | Story             | Status      | Evidence |
+|-----|-------------------|-------------|----------|
+| 1.1 | User can log in   | backlog     | —        |
+```
+
+- **ID** — `<epic>.<story>`, e.g. `1.1`, `1.2`, `2.1`
+- **Status** — one of exactly: `backlog` · `in-progress` · `review` · `done`
+- **Evidence** — `—` until the story reaches `done`. See the evidence gate below.
+
+Keep a `## Spec` line above the table pointing at the spec file this batch of stories came from.
+
+## 4. Build stage
+
+Implement against the spec, one story at a time.
+
+- The moment a story's status changes, update the tracker. Not at the end of the session, not
+  batched — the instant it moves (e.g. `backlog` → `in-progress` when you start it, `in-progress`
+  → `review` when the code is written).
+- Build against what the spec says, not what you assume it should say. If the spec is wrong or
+  something it references doesn't exist, stop and flag it — don't improvise around it.
+
+## 5. Review stage
+
+Two checks, both required, neither optional:
+
+1. **Correctness** — does the code do what the spec's acceptance criteria describe? Read it back
+   against the criteria, line by line.
+2. **Does it actually work** — run it, or trace through the actual execution path. Green tests are
+   not proof of a working feature; a test can pass while testing the wrong thing.
+
+### The evidence gate — the most important rule in this flow
+
+A story cannot move to `done` without a note stating:
+
+- What was verified (specifically — "ran X, saw Y", not "looks good")
+- What was NOT verified (be honest about the gaps — untested edge cases, unexercised code paths,
+  anything you didn't actually run)
+
+"Green tests" is not evidence on its own. If you didn't check it, the story is not `done` — leave
+it at `review` and say what's still open. A story marked `done` with no evidence note is worse
+than one left at `review`, because it hides risk instead of surfacing it.

package/templates/skills/kracked-wrap/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: kracked-wrap
+description: Use at the end of a session, or when the user says they're done for now, to write memory before context is lost and close the session cleanly.
+---
+
+Run this at the end of a session, before context is lost. Work through the steps in order.
+
+## 1. Decide if this session is worth logging
+
+Not every session needs a memory write. If nothing changed — pure discussion with no decisions,
+no code, no lesson — say so and skip the writes below. Logging a trivial session pollutes the
+signal for future boots, which makes the real lessons harder to find.
+
+If the session had meaningful work (code changed, a decision was made, or something was learned
+the hard way), continue.
+
+## 2. Check for a lesson
+
+Ask: did the agent get corrected, drift off track, or hit a trap that will recur? If yes, that's a
+lesson. If the session went smoothly with no correction needed, there is no lesson to log — do not
+invent one to fill the step.
+
+If there is a lesson:
+
+1. Append the FULL entry to `~/.kracked/lessons-archive.md` — what happened, what triggered it,
+   what the fix or avoidance is. Enough detail that a future session reading it cold understands
+   the trap without re-living it.
+2. Add exactly ONE line to `~/.kracked/lessons.md` — short enough to scan at boot, specific enough
+   to be useful, pointing at the archive entry.
+
+Never paste the full entry into the index file. The index stays scannable; the archive holds the
+detail.
+
+## 3. Update project session state
+
+Write `.kracked/session.md` with:
+
+- Current state — what's actually true right now, not a history of how you got there
+- Next steps — what to pick up next session
+
+Keep this file to current state, not a running log. If it's grown into a chronicle of every past
+session, trim it back to what's still relevant before writing the new entry — session.md is
+working memory, not an archive.
+
+## 4. Update decisions, if one was made
+
+If a non-obvious decision was made this session (a tradeoff chosen for a reason that wouldn't be
+obvious from the code alone), add it to `.kracked/decisions.md`. Skip this if nothing decision-
+worthy happened — not every session needs a decisions entry.
+
+## 5. Never write secrets
+
+Before writing anything, check it for API keys, tokens, passwords, connection strings, or other
+credentials. None of that belongs in any memory file, archive or otherwise. If a lesson or
+decision references a secret, describe it generically ("the deploy token" not the token itself).
+
+## 6. Close
+
+Confirm to the user, in one or two lines, what was written and where — not a restatement of the
+whole session.