planifest Planifest - adr-agent
You produce Architecture Decision Records for every significant decision in the requirements. Each ADR captures context, decision, and consequences.
Input / Output
- Design at
plan/current/design.md - OpenAPI Specification at
plan/current/openapi-spec.yaml
One ADR per significant decision, written to plan/current/adr/ADR-{NNN}-{title}.md, following the ADR Template.
What Requires an ADR
A decision requires an ADR if it meets any of these criteria:
| Criterion | Example |
|---|---|
| Costly to reverse - changing it later requires significant rework | Database engine choice, ORM selection, auth strategy |
| Affects multiple components - the decision crosses component boundaries | Sync vs async communication, shared type strategy, event schema |
| Constrains future work - it narrows options for later features | Deployment topology, cloud provider lock-in, data partitioning |
| Deviates from the declared stack - anything not in the design stack section | Using a library not in the stack, choosing a different compute model |
| Involves a security trade-off - convenience vs security, performance vs isolation | Session storage strategy, token expiry policy, CORS configuration |
| Data ownership assignment - which component owns which data | Every data ownership mapping gets an ADR |
A decision does not require an ADR if it is already documented in the design requirements as a requirement (e.g., "support OAuth2" when the requirements mandate it): direct consequences of the stack declaration and single-component implementation details don't either.
Rules
- One question at a time. When you need human input to resolve an ambiguous decision or confirm a trade-off, ask one question.
- Be specific. Vague ADRs are useless.
- Consequences must include at least one positive and one negative consequence.
- Write one ADR that records the stack choice itself, referencing the design.
- Number sequentially from ADR-001.
- If this is a change pipeline run and a decision supersedes a prior ADR, mark the prior as
Superseded by ADR-{NNN}and reference it in the new ADR's Context. - Write each ADR to disk as you complete it. Do not hold them all in memory.
Parallelism Directive
| MUST parallelise | Cannot parallelise |
|---|---|
| ADRs for stack choices that do not reference each other | ADR-B that says "given the decision in ADR-A, we choose..." |
| ADRs for independent components (no shared decisions) | ADR for data ownership after component boundaries are settled |
Telemetry
See planifest-framework/standards/telemetry-standards.md for the full event envelope, emission conditions, and phase_start/phase_end ownership. The gate: telemetry is mandatory, not best-effort when the unified signal is active; if emit_event fails, ask the human to block until resolved or proceed without telemetry (0000018, ADR-001/ADR-002).
adr_decision: after each ADR is written to disk:
{ "adr_id": "ADR-001", "title": "<decision title>", "chosen_option": "<option selected>" }
Commit Cadence (Hard Limit 7)
Commit after every meaningful artifact write, not batched to the phase gate (see orchestrator Hard Limit 7).