Menu
Use when an agent is unfamiliar with a Gormes code area, a change crosses package boundaries, or a refactor needs a source-backed module map before edits.
Installer avec Codex ou Claude Copiez ce prompt, collez-le dans Codex, Claude ou un autre assistant, puis laissez-le vérifier la page du skill et l'installer pour vous.
Basé sur la classification professionnelle SOC
Implement one selected repo-scoped Gormes row with tests. Use when next-work says decision=build. Do not use for decision=plan, broad parity audits, or untracked feature ideas.
Shape source-backed Gormes progress rows. Use for decision=plan builder handoffs, row splitting, feature maps, or parity planning. Do not use when decision=build or for runtime code.
Route Gormes work to the smallest repo-local skill chain. Use before substantial planning/building/refactor work, when unsure which Gormes skill applies, or when creating/improving repo-local skills.
Build one selected Gormes behavior with red-green-refactor. Use when the row or reproduced bug defines a test target. Do not use after decision=plan or for broad planning.
Move one bounded cmd/gormes command domain out of root files toward root main.go only. Use when thinning cmd/gormes, burning down loose root files, preserving CLI behavior, or catching refactor regressions during cmd moves.
Plan or implement browser automation parity. Use for Browser Use, go-browser-harness, CDP, /browser connect, browser providers, tool descriptors, and browser interaction skills.
| name | gormes-architecture-zoomout |
| description | Use when an agent is unfamiliar with a Gormes code area, a change crosses package boundaries, or a refactor needs a source-backed module map before edits. |
Use this before changing an unfamiliar subsystem, when a planned change spans packages and callers, or when the user asks to improve codebase architecture.
Inspired by mattpocock/skills zoom-out and improve-codebase-architecture; adapted for Gormes source evidence, progress rows, branch rules, and Hermes/Honcho parity boundaries.
Pick one mode before exploring:
Default to zoom-out map for vague debugging. Use architecture review when the user says “improve codebase architecture,” “find refactors,” “make this more testable,” “reduce coupling,” or “AI-navigable.”
Protect the worktree first. Run git status --short --branch --untracked-files=all. If unrelated dirty work exists, name it in the report, avoid broad formatters/regenerators, and stage only explicit architecture-skill files.
Read local maps first. Start with the current repository root's codemap.md (git rev-parse --show-toplevel); read folder codemap.md when present.
Choose one subsystem. Do not review the whole repository at once. Good first cuts are cmd/gormes setup/CLI, internal/tools, internal/gateway, internal/channels/<name>, internal/goncho, internal/memory, internal/tui, or internal/provider.
Run targeted discovery. Use commands like these, scoped to the subsystem:
find <area> -maxdepth 2 -type f -name '*.go' | sort
rg -n "type .*interface|func New|func \(.*\)|TODO|panic\(|os\.Getenv|http\.Client|time\.Now|json\.Marshal|AtomicReplace|Status|Evidence" <area>
rg -n "<public command/tool/error/status text>" cmd internal webpages/docs/content/building-gormes
go test ./<package> -run '<focused existing test pattern>' -count=1
Map the subsystem. List modules, owners, entry points, data flow, persistence, and test surfaces.
Find user-visible contracts. CLI flags, TUI text, gateway protocol, files on disk, progress rows, and Hermes parity refs.
Evaluate module depth. Use these terms consistently:
Classify architecture smells. Prefer candidates that match one or more of these Gormes-specific smells:
Apply architecture tests. For each candidate:
Score candidates. Use the scorecard below; discard candidates below 3 unless the user specifically asks to see speculative ideas.
List anti-candidates. Name tempting refactors you rejected and why, so future agents do not re-suggest them.
Separate facts from guesses. Every claim gets a file path, function, test, progress row, or command.
Run the architecture stop/ask gates. If any gate below trips, stop the review at a recommendation instead of implementation.
Recommend the smallest next skill. Usually gormes-tdd-slice, gormes-interface-designer, gormes-service-layer-refactor, or gormes-progress-slicer.
Stop and ask Juan, or route to planner, when:
Continue without asking when:
Score each candidate 0-10:
| Points | Signal |
|---|---|
| +2 | Repeated mechanics exist in two or more callers |
| +2 | Public behavior can be characterized through one seam |
| +1 | Deletion test says complexity would spread across callers |
| +1 | Refactor reduces caller knowledge/config/error handling |
| +1 | Existing tests or fixtures can protect behavior |
| +1 | Change preserves Hermes/Honcho/Gormes user-visible contracts |
| +1 | Candidate removes or centralizes one Gormes-specific smell from the taxonomy |
| +1 | First slice can update one package or one caller family without broad churn |
| -2 | Needs public behavior change without a progress row |
| -2 | Only one adapter/caller and no near-term second adapter |
| -2 | Mainly renames/moves code without improving locality |
| -2 | Requires broad edits across unrelated subsystems |
Recommendation strength:
Strong: 7-10 and first slice is clear.Worth exploring: 3-6 or needs interface design first.Speculative: 0-2; usually report as anti-candidate, not a task.Use these examples to keep reviews consistent:
| Example | Likely score | Why |
|---|---|---|
| Three channel runtimes independently redact the same token/error/status shape | 8-10 | repeated mechanics, clear caller burden, public behavior can be characterized with transcript fixtures |
cmd/gormes setup and internal/tui/admin both clamp terminal layout with copied width/height math | 6-8 | repeated mechanics and focused TUI tests, but user-visible layout must be preserved exactly |
| A package exports an interface with one implementation and tests use it only to mock private helpers | 1-3 | likely one-off seam; prefer package-local helper or deletion unless a second adapter is imminent |
| Moving files into a new package because the old package is large | 0-2 | layout aesthetics only unless caller knowledge, tests, or locality improve |
| Replacing provider-specific behavior with one generic provider abstraction | 2-5 | may reduce duplication, but high parity drift risk; route through provider parity/interface design first |
Prefer candidates with A or B evidence. Mark C as speculative unless the user asks for exploration.
Area: <subsystem>
Entry points: <files/functions>
Data flow: <source -> transform -> sink>
User-visible contracts: <CLI/TUI/API/files>
Tests/evidence: <commands/files>
Risks: <seam/persistence/security/parity>
Architecture candidates:
1. <candidate title> — <Strong/Worth exploring/Speculative> (<score>/10)
files: <paths>
current shape: <modules/callers>
interface burden: <facts callers/tests must know today>
evidence_quality: <A executable/B source/C impression>
friction: <why locality/leverage/testability is weak>
deepening move: <smaller interface or better seam>
deletion test: <complexity vanishes/spreads>
two-adapter test: <real seam/hypothetical seam>
characterization test: <focused test to write before refactor>
first safe slice: <TDD/refactor/planner action>
validation: <focused command + full gate if implemented>
Anti-candidates:
- <tempting refactor rejected> — <why>
Top recommendation: <one candidate + why>
Next skill packet:
selected_skill: <skill>
intent: <implementation/design/planning>
scope: <files/packages>
behavior_to_preserve: <contract>
first_test: <command/test name>
stop_if: <risk or blocker>
validation_matrix_row: <row from table above>
For broad architecture review requests, produce 2-4 candidates, not a grand rewrite plan. Keep the report text-first for Juan. Do not write HTML reports inside this repo; if a visual report is useful, put it under /tmp and report the absolute path.
Match the proposed next slice to the smallest proof:
| Next slice type | Minimum proof before implementation | Green gate after implementation |
|---|---|---|
| Package-local helper extraction | Characterization test through existing public caller | focused package test + git diff --check |
| New seam or adapter | Interface test with fake and production adapter evidence | focused package test + affected caller test |
| Progress-row refactor plan | go run ./cmd/progress validate before and after row edit | go test ./internal/planning/progress ./webpages/docs -count=1 |
| CLI/tool behavior-preserving refactor | CLI/tool golden or fixture test before moving code | focused command/tool test + full Go gate when feasible |
| Channel/gateway refactor | transcript/status fixture proving no duplicate/leaked output | channel/gateway focused test + progress validate |
| Persistence/config refactor | temp-home/temp-db fixture proving ordering, redaction, and atomicity | package test plus migration/config focused tests |
If no minimum proof exists, the first safe slice is to add the characterization test, not to refactor.
Use this compact packet when handing off implementation:
architecture_review_packet:
area: <subsystem>
candidate: <title>
score: <n>/10
smell: <taxonomy item>
evidence_quality: <A/B/C>
preserve_contracts:
- <CLI/tool/API/status behavior>
characterization_test:
name: <test to add or existing test to extend>
command: <focused go test command>
allowed_write_scope:
- <package/file family>
forbidden_scope:
- <public behavior or package not to touch>
next_skill: <gormes-service-layer-refactor|gormes-interface-designer|gormes-tdd-slice|gormes-progress-slicer>
If the packet cannot name a characterization test and allowed write scope, the candidate is not ready for implementation. If evidence quality is C, the next skill must be gormes-architecture-zoomout or gormes-interface-designer, not implementation.
gormes-progress-slicer or gormes-planner.