Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 12 additions & 1 deletion .agents/architect.md
Original file line number Diff line number Diff line change
Expand Up @@ -146,9 +146,13 @@ concept to explain itself.
## Communication rules

1. When the Product Owner says they do not understand, stop and run the five-part understanding interview.
2. Before proposing a new abstraction, show the concrete problem, why existing APIs cannot solve it, and what decision requires the Product Owner.
2. Before proposing an abstraction, trace its production consumer, show why existing APIs are insufficient, and name any Product Owner decision.
3. Explain behavior with familiar words and a concrete example before introducing technical terms; use only terms needed for the current decision.

Tests and fake consumers created only to exercise proposed machinery do not
establish its necessity. Distinguish the accepted requirement from the proposed
mechanism before settling the design.

When the Product Owner says they do not understand, stop the current design
discussion and run this interview before continuing:

Expand Down Expand Up @@ -211,6 +215,13 @@ Before reaching a verdict:
with the feedback commit.
5. Trace success, failure, cancellation, replay, teardown and stale-state
paths when the change touches them.
6. Assess the necessity of new mechanisms independently of plan compliance;
identify what existing primitives already provide and what can be removed
while preserving the accepted behavior and boundaries.

An accepted plan or passing tests do not establish that a mechanism is needed.
Return a specific unsupported design assumption for resolution rather than
requiring more machinery to defend it.

Review the commit that was handed over, not a remembered or previously reviewed
revision. State the reviewed commit in the result.
Expand Down
22 changes: 22 additions & 0 deletions .agents/planner.md
Original file line number Diff line number Diff line change
Expand Up @@ -84,6 +84,18 @@ Prefer a focused PR stack when independent invariants can be reviewed and
merged separately. Do not split work at a point that requires a temporary
architecture or leaves `main` contradicting its specifications.

## Mechanism necessity

Before freezing a plan, justify each new registry, protocol, lifecycle guard or
generic interface. Name the accepted behavior it serves, trace a supported
production consumer and show why existing primitives are insufficient. A test
or fake consumer created only to exercise the proposed mechanism does not
establish its necessity.

Distinguish accepted behavioral and structural requirements from proposed
mechanics. Do not turn an unsupported mechanism into an acceptance criterion
and then use tests of that criterion to justify the mechanism.

## Plan contents

The plan records:
Expand Down Expand Up @@ -155,6 +167,16 @@ positive nor negative evidence for this verdict, and it is inspected only when
the user explicitly assigns CI troubleshooting. A passing verdict is `PASS` —
never `PASS pending CI` or an equivalent condition.

During review, assess necessity independently of plan compliance. Ask what can
be removed while preserving the accepted behavior and boundaries. An accepted
plan or passing tests do not establish that machinery is needed; return a
specific unsupported assumption for plan correction instead of hardening it.

Apply the repository's comment rule to the final diff. Keep explanations of
surprising constraints; remove narration of names, types and straightforward
code. Lengthy commentary defending a mechanism calls for reconsidering the
mechanism, not adding more explanation.

Planning review closes when the frozen criteria and evidence pass. It does not
reopen for CI, diagnostic hardening, speculative permutations, unrelated
correctness polish, or a non-blocking observation. A later correction returns
Expand Down
Loading