Architecture Quality Loop - Analyze, Assess, Improve (Deliberate)
You drive a deliberate loop that improves a project's architecture: analyze it, get a reasoned assessment, work the fixable weaknesses by tier, reconcile the map, and loop until the fixable ones are resolved or the loop plateaus. The assessment itself is never yours to write or prune - a separate deliberate capture recomputes it fresh every round. The measurements behind these rules live in references/evidence.md - an audit appendix, not a run-time load.
On a large codebase, scope it - point it at one bounded context or module subtree per run. This skill carries NO model pin and asks for no model switch: the judgment runs in-session, on the session's model, per the capture (a skill-level pin lasts only for the turn it activates in; measured: Sonnet at xhigh matched Opus on a capture at the same cost).
When to use
- The deliberate architecture loop, run only by its slash command: structural weaknesses are flagged for a user decision, never auto-applied, and a decision the run turns up is proposed, never written.
- Not for a code-quality polish (loop-code-quality), a single feature build (task-solve-cross), a capture-only run with no fixes (/capture-awareness architecture alone), or test-suite and coverage weaknesses - the deliberate coverage analyze-and-improve loop covers those.
Modes. Mode flags right after the command - --mode-auto-run-on, --mode-auto-run-off, --mode-output-scorer-on, --mode-output-scorer-off - are switches, not the request: strip them; with only flags typed, run as with no arguments. Under the hook's auto-run contract, follow it. With no hook line (hooks off, Cursor), -on holds for this run only: each stop takes its (Recommended) option, listed in the close, an unmarked one waits, nothing goes outward, no fresh-session hand-off, and the close says auto-run ended; --mode-output-scorer-on grades this run's output like a typed stack. A typed 'no stops' or 'run it without asking me' is no waiver in this flow: say in one line that --mode-auto-run-on right after the command turns auto-run on, and never hand-write an AUTO line.
Execution modes
DELEGATED vs INLINE keys on dispatch capability, not file presence - a project can carry the agent files on disk with no Agent tool to dispatch them, which is still INLINE. Detection only names what is possible; the user picks: when dispatch is available, ask ONE question before ANALYZE and hold the answer for the run; the mark sits on the mode the habits-execution-strategy verdict picks (parallel seats moves it to the seats, listed first):
Run this loop here or through the stack seats? <the verdict's reason>
- 'In this session (Recommended)' - <why it fits one chat>
- 'Dispatch the stack seats' - <the fixes that run in parallel>
No dispatch capability is INLINE without asking - never offer seats that cannot run. Every AskUserQuestion below falls back to plain-text options where the harness lacks the tool.
- DELEGATED (the user chose agents) - the main session dispatches every seat, exactly as the roster spells it (
alfred-code:<seat>where the core plugin carries it) - architecture-analyzer for the capture's gathering, then the domain designer / implementers / verifier for a substantial fix, or an implementer for a small one - never doing their work itself. This skill stays the orchestrator - a substantial fix dispatches that stack's seats directly, never a re-entry into the full router. - INLINE (the user chose the current session - or forced, no question asked: no dispatch, a non-stack project, a scope too small to fan out) - the same steps in-session: map and assess against the house architecture skills yourself, then apply the fixable cons directly, smallest blast radius first.
Substantial and structural changes are gated on user approval before building; small localized fixes proceed. In DELEGATED mode, the mode ask's answer IS the dispatch consent for small-tier fixes: write the <data root>/state/approvals/loop-architecture-quality/APPROVAL stamp (APPROVED small-tier - "<the answer, verbatim>") the moment that answer lands (under auto-run the hook's AUTO stamp already stands - leave it), and rewrite it as substantial-tier approvals arrive - the dispatch guard is deliberately tier-blind, so an unstamped small-tier dispatch just bounces. On a RESUMED session no mode ask fires - the small-tier stamp then quotes the RESUME BLOCK's own dispatch line (APPROVED small-tier - resumed round <N>, "<the block's mode line, verbatim>"), never repurposed task framing. The mode answer covers the WHOLE round - a DELEGATED round's fixes go to the seats, its lens sweeps to analyzer seats; working a fix inline under a DELEGATED answer, or scoping the ask to just the analyze step, leaves the round's real work with no mode decision at all.
The loop
1. ANALYZE + ASSESS
Two captures, in order, both Skill calls: first capture-awareness with architecture <DELEGATED|INLINE> <target> - the run's mode, then the target - for the map (its own UPDATE path is diff-scoped and cheap where the stamp already matches HEAD). Then capture-quality with architecture-quality <DELEGATED|INLINE> <target> - the run's mode, then the target (it judges weaknesses, strengths and tiers over the map, the code and the decision log, recomputing <docs-path>/quality/ARCHITECTURE-ASSESSMENT.md fresh - it carries no zero-drift shortcut of its own, because nothing about that doc is cached, so it always runs in full - one exception, below). Hand each capture the run's mode and TARGET only - never a status of the findings (which shipped, which remain): the findings capture recomputes them from the code, and a status brief turned a reconcile into a patch of the old file. Past the fresh-session trigger (the resolved window's own absolute figure - 400,000 tokens on a window of 1M or more, 280,000 on one of 300k up to 1M, 180,000 on any other and on one that cannot be read at all) a Skill call the fresh-session guard blocks is the gate working, not a fault - on 'continue', re-issue the same Skill call: the answered offer lets it through until the context grows 1.5x past it:
The fresh-session guard held the capture at <N>k; a fresh session restarts at <M>k.
- 'Resume in a fresh session (Recommended)' - this turn ends with the RESUME BLOCK
- 'Continue here' - the same Skill call again
The exception: round 1 of a run whose assessment's As of: sha is HEAD, on a clean tree, with no decision record newer than the assessment, may take it as the work list - through the reuse ask in references/loop-mechanics.md (that section only), put before the findings capture or any of its references is read; the end-of-loop reconcile still runs in full.
The findings capture's output is this loop's work list: <docs-path>/quality/ARCHITECTURE-ASSESSMENT.md's Must-fix weaknesses - each with a remediation and a tier, small / substantial / structural; counts are outputs, never targets - the tier being the routing key. The Worth-knowing and Deliberate-tradeoff buckets are left alone - do not 'fix' a conscious choice, and a Must-fix entry you decline this round goes on the in-run declined set (step 2) rather than being re-asked about again before this run ends.
When the work list is drained (or a later round wants findings the last run missed), run a lens sweep instead of re-running the findings capture - Read the lens-sweep section of references/loop-mechanics.md first: it owns the lens choice, the one-lens-per-seat brief and the map-orientation rule. Findings triage into the same tier routing as the capture's own weaknesses.
2. TRIAGE + FIX by tier
Take the open weaknesses in leverage order (the assessment's top-few first) and confirm the green baseline (build + tests) before you start, so a regression is visible - round 1 also records the sweep baseline (HEAD, or the git stash create sha on a dirty tree). A user preference's breach (its rule ARCHITECTURE-PREFERENCES.md#a<n>) is fixed like any other; one whose fix sweeps many modules - wrap every external package - is structural, taken one module per round. Hold every fix against the assessment's Strengths list: a remediation whose entry names a strength tension is applied the way the entry preserves the strength, and a fix that turns out mid-round to erode a listed strength stops - a genuine strength-vs-weakness tradeoff is a structural-tier user decision, never an auto-fix. Route each by its tier:
small (a localized edit) - dispatch the matching domain implementer with the remediation as a scoped brief - shape in
references/loop-mechanics.md; it statesnote: noneunless it hands a note, which it then names literally, read side included. Re-run build + tests.substantial (a designer-led multi-task change) - five steps in order, none of them optional:
Decompose - dispatch the domain solution-designer to turn the remediation into a decomposition.
Gate the plan -
task-verify-plan, an actual Skill invocation, recording itsPasses:line.Get the user's approval on that plan before building - never fan out against an unapproved plan. Present the plan, then:
<plan id>, <N> tasks. Build it? - 'Approve and build (Recommended)' - stamp, then fan out - 'Changes needed' - I ask what to change next, in plain textStamp the approval, in four parts:
Shape - write
<data root>/state/approvals/<plan id>/APPROVAL(<plan id>is this loop's own,loop-architecture-quality), first lineAPPROVED <plan id> - "<the user's words, verbatim>"(under auto-run the hook'sAUTOstamp already stands - leave it); the selected answer IS those words. The dispatch hook blocks an unstamped implementer; delete the file when the run completes. A question the idle timeout closed is no answer: its result opens 'No response after' and says the user may be away from keyboard, even when it carries an option already selected - write no APPROVED or AUTO line from it; re-ask, or stop and say what waits.Path - Write the stamp at the ABSOLUTE path
<project root>/<data root>/state/approvals/<plan id>/APPROVALwith the Write tool, and give every implementer brief the lineplan: <plan id>- the dispatch hook passes a brief only on its own plan's stamp. A relative write follows whatever cwd the shell drifted to, and the dispatch then bounces.Ownership - the stamp belongs to the session that dispatches, written when its own decision lands and deleted at its own close; an earlier session's leftover stamp is not consent.
Refused - if BOTH the Write tool and an absolute-path Bash write are refused by the harness's classifier, stop and ask rather than retrying blind or dispatching around the gate:
Both write routes refused the approval stamp: <the refusal>. - 'Retry the stamp (Recommended)' - allow the write at the prompt - 'Run this fix inline' - no dispatch, no stamp
Build and verify - fan the tasks out to the domain implementers, then gate the assembled result with the domain verifier, looping its punch-list back. This is the domain-trio vertical (this skill's own
references/domain-trio-protocol.md), dispatched directly.
Re-tier only through the ask: when the designer's findings SHRINK the item ('this is actually small'), the re-tier still routes through this ask before any implementer dispatch - a self-declared downgrade that proceeds on the old small-tier stamp is the silent-downgrade this tiering forbids:
The designer reads <weakness> as small: <why>. - 'Keep it substantial (Recommended)' - the gated plan stands - 'Re-tier to small' - one implementer, scoped briefstructural (a risky, cross-cutting rework) - do NOT auto-apply. Present the weakness, its reasoning, and the remediation, then ask:
<weakness> is structural: <the remediation>. - 'Defer (Recommended)' - <why it can wait> - 'Apply - routes as substantial' - <what it touches> - 'Decline' - <the tradeoff kept>A structural rework the user has not approved is flagged in the final report, not attempted. decline or defer adds the entry to this run's declined set - an in-context list only, never written to a file: the same weakness reappearing later this run (a lens sweep, the next round's fresh capture) is checked against it and skipped without a second ask. The set holds for this run alone - it is not written anywhere, so a fresh session (or a genuinely new run later) starts clean and may ask again; that reappearance is correct, not a bug, because an undecided weakness genuinely is still undecided until someone writes it to the decision log.
Keep the build and tests green across the round: after each fix batch, re-run them, and a red routes, in DELEGATED mode, to the matching build- or test-failure resolver seat where the project installed one, before the next weakness. INLINE, or with no matching seat installed, fix the red in-session before moving on - never carry a red into the next weakness.
3. LOOP or STOP
Read references/loop-mechanics.md now - the RESUME BLOCK shape and the final report's field rules are this step's gate, not homework; the report's Mechanics line is the receipt. Decide off the weakness set the findings capture returned this round - it is already in this context; do not re-run that capture mid-decision just to re-read it. On a LOOP verdict, run the fresh-session ask (Bounded and honest) before the next round. The round verdict line carries the ask's receipt - next: fresh-session | continue - "<the user's answer, verbatim>" - and that receipt can only come from the AskUserQuestion answer; a verdict line without it is an unfinished step 3. Decide off the set, not by eye:
- SATISFIED - no fixable (small/substantial) weakness remains; only accepted tradeoffs and user-declined structural items are left.
- PLATEAU - the fixable-weakness set equals the previous round's and none is now resolvable - stop rather than re-run identically.
- CAPPED - you reached the improve-round cap (see Bounded and honest).
- BLOCKED - only structural weaknesses remain and the user has not approved a rework - report and stop.
On STOP, when any fix shipped: after the final build + tests, Read references/anti-gaming-sweep.md and run its sweep - a gamed bar is a BLOCKER, reverted and fixed. Then reconcile ONCE: run capture-awareness with architecture <mode> <target> (its UPDATE path - the diff since the Captured stamp) so the map picks up the shipped boundaries, then capture-quality with architecture-quality <mode> <target> again so <docs-path>/quality/ARCHITECTURE-ASSESSMENT.md reflects the code as it now stands (this run's declined set still applies - it does not re-ask about what was already declined this run). When this session is already past the fresh-session trigger, the same fresh-session choice above applies before either capture runs. This reconcile is the step, not a suggestion: substituting anything lighter (a 'targeted reconcile', a hand edit) goes through this ask first - a substitution offered back in prose is a skipped mandatory step wearing a courtesy:
The reconcile reruns both captures; <the substitute> covers <what>.
- 'Run the reconcile captures (Recommended)' - both docs match the code
- '<the substitute>' - <what it leaves stale>
A run that shipped nothing skips the sweep and the reconcile - there is no drift to pick up. Then emit the final report - one line per field, a table where a field lists several items - with the fields references/loop-mechanics.md defines: Outcome (verdict + round), Resolved, Deferred, Proposed decisions, Docs (which captures ran at stop, or skipped - nothing shipped), Baseline, Anti-gaming, Notes (notes purged: <names|none>, fold-first), Next actions, Mechanics (loop-mechanics.md: read - the receipt for this step's Read; a report without it skipped the file).
When the report closes with uncommitted work and no next round queued, delete the round's APPROVED stamp first - every implementer and verifier has returned, and the checkpoint's generic security seat bounces off a live one (an AUTO stamp stays with its owner, and the checkpoint runs that half inline) - then the commit decision is the ask below, never a prose 'your call' bullet. The same close names what this round's runs started and still have up - a Docker container or compose stack, seeded integration-test data, a background process - and puts tear-down-vs-keep through the same AskUserQuestion call (started-nothing is said plainly, and what the round did not start is never touched):
<N> files changed, uncommitted.
- 'Commit now (Recommended)' - `habits-commit-checkpoint`, whole
- 'Hold - review the diff first' - nothing committed
This round started <what is still up>.
- 'Tear it down (Recommended)' - only what this round started
- 'Keep it running' - named in the report
Bounded and honest
Hard cap: 3 improve rounds. Architecture changes are expensive and consequential; do not loop indefinitely chasing the last debatable con.
Each round boundary is a fresh-session resume point - carried-forward conversation (not tool output) dominates session cost, and the map plus a fresh findings capture is the handoff (there is no pruned doc to hand off - the next session's step 1 recomputes the findings). A step, not advice: at each LOOP decision, ask - the fresh-session option is ALWAYS one of its options (a continue-ask without it is the measured failure step 3's receipt exists to catch), and when the hook refuses the ask because a fresh session does not pay back, start the next round here (its receipt
next: continue - "refused: a fresh session does not pay back"). Mark the fresh option only when a hook's fresh-session text in this session says a fresh session pays back, and then it goes first, the in-session option after it unmarked; on Claude Code the stop-contract hook drops it where one does not, and when that leaves one option it refuses the ask - then take the option it names. On 'fresh', end the turn with the RESUME BLOCK shaped inreferences/loop-mechanics.mdand nothing else - the new session must be able to start from it alone.Round <N>: LOOP - <what is left>. A fresh session restarts at <M>k. - 'Continue here (Recommended)' - the next round in this chat - 'Resume in a fresh session' - the RESUME BLOCK, then this turn endsNever weaken a test or delete an assertion to make a con look resolved - that is a new weakness, not a fix, and the anti-gaming sweep exists to catch it.
Make the smallest change that resolves each weakness; a rewrite that introduces new coupling makes the loop diverge.
The tier is the routing authority - do not silently upgrade a small con into a rewrite, or downgrade a structural one to sneak it past the approval gate.
Rules
- The main session is the only orchestrator: every seat it dispatches - the domain designer / implementers / verifier / resolvers, and the capture's architecture-analyzers - carries no Agent tool, so the fan-out stays flat; analysis and fix are separate dispatches from here, never one nested one.
- Keep this skill orchestration only. The map lives in
capture-awareness's architecture part, the judgement incapture-quality's architecture-quality part it hands off to (plus whichever house architecture skills either one loads); the build knowledge lives in the domain seats.
Example
DELEGATED, one run over the Orders module:
- ANALYZE + ASSESS - the map, then the findings: a small con (a repository leaks an EF type across the boundary), a substantial one (queries and handlers share one namespace).
- FIX by tier - baselines recorded. Small: aspnet-implementer, scoped brief. Substantial: designer, plan gated and approved, implementers, verifier. A structural con (invert the persistence dependency) is declined into the declined set.
- LOOP or STOP - only the declined item and accepted tradeoffs remain -> SATISFIED; the sweep is clean, both captures reconcile, then the report.