Documents
Two documents anchor every Synthex project: the Product Requirements Document and the Implementation Plan. They are checked into the repository, peer-reviewed by AI agents, and updated continuously — never throwaway artifacts.
Product Requirements Document (PRD)
The PRD lives at docs/reqs/main.md (configurable via documents.requirements in
.synthex/config.yaml). It captures the why of the work: who is the user, what is the
problem, what does success look like, what is out of scope.
A PRD authored by Synthex is structured to make ambiguity visible. It includes:
- Context — the user, the problem, the current state, the desired state.
- Goals and non-goals — what success means; what we are explicitly not trying to do.
- Success metrics — measurable, time-bounded outcomes.
- Constraints — regulatory, technical, organizational, time/budget.
- Acceptance criteria — typed (
[T]/[H]/[O]) so the implementation phase has a contract to verify against.
How it gets written
refine-requirements/synthex:refine-requirements drives a structured PM-led interview. The Product Manager agent prompts for missing information, then runs the draft through a peer-review loop with the Tech Lead and Designer to surface unstated assumptions and untestable claims. The loop exits when severity-high findings are addressed.
The PRD is the input to write-implementation-plan/synthex:write-implementation-plan — every plan task points back to a requirement, so a misshapen PRD produces a misshapen plan.
Implementation Plan
The implementation plan lives at docs/plans/main.md (configurable via
documents.implementation_plan). It converts the PRD into a milestone-and-task structure that
parallel agentic execution can chew through.
A plan authored by Synthex contains:
- Phases and milestones — phases group milestones; milestones group tasks.
- Tasks — each with a complexity estimate, dependencies, and one or more acceptance criteria.
- Decisions table — architectural and product decisions made during planning, with rationale.
- Open questions — explicit unresolved items with proposed defaults.
- Parallelizable batches — which tasks can run simultaneously per milestone.
- Observational outcomes —
[O]metrics tracked at the milestone or phase level.
How it gets written
write-implementation-plan/synthex:write-implementation-plan takes the PRD and drafts the plan. The PM leads; the Architect, Designer, and Tech Lead review in parallel. The PM addresses severity-high findings until the loop exits. The plan is the system of record for the remainder of the project — every next-priority/synthex:next-priority run reads it, picks unblocked tasks, executes them, and writes back completion notes.
What evolves
The plan is not frozen. Completion notes append to it iteratively. Discoveries, blockers, and decisions made during execution are recorded inline with the relevant tasks. This makes the plan auditable in either direction: you can read forward (what's next) or backward (why did we do that).
Two documents, one chain
Together, the PRD and the plan form the contract between intent and execution:
PRD (docs/reqs/main.md) ───────► Plan (docs/plans/main.md) ──────► Code
"what & why" "how & when" "the change"
Every code change traces back to a plan task, every plan task to a requirement, every requirement to a stated user, problem, and success metric. When the chain holds, the project is auditable. When it breaks, you know exactly where.