Two files, one repository
angad-kandhari/deliberate ships 2 formats across 2 indexed files. The question worth asking is whether the second one says anything the first does not.
CompareAGENTS.md ↔ CLAUDE.md
| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 4 | 5 | 0% |
| Commands | 0 | 0 | 1 | 0% |
| Section tags | 0 | 0 | 2 | 0% |
What each file covers
Sections
0 shared · 4 only in A · 5 only in B- − AGENTS.md — Deliberate
- − Core discipline (apply to every non-trivial task)
- − Verify before you claim done
- − Load the matching discipline
- + Deliberate
- + Repo structure
- + Sibling repo
- + Conventions
- + License
Commands
0 shared · 0 only in A · 1 only in B- + npx skills add angad-kandhari/deliberate
Section tags
0 shared · 0 only in A · 2 only in B- + code-style
- + architecture
Line diff
angad-kandhari/deliberate · AGENTS.md
@@ −1 @@
1# AGENTS.md — Deliberate
2
3Engineering discipline for AI coding agents, distilled for tools that read `AGENTS.md` (Codex, Copilot, Cursor, Windsurf, Aider, Zed, Jules, Gemini CLI, and others). The full skills live in [`skills/`](./skills/) — this file is the always-on core; load the matching skill when a task calls for it.
4
5Bias toward caution over speed. For trivial one-liners, use judgment.
6
7## Core discipline (apply to every non-trivial task)
8
91. **Think before coding.** Don't assume — state assumptions, and if multiple interpretations exist, surface them instead of silently picking one. If something's unclear, ask.
102. **Push back when warranted.** No sycophancy. If a request creates risk, tech debt, or contradicts an earlier decision, say so before doing it.
113. **Plan first.** For anything multi-step, state the plan (what → how you'll verify) before executing.
124. **Simplicity first.** Minimum code that solves the problem. No speculative abstractions, no features not asked for, no new deps the stdlib covers.
135. **Surgical changes.** Touch only what the task requires. Don't reformat, refactor, or "improve" adjacent code. Don't remove comments or code you don't understand. Every changed line should trace to the request.
146. **Goal-driven execution.** Turn vague tasks into verifiable ones. Write the naive correct version first, then optimize while preserving correctness.
157. **Know when to stop.** After ~3 failed attempts at the same approach, stop and reassess — don't grind. Escalate instead of masking confusion with activity.
168. **Calibrate confidence.** Distinguish what you know from what you're guessing. "I haven't tested this" and "I'm pattern-matching" are useful, valid statements.
179. **Maintain context integrity.** Don't silently reverse earlier decisions. Re-read the relevant context before changing code tied to a prior choice.
18
19## Verify before you claim done
20
21Done means demonstrated, not asserted. Run the thing — the test, the build, the actual flow — before saying "done" or "fixed." Never weaken or delete a check to make it pass. Report what you observed, not what you expect. If you couldn't run it, say so.
22
23## Load the matching discipline
24
25When a task fits one of these, apply the corresponding skill in [`skills/`](./skills/):
26
27| When you're… | Apply |
28|---|---|
29| Building against a PRD or design doc | [`spec`](./skills/spec/SKILL.md) |
30| Working in code you didn't write, before adding to it | [`explore`](./skills/explore/SKILL.md) |
31| Crossing a component boundary or shaping a contract | [`architect`](./skills/architect/SKILL.md) |
32| Fixing a bug or a failing test | [`debug`](./skills/debug/SKILL.md) |
33| Writing or auditing tests | [`test`](./skills/test/SKILL.md) |
34| About to claim work is done | [`verify`](./skills/verify/SKILL.md) |
35| Touching auth, input, secrets, or data boundaries | [`secure`](./skills/secure/SKILL.md) |
36| Auditing code for vulnerabilities (authorized) | [`pentest`](./skills/pentest/SKILL.md) |
37| Reviewing a PR or your own diff | [`review`](./skills/review/SKILL.md) |
38| Doing a schema change, upgrade, or version bump | [`migrate`](./skills/migrate/SKILL.md) |
39| Responding to a production incident | [`incident`](./skills/incident/SKILL.md) |
40| Writing to or recalling from persistent memory | [`memory`](./skills/memory/SKILL.md) |
41
42Full text and per-section tests are in each skill file. This distillation is intentionally lean — the detail lives in the skills, loaded on demand.
43
angad-kandhari/deliberate · CLAUDE.md
@@ +1 @@
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
@@ −1 +1 @@
1−# AGENTS.md — Deliberate
1+# Deliberate
22
3−Engineering discipline for AI coding agents, distilled for tools that read `AGENTS.md` (Codex, Copilot, Cursor, Windsurf, Aider, Zed, Jules, Gemini CLI, and others). The full skills live in [`skills/`](./skills/) — this file is the always-on core; load the matching skill when a task calls for it.
3+Engineering discipline for AI harnesses. A drop-in skill library for LLM coding agents.
44
5−Bias toward caution over speed. For trivial one-liners, use judgment.
5+## Repo structure
66
7−## Core discipline (apply to every non-trivial task)
7+```
8+skills/
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
25+hooks/
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)
29+evals/ — honest with/without eval harness (scenarios, rubric, runner)
30+AGENTS.md — distilled core for AGENTS.md-native tools (Codex, Cursor, …)
31+README.md
32+LICENSE — Apache 2.0
33+NOTICE — copyright + attribution
34+```
835
9−1. **Think before coding.** Don't assume — state assumptions, and if multiple interpretations exist, surface them instead of silently picking one. If something's unclear, ask.
10−2. **Push back when warranted.** No sycophancy. If a request creates risk, tech debt, or contradicts an earlier decision, say so before doing it.
11−3. **Plan first.** For anything multi-step, state the plan (what → how you'll verify) before executing.
12−4. **Simplicity first.** Minimum code that solves the problem. No speculative abstractions, no features not asked for, no new deps the stdlib covers.
13−5. **Surgical changes.** Touch only what the task requires. Don't reformat, refactor, or "improve" adjacent code. Don't remove comments or code you don't understand. Every changed line should trace to the request.
14−6. **Goal-driven execution.** Turn vague tasks into verifiable ones. Write the naive correct version first, then optimize while preserving correctness.
15−7. **Know when to stop.** After ~3 failed attempts at the same approach, stop and reassess — don't grind. Escalate instead of masking confusion with activity.
16−8. **Calibrate confidence.** Distinguish what you know from what you're guessing. "I haven't tested this" and "I'm pattern-matching" are useful, valid statements.
17−9. **Maintain context integrity.** Don't silently reverse earlier decisions. Re-read the relevant context before changing code tied to a prior choice.
36+Every 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).
1837
19−## Verify before you claim done
38+The 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.
2039
21−Done means demonstrated, not asserted. Run the thing — the test, the build, the actual flow — before saying "done" or "fixed." Never weaken or delete a check to make it pass. Report what you observed, not what you expect. If you couldn't run it, say so.
40+## Sibling repo
2241
23−## Load the matching discipline
42+The 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.
2443
25−When a task fits one of these, apply the corresponding skill in [`skills/`](./skills/):
44+When editing skills here, the site repo's submodule needs to be bumped to pick up changes.
2645
27−| When you're… | Apply |
28−|---|---|
29−| Building against a PRD or design doc | [`spec`](./skills/spec/SKILL.md) |
30−| Working in code you didn't write, before adding to it | [`explore`](./skills/explore/SKILL.md) |
31−| Crossing a component boundary or shaping a contract | [`architect`](./skills/architect/SKILL.md) |
32−| Fixing a bug or a failing test | [`debug`](./skills/debug/SKILL.md) |
33−| Writing or auditing tests | [`test`](./skills/test/SKILL.md) |
34−| About to claim work is done | [`verify`](./skills/verify/SKILL.md) |
35−| Touching auth, input, secrets, or data boundaries | [`secure`](./skills/secure/SKILL.md) |
36−| Auditing code for vulnerabilities (authorized) | [`pentest`](./skills/pentest/SKILL.md) |
37−| Reviewing a PR or your own diff | [`review`](./skills/review/SKILL.md) |
38−| Doing a schema change, upgrade, or version bump | [`migrate`](./skills/migrate/SKILL.md) |
39−| Responding to a production incident | [`incident`](./skills/incident/SKILL.md) |
40−| Writing to or recalling from persistent memory | [`memory`](./skills/memory/SKILL.md) |
46+## Conventions
4147
42−Full text and per-section tests are in each skill file. This distillation is intentionally lean — the detail lives in the skills, loaded on demand.
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+
55+Apache 2.0. Copyright 2026 Angad Kandhari. See LICENSE and NOTICE.
4356
