Getting started
Project layout
Every file and folder agent-kit adds to a project, and what each one is for.
The agent layer (every project)
| Path | What |
|---|---|
agent-kit.json | The setup answers (every field). Change them by re-running init. |
AGENTS.md + CLAUDE.md | Short project rules plus a managed agent-kit block; CLAUDE.md imports @AGENTS.md. Keep it under 300 lines. |
.claude/settings.json | Plugin enabled from its marketplace + git permission rules for your flow (your own rules are kept). |
.claude/skills/stack-* | The stack conventions skill of your template (refreshed by upgrade). |
.knowledge/ | Project knowledge: business, env, decisions, ux, stack, and local (gitignored). See Knowledge. |
work/ | Specs, changes, features, QA — see below. |
scripts/ | Kept, documented scripts; scripts/README.md is a generated index. |
.agent-kit/ | Gitignored machine state: scratch/ throwaway scripts (still searchable), runs/ full logs, backups/, the checkpoint. |
commitlint.config.mjs, .husky/commit-msg | Commit message checks (Conventional Commits only). |
.mcp.json | Read-only Supabase MCP server, when you gave a project ref. |
work/
| Path | What |
|---|---|
work/specs/<capability>/spec.md | Living specs: how the system behaves now. The source of truth. |
work/changes/NNN-slug/ | Changes from the spec lane: proposal.md, delta specs in specs/<capability>.md, plan.md, tasks.md. |
work/features/NNN-slug.md | Fast-track work: goal, tasks, evidence. |
work/qa/ | checklist.md and checklist.html (generated), runs/ (QA passes). |
work/BOARD.md | Generated overview of active work. |
work/README.md | A map of this folder (managed by the kit). |
Templates
| Kind | Adds |
|---|---|
| App monorepo | apps/web (public site), apps/app (SPA + BFF + Supabase auth starter), apps/docs (Docus), packages/ui (shadcn-vue layer), packages/shared (Zod + utils), supabase/migrations/, supabase/test-data/, CI. |
| Content site | One Nuxt site: every Markdown file in content/ is a page; colours in app/assets/css/main.css. |
| Existing / blank | Only the agent layer (blank also gets a minimal package.json). |
Details in Templates.