A Claude Code harness and a knowledge-base format for building software with an AI assistant doing most of the editing. Derived from three real installations, not designed on paper. Every rule in it was paid for by a named failure, every number in it carries the date and the commit it was measured at, and the kit says plainly which parts are enforced and which are advice.
The human owns direction. An independent review owns judgment. Deterministic checks own facts.
If you want the kit, start with Install. If you want to know why it is shaped this way, start with Where this came from. Both are short.
An assistant with a fresh context knows nothing about your project, and the expensive failure is that it does not know that it knows nothing. It reads the default branch and reports on code that was superseded weeks ago. It proposes a fix that was tried and rejected in March. It edits a test so the suite passes. It writes a confident summary that drops the one caveat that mattered. Documentation written to prevent this rots within a month, because nobody reads a page that changes three times a day next to a page that stays true.
This kit answers with two things and one boundary between them:
| The harness | The knowledge base | |
|---|---|---|
| holds | how the assistant works on this project | what is true about the project, with evidence |
| made of | rules, skills, hooks, tools, settings under .claude/ |
Markdown pages with evidence headers |
| read by | the assistant, automatically, at session start or on a trigger | humans and assistants, on demand |
| the test for inclusion | would the assistant get this wrong without it? | would this still be worth reading in a year? |
Volatile status, where the last session got to and what to resume, lives in a third folder,
working/, which is disposable and never committed. Durable facts never share a folder with
volatile status. That boundary is the design. It is also per checkout: because everything there is
ignored by git, a linked worktree starts without it, so a task agreed in one does not travel to
another, and nothing is copied between them.
Four rules, ten skills, four hooks, nine tools. Install is a copy, and an update replaces only what you have not changed.
| Part | What it does |
|---|---|
standing-orders |
how to work here: name the destination before acting, say what you did rather than what you intended, confirm before anything irreversible; the risk tier with its hard floor; the stop-list; what counts as done |
writing |
one register for a mixed audience of developers, analysts, managers, and non-technical readers, most of whom read English as a second language |
working-here |
the traps that fail silently, each with symptom, mechanism, fix, and the date it was measured. It grows with every incident |
knowledge-base |
loads only when a knowledge-base file is touched: how a claim is written so it is still true in a year |
/orient |
where things stand at the start of a session, in five lines. Then it stops and lets you choose |
/work |
a task from a description, a GitHub issue, or an Azure DevOps item: understand, one yes, an uninterrupted build, a review menu, a hand-back with evidence |
/record /handoff |
durable facts into the knowledge base with evidence and what was not checked; session state into working/ so it survives a compaction |
/codex-relay |
an optional second model, read-only, briefed in full, answering verdict first, with pushback allowed only with evidence |
/test-guide /pr /board |
plain-English test steps that double as the pull request's "How to test"; a well-formed pull request; a tracker update that proposes and stops |
/explain /summarize |
the real version at a named audience, with a verify mode that re-checks a claim against the current tree; and the short version, without losing the caveats |
| four hooks | a secret value is blocked before it is written; a test weakened, skipped, or deleted blocks the turn, measured from the baseline of the task this session carries when there is one, and from HEAD otherwise, and it keeps blocking until the test is repaired or you authorize that exact change; a destructive-command list that starts empty and grows from incidents; that same task's brief re-read after a compaction |
baseline.sh |
seals the task's starting point into the agreed brief at the owner's yes: the approval time, the tier, the digest of the agreed text, the commit of every checkout, and a second digest over all of those, so the starting point cannot be moved by a hand edit. It lists the files that were already dirty, and binds the brief to this Claude session so both hooks know which agreement is in flight rather than taking the newest file; unbound, both fall back and say so. check at hand-back reads it back and refuses a top-tier task with neither a completed independent review nor an owner's waiver, or one whose code has moved past the commit that was reviewed. allow-test-change is the one escape from the Stop hook: it records a file, the exact content it ends at, and why, so that change is allowed and the next one is not |
knowledge-check.sh |
the knowledge base's mechanical floor: every durable page carries the header the rules require, the values with an objective shape have it, and every reference it can identify without guessing resolves, which is local links, page-relative references, repo: paths, commit: shas, and decision codes. It also proves a short curated list of counts the README states still matches the tree. It decides structure, never truth |
verify.sh |
the checks that exist here, a canary that must fail, and three test suites that prove the hooks, the knowledge checks, and the updater can each go red |
Every hook ships in PowerShell and in Bash, because the host launches whichever the machine runs. The tools are Bash, so Windows needs Git Bash; that is stated again under Install, because it is the one thing that will stop you.
git clone https://github.com/Eslam93/agentic-methodology kit bash kit/.claude/tools/install.sh <your-repo> --shape A # one repository bash kit/.claude/tools/install.sh <workspace> --shape B --repos <clones> # several repositories
On Windows, powershell -File kit\.claude\tools\install.ps1 -Target <dir> -Shape A copies the same
files and writes the same manifest. Git Bash is still required to use the harness: verify.sh,
baseline.sh, and the test suites are Bash scripts, and the PowerShell installer says so and exits
non-zero when it cannot find bash to verify with. Only the four hooks ship in both shells, because
those are what the host launches.
The installer copies .claude/ without overwriting anything, writes the hook settings for your
operating system, creates working/ and the knowledge-base skeleton, adds the ignore and attribute
lines, and ends by running verify.sh. It prints INSTALLED AND VERIFIED only when that passes; if
anything is red it says the files are copied but not verified, and exits non-zero, because a copied
tree whose hooks are not wired is not a working harness. Then open Claude Code on the project,
start a new session, and say:
read START-HERE.md in
kit/and follow it
The assistant asks you the eleven questions it cannot answer from the code, measures the rest, writes the project rule, and runs the acceptance tests. START-HERE.md is written for the assistant; you only have to point at it.
/orient where things stand, in five lines. Then STOP and let the human choose.
/work intake, understand, one yes, route, build, the review menu, hand back.
/record durable findings into the knowledge base, with evidence and what was NOT checked.
99-pending everything noticed and not acted on: one line, same turn.
/handoff session state to a file in working/, so it survives compaction and Monday.
Two boundaries carry the whole design: orienting and deciding are different jobs, and the second is the human's; and a finding goes to the knowledge base the first time, never to the disposable folder.
- Name the destination out loud before you act. Which repository, which branch it is cut from, which branch the pull request targets. The sentence is what catches the mistake, not caution.
- One yes, then build uninterrupted. The assistant asks only the questions whose answers change what gets built, gives one summary with a checkable outcome list, and stops once. After the yes it pauses only for a short stop-list: a security area touched unexpectedly, a new dependency, a migration, data deletion, anything reaching production, two failed attempts at the same thing.
- Size the job with a tier, and a hard floor. Auth, payments, secrets, migrations, public contracts, security controls, and cross-module architecture are always the top tier and cannot be tiered down. The top tier finishes one of two ways: one independent review completed, or the owner waived it in their own words. Reaching the end without either is not a waiver, and a review covers the commit it read: change the code afterwards and it needs reviewing again.
- Evidence settles findings, in a fixed order. A deterministic failing check, then the reviewer's own recompute, then a spec line nobody in the loop wrote, then a builder-produced result, then model judgment alone, which settles nothing. A citation never settles a finding by itself.
- A green counts only if the check can go red.
verify.sh --canarymust fail. A check that has never failed is suspect. - Spend the enforcement budget only where damage is irreversible and silent. Four hooks. A gate people click through ten times a day is not a gate.
- Never assert a changeable condition in the present tense. Write the measurement, with its
date and commit. "As of 2026年08月31日 at
2c617f31, no test project existed" stays true forever. - Describe the system, not the people. Knowledge concentration is a property of the code.
- Keep negative results. A thing that turned out not to be true saves the next person a day.
- The grader must not be the worker. A fresh-context review is the default; a second model is optional and read-only.
Every substantial page opens with a header: what the page settles, when the facts were gathered, when they were last verified and how, the scope, the confidence and why, what was not checked, and when to re-verify. A page with volatile numbers carries a three-line banner: measured when, expires when somebody does their job, stays true regardless. Every claim says what kind of sentence it is, so a reader never mistakes a fact for a measurement, a measurement for an opinion, or an opinion for a decision. Corrections are swept by code symbol, not by phrase, because one refuted claim once survived five correction passes across nine documents.
This repository keeps its own knowledge base under docs/knowledge-base/,
written under those rules, about itself.
Version 1 of this methodology was documents a project fills in: a per-task flow, a constitution
built into AGENTS.md, design notes, ADRs, a worklog, a resume file, an escape log, a promotion
ledger, a memory system. Complete, and reachable at tag v1.5.1. In real use the documents were
filled in and not read. Version 2 keeps the theory and deletes the documents: what survives lives
as rule lines a session loads, skill beats a session runs, and checks a script can fail.
The harness itself was generalized from three installations in daily use during 2026: the owner's own public site, and two multi-repository consultancy workspaces. Their project content stays private; what this kit took is the rules, the skills, the hooks, and the measured traps. The knowledge-base format follows a blueprint written from a nine-repository .NET estate.
The reasoning is all recorded, with what each decision superseded and when to revisit it:
decisions.md: every decision in forceevidence-and-verification-rules.md: how a claim is written_readings/: the sources, with what was taken and what was notwhat-we-do-not-know.md: the gaps, by root cause_investigations/: the commands and commits behind every number, and the acceptance results
The kit is copied into your repository on purpose, so you can read it, review it in your pull
requests, pin it with your history, and change it. That makes upgrading a real question, so the
installer records what it gave you, in .claude/install-manifest.txt: the release, and the SHA-256
of every managed file as delivered. It is installer metadata, not project content, and you do not
edit it by hand.
bash <kit>/.claude/tools/install.sh <your-repo> --update --check # say what would change bash <kit>/.claude/tools/install.sh <your-repo> --update # do it
An update replaces only files whose content still matches the manifest, which is the one thing
it can prove you have not changed. Content, never a timestamp. Running the installer without
--update never replaces anything: it lists what is out of date and tells you the command.
| Your file | What happens |
|---|---|
| untouched since install | replaced with the new version |
| you changed it | preserved, and listed under "Locally modified, preserved" |
| new in this release | installed, unless a file is already at that path |
| a path you already had | left alone and listed; the installer never assumes ownership |
| removed from the kit | left in place and listed. Nothing is ever deleted |
| you deleted it | not restored. Removing a control is a decision, not a gap |
| yours, not the kit's | invisible to the updater. It manages only what it shipped |
Nothing is merged. No three-way merge, no conflict markers, no backup files, no model. A file you changed has deliberately stepped outside automatic replacement and stays exactly as you left it until you reconcile it yourself. That also means a customized file does not receive later upstream changes: the updater tells you which files diverged, and the reconciliation is yours.
Preserving your files is a success, not a failure: an update that skips everything you changed and
verifies clean exits 0 and says UPDATED AND VERIFIED. A non-zero exit means one of two things, and
the output says which: a file could not be written, or verification is red afterwards. Neither is
"you have local changes".
If you installed before the manifest existed, the first update adopts every file that is already byte-identical to the new release, and leaves everything else alone: without a record of what you started from, "original" and "customized" cannot be told apart, and the installer will not guess.
The last tag is v2.0.0, 2026年09月05日. main has moved past it: the task baseline, the knowledge
checks, the update path, and several rounds of hardening all landed after it, each with its own page
in the knowledge base. Take main.
Seventeen acceptance tests, seventeen passed, seven of them live on the Claude Code desktop app
rather than by hand: the secret guard blocked a real write and allowed the false-positive case, the
Stop hook blocked a weakened test, the path-scoped rule loaded on a real read, the resume hook fired
on a real compaction, the goal evaluator blocked a failing stop, and /board proposed a close and
stopped. The exact steps and the caveats per row are on the acceptance page. CI runs the checks, the
canary, and the test suites on Linux on every push.
The limits, stated once: nothing here has been shown by comparison to help. The measurements are one maintainer's, on Windows and Linux CI, dated in the knowledge base. These four hooks watch the editing tools and the two shells and nothing else, so a shell redirect or an MCP call passes them untouched; that is a choice about what this kit matches, not a limit of the platform. No adopter has installed or upgraded this but its author. If you install it, write your own limits down the same way.
.claude/ the kit, live on this repository as well
rules/ standing-orders · writing · working-here · knowledge-base · methodology (this repo's own)
skills/ orient · work · codex-relay · test-guide · pr · board · record · handoff · explain · summarize
hooks/ guard-secrets · guard-commands · verify-on-finish · resume-brief, each .ps1 and .sh
tools/ layout.sh · verify.sh · baseline.sh · knowledge-check.sh · install.sh · install.ps1
hooks.test.sh · knowledge-check.test.sh · install.test.sh · stop-hook-canary.test.js
install-manifest.txt what the installer gave you, so an update can tell your edits from ours
knowledge-drift.conf this repository's curated list of counts the README states
settings.json the hook wiring
docs/knowledge-base/ this repository's knowledge base
working/ disposable; only its README is committed
START-HERE.md for the assistant
.github/workflows/ verify.sh, its canary, and the hook tests, on every push
Issues and pull requests are welcome. A change to a rule, a hook, or a skill should say what failure it prevents, with the date and the command that showed it. That is the standard every line in the kit was held to, and it is the only kind of evidence that settles a change here.
Built by Eslam Hamed, from daily use. MIT licensed; see LICENSE.