CLAUDE.md

1# Deliberate
2 
3Engineering discipline for AI harnesses. A drop-in skill library for LLM coding agents.
4 
5## Repo structure
6 
7```
8skills/
9  deliberate/SKILL.md   — foundational, 9 principles (always load)
10  spec/SKILL.md         — spec-driven feature work against a PRD
11  debug/SKILL.md        — debugging discipline
12  review/SKILL.md       — code review discipline
13  test/SKILL.md         — testing discipline
14  verify/SKILL.md       — verification discipline (completion claims)
15  secure/SKILL.md       — security discipline (writing safe code)
16  pentest/SKILL.md      — penetration-testing discipline (authorized offensive testing)
17  explore/SKILL.md      — codebase-familiarity discipline
18  memory/SKILL.md       — memory discipline (persistent agent memory)
19  architect/SKILL.md    — architectural thinking
20  migrate/SKILL.md      — migration playbook
21  incident/SKILL.md     — incident response
22.claude-plugin/
23  plugin.json           — Claude Code plugin manifest
24  marketplace.json      — makes the repo /plugin-installable
25hooks/
26  hooks.json            — SessionStart activation hook
27  activation.md         — discipline-check injected at session start
28  enforcement/          — opt-in deterministic gates (block-no-verify, test-gate, scope-lock)
29evals/                  — honest with/without eval harness (scenarios, rubric, runner)
30AGENTS.md               — distilled core for AGENTS.md-native tools (Codex, Cursor, …)
31README.md
32LICENSE                 — Apache 2.0
33NOTICE                  — copyright + attribution
34```
35 
36Every skill lives at `skills/<name>/SKILL.md` with YAML frontmatter (`name`, `description`). This structure is required for compatibility with `npx skills add angad-kandhari/deliberate` (vercel-labs/skills CLI).
37 
38The repo doubles as a **Claude Code plugin**: `.claude-plugin/plugin.json` marks it a plugin (the existing `skills/` folder is auto-discovered), `.claude-plugin/marketplace.json` makes it installable via `/plugin marketplace add angad-kandhari/deliberate`, and `hooks/hooks.json` wires a SessionStart hook that `cat`s `hooks/activation.md` into context so the skills actually activate. The activation hook is the fix for the ecosystem-wide "instruction dropout" problem — passive skills fire only ~6–44% of the time without it.
39 
40## Sibling repo
41 
42The marketing site lives at `angad-kandhari/deliberate-site` (separate repo). It pulls this repo in as a git submodule at `content/deliberate/`. Deployed to https://deliberate.work via Cloudflare Pages.
43 
44When editing skills here, the site repo's submodule needs to be bumped to pick up changes.
45 
46## Conventions
47 
48- Each SKILL.md follows a consistent voice: terse intro, numbered principles, one-line `**Test:**` per section, "These Guidelines Are Working If" summary, footer with cross-references.
49- Frontmatter is minimal: `name` (lowercase, matches directory) and `description` (one paragraph).
50- Cross-references between skills use relative paths: `[deliberate](../deliberate/SKILL.md)`.
51- No tool-specific syntax — plain markdown with frontmatter, works with any agent.
52 
53## License
54 
55Apache 2.0. Copyright 2026 Angad Kandhari. See LICENSE and NOTICE.
56