Reframe team-guide as praxis (Greek for "practice"): Simgreek's coding
agent rulebook, distributed as a Claude Code plugin so SessionStart
hook can force-inject the using-praxis bootstrap.
- Add .claude-plugin/{marketplace,plugin}.json: makes this repo a
one-plugin marketplace installable via /plugin marketplace add.
- Add hooks/{hooks.json,session-start,run-hook.cmd}: SessionStart
hook reads using-praxis SKILL.md and injects it into context as
hookSpecificOutput.additionalContext (Claude Code) or
additional_context (Cursor) or additionalContext (Copilot CLI).
- Migrate library/<topic>/SPEC.md → skills/<topic>/SKILL.md with
YAML frontmatter (name + when-to-invoke description).
- Add skills/using-praxis: bootstrap with iron law, red-flags table,
catalog, instruction priority, sub-agent stop, Codex/Cursor fallback.
- Add skills/debugging: 4-phase root-cause investigation with
3-fixes-failed → architectural problem rule.
- Add skills/verification: evidence-before-claims gate with
rationalization table.
- Drop library/, references in AGENTS.md updated to skills/.
- Rename throughout: team-guide → praxis.
- README rewritten with both install paths (plugin / external spec)
and updated bootstrap prompt.
Codex / Cursor / non-Claude users still get the spec by reading
AGENTS.md and skills/ files manually — only the auto-injection
requires Claude Code.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
738 lines
24 KiB
Markdown
738 lines
24 KiB
Markdown
# AGENTS.md — praxis
|
|
|
|
Working agreements for the Simgreek team's AI-assisted development.
|
|
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.
|
|
|
|
If installed as a Claude Code plugin (`/plugin install praxis`), the
|
|
`SessionStart` hook also injects the `using-praxis` skill into the
|
|
session — see [`skills/using-praxis/SKILL.md`](skills/using-praxis/SKILL.md).
|
|
|
|
> Human-facing entry point: [`README.md`](README.md) (Chinese,
|
|
> condensed). When humans want the full ruleset, they read this file.
|
|
|
|
## How AI agents use this repo
|
|
|
|
Before starting non-trivial work in any team project, an agent should:
|
|
|
|
1. **Read this `AGENTS.md`** — general rules (vibe coding, Git, code
|
|
style, planning, handoff).
|
|
2. **Scan [`skills/`](skills/)** — narrower SOPs. The
|
|
[`using-praxis` skill](skills/using-praxis/SKILL.md) lists the full
|
|
catalog and tells you when to invoke each.
|
|
3. **Read the project's own `AGENTS.md`** — project-specific stuff
|
|
(how to run it, architecture, project-only don'ts). Project AGENTS.md
|
|
files do **not** repeat praxis content; they reference it.
|
|
|
|
In short: praxis is the external rulebook every project's agent reads
|
|
at task start. Project AGENTS.md files stay small and specific.
|
|
|
|
## 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.
|
|
- Keep AGENTS.md under ~600 lines. Past that, split a section into
|
|
`skills/`.
|
|
- Examples beat prose. A 3-line code block beats a paragraph.
|
|
|
|
## Language policy
|
|
|
|
- **Human-facing**: Chinese — `README.md` only.
|
|
- **AI-facing**: English — this file, `CLAUDE.md`, anything under
|
|
`skills/`.
|
|
- **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
|
|
|
|
AI writes most of the code. Humans steer: framing problems, making
|
|
decisions, deciding what's good enough. The point of AI assistance is
|
|
to skip typing, not to skip 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
|
|
- Stop AI when it's tried twice and is going in circles
|
|
- Sign off on commit messages and PR descriptions (AI drafts; human signs)
|
|
|
|
### Spec requirement
|
|
|
|
If the task description from the human is shorter than ~3 sentences and
|
|
the work touches more than one file, the AI must **stop and ask for a
|
|
5-line spec** before writing code:
|
|
|
|
```
|
|
Goal: <what should be true after this task>
|
|
Why: <one sentence>
|
|
Done when: <measurable acceptance>
|
|
Out of scope: <things explicitly not to touch>
|
|
Risks: <what could go wrong>
|
|
```
|
|
|
|
Don't infer the spec silently. Vague task + silent inference is the most
|
|
common cause of AI rework.
|
|
|
|
### Prompt habits (rules for human input that improve AI output)
|
|
|
|
- **Frame, don't dictate.** Goal + constraints + what's been ruled out.
|
|
Don't prescribe steps unless the steps are the point.
|
|
- **Name files.** "Fix the bug in `<repo>/<file>.py`" beats "fix the bug."
|
|
- **Say what done looks like.** Measurable phrasing — "tests pass and
|
|
the new flag defaults to off." Not "make it cleaner."
|
|
- **One task per session.** Unrelated asks → separate sessions.
|
|
- **Push back on bad output.** Point at the wrong part specifically.
|
|
|
|
### When AI must stop and surface to the human
|
|
|
|
AI stops driving and surfaces the situation to the human when:
|
|
|
|
- The same approach has failed twice with the same error.
|
|
- The task is asking AI to add code (validation, retry logic, defensive
|
|
guards) the spec didn't request.
|
|
- The current diff has grown past ~300 lines or touches >5 files when
|
|
the spec called for a narrower change.
|
|
- AI is about to do something irreversible (delete data, force-push,
|
|
rotate auth, drop a database, modify a production config).
|
|
|
|
In each case, AI summarizes the situation and asks for direction. Don't
|
|
keep iterating.
|
|
|
|
### Output verification (AI runs this on its own diffs before declaring done)
|
|
|
|
1. Does the build / typecheck pass?
|
|
2. Do tests pass — and do new tests actually exercise the new code?
|
|
3. Are there files in the diff outside the stated scope? If yes, justify
|
|
each or revert.
|
|
4. Did this PR add dependencies? If yes, name them in the summary.
|
|
5. Are there AI-generated comments restating what the code says? Delete.
|
|
6. For user-facing changes: state how the change was exercised end-to-end.
|
|
Type-check passing is not evidence of working software.
|
|
|
|
### Anti-patterns AI must avoid
|
|
|
|
- **Snowballing context.** Long single session covering multiple
|
|
unrelated tasks; stale assumptions leak across tasks.
|
|
- **Refactor drift.** "While I'm here, let me also clean up X." Open a
|
|
separate task instead.
|
|
- **Comment padding.** Adding obvious or restating comments to make a
|
|
diff look thorough.
|
|
- **Silent scope expansion.** Touching files not implied by the task
|
|
without flagging them in the summary.
|
|
|
|
---
|
|
|
|
## 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.
|
|
|
|
### Per-project AGENTS.md content
|
|
|
|
Order: **Project** (≤2 sentences) → **Run it** (bash blocks) →
|
|
**Architecture** (one paragraph + key files) → **Conventions specific
|
|
to this repo** → **Don'ts** (things AI got wrong here before).
|
|
|
|
Past 100 lines → split. Skeleton:
|
|
|
|
```markdown
|
|
# AGENTS.md — <project name>
|
|
|
|
> Reference: praxis for cross-project rules. This file holds only
|
|
> what's specific to this project.
|
|
|
|
## Project
|
|
<one or two sentences>
|
|
|
|
## Run it
|
|
```bash
|
|
<install / run / test / lint commands>
|
|
```
|
|
|
|
## Architecture
|
|
<one paragraph: entry points, data flow, major modules>
|
|
|
|
Key files:
|
|
- `<path>` — <one-line role>
|
|
|
|
## Conventions specific to this repo
|
|
<naming patterns, where to add new features, what's auto-generated>
|
|
|
|
## Don'ts
|
|
- Don't <…>
|
|
```
|
|
|
|
`CLAUDE.md` in a new project is one line: `@AGENTS.md`.
|
|
|
|
### Permissions (Claude Code)
|
|
|
|
Default: prompt for risky, allow read-only. **Why:** keeps friction
|
|
low for safe ops while preserving review of mutations.
|
|
|
|
Allow without prompt: all `Read`/`Glob`/`Grep`, read-only Bash
|
|
(`git status`, `git diff`, `git log`, `git branch`, project test
|
|
runners).
|
|
|
|
Always prompt: `Edit`/`Write` outside the working tree; destructive
|
|
Bash (`rm`, `mv`, `git push`, `git reset --hard`, package installs);
|
|
any MCP tool hitting a remote service.
|
|
|
|
### Codex approval & sandbox
|
|
|
|
- **Approval**: default `on-request`. **Why:** unfamiliar repos and
|
|
shared machines need command-level review.
|
|
- **Sandbox**: default `workspace-write` + network off. Turn network
|
|
on only when fetching/installing, then off again.
|
|
- Personal Codex prefs go in `~/.codex/config.toml`, never committed.
|
|
|
|
### Hooks
|
|
|
|
AI does not reliably remember "from now on do X" across sessions —
|
|
hooks enforce automatically.
|
|
|
|
Use for: auto-format on edit, block writes to protected paths
|
|
(`.env`, generated files, `dist/`), auto-test after writing test files,
|
|
session-stop notifications.
|
|
|
|
Don't use for: one-off reminders, anything depending on AI judgment.
|
|
|
|
### Memory
|
|
|
|
Per-machine. Use for: who you are (User), corrections that should
|
|
persist across sessions with the *why* (Feedback), facts about
|
|
ongoing work that aren't in code (Project), pointers to external
|
|
resources (Reference).
|
|
|
|
Memory is personal and per-machine — never substitute for AGENTS.md.
|
|
Task-scoped state goes in plans or PR descriptions, not memory.
|
|
|
|
### Skills
|
|
|
|
Locations: user (`~/.claude/skills/`), project
|
|
(`<repo>/.claude/skills/`), plugin marketplace.
|
|
|
|
Promote a workflow to a skill when **all three** hold: done the same
|
|
way 3+ times, steps stable enough to write down, someone else would do
|
|
it the same way given the spec.
|
|
|
|
Skill design:
|
|
|
|
- One skill, one job. Branching skills are two skills.
|
|
- Verb-phrase names (`review-pr`, `cut-release`), not nouns
|
|
(`pr-helper`).
|
|
- Description tells the model **when to invoke**, not what the skill
|
|
does.
|
|
- `SKILL.md` under 200 lines.
|
|
|
|
Recommended installs (read each skill's own description for what it
|
|
does):
|
|
|
|
```
|
|
consolidate-memory simplify fewer-permission-prompts review security-review
|
|
```
|
|
|
|
### Sub-agents
|
|
|
|
Spawn one when: cross-file search and you don't want results in main
|
|
context, second independent read on a design or diff, genuinely parallel
|
|
work (e.g. three options to research). Don't spawn for tasks doable 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 `--continue` yesterday's session for a new topic.
|
|
|
|
### Mixing Claude Code + Codex
|
|
|
|
Both fine. **Don't** run two tools editing the same file simultaneously
|
|
— overwrites are hard to trace.
|
|
|
|
Mild preferences: docs/specs and large refactors → Claude Code (plan
|
|
mode, sub-agents); narrow edits and quick test runs → Codex CLI
|
|
(faster startup); in-IDE inline → Codex IDE plugin or Cursor.
|
|
|
|
---
|
|
|
|
## 3. Git workflow
|
|
|
|
### Branches
|
|
|
|
- `main` (spec repos) / `dev` (product repos) is always shippable. No
|
|
direct pushes.
|
|
- Feature branches: `<short-slug>`, lowercase, hyphenated. Project may
|
|
prefix with owner (`<owner>/<slug>`) — follow the project's existing
|
|
convention.
|
|
- 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.
|
|
- Imperative: "add", "fix", "rename" — not "added" / "adding".
|
|
- One topic per commit. "and" in the summary → split.
|
|
- Always include `Co-Authored-By` for 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 structure: **Summary** (1 sentence + bullets if needed) /
|
|
**Why** / **What changed** (bulleted by file or area) / **Test plan**
|
|
(checkbox list, honest about what was and wasn't tested) /
|
|
**Out of scope** (optional) / **Notes for reviewer** (optional, for
|
|
surprising AI decisions). Add an `AI-assisted` trailer for
|
|
AI-assisted PRs.
|
|
- First push of a feature branch uses `-u`.
|
|
|
|
### Review (when AI is reviewer)
|
|
|
|
When AI reviews a PR, run these checks in order:
|
|
|
|
1. Does the PR description match the actual diff? Flag surprises.
|
|
2. Read every changed file. Files outside the stated topic → flag with
|
|
"this file is not implied by the description".
|
|
3. Run the change locally if correctness isn't obvious from reading.
|
|
4. Block until justified: new deps, schema changes, env var additions,
|
|
auth-touching code, anything affecting persisted data.
|
|
5. Output critical findings (merge-blockers) last in the review summary
|
|
so they're visually distinct from minor comments.
|
|
|
|
### Merging
|
|
|
|
- Squash for feature branches.
|
|
- Final squash message follows commit format.
|
|
- Delete the branch on merge.
|
|
|
|
### Tagging (this repo)
|
|
|
|
Tags are dated: `<YYYYMMDD>`, with `-N` suffix for same-day reissues
|
|
(e.g. `<YYYYMMDD>-2`). Tag from `main`.
|
|
|
|
Rules:
|
|
|
|
- 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.
|
|
- Max one tag per day; use `-N` for same-day reissues.
|
|
|
|
Cut a tag:
|
|
|
|
```bash
|
|
git checkout main && git pull --ff-only
|
|
git tag -a <YYYYMMDD> -m "praxis <YYYYMMDD>: <summary>"
|
|
git push origin <YYYYMMDD>
|
|
```
|
|
|
|
Inspect:
|
|
|
|
```bash
|
|
git tag --sort=-creatordate
|
|
git show <YYYYMMDD>
|
|
git log --oneline <prev-tag>..<this-tag>
|
|
```
|
|
|
|
When to cut a tag:
|
|
|
|
- Rules changed in a way that affects how AI should behave on tasks.
|
|
- A skill was added, removed, or restructured.
|
|
|
|
When **not** to cut a tag:
|
|
|
|
- Typos, formatting, link fixes → just push to `main`.
|
|
- Drafts under discussion → use a PR.
|
|
|
|
Project repos in the workspace use their own tag schemes (typically
|
|
semver `vX.Y.Z`). Each project documents its own scheme in its own
|
|
`AGENTS.md`.
|
|
|
|
### Don'ts
|
|
|
|
- No `git push --force` to `main` / `dev` — ever.
|
|
- No `--no-verify` to 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 explicit
|
|
approval (Git LFS or out-of-band).
|
|
- No `git add .` / `git add -A` when untracked files are present that
|
|
weren't explicitly part of the task. 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`, not `config`. `runTask`,
|
|
not `taskRunner`.
|
|
- **Variables** — what they are, not their type. `users`, not
|
|
`userArray`. `retryCount`, not `n`.
|
|
- **Booleans** — `is*`, `has*`, `should*`. `isReady`, not `ready`.
|
|
- **Constants** — `UPPER_SNAKE_CASE` only at module level. Inside
|
|
functions, plain `const`.
|
|
- **No abbreviations** unless they're domain terms. `database`, not
|
|
`db`. (`req`/`res` in 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 counter` next to `counter++`
|
|
- `// 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/except` to 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:
|
|
|
|
1. **What is this?** One paragraph.
|
|
2. **How do I run it?** Bash blocks.
|
|
3. **How do I develop on it?** Code layout, conventions.
|
|
4. **Where does data come from / go to?** Only if non-obvious.
|
|
5. **Pointers.** Related repos, dashboards, docs.
|
|
|
|
Shorter than this is fine — drop sections that don't apply.
|
|
|
|
### 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. Skills catalog
|
|
|
|
Narrower SOPs live under [`skills/`](skills/). Each `SKILL.md` has a
|
|
YAML `description` frontmatter telling the AI **when to invoke it**.
|
|
The `using-praxis` skill is the bootstrap — read it first; it lists the
|
|
catalog with full triggering criteria.
|
|
|
|
Current skills:
|
|
|
|
- [`skills/using-praxis/`](skills/using-praxis/SKILL.md) — bootstrap,
|
|
iron-law / red-flags / catalog. Loaded automatically by the
|
|
`SessionStart` hook when the praxis plugin is installed.
|
|
- [`skills/git-upload/`](skills/git-upload/SKILL.md) — what to commit,
|
|
what not to, how to recover from leaked secrets.
|
|
- [`skills/nodejs-project/`](skills/nodejs-project/SKILL.md) — task
|
|
execution SOP for Node.js / Next.js projects (8 phases, includes
|
|
encoding checks).
|
|
- [`skills/debugging/`](skills/debugging/SKILL.md) — root-cause
|
|
investigation before any fix; 4-phase process.
|
|
- [`skills/verification/`](skills/verification/SKILL.md) — evidence
|
|
before completion claims.
|
|
|
|
A skill graduates from "this seems like a good idea" to a real entry
|
|
when **all three** hold:
|
|
|
|
1. Done the same way 3+ times.
|
|
2. Steps stable enough to write down.
|
|
3. Someone else would do it the same way given the spec.
|
|
|
|
Skill design rules: one skill, one job; verb-phrase name; description
|
|
field tells the model **when to invoke**, not what the skill does;
|
|
under ~300 lines.
|
|
|
|
---
|
|
|
|
## 6. Per-task spec
|
|
|
|
Before AI writes code on a task that touches more than one file:
|
|
|
|
1. Confirm or produce a 5-line spec.
|
|
|
|
```
|
|
Goal: <what should be true after this task>
|
|
Why: <one sentence>
|
|
Done when: <measurable acceptance>
|
|
Out of scope: <things explicitly not to touch>
|
|
Risks: <what could go wrong>
|
|
```
|
|
|
|
2. Put the spec at the top of the PR description (draft PR is fine)
|
|
**before** writing code.
|
|
3. Reuse the spec as the AI prompt when handing the task off.
|
|
|
|
After the task ships:
|
|
|
|
- Update the PR description to match what actually shipped (not what
|
|
was originally proposed).
|
|
- Lessons future tasks would want → Claude memory (feedback / project
|
|
types). See [Memory](#memory).
|
|
|
|
---
|
|
|
|
## 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 the [handoff checklist](#handoff-checklist) below. 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:
|
|
|
|
```json
|
|
{
|
|
"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's `v1.0`.
|
|
- A package without a README. Even a one-line README beats none.
|
|
|
|
### Receiving a handoff
|
|
|
|
1. Read the README first, fully. Resist running scripts.
|
|
2. Run the verification report. Fails → stop and message the sender
|
|
before doing anything else.
|
|
3. Note any surprise — naming, missing files, version mismatch — and
|
|
send back within a day. Drift gets worse with silence.
|
|
|
|
### Handoff checklist
|
|
|
|
Copy into the package (external handoff) or PR description (internal).
|
|
Fill it before declaring handoff done.
|
|
|
|
```markdown
|
|
## Identity
|
|
- Name:
|
|
- Version: <e.g. v0.5.0 or commit sha or tag>
|
|
- Generated at: <ISO timestamp>
|
|
- Source repo:
|
|
- Source commit: <full sha>
|
|
- Owner: <name>
|
|
- Recipient: <name or team>
|
|
|
|
## Contents
|
|
- [ ] README.md — what this is, how to use it
|
|
- [ ] CHANGELOG.md — diff vs previous version (or "first release")
|
|
- [ ] manifest.json — all fields filled or explicitly null
|
|
- [ ] VERIFICATION.md — what was checked, results
|
|
- [ ] Data / artifacts
|
|
- [ ] Scripts (only what's required to use the package)
|
|
|
|
## Verification
|
|
- [ ] Record / file counts match expected
|
|
- [ ] Checksums computed and recorded
|
|
- [ ] Sanity checks pass (list them)
|
|
- [ ] No secrets, .env, or credentials
|
|
- [ ] No PII unless explicitly part of deliverable
|
|
- [ ] Total size reasonable for delivery channel
|
|
|
|
## Reproducibility (external handoff only)
|
|
- [ ] Confirmed someone with repo access can rebuild from source_commit
|
|
- [ ] Build / generation command documented in README.md
|
|
- [ ] External dependencies pinned
|
|
|
|
## Provenance (if AI-assisted)
|
|
- Model used:
|
|
- Human-in-loop steps:
|
|
- Notable AI-assisted decisions:
|
|
|
|
## Known limitations
|
|
- <…>
|
|
|
|
## Recipient instructions
|
|
- [ ] Read README.md first
|
|
- [ ] Run verification report; if fails, stop and contact sender
|
|
- [ ] Confirm receipt within <X days>
|
|
- [ ] Report any surprises within <X days>
|
|
```
|
|
|
|
---
|
|
|
|
## Working directory expectations (this repo)
|
|
|
|
- This is a small docs-only repo. `Read` everything in scope before
|
|
acting; don't spawn a sub-agent for exploration.
|
|
- Don't introduce `package.json`, `Makefile`, CI configs, or other
|
|
toolchain files. There is no build/test/lint here.
|