CLAUDE.md

Instructions for Claude Code agents in this repo. History and rationale for these rules live in docs/internal/architecture/decisions/claude-md-history.log; this file holds only the rules.

Role and session log

If PM assigns a role, read its briefing in docs/briefing/ and use its log slug. If no role is assigned, you are a general agent (slug code); ask PM if the task needs a role.

Tiers and lanes: docs/briefing/ROSTER.md.

Session log: dev/YYYY/MM/DD/YYYY-MM-DD-HHMM-{slug}-log.md. All dates, times and filenames are Pacific time: run TZ=America/Los_Angeles date and never guess a timestamp. It is the only durable log (a cycle log in dev/active/ is optional scratch). One log per role per day; record the model in its header. Create it (skill create-session-log) before any other work, even for a greeting. After compaction, resume that log; it is how you recover your role. If you can't find it, stop and ask PM.

State you don't remember creating (commits, a changed cron, file edits) is most likely your own work from before a context gap. Check your session log first; use list_sessions only if doubt remains.

Near compaction, keep your rigor; the session log, mail and skills carry you across.

Session start

1. Create or resume the session log.
2. Read mailboxes/{role}/inbox/ (skill check-mailbox).
3. Read the "Now" section of docs/briefing/BRIEFING-CURRENT-STATE.md (not the history below it).
4. Read docs/briefs/cross-pollination/current.md.
5. Confirm you're in your worktree and on your branch, not main in the shared checkout.

The SessionStart hook prints a short status (log, mail, briefing freshness, role). If it says BRIEFING: STALE, or the briefing is visibly behind recent logs and commits, refresh what you can attest with skill update-current-state before other work. A partial refresh is better than none.

Before reading git or file state to answer a question or start work, git fetch and fast-forward if more than a few minutes have passed. A sync from earlier in the session is stale.

Worktrees

• Amber (cohort host): your stable worktree ~/Development/piper-morgan-worktrees/{role} on claude/{role}-cycle, reused every session (Claude Code keys state to the path). Check git rev-list --count HEAD..origin/main is 0 before working.
• Claude Desktop: the ephemeral worktree Desktop creates.
• Never work in the shared checkout ~/Development/piper-morgan-product.

Lifecycle: docs/internal/operations/amber-worktree-lifecycle.md.

Hard rules (data loss, exposure, irreversible changes)

1. The shared checkout ~/Development/piper-morgan-product (on Amber and PM's Mac: /Users/xian/Development/piper-morgan-product) is PM's live workspace with uncommitted edits. Never run there: git checkout -- <path> or ., git reset --hard, git stash, git clean, or anything else that discards working-tree changes. If a merge or rebase there is blocked by unstaged changes, stop and push from your own worktree instead.
2. Before any git checkout <ref> -- <path> anywhere, run git diff HEAD -- <path>. If it is non-empty you are about to discard uncommitted work; read it and decide which side is stale. Clear MANIFEST noise only by your own role's explicit path.
3. Never write a bearer credential (invite code, API key, token) in full in any committed file. This repo is public. Use the masked form ABCD…WXYZ. A credential that reached git history must be rotated.
4. Projects v2: never send updateProjectV2Field with a partial singleSelectOptions list; it replaces the whole list and wipes assignments. Use skill assign-sprint-safely.
5. A commit message that pairs close/fix/resolve with #N closes issue N, whatever the surrounding words. Write the number without #, or add the trailer Auto-Close: intentional when closing is intended.
6. Memory in ~/.claude-pm/ is shared and has no git history. Export it to a tracked file before any prune or delete.
7. For any action with no undo (volume delete, rm -rf, force-push, bulk update), first check whether the narrow reversible step still works, and whether an API call is additive or full-replace.
8. Never write an outside person's name, address, employer or words into this public repo: files, filenames, commits, mail, logs, rollups. Use a role label ("an alpha tester"). When the detail matters, write it in a private repo (designinproduct docs/mail/, -private- in the filename) and leave a name-free pointer here. Outside means anyone but xian and his agents; the one exception is xian's Piper Morgan advisor. Report old mentions to Exec; don't remove them (a history rewrite is xian's call). Rule page: designinproduct docs/conventions/people-details-stay-private.md.

These are backed by guards where noted in docs/internal/operations/github-and-tooling-gotchas.md; guards are advisory and bypassable, so the rule still applies. Scope is not direction: a narrow path list does not make an overwrite safe.

Git, push, sign-off

• Commit from your worktree and push finished units to main as you go: git push origin HEAD:main. Work not on origin/main is invisible to other agents.
• Commit the session-log entry for a unit with that unit.
• At idle points, run scripts/sync-pm-local.sh to fast-forward PM's checkout (it never touches PM's prose edits).
• After subagent work, run git status and stage or explain any modified files left in services/, tests/, web/.
• Stage in one call, commit in the next: the mailbox hook reads the index before a compound git add && git commit runs.

Sign-off (paste the output in your log):

git status
git fetch origin main
git rev-parse --verify -q origin/main >/dev/null || echo "STOP: origin/main did not resolve; the check below did not run"
git log --oneline origin/main..HEAD   # must be empty

If it is not empty: git fetch origin main && git merge origin/main && git push origin HEAD:main, or leave a NOTICE memo saying why the work is held, or ask PM. Before going dark on purpose (migration, stand-down), park your row in dev/active/duty-cycle-registry.tsv with a checkable clearing condition.

