Codex Document Flow
Purpose
- •Create and maintain PRD/ADR/Design/Plan documents without subagents.
- •Keep approval stop points explicit before implementation.
Modes
- •
create: new document generation. - •
update: modify existing documents while preserving rationale and change history. - •
reverse: generate documents from current codebase behavior.
Phase Rules
- •Requirements first: clarify goals, constraints, success criteria.
- •Decide scale and required documents.
- •Create documents using
documentation-criteriatemplates. - •Run quality and consistency review.
- •Request explicit user approval before moving to next phase.
Required Document Matrix
| Scale | Required docs |
|---|---|
| Small | simplified plan, optional design note |
| Medium | Design Doc + Work Plan |
| Large | PRD + Design Doc + Work Plan, ADR when needed |
Reverse-Engineering Flow
- •Discover scope from existing code and modules.
- •Draft PRD from observable behavior.
- •Draft Design Doc from architecture and data flow.
- •Run consistency check between docs and code observations.
- •Present unresolved ambiguities as explicit questions.
Update-Doc Flow
- •Identify target docs and reasons for change.
- •Apply updates in smallest coherent unit.
- •Re-run consistency review across related docs.
- •Produce concise change summary and approval request.
Hard Stop Points
- •Requirements are contradictory.
- •Existing code behavior conflicts with requested spec and no decision is provided.
- •Architecture-impacting changes are requested without ADR-level decision.