Review module relationships and change history to identify structural improvements in a codebase. Receive ranked candidates with file references, suggested changes, and risks, plus a recommendation for where to start, without modifying code.
Periodic architecture survey — walks the module graph and reports ranked deepening candidates (shallow modules, hypothetical seams, logic behind the wrong seam). Survey, not rescue: it finds candidates and hands them to the captain; it never refactors on its own.
Review the instructions the agent will receive before you install.
A surveyor charts the reef; the captain decides whether to dredge. The survey reads the water, reports what it found with evidence, and stops. It is the maintenance twin of the loft: where the loft answers one design question before building, the survey answers "where is this repo getting harder to change, and what would deepen it" after building.
Optional argument narrows the survey to a directory or area; with no argument, survey the whole repo.
docs/standards/architecture.md — the definitions of seam and deep module.Apply the demolition test to every suspect: if the module were removed, would its complexity vanish (a pass-through wearing a uniform) or reappear across its callers (load-bearing)? Only load-bearing shallowness is a finding.
Rank candidates by leverage against risk. Each candidate carries:
Every candidate states the yard's shared findings vocabulary — severity (how much friction the shallowness causes), confidence (a survey finding is heuristic-class and therefore low by construction; the mechanically checkable end of the scale belongs to the drydock --check audit), and actionable (whether the deepening move is specific enough to start from the report alone). End the report with the top recommendation: the one candidate to deepen first, and why — the captain reads one card, not the whole reef.
Logbook conflicts. A candidate that contradicts an existing ADR is nominated only when the friction is real: the card names the ADR and why the water has changed. Theoretical conflicts stay off the report — the logbook's rejections are not re-litigated by default.
The report may be rendered visually with the repo's diagram skill when the yard has one; the prose report stays the source of truth either way.
The report is decision input, not work. Candidates feed the mission brief (launch Phase 1) or grilling material for the next effort. Survey proposes; the captain disposes.
Grill the top candidate on the spot. When the captain wants to act on the survey immediately rather than filing it, the report's top recommendation becomes the first question of a design-tree interview in the same session — launch Phase 1's frontier protocol, run right here: what would deepening this candidate involve, what does it cost, what does it unblock. The evidence is fresh and the captain is present; a finding worked now is a decided effort, not a report waiting to go stale. The survey still makes no edits — the interview decides, and delivery goes through launch's own gates.
A candidate the captain declines with a load-bearing reason is offered as an ADR — the same ADR test launch applies (hard to reverse, surprising without context, a real tradeoff) — so the next survey does not re-nominate the same reef. Declined without one, it simply sinks.
--check stays strictly mechanically checkable — high-confidence findings only. Architecture judgment is a low-confidence heuristic; mixing it in dilutes the contract.The survey is done when the report exists with evidence, rankings, and risk notes for every finding — and no file was modified.
No reviews yet. Tell others what you thought.
No login needed. Share how it worked for you, ask a question, or note where it did not run.
No comments yet. Be the first to write one.
Write or revise instructions, specifications, tickets, and skill files so an agent can act without prior chat history. Make rules checkable, explain their reasons, define completion criteria, and keep authoritative information in one place.
Simplify bloated AI-generated code by removing dead code, duplicated logic, and unnecessary layers while checking that existing behavior stays intact. Use a limited cleanup scope, verify changes with relevant checks, or request a review without edits.
Send questions, review requests, or implementation tasks to a supported local AI command-line tool through one shared command. The wrapper handles provider-specific options and saves the result as a Markdown file for later reference.
Turn an unclear idea into linked decision tickets on a repository’s issue tracker. Work through one decision per session, record outcomes and dependencies, and prepare a brief defining the objective, scope, and exclusions for delivery.
Turn a short product idea into working code through requirements analysis, technical planning, implementation, testing, and review. It coordinates agents across these stages, fixes detected problems, and reports assumptions that still need a human decision.
Run repeated change-and-evaluation cycles for one predefined improvement mission within an explicit runtime limit. Save each evaluation as JSON and each decision in readable Markdown logs, with support for periodic reruns through Claude Code native cron.