Improve Codebase Architecture

Identify deepening opportunities: refactors that place more behavior behind a smaller interface at a defined seam, improving testability and code navigation.

Use two authoritative vocabularies:

• Read codebase-design for module, interface, depth, seam, adapter, leverage, locality, the deletion test, interface-as-test-surface, and adapter-count rules. Use those architecture terms in every candidate; do not substitute component, service, API, or boundary.
• Use domain terms from applicable CONTEXT.md files; when the glossary defines Order, write Order intake module, not an implementation class name or Order service. Treat ADRs in docs/adr/ as decisions that remain in force unless the report supplies repository evidence for reopening one.

Process

1. Scan

Read the applicable domain glossary and ADRs before scanning code.

By default, delegate the scan to one new Explore worker with clean context through the active harness's isolated-worker mechanism. If the maintainer explicitly requests a direct scan, perform it locally with the same scope, evidence, findings-artifact and validation requirements; skip worker launch and settlement, not the investigation. The worker directly inspects the repository and produces findings; the Explore role or name does not grant tools, isolation, delivery, or permission to delegate. In Pi, follow PI.md.

Before a delegated scan, read model-routing and select for the actual investigation scope within authorized routes; local scanning creates no model launch. Before reading relative links, run cd '<loaded-skill-directory>' && pwd -P with this loaded file's directory to obtain the physical base, then resolve links against that printed directory. Resolve the source symlink before applying ..; read linked files even when their skills are absent from the discovery list. Before launch, preflight the repository-read and findings-write tools and providers. Where the harness exposes lineage controls, inherit the existing depth ceiling and set the worker's direct-child ceiling to zero or remove delegation capability. An interactive root may use documented visible or asynchronous delivery; print and managed nested callers use direct delivery, as may a root RPC caller for dependent work when supported. Direct settlement returns once and produces no later asynchronous completion notification. After asynchronous acceptance, do not wait, sleep, or poll; resume only from the documented completion notification. A non-delegating leaf performs an explicitly assigned scan directly or validates supplied findings within its assignment; it returns genuinely unresolved authority or capability gaps to its caller.

The initial prompt must let the worker execute without inherited conversation context and include the worker role, repository path, authoritative domain and architecture references, scan scope, one exact findings-artifact path, and required finding fields. State that the worker is a non-delegating leaf, must not invoke this skill, and must report the artifact path. Do not create separate workers for candidates or alternatives. Treat an over-depth or capability rejection before prompt acceptance as no scan, not partial evidence.

Require an adversarial scan in the worker brief, and apply the same standard locally: challenge the existing architecture against observed behavior and the governing references, stating problems and consequences directly without sugar-coating. Report every supported deepening opportunity within the scan scope, not just the strongest candidates; distinguish observed problems from speculative benefits, and invent no defects to fill the report.

The worker must follow repository references based on observed code rather than stop at a fixed directory or match quota. Use these categories to classify observed friction; they are neither an exhaustive navigation checklist nor a requirement to produce one finding per category:

• domain behavior that requires navigation across multiple modules;
• modules whose caller-visible interface exposes nearly every implementation decision;
• pure functions extracted for tests while defects can still arise in their call ordering or coordination;
• coupled modules where a change to one requires callers to know another module's implementation; and
• behavior with no test through the current interface, or whose tests must bypass that interface.

Apply the canonical deletion test from codebase-design to each suspected shallow module. Use its result as evidence for the candidate's effect on locality, leverage, and caller-visible complexity.

After a completed worker settlement or local scan, read the exact findings artifact and validate it before continuing. It must be non-empty, cover the requested scope, cite inspected repository paths for every candidate, include every required finding field, use the authoritative vocabularies, report evidence gaps, and contain no repository edits or private data. Bounded terminal output or a native session reference may recover transport evidence but never replaces the artifact. A failed, interrupted, missing, or invalid artifact blocks report generation.

2. Write and open the HTML report

Write one HTML file outside the repository:

• In Pi, use the temp location specified by PI.md.
• Otherwise use $TMPDIR, falling back to /tmp on Unix or %TEMP% on Windows.
• Name it <tmpdir>/architecture-review-<timestamp>.html so an existing report is not overwritten.

Use HTML-REPORT.md for the HTML scaffold, diagram patterns, and styling constraints.

For each candidate, render one card containing:

• Files: every inspected file or module that supports the finding;
• Problem: the observed navigation, coupling, interface, or testing evidence;
• Solution: the behavior to concentrate and the proposed seam location, without defining an interface;
• Benefits: the expected change in locality, leverage, and tests, tied to the listed evidence;
• Before / After: side-by-side diagrams of the current and proposed responsibility distribution; and
• Recommendation strength: one of Strong, Worth exploring, or Speculative, rendered as a badge.

End with Top recommendation, naming the candidate to tackle first and explaining why. If no candidate is supported, state that conclusion with scan coverage and evidence gaps instead.

If a candidate conflicts with an ADR, include it only when the observed friction is substantial enough to warrant revisiting that ADR. Add a warning naming the ADR and the supporting evidence.

Do not propose method signatures, parameter shapes, or other interfaces before step 3. After writing the file, read it back and apply the completion checks in HTML-REPORT.md. Only then attempt xdg-open <path> on Linux, open <path> on macOS, or start <path> on Windows. In headless or print operation, an unavailable opener or non-zero opener result is explicit and non-fatal once the complete report has been validated: report the failure, absolute path, and recommendation or no-candidate conclusion. Do not treat a successful opener as report validation. If the invocation names a candidate to develop, continue to step 3. Otherwise stop; the validated report is the complete deliverable and no selection question is required.

3. Develop a selected candidate

After the user selects a candidate, use grill-with-docs's Question rounds, evidence checks, recording gates, and shared-understanding confirmation to resolve constraints, dependencies, behavior ownership, seam placement, and the interface test surface. Keep each round inside that candidate, with no more than three independent Questions. This composition ends at design confirmation; it does not include the generic destination-selection and routing steps.

Maintain domain and decision docs while resolving the design:

• When the module is named after a domain concept absent from CONTEXT.md, add the confirmed term. Create the file only when adding the first term.
• When the user confirms a narrower or distinct meaning for an existing term, update that term in the same turn.
• Apply grill-with-docs' ADR eligibility and approval gates to already-established rejections too. Record one only when it rules out candidate architectures and future agents could otherwise repeat the proposal. Do not record a rejection whose reason is represented directly in code or the domain glossary, or applies only to the current session.
• To compare alternative interfaces, follow codebase-design and its one-designer Design It Twice process.

This step is complete when the selected candidate has confirmed behavior ownership, seam placement, interface test surface, which existing tests remain unchanged, and applicable domain or ADR updates. Summarize the design and ask the user what to do next, then stop. If a continuation was already explicitly authorized, follow it under its owning workflow without asking again. Design confirmation alone authorizes neither publication nor implementation.