Comparison

A · CLAUDE.md · angad-kandhari/deliberate B · AGENTS.md · angad-kandhari/deliberate

What each file covers, counted
Dimension	Only in A	Only in B	Overlap
Sections	5	4	0%
Commands	1	0	0%
Section tags	2	0	0%

What each file covers

Sections

0 shared · 5 only in A · 4 only in B

− Deliberate
− Repo structure
− Sibling repo
− Conventions
− License
+ AGENTS.md — Deliberate
+ Core discipline (apply to every non-trivial task)
+ Verify before you claim done
+ Load the matching discipline

Commands

0 shared · 1 only in A · 0 only in B

− npx skills add angad-kandhari/deliberate

Section tags

0 shared · 2 only in A · 0 only in B

− code-style
− architecture

Line diff

+32 added−45 removed11 unchanged19.6% identical

angad-kandhari/deliberate · CLAUDE.md

@@ −1 @@

1# Deliberate

3Engineering discipline for AI harnesses. A drop-in skill library for LLM coding agents.

5## Repo structure

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```

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).

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.

40## Sibling repo

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.

44When editing skills here, the site repo's submodule needs to be bumped to pick up changes.

46## Conventions

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.

53## License

angad-kandhari/deliberate · AGENTS.md

@@ +1 @@

1# AGENTS.md — Deliberate

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.

5Bias toward caution over speed. For trivial one-liners, use judgment.

7## Core discipline (apply to every non-trivial task)

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.

19## Verify before you claim done

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.

23## Load the matching discipline

25When a task fits one of these, apply the corresponding skill in [`skills/`](./skills/):

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) |

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.

@@ −1 +1 @@

1−# Deliberate

1+# AGENTS.md — Deliberate

3−Engineering discipline for AI harnesses. A drop-in skill library for LLM coding agents.

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.

5−## Repo structure

5+Bias toward caution over speed. For trivial one-liners, use judgment.

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−```

7+## Core discipline (apply to every non-trivial task)

358

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).

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.

3718

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.

19+## Verify before you claim done

3920

40−## Sibling repo

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.

4122

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.

23+## Load the matching discipline

4324

44−When editing skills here, the site repo's submodule needs to be bumped to pick up changes.

25+When a task fits one of these, apply the corresponding skill in [`skills/`](./skills/):

4526

46−## Conventions

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) |

4741

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−

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.

5643