Mail

• Write memo, cc copies and sent mirror under mailboxes/, then send with scripts/mail-send.sh "mail({role}): {subject}" <every changed path>. Don't git add or commit mailbox files yourself. Details: docs/internal/operations/branch-worktree-mailbox-discipline.md.
• Routing: mailboxes/DIRECTORY.md. Every memo's frontmatter carries reply-to: piper-morgan-product:mailboxes/{your-slug}/inbox/; reply to the memo's reply-to.
• Never cc PM and never address mail to PM (the mailboxes/xian (ceo)/ box is retired). Anything that needs PM (a decision only PM can make, a relayed PM ruling, something PM would contradict) goes to exec, with which of the three in the subject.
• Mail to an agent outside this repo (Janus, Pard, Dispatch, …) goes to that agent's home repo: look it up in ~/Development/dispatch/CLAUDE.md §"Mail routing" and send it with scripts/mail-send-external.sh, never a hand commit. Steps: mailboxes/DIRECTORY.md.
• Write date: now in a memo's front matter: mail-send.sh and mail-send-external.sh stamp the clock, refuse a stamp ahead of it, and add the session's attribution trailers.
• Mail asks another agent to act; a GitHub comment records something about the work.

Working rules

• STOP and ask PM when: infrastructure doesn't match the plan; tests fail; the thing you're building already exists (complete it); you can't produce evidence; the issue is missing; an ADR conflicts; user data is at risk; you want to defer work; you catch yourself claiming done without proof; you find work about 75% complete (report it). PM decides what is critical.
• Done means a user can use it, tests exist and pass, evidence is on the issue, and your log is updated. Passing tests alone is not done.
• Evidence. Every completion claim (memo, issue closure, report) carries Verified how: with the method you ran this time, the layer it measured (a curl 200 is not a render test), and the denominator (what it covered out of what exists). Close issues with skill close-issue-properly (description first, then comment, then close).
• Don't guess facts. Look up names, credentials, config, counts and history, and quote the output in the same turn; otherwise say "unverified".
• Investigate before extending. Read the whole issue, memo or module before acting on part of it. GitHub is the source of truth for issue status.
• Discovered work: file it immediately with gh issue create; list filed issues at wrap-up.
• Deferral needs a named trigger (a fresh session or a compaction, with the reason). Rows in dev/active/{role}-standing-items.md carry a Filed column or a **Filed**: YYYY-MM-DD line so scripts/aging-standing-items.sh can read them.
• Duty-cycle fires wake you to check for work. Drain all unblocked work in priority order; commit at each unit but don't stop there. Procedure: skill duty-cycle-tick.
• Honesty. Give your actual assessment and call out mistakes, including PM's.
• Decisions other agents will need: an ADR in docs/internal/architecture/adrs/ or a PDR in docs/internal/product/pdr/, or a line in docs/internal/architecture/decisions/decisions.log. Session logs are not the cross-session record.

Subagents

• Brief with role, task, issue, acceptance criteria and expected evidence (skill brief-coding-agent).
• Set the model parameter explicitly and record the tier in your log entry: Haiku for fully specified mechanical work, Sonnet for bounded implementation, Opus for hard reasoning inside the unit.
• Quick search subagents report back; implementation subagents keep their own session log.

Code conventions

• API routes use /api/v1/ (exceptions: docs/internal/architecture/current/web-routes-conventions.md).
• New action handlers register a WorkflowEntry(..., action_triggered=True) in services/intent_service/workflow_entries.py; never add an elif intent.action branch. Lower MAX_DISPATCH_SITES when you migrate one.
• A new failing phrasing gets a corpus row, not a new extraction regex (TestExtractionPatternRatchet).
• Read docs/internal/architecture/current/intent-routing-stack.md before touching classification, dispatch or chat responses, and update it if your change makes it stale.
• Read knowledge/piper-morgan-glossary-v1.1.md before writing about Plugin, MCPB, Connector, Extension, Skills, Cowork or Claude Desktop.

Quick reference

python main.py                    # server, port 8001 (entry point; not web/app.py)
python -m pytest tests/unit/ -v
docker compose up -d && alembic upgrade head   # Postgres 5433
./scripts/fix-newlines.sh         # before committing

Ports: server 8001, Postgres 5433, Redis 6379, ChromaDB 8000. Domain models services/domain/models.py; enums services/shared_types.py; config config/PIPER.md (config/PIPER.user.md is an optional, often absent overlay).

From a Claude Code shell, start the server with the inherited Anthropic vars stripped, or every LLM call fails:

env -u ANTHROPIC_API_KEY -u ANTHROPIC_BASE_URL -u ANTHROPIC_AUTH_TOKEN -u ANTHROPIC_CUSTOM_HEADERS \
  POSTGRES_PORT=5433 nohup venv/bin/python main.py > /tmp/piper-server.log 2>&1 &

A local server also needs JWT_SECRET_KEY set, or main.py refuses to start: export JWT_SECRET_KEY=$(python -c 'import secrets; print(secrets.token_urlsafe(32))').

Deploys come from origin/main (origin/production is stale; don't cite it); for what is live, check the running host's commit. Store app credentials with KeychainService, not the security CLI.

Repository: https://github.com/mediajunkie/piper-morgan-product.

More detail when you need it