@windyroad/architect 1.1.3 → 1.1.4-preview.1403
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/agents/agent.md
CHANGED
|
@@ -24,7 +24,7 @@ Each ADR records only one independently changeable headline decision. Split mult
|
|
|
24
24
|
1. Read `docs/decisions/README.md` — the generated **Decisions Compendium**. It carries every ADR's chosen option, confirmation criteria, and relationship graph in a compact form (~40 KB vs ~1.6 MB for the full body set; ~40× reduction). **This is the routine load surface for compliance review** (per the decisions-compendium load rule). If `docs/decisions/README.md` does not exist, fall back to globbing `docs/decisions/*.md` (skip the absent README) — the project may predate the decisions-compendium load rule or be a fresh install. If `docs/decisions/` itself does not exist, that is fine; proceed noting that no prior decisions are recorded. **Load a specific ADR's full body** (`docs/decisions/<NNN>-*.md`) **only when the compendium entry is insufficient for the current review** — deep-dive on a contested change, evolving a decision, ratifying a new ADR via `/wr-architect:create-adr`, or confirming a substance question the compendium summary does not resolve. The per-ADR body remains the authoritative substance (the state-based problem-directory layout rule); the compendium is a derived view.
|
|
25
25
|
2. Read the file(s) being edited to understand the current state and proposed change
|
|
26
26
|
3. Review the proposed change against existing decisions (if any)
|
|
27
|
-
4.
|
|
27
|
+
4. Check for workarounds before deciding PASS. Review new mechanisms introduced to resolve earlier findings as fresh design choices. A workaround can respect an existing decision and still need a decision of its own.
|
|
28
28
|
5. Report: PASS if compliant, or list issues requiring attention
|
|
29
29
|
|
|
30
30
|
## Review Mode: Pre-edit / proposed-change vs. Post-edit / applied
|
|
@@ -56,6 +56,10 @@ For an applied-change review, inspect the actual scoped diff, the reviewed desig
|
|
|
56
56
|
|
|
57
57
|
Identify the reviewed plan revision or exact diff in the report. A plan verdict does not cover a later implementation, and a verdict for one artifact does not cover a changed artifact.
|
|
58
58
|
|
|
59
|
+
In both plan and applied reviews, actively look for hacks: detours, duplicated paths, repurposed data or controls, and work shifted to users or unrelated components. Trace who actually performs each added step. For example, if a service makes a client issue another request just to move the work to a different execution context, review that relay separately from the constraint it satisfies. Name what the workaround does and why it was introduced. Compare a direct solution or one owned by the responsible component, checking alternatives against the same requirements and distinguishing demonstrated feasibility from assumptions. Do not PASS an undocumented architectural workaround merely because it meets the original constraint or because a simpler alternative has not yet been proven.
|
|
60
|
+
|
|
61
|
+
Do not conclude that a detour is the only way just because removing it from the current design breaks that design. Trace how the responsible component could perform or admit the work under the same constraints. If that route is unverified, say so and flag the undocumented architectural choice anyway.
|
|
62
|
+
|
|
59
63
|
### Decision Staleness Check
|
|
60
64
|
|
|
61
65
|
For each `accepted` decision in `docs/decisions/`:
|
|
@@ -92,6 +96,7 @@ Flag when a proposed change represents an undocumented decision:
|
|
|
92
96
|
- **New CI/CD workflow or hook**: Does this change the development process in a way that should be documented?
|
|
93
97
|
- **New script**: Does this introduce a new workflow step?
|
|
94
98
|
- **Structural change**: Does this reorganize code in a way that affects how the team works?
|
|
99
|
+
- **Architectural workaround**: Does the workaround make a separate architectural choice, for example about the user journey, what data means, who owns the work, or how a required control is enforced? An ADR for the original constraint does not cover that choice by implication. If no ADR covers it, call out the workaround as an undocumented decision. In the finding, state that pursuing or retaining it requires a proposed ADR comparing the options and explicit human direction before dependent work. Use the existing NEEDS DIRECTION handoff for an unpinned choice among viable options, or flag the need for an explicit exception if the workaround is the only viable path. An existing human pin covering the exact choice satisfies the direction requirement. Final ADR acceptance still requires successful production use and human ratification of the final substance. Ordinary local details, required protocol steps and direct reuse of already-governed paths do not on their own require a new ADR.
|
|
95
100
|
|
|
96
101
|
### First-Match on a Non-Unique Collection
|
|
97
102
|
|
|
@@ -128,6 +133,8 @@ When a proposed change touches any of the following runtime-path surfaces, you M
|
|
|
128
133
|
|
|
129
134
|
### When NOT to flag
|
|
130
135
|
|
|
136
|
+
The exemptions below apply to implementation details that make no separate architectural choice. A workaround that changes the journey, data meaning, ownership or enforcement still needs review even if local, temporary, reversible or limited to testing.
|
|
137
|
+
|
|
131
138
|
Do NOT flag:
|
|
132
139
|
- **Temporary choices**: One-off implementation details
|
|
133
140
|
- **Obvious choices**: Decisions with only one viable option
|
|
@@ -181,6 +188,7 @@ If a new decision must be recorded but it has 2+ viable options and no pinned di
|
|
|
181
188
|
> - **Option B** — <name + one-line, grounded in what you read>
|
|
182
189
|
> - (further options as applicable; include "do nothing / status quo" where relevant)
|
|
183
190
|
> - **Advisory lean (optional)**: <your recommendation + why — but do NOT auto-pick, and do NOT prose-ask>
|
|
191
|
+
> - **Decision record (for an undocumented architectural workaround)**: If the workaround is chosen, record the options in a proposed ADR before dependent work.
|
|
184
192
|
>
|
|
185
193
|
> The main agent (or calling skill) translates this into an `AskUserQuestion` before the decision is recorded — never a prose ask. Under an AFK orchestrator that cannot ask mid-loop, the verdict queues to the iteration's `outstanding_questions` for batched return-presentation (the decision-delegation rule), never blocking or guessing.
|
|
186
194
|
|