# agent-kit

> A minimal harness for agent-driven development with Claude Code: an npx CLI (npx @razcue/agent-kit init) that sets up a project from fixed questions, and a plugin (/plugin install agent-kit --marketplace razcue/agent-kit) with skills, hooks, living specs, QA and scoped knowledge. MCP server for these docs: https://razcue-agent-kit.vercel.app/mcp

## Resources for Agents

- [API catalog: every service document this site publishes](https://razcue.github.io/agent-kit/.well-known/api-catalog)
- [Sitemap (XML)](https://razcue.github.io/agent-kit/sitemap.xml)
- [Sitemap (Markdown): every page on the site](https://razcue.github.io/agent-kit/sitemap.md)
- [MCP server card: MCP endpoint at https://razcue.github.io/agent-kit/mcp](https://razcue.github.io/agent-kit/.well-known/mcp/server-card.json)
- [MCP endpoint (streamable HTTP)](https://razcue.github.io/agent-kit/mcp)
- [llms.txt: index of the documentation for LLMs](https://razcue.github.io/agent-kit/llms.txt)
- [llms-full.txt: the full documentation as a single file](https://razcue.github.io/agent-kit/llms-full.txt)
- [OpenAPI document: every route this site serves to agents](https://razcue.github.io/agent-kit/openapi.json)

Every page on this site is available as raw markdown: append `.md` to its
URL or send `Accept: text/markdown`.


<u-page-hero :ui="{"title":"text-4xl sm:text-5xl lg:text-[3.4rem] lg:leading-[1.1]"}" orientation="horizontal">
<template v-slot:headline="">
<repo-stats>



</repo-stats>
</template>

<template v-slot:title="">

Answer a few questions. Get a project your agent <span className="text-primary">

understands

</span>

.

</template>

<template v-slot:description="">

agent-kit sets up a project for agent-driven development with Claude Code: rules enforced by hooks instead of prose, a small context loaded every session, work that resumes where it stopped, living specs traced to tests, and a QA checklist that follows the specs.

</template>

<template v-slot:links="">
<u-button to="https://razcue.github.io/agent-kit/en/getting-started/installation" size="xl" trailing-icon="i-lucide-arrow-right">

Get started

</u-button>

<u-button to="https://github.com/razcue/agent-kit" color="neutral" size="xl" variant="outline" icon="i-simple-icons-github">

View on GitHub

</u-button>
</template>

<terminal-demo :lines="[{"t":"cmd","text":"npx @razcue/agent-kit init shop"},{"t":"q","text":"Setup","a":"New app monorepo"},{"t":"q","text":"Technical level","a":"Technical"},{"t":"q","text":"Development method","a":"SDD + TDD"},{"t":"q","text":"Git flow for the agent","a":"Branches + pull requests"},{"t":"q","text":"QA checklist · Supabase test data","a":"Yes · Yes"},{"t":"gap"},{"t":"ok","text":"apps/web · apps/app · apps/docs · packages/ui · packages/shared"},{"t":"ok","text":"AGENTS.md · agent-kit.json · .claude/settings.json"},{"t":"ok","text":".knowledge/ · work/specs/ · work/qa/ · supabase/test-data/"},{"t":"ok","text":"plugin agent-kit@agent-kit enabled"},{"t":"gap"},{"t":"out","text":"Next: cd shop && npm install && claude"}]" replay="Replay" title="~/shop">



</terminal-demo>
</u-page-hero>

<u-page-section>
<template v-slot:title="">

Less context, more work

</template>

<template v-slot:description="">

What the agent reads before your first question, measured with `agent-kit context`.

</template>

<context-meter :with="3631" :without="22974" saved-label="less context every session" source="Both measured with agent-kit context, including the same personal ~/CLAUDE.md. agent-kit's own session context is about 1,300 tokens; doctor fails a project above 8,000." with-label="A new agent-kit monorepo, everything included" without-label="A real production project, rules in AGENTS.md + memory">



</context-meter>

<compare-rows :rows="[{"topic":"Rules","without":"A line in AGENTS.md the agent may forget or ignore.","with":"Hooks and checks — the git guard blocks what your git flow forbids, live-tested every release."},{"topic":"New session","without":"You explain again where you were and what was next.","with":"It starts with the last checkpoint and each piece of work's next task."},{"topic":"Requirements","without":"Scattered across chats and tickets; nobody knows the current truth.","with":"Living specs — EARS requirements with Given / When / Then scenarios, ids never reused."},{"topic":"Proof","without":"“Looks done.”","with":"Every scenario traced to a test or a check; preflight blocks a change that isn't."},{"topic":"Scripts","without":"Rewritten in /tmp every time, lost the next day.","with":"Searched first, kept with a header and a test, run with a compact result."},{"topic":"QA","without":"Clicking around from memory.","with":"A checklist generated from the living specs, dated runs, seed / purge test data."},{"topic":"Setup","without":"Hand-written AGENTS.md, settings, hooks and conventions.","with":"One command, about ten questions, nothing inferred."}]" with-title="With agent-kit" without-title="On your own">



</compare-rows>
</u-page-section>

<u-page-section orientation="horizontal">
<template v-slot:title="">

Rules that are enforced, not requested

</template>

<template v-slot:description="">

"Never commit on main" in a Markdown file is a suggestion. agent-kit's git guard reads your git flow and blocks the command before it runs — even through `bash -c`, `eval` and aliases — and tells the agent what to do instead.

</template>

<template v-slot:links="">
<u-button to="https://razcue.github.io/agent-kit/en/concepts/guardrails" color="neutral" trailing-icon="i-lucide-arrow-right" variant="outline">

Guardrails

</u-button>
</template>

<terminal-demo :lines="[{"t":"cmd","text":"git commit -m \"feat: add invoices\""},{"t":"err","text":"[agent-kit git-guard] Git flow is branches + pull requests:"},{"t":"out","text":"  don't `git commit` on main. Create a feature branch first"},{"t":"out","text":"  (`git switch -c feat/<name>`)."},{"t":"gap"},{"t":"cmd","text":"git switch -c feat/invoices"},{"t":"ok","text":"Switched to a new branch 'feat/invoices'"}]" replay="Replay" title="agent · shop (main)">



</terminal-demo>
</u-page-section>

<u-page-section>
<template v-slot:title="">

Living specs that merge, not rot

</template>

<template v-slot:description="">

A change carries a delta. When it is verified, one command merges it into the living spec: the new requirement lands, the removed one is retired for good, and its scenario is already proven by a test and listed for QA.

</template>

<spec-merge delta-label="Change 004 — delta spec" qa-label="QA checklist" retired-label="retired" spec-label="Living spec" test-label="Test">



</spec-merge>
</u-page-section>

<u-page-section>
<template v-slot:title="">

How it works

</template>

<template v-slot:features="">
<u-page-feature icon="i-lucide-list-checks" to="https://razcue.github.io/agent-kit/en/getting-started/installation">
<template v-slot:title="">

Answer fixed questions

</template>

<template v-slot:description="">

Setup kind, technical level, language, method (SDD or SDD + TDD), commits, git flow, QA. Nothing is inferred.

</template>
</u-page-feature>

<u-page-feature icon="i-lucide-layers" to="https://razcue.github.io/agent-kit/en/getting-started/project-layout">
<template v-slot:title="">

Get the agent layer

</template>

<template v-slot:description="">

A short AGENTS.md block, agent-kit.json, enforced settings, knowledge, work files, scripts — and the plugin with its skills and hooks.

</template>
</u-page-feature>

<u-page-feature icon="i-lucide-route" to="https://razcue.github.io/agent-kit/en/concepts/lanes-and-methods">
<template v-slot:title="">

Work in lanes

</template>

<template v-slot:description="">

Answer, fast-track or spec. Complex work becomes a change with EARS requirements and Given/When/Then scenarios that merge into the living specs.

</template>
</u-page-feature>
</template>
</u-page-section>

<u-page-section>
<template v-slot:title="">

What you get

</template>

<template v-slot:features="">
<u-page-feature icon="i-lucide-book-open-check" to="https://razcue.github.io/agent-kit/en/concepts/living-specs">
<template v-slot:title="">

Living specs, one notation

</template>

<template v-slot:description="">

EARS requirements, Given/When/Then scenarios as acceptance tests, ZOMBIES to pick the cases — merged by a script, ids never reused.

</template>
</u-page-feature>

<u-page-feature icon="i-lucide-clipboard-check" to="https://razcue.github.io/agent-kit/en/concepts/qa-and-test-data">
<template v-slot:title="">

QA that follows the specs

</template>

<template v-slot:description="">

A checklist generated from the living specs, dated QA runs, and Supabase test data that refuses to run on production.

</template>
</u-page-feature>

<u-page-feature icon="i-lucide-sparkles" to="https://razcue.github.io/agent-kit/en/reference/skills">
<template v-slot:title="">

Skills loaded only when needed

</template>

<template v-slot:description="">

Eleven plugin skills plus one stack skill per template; descriptions are tested to trigger on real requests and stay quiet otherwise.

</template>
</u-page-feature>

<u-page-feature icon="i-lucide-shield" to="https://razcue.github.io/agent-kit/en/concepts/guardrails">
<template v-slot:title="">

Guardrails that are enforced

</template>

<template v-slot:description="">

Git guard, preflight before a merge, commit checks, a stray-script reminder — silent outside agent-kit projects.

</template>
</u-page-feature>

<u-page-feature icon="i-lucide-brain" to="https://razcue.github.io/agent-kit/en/concepts/knowledge">
<template v-slot:title="">

Knowledge that stays cheap

</template>

<template v-slot:description="">

One concept per file, only one-line summaries load; project, machine and global scopes.

</template>
</u-page-feature>

<u-page-feature icon="i-lucide-bot" to="https://razcue.github.io/agent-kit/en/guides/docs-for-agents">
<template v-slot:title="">

Docs for agents too

</template>

<template v-slot:description="">

llms.txt, llms-full.txt and an MCP server, so your agent can read these docs while it works.

</template>
</u-page-feature>
</template>
</u-page-section>

<u-page-c-t-a :links="[{"label":"Read the installation guide","to":"/en/getting-started/installation","trailingIcon":"i-lucide-arrow-right"},{"label":"Adopt an existing project","to":"/en/guides/adopt-existing-project","color":"neutral","variant":"outline"}]" description="Node ≥ 20.11 and Claude Code. No runtime dependencies are added to your project." title="Start with one command" variant="subtle">

```bash [Terminal]
npx @razcue/agent-kit init my-project
```

</u-page-c-t-a>

## Resources for Agents

- [API catalog: every service document this site publishes](https://razcue.github.io/agent-kit/.well-known/api-catalog)
- [Sitemap (XML)](https://razcue.github.io/agent-kit/sitemap.xml)
- [Sitemap (Markdown): every page on the site](https://razcue.github.io/agent-kit/sitemap.md)
- [MCP server card: MCP endpoint at https://razcue.github.io/agent-kit/mcp](https://razcue.github.io/agent-kit/.well-known/mcp/server-card.json)
- [MCP endpoint (streamable HTTP)](https://razcue.github.io/agent-kit/mcp)
- [llms.txt: index of the documentation for LLMs](https://razcue.github.io/agent-kit/llms.txt)
- [llms-full.txt: the full documentation as a single file](https://razcue.github.io/agent-kit/llms-full.txt)
- [OpenAPI document: every route this site serves to agents](https://razcue.github.io/agent-kit/openapi.json)


# Guardrails

> Hooks and checks that enforce the rules instead of asking for them.

Four hooks and a few scripts do the checking. They are silent outside agent-kit projects and take about 70–100 ms each. Full list in [Hooks](https://razcue.github.io/agent-kit/en/reference/hooks).

## Git guard

A `PreToolUse(Bash)` hook applies the git flow you chose, even through `bash -c`, `eval`, `$( )` and git aliases:

<table>
<thead>
  <tr>
    <th>
      Flow
    </th>
    
    <th>
      The agent may
    </th>
    
    <th>
      Blocked
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <strong>
        Read-only
      </strong>
    </td>
    
    <td>
      read (<code>
        status
      </code>
      
      , <code>
        diff
      </code>
      
      , <code>
        log
      </code>
      
      , …)
    </td>
    
    <td>
      every git write — the agent hands you the exact command
    </td>
  </tr>
  
  <tr>
    <td>
      <strong>
        Branches + PRs
      </strong>
    </td>
    
    <td>
      commit on a feature branch
    </td>
    
    <td>
      commits / pushes on the main branch
    </td>
  </tr>
  
  <tr>
    <td>
      <strong>
        Trunk
      </strong>
    </td>
    
    <td>
      commit on main
    </td>
    
    <td>
      —
    </td>
  </tr>
</tbody>
</table>

Every flow blocks force-push, `reset --hard`, `clean -f`, `branch -D` and `--no-verify`, and the guard validates `git commit -m` messages before they run. Permission rules in `.claude/settings.json` are the first layer; the hook is the backstop.

## Preflight

`agent-kit preflight [base]` (and the `preflight` skill) before a merge:

- **Violations (block)**: changed logic without a test (SDD + TDD), an edited committed migration, grants to the browser roles, possible secrets, undocumented kept scripts, done changes with uncovered scenarios or not merged into the living specs.
- **Report**: migrations to apply, new env vars, new dependencies.
- **Warnings**: debug leftovers, living-spec gaps, notation errors, a stale QA checklist, migrations without seed / purge changes.

## Commits

With Conventional Commits, `init` adds commitlint + husky. The `commit` skill runs preflight, writes the message, checks it with `agent-kit commit check` and commits within the git flow — or gives you the command in a read-only project. `agent-kit commit draft` groups changed files by suggested scope.

## Reviewer

A read-only `reviewer` agent reviews a diff against its change: every scenario's proof, the EARS requirements, the knowledge rules, and correctness bugs (scope checks, rounding, idempotent migrations).


# Knowledge

> Facts and decisions in small files, scoped to the project, the machine or every project — only summaries load.

One concept per Markdown file with a one-line `summary`, linked with `[[name]]`. Each folder has an `index.md` and a `log.md` (added / changed / removed entries) — the Open Knowledge Format layout. Only the summaries are injected at session start; agents open files on demand or search.

## Scopes

<table>
<thead>
  <tr>
    <th>
      Scope
    </th>
    
    <th>
      Lives in
    </th>
    
    <th>
      Shared through
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        business
      </code>
      
       · <code>
        env
      </code>
      
       · <code>
        decisions
      </code>
      
       · <code>
        ux
      </code>
      
       · <code>
        stack
      </code>
    </td>
    
    <td>
      <code>
        .knowledge/
      </code>
      
       in the project
    </td>
    
    <td>
      the project repo
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        local
      </code>
    </td>
    
    <td>
      <code>
        .knowledge/local/
      </code>
    </td>
    
    <td>
      nobody (gitignored)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        stack
      </code>
      
       · <code>
        meta
      </code>
      
       · <code>
        ux
      </code>
      
       (global)
    </td>
    
    <td>
      <code>
        plugin/knowledge/
      </code>
      
       in the kit
    </td>
    
    <td>
      every project using the plugin
    </td>
  </tr>
</tbody>
</table>

Global knowledge is writable only from a kit clone registered with `agent-kit setup`; otherwise agents read the copy bundled with the plugin and write to the project.

## Entry

```markdown [.knowledge/business/money-three-decimals.md]
---
name: money-three-decimals
title: Money uses 3 decimals
type: rule
status: active
tags: [money]
summary: All money values use 3 decimals — display, inputs, rounding and DB columns.
---

Why, examples, links to [[other-entries]].
```

Types: `concept`, `rule`, `decision`, `howto`, `reference`. Status: `active`, `proposed`, `superseded`, `deprecated`.

## Skills and tools

- `knowledge` skill — read and write entries in the right scope (search first, never near-duplicates).
- `decide` skill — decisions with context, options and consequences; superseded instead of deleted; only you set `active`.
- `agent-kit knowledge find <words> [--body]`, `index`, `check`, `paths`.


# Lanes and methods

> Every request goes through one of three lanes; the method decides how much proof a change needs.

The agent names the lane before it starts, so you can redirect early.

<table>
<thead>
  <tr>
    <th>
      Lane
    </th>
    
    <th>
      When
    </th>
    
    <th>
      What happens
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <strong>
        Answer
      </strong>
    </td>
    
    <td>
      Questions, exploration
    </td>
    
    <td>
      Read-only.
    </td>
  </tr>
  
  <tr>
    <td>
      <strong>
        Fast-track
      </strong>
      
       (<code>
        feature
      </code>
      
       skill)
    </td>
    
    <td>
      ≤ 3 files and no schema, permission or money change
    </td>
    
    <td>
      A feature file in <code>
        work/features/
      </code>
      
       with tasks and evidence; a behaviour change also edits its living spec.
    </td>
  </tr>
  
  <tr>
    <td>
      <strong>
        Spec
      </strong>
      
       (<code>
        spec
      </code>
      
       skill)
    </td>
    
    <td>
      Everything bigger or riskier
    </td>
    
    <td>
      A <a href="https://razcue.github.io/agent-kit/en/concepts/living-specs">
        change
      </a>
      
      : proposal + delta specs → your approval → plan → tasks → implement → verify every scenario → merge into the living specs.
    </td>
  </tr>
</tbody>
</table>

Fast-track work that grows past the threshold moves to the spec lane. Ticking a task always needs evidence: the command run and its result.

## Methods

Chosen at setup (`methodology` in `agent-kit.json`):

<table>
<thead>
  <tr>
    <th>
      Method
    </th>
    
    <th>
      What it requires
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <strong>
        SDD
      </strong>
    </td>
    
    <td>
      Every scenario is proven by a test or a reproducible check; tests are written where logic warrants them.
    </td>
  </tr>
  
  <tr>
    <td>
      <strong>
        SDD + TDD
      </strong>
    </td>
    
    <td>
      A failing test before every behaviour change (<code>
        tdd
      </code>
      
       skill: red → green → refactor, cases chosen with ZOMBIES). <code>
        agent-kit tdd status
      </code>
      
       lists changed logic without tests and preflight blocks it.
    </td>
  </tr>
</tbody>
</table>

Paths in `testIgnore` (thin route handlers, for example) are exempt from the TDD check.


# Living specs and changes

> Spec-anchored SDD — living specs are the source of truth, changes carry deltas that merge into them.

agent-kit's SDD is **spec-anchored**: specs are not throw-away planning documents, they stay true for as long as the code lives.

## Living specs

`work/specs/<capability>/spec.md` says how one area of the system behaves **now**. A capability is an area users recognise — `auth`, `invoices`, `user-roles` — not a page or a table.

```markdown [work/specs/auth/spec.md]
---
capability: auth
retired: [auth.R1]
---

# Auth

## Purpose
Who can sign in and how.

## Requirements

### auth.R2 — Session restore
While a session is stored, the app shall restore it on reload.

#### auth.R2.S1 — Reload keeps the user signed in @simple
- Given a signed-in user
- When the page reloads
- Then the user is still signed in
```

The session context lists the capabilities (one line); the agent reads a capability's spec before changing its behaviour. The notation is described in [Notation](https://razcue.github.io/agent-kit/en/concepts/notation).

## Changes

Complex work is a **change** in `work/changes/NNN-slug/`, created with `agent-kit work new change <slug>`:

<table>
<thead>
  <tr>
    <th>
      File
    </th>
    
    <th>
      What
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        proposal.md
      </code>
    </td>
    
    <td>
      Why, what changes (in / out), capabilities touched, open questions. The first artifact you approve.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        specs/<capability>.md
      </code>
    </td>
    
    <td>
      Delta spec: <code>
        ## ADDED
      </code>
      
      , <code>
        ## MODIFIED
      </code>
      
       (the whole block as it must read after) and <code>
        ## REMOVED Requirements
      </code>
      
       (with a reason).
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        plan.md
      </code>
    </td>
    
    <td>
      Files, schema / RPC changes, decisions, risks.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        tasks.md
      </code>
    </td>
    
    <td>
      Ordered tasks tagged with the scenario ids they cover, evidence under each, and a verification table.
    </td>
  </tr>
</tbody>
</table>

## Merge

When the change is verified, `agent-kit specs merge NNN`:

- applies every delta of the change **all or nothing** — it refuses and names the conflict when a MODIFIED or REMOVED requirement is missing, or an ADDED id is taken or retired;
- retires removed requirement ids and scenarios left out of a MODIFIED block (they are never reused, so old tests, QA runs and fixtures can't point at the wrong behaviour);
- marks the proposal `merged: <date>` and refreshes the QA checklist.

The change folder stays as the record of why the behaviour changed.

## Ids

`agent-kit specs next <capability>` hands out the next requirement id; `agent-kit specs next <capability>.R<n>` the next scenario id. Both count living, retired and pending-delta ids, so two open changes don't collide.

## Tools

<table>
<thead>
  <tr>
    <th>
      Command
    </th>
    
    <th>
      Does
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        agent-kit specs lint [cap|NNN]
      </code>
    </td>
    
    <td>
      Checks the notation and the ids (exit 1 on errors).
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        agent-kit specs list
      </code>
    </td>
    
    <td>
      Capabilities with requirement and scenario counts.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        agent-kit specs trace [NNN|cap]
      </code>
    </td>
    
    <td>
      Scenario → tests or ✅ checks.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        agent-kit work status
      </code>
      
       / <code>
        board
      </code>
    </td>
    
    <td>
      Active work and its next task.
    </td>
  </tr>
</tbody>
</table>


# Notation

> One standard notation at every step — EARS requirements, Given/When/Then scenarios, ZOMBIES tags, scenario ids in test names.

<table>
<thead>
  <tr>
    <th>
      Step
    </th>
    
    <th>
      Standard
    </th>
    
    <th>
      Looks like
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Why and scope
    </td>
    
    <td>
      Proposal
    </td>
    
    <td>
      <code>
        work/changes/004-invoices/proposal.md
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Requirement
    </td>
    
    <td>
      <strong>
        EARS
      </strong>
    </td>
    
    <td>
      <code>
        ### invoices.R2 — Totals
      </code>
      
       + <code>
        When an invoice is saved, the BFF shall round its total to 3 decimals.
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Acceptance
    </td>
    
    <td>
      <strong>
        BDD / ATDD
      </strong>
    </td>
    
    <td>
      <code>
        #### invoices.R2.S3 — Rounding edge @boundary
      </code>
      
       + Given / When / Then
    </td>
  </tr>
  
  <tr>
    <td>
      Choosing cases
    </td>
    
    <td>
      <strong>
        ZOMBIES
      </strong>
    </td>
    
    <td>
      one tag per scenario
    </td>
  </tr>
  
  <tr>
    <td>
      Tests
    </td>
    
    <td>
      Traceability
    </td>
    
    <td>
      <code>
        it("invoices.R2.S3 rounds 0.0005 up")
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Test data
    </td>
    
    <td>
      ZOMBIES on data
    </td>
    
    <td>
      <code>
        -- @fixture invoices.R2.S3 @boundary
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      QA
    </td>
    
    <td>
      Checklist
    </td>
    
    <td>
      one item per scenario
    </td>
  </tr>
</tbody>
</table>

## EARS requirements

EARS (Easy Approach to Requirements Syntax) limits each requirement to one sentence in one of these shapes:

<table>
<thead>
  <tr>
    <th>
      Pattern
    </th>
    
    <th>
      Template
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Ubiquitous
    </td>
    
    <td>
      The <code>
        <system>
      </code>
      
       shall <code>
        <response>
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      Event
    </td>
    
    <td>
      When <code>
        <trigger>
      </code>
      
      , the <code>
        <system>
      </code>
      
       shall <code>
        <response>
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      State
    </td>
    
    <td>
      While <code>
        <state>
      </code>
      
      , the <code>
        <system>
      </code>
      
       shall <code>
        <response>
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      Unwanted
    </td>
    
    <td>
      If <code>
        <condition>
      </code>
      
      , then the <code>
        <system>
      </code>
      
       shall <code>
        <response>
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      Optional
    </td>
    
    <td>
      Where <code>
        <feature>
      </code>
      
      , the <code>
        <system>
      </code>
      
       shall <code>
        <response>
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      Complex
    </td>
    
    <td>
      While <code>
        <state>
      </code>
      
      , when <code>
        <trigger>
      </code>
      
      , the <code>
        <system>
      </code>
      
       shall <code>
        <response>
      </code>
      
      .
    </td>
  </tr>
</tbody>
</table>

Name a concrete system ("the BFF", "the invoices page"), one behaviour per requirement, and measurable outcomes (`within 15 minutes`, `answers 409`). `agent-kit specs lint` rejects any other shape.

## Scenarios (BDD / ATDD)

Each requirement has scenarios written as examples — `Given` a context, `When` an action, `Then` an observable outcome (`And` / `But` extend a step). They are agreed before code and are the **acceptance tests**.

## ZOMBIES

Pick the scenarios (and the test cases) with ZOMBIES and tag each scenario with the one category it covers:

<table>
<thead>
  <tr>
    <th>
      Tag
    </th>
    
    <th>
      Ask
    </th>
    
    <th>
      Example
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        @zero
      </code>
    </td>
    
    <td>
      nothing / empty
    </td>
    
    <td>
      no invoices → empty state
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @one
      </code>
    </td>
    
    <td>
      the single basic case
    </td>
    
    <td>
      one line totals correctly
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @many
      </code>
    </td>
    
    <td>
      several, order, duplicates
    </td>
    
    <td>
      three lines in two currencies
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @boundary
      </code>
    </td>
    
    <td>
      limits and edges
    </td>
    
    <td>
      the 5th failed login blocks; last day of a period
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @interface
      </code>
    </td>
    
    <td>
      the contract
    </td>
    
    <td>
      403 for another provincia; API shape
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @exception
      </code>
    </td>
    
    <td>
      bad input, failure
    </td>
    
    <td>
      invalid code → clear error, nothing saved
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @simple
      </code>
    </td>
    
    <td>
      the happy path
    </td>
    
    <td>
      create and see it in the list
    </td>
  </tr>
</tbody>
</table>

Lint warns when a requirement has no `@exception` or `@boundary` scenario. Money, permissions and data rules always get them.

## Traceability

A test that proves a scenario **starts its name with the scenario id**:

```ts
it("auth.R2.S2 shows the login page for an expired session", () => { /* … */ })
```

A scenario proven without a test (a visual check, a manual flow, an SQL check) gets a ✅ row in the change's `tasks.md`:

```markdown
| auth.R2.S2 | manual: reloaded with an expired token, login shown | ✅ |
```

`agent-kit specs trace` and `agent-kit work trace NNN` list `✗ not covered` scenarios; preflight blocks a done change with any.


# QA and test data

> A QA checklist generated from the living specs, dated QA runs, and Supabase test data that can't touch production.

Both parts are optional, asked at setup (default on) and changeable by re-running `init` (`--qa-checklist`, `--test-data`).

## QA checklist

`work/qa/checklist.md` is **generated** from the living specs — never edited by hand:

- one item per scenario, grouped by capability and requirement;
- the EARS sentence, the Given / When / Then steps, the ZOMBIES tag;
- the test-data fixture that provides the scenario's data (or "no fixture").

`agent-kit qa sync` regenerates it (and `checklist.html`); `agent-kit specs merge` runs it for you.

## QA runs

A QA pass is a dated file in `work/qa/runs/`:

```bash [Terminal]
npx @razcue/agent-kit qa run --env staging
```

Fill **Result** (`pass` · `fail` · `blocked` · `n/a`) and **Note** for each scenario. Or open `work/qa/checklist.html` in a browser, record results there (kept in the browser) and **Export run** to save the same file.

`agent-kit qa status` shows the latest result per scenario. Each run stores the scenario's text hash, so a scenario that changed after it passed shows **re-check**, and one never tested shows **never run**.

## Test data (Supabase)

Supabase projects get `supabase/test-data/` (path and prefix configurable):

<table>
<thead>
  <tr>
    <th>
      File
    </th>
    
    <th>
      What
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        env.sql
      </code>
    </td>
    
    <td>
      Creates <code>
        public._env
      </code>
      
       — which environment a database is. Run it in <strong>
        every
      </strong>
      
       environment and set the value once.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        seed.sql
      </code>
    </td>
    
    <td>
      Creates the test data through the app's RPCs. One transaction.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        purge.sql
      </code>
    </td>
    
    <td>
      Deletes only the test rows, children first. One transaction.
    </td>
  </tr>
</tbody>
</table>

Rules the scripts and the stack skill enforce:

- **The _env guard first.** Both scripts refuse unless `_env` says `dev`, `test` or `staging` — no row or `production` means no change.
- **Marked rows only.** Every row starts with the prefix (`TEST_`); purge matches with `starts_with()`, never `LIKE`.
- **Through the RPCs**, so balances, stock and audit rows stay consistent.
- **Relative dates** (`current_date - 30`).
- **Fixtures per scenario, chosen with ZOMBIES**: `-- @fixture invoices.R2.S3 @boundary`. `agent-kit qa gaps` lists scenarios without a fixture and fixtures naming unknown scenarios.

Preflight warns when migrations change and neither seed nor purge does. See the [test data guide](https://razcue.github.io/agent-kit/en/guides/test-data) for applying them.


# Scripts

> A registry so agents search, keep, document and test scripts instead of rewriting them.

The `scripts` skill runs every time an agent is about to write a script:

1. **Necessity** — one command, `grep`, an existing CLI or a `package.json` script is enough → no script.
2. **Search** — `agent-kit scripts find <words>` searches project scripts, scratch, the global library **and skills**.
3. **Build** — throwaway: `scripts new <area>/<name>.mjs --scratch` (in `.agent-kit/scratch/`, gitignored, still searchable); kept: `scripts new <area>/<name>.<ext> --summary "…"` (header + test stub + index).
4. **Document** — `@summary`, `@usage`, `@tags`, `@test` header; `scripts/README.md` is generated.
5. **Test** — a ZOMBIES test next to the script.
6. **Run** — `agent-kit scripts run <name>` returns the exit code and only the relevant lines; the full log stays in `.agent-kit/runs/`.

A scratch script needed a second time is promoted to `scripts/<area>/`; one useful across projects goes to the kit's global library. Preflight blocks kept scripts without a header, and a hook reminds the agent when a script is written where it would be lost (`/tmp`, the project root).


# How the kit improves

> From projects to the kit and back — retros, proposals, the weekly scout, releases.

Nothing changes without you: every step is a proposal you approve.

## From your project

- The `retro` skill gathers evidence (`agent-kit usage --days 30`, `agent-kit context`, git log, your corrections) and turns repeated corrections into knowledge, checks, hooks or promoted scripts.
- An improvement any project would benefit from becomes a proposal to the kit:

```bash [Terminal]
npx @razcue/agent-kit propose "Warn when a migration has no rollback note" --kind hook --body "problem, proposal, evidence"
```

`agent-kit propose` writes into the kit clone's `work/proposals/` (when registered with `agent-kit setup`) or prints a ready `gh issue create` command.

## From the ecosystem

`node scripts/evolve/scout.mjs` compares a reviewed baseline with new Claude Code versions, new hook events and template dependencies a major behind. A weekly cloud routine (`scripts/evolve/ROUTINE.md`, created with `/schedule`) adds web research on skills, harnesses and workflows and writes at most five proposals. It never edits code or releases.

## Back to projects

Accepted proposals ship as a release. Projects update the plugin with `/plugin marketplace update agent-kit` and the project files with `agent-kit upgrade`.


# Session context

> What every session starts with, how work resumes, and how the context budget is kept.

The `SessionStart` hook injects, in about 1.3k tokens:

- the profile — voice for your technical level, reply language, git flow, method, stack;
- the lanes and one line about the living specs (capabilities and requirement counts) and the QA setup;
- **Resume** — where the last session stopped (branch, uncommitted files) and each active work item with its next task;
- the knowledge index (one line per entry) and the script index.

Claude Code caps hook context at 10,000 characters, so the hook renders under 9,500: when needed it collapses global knowledge groups, then the scripts list, then project groups, and clips summaries to 160 characters.

## Resume

A `Stop` hook writes `.agent-kit/checkpoint.json` after every turn. Keep `status` and the next open task of work files accurate — a new session picks them up automatically.

## Budget

`agent-kit context` measures what loads every session: the `CLAUDE.md` / `AGENTS.md` chain, skill listings, the session context, and skills Claude Code can't see. `--sections` ranks every heading by tokens. `agent-kit doctor` fails above `contextBudget` (default 8000 tokens). The [adopt guide](https://razcue.github.io/agent-kit/en/guides/adopt-existing-project) shows how to shrink a big `AGENTS.md`.

## Debugging hooks

Start Claude Code with `AGENT_KIT_HOOK_LOG=/tmp/agent-kit-hooks.log`: every agent-kit hook appends one line when it runs.


# Channels

> Where agent-kit is published — documentation, docs MCP server, Claude Code plugin, npm CLI — and how they fit together.

agent-kit is one project published through four channels. Each one points to the others, so you — or your agent — can start from any of them.

<table>
<thead>
  <tr>
    <th>
      Channel
    </th>
    
    <th>
      Where
    </th>
    
    <th>
      What it is for
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <strong>
        Documentation
      </strong>
    </td>
    
    <td>
      <a href="https://razcue.github.io/agent-kit/" rel="nofollow">
        https://razcue.github.io/agent-kit/
      </a>
    </td>
    
    <td>
      Everything, in English and Spanish: installation, concepts, guides, reference. Also <a href="https://razcue.github.io/agent-kit/llms.txt" rel="nofollow">
        <code>
          llms.txt
        </code>
      </a>
      
       and <a href="https://razcue.github.io/agent-kit/llms-full.txt" rel="nofollow">
        <code>
          llms-full.txt
        </code>
      </a>
      
       for agents.
    </td>
  </tr>
  
  <tr>
    <td>
      <strong>
        Docs for agents (MCP)
      </strong>
    </td>
    
    <td>
      <a href="https://razcue-agent-kit.vercel.app/mcp" rel="nofollow">
        https://razcue-agent-kit.vercel.app/mcp
      </a>
    </td>
    
    <td>
      The same documentation as an MCP server: <code>
        list-pages
      </code>
      
       and <code>
        get-page
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <strong>
        Claude Code plugin
      </strong>
    </td>
    
    <td>
      <code>
        /plugin install agent-kit --marketplace razcue/agent-kit
      </code>
    </td>
    
    <td>
      Skills, hooks, the reviewer agent and the scripts, from this repository's marketplace. Soon also in Anthropic's directory on claude.ai.
    </td>
  </tr>
  
  <tr>
    <td>
      <strong>
        npm CLI
      </strong>
    </td>
    
    <td>
      <code>
        npx @razcue/agent-kit init my-project
      </code>
    </td>
    
    <td>
      Asks the setup questions and writes the project; <code>
        upgrade
      </code>
      
      , <code>
        doctor
      </code>
      
      , <code>
        uninstall
      </code>
      
       and the other <a href="https://razcue.github.io/agent-kit/en/reference/cli">
        commands
      </a>
      
      .
    </td>
  </tr>
</tbody>
</table>

## How they fit together

<steps>

### The CLI sets a project up

`npx @razcue/agent-kit init` writes `agent-kit.json`, the managed block in `AGENTS.md`, and `.claude/settings.json`, which declares the marketplace and turns the plugin on. Its help and its final output name the documentation and the MCP server.

### Claude Code installs the plugin

Open Claude Code in the project and accept the plugin. To install it in another project by hand:

```text [Claude Code]
/plugin install agent-kit --marketplace razcue/agent-kit
```

### The plugin uses the CLI and the docs

The plugin's skills call the CLI pinned to the plugin's own version (for example `npx @razcue/agent-kit@0.14.1 upgrade`), and the plugin declares the docs MCP server as `agent-kit-docs`, so Claude can look up a page while it works.

### The docs describe all of them

This site documents every channel, and its reference pages are generated from the CLI and the plugin, so they can't drift.

</steps>

## Use the MCP server without the plugin

```bash [Terminal]
claude mcp add --transport http agent-kit-docs https://razcue-agent-kit.vercel.app/mcp
```

Any MCP client that speaks streamable HTTP works the same way. See [Docs for agents](https://razcue.github.io/agent-kit/en/guides/docs-for-agents).


# Installation

> Set up a new or existing project, install the plugin, and check the result.

## Requirements

- **Node.js ≥ 20.11** and npm.
- **Claude Code** (CLI, desktop app or IDE extension).
- Git is recommended: the git guard and preflight work on the repository.

## Set up a project

<steps>

### Run `init`

```bash [Terminal]
npx @razcue/agent-kit init my-project
```

In an existing repository, run it inside the folder: `cd my-repo && npx @razcue/agent-kit init`. Your `AGENTS.md` is kept and gets a managed block.

### Answer the questions

<table>
<thead>
  <tr>
    <th>
      Question
    </th>
    
    <th>
      Choices
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Setup
    </td>
    
    <td>
      <strong>
        New app monorepo
      </strong>
      
       (web + app + docs on Nuxt + Supabase) · <strong>
        New content site
      </strong>
      
       (one Nuxt site with Markdown pages) · <strong>
        Existing project
      </strong>
      
       (agent layer only) · <strong>
        Blank project
      </strong>
      
       (agent layer only, no template)
    </td>
  </tr>
  
  <tr>
    <td>
      Apps (monorepo)
    </td>
    
    <td>
      <code>
        web
      </code>
      
      , <code>
        app
      </code>
      
      , <code>
        docs
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Technical level
    </td>
    
    <td>
      Technical (concise developer language) · Non-technical (plain language; the agent makes technical decisions)
    </td>
  </tr>
  
  <tr>
    <td>
      Agent reply language
    </td>
    
    <td>
      English · Español
    </td>
  </tr>
  
  <tr>
    <td>
      Development method
    </td>
    
    <td>
      SDD + TDD (tests first, enforced) · SDD (every scenario verified by a test or a check)
    </td>
  </tr>
  
  <tr>
    <td>
      Commit messages
    </td>
    
    <td>
      Conventional Commits (commitlint + git hook) · Free-form
    </td>
  </tr>
  
  <tr>
    <td>
      Git flow for the agent
    </td>
    
    <td>
      Branches + pull requests · Trunk · Read-only (you run git yourself)
    </td>
  </tr>
  
  <tr>
    <td>
      Main (production) branch
    </td>
    
    <td>
      Detected from git — origin's HEAD, or the only <code>
        main
      </code>
      
       / <code>
        master
      </code>
      
       / <code>
        trunk
      </code>
      
       / <code>
        production
      </code>
      
       / <code>
        prod
      </code>
      
       branch; asked only when not sure (<code>
        --main <branch>
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      Stack conventions skill (existing / blank)
    </td>
    
    <td>
      None · Nuxt + Supabase · Nuxt Content site
    </td>
  </tr>
  
  <tr>
    <td>
      QA checklist
    </td>
    
    <td>
      Generated from the living specs in <code>
        work/qa/
      </code>
      
       (default yes)
    </td>
  </tr>
  
  <tr>
    <td>
      Supabase test data (Supabase projects)
    </td>
    
    <td>
      seed / purge scripts in <code>
        supabase/test-data/
      </code>
      
       (default yes)
    </td>
  </tr>
  
  <tr>
    <td>
      Supabase project ref (optional)
    </td>
    
    <td>
      Adds a read-only, project-scoped Supabase MCP server to <code>
        .mcp.json
      </code>
    </td>
  </tr>
</tbody>
</table>

`init` shows the plan and asks before writing. Every file it changes is backed up in `.agent-kit/backups/`.

### Open Claude Code in the project

```bash [Terminal]
cd my-project && npm install && claude
```

Trust the folder. `.claude/settings.json` declares the agent-kit marketplace and enables `agent-kit@agent-kit`, so Claude Code offers to install the plugin — accept. If it doesn't:

```text [Claude Code]
/plugin marketplace add razcue/agent-kit
/plugin install agent-kit@agent-kit
```

### Check the setup

```bash [Terminal]
npx @razcue/agent-kit doctor
```

`agent-kit doctor` checks the answers, the AGENTS.md block, the plugin, the knowledge and script indexes, the context budget and the stack skill. `--fix` regenerates everything that is generated (indexes, the work board, the QA checklist).

</steps>

## Non-interactive setup

Every question has a flag; `--yes` takes the defaults for the rest:

```bash [Terminal]
npx @razcue/agent-kit init shop --yes --kind monorepo --apps web,app,docs \
  --level technical --lang en --method sdd-tdd --commits conventional --git pr \
  --qa-checklist true --test-data true --test-prefix TEST_
```

All flags are listed in the [CLI reference](https://razcue.github.io/agent-kit/en/reference/cli#agent-kit-init).

## Change an answer later

Re-run `init` with the new value; it only touches the agent layer:

```bash [Terminal]
npx @razcue/agent-kit init --git read-only --yes
```

## Make global knowledge writable (kit maintainers)

Projects read the global knowledge bundled with the plugin. To write global entries from your machine, register a clone of the kit:

```bash [Terminal]
git clone https://github.com/razcue/agent-kit.git && cd agent-kit
npx @razcue/agent-kit setup
```

`agent-kit setup` writes `~/.config/agent-kit/config.json`; agents then save global knowledge and improvement proposals into that clone.


# Introduction

> What agent-kit is, what it is not, and the problems it solves.

agent-kit is a minimal harness for **agent-driven development with Claude Code**. It has two parts:

- **An npx CLI** (`npx @razcue/agent-kit`) that sets a project up from fixed questions and writes plain files: `agent-kit.json`, a managed block in `AGENTS.md`, `.claude/settings.json`, `.knowledge/`, `work/`, `scripts/` and, for new projects, a scaffold.
- **A Claude Code plugin** (`agent-kit@agent-kit`) with skills, hooks, a read-only reviewer agent and zero-dependency scripts. It is versioned and installed from this repository's marketplace.

## Why it exists

Agents read whatever you load into every session and forget everything else. Without a harness, projects drift into the same failures:

<table>
<thead>
  <tr>
    <th>
      Failure
    </th>
    
    <th>
      What agent-kit does
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      A huge <code>
        AGENTS.md
      </code>
      
       loaded every session
    </td>
    
    <td>
      A short managed block; procedures in skills (loaded on demand), facts in knowledge (only summaries load). <code>
        agent-kit context
      </code>
      
       measures the cost.
    </td>
  </tr>
  
  <tr>
    <td>
      Rules written as prose
    </td>
    
    <td>
      Hooks and checks: the git guard blocks git commands your flow forbids; preflight blocks unsafe merges.
    </td>
  </tr>
  
  <tr>
    <td>
      Helpers rebuilt every time
    </td>
    
    <td>
      A script registry: search before writing, keep and document what is reused.
    </td>
  </tr>
  
  <tr>
    <td>
      Sessions that forget
    </td>
    
    <td>
      A checkpoint after every turn and a "resume" section at the start of the next session.
    </td>
  </tr>
  
  <tr>
    <td>
      Specs that rot
    </td>
    
    <td>
      Living specs per capability, changed only through approved changes, with every scenario traced to a test.
    </td>
  </tr>
  
  <tr>
    <td>
      Manual QA from memory
    </td>
    
    <td>
      A QA checklist generated from the living specs and test data that grows with them.
    </td>
  </tr>
</tbody>
</table>

## Principles

- **Profile, not inference.** Your technical level, language, method and git flow are answered once; nothing is guessed from the code.
- **Enforce, don't request.** Anything a machine can check becomes a hook, a script or a permission rule.
- **Small context.** Every skill, rule and knowledge entry must earn the tokens it costs per session.
- **No runtime dependencies.** The CLI and plugin scripts use Node built-ins only (Node ≥ 20.11).
- **Claude Code only.** The kit uses Claude Code's plugins, skills, hooks and settings directly.

## Next

- [Install it](https://razcue.github.io/agent-kit/en/getting-started/installation) in a new or existing project.
- Read how [lanes and methods](https://razcue.github.io/agent-kit/en/concepts/lanes-and-methods) shape every request.


# Project layout

> Every file and folder agent-kit adds to a project, and what each one is for.

## The agent layer (every project)

<table>
<thead>
  <tr>
    <th>
      Path
    </th>
    
    <th>
      What
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        agent-kit.json
      </code>
    </td>
    
    <td>
      The setup answers (<a href="https://razcue.github.io/agent-kit/en/reference/configuration">
        every field
      </a>
      
      ). Change them by re-running <code>
        init
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        AGENTS.md
      </code>
      
       + <code>
        CLAUDE.md
      </code>
    </td>
    
    <td>
      Short project rules plus a managed agent-kit block; <code>
        CLAUDE.md
      </code>
      
       imports <code>
        @AGENTS.md
      </code>
      
      . Keep it under 300 lines.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        .claude/settings.json
      </code>
    </td>
    
    <td>
      Plugin enabled from its marketplace + git permission rules for your flow (your own rules are kept).
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        .claude/skills/stack-*
      </code>
    </td>
    
    <td>
      The stack conventions skill of your template (refreshed by <code>
        upgrade
      </code>
      
      ).
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        .knowledge/
      </code>
    </td>
    
    <td>
      Project knowledge: <code>
        business
      </code>
      
      , <code>
        env
      </code>
      
      , <code>
        decisions
      </code>
      
      , <code>
        ux
      </code>
      
      , <code>
        stack
      </code>
      
      , and <code>
        local
      </code>
      
       (gitignored). See <a href="https://razcue.github.io/agent-kit/en/concepts/knowledge">
        Knowledge
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        work/
      </code>
    </td>
    
    <td>
      Specs, changes, features, QA — see below.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        scripts/
      </code>
    </td>
    
    <td>
      Kept, documented scripts; <code>
        scripts/README.md
      </code>
      
       is a generated index.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        .agent-kit/
      </code>
    </td>
    
    <td>
      Gitignored machine state: <code>
        scratch/
      </code>
      
       throwaway scripts (still searchable), <code>
        runs/
      </code>
      
       full logs, <code>
        backups/
      </code>
      
      , the checkpoint.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        commitlint.config.mjs
      </code>
      
      , <code>
        .husky/commit-msg
      </code>
    </td>
    
    <td>
      Commit message checks (Conventional Commits only).
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        .mcp.json
      </code>
    </td>
    
    <td>
      Read-only Supabase MCP server, when you gave a project ref.
    </td>
  </tr>
</tbody>
</table>

## `work/`

<table>
<thead>
  <tr>
    <th>
      Path
    </th>
    
    <th>
      What
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        work/specs/<capability>/spec.md
      </code>
    </td>
    
    <td>
      <strong>
        Living specs
      </strong>
      
      : how the system behaves now. The source of truth.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        work/changes/NNN-slug/
      </code>
    </td>
    
    <td>
      <strong>
        Changes
      </strong>
      
       from the spec lane: <code>
        proposal.md
      </code>
      
      , delta specs in <code>
        specs/<capability>.md
      </code>
      
      , <code>
        plan.md
      </code>
      
      , <code>
        tasks.md
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        work/features/NNN-slug.md
      </code>
    </td>
    
    <td>
      Fast-track work: goal, tasks, evidence.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        work/qa/
      </code>
    </td>
    
    <td>
      <code>
        checklist.md
      </code>
      
       and <code>
        checklist.html
      </code>
      
       (generated), <code>
        runs/
      </code>
      
       (QA passes).
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        work/BOARD.md
      </code>
    </td>
    
    <td>
      Generated overview of active work.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        work/README.md
      </code>
    </td>
    
    <td>
      A map of this folder (managed by the kit).
    </td>
  </tr>
</tbody>
</table>

## Templates

<table>
<thead>
  <tr>
    <th>
      Kind
    </th>
    
    <th>
      Adds
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      App monorepo
    </td>
    
    <td>
      <code>
        apps/web
      </code>
      
       (public site), <code>
        apps/app
      </code>
      
       (SPA + BFF + Supabase auth starter), <code>
        apps/docs
      </code>
      
       (Docus), <code>
        packages/ui
      </code>
      
       (shadcn-vue layer), <code>
        packages/shared
      </code>
      
       (Zod + utils), <code>
        supabase/migrations/
      </code>
      
      , <code>
        supabase/test-data/
      </code>
      
      , CI.
    </td>
  </tr>
  
  <tr>
    <td>
      Content site
    </td>
    
    <td>
      One Nuxt site: every Markdown file in <code>
        content/
      </code>
      
       is a page; colours in <code>
        app/assets/css/main.css
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      Existing / blank
    </td>
    
    <td>
      Only the agent layer (blank also gets a minimal <code>
        package.json
      </code>
      
      ).
    </td>
  </tr>
</tbody>
</table>

Details in [Templates](https://razcue.github.io/agent-kit/en/reference/templates).


# Upgrade and uninstall

> Keep a project on the latest kit, or remove the kit and keep your content.

A release reaches projects in two parts: the **plugin** (skills, hooks, scripts) and the **project files** (managed blocks, stack skill, new questions).

## Upgrade

<steps>

### Update the plugin

```text [Claude Code]
/plugin marketplace update agent-kit
```

### Update the project files

```bash [Terminal]
npx @razcue/agent-kit upgrade
```

`agent-kit upgrade` asks only the questions your project hasn't answered yet, re-applies the agent layer with your saved answers, backs up every file it changes and prints what's new since your project's `kitVersion`.

</steps>

<tip>

When the installed plugin is newer than the project's setup, the session suggests `agent-kit upgrade` once.

</tip>

### What an upgrade may move

- **0.13**: spec-lane folders moved from `work/specs/NNN-slug/` to `work/changes/NNN-slug/` (untouched; their `NNN/AC-n` test names keep working). `work/specs/` now holds living specs. The QA questions are asked.

## Uninstall

```bash [Terminal]
npx @razcue/agent-kit uninstall --dry-run   # see what would change
npx @razcue/agent-kit uninstall
```

`agent-kit uninstall` removes the managed `AGENTS.md` block, agent-kit's entries in `.claude/settings.json`, the stack skill and `agent-kit.json` — each backed up in `.agent-kit/backups/`. Your `.knowledge/`, `work/`, `scripts/` and commit tooling stay.


# Adopt an existing project

> Add the agent layer to a repository you already have, shrink its AGENTS.md and bootstrap living specs.

<steps>

### Add the agent layer

```bash [Terminal]
cd my-repo
npx @razcue/agent-kit init --kind existing
```

Your `AGENTS.md` is kept and gets a managed block at the end. Pick a stack skill if one fits (`--stack nuxt-supabase`).

### Measure

```bash [Terminal]
npx @razcue/agent-kit context --sections
```

`agent-kit context` shows the tokens loaded every session; `--sections` ranks each heading of the `CLAUDE.md` / `AGENTS.md` chain.

### Slim it down with the `adopt` skill

Ask Claude: *"Adopt agent-kit: slim our AGENTS.md"*. The skill classifies every section, shows you the table, then moves one section at a time:

<table>
<thead>
  <tr>
    <th>
      The section is…
    </th>
    
    <th>
      Goes to
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      An invariant for almost every task
    </td>
    
    <td>
      stays in <code>
        AGENTS.md
      </code>
      
       (≤ 15 lines)
    </td>
  </tr>
  
  <tr>
    <td>
      A procedure or pattern
    </td>
    
    <td>
      a project skill in <code>
        .claude/skills/
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Rules for one folder
    </td>
    
    <td>
      a <code>
        CLAUDE.md
      </code>
      
       in that folder
    </td>
  </tr>
  
  <tr>
    <td>
      A business fact or decision
    </td>
    
    <td>
      <code>
        .knowledge/
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Derivable or outdated
    </td>
    
    <td>
      deleted, after you confirm
    </td>
  </tr>
</tbody>
</table>

It re-measures after each move and suggests moving durable rules from Claude's auto-memory into `.knowledge/`.

### Bootstrap living specs

The skill proposes a capability list from routes, pages and RPCs; you trim it. Then, one capability at a time, it writes the spec of what the code does today and you confirm. A capability without a spec gets one the first time a change touches it.

</steps>


# Your website with Claude

> A quick guide for non-programmers — build and change a content site by talking to Claude.

This guide is for creating and changing a website by talking to Claude, without knowing how to program. Claude does the technical part; you decide what you want, how it looks and what it says.

## What you need (once)

1. **The Claude app** on your computer, with Claude Code.
2. **Your project, prepared.** Ask whoever helps you with the technical side to run:```bash [Terminal]
npx @razcue/agent-kit init my-site --kind site --level non-technical --lang en --git read-only
```

<br />

This creates a `my-site` folder with the site and sets Claude up to talk to you in plain language, without asking you technical decisions.
3. Open the `my-site` folder in Claude and accept when it asks whether you trust it and whether to install **agent-kit**.

## How to work

- **To start something new**, write: *"I want to start my site"* or *"I want to add a pricing page"*. Claude asks short questions (what it is, for whom, which pages, colours, texts) and shows you a summary before building anything.
- **For small changes**, just say it: *"Make the headings green"*, *"Put my phone number on the contact page"*.
- **To see the result**, Claude tells you what to type to open the preview and which address to open in the browser (usually `http://localhost:3000`).
- **If you don't like something**, say so: *"The title is too big"*, *"Go back to how it was"*.

## Your texts

Each page is a text file in the `content/` folder. Ask Claude to write or correct them, or edit them yourself: what you write is what appears on the page.

## What you can't break

- Claude **can't erase the project's history**: the important steps (saving versions, publishing) are done by the person who helps you with the technical side.
- Before anything hard to undo, Claude explains what will happen and asks.
- If you get lost, write: *"Where are we? What's left?"*. Claude remembers where you stopped last time.

## Publishing the site

When it's ready, ask your helper to publish it (for example on Vercel or Netlify). The site is generated with `npm run generate` and ends up in the `.output/public` folder.


# Docs for agents

> Let your agent read these docs — llms.txt, llms-full.txt and the MCP server.

## llms.txt

The site publishes [`/llms.txt`](https://razcue.github.io/agent-kit/llms.txt) (an index) and [`/llms-full.txt`](https://razcue.github.io/agent-kit/llms-full.txt) (every English page in one file), generated on each build.

## MCP server

The same documentation runs as a server on Vercel and exposes Docus's MCP server at **https://razcue-agent-kit.vercel.app/mcp** with two tools:

<table>
<thead>
  <tr>
    <th>
      Tool
    </th>
    
    <th>
      Does
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        list-pages
      </code>
    </td>
    
    <td>
      Every page with title, path and description (optional <code>
        locale
      </code>
      
      ).
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        get-page
      </code>
    </td>
    
    <td>
      The full Markdown of one page, e.g. <code>
        /en/concepts/notation
      </code>
      
      .
    </td>
  </tr>
</tbody>
</table>

Add it to Claude Code:

```bash [Terminal]
claude mcp add --transport http agent-kit-docs https://razcue-agent-kit.vercel.app/mcp
```

The agent-kit plugin already declares this server as `agent-kit-docs`, so with the plugin installed there is nothing to add.

The GitHub Pages site is static and has no `/mcp` endpoint.

### Deploying the MCP server (maintainers)

Import the repository in Vercel with **Root Directory** `site` (framework Nuxt, build `nuxt build`; `site/vercel.json` sets both). Set `NUXT_SITE_URL` to the deployment URL. Every push to `master` redeploys.


# A fast-track change

> Small changes with a feature file, evidence, and the living spec kept true.

Example: *"Rename the Sign out button on the home page to Log out."*

1. **Lane check** — ≤ 3 files, no schema, permission or money change. Otherwise the agent says so and uses the spec lane.
2. **Feature file** — `agent-kit work new feature rename-logout` creates `work/features/NNN-rename-logout.md` with the goal and tasks (skipped for a one-line edit).
3. **Do the work** — logic changes go test-first in SDD + TDD.
4. **Keep the living spec true** — if a living spec describes this behaviour (`home.R1 — Sign out`), the agent edits the requirement or scenario in place, runs `agent-kit specs lint home` and `agent-kit qa sync`. A new requirement or capability isn't fast-track.
5. **Evidence and finish** — each task ticked with the check run; project checks; `status: done`.


# New app monorepo

> From an empty folder to a Nuxt + Supabase monorepo with the agent layer, auth starter and first change.

<steps>

### Scaffold

```bash [Terminal]
npx @razcue/agent-kit init shop --kind monorepo --apps web,app,docs
cd shop && npm install
```

You get `apps/web` (public site, prerendered), `apps/app` (SPA + server routes + Supabase), `apps/docs` (Docus), `packages/ui` (shadcn-vue components, Tailwind v4 theme), `packages/shared` (Zod schemas and utils), `supabase/migrations/`, `supabase/test-data/` and a CI workflow.

### Connect Supabase

Create a Supabase project, copy `apps/app/.env.example` to `.env` with your URL and keys, and apply `supabase/migrations/` in order in the SQL Editor. The first migration locks the Data API to `service_role` and creates `_env`; set it on this database:

```sql [SQL Editor]
INSERT INTO public._env (name) VALUES ('dev') ON CONFLICT (id) DO UPDATE SET name = excluded.name;
```

With `--supabase-mcp <project-ref>` agents also get a read-only Supabase MCP server to check the live schema.

### Run the checks

```bash [Terminal]
npm run check         # typecheck + tests
npm run dev:app       # http://localhost:3001
```

### Start Claude Code

```bash [Terminal]
claude
```

Accept the plugin, then describe the first feature. A new module goes through the [spec lane](https://razcue.github.io/agent-kit/en/guides/spec-lane-change).

</steps>

## Conventions the agent follows

The `stack-nuxt-supabase` skill (in `.claude/skills/`) loads when the agent touches pages, server routes, migrations, RPCs or test data:

- the browser never reaches the database — all data goes through `apps/app/server/api/*` with the service-role client;
- writes go through RPCs (SECURITY DEFINER), after Zod validation;
- schemas are shared from `packages/shared`;
- migrations are append-only and idempotent;
- npm workspaces only.


# Proposing improvements

> Send what you learned in a project back to the kit.

```bash [Terminal]
npx @razcue/agent-kit propose "Skill X loads on unrelated questions" --kind skill --body "Problem, proposal, evidence (prompt, session)."
```

Kinds: `skill`, `hook`, `script`, `knowledge`, `template`, `cli`, `bug`. With a registered kit clone (`agent-kit setup`) the proposal lands in its `work/proposals/` inbox; otherwise `agent-kit propose` prints a ready `gh issue create` command for you to send. The `retro` skill proposes these for you when it finds an improvement every project would benefit from.


# A QA pass

> Test the whole product against the living specs and record the results.

<steps>

### Refresh the checklist

```bash [Terminal]
npx @razcue/agent-kit qa sync
```

### Prepare the data

On Supabase projects, reset the test data on the QA database: `purge.sql`, then `seed.sql` (see [Test data](https://razcue.github.io/agent-kit/en/guides/test-data)).

### Start a run

```bash [Terminal]
npx @razcue/agent-kit qa run --env staging
```

This creates `work/qa/runs/<today>.md` with every scenario unticked, grouped by capability. A second run the same day gets `-2`.

### Test and record

For each scenario, follow its Given / When / Then and write the **Result** (`pass`, `fail`, `blocked`, `n/a`) and a **Note**. Prefer the browser? Open `work/qa/checklist.html`, record there and **Export run** into `work/qa/runs/`.

### Review

```bash [Terminal]
npx @razcue/agent-kit qa status
```

Failures become fast-track fixes or changes. Scenarios marked **re-check** changed since they last passed; **never run** were never tested.

</steps>


# Releasing and upgrading

> Ship a kit release and bring projects up to date.

## Upgrading your projects

```text [Claude Code]
/plugin marketplace update agent-kit
```

```bash [Terminal]
npx @razcue/agent-kit upgrade
npx @razcue/agent-kit doctor
```

See [Upgrade and uninstall](https://razcue.github.io/agent-kit/en/getting-started/upgrade-uninstall) for what an upgrade may move.

## Releasing the kit (maintainers)

```bash [Terminal]
npm test                                  # unit + lint tests
node scripts/e2e/live.mjs                 # live smoke test in real Claude Code (~$0.01)
node scripts/e2e/triggers.mjs             # every skill triggers on its prompt (--model sonnet too)
node scripts/e2e/spec-flow.mjs            # spec and fast-track lanes end to end
node scripts/release/docs.mjs sync        # regenerate the reference pages
node scripts/release/docs.mjs check       # every page translated and current
node scripts/release/bump.mjs 0.14.0      # after adding "## 0.14.0" to CHANGELOG.md
npm publish --access public
```

Template changes are verified by scaffolding a project, `npm install`, then `npm run check` and `npm run build`. The website deploys from `site/` on every push to `master` and once a day, which refreshes the homepage's GitHub stars and forks. To also show clones (last 14 days), add a repository secret `TRAFFIC_TOKEN` with a token that has push access — GitHub's traffic API requires it.


# A change, end to end

> The spec lane step by step — proposal, delta specs, approval, test-first tasks, verification, merge.

Example: *"Add invoices with lines, totals rounded to 3 decimals, visible only to users of the invoice's provincia."*

<steps>

### Ground

The agent searches knowledge (`agent-kit knowledge find invoices`), lists the living specs (`agent-kit specs list`) and reads the code the change touches. Nothing is written yet.

### Proposal and delta specs

```bash [Terminal]
npx @razcue/agent-kit work new change invoices --title "Invoices module"
```

The agent fills `proposal.md` (why, in / out, capabilities, open questions) and one delta per capability, e.g. `specs/invoices.md`:

```markdown
## ADDED Requirements

### invoices.R2 — Rounded totals
When an invoice is saved, the BFF shall store each line amount and the total rounded half-up to 3 decimals.

#### invoices.R2.S3 — Rounding edge @boundary
- Given a line of quantity 1 at unit price 0.0005
- When the invoice is saved
- Then the line amount is 0.001
```

`agent-kit specs lint 001` must report no errors.

### You approve

The agent shows the requirements with their scenarios and the open questions, and stops. Your answers go into the proposal; it becomes `status: approved`.

### Plan and tasks

`plan.md` lists files, schema / RPC changes and risks. `tasks.md` tags every task with the scenario ids it covers; in SDD + TDD each scenario's test task comes before its implementation. On Supabase projects with test data on, a task extends seed and purge for the new scenarios.

### Implement

One task at a time, test first (`tdd` skill). A task is ticked only with evidence under it — the command and its result.

### Verify

Project checks and tests, the scenario → evidence table, `agent-kit work trace 001` with nothing uncovered, `agent-kit preflight`, and the reviewer agent for non-trivial diffs.

### Merge and close

```bash [Terminal]
npx @razcue/agent-kit specs merge 001
```

The deltas land in `work/specs/invoices/spec.md`, the QA checklist refreshes, the proposal is marked `status: done`. You commit under your git flow.

</steps>


# The TDD loop

> Red, green, refactor — one behaviour at a time, cases from the scenarios and ZOMBIES.

In SDD + TDD projects the `tdd` skill drives every behaviour change:

1. **List the cases** — the scenarios being implemented (each already tagged with a ZOMBIES category), then extra unit cases with ZOMBIES. Write the test names first, simplest first.
2. **Red** — write one test, run it, confirm it fails for the expected reason (the assertion, not an import error).
3. **Green** — the smallest change that passes.
4. **Refactor** — only on green, then run again.
5. **Next case.** A bug fix starts with a test that reproduces it.

```bash [Terminal]
npx @razcue/agent-kit tdd status        # changed logic files and their tests (✗ no test = to do)
npx @razcue/agent-kit tdd run           # only the tests related to your changes; --all for the suite
```

`agent-kit tdd run` prints the exit code and the failures; the full log goes to `.agent-kit/runs/`. Test names read as rules and start with the scenario id they prove. Never weaken, skip or delete a test to get to green.


# Test data

> Write fixtures per scenario, and seed or purge them safely on dev, test and staging databases.

## One-time setup per database

Run `supabase/test-data/env.sql` in **every** environment (the monorepo template has it in its first migration), then set the value:

```sql [SQL Editor]
INSERT INTO public._env (name) VALUES ('dev')      -- or 'test' / 'staging' / 'production'
ON CONFLICT (id) DO UPDATE SET name = excluded.name;
```

## Writing fixtures

When a change adds tables or RPCs, or its scenarios need data, its tasks include "extend seed + purge". Each fixture is a section tagged with its scenarios and ZOMBIES category:

```sql [supabase/test-data/seed.sql]
-- @fixture invoices.R2.S3 @boundary
SELECT public.create_invoice(p_codigo => 'TEST_INV_EDGE', p_fecha => current_date - 15, …);
```

<table>
<thead>
  <tr>
    <th>
      Tag
    </th>
    
    <th>
      Data to create
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        @zero
      </code>
    </td>
    
    <td>
      a parent with no children
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @one
      </code>
      
       / <code>
        @simple
      </code>
    </td>
    
    <td>
      one ordinary record per main entity
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @many
      </code>
    </td>
    
    <td>
      several records: lists, totals, ordering
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @boundary
      </code>
    </td>
    
    <td>
      limits, period edges, rounding edges
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @interface
      </code>
    </td>
    
    <td>
      one record per role / scope
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @exception
      </code>
    </td>
    
    <td>
      inactive, cancelled, invalid states
    </td>
  </tr>
</tbody>
</table>

Every table the seed writes to must be cleaned by `purge.sql`, children first. `agent-kit qa gaps` lists scenarios without fixtures and fixtures naming unknown scenarios.

## Applying

**SQL Editor (supported):** run `purge.sql`, then `seed.sql`, each as a whole file.

From a terminal — the agent shows the command and runs it only after you approve:

```bash [Terminal]
supabase db query --linked -f supabase/test-data/purge.sql   # --local or --db-url "<url>"
supabase db query --linked -f supabase/test-data/seed.sql
psql "$DATABASE_URL" -v ON_ERROR_STOP=1 -f supabase/test-data/seed.sql
```

<warning>

Never use `supabase db reset` to reset test data on a shared database: it rebuilds the whole database. `purge.sql` removes only the test rows.

</warning>


# Changelog

> What changed in every version.

## 0.14.3 — 2026-10-11

- **Git guard without download-like words**: the list of every git subcommand the guard recognises (with `pull` and `clone`) also moved to `git-rules.mjs`, and the guard's messages say "branches + PRs"; the directory validator still read `git-guard.mjs` as a download-and-execute pattern after `fetch` moved out. Behaviour unchanged: `git pull` and `git clone` are still blocked in read-only projects.
- **No "Ask AI" assistant on the docs**: Docus switches its assistant on whenever AI Gateway credentials exist, and Vercel always provides them (`VERCEL_OIDC_TOKEN`), so the Vercel deployment showed an "Ask AI" box that failed on every question. It is now explicitly off (`docus.assistant.enabled: false`); agents read the docs through the MCP server and `llms.txt`.

## 0.14.2 — 2026-10-11

- **Directory validation warnings cleared**: a 1024 × 1024 listing icon (`plugin/.claude-plugin/icon.png`, the razcue.github.io terminal icon); a Privacy page in the docs (EN + ES) linked as `privacyPolicyUrl`; the read-only git subcommand data moved from `git-guard.mjs` to `git-rules.mjs`, so the guard no longer reads as a download-and-execute pattern. The plugin README states that the environment only reaches local tools (git, commitlint, the project's tests). Two reviewer holds remain by design: Node hook scripts in a subfolder plugin, and local tools receiving the environment while the plugin also has a remote MCP server.

## 0.14.1 — 2026-10-11

- **Ready for Anthropic's plugin directory**: `plugin/README.md` (what each hook reads, runs and writes; no network, no data collected) and `plugin/LICENSE`; `plugin.json` gets `displayName`, `homepage`, `repository`, `license`, `keywords` and an up-to-date description (also in the marketplace entry).
- **Every channel points to the others** — documentation ([https://razcue.github.io/agent-kit/](https://razcue.github.io/agent-kit/)), docs MCP server ([https://razcue-agent-kit.vercel.app/mcp](https://razcue-agent-kit.vercel.app/mcp)), Claude Code plugin (`/plugin install agent-kit --marketplace razcue/agent-kit`) and npm CLI (`npx @razcue/agent-kit init`): one source of truth in `cli/lib/channels.mjs`; a "Channels" docs page (EN + ES); the plugin declares the MCP server as `agent-kit-docs` (`plugin/.mcp.json`; its README says what is sent: only the page path or locale); README, npm metadata (`homepage`, `bugs`, `keywords`), CLI help and `init` output name the docs and the MCP server; `llms.txt` names the MCP endpoint; the Pages root redirects to `/en/` or `/es/` by browser language (it returned 404).
- **Pinned launchers**: `.ts` scripts and vitest run with the project's own `node_modules/.bin` binaries, else `npx --yes tsx@4.23.15` / `vitest@5.0.3` — never a floating version. Every `npx @razcue/agent-kit@<version>` command inside the plugin carries the plugin's version, and `bump.mjs` re-pins them on release. The upgrade notice names the package and version instead of a launcher.

## 0.14.0 — 2026-10-11

- **Documentation website on Docus 5**: `site/` is now a Docus project (Nuxt 4 + Nuxt Content + Nuxt UI) in **English and Spanish** — landing, getting started, concepts, guides and reference: installation, every setup kind, upgrade, uninstall, lanes, living specs and notation, QA and test data, knowledge, scripts, guardrails, session context, self-improvement, and step-by-step workflows. Search, dark mode, `llms.txt` / `llms-full.txt` built in. The Spanish guide for non-technical users moved into the site, with an English version.
- **Reference generated from the source**: `scripts/release/docs.mjs sync` writes the CLI, configuration, skills, hooks, scripts and changelog pages; `docs.mjs check` (run by `npm test`) fails on stale generated pages, missing or stale translations (each Spanish page records its English page's hash; `docs.mjs stamp` after translating) and CLI commands not explained outside the reference.
- **Deploy**: GitHub Pages builds the static site (`npm run generate:pages` in `site/`, base path `/agent-kit/`); the same app on Vercel (`site/vercel.json`) serves Docus's MCP server at `/mcp` for agents. `scripts/release/site-base.mjs` adds the base path where Docus 5.14 leaves it out (`llms*.txt`, `sitemap.md`, favicon).
- Look of [https://razcue.github.io](https://razcue.github.io): its light / dark palette mapped onto Nuxt UI's tokens (`site/app/app.css`), its terminal icon as favicon and header logo; the footer keeps one GitHub link plus the author's website, the theme toggle stays in the header. The homepage shows GitHub stars and forks (live, with `stats.json` from `scripts/release/repo-stats.mjs` as fallback) and clones of the last 14 days when the `TRAFFIC_TOKEN` secret is set; the Pages site rebuilds daily.
- **Homepage**: an animated terminal hero (`init` typing itself), a measured comparison — about 23k tokens loaded every session by a real project vs about 3.6k by a new agent-kit monorepo (84% less, both from `agent-kit context`) — with rows comparing work with and without the kit, the git guard blocking a commit on main, and a delta merging into a living spec (requirement lands, old id retired, test and QA item shown). CSS animations that play once in view and stay still with reduced motion.
- **Main branch detected at setup**: `init` reads it from git (origin's HEAD, or the only main / master / trunk / production / prod branch) and asks when not sure; `upgrade` replaces a configured branch that doesn't exist. `init` / `upgrade` keep `agent-kit.json` fields they don't ask about (`testCommand`, `contextBudget`).
- The kit runs its own workflow: 001 and 002 converted to proposals + EARS / Given-When-Then delta specs and merged; living specs `specs`, `qa`, `setup`, `website`; every kit test that proves a scenario is named by its id; the kit's branch is `master` (Pages trigger, edit links).
- CLI help moved to `cli/lib/help.mjs`; the `--commits` flag is listed under `init`.

## 0.13.0 — 2026-10-10

- **Spec-anchored SDD with living specs**: `work/specs/<capability>/spec.md` is the source of truth for current behaviour. Spec-lane work is a **change** in `work/changes/NNN-slug/` — `proposal.md` (first artifact), delta specs `specs/<capability>.md` (ADDED / MODIFIED / REMOVED requirements), `plan.md`, `tasks.md`. `specs.mjs merge NNN` applies the deltas all or nothing, retires removed ids (never reused) and marks the proposal `merged:`. Fast-track edits the living spec in place.
- **One standard notation**: requirements in **EARS** (`### cap.R1 — name` + `When …, the <system> shall …`), **Given/When/Then** scenarios (BDD) as the acceptance tests (ATDD), one **ZOMBIES** tag each (`#### cap.R1.S1 — name @boundary`). `specs.mjs lint|next|merge|trace|list` (also `agent-kit specs …`); skill reference `spec/references/notation.md`; global knowledge `ears-requirements`, `gherkin-scenarios`.
- **Scenario traceability**: tests start their name with the scenario id; preflight blocks a done change with uncovered scenarios or not merged, warns on living-spec gaps and notation errors. Changes from ≤ 0.12 keep their `NNN/AC-n` traces.
- **QA dimension** (asked at setup, default on, change by re-running init): `work/qa/checklist.md` + offline `checklist.html` generated from the living specs (one item per scenario, its steps, ZOMBIES tag and fixture); dated QA runs (`qa.mjs run`), `qa.mjs status` with **re-check** when a scenario changed after passing; `qa.mjs gaps`. `specs.mjs merge` refreshes the checklist.
- **Supabase test data** (`--test-data`, Supabase projects only): `supabase/test-data/{env,seed,purge}.sql` + README — one transaction each, the `_env` guard first (refuses unless dev / test / staging; `_env` belongs in every environment and is in the monorepo init migration), rows marked with `qa.testPrefix` (`TEST_`), fixtures tagged `-- @fixture <ids> @<zombies>`. Applied in the SQL Editor; skills may offer `supabase db query --linked -f …` / psql and run it only after approval — never `db reset`. Preflight warns when migrations change without seed/purge changes. Stack skill reference `test-data.md`.
- **Upgrade**: `agent-kit upgrade` moves `work/specs/NNN-*` to `work/changes/`, asks the new QA questions, and refreshes `work/README.md`.
- E2E: `scripts/e2e/spec-flow.mjs --lane spec|feature` — a complex request opens a change with lint-clean deltas; a fast-track tweak keeps its living spec true.

## 0.12.0 — 2026-10-08

- **A stack skill per template, in the project only**: `stack-nuxt-supabase` moved out of the plugin and `stack-nuxt-content-site` is new; `init` installs the template's skill into `.claude/skills/`, so unrelated projects pay no tokens for it. `upgrade` refreshes it (backed up), `doctor` checks it's current, `uninstall` removes it.
- **Blank projects**: `--kind blank` (or "Blank project") — agent layer only, no template, with a minimal `package.json`; existing and blank projects can opt into a stack skill (`--stack none|nuxt-supabase|nuxt-content-site`).
- **agent-kit propose "<title>"**: projects send improvement ideas to the kit — into the clone's `work/proposals/` inbox, or as a ready `gh issue create` command; the `retro` skill uses it.
- **Evolve**: `scripts/evolve/scout.mjs` (new Claude Code version, new hook events in the docs, template dependencies a major behind, vs a reviewed baseline) and `scripts/evolve/ROUTINE.md` (weekly cloud routine: scout + web research on skills, harnesses and workflows → at most 5 proposals).
- Trigger eval covers both stack skills (each in its template's project).

## 0.11.0 — 2026-10-08

- **Session context budget**: rendered under 9,500 characters (Claude Code caps hook context at 10,000 and cuts the rest silently); when needed it collapses global knowledge groups, then the scripts list, then project groups, and clips summaries to 160 characters. `knowledge check` warns about longer summaries.
- **Template CI** (`.github/workflows/templates.yml`): scaffolds the app monorepo and the content site, installs, checks, builds, and runs the auth e2e — on template changes and weekly.
- **Site figures stay true**: `scripts/release/site.mjs` syncs the version and skill count into both languages and `llms.txt`; `bump.mjs` runs it; a test fails when the site is stale.

## 0.10.0 — 2026-10-08

- **Project website** (`site/`): single page in English and Spanish — problem, how it works, lanes and methods, the 12 skills, guardrails, knowledge, scaffolds, verification, get started; light/dark, mobile, copy buttons, `llms.txt`. Deployed to GitHub Pages by `.github/workflows/pages.yml`. Site test: links, anchors, assets, same sections in both languages.

## 0.9.0 — 2026-10-08

- **Auth e2e** `scripts/e2e/auth.mjs`: the built app server + real supabase-js against a fake Supabase (Auth + RPC) — wrong password 401, short login + email domain, `app_metadata` name, `/me`, server-side logout revocation, throttle 429 after 5 failures (9/9).
- **Git guard**: configured aliases are resolved (`git ci` → `git commit`, shell aliases too); inline `-c alias.…` is blocked; branch detection works in a fresh repo with no commits (a first commit onto main in `pr` flow was not caught).
- **Spanish guide for non-technical users**: `docs/guia-sitio-web.md`.

## 0.8.0 — 2026-10-08

- **Version-drift notice**: when the installed plugin is newer than the project's `kitVersion`, the session suggests `agent-kit upgrade` once.
- **Knowledge log.md** (OKF): every index run appends what was added, changed or removed, newest first.
- **agent-kit doctor --fix**: regenerates knowledge indexes (+ log), the scripts index and the work board, then checks.
- **Negative trigger evals**: unrelated questions must load no agent-kit skill — 3/3 on haiku and sonnet (no over-triggering).
- **Hook latency budget** in the lint tests (< 1.5 s each; measured 72–101 ms).

## 0.7.0 — 2026-10-08

- **Fix**: frontmatter values kept YAML inline comments (`status: draft # draft | approved…`), so work files created from the templates were never seen as active (resume, board, AC trace) and commented knowledge examples failed `check`.
- **Git guard hardening**: quote-aware command splitting; git hidden in `bash/sh -c`, `eval`, `xargs`, `$( )`, backticks, `nohup`, `timeout` is checked too.
- **work.mjs new feature|spec <slug>** (`agent-kit work new …`): next free number, files from the templates, board updated; `feature`, `spec` and `start` use it.
- **Skill trigger eval** `scripts/e2e/triggers.mjs`: one realistic prompt per skill in a scaffolded monorepo; descriptions of `feature`, `tdd`, `commit`, `adopt`, `stack-nuxt-supabase` rewritten to "Use BEFORE…" — 12/12 skills trigger on haiku and sonnet after the changes (borderline ones re-run twice per model).
- The kit adopts itself: `agent-kit.json`, a 48-line AGENTS.md for kit work, commitlint + husky, `.knowledge/`.

## 0.6.0 — 2026-10-08

- **Auth starter** in the app template: BFF `POST /api/auth/login` (DB-backed throttle per login and IP, migration `000000000001_login_throttle.sql`), `GET /api/auth/me`, `POST /api/auth/logout`; Pinia `useAuthStore` (session restore, setSession, logout), global route guard with safe redirects, login page; `Input`/`Label` in the UI layer.
- **agent-kit upgrade**: asks only questions the project hasn't answered, re-applies the agent layer, prints the CHANGELOG since the project's `kitVersion`.
- **agent-kit uninstall [--dry-run]**: removes the AGENTS.md block, agent-kit settings entries and `agent-kit.json` (backed up); project content stays.
- **Optional read-only Supabase MCP** (`--supabase-mcp <ref>`, asked for new app projects): hosted server, project-scoped, `read_only=true`; `doctor` flags a non-read-only one.
- Kit CI (Node 20 and 22: tests + pack check).

## 0.5.0 — 2026-10-08

- **commit skill**: preflight → review → Conventional Commit message (English, `type(scope): subject`, ≤ 72) → validate → commit by git flow (read-only projects get the exact command).
- **Setup question "Commit messages"** (`--commits conventional|none`, default conventional): adds `@commitlint/cli`, `@commitlint/config-conventional`, `husky` and a `prepare` script to package.json, `commitlint.config.mjs` and `.husky/commit-msg`; `npm install` activates the hook.
- **commit.mjs** (`agent-kit commit draft|check`): files → scope/type hints; message check via the project's commitlint, or built-in rules pinned to commitlint's verdicts by a parity test.
- **Git guard**: validates `git commit -m …` messages in conventional projects before they run; blocks `--no-verify` / `-n` everywhere.
- **doctor**: commitlint configured, hook file present, hooks active (`core.hooksPath`).
- `init` no longer backs up files it created earlier in the same run.

## 0.4.0 — 2026-10-08

- **Verified live in Claude Code** (2.1.294): `scripts/e2e/live.mjs` runs a headless session with `--plugin-dir` and a cheap model, and checks plugin + skills load, SessionStart context, git guard, stray-script reminder and checkpoint (~$0.01 per run).
- **Fix**: the Stop checkpoint hook is now synchronous — async hooks were dropped when a headless run exited (found by the live test).
- **adopt skill** + `agent-kit context --sections`: move a large AGENTS.md/CLAUDE.md and auto-memory onto agent-kit section by section (skill, folder CLAUDE.md, knowledge or delete), measuring tokens after each move.
- **Hook tracing**: `AGENT_KIT_HOOK_LOG=<file>` makes every hook append one line when it runs.
- **Plugin lint tests**: skill names/description budget, total listing ≤ 1500 tokens, hook commands exist, hooks silent outside agent-kit projects, versions agree.

## 0.3.0 — 2026-10-08

- **Resume across sessions**: Stop hook (async) saves `.agent-kit/checkpoint.json`; session start shows where the last session ended and the active work with its next task. `work.mjs status|board`.
- **Acceptance-criteria traceability**: tests name `NNN/AC-n`; `work.mjs trace`; preflight blocks a `done` spec with an uncovered AC, warns for `approved`.
- **Context report**: `agent-kit context` estimates the tokens loaded every session (CLAUDE.md chain + imports, memory, agent-kit context, skill listings) and lists skills Claude Code can't see; `doctor` checks the budget (`contextBudget`, default 8000).
- **Stray-script reminder**: PostToolUse(Write) hook points to the `scripts` skill when a script is written outside `scripts/`/scratch.
- **Content site**: `--kind site` scaffold (Nuxt + Nuxt Content, Markdown pages, static) and the `start` skill (guided kickoff in plain language).
- **Retro**: `retro` skill + `agent-kit usage` (runs, failures, unused scripts, scratch to promote, orphan knowledge).
- Also: `knowledge related <name>` (links + backlinks), `kitVersion` in agent-kit.json checked by `doctor`, backups of every file `init` changes, GitHub Actions `check` workflow in scaffolds, `agent-kit preflight|work|context|usage` commands.

## 0.2.0 — 2026-10-07

- Method question: SDD or SDD + TDD; `tdd` skill, `tdd.mjs status|run`, preflight blocks untested logic.
- `scripts` skill + `scripts.mjs` registry (find/run/test/new/index/check), ZOMBIES test stubs, `.agent-kit/scratch/`.

## 0.1.0 — 2026-10-07

- Plugin (spec, feature, knowledge, decide, stack-nuxt-supabase, preflight; reviewer agent; session + git-guard hooks), `init/setup/doctor` CLI, Nuxt + Supabase monorepo scaffold, global knowledge.


# CLI

> Every agent-kit command and flag.

Run with `npx @razcue/agent-kit <command>`.

## agent-kit init

Ask the setup questions and write the project (re-runnable).

```bash
agent-kit init [dir]
    --name <kebab>  --kind monorepo|site|existing|blank  --stack none|nuxt-supabase|nuxt-content-site  --apps web,app,docs
    --level technical|non-technical  --lang en|es  --method sdd-tdd|sdd  --commits conventional|none  --git pr|trunk|read-only
    --main <branch>  --marketplace github:<owner/repo>|<local path>  --yes (defaults, no prompts)
    --supabase-mcp <project-ref>   read-only Supabase MCP server in .mcp.json
    --qa-checklist true|false  --test-data true|false (Supabase only)  --test-prefix TEST_  --test-data-dir supabase/test-data
```

## agent-kit upgrade

New questions only + re-apply the agent layer + what's new.

```bash
agent-kit upgrade [dir] [--yes]
```

## agent-kit propose

Send an improvement idea to the kit.

```bash
agent-kit propose "<title>" [--kind skill|hook|…] [--body …]
```

## agent-kit uninstall

Remove what agent-kit added (backed up; your content stays).

```bash
agent-kit uninstall [dir] [--dry-run]
```

## agent-kit setup

Make global knowledge writable on this machine.

```bash
agent-kit setup [--home <agent-kit clone>]
```

## agent-kit doctor

Check a project's agent setup (--fix regenerates indexes and the board).

```bash
agent-kit doctor [dir] [--fix]
```

## agent-kit knowledge

Knowledge base tools.

```bash
agent-kit knowledge <paths|find|index|check> ...
```

## agent-kit scripts

Script registry.

```bash
agent-kit scripts <find|list|run|test|new|index|check> ...
```

## agent-kit tdd

TDD status and related-test runs.

```bash
agent-kit tdd <status|run> ...
```

## agent-kit work

Active work, board, scenario trace of a change.

```bash
agent-kit work <status|board|trace|new> ...
```

## agent-kit specs

Living specs: notation lint, next id, merge a change, trace.

```bash
agent-kit specs <lint|next|merge|trace|list> ...
```

## agent-kit qa

QA checklist from the living specs, QA runs, test-data fixture gaps.

```bash
agent-kit qa <sync|run|status|gaps> ...
```

## agent-kit preflight

Pre-merge checklist (exit 1 = block).

```bash
agent-kit preflight [base]
```

## agent-kit context

Tokens loaded every session + invisible skills.

```bash
agent-kit context [dir] [--budget N]
```

## agent-kit usage

Usage signals for a retro.

```bash
agent-kit usage [--days N]
```

## agent-kit commit

Conventional Commit helpers.

```bash
agent-kit commit draft [--staged] | check "<message>"
```


# Configuration

> Every field of agent-kit.json.

`agent-kit.json` holds the setup answers. Change them by re-running `agent-kit init`.

<table>
<thead>
  <tr>
    <th>
      Field
    </th>
    
    <th>
      What
    </th>
    
    <th>
      Default
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        name
      </code>
    </td>
    
    <td>
      Project name (kebab-case).
    </td>
    
    <td>
      folder name
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        kind
      </code>
    </td>
    
    <td>
      Setup kind: what <code>
        init
      </code>
      
       scaffolded.<br />
      
      <code>
        monorepo
      </code>
      
       — web + app + docs scaffold on Nuxt + Supabase<br />
      
      <code>
        site
      </code>
      
       — one simple Nuxt site with Markdown pages — easiest<br />
      
      <code>
        existing
      </code>
      
       — add the agent layer to this folder's code<br />
      
      <code>
        blank
      </code>
      
       — agent layer only, no template — start from nothing
    </td>
    
    <td>
      asked
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        apps
      </code>
    </td>
    
    <td>
      Monorepo apps (<code>
        web
      </code>
      
      , <code>
        app
      </code>
      
      , <code>
        docs
      </code>
      
      ); empty for other kinds.<br />
      
      <code>
        web
      </code>
      
       — public website (Nuxt, prerendered)<br />
      
      <code>
        app
      </code>
      
       — main solution (Nuxt SPA + BFF + Supabase)<br />
      
      <code>
        docs
      </code>
      
       — help / wiki site (Docus)
    </td>
    
    <td>
      <code>
        web,app,docs
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        stack
      </code>
    </td>
    
    <td>
      Stack conventions skill installed in <code>
        .claude/skills/
      </code>
      
      .<br />
      
      <code>
        none
      </code>
      
       — no stack conventions skill<br />
      
      <code>
        nuxt-supabase
      </code>
      
       — stack-nuxt-supabase skill (pages, BFF routes, migrations, RPCs)<br />
      
      <code>
        nuxt-content-site
      </code>
      
       — stack-nuxt-content-site skill (Markdown pages, styling, build)
    </td>
    
    <td>
      from the kind
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        technicalLevel
      </code>
    </td>
    
    <td>
      How the agent talks to you.<br />
      
      <code>
        technical
      </code>
      
       — concise developer language<br />
      
      <code>
        non-technical
      </code>
      
       — plain language; the agent makes technical decisions
    </td>
    
    <td>
      <code>
        technical
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        language
      </code>
    </td>
    
    <td>
      Agent reply language.<br />
      
      <code>
        en
      </code>
      
       — English<br />
      
      <code>
        es
      </code>
      
       — Español
    </td>
    
    <td>
      <code>
        en
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        methodology
      </code>
    </td>
    
    <td>
      SDD, or SDD + TDD (tests first, enforced by preflight).<br />
      
      <code>
        sdd-tdd
      </code>
      
       — spec first, then tests before code; preflight blocks untested logic<br />
      
      <code>
        sdd
      </code>
      
       — spec first; every scenario verified by a test or a check
    </td>
    
    <td>
      <code>
        sdd-tdd
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        commitConvention
      </code>
    </td>
    
    <td>
      Conventional Commits checked by commitlint, or free-form.<br />
      
      <code>
        conventional
      </code>
      
       — type(scope): subject — checked by commitlint and a git hook<br />
      
      <code>
        none
      </code>
      
       — no message checks
    </td>
    
    <td>
      <code>
        conventional
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        gitFlow
      </code>
    </td>
    
    <td>
      What the agent may do with git (enforced by a hook).<br />
      
      <code>
        pr
      </code>
      
       — agent never commits or pushes on main<br />
      
      <code>
        trunk
      </code>
      
       — commits on main; no force-push or hard reset<br />
      
      <code>
        read-only
      </code>
      
       — agent never changes git; you run git yourself
    </td>
    
    <td>
      <code>
        pr
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        mainBranch
      </code>
    </td>
    
    <td>
      The main (production) branch: detected from git at setup (origin's HEAD, or the only main / master / trunk / production / prod branch), asked when not sure; <code>
        upgrade
      </code>
      
       re-checks that it exists. Preflight compares against it; the git guard protects it.
    </td>
    
    <td>
      detected, else <code>
        main
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        testIgnore
      </code>
    </td>
    
    <td>
      Paths without unit tests (thin route handlers).
    </td>
    
    <td>
      <code>
        apps/*/server/api/
      </code>
      
       in the monorepo
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        testCommand
      </code>
    </td>
    
    <td>
      Command that runs the tests, when not the default.
    </td>
    
    <td>
      —
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        contextBudget
      </code>
    </td>
    
    <td>
      Tokens per session above which <code>
        doctor
      </code>
      
       fails.
    </td>
    
    <td>
      <code>
        8000
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        supabaseMcp
      </code>
    </td>
    
    <td>
      Supabase project ref for the read-only MCP server in <code>
        .mcp.json
      </code>
      
      .
    </td>
    
    <td>
      —
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        qa.checklist
      </code>
    </td>
    
    <td>
      Generate <code>
        work/qa/checklist.md
      </code>
      
       from the living specs.
    </td>
    
    <td>
      <code>
        true
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        qa.testData
      </code>
    </td>
    
    <td>
      Supabase seed / purge scripts (Supabase projects only).
    </td>
    
    <td>
      <code>
        true
      </code>
      
       on Supabase
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        qa.testPrefix
      </code>
    </td>
    
    <td>
      Marker every test row starts with.
    </td>
    
    <td>
      <code>
        TEST_
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        qa.testDataDir
      </code>
    </td>
    
    <td>
      Where the test-data scripts live.
    </td>
    
    <td>
      <code>
        supabase/test-data
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        kitVersion
      </code>
    </td>
    
    <td>
      Kit version that last wrote the setup (drives the upgrade notice).
    </td>
    
    <td>
      written by init
    </td>
  </tr>
</tbody>
</table>


# Hooks

> The plugin hooks and what they enforce.

Hooks are silent outside agent-kit projects and never block on their own errors.

<table>
<thead>
  <tr>
    <th>
      Event
    </th>
    
    <th>
      Matcher
    </th>
    
    <th>
      Script
    </th>
    
    <th>
      What it does
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        SessionStart
      </code>
    </td>
    
    <td>
      —
    </td>
    
    <td>
      <code>
        session-start.mjs
      </code>
    </td>
    
    <td>
      SessionStart hook: injects the project profile (voice, language, git flow, method, work lanes), a compact knowledge index and the script index. Silent outside agent-kit projects.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        PreToolUse
      </code>
    </td>
    
    <td>
      <code>
        Bash
      </code>
    </td>
    
    <td>
      <code>
        git-guard.mjs
      </code>
    </td>
    
    <td>
      PreToolUse(Bash) hook: blocks git commands the project's git flow forbids. Exit 2 blocks the call and shows stderr to Claude. Silent outside agent-kit projects.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        PostToolUse
      </code>
    </td>
    
    <td>
      <code>
        Write
      </code>
    </td>
    
    <td>
      <code>
        script-nudge.mjs
      </code>
    </td>
    
    <td>
      PostToolUse(Write) hook: when the agent writes a script somewhere it will be lost (outside the project, at the project root, or in a tmp folder), remind it of the <code>
        scripts
      </code>
      
       skill so the script is found and reused next time.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        Stop
      </code>
    </td>
    
    <td>
      —
    </td>
    
    <td>
      <code>
        checkpoint.mjs
      </code>
    </td>
    
    <td>
      Stop hook: after every turn (sync: async hooks are dropped when a headless run exits), saves where the work stands so the next session can resume — branch, changed files, active work. Silent; never fails.
    </td>
  </tr>
</tbody>
</table>


# Privacy

> What agent-kit's plugin, CLI, documentation site and docs MCP server collect and send — in short, nothing about you or your project.

*Last updated: 11 October 2026.*

agent-kit has no accounts, no analytics and no telemetry. Its author doesn't collect, store or sell personal data. This page covers each channel: the Claude Code plugin, the npm CLI, this documentation site and the docs MCP server.

## The Claude Code plugin

- **Runs on your machine.** Its hooks and scripts read your project's files, run read-only `git` commands, and write only inside the project (`.agent-kit/`, `work/`, `.knowledge/`, `scripts/`).
- **Your environment stays local.** Scripts pass your environment variables only to the local tools they start — `git`, commitlint, your project's tests — and never send them anywhere.
- **The docs MCP server** (`agent-kit-docs`) is the plugin's only remote service. When Claude calls its tools (`list-pages`, `get-page`), the request carries the page path or the locale being looked up. It never carries project files, code or conversation content.
- **Package downloads.** When a project has no `tsx` or `vitest` of its own and you run a TypeScript script or its tests, `npx` downloads those exact versions from the npm registry.

## The npm CLI

`npx @razcue/agent-kit` is downloaded from the npm registry (operated by GitHub, under the [GitHub General Privacy Statement](https://docs.github.com/en/site-policy/privacy-policies/github-general-privacy-statement)). It runs locally, writes only the project folder you give it, and sends nothing anywhere.

## This documentation site

- **Hosting.** The site is served by GitHub Pages; GitHub may log visits (such as IP address and browser) under the [GitHub General Privacy Statement](https://docs.github.com/en/site-policy/privacy-policies/github-general-privacy-statement).
- **GitHub stars and forks.** The homepage asks GitHub's public API for the repository's stars and forks from your browser, so GitHub receives that request.
- **No cookies or trackers** are set by agent-kit. Your browser may remember your colour theme and language in local storage; that never leaves your device.

## The docs MCP server

The server at [https://razcue-agent-kit.vercel.app/mcp](https://razcue-agent-kit.vercel.app/mcp) is hosted by Vercel, which may log requests (such as IP address, time and path) under the [Vercel Privacy Policy](https://vercel.com/legal/privacy-policy). It answers documentation lookups and stores nothing about the caller.

## Contact

Questions or requests: open an issue at [https://github.com/razcue/agent-kit/issues](https://github.com/razcue/agent-kit/issues), or reach the author through [https://razcue.github.io/agent-kit/](https://razcue.github.io/agent-kit/).


# Scripts

> The zero-dependency plugin scripts and their commands.

The scripts folder path is in the session context; most are also `agent-kit` commands.

## changes

What changed since the base branch: committed + staged + unstaged + untracked. Shared by preflight.mjs and tdd.mjs. Read-only git.

## checkpoint

Stop hook: after every turn (sync: async hooks are dropped when a headless run exits), saves where the work stands so the next session can resume — branch, changed files, active work. Silent; never fails.

## commit

Conventional Commit helpers for agents.

```bash
node commit.mjs draft [--staged]        changed files → suggested scope(s) and type
node commit.mjs check "<message>"       validate: project commitlint if installed,
node commit.mjs check --file <path>     else the built-in rules below (exit 1 = invalid)
```

## config

Shared paths and config for the agent-kit plugin scripts and CLI.

## context

Estimates the context loaded into EVERY Claude Code session of a project (CLAUDE.md chain + imports, memory index, agent-kit session context, skill listings) and finds skills Claude Code can't see. ~4 characters per token.

```bash
node context.mjs [dir] [--budget 8000]      exit 1 over budget
node context.mjs [dir] --sections            cost of every heading in the CLAUDE.md chain
```

## git-guard

PreToolUse(Bash) hook: blocks git commands the project's git flow forbids. Exit 2 blocks the call and shows stderr to Claude. Silent outside agent-kit projects.

## git-rules

Which git commands never change a repository: data for the git guard (git-guard.mjs). Subcommands that never change the repo, whatever their arguments.

## knowledge

Knowledge base: one concept per Markdown file with frontmatter, grouped in scopes, linked with [[name]]. This script does the deterministic work (index, search, validation) so agents spend tokens only on the entries they open.

```bash
node knowledge.mjs paths
node knowledge.mjs find <terms...> [--body]
node knowledge.mjs related <name>       the entry, what it links to, what links to it
node knowledge.mjs index [--global]
node knowledge.mjs check [--global]
```

## preflight

Pre-merge checklist from the diff between the merge base and the working tree (committed + staged + unstaged + untracked). Read-only git.

```bash
node preflight.mjs [base-branch]      exit 1 when a violation is found
```

## qa

QA dimension: a checklist generated from the living specs (one item per scenario), dated QA runs that record results, and the map from scenarios to the test-data fixtures (`-- @fixture <ids…> @tag` in seed.sql).

```bash
node qa.mjs sync [--check]   regenerate work/qa/checklist.md + checklist.html (--check: exit 1 if stale)
node qa.mjs run              start work/qa/runs/<today>.md with every scenario unticked
node qa.mjs status           latest result per scenario (pass / fail / blocked / n/a / re-check / never run)
node qa.mjs gaps             scenarios without a fixture; fixtures naming unknown scenarios (exit 1)
```

## run

Runs a command and returns a compact result for the agent: exit code, time, the lines that matter (failures, errors) and the tail. The full output goes to a log file, so a long run costs a few dozen lines of context, not thousands.

## script-nudge

PostToolUse(Write) hook: when the agent writes a script somewhere it will be lost (outside the project, at the project root, or in a tmp folder), remind it of the `scripts` skill so the script is found and reused next time.

## scripts

Script registry: find, run, test, scaffold and document the scripts agents and users write, so they are reused instead of rebuilt. A script is documented by `@key: value` lines in its first 40 lines (any comment style): @name @summary @usage (required: summary, usage) · @tags <span>

a, b

</span>

 · @test file

```bash
node scripts.mjs find <words...>          scripts (project, scratch, library) + skills
node scripts.mjs list
node scripts.mjs run <name|path> [--lines N] [-- args...]
node scripts.mjs test [name]
node scripts.mjs new <area>/<name>.<ext> --summary "…" [--usage "…"] [--scratch|--library]
node scripts.mjs index                    regenerate scripts/README.md
node scripts.mjs check                    undocumented, duplicate, missing tests
```

## session-start

SessionStart hook: injects the project profile (voice, language, git flow, method, work lanes), a compact knowledge index and the script index. Silent outside agent-kit projects.

## specs

Living specs (work/specs/<capability>

/spec.md) and the delta specs of changes (work/changes/NNN-slug/specs/<capability>

.md). Notation: EARS requirements (`### cap.R1 — name`), Given/When/Then scenarios tagged with one ZOMBIES category (`#### cap.R1.S1 — name @boundary`). IDs are never reused.

</capability>
</capability>



```bash
node specs.mjs lint [cap|NNN]          notation + id checks (exit 1 on errors)
node specs.mjs next <cap|cap.Rn>       next free requirement / scenario id
node specs.mjs merge <NNN>             apply a change's deltas to the living specs
node specs.mjs trace [NNN|cap]         scenario → tests (id in the test name) or ✅ rows
node specs.mjs list                    capabilities with requirement and scenario counts
```

## tdd

TDD support: which changed logic files have no test, and a compact run of only the tests related to the current changes.

```bash
node tdd.mjs status [base]
node tdd.mjs run [test files...] [--all] [--base <branch>] [--lines N]
```

## usage

Usage signals for a retro: what ran and failed, scripts never used, scratch scripts to promote or delete, knowledge nobody links to, work status.

```bash
node usage.mjs [--days 30]
```

## work

Work tracking: fast-track features (work/features/) and changes (work/changes/NNN-slug/: proposal, delta specs, plan, tasks), their status and next task, and traceability (scenario → test or verified check). Living specs (work/specs/<capability>

/spec.md) are handled by specs.mjs.

</capability>



```bash
node work.mjs status              active work with progress and next task
node work.mjs board               regenerate work/BOARD.md
node work.mjs trace [NNN]         scenarios (or legacy AC-n) → tests or ✅ checks
node work.mjs new feature|change <slug> [--title "…"]   next number + files from the templates
```


# Skills

> Every skill and when it loads.

Only the description of each skill loads every session; the body loads when a task needs it.

## adopt

Use BEFORE editing AGENTS.md / CLAUDE.md to shrink them or reduce per-session context, and when moving an existing project onto agent-kit — measure, map every section, move procedures into skills, area rules into folder CLAUDE.md files and facts into .knowledge/, one section at a time. Triggers: "adopt agent-kit", "slim AGENTS.md", "too many tokens", context over budget.

- **Origin**: plugin (every project)

## commit

Use BEFORE any git commit — whenever the user says "commit", "commit message", "save this work", or a spec/feature is done. Runs preflight, reviews what goes in, writes a Conventional Commit message (type(scope) subject, English), validates it with commitlint, then commits within the project's git flow (or hands the user the exact command when git is read-only).

- **Origin**: plugin (every project)

## decide

Record an architecture or design decision (ADR) in the right scope — project decisions in .knowledge/decisions, cross-project ones in global meta. Use when a choice with lasting impact is made or asked about ("let's go with…", "we decided…", "should we use X or Y" once settled), or when an earlier decision is replaced.

- **Origin**: plugin (every project)

## feature

Use BEFORE making any small code change — a fix, a tweak, a small UI addition (≤3 files, no schema, permission or money change). Opens a work/features file with goal, tasks and evidence so the work survives session restarts. Triggers: "fix", "tweak", "small change", "change X to Y", "add X to the page". Bigger or riskier work → `spec` skill.

- **Origin**: plugin (every project)

## knowledge

Read and write the scoped knowledge base — business concepts, environment facts, stack conventions, UI/UX rules, cross-project meta rules. Use before working in an unfamiliar area ("how do we…", "what is…"), and whenever a lasting fact, rule or convention comes up that a future session must know ("remember…", "from now on…", "the rule is…").

- **Origin**: plugin (every project)

## preflight

Pre-merge check of the current branch — migrations to apply or wrongly edited, new env vars, new dependencies, possible secrets, debug leftovers, grants to anon/authenticated, undocumented scripts, and (SDD + TDD) changed logic without a test. Use before a PR or merge, when a spec/feature is closing, or when the user asks "what do I need to do to ship this?".

- **Origin**: plugin (every project)

## retro

Retrospective that turns experience into durable setup — repeated corrections become knowledge or hook rules, reused scratch scripts get promoted, unused things get pruned. Use when the user says "retro", "what did we learn", "improve the setup", after finishing a spec, or about once a month.

- **Origin**: plugin (every project)

## scripts

Decide, find, build, document, test and run scripts so they are reused instead of rewritten. Use before writing ANY script or helper program (test helpers, data checks, generators, "write a script that…"), before re-creating an earlier ad-hoc script, and when keeping or documenting scripts. Searches existing scripts and skills first.

- **Origin**: plugin (every project)

## spec

Spec-driven lane (SDD × TDD) for big or risky work — a new module or page set, schema/RPC changes, permissions, money, anything over ~3 files. Opens a change (proposal + delta specs), gets approval, implements test-first, verifies every scenario and merges into the living specs. Use when the user says "spec", "plan this", "new module", or the work exceeds the fast-track lane.

- **Origin**: plugin (every project)
- **Files**: `references/notation.md`, `templates/delta.md`, `templates/plan.md`, `templates/proposal.md`, `templates/tasks.md`

## start

Guided kickoff for a new project or a big new piece of work — asks plain questions (what, for whom, which pages or features, look and feel, content) and turns the answers into the first spec. Use when the user says "start", "I want to build…", "new site/app/project", or when work/ is empty and the request is open-ended.

- **Origin**: plugin (every project)

## tdd

Use BEFORE writing or changing logic when the user asks for TDD, "test first" or tests, or the project method is SDD + TDD. Red → green → refactor one behaviour at a time, test cases chosen with ZOMBIES, related tests run compactly with tdd.mjs. Also when preflight reports logic without tests.

- **Origin**: plugin (every project)

## stack-nuxt-content-site

Use BEFORE adding or changing pages, texts, navigation, colours, images or components in this Nuxt Content site (content/*.md, app/, nuxt.config.ts). Conventions for Markdown pages, frontmatter, ordering, styling tokens, MDC components, SEO and the static build.

- **Origin**: template (installed in `.claude/skills/` of projects on that stack)

## stack-nuxt-supabase

Use BEFORE adding or changing pages, components, server routes (apps/*/server/api), auth, Zod schemas, SQL migrations, RPCs or test data in the Nuxt 4 + shadcn-vue + Tailwind v4 + Supabase monorepo (apps/web, apps/app, apps/docs, packages/ui, packages/shared). Conventions and patterns, details in references/.

- **Origin**: template (installed in `.claude/skills/` of projects on that stack)
- **Files**: `references/bff.md`, `references/migrations.md`, `references/monorepo.md`, `references/test-data.md`, `references/ui.md`


# Templates

> What each setup kind scaffolds.

## App monorepo (`--kind monorepo`)

Nuxt 4 + shadcn-vue + Tailwind v4 + Supabase, npm workspaces. Stack skill: `stack-nuxt-supabase`.

<table>
<thead>
  <tr>
    <th>
      Workspace
    </th>
    
    <th>
      Purpose
    </th>
    
    <th>
      Dev
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        apps/web
      </code>
    </td>
    
    <td>
      Public website (prerendered)
    </td>
    
    <td>
      <code>
        npm run dev:web
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        apps/app
      </code>
    </td>
    
    <td>
      Main solution: SPA + BFF (<code>
        server/api
      </code>
      
      ) + Supabase, with an auth starter — throttled login, session restore, route guard with safe redirects, server-side logout, login page
    </td>
    
    <td>
      <code>
        npm run dev:app
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        apps/docs
      </code>
    </td>
    
    <td>
      Help / wiki site (Docus, Markdown in <code>
        content/
      </code>
      
      )
    </td>
    
    <td>
      <code>
        npm run dev:docs
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        packages/ui
      </code>
    </td>
    
    <td>
      Nuxt layer: shadcn-vue components, Tailwind theme
    </td>
    
    <td>
      —
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        packages/shared
      </code>
    </td>
    
    <td>
      Zod schemas + utils (no Nuxt / Vue imports)
    </td>
    
    <td>
      —
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        supabase/migrations/
      </code>
    </td>
    
    <td>
      <code>
        000000000000_init.sql
      </code>
      
       (migration tracking, <code>
        _env
      </code>
      
      , Data API locked to <code>
        service_role
      </code>
      
      ), login throttle
    </td>
    
    <td>
      —
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        supabase/test-data/
      </code>
    </td>
    
    <td>
      <code>
        env.sql
      </code>
      
      , <code>
        seed.sql
      </code>
      
      , <code>
        purge.sql
      </code>
      
       (when test data is on)
    </td>
    
    <td>
      —
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        .github/workflows/
      </code>
    </td>
    
    <td>
      <code>
        npm run check
      </code>
      
       + preflight
    </td>
    
    <td>
      —
    </td>
  </tr>
</tbody>
</table>

Commands: `npm run check` (typecheck + tests), `npm test`, `npm run format`. Choose the apps with `--apps web,app,docs`.

## Content site (`--kind site`)

One Nuxt 4 site with Nuxt Content: every Markdown file in `content/` is a page (`content/about.md` → `/about`), colours in `app/assets/css/main.css`, built to static HTML (`npm run generate`). Stack skill: `stack-nuxt-content-site`. Made for non-technical users — see [Your website with Claude](https://razcue.github.io/agent-kit/en/guides/content-site).

## Existing project (`--kind existing`)

Only the agent layer. Your `AGENTS.md` gets a managed block; pick a stack skill with `--stack`.

## Blank project (`--kind blank`)

Only the agent layer, plus a minimal `package.json` so tests and commit checks have a home.

## Base (every kind)

`AGENTS.md` skeleton, `.knowledge/` scopes, `work/` with its README, and — with the QA checklist on — `work/qa/`.