Comparison

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

What each file covers, counted
Dimension	Only in A	Only in B	Overlap
Sections	4	5	0%
Commands	0	1	0%
Section tags	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

+45 added−32 removed11 unchanged19.6% identical

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.

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

@@ −1 +1 @@

1−# AGENTS.md — Deliberate

1+# Deliberate

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.

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

5+## Repo structure

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+

4356