Single source of truth for AI is AGENTS.md. CLAUDE.md becomes a one-line @AGENTS.md import so Claude Code and Codex read the same spec — zero drift. README.md becomes a short Chinese entry point (language policy, layout, tag styles, top pitfalls) and links into AGENTS.md for full rules. - Consolidate docs/01-08 into AGENTS.md (7 sections, ~700 lines) - README.md: ~80-line Chinese entry point, no rule duplication - CLAUDE.md: just "@AGENTS.md" - Delete docs/ — content preserved in git history at tag 20260520-3 Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
31 KiB
AGENTS.md — team-guide
Working agreements for our 1–3 person AI-assisted development team.
This is the canonical spec for AI coding agents (Claude Code, Codex,
and any other AGENTS.md-aware tool). Claude Code reads this via
CLAUDE.md's @AGENTS.md import, so there's exactly one source of
truth.
Human-facing entry point:
README.md(Chinese, condensed). When humans want the full ruleset, they read this file.
Project
This repo holds our team's working agreements. It is documentation, not code — no build, test, or lint step. Acceptance is "a human can read the change and would have written the same."
Editing rules (this repo)
- One rule per bullet. If a rule needs a paragraph of justification,
split the rule out and put the reason on a
**Why:**line. - Lead with the rule, then
**Why:**, then**How to apply:**only when the rule isn't self-evident. - No emoji. No decorative headers. No "🚀 Getting started!" energy.
- Keep AGENTS.md under ~800 lines. Past that, split.
- Examples beat prose. A 3-line code block beats a paragraph.
Language policy
- Human-facing: Chinese —
README.mdand the human-fillable templates (templates/README.md.template,templates/PR_DESCRIPTION.template.md,templates/HANDOFF_CHECKLIST.template.md). - AI-facing: English — this file,
CLAUDE.md,templates/CLAUDE.md.template,templates/AGENTS.md.template. - Git metadata: English — commit messages, PR titles, branch names, tag annotations. AI tools and search work better on English.
If you're an agent about to write Chinese into a file the human would never read (or English into a file only humans read), stop — wrong file.
CLAUDE.md and AGENTS.md sync
Claude Code reads CLAUDE.md; Codex and other agents read AGENTS.md.
In this repo, CLAUDE.md is a single line: @AGENTS.md. That makes
this file the only spec; both tools see the same content.
For other projects in our workspace where the two files are physical copies (legacy or tool-mismatch reasons), the rules are:
- Bodies must stay in sync. Drift breaks one of the tools silently.
- Whoever edits one updates the other in the same PR. Add "Synced AGENTS.md" (or "Synced CLAUDE.md") to the PR description.
- Reviewer blocks PRs that only touch one side.
When starting a new project, prefer the single-file approach: write
AGENTS.md, make CLAUDE.md a one-line @AGENTS.md import.
1. Vibe coding — humans + AI work split
The premise
Claude / Codex write most of the code. Humans steer: framing problems, making decisions, deciding what's good enough. We're not racing the AI — we're skipping typing so we spend more time thinking.
The split
AI does:
- Read code and explain it
- Write first-pass implementations against a clear spec
- Mechanical refactors (renames, extractions, type changes)
- Run tests, builds, linters; iterate on errors
- Generate boilerplate (configs, fixtures, CRUD)
- Search across the workspace and summarize
Humans do:
- Decide what to build and why
- Frame the spec before AI touches code
- Approve any change with non-local consequences (deps, schema, infra, auth, secrets)
- Read every diff before merging
- Make the call when AI has tried twice and is going in circles
- Sign off on commit messages and PR descriptions (AI drafts; you sign)
If a task feels like it's drifting toward "AI decides", stop and write a spec yourself first.
Prompt habits
- Frame, don't dictate. Tell AI the goal, the constraints, and what you've ruled out. Don't prescribe steps unless the steps are the point.
- Name the file. "Fix the bug in
eval-agent/runner.py" beats "fix the bug." Save AI a search. - Say what done looks like. "Tests pass and the new flag defaults to off" — measurable. "Make it cleaner" — not.
- One task per turn. Three unrelated asks → three messages or three sessions.
- Push back on bad output. If the diff is wrong, say so plainly and point at what's wrong. Don't accept code you wouldn't write yourself.
When to take over
Stop letting AI drive when:
- It's failed the same approach twice and the error is unchanged.
- It's adding "safety" code the task didn't ask for.
- The diff has grown past what you can read in one sitting.
- You can't explain the change to a teammate without re-reading the diff.
- It's about to do something irreversible — confirm explicitly.
When you take over, write why in the PR description so the next person doesn't repeat the loop.
Verifying AI output
Treat every AI diff like a fast junior's PR:
- Does it build?
- Do tests pass — and do new tests actually test the new code?
- Did it touch files outside the stated scope? Look at every one.
- Did it add deps? Check the lockfile diff.
- Read every comment AI added. Half are noise — delete those.
- Run user-facing features end-to-end. Type checks ≠ working software.
Anti-patterns
- Snowballing context. Long sessions accumulate stale assumptions. New task → new session.
- Approval-by-default. "Looks good" without reading the diff is how bugs ship.
- Outsourcing the spec. "Figure out what we should do" is avoidance, not a prompt.
- Letting AI rewrite history. If AI wants to refactor unrelated code "while we're here", say no. Open a separate task.
2. Claude Code & Codex configuration
Per-project files
<repo>/
├── AGENTS.md ← canonical spec, committed
├── CLAUDE.md ← committed, single line: @AGENTS.md
└── .claude/
├── settings.json ← shared settings, committed
├── settings.local.json ← personal overrides, gitignored
└── skills/ ← project skills, committed
settings.local.json is always gitignored — personal API keys,
local paths, individual hook tweaks.
AGENTS.md content per project
In this order:
- Project — two sentences max.
- Run it — build, test, lint as bash blocks.
- Architecture — one paragraph. Entry points and data flow. No diagrams unless they save words.
- Conventions specific to this repo — naming, layout, patterns that aren't obvious from the code.
- Don'ts — things AI has gotten wrong before. One line each.
A new contributor (human or AI) should be productive after one read. Past 100 lines, split — it's drifted into "documentation."
Use templates/AGENTS.md.template.
Permissions (Claude Code)
Default: prompt for risky, allow read-only freely.
In .claude/settings.json, allow without prompting:
- All
Read,Glob,Grep Bash(git status),Bash(git diff),Bash(git log),Bash(git branch)- Project-specific read-only commands (
Bash(npm test),Bash(pytest))
Always prompt for:
Edit/Writeoutside the working treeBashwith destructive verbs (rm,mv,git push,git reset --hard, package installs)- Any MCP tool that talks to a remote service
Approving the same prompt repeatedly → run the
fewer-permission-prompts skill to propose an allowlist from your
transcripts.
Codex approval & sandbox
- Approval: default
on-request(asks before commands). Useon-failureorneveronly on personal, low-risk machines. Production / shared / unfamiliar repos → keepon-request. - Sandbox: default
workspace-write+ network off. Toggle network on temporarily to install packages or fetch resources, then off.danger-full-accessrarely. - Personal Codex preferences in
~/.codex/config.toml— never commit.
Hooks
Hooks enforce rules automatically. AI does not reliably remember "from now on do X" across sessions; hooks do.
Use hooks for:
- Auto-formatting on file edit (Prettier, ruff, gofmt)
- Blocking edits to protected paths (
.env, generated files,dist/) - Auto-running tests after writing to a known test path
- Notifying on session stop / long-task completion
Don't use hooks for:
- One-off checks ("just remember X this week")
- Anything that depends on AI judgment
Configure via update-config skill or edit .claude/settings.json
directly. One-line comment per hook.
Memory
Per-machine memory system. Use it for:
- User: who you are, role, preferences.
- Feedback: corrections that should stick across sessions, with the why.
- Project: facts about ongoing work that aren't in the code (deadlines, stakeholder decisions, why a refactor is happening).
- Reference: pointers to external resources (Linear, Grafana, internal wikis).
Don't put memory content in AGENTS.md. AGENTS.md is shared with the
team; memory is personal, per-machine, outside the repo. Don't use
memory as a notes app — task-scoped state goes in plans or PR descriptions.
Skills
Skills live in three places:
- User skills (
~/.claude/skills/) — installed once, available everywhere - Project skills (
<repo>/.claude/skills/) — committed, team-shared - Plugin skills — installed via marketplace
Promote a workflow to a skill when all three are true:
- Done it the same way three times.
- Steps stable enough to write down.
- Someone else would do it the same way given the spec.
Only two true → leave it as a prompt snippet.
Skill design:
- One skill, one job. Branching skills are two skills.
- Verb-phrase names:
review-pr,cut-release,rebuild-fixtures— notpr-helper. - Description (the line the model sees) says when to invoke, not what the skill does.
SKILL.mdunder 200 lines; long skills split into stages.- Examples beat instructions.
Recommended installs:
anthropic-skills:consolidate-memory periodic memory cleanup
simplify review changed code for reuse/quality
fewer-permission-prompts propose allowlist from transcripts
review review a pull request
security-review security pass on pending changes
Review skills like PRs — read, run once on a real task, merge. Skills
nobody runs after a month → archive (.claude/skills/_archive/).
Sub-agents
Spawn a sub-agent (Claude Agent tool) when:
- Task needs cross-file search and you don't want results in main context.
- You want a second independent read on a design or diff.
- Work is genuinely parallel (e.g. researching three options).
Don't spawn for tasks the main agent can do in two tool calls.
Sessions
- One task per session. New task → new session.
- Long session, context bar filling → finish current step, summarize into a plan or PR draft, start fresh.
- Don't
--continueyesterday's session for a new topic. Stale context leaks in.
Tool selection (mixing Claude Code + Codex)
Both fine; mild preferences:
- Writing docs / specs — Claude Code (this repo was written that way).
- Large refactors / cross-file features — Claude Code (plan mode + sub-agents).
- Narrow edits, run a test, change a config — Codex CLI (faster startup).
- In-IDE inline edits — Codex IDE plugin or Cursor.
Don't run two tools editing the same file simultaneously — overwrites are hard to trace.
3. Git workflow
Branches
main(spec repos) /dev(product repos) is always shippable. No direct pushes, no exceptions.- Feature branches:
<owner>/<short-slug>—bai/auth-retry,bai/eval-agent-rerun. Lowercase, hyphens, handle prefix. - Long-lived integration:
integration/<topic>— only by team agreement. - Delete branches after merge.
Commits
<area>: <imperative summary under 60 chars>
<optional body — what changed and why, not how>
<area>is a directory or component, lowercase:eval-agent,task_assistant,docs,git-workflow.- Imperative: "add", "fix", "rename" — not "added" / "adding".
- Body wraps at ~72 chars. Skip it for trivial commits.
- One topic per commit. "and" in the summary → split.
- Always include
Co-Authored-Byfor AI-assisted commits. - English.
Examples:
eval-agent: rerun failed tasks with stable seed
docs: clarify branch naming
task_assistant: drop unused legacy export path
Pull requests
- One PR per topic. Can't describe in one sentence → multiple PRs.
- Title under 70 chars, same shape as commit summary.
- Description uses
templates/PR_DESCRIPTION.template.md. - First push of a feature branch uses
-u. - Open as draft once runnable. Review-as-you-go beats review-at-the-end.
Review
Every PR reviewed before merge — own AI-assisted PRs included.
Reviewer:
- Description matches diff? Surprises → ask.
- Read every changed file. Off-topic file → ask why it's in this PR.
- Run locally if not obviously correct from reading.
- New deps, schema changes, env vars, auth-touching code → block until justified.
- Comment on least-important issue first; merge-blocker last so it's clearly the gate.
Author follow-ups:
- Address every comment, even with "agreed, fixed in ".
- Disagree → push back in writing. Don't silently ignore.
- Squash fixup commits before merge if history is noisy.
Merging
- Squash for feature branches. Merge commits reserved for integration.
- Final squash message follows commit format.
- Delete the branch on merge.
Tagging
Two styles by project type:
| Project type | Tag format | Example | Tag from |
|---|---|---|---|
| Spec repo | YYYYMMDD[-N] |
20260520, 20260520-2 |
main |
| Product repo | vX.Y.Z |
v0.2.4 |
dev |
Decide: would a "user" receive a versioned artifact from this project? Yes → product. No → spec.
Universal:
- Annotated only (
git tag -a). - Tag message summarizes what changed since the previous tag.
- Tags are immutable once pushed. Wrong tag → cut a new one.
- Don't tag on feature branches.
Spec-repo specific: max one tag per day. Same-day reissues → -N
suffix.
Product-repo specific: see Product project rules for the full ruleset (semver triplet, manifest, sync list).
Spec tag:
git checkout main && git pull --ff-only
git tag -a 20260520 -m "team-guide 20260520: bilingual policy"
git push origin 20260520
Product tag:
git checkout dev && git pull --ff-only <remote> dev
git tag -a v0.2.4 HEAD -m "<Project> V0.2.4"
git push <remote> v0.2.4
Inspect:
git tag --sort=-creatordate
git show 20260520
git log --oneline 20260513..20260520
When to cut a spec-repo tag:
- Docs changed in a way teammates need to re-read.
- A template was added, removed, or restructured.
- A new convention is now in effect (not just proposed).
When not to cut a spec-repo tag:
- Typos, formatting, link fixes → just push to
main. - Drafts under discussion → use a PR.
Product tagging follows the release flow in Product projects.
Don'ts
- No
git push --forcetomain. Period. To your own branch only if certain nobody pulled it. - No
--no-verifyto skip hooks. Fix what the hook reports. - No amending pushed commits. Add a new commit instead.
- No deleting or moving pushed tags. Cut a new one.
- No committing
.env, secrets, or files >5 MB without a Git LFS conversation. - No
git add ./git add -Awhen there are unrecognized untracked files. Stage by name.
4. Code & deliverable style
Naming
- Files — lowercase. Docs hyphenated (
git-workflow.md), Python underscored (task_runner.py), JS/TS kebab where ecosystem prefers. Match the surrounding project. - Functions — verb phrases.
loadConfig, notconfig.runTask, nottaskRunner. - Variables — what they are, not their type.
users, notuserArray.retryCount, notn. - Booleans —
is*,has*,should*.isReady, notready. - Constants —
UPPER_SNAKE_CASEonly at module level. Inside functions, plainconst. - No abbreviations unless they're domain terms.
database, notdb. (req/resin Express is fine.)
Comments
Default: none. Justified when all are true:
- Why is non-obvious from code.
- A future reader would otherwise misread.
- The code can't be made clearer (rename / extract / restructure).
Don't write:
// increment counternext tocounter++// added for the auth refactor— belongs in the commit message- Block comments restating signatures
- TODOs without owner or date
Do write:
- One-liners for non-obvious workarounds, with the why.
# NOTE:for behavior that would surprise a reader.- Module headers when the file does something the layout doesn't explain.
File structure
- One concept per file. Can't summarize in one sentence → split.
- Tests next to the code unless project already uses parallel test trees.
- Generated files in
dist/,build/, etc. — and.gitignore. Never edit a generated file. - Lockfiles always checked in.
Errors
- Fail loudly at boundaries (user input, external APIs, file I/O).
- Don't
try/exceptto silence. Catch → handle. - Internal functions trust callers. Don't validate the same input three layers deep.
- Logged errors include enough context to debug from logs alone.
Tests
- Test behavior, not implementation. Behavior-preserving refactor that breaks a test → test was wrong.
- One assertion per test ideally.
- Fixtures next to the tests using them.
- Slow / flaky tests get marked or quarantined, not silently retried.
- New code without a test is incomplete unless project has no test infrastructure (rare, and a bug itself).
READMEs
Every repo has one. In order:
- What is this? One paragraph.
- How do I run it? Bash blocks.
- How do I develop on it? Code layout, conventions.
- Where does data come from / go to? Only if non-obvious.
- Pointers. Related repos, dashboards, docs.
Use templates/README.md.template.
Shorter than the template is fine — delete unused sections.
Don'ts
- No third way to do something we already do two ways.
- No config options "for flexibility" without a real use case. YAGNI.
- No unrelated refactors in a feature PR. Open a separate one.
- No optimization before measurement.
5. Product projects
For projects that ship versioned artifacts to users (task_assistant, authoring-tool, etc.). Spec repos (this one) ignore this section.
Spec vs product
| Dimension | Spec repo | Product repo |
|---|---|---|
| Content | Docs, conventions, templates | Executable code, shippable artifacts |
| Tag format | YYYYMMDD / YYYYMMDD-N |
vX.Y.Z |
| Acceptance | Human can read it | Tests pass, runs |
| Distribution | Git itself | Git (source) + dist channel (binaries) |
| Version-field sync | None | Multiple sites must agree |
| Users | Team members | Real end users |
Unsure? "Will a user receive a versioned artifact from this?" Yes → product.
Versioning
Semver triplet: major.minor.patch.
- major — backward-incompatible (schema, CLI args, artifact format)
- minor — backward-compatible additions
- patch — bug fixes, perf, internal refactors
Three forms, all must agree:
| Use | Format | Example | Where |
|---|---|---|---|
| Internal | X.Y.Z |
0.2.4 |
package.json, pyproject.toml |
| Display | VX.Y.Z |
V0.2.4 |
UI chips, README title, release note |
| Git tag | vX.Y.Z |
v0.2.4 |
Git tag |
Each product project lists its release-bump checklist in one place
(usually its own AGENTS.md). task_assistant's example:
package.json "version": "0.2.4"
public/index.html version chip default
server.js fallback version
scripts/build-release.js fallback + release notes
scripts/build-release-windows.js fallback + release notes
README.md title, version status
README.en.md same
Miss one → next release drifts.
Tags (product)
- Annotated. Message:
<Project Name> V<x.y.z>. - One version, one tag — don't split across platforms.
- Already-shipped tags don't move. Wrong → ship a patch.
- Mistake before shipping (rare):
git tag -d v0.2.4
git push <remote> :refs/tags/v0.2.4
git tag -a v0.2.4 <correct-sha> -m "<Project> V0.2.4"
git push <remote> v0.2.4
Branches
dev is the collaboration trunk. Feature branches off dev, PR back to
dev. Don't keep an unclear master. Stable branches use clear names:
release/v0.3, release/v0.3-hotfix.
Git vs distribution channel
Git holds source. The distribution channel (OpenList, Hugging Face, S3, etc.) holds artifacts. They don't mix.
Into Git:
- Source, build scripts, docs, conventions, small static assets, templates, role/config tables.
Out of Git:
config/ local config
logs/ runtime logs
feedback-records/ user feedback
generated_task_packages/ task outputs
reports/ verification reports
runtime-temp/ transient state
release/ release-build/ release-dev/ release-merge/
.venv/ __pycache__/ node_modules/
Distribution channel layout (typical):
/<project>/dist/ release zips + manifest
/<project>/feedback/<machine-id>/ uploaded user feedback
Release zips are self-contained: user unzips, clicks, runs. No dependency installs on user machines.
Manifest
Top-level manifest.json in the dist channel — clients read it to
decide whether to update:
{
"name": "<project-name>",
"version": "0.2.4",
"displayVersion": "V0.2.4",
"released_at": "2026-05-18T17:00:00Z",
"platforms": {
"windows": {
"url": "<dist-url>/<project>-v0.2.4-windows.zip",
"size": 123456789,
"sha256": "<hex>"
},
"macos-arm64": { "url": "...", "size": ..., "sha256": "..." },
"macos-x64": { "url": "...", "size": ..., "sha256": "..." }
},
"release_notes": "<short markdown>"
}
After upload, re-fetch the manifest and eyeball size + sha256. Same size as previous → cache or upload error.
Update flow (user-confirmed, not silent)
- Client startup fetches manifest, compares versions.
- New version → prompt the user, don't auto-download.
- User confirms → download to local.
- User confirms install → restart.
Never silently skip a step. This goes in every product's AGENTS.md
"Don'ts."
Feedback & logs
Local-first, async upload:
local:
feedback-records/feedback-<timestamp>-<id>.json
logs/<project>-YYYY-MM-DD.jsonl
remote (after successful upload):
/<project>/feedback/<machine-id>/<feedback-file>.json
- Upload failure must not lose local data. UI says "saved locally, upload failed, retry later."
- Redact before send: API keys, Bearer tokens, cookies, passwords, secrets, private account info.
- Triage flow: ask users to use the feedback page, not to send raw
config/or full log directories.
Sensitive-info scan
Pre-commit:
git diff --cached
Periodic keyword scan:
git grep -nE "sk-|hf_|Bearer |apiKey|ANTHROPIC_API_KEY|OPENAI_API_KEY|password|secret" \
-- ':!*.lock' ':!vendor/**' ':!**/__pycache__/**'
Hits require human judgment — demo keys in comments and real keys both match. Don't blind-commit, don't blind-delete.
If a real secret was committed:
- Invalidate the key/token immediately.
- Replace local config.
- Notify collaborators.
- Decide whether to rewrite Git history (
git filter-repoor team-agreed tool).
A "delete the key" commit alone is not safe — history still has it.
Standard release flow
# 1. Sync
git checkout dev
git pull --ff-only <remote> dev
git status --short --branch
# 2. Check
<lint command>
<test command>
# 3. Bump version (every site on the project's bump checklist)
# 4. Commit + tag
git add <files>
git commit -m "chore: release vX.Y.Z"
git tag -a vX.Y.Z HEAD -m "<Project> VX.Y.Z"
git push <remote> dev
git push <remote> vX.Y.Z
# 5. Build
<build command>
# 6. Upload manifest + zips, verify size/sha256
Product README required sections
On top of the standard README sections, product projects add:
- Version status — current source version, internal version, collaboration branch, repo URL, migration source (if any), default local service URL (if any), default output dir.
- Quick start — per platform (Windows / macOS / Linux): unpack, start, access, stop.
- Bundle contents — what's inside the release zip.
- Release-bump checklist — which files contain version strings to update on release.
Minimum delivery checklist
Every "ready to ship" version must have:
<remote>/devhas the corresponding commit<remote>has the corresponding tag (v<x.y.z>)package.json/pyproject.tomlversion correct- UI version chip displays correctly
- Lint / typecheck / test all pass
- Distribution channel manifest points at correct platform zips
- manifest size / sha256 match actual files
- Release zip unpacks → start script → runs
- Zip contains no API keys, logs, user feedback, generated outputs, or verification reports
Any unchecked → not "ready to ship."
What new product projects need
Beyond the standard AGENTS.md + CLAUDE.md + .claude/:
docs/COLLABORATION_AND_RELEASE_WORKFLOW.md(or similar) — a project-specific specialization referencing this section, listing the project's bump checklist, build commands, and dist paths. task_assistant's is the reference example.scripts/build-release.*— outputs zip + updatesmanifest.json.- Bump checklist — single source of truth in
AGENTS.mdor the workflow doc above. CHANGELOG.md— one entry per version, semver order, user-visible changes.
YAGNI:
- Complex release tooling (Lerna, Changesets) — small team, manual is fine.
- Auto-generated release notes — good commit messages suffice.
- Multi-environment config systems — only when actually needed.
6. Planning cadence
1–3 person team. Lightest process that keeps us aligned.
Weekly
- Async written sync (Monday morning). Each person posts:
- What I shipped last week (one line per item).
- What I'm picking up this week (one line per item).
- What's blocked or unclear (the only section worth reading carefully).
- 30-minute live call mid-week. Agenda is the "blocked or unclear" lines.
Per task
Before starting work that takes more than ~half a day:
- Write a 5-line spec: Goal / Why / Done when / Out of scope / Risks.
- Drop in PR description (draft PR fine) before writing code.
- If AI does most of the typing, the spec is also the prompt.
After:
- PR description matches what shipped.
- Lessons future-you would want → Claude memory (feedback / project types). See Memory.
Quarterly
Half a day to:
- Re-read this
AGENTS.md. Open PRs for what's stale. - Review skill catalog. Archive unused.
- Run
consolidate-memoryon personal memory files.
What planning is not
- Not Jira tickets. Two people don't need a board.
- Not Gantt charts. Need one → building the wrong thing.
- Not status theater. Monday post is for spotting blocks, not proving you worked.
7. Handoff
Task packages, deliverables, work transfers between team members or to external consumers.
Why this matters
Handoff failures cost more than the original work. A package that's "obvious" to the author is a half day of confusion for the recipient. Handoff is part of the deliverable, not afterthought packaging.
Two kinds
- Internal — passing work to a teammate or future-you. Branch, PR, half-finished prototype.
- External — versioned artifact to a partner / customer / downstream. Zip, dataset, release.
Both use
templates/HANDOFF_CHECKLIST.template.md.
External has higher bar.
Task package layout
<package>/
├── README.md ← what this is, who it's for, how to use
├── CHANGELOG.md ← what changed since last version
├── VERIFICATION.md ← counts, checksums, sanity checks
├── manifest.json ← machine-readable metadata
├── data/ ← the actual deliverable
└── scripts/ ← only what's needed to use the package
manifest.json minimum fields:
{
"name": "praxis-sample-5",
"version": "0.5.0",
"generated_at": "2026-05-18T17:00:00Z",
"source_commit": "<full sha>",
"source_repo": "<git remote url>",
"record_count": 1234,
"schema_version": "1.0"
}
Can't fill a field → null and explain in README. Never make one up.
Internal handoff
Before handoff:
- PR description is current. Summary describes what shipped, not what was attempted.
- Test plan in PR template filled honestly. Untested → say so, don't bury.
- Surprising AI-assisted decisions →
## Notes for reviewer. "AI tried X first, didn't work because Y, working approach is Z" — saves the reviewer a re-derivation. - Local-only state (env vars, scratch data) documented or scripted. "Works on my machine" is not a handoff.
The recipient should be able to: git checkout the branch → read PR
description → run test plan → form an opinion — without messaging you.
External handoff (additional bar)
- Reproducibility. Someone with source access can rebuild from the
commit hash in
manifest.json. Test once before first release. - Verification report. Machine-checkable (JSON or similar) showing pre-ship checks passed.
- Provenance. AI-generated → record model and human-in-loop steps. For debugging six months later, not ceremony.
- License & attribution. Even for internal partners.
What not to ship
- Files >500 MB without a delivery-channel conversation.
- Real PII unless that's explicitly the deal.
.env, secrets, API keys, internal hostnames.- "Final final v3" filenames. Use the version field. If it's
final, it'sv1.0. - A package without a README. Even a one-line README beats none.
Receiving a handoff
- Read the README first, fully. Resist running scripts.
- Run the verification report. Fails → stop and message the sender before doing anything else.
- Note any surprise — naming, missing files, version mismatch — and send back within a day. Drift gets worse with silence.
Working directory expectations (this repo)
- Small repo (~10 files).
Readeverything before acting; no need to spawn a sub-agent for exploration. - Don't introduce
package.json,Makefile, CI configs, or other toolchain files unless explicitly asked. This is a docs repo.