Team PRD Workflow
The team's shared product requirements doc lives in the team-prd MCP workspace.
Multiple developers' Claude Code instances write here concurrently, so the
layout is structured to avoid write conflicts without needing a locking
protocol.
Layout convention
/prd.md # canonical spec (shared — append-only edits)
/inflight/<dev-handle>/*.md # per-dev work-in-progress (single-writer subdir)
/done/<YYYY-MM-DD>-<slug>.md # completed items (append-only log)
/questions.md # open questions (shared — append-only)
/CONVENTIONS.md # this convention doc (read before first use)
Rules for avoiding conflicts
- You only ever write under
/inflight/<your-handle>/. No exceptions for your own drafts. Never touch another developer's subdir. - Shared files (
/prd.md,/questions.md) are append-only. If you must revise an existing section, ask the user first, then usefile_replaceon a uniquely-identified block and add a<!-- revised by @<handle> YYYY-MM-DD -->marker. /done/is append-only. New files only — never rewrite existing entries.- Each shared section should carry a trailing owner marker:
<!-- @<owner-handle> last-updated-YYYY-MM-DD -->.
Establishing identity
Before any write, know the current developer's handle. Ask the user once:
"What handle should I use for you in the team PRD workspace?"
Remember it for the session. Use the handle as the subdir under /inflight/.
Starting a new work item
- Read
/prd.md— find the section the item belongs to. - Read existing files under
/inflight/to make sure nobody else is already working on it. - Create
/inflight/<handle>/<slug>.mdwith:- A one-sentence description
- A link/excerpt from
/prd.md - A "Plan" section with concrete steps
- A timestamp and owner marker
Marking an item done
- Read
/inflight/<handle>/<slug>.md. - Write
/done/<YYYY-MM-DD>-<slug>.mdwith the original content plus a "Completed" section summarizing what shipped. - Delete the inflight file.
Adding an open question
Append to /questions.md — do not rewrite. Format:
## <question title>
<!-- @<handle> YYYY-MM-DD STATUS: open -->
<question body>
When a question is answered, file_replace only the STATUS: open marker
with STATUS: answered (<answer-slug>).
Read-heavy reflexes
Before any write, re-read the relevant shared file. The workspace is live — state may have changed since you last looked.