improve-codebase-architecture

A preserved method from https://github.com/mattpocock/skills at 3cca18b368ae, path skills/engineering/improve-codebase-architecture, MIT. 124 of 199 source lines differ (62%), every difference claimed by an entry of the ledger with its reason. Entries: baseline-copies-2026-09-11, pull-2026-09-11, fold-2026-09-11, vocabulary-owner-2026-09-12, roster-keepers-2026-09-15, roster-keepers-fix-2026-09-15.

  • dependency 17
  • harness 5
  • lifecycle 1
  • location 1
  • method 1
  • rename 4
  • scope 1

Files

Every difference, as it stands

HTML-REPORT.md

# HTML Report Format
# HTML Report Format
 
 
dependencychangedfold-2026-09-11

The report is offline-complete: embedded CSS and static inline SVG replace the Tailwind and Mermaid CDN scripts in step 2 and throughout HTML-REPORT.md (the scaffold's stylesheet, the SVG graph pattern in place of the Mermaid workhorse, the utility-class mentions, the no-scripts rule), with a network-off check before handoff and the HTML-REPORT.md passed to any delegate; greenline's consumer must open the report with no network, and HTML-REPORT.md's intro line also names the tmp home the report lives in.

The architectural review is rendered as a single self-contained HTML file in the OS temp directory. Tailwind and Mermaid both come from CDNs. Mermaid handles graph-shaped diagrams reliably; hand-built divs and inline SVG handle the more editorial visuals (mass diagrams, cross-sections). Mix the two: don't lean on Mermaid for everything, it'll start to look generic.
The architectural review is rendered as a single self-contained HTML file under `.greenline/tmp/improve-codebase-architecture/`. It is offline-complete: the CSS is embedded and every diagram is static inline SVG or HTML, so no script, style, font, or image loads from a network. Inline SVG draws the graph-shaped diagrams; hand-built divs and inline SVG handle the more editorial visuals (mass diagrams, cross-sections). Mix the two: don't lean on one pattern for everything, it'll start to look generic.
 
 
## Scaffold
## Scaffold
 
 
3 unchanged lines
```html
```html
<!doctype html>
<!doctype html>
<html lang="en">
<html lang="en">
<head>
<head>
<meta charset="utf-8" />
<meta charset="utf-8" />
<title>Architecture review for {{repo name}}</title>
<title>Architecture review for {{repo name}}</title>
dependencychangedfold-2026-09-11

The report is offline-complete: embedded CSS and static inline SVG replace the Tailwind and Mermaid CDN scripts in step 2 and throughout HTML-REPORT.md (the scaffold's stylesheet, the SVG graph pattern in place of the Mermaid workhorse, the utility-class mentions, the no-scripts rule), with a network-off check before handoff and the HTML-REPORT.md passed to any delegate; greenline's consumer must open the report with no network, and HTML-REPORT.md's intro line also names the tmp home the report lives in.

<script src="https://cdn.tailwindcss.com"></script>
<script type="module">
import mermaid from "https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs";
mermaid.initialize({ startOnLoad: true, theme: "neutral", securityLevel: "loose" });
</script>
<style>
<style>
dependencychangedfold-2026-09-11

The report is offline-complete: embedded CSS and static inline SVG replace the Tailwind and Mermaid CDN scripts in step 2 and throughout HTML-REPORT.md (the scaffold's stylesheet, the SVG graph pattern in place of the Mermaid workhorse, the utility-class mentions, the no-scripts rule), with a network-off check before handoff and the HTML-REPORT.md passed to any delegate; greenline's consumer must open the report with no network, and HTML-REPORT.md's intro line also names the tmp home the report lives in.

/* small custom layer for things Tailwind doesn't cover cleanly:
/* the whole stylesheet is embedded: nothing loads from a network */
body { margin: 0; background: #fafaf9; color: #0f172a; font-family: system-ui, sans-serif; }
main { max-width: 64rem; margin: 0 auto; padding: 3rem 1.5rem; }
main > * + * { margin-top: 3rem; }
article { border: 1px solid #e2e8f0; border-radius: 0.5rem; background: #fff; padding: 1.5rem; }
article + article { margin-top: 2.5rem; }
.badge { display: inline-block; border-radius: 9999px; padding: 0.125rem 0.625rem; font-size: 0.75rem; font-weight: 600; }
.strong { background: #d1fae5; color: #065f46; }
.explore { background: #fef3c7; color: #92400e; }
.speculative { background: #e2e8f0; color: #334155; }
.files { font-family: ui-monospace, monospace; font-size: 0.875rem; }
.label { font-size: 0.75rem; text-transform: uppercase; letter-spacing: 0.05em; }
.pair { display: grid; grid-template-columns: 1fr 1fr; gap: 1.5rem; }
.diagram { border: 1px solid #e2e8f0; border-radius: 0.5rem; background: #fff; padding: 1rem; }
.callout { border: 1px solid #fcd34d; background: #fffbeb; border-radius: 0.375rem; padding: 0.5rem 0.75rem; }
/* small custom layer for the diagrams:
dashed seam lines, hand-drawn-feeling arrow heads, etc. */
dashed seam lines, hand-drawn-feeling arrow heads, etc. */
.seam { stroke-dasharray: 4 4; }
.seam { stroke-dasharray: 4 4; }
.leak { stroke: #dc2626; }
.leak { stroke: #dc2626; }
.deep { background: linear-gradient(135deg, #0f172a, #1e293b); }
.deep { background: linear-gradient(135deg, #0f172a, #1e293b); }
</style>
</style>
</head>
</head>
dependencychangedfold-2026-09-11

The report is offline-complete: embedded CSS and static inline SVG replace the Tailwind and Mermaid CDN scripts in step 2 and throughout HTML-REPORT.md (the scaffold's stylesheet, the SVG graph pattern in place of the Mermaid workhorse, the utility-class mentions, the no-scripts rule), with a network-off check before handoff and the HTML-REPORT.md passed to any delegate; greenline's consumer must open the report with no network, and HTML-REPORT.md's intro line also names the tmp home the report lives in.

<body class="bg-stone-50 text-slate-900 font-sans">
<body>
<main class="max-w-5xl mx-auto px-6 py-12 space-y-12">
<main>
<header>...</header>
<header>...</header>
dependencychangedfold-2026-09-11

The report is offline-complete: embedded CSS and static inline SVG replace the Tailwind and Mermaid CDN scripts in step 2 and throughout HTML-REPORT.md (the scaffold's stylesheet, the SVG graph pattern in place of the Mermaid workhorse, the utility-class mentions, the no-scripts rule), with a network-off check before handoff and the HTML-REPORT.md passed to any delegate; greenline's consumer must open the report with no network, and HTML-REPORT.md's intro line also names the tmp home the report lives in.

<section id="candidates" class="space-y-10">...</section>
<section id="candidates">...</section>
<section id="top-recommendation">...</section>
<section id="top-recommendation">...</section>
</main>
</main>
</body>
</body>
6 unchanged lines
</html>
</html>
```
```
 
 
## Header
## Header
 
 
Repo name, date, and a compact legend: solid box = module, dashed line = seam, red arrow = leakage, thick dark box = deep module. No introduction paragraph. Straight into the candidates.
Repo name, date, and a compact legend: solid box = module, dashed line = seam, red arrow = leakage, thick dark box = deep module. No introduction paragraph. Straight into the candidates.
 
 
## Candidate card
## Candidate card
 
 
renamechangedbaseline-copies-2026-09-11

renamed skill references and bare roster names in prose (the notation pass)

The diagrams carry the weight. Prose is sparse, plain, and uses the glossary terms (from the `/codebase-design` skill) without ceremony.
The diagrams carry the weight. Prose is sparse, plain, and uses the glossary terms (from the `codebase-design` skill) without ceremony.
 
 
Each candidate is one `<article>`:
Each candidate is one `<article>`:
 
 
- **Title**: short, names the deepening (e.g. "Collapse the Order intake pipeline").
- **Title**: short, names the deepening (e.g. "Collapse the Order intake pipeline").
- **Badge row**: recommendation strength (`Strong` = emerald, `Worth exploring` = amber, `Speculative` = slate), plus a tag for the dependency category (`in-process`, `local-substitutable`, `ports & adapters`, `mock`).
- **Badge row**: recommendation strength (`Strong` = emerald, `Worth exploring` = amber, `Speculative` = slate), plus a tag for the dependency category (`in-process`, `local-substitutable`, `ports & adapters`, `mock`).
dependencychangedfold-2026-09-11

The report is offline-complete: embedded CSS and static inline SVG replace the Tailwind and Mermaid CDN scripts in step 2 and throughout HTML-REPORT.md (the scaffold's stylesheet, the SVG graph pattern in place of the Mermaid workhorse, the utility-class mentions, the no-scripts rule), with a network-off check before handoff and the HTML-REPORT.md passed to any delegate; greenline's consumer must open the report with no network, and HTML-REPORT.md's intro line also names the tmp home the report lives in.

- **Files**: monospaced list, `font-mono text-sm`.
- **Files**: monospaced list (the `.files` class).
- **Before / After diagram**: the centrepiece. Two columns, side by side. See patterns below.
- **Before / After diagram**: the centrepiece. Two columns, side by side. See patterns below.
- **Problem**: one sentence. What hurts.
- **Problem**: one sentence. What hurts.
- **Solution**: one sentence. What changes.
- **Solution**: one sentence. What changes.
6 unchanged lines
- **Wins**: bullets, ≤6 words each. e.g. "Tests hit one interface", "Pricing logic stops leaking", "Delete 4 shallow wrappers".
- **Wins**: bullets, ≤6 words each. e.g. "Tests hit one interface", "Pricing logic stops leaking", "Delete 4 shallow wrappers".
- **ADR callout** (if applicable): one line in an amber-tinted box.
- **ADR callout** (if applicable): one line in an amber-tinted box.
 
 
No paragraphs of explanation. If the diagram needs a paragraph to be understood, redraw the diagram.
No paragraphs of explanation. If the diagram needs a paragraph to be understood, redraw the diagram.
 
 
## Diagram patterns
## Diagram patterns
 
 
Pick the pattern that fits the candidate. Mix them. Don't make every diagram look the same. Variety is part of the point.
Pick the pattern that fits the candidate. Mix them. Don't make every diagram look the same. Variety is part of the point.
 
 
dependencychangedfold-2026-09-11

The report is offline-complete: embedded CSS and static inline SVG replace the Tailwind and Mermaid CDN scripts in step 2 and throughout HTML-REPORT.md (the scaffold's stylesheet, the SVG graph pattern in place of the Mermaid workhorse, the utility-class mentions, the no-scripts rule), with a network-off check before handoff and the HTML-REPORT.md passed to any delegate; greenline's consumer must open the report with no network, and HTML-REPORT.md's intro line also names the tmp home the report lives in.

### Mermaid graph (the workhorse for dependencies / call flow)
### Inline SVG graph (the workhorse for dependencies / call flow)
 
 
dependencychangedfold-2026-09-11

The report is offline-complete: embedded CSS and static inline SVG replace the Tailwind and Mermaid CDN scripts in step 2 and throughout HTML-REPORT.md (the scaffold's stylesheet, the SVG graph pattern in place of the Mermaid workhorse, the utility-class mentions, the no-scripts rule), with a network-off check before handoff and the HTML-REPORT.md passed to any delegate; greenline's consumer must open the report with no network, and HTML-REPORT.md's intro line also names the tmp home the report lives in.

Use a Mermaid `flowchart` or `graph` when the point is "X calls Y calls Z, and look at the mess." Wrap it in a Tailwind-styled card so it doesn't feel parachuted in. Style with classDef to colour leakage edges red and the deep module dark. Sequence diagrams work well for "before: 6 round-trips; after: 1."
Draw the graph directly in SVG when the point is "X calls Y calls Z, and look at the mess": modules as `<rect>` elements with a `<text>` label, calls as `<path>` elements ending in an arrowhead `<marker>`, laid out by hand left to right. Wrap it in a `.diagram` card so it doesn't feel parachuted in. Put the `leak` class on leakage edges to colour them red and the `deep` treatment on the deep module. Prefix marker ids per diagram so two SVGs on the page never share one. A hand-drawn sequence (lifelines as vertical lines, messages as horizontal arrows) works well for "before: 6 round-trips; after: 1."
 
 
```html
```html
dependencychangedfold-2026-09-11

The report is offline-complete: embedded CSS and static inline SVG replace the Tailwind and Mermaid CDN scripts in step 2 and throughout HTML-REPORT.md (the scaffold's stylesheet, the SVG graph pattern in place of the Mermaid workhorse, the utility-class mentions, the no-scripts rule), with a network-off check before handoff and the HTML-REPORT.md passed to any delegate; greenline's consumer must open the report with no network, and HTML-REPORT.md's intro line also names the tmp home the report lives in.

<div class="rounded-lg border border-slate-200 bg-white p-4">
<div class="diagram">
<pre class="mermaid">
<svg viewBox="0 0 560 120" role="img" aria-label="OrderHandler calls OrderValidator, which calls OrderRepo, which leaks into PricingClient">
flowchart LR
<defs>
A[OrderHandler] --> B[OrderValidator]
<marker id="c1-arrow" markerWidth="8" markerHeight="6" refX="7" refY="3" orient="auto">
B --> C[OrderRepo]
<polygon points="0 0, 8 3, 0 6" fill="#475569" />
C -.leak.-> D[PricingClient]
</marker>
classDef leak stroke:#dc2626,stroke-width:2px;
</defs>
class C,D leak
<rect x="8" y="40" width="112" height="40" rx="4" fill="#fff" stroke="#0f172a" />
</pre>
<text x="64" y="64" text-anchor="middle" font-size="12">OrderHandler</text>
<rect x="168" y="40" width="112" height="40" rx="4" fill="#fff" stroke="#0f172a" />
<text x="224" y="64" text-anchor="middle" font-size="12">OrderValidator</text>
<rect x="328" y="40" width="88" height="40" rx="4" fill="#fff" stroke="#dc2626" />
<text x="372" y="64" text-anchor="middle" font-size="12">OrderRepo</text>
<rect x="456" y="40" width="96" height="40" rx="4" fill="#fff" stroke="#dc2626" />
<text x="504" y="64" text-anchor="middle" font-size="12">PricingClient</text>
<path d="M120 60 H168" stroke="#475569" fill="none" marker-end="url(#c1-arrow)" />
<path d="M280 60 H328" stroke="#475569" fill="none" marker-end="url(#c1-arrow)" />
<path class="leak seam" d="M416 60 H456" stroke-width="2" fill="none" marker-end="url(#c1-arrow)" />
</svg>
</div>
</div>
```
```
 
 
dependencychangedfold-2026-09-11

The report is offline-complete: embedded CSS and static inline SVG replace the Tailwind and Mermaid CDN scripts in step 2 and throughout HTML-REPORT.md (the scaffold's stylesheet, the SVG graph pattern in place of the Mermaid workhorse, the utility-class mentions, the no-scripts rule), with a network-off check before handoff and the HTML-REPORT.md passed to any delegate; greenline's consumer must open the report with no network, and HTML-REPORT.md's intro line also names the tmp home the report lives in.

### Hand-built boxes-and-arrows (when Mermaid's layout fights you)
### Hand-built boxes-and-arrows (when the graph needs weight)
 
 
dependencychangedfold-2026-09-11

The report is offline-complete: embedded CSS and static inline SVG replace the Tailwind and Mermaid CDN scripts in step 2 and throughout HTML-REPORT.md (the scaffold's stylesheet, the SVG graph pattern in place of the Mermaid workhorse, the utility-class mentions, the no-scripts rule), with a network-off check before handoff and the HTML-REPORT.md passed to any delegate; greenline's consumer must open the report with no network, and HTML-REPORT.md's intro line also names the tmp home the report lives in.

Modules as `<div>`s with borders and labels. Arrows as inline SVG `<line>` or `<path>` elements positioned absolutely over a relative container. Reach for this when you want the "after" diagram to feel like one thick-bordered deep module with greyed-out internals, since Mermaid won't render that with the right weight.
Modules as `<div>`s with borders and labels. Arrows as inline SVG `<line>` or `<path>` elements positioned absolutely over a relative container. Reach for this when you want the "after" diagram to feel like one thick-bordered deep module with greyed-out internals, since a plain node graph won't carry that weight.
 
 
### Cross-section (good for layered shallowness)
### Cross-section (good for layered shallowness)
 
 
dependencychangedfold-2026-09-11

The report is offline-complete: embedded CSS and static inline SVG replace the Tailwind and Mermaid CDN scripts in step 2 and throughout HTML-REPORT.md (the scaffold's stylesheet, the SVG graph pattern in place of the Mermaid workhorse, the utility-class mentions, the no-scripts rule), with a network-off check before handoff and the HTML-REPORT.md passed to any delegate; greenline's consumer must open the report with no network, and HTML-REPORT.md's intro line also names the tmp home the report lives in.

Stack horizontal bands (`h-12 border-l-4`) to show layers a call passes through. Before: 6 thin layers each doing nothing. After: 1 thick band labelled with the consolidated responsibility.
Stack horizontal bands (3rem tall, with a thick left border) to show layers a call passes through. Before: 6 thin layers each doing nothing. After: 1 thick band labelled with the consolidated responsibility.
 
 
### Mass diagram (good for "interface as wide as implementation")
### Mass diagram (good for "interface as wide as implementation")
 
 
5 unchanged lines
Two rectangles per module: one for interface surface area, one for implementation. Before: interface rectangle is nearly as tall as the implementation rectangle (shallow). After: interface rectangle is short, implementation rectangle is tall (deep).
Two rectangles per module: one for interface surface area, one for implementation. Before: interface rectangle is nearly as tall as the implementation rectangle (shallow). After: interface rectangle is short, implementation rectangle is tall (deep).
 
 
### Call-graph collapse
### Call-graph collapse
 
 
Before: a tree of function calls rendered as nested boxes. After: the same tree collapsed into one box, with the now-internal calls shown faded inside it.
Before: a tree of function calls rendered as nested boxes. After: the same tree collapsed into one box, with the now-internal calls shown faded inside it.
 
 
## Style guidance
## Style guidance
 
 
dependencychangedfold-2026-09-11

The report is offline-complete: embedded CSS and static inline SVG replace the Tailwind and Mermaid CDN scripts in step 2 and throughout HTML-REPORT.md (the scaffold's stylesheet, the SVG graph pattern in place of the Mermaid workhorse, the utility-class mentions, the no-scripts rule), with a network-off check before handoff and the HTML-REPORT.md passed to any delegate; greenline's consumer must open the report with no network, and HTML-REPORT.md's intro line also names the tmp home the report lives in.

- Lean editorial, not corporate-dashboard. Generous whitespace. Serif optional for headings (`font-serif` works well with stone/slate).
- Lean editorial, not corporate-dashboard. Generous whitespace. Serif optional for headings (a serif stack works well with stone/slate).
- Colour sparingly: one accent (emerald or indigo) plus red for leakage and amber for warnings.
- Colour sparingly: one accent (emerald or indigo) plus red for leakage and amber for warnings.
- Keep diagrams ~320px tall so before/after sits comfortably side by side without scrolling.
- Keep diagrams ~320px tall so before/after sits comfortably side by side without scrolling.
dependencychangedfold-2026-09-11

The report is offline-complete: embedded CSS and static inline SVG replace the Tailwind and Mermaid CDN scripts in step 2 and throughout HTML-REPORT.md (the scaffold's stylesheet, the SVG graph pattern in place of the Mermaid workhorse, the utility-class mentions, the no-scripts rule), with a network-off check before handoff and the HTML-REPORT.md passed to any delegate; greenline's consumer must open the report with no network, and HTML-REPORT.md's intro line also names the tmp home the report lives in.

- Use `text-xs uppercase tracking-wider` for module labels inside diagrams, so they read as schematic, not as UI.
- Use the `.label` treatment (small, uppercase, tracked) for module labels inside diagrams, so they read as schematic, not as UI.
- The only scripts are the Tailwind CDN and the Mermaid ESM import. The report is otherwise static: no app code, no interactivity beyond Mermaid's own rendering.
- No scripts at all. The report is static: no app code, no interactivity, and nothing fetched from a network, so it reads the same with the network off.
 
 
## Top recommendation section
## Top recommendation section
 
 
1 unchanged lines
One larger card. Candidate name, one sentence on why, anchor link to its card. That's it.
One larger card. Candidate name, one sentence on why, anchor link to its card. That's it.
 
 
## Tone
## Tone
 
 
renamechangedbaseline-copies-2026-09-11

renamed skill references and bare roster names in prose (the notation pass)

Plain English, concise, but the architectural nouns and verbs come straight from the `/codebase-design` skill. Concision is not an excuse to drift.
Plain English, concise, but the architectural nouns and verbs come straight from the `codebase-design` skill. Concision is not an excuse to drift.
 
 
**Use exactly:** module, interface, implementation, depth, deep, shallow, seam, adapter, leverage, locality.
**Use exactly:** module, interface, implementation, depth, deep, shallow, seam, adapter, leverage, locality.
 
 
8 unchanged lines
**Never substitute:** component, service, unit (for module) · API, signature (for interface) · boundary (for seam) · layer, wrapper (for module, when you mean module).
**Never substitute:** component, service, unit (for module) · API, signature (for interface) · boundary (for seam) · layer, wrapper (for module, when you mean module).
 
 
**Phrasings that fit the style:**
**Phrasings that fit the style:**
 
 
- "Order intake module is shallow: interface nearly matches the implementation."
- "Order intake module is shallow: interface nearly matches the implementation."
- "Pricing leaks across the seam."
- "Pricing leaks across the seam."
- "Deepen: one interface, one place to test."
- "Deepen: one interface, one place to test."
- "Two adapters justify the seam: HTTP in prod, in-memory in tests."
- "Two adapters justify the seam: HTTP in prod, in-memory in tests."
 
 
**Wins bullets** name the gain in glossary terms: *"locality: bugs concentrate in one module"*, *"leverage: one interface, N call sites"*, *"interface shrinks; implementation absorbs the wrappers"*. Don't write *"easier to maintain"* or *"cleaner code"*, because those terms aren't in the glossary and don't earn their place.
**Wins bullets** name the gain in glossary terms: *"locality: bugs concentrate in one module"*, *"leverage: one interface, N call sites"*, *"interface shrinks; implementation absorbs the wrappers"*. Don't write *"easier to maintain"* or *"cleaner code"*, because those terms aren't in the glossary and don't earn their place.
 
 
renamechangedbaseline-copies-2026-09-11

renamed skill references and bare roster names in prose (the notation pass)

No hedging, no throat-clearing, no "it's worth noting that…". If a sentence could be a bullet, make it a bullet. If a bullet could be cut, cut it. If a term isn't in the `/codebase-design` glossary, reach for one that is before inventing a new one.
No hedging, no throat-clearing, no "it's worth noting that…". If a sentence could be a bullet, make it a bullet. If a bullet could be cut, cut it. If a term isn't in the `codebase-design` glossary, reach for one that is before inventing a new one.

SKILL.md

---
---
harnesschangedbaseline-copies-2026-09-11

greenline renders its own frontmatter: quoted name and description, the description from the manifest override where one existed, no upstream activation flag

name: improve-codebase-architecture
name: "improve-codebase-architecture"
description: Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.
description: "Scan a codebase for deepening opportunities and present them as a visual report, then grill through the one you pick. Use for 'refactor what next', 'tech debt', 'this repo is a mess, where do I start', or a scoped architecture review."
disable-model-invocation: true
---
---
 
 
# Improve Codebase Architecture
# Improve Codebase Architecture
 
 
scopechangedvocabulary-owner-2026-09-12

An opening paragraph after the title says when the skill fires, that it reads .greenline/map/snapshot.json when architecture-map (opt-in) has written it and that architecture-map (opt-in) is the refresh once a deepening lands, and that the survey is a report the operator decides on; greenline needs this because the consumer reads no prelude. (carried from fold-2026-09-11; the word operator became owner where the copy names the workspace's person, and request owner became request holder (the internal refactor's step 1, ruling 10, 2026-09-12))

This skill surveys a codebase for deepening opportunities: use it for "refactor what next", "tech debt", "this repo is a mess, where do I start", or a scoped architecture review. When `architecture-map` (opt-in) has written `.greenline/map/snapshot.json`, read it before walking the codebase; once a deepening lands, `architecture-map` (opt-in) is the refresh that folds it back into the map. The survey is a report, not implementation work: the owner decides what is taken up, and a taken-up finding becomes a compact ticket or an initiative.
 
Surface architectural friction and propose **deepening opportunities**: refactors that turn shallow modules into deep ones. The aim is testability and AI-navigability.
Surface architectural friction and propose **deepening opportunities**: refactors that turn shallow modules into deep ones. The aim is testability and AI-navigability.
 
 
This command is _informed_ by the project's domain model and built on a shared design vocabulary:
This command is _informed_ by the project's domain model and built on a shared design vocabulary:
 
 
harnesschangedfold-2026-09-11

Where upstream says 'call the Skill tool with' codebase-design, grilling or domain-modeling, the copy loads the method through the harness's native skill mechanism or reads its installed SKILL.md and required support, and carries the vocabulary into every delegated brief; greenline runs on Codex and Claude Code, neither of which is promised a tool by that name.

- Call the Skill tool with "codebase-design" for the architecture vocabulary (**module**, **interface**, **depth**, **seam**, **adapter**, **leverage**, **locality**) and its principles (the deletion test, "the interface is the test surface", "one adapter = hypothetical seam, two = real"). Use these terms exactly in every suggestion, and don't drift into "component," "service," "API," or "boundary."
- Load codebase-design through the harness's native skill mechanism, or read its installed SKILL.md and required support when the harness has none, for the architecture vocabulary (**module**, **interface**, **depth**, **seam**, **adapter**, **leverage**, **locality**) and its principles (the deletion test, "the interface is the test surface", "one adapter = hypothetical seam, two = real"). Use these terms exactly in every suggestion and in every delegated brief, and don't drift into "component," "service," "API," or "boundary."
- The domain language in `CONTEXT.md` gives names to good seams; ADRs in `docs/adr/` record decisions this command should not re-litigate.
- The domain language in `CONTEXT.md` gives names to good seams; ADRs in `docs/adr/` record decisions this command should not re-litigate.
 
 
## Process
## Process
3 unchanged lines
 
 
### 1. Explore
### 1. Explore
 
 
**Scope before you scan: YAGNI.** Deepening a module pays off by making future changes to it easier, so put extra weight on the parts of the codebase that have recently changed. Decide *where* to look before you look:
**Scope before you scan: YAGNI.** Deepening a module pays off by making future changes to it easier, so put extra weight on the parts of the codebase that have recently changed. Decide *where* to look before you look:
 
 
- If the user named a direction (a module, a subsystem, a pain point), take it, and skip the inference below.
- If the user named a direction (a module, a subsystem, a pain point), take it, and skip the inference below.
dependencychangedfold-2026-09-11

Step 1's hot-spot search starts from .greenline/map/snapshot.json when it exists: its drifting nodes and churn tint are the hot spots already measured and its unclaimed-files list is ground to inspect before a finding; an optional consume of the opt-in map's home, so the survey does not re-walk what the map measured.

- Otherwise, walk back a good stretch of the commit history (`git log --oneline`) to find the codebase's hot spots, the files and areas that keep coming up, and let those paths pull your attention first. If the changes are scattered with no clear hot spot, widen the net.
- Otherwise, walk back a good stretch of the commit history (`git log --oneline`) to find the codebase's hot spots, the files and areas that keep coming up, and let those paths pull your attention first. If the changes are scattered with no clear hot spot, widen the net. When `.greenline/map/snapshot.json` exists, start from it: its drifting nodes and churn tint are these hot spots, already measured, and its unclaimed-files list is ground the map has not described, so inspect that ground before making a finding.
 
 
Read the project's domain glossary (`CONTEXT.md`) and any ADRs in the area you're touching first.
Read the project's domain glossary (`CONTEXT.md`) and any ADRs in the area you're touching first.
 
 
9 unchanged lines
Then spawn a sub-agent to walk the codebase. Don't follow rigid heuristics; explore organically and note where you experience friction:
Then spawn a sub-agent to walk the codebase. Don't follow rigid heuristics; explore organically and note where you experience friction:
 
 
- Where does understanding one concept require bouncing between many small modules?
- Where does understanding one concept require bouncing between many small modules?
- Where are modules **shallow**, with an interface nearly as complex as the implementation?
- Where are modules **shallow**, with an interface nearly as complex as the implementation?
- Where have pure functions been extracted just for testability, but the real bugs hide in how they're called (no **locality**)?
- Where have pure functions been extracted just for testability, but the real bugs hide in how they're called (no **locality**)?
- Where do tightly-coupled modules leak across their seams?
- Where do tightly-coupled modules leak across their seams?
- Which parts of the codebase are untested, or hard to test through their current interface?
- Which parts of the codebase are untested, or hard to test through their current interface?
 
 
Apply the **deletion test** to anything you suspect is shallow: would deleting it concentrate complexity, or just move it? A "yes, concentrates" is the signal you want.
Apply the **deletion test** to anything you suspect is shallow: would deleting it concentrate complexity, or just move it? A "yes, concentrates" is the signal you want.
 
 
### 2. Present candidates as an HTML report
### 2. Present candidates as an HTML report
 
 
locationchangedfold-2026-09-11

Step 2 writes the report to .greenline/tmp/improve-codebase-architecture/architecture-review-<timestamp>.html instead of the OS temp directory resolved from $TMPDIR and /tmp, and promotes it to .greenline/work/evidence/<work-id>/ when authorized work takes a finding up; greenline's scratch home keeps the survey out of git and lets accepted work cite the report durably.

Write a self-contained HTML file to the OS temp directory so nothing lands in the repo. Resolve the temp dir from `$TMPDIR`, falling back to `/tmp` (or `%TEMP%` on Windows), and write to `<tmpdir>/architecture-review-<timestamp>.html` so each run gets a fresh file. Open it for the user (`xdg-open <path>` on Linux, `open <path>` on macOS, `start <path>` on Windows) and tell them the absolute path.
Write a self-contained HTML file to `.greenline/tmp/improve-codebase-architecture/architecture-review-<timestamp>.html` so each run gets a fresh file and nothing lands in the repo: a survey need not create implementation work, and git never sees tmp. Open it for the user (`xdg-open <path>` on Linux, `open <path>` on macOS, `start <path>` on Windows) and tell them the absolute path. When authorized work takes a finding up, retain the report in that work's evidence home, `.greenline/work/evidence/<work-id>/`, so its artifacts can cite it durably.
 
 
dependencychangedfold-2026-09-11

The report is offline-complete: embedded CSS and static inline SVG replace the Tailwind and Mermaid CDN scripts in step 2 and throughout HTML-REPORT.md (the scaffold's stylesheet, the SVG graph pattern in place of the Mermaid workhorse, the utility-class mentions, the no-scripts rule), with a network-off check before handoff and the HTML-REPORT.md passed to any delegate; greenline's consumer must open the report with no network, and HTML-REPORT.md's intro line also names the tmp home the report lives in.

The report uses **Tailwind via CDN** for layout and styling, and **Mermaid via CDN** for diagrams where a graph/flow/sequence reliably communicates the structure. Mix Mermaid with hand-crafted CSS/SVG visuals: use Mermaid when relationships are graph-shaped (call graphs, dependencies, sequences), and hand-built divs/SVG when you want something more editorial (mass diagrams, cross-sections, collapse animations). Each candidate gets a **before/after visualisation**. Be visual.
The report is offline-complete: **embedded CSS** for layout and styling, and **static inline SVG** for diagrams where a graph/flow/sequence reliably communicates the structure, with no network-loaded script, style, font, or image needed to view it. Mix graph-shaped SVG with hand-crafted CSS/HTML visuals: draw relationships directly in SVG when they are graph-shaped (call graphs, dependencies, sequences), and use hand-built divs/SVG when you want something more editorial (mass diagrams, cross-sections, collapse animations). Each candidate gets a **before/after visualisation**. Be visual.
 
 
For each candidate, render a card with:
For each candidate, render a card with:
 
 
6 unchanged lines
- **Files**: which files/modules are involved
- **Files**: which files/modules are involved
- **Problem**: why the current architecture is causing friction
- **Problem**: why the current architecture is causing friction
- **Solution**: plain English description of what would change
- **Solution**: plain English description of what would change
- **Benefits**: explained in terms of locality and leverage, and how tests would improve
- **Benefits**: explained in terms of locality and leverage, and how tests would improve
- **Before / After diagram**: side-by-side, custom-drawn, illustrating the shallowness and the deepening
- **Before / After diagram**: side-by-side, custom-drawn, illustrating the shallowness and the deepening
- **Recommendation strength**: one of `Strong`, `Worth exploring`, `Speculative`, rendered as a badge
- **Recommendation strength**: one of `Strong`, `Worth exploring`, `Speculative`, rendered as a badge
 
 
End the report with a **Top recommendation** section: which candidate you'd tackle first and why.
End the report with a **Top recommendation** section: which candidate you'd tackle first and why.
 
 
renamechangedbaseline-copies-2026-09-11

renamed skill references and bare roster names in prose (the notation pass)

**Use CONTEXT.md vocabulary for the domain, and the `/codebase-design` vocabulary for the architecture.** If `CONTEXT.md` defines "Order," talk about "the Order intake module," not "the FooBarHandler," and not "the Order service."
**Use CONTEXT.md vocabulary for the domain, and the `codebase-design` vocabulary for the architecture.** If `CONTEXT.md` defines "Order," talk about "the Order intake module," not "the FooBarHandler," and not "the Order service."
 
 
**ADR conflicts**: if a candidate contradicts an existing ADR, only surface it when the friction is real enough to warrant revisiting the ADR. Mark it clearly in the card (e.g. a warning callout: _"contradicts ADR-0007, but worth reopening because…"_). Don't list every theoretical refactor an ADR forbids.
**ADR conflicts**: if a candidate contradicts an existing ADR, only surface it when the friction is real enough to warrant revisiting the ADR. Mark it clearly in the card (e.g. a warning callout: _"contradicts ADR-0007, but worth reopening because…"_). Don't list every theoretical refactor an ADR forbids.
 
 
dependencychangedfold-2026-09-11

The report is offline-complete: embedded CSS and static inline SVG replace the Tailwind and Mermaid CDN scripts in step 2 and throughout HTML-REPORT.md (the scaffold's stylesheet, the SVG graph pattern in place of the Mermaid workhorse, the utility-class mentions, the no-scripts rule), with a network-off check before handoff and the HTML-REPORT.md passed to any delegate; greenline's consumer must open the report with no network, and HTML-REPORT.md's intro line also names the tmp home the report lives in.

See [HTML-REPORT.md](HTML-REPORT.md) for the full HTML scaffold, diagram patterns, and styling guidance.
See [HTML-REPORT.md](HTML-REPORT.md) for the full HTML scaffold, diagram patterns, and styling guidance, and pass it to any report-writing delegate. Before handing the report over, open it with network access disabled and confirm every diagram and label remains visible; if that check could not run, say so and call the report unverified offline.
 
 
Do NOT propose interfaces yet. After the file is written, ask the user: "Which of these would you like to explore?"
Do NOT propose interfaces yet. After the file is written, ask the user: "Which of these would you like to explore?"
 
 
### 3. Grilling loop
### 3. Grilling loop
 
 
harnesschangedfold-2026-09-11

Where upstream says 'call the Skill tool with' codebase-design, grilling or domain-modeling, the copy loads the method through the harness's native skill mechanism or reads its installed SKILL.md and required support, and carries the vocabulary into every delegated brief; greenline runs on Codex and Claude Code, neither of which is promised a tool by that name.

Once the user picks a candidate, call the Skill tool with "grilling" to walk the decision tree with them: constraints, dependencies, the shape of the deepened module, what sits behind the seam, what tests survive.
Once the user picks a candidate, load grilling (through the harness's native skill mechanism, or its installed SKILL.md) to walk the decision tree with them: constraints, dependencies, the shape of the deepened module, what sits behind the seam, what tests survive.
 
 
harnesschangedfold-2026-09-11

Where upstream says 'call the Skill tool with' codebase-design, grilling or domain-modeling, the copy loads the method through the harness's native skill mechanism or reads its installed SKILL.md and required support, and carries the vocabulary into every delegated brief; greenline runs on Codex and Claude Code, neither of which is promised a tool by that name.

Side effects happen inline as decisions crystallize; call the Skill tool with "domain-modeling" to keep the domain model current as you go:
Side effects happen inline as decisions crystallize; load domain-modeling to keep the domain model current as you go:
 
 
methodchangedroster-keepers-fix-2026-09-15

both side-effect bullets write CONTEXT.md only when the request's grant covers it and otherwise offer the entry in one line, matching the block's situational-skill rule; carried from roster-keepers-2026-09-15; the method edit is on the operator's word of 2026-09-15 at the card J-8, with J-2 folded in

- **Naming a deepened module after a concept not in `CONTEXT.md`?** Add the term to `CONTEXT.md`. Create the file lazily if it doesn't exist.
- **Naming a deepened module after a concept not in `CONTEXT.md`?** Add the term to `CONTEXT.md` when the request's grant covers it, creating the file lazily if it doesn't exist; otherwise offer the entry in one line.
- **Sharpening a fuzzy term during the conversation?** Update `CONTEXT.md` right there.
- **Sharpening a fuzzy term during the conversation?** Update `CONTEXT.md` right there when the request's grant covers it, or offer the entry in one line.
- **User rejects the candidate with a load-bearing reason?** Offer an ADR, framed as: _"Want me to record this as an ADR so future architecture reviews don't re-suggest it?"_ Only offer when the reason would actually be needed by a future explorer to avoid re-suggesting the same thing; skip ephemeral reasons ("not worth it right now") and self-evident ones.
- **User rejects the candidate with a load-bearing reason?** Offer an ADR, framed as: _"Want me to record this as an ADR so future architecture reviews don't re-suggest it?"_ Only offer when the reason would actually be needed by a future explorer to avoid re-suggesting the same thing; skip ephemeral reasons ("not worth it right now") and self-evident ones.
lifecyclechangedvocabulary-owner-2026-09-12

After the grilling loop the survey returns to the operator (a recommendation is not authorization, accepted work is linked to the report and becomes a compact ticket or an initiative, no planning program per observation) and the Handoff section the skills-handoff gate parses closes the skill: consumes the repository, the optional map snapshot, CONTEXT.md and the decision records; produces the offline report in tmp promoted only when taken up; next is implement or grill-with-docs. The hunk's first line is the same harness rewrite as the edit above, on the last 'call the Skill tool' sentence. (carried from fold-2026-09-11; the word operator became owner where the copy names the workspace's person, and request owner became request holder (the internal refactor's step 1, ruling 10, 2026-09-12))

- **Want to explore alternative interfaces for the deepened module?** Call the Skill tool with "codebase-design" and use its design-it-twice parallel sub-agent pattern.
- **Want to explore alternative interfaces for the deepened module?** Load codebase-design and use its design-it-twice parallel sub-agent pattern.
 
The survey, its evidence and the grilled candidate return to the owner; a recommendation alone does not authorize implementation. Work the owner takes up stays linked to the survey's report and becomes a compact ticket for a bounded change, or an initiative where unresolved intent and dependent work warrant one. Do not manufacture a planning program for each observation.
 
## Handoff
 
Consumes: the repository; .greenline/map/snapshot.json when architecture-map (opt-in) has written it (optional); CONTEXT.md and the decision records
Produces: the offline HTML report under .greenline/tmp/improve-codebase-architecture/, promoted to .greenline/work/evidence/<work-id>/ only when a finding is taken up; the survey returns to the owner and a recommendation is not authorization
Next: accepted work becomes a compact ticket (implement) or an initiative (grill-with-docs)

agents/openai.yaml

harnessremoved filebaseline-copies-2026-09-11

the renderer generates agents/openai.yaml from the manifest; the vendored copy is not projected

interface:
display_name: "Improve Codebase Architecture"
short_description: "Find and grill architecture improvements"
policy:
allow_implicit_invocation: false

The timeline

Each entry that touched this method, with the differences it claimed as they stood at its commit, read from the repository's history.

2026-09-11 baseline-copies-2026-09-11

the cutover to an edited copy (ADR 0039): the composed output written as the copy, every difference from upstream claimed with the reason of the overlay that produced it

HTML-REPORT.md

renamechangedbaseline-copies-2026-09-11

renamed skill references and bare roster names in prose (the notation pass)

The diagrams carry the weight. Prose is sparse, plain, and uses the glossary terms (from the `/codebase-design` skill) without ceremony.
The diagrams carry the weight. Prose is sparse, plain, and uses the glossary terms (from the `codebase-design` skill) without ceremony.
renamechangedbaseline-copies-2026-09-11

renamed skill references and bare roster names in prose (the notation pass)

Plain English, concise, but the architectural nouns and verbs come straight from the `/codebase-design` skill. Concision is not an excuse to drift.
Plain English, concise, but the architectural nouns and verbs come straight from the `codebase-design` skill. Concision is not an excuse to drift.
renamechangedbaseline-copies-2026-09-11

renamed skill references and bare roster names in prose (the notation pass)

No hedging, no throat-clearing, no "it's worth noting that…". If a sentence could be a bullet, make it a bullet. If a bullet could be cut, cut it. If a term isn't in the `/codebase-design` glossary, reach for one that is before inventing a new one.
No hedging, no throat-clearing, no "it's worth noting that…". If a sentence could be a bullet, make it a bullet. If a bullet could be cut, cut it. If a term isn't in the `codebase-design` glossary, reach for one that is before inventing a new one.

SKILL.md

harnesschangedbaseline-copies-2026-09-11

greenline renders its own frontmatter: quoted name and description, the description from the manifest override where one existed, no upstream activation flag

name: improve-codebase-architecture
name: "improve-codebase-architecture"
description: Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.
description: "Scan a codebase for deepening opportunities and present them as a visual report, then grill through the one you pick. Use for 'refactor what next', 'tech debt', 'this repo is a mess, where do I start', or a scoped architecture review."
disable-model-invocation: true
lifecyclechangedbaseline-copies-2026-09-11

greenline prelude, to fold: read .greenline/map/snapshot.json first when it exists; the report goes to .greenline/tmp/improve-codebase-architecture/ as offline-complete HTML; the Skill-tool call is the native mechanism

**greenline prelude: read the map before you walk the codebase.** When `.greenline/map/snapshot.json` exists, read it first: its drifting nodes and churn tint are step 1's hot spots, already measured, and its unclaimed-files list identifies ground the map has not described; inspect it before making a finding. Once a deepening lands, `architecture-map` (opt-in) is the refresh that folds it back into the city. Write step 2's HTML report into `.greenline/tmp/improve-codebase-architecture/` first: a survey need not create implementation work, and git never sees tmp. When authorized work takes a finding up, retain its report in that work's evidence home so its artifacts can cite it durably. Without a workspace, the system temp directory as the body says.
 
**Self-contained means offline-complete.** Replace step 2's CDN requirement and
HTML-REPORT.md's CDN scaffold, Mermaid runtime examples, and “only scripts” rule
with embedded CSS and static inline SVG/HTML diagrams. Preserve its candidate
cards, before/after visuals, recommendation strengths, and architectural
vocabulary. Draw graph relationships directly in SVG; no network-loaded script,
style, font, or image is required to view the report. Pass this replacement with
HTML-REPORT.md to any report-writing delegate. Before handoff, open the file with
network access disabled and confirm every diagram and label remains visible;
state it as unverified if that check could not run.
 
Where the body says “Call the Skill tool,” use the harness's native skill
mechanism; if none exists, read the named installed skill's SKILL.md and its
required support files. “Twice” means load both named methods. Carry this
translation into any delegated brief; it does not require a tool with that name.
 
renamechangedbaseline-copies-2026-09-11

renamed skill references and bare roster names in prose (the notation pass)

**Use CONTEXT.md vocabulary for the domain, and the `/codebase-design` vocabulary for the architecture.** If `CONTEXT.md` defines "Order," talk about "the Order intake module," not "the FooBarHandler," and not "the Order service."
**Use CONTEXT.md vocabulary for the domain, and the `codebase-design` vocabulary for the architecture.** If `CONTEXT.md` defines "Order," talk about "the Order intake module," not "the FooBarHandler," and not "the Order service."
lifecyclechangedbaseline-copies-2026-09-11

greenline completion, to fold: the survey returns to the operator; a recommendation is not authorization; accepted work becomes a compact ticket or an initiative

 
 
## greenline completion: opportunities return to the operator
 
Return the survey and its evidence. A recommendation alone does not authorize implementation. When the operator takes an opportunity, use a compact ticket for a bounded change or an initiative where the unresolved intent and dependent work warrant one. Keep the accepted work linked to the actual survey; do not manufacture a planning program for each observation.

agents/openai.yaml

harnessremoved filebaseline-copies-2026-09-11

the renderer generates agents/openai.yaml from the manifest; the vendored copy is not projected

interface:
display_name: "Improve Codebase Architecture"
short_description: "Find and grill architecture improvements"
policy:
allow_implicit_invocation: false

2026-09-11 pull-2026-09-11

pin advance to 3cca18b: upstream moved with no change under the vendored paths

2026-09-11 fold-2026-09-11

The prelude and completion are folded into the body where the reader reaches them: the scope after the title, the map snapshot in step 1's hot-spot search, the tmp home and the offline-complete report in step 2 and in HTML-REPORT.md, the native skill mechanism where the Skill tool was called, the return to the operator after the grilling loop, and a Handoff section at the end.

HTML-REPORT.md

dependencychangedfold-2026-09-11

The report is offline-complete: embedded CSS and static inline SVG replace the Tailwind and Mermaid CDN scripts in step 2 and throughout HTML-REPORT.md (the scaffold's stylesheet, the SVG graph pattern in place of the Mermaid workhorse, the utility-class mentions, the no-scripts rule), with a network-off check before handoff and the HTML-REPORT.md passed to any delegate; greenline's consumer must open the report with no network, and HTML-REPORT.md's intro line also names the tmp home the report lives in.

The architectural review is rendered as a single self-contained HTML file in the OS temp directory. Tailwind and Mermaid both come from CDNs. Mermaid handles graph-shaped diagrams reliably; hand-built divs and inline SVG handle the more editorial visuals (mass diagrams, cross-sections). Mix the two: don't lean on Mermaid for everything, it'll start to look generic.
The architectural review is rendered as a single self-contained HTML file under `.greenline/tmp/improve-codebase-architecture/`. It is offline-complete: the CSS is embedded and every diagram is static inline SVG or HTML, so no script, style, font, or image loads from a network. Inline SVG draws the graph-shaped diagrams; hand-built divs and inline SVG handle the more editorial visuals (mass diagrams, cross-sections). Mix the two: don't lean on one pattern for everything, it'll start to look generic.
dependencychangedfold-2026-09-11

The report is offline-complete: embedded CSS and static inline SVG replace the Tailwind and Mermaid CDN scripts in step 2 and throughout HTML-REPORT.md (the scaffold's stylesheet, the SVG graph pattern in place of the Mermaid workhorse, the utility-class mentions, the no-scripts rule), with a network-off check before handoff and the HTML-REPORT.md passed to any delegate; greenline's consumer must open the report with no network, and HTML-REPORT.md's intro line also names the tmp home the report lives in.

<script src="https://cdn.tailwindcss.com"></script>
<script type="module">
import mermaid from "https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs";
mermaid.initialize({ startOnLoad: true, theme: "neutral", securityLevel: "loose" });
</script>
dependencychangedfold-2026-09-11

The report is offline-complete: embedded CSS and static inline SVG replace the Tailwind and Mermaid CDN scripts in step 2 and throughout HTML-REPORT.md (the scaffold's stylesheet, the SVG graph pattern in place of the Mermaid workhorse, the utility-class mentions, the no-scripts rule), with a network-off check before handoff and the HTML-REPORT.md passed to any delegate; greenline's consumer must open the report with no network, and HTML-REPORT.md's intro line also names the tmp home the report lives in.

/* small custom layer for things Tailwind doesn't cover cleanly:
/* the whole stylesheet is embedded: nothing loads from a network */
body { margin: 0; background: #fafaf9; color: #0f172a; font-family: system-ui, sans-serif; }
main { max-width: 64rem; margin: 0 auto; padding: 3rem 1.5rem; }
main > * + * { margin-top: 3rem; }
article { border: 1px solid #e2e8f0; border-radius: 0.5rem; background: #fff; padding: 1.5rem; }
article + article { margin-top: 2.5rem; }
.badge { display: inline-block; border-radius: 9999px; padding: 0.125rem 0.625rem; font-size: 0.75rem; font-weight: 600; }
.strong { background: #d1fae5; color: #065f46; }
.explore { background: #fef3c7; color: #92400e; }
.speculative { background: #e2e8f0; color: #334155; }
.files { font-family: ui-monospace, monospace; font-size: 0.875rem; }
.label { font-size: 0.75rem; text-transform: uppercase; letter-spacing: 0.05em; }
.pair { display: grid; grid-template-columns: 1fr 1fr; gap: 1.5rem; }
.diagram { border: 1px solid #e2e8f0; border-radius: 0.5rem; background: #fff; padding: 1rem; }
.callout { border: 1px solid #fcd34d; background: #fffbeb; border-radius: 0.375rem; padding: 0.5rem 0.75rem; }
/* small custom layer for the diagrams:
dependencychangedfold-2026-09-11

The report is offline-complete: embedded CSS and static inline SVG replace the Tailwind and Mermaid CDN scripts in step 2 and throughout HTML-REPORT.md (the scaffold's stylesheet, the SVG graph pattern in place of the Mermaid workhorse, the utility-class mentions, the no-scripts rule), with a network-off check before handoff and the HTML-REPORT.md passed to any delegate; greenline's consumer must open the report with no network, and HTML-REPORT.md's intro line also names the tmp home the report lives in.

<body class="bg-stone-50 text-slate-900 font-sans">
<body>
<main class="max-w-5xl mx-auto px-6 py-12 space-y-12">
<main>
dependencychangedfold-2026-09-11

The report is offline-complete: embedded CSS and static inline SVG replace the Tailwind and Mermaid CDN scripts in step 2 and throughout HTML-REPORT.md (the scaffold's stylesheet, the SVG graph pattern in place of the Mermaid workhorse, the utility-class mentions, the no-scripts rule), with a network-off check before handoff and the HTML-REPORT.md passed to any delegate; greenline's consumer must open the report with no network, and HTML-REPORT.md's intro line also names the tmp home the report lives in.

<section id="candidates" class="space-y-10">...</section>
<section id="candidates">...</section>
dependencychangedfold-2026-09-11

The report is offline-complete: embedded CSS and static inline SVG replace the Tailwind and Mermaid CDN scripts in step 2 and throughout HTML-REPORT.md (the scaffold's stylesheet, the SVG graph pattern in place of the Mermaid workhorse, the utility-class mentions, the no-scripts rule), with a network-off check before handoff and the HTML-REPORT.md passed to any delegate; greenline's consumer must open the report with no network, and HTML-REPORT.md's intro line also names the tmp home the report lives in.

- **Files**: monospaced list, `font-mono text-sm`.
- **Files**: monospaced list (the `.files` class).
dependencychangedfold-2026-09-11

The report is offline-complete: embedded CSS and static inline SVG replace the Tailwind and Mermaid CDN scripts in step 2 and throughout HTML-REPORT.md (the scaffold's stylesheet, the SVG graph pattern in place of the Mermaid workhorse, the utility-class mentions, the no-scripts rule), with a network-off check before handoff and the HTML-REPORT.md passed to any delegate; greenline's consumer must open the report with no network, and HTML-REPORT.md's intro line also names the tmp home the report lives in.

### Mermaid graph (the workhorse for dependencies / call flow)
### Inline SVG graph (the workhorse for dependencies / call flow)
dependencychangedfold-2026-09-11

The report is offline-complete: embedded CSS and static inline SVG replace the Tailwind and Mermaid CDN scripts in step 2 and throughout HTML-REPORT.md (the scaffold's stylesheet, the SVG graph pattern in place of the Mermaid workhorse, the utility-class mentions, the no-scripts rule), with a network-off check before handoff and the HTML-REPORT.md passed to any delegate; greenline's consumer must open the report with no network, and HTML-REPORT.md's intro line also names the tmp home the report lives in.

Use a Mermaid `flowchart` or `graph` when the point is "X calls Y calls Z, and look at the mess." Wrap it in a Tailwind-styled card so it doesn't feel parachuted in. Style with classDef to colour leakage edges red and the deep module dark. Sequence diagrams work well for "before: 6 round-trips; after: 1."
Draw the graph directly in SVG when the point is "X calls Y calls Z, and look at the mess": modules as `<rect>` elements with a `<text>` label, calls as `<path>` elements ending in an arrowhead `<marker>`, laid out by hand left to right. Wrap it in a `.diagram` card so it doesn't feel parachuted in. Put the `leak` class on leakage edges to colour them red and the `deep` treatment on the deep module. Prefix marker ids per diagram so two SVGs on the page never share one. A hand-drawn sequence (lifelines as vertical lines, messages as horizontal arrows) works well for "before: 6 round-trips; after: 1."
dependencychangedfold-2026-09-11

The report is offline-complete: embedded CSS and static inline SVG replace the Tailwind and Mermaid CDN scripts in step 2 and throughout HTML-REPORT.md (the scaffold's stylesheet, the SVG graph pattern in place of the Mermaid workhorse, the utility-class mentions, the no-scripts rule), with a network-off check before handoff and the HTML-REPORT.md passed to any delegate; greenline's consumer must open the report with no network, and HTML-REPORT.md's intro line also names the tmp home the report lives in.

<div class="rounded-lg border border-slate-200 bg-white p-4">
<div class="diagram">
<pre class="mermaid">
<svg viewBox="0 0 560 120" role="img" aria-label="OrderHandler calls OrderValidator, which calls OrderRepo, which leaks into PricingClient">
flowchart LR
<defs>
A[OrderHandler] --> B[OrderValidator]
<marker id="c1-arrow" markerWidth="8" markerHeight="6" refX="7" refY="3" orient="auto">
B --> C[OrderRepo]
<polygon points="0 0, 8 3, 0 6" fill="#475569" />
C -.leak.-> D[PricingClient]
</marker>
classDef leak stroke:#dc2626,stroke-width:2px;
</defs>
class C,D leak
<rect x="8" y="40" width="112" height="40" rx="4" fill="#fff" stroke="#0f172a" />
</pre>
<text x="64" y="64" text-anchor="middle" font-size="12">OrderHandler</text>
<rect x="168" y="40" width="112" height="40" rx="4" fill="#fff" stroke="#0f172a" />
<text x="224" y="64" text-anchor="middle" font-size="12">OrderValidator</text>
<rect x="328" y="40" width="88" height="40" rx="4" fill="#fff" stroke="#dc2626" />
<text x="372" y="64" text-anchor="middle" font-size="12">OrderRepo</text>
<rect x="456" y="40" width="96" height="40" rx="4" fill="#fff" stroke="#dc2626" />
<text x="504" y="64" text-anchor="middle" font-size="12">PricingClient</text>
<path d="M120 60 H168" stroke="#475569" fill="none" marker-end="url(#c1-arrow)" />
<path d="M280 60 H328" stroke="#475569" fill="none" marker-end="url(#c1-arrow)" />
<path class="leak seam" d="M416 60 H456" stroke-width="2" fill="none" marker-end="url(#c1-arrow)" />
</svg>
dependencychangedfold-2026-09-11

The report is offline-complete: embedded CSS and static inline SVG replace the Tailwind and Mermaid CDN scripts in step 2 and throughout HTML-REPORT.md (the scaffold's stylesheet, the SVG graph pattern in place of the Mermaid workhorse, the utility-class mentions, the no-scripts rule), with a network-off check before handoff and the HTML-REPORT.md passed to any delegate; greenline's consumer must open the report with no network, and HTML-REPORT.md's intro line also names the tmp home the report lives in.

### Hand-built boxes-and-arrows (when Mermaid's layout fights you)
### Hand-built boxes-and-arrows (when the graph needs weight)
dependencychangedfold-2026-09-11

The report is offline-complete: embedded CSS and static inline SVG replace the Tailwind and Mermaid CDN scripts in step 2 and throughout HTML-REPORT.md (the scaffold's stylesheet, the SVG graph pattern in place of the Mermaid workhorse, the utility-class mentions, the no-scripts rule), with a network-off check before handoff and the HTML-REPORT.md passed to any delegate; greenline's consumer must open the report with no network, and HTML-REPORT.md's intro line also names the tmp home the report lives in.

Modules as `<div>`s with borders and labels. Arrows as inline SVG `<line>` or `<path>` elements positioned absolutely over a relative container. Reach for this when you want the "after" diagram to feel like one thick-bordered deep module with greyed-out internals, since Mermaid won't render that with the right weight.
Modules as `<div>`s with borders and labels. Arrows as inline SVG `<line>` or `<path>` elements positioned absolutely over a relative container. Reach for this when you want the "after" diagram to feel like one thick-bordered deep module with greyed-out internals, since a plain node graph won't carry that weight.
dependencychangedfold-2026-09-11

The report is offline-complete: embedded CSS and static inline SVG replace the Tailwind and Mermaid CDN scripts in step 2 and throughout HTML-REPORT.md (the scaffold's stylesheet, the SVG graph pattern in place of the Mermaid workhorse, the utility-class mentions, the no-scripts rule), with a network-off check before handoff and the HTML-REPORT.md passed to any delegate; greenline's consumer must open the report with no network, and HTML-REPORT.md's intro line also names the tmp home the report lives in.

Stack horizontal bands (`h-12 border-l-4`) to show layers a call passes through. Before: 6 thin layers each doing nothing. After: 1 thick band labelled with the consolidated responsibility.
Stack horizontal bands (3rem tall, with a thick left border) to show layers a call passes through. Before: 6 thin layers each doing nothing. After: 1 thick band labelled with the consolidated responsibility.
dependencychangedfold-2026-09-11

The report is offline-complete: embedded CSS and static inline SVG replace the Tailwind and Mermaid CDN scripts in step 2 and throughout HTML-REPORT.md (the scaffold's stylesheet, the SVG graph pattern in place of the Mermaid workhorse, the utility-class mentions, the no-scripts rule), with a network-off check before handoff and the HTML-REPORT.md passed to any delegate; greenline's consumer must open the report with no network, and HTML-REPORT.md's intro line also names the tmp home the report lives in.

- Lean editorial, not corporate-dashboard. Generous whitespace. Serif optional for headings (`font-serif` works well with stone/slate).
- Lean editorial, not corporate-dashboard. Generous whitespace. Serif optional for headings (a serif stack works well with stone/slate).
dependencychangedfold-2026-09-11

The report is offline-complete: embedded CSS and static inline SVG replace the Tailwind and Mermaid CDN scripts in step 2 and throughout HTML-REPORT.md (the scaffold's stylesheet, the SVG graph pattern in place of the Mermaid workhorse, the utility-class mentions, the no-scripts rule), with a network-off check before handoff and the HTML-REPORT.md passed to any delegate; greenline's consumer must open the report with no network, and HTML-REPORT.md's intro line also names the tmp home the report lives in.

- Use `text-xs uppercase tracking-wider` for module labels inside diagrams, so they read as schematic, not as UI.
- Use the `.label` treatment (small, uppercase, tracked) for module labels inside diagrams, so they read as schematic, not as UI.
- The only scripts are the Tailwind CDN and the Mermaid ESM import. The report is otherwise static: no app code, no interactivity beyond Mermaid's own rendering.
- No scripts at all. The report is static: no app code, no interactivity, and nothing fetched from a network, so it reads the same with the network off.

SKILL.md

scopechangedfold-2026-09-11

An opening paragraph after the title says when the skill fires, that it reads .greenline/map/snapshot.json when architecture-map (opt-in) has written it and that architecture-map (opt-in) is the refresh once a deepening lands, and that the survey is a report the operator decides on; greenline needs this because the consumer reads no prelude.

This skill surveys a codebase for deepening opportunities: use it for "refactor what next", "tech debt", "this repo is a mess, where do I start", or a scoped architecture review. When `architecture-map` (opt-in) has written `.greenline/map/snapshot.json`, read it before walking the codebase; once a deepening lands, `architecture-map` (opt-in) is the refresh that folds it back into the map. The survey is a report, not implementation work: the operator decides what is taken up, and a taken-up finding becomes a compact ticket or an initiative.
 
harnesschangedfold-2026-09-11

Where upstream says 'call the Skill tool with' codebase-design, grilling or domain-modeling, the copy loads the method through the harness's native skill mechanism or reads its installed SKILL.md and required support, and carries the vocabulary into every delegated brief; greenline runs on Codex and Claude Code, neither of which is promised a tool by that name.

- Call the Skill tool with "codebase-design" for the architecture vocabulary (**module**, **interface**, **depth**, **seam**, **adapter**, **leverage**, **locality**) and its principles (the deletion test, "the interface is the test surface", "one adapter = hypothetical seam, two = real"). Use these terms exactly in every suggestion, and don't drift into "component," "service," "API," or "boundary."
- Load codebase-design through the harness's native skill mechanism, or read its installed SKILL.md and required support when the harness has none, for the architecture vocabulary (**module**, **interface**, **depth**, **seam**, **adapter**, **leverage**, **locality**) and its principles (the deletion test, "the interface is the test surface", "one adapter = hypothetical seam, two = real"). Use these terms exactly in every suggestion and in every delegated brief, and don't drift into "component," "service," "API," or "boundary."
dependencychangedfold-2026-09-11

Step 1's hot-spot search starts from .greenline/map/snapshot.json when it exists: its drifting nodes and churn tint are the hot spots already measured and its unclaimed-files list is ground to inspect before a finding; an optional consume of the opt-in map's home, so the survey does not re-walk what the map measured.

- Otherwise, walk back a good stretch of the commit history (`git log --oneline`) to find the codebase's hot spots, the files and areas that keep coming up, and let those paths pull your attention first. If the changes are scattered with no clear hot spot, widen the net.
- Otherwise, walk back a good stretch of the commit history (`git log --oneline`) to find the codebase's hot spots, the files and areas that keep coming up, and let those paths pull your attention first. If the changes are scattered with no clear hot spot, widen the net. When `.greenline/map/snapshot.json` exists, start from it: its drifting nodes and churn tint are these hot spots, already measured, and its unclaimed-files list is ground the map has not described, so inspect that ground before making a finding.
locationchangedfold-2026-09-11

Step 2 writes the report to .greenline/tmp/improve-codebase-architecture/architecture-review-<timestamp>.html instead of the OS temp directory resolved from $TMPDIR and /tmp, and promotes it to .greenline/work/evidence/<work-id>/ when authorized work takes a finding up; greenline's scratch home keeps the survey out of git and lets accepted work cite the report durably.

Write a self-contained HTML file to the OS temp directory so nothing lands in the repo. Resolve the temp dir from `$TMPDIR`, falling back to `/tmp` (or `%TEMP%` on Windows), and write to `<tmpdir>/architecture-review-<timestamp>.html` so each run gets a fresh file. Open it for the user (`xdg-open <path>` on Linux, `open <path>` on macOS, `start <path>` on Windows) and tell them the absolute path.
Write a self-contained HTML file to `.greenline/tmp/improve-codebase-architecture/architecture-review-<timestamp>.html` so each run gets a fresh file and nothing lands in the repo: a survey need not create implementation work, and git never sees tmp. Open it for the user (`xdg-open <path>` on Linux, `open <path>` on macOS, `start <path>` on Windows) and tell them the absolute path. When authorized work takes a finding up, retain the report in that work's evidence home, `.greenline/work/evidence/<work-id>/`, so its artifacts can cite it durably.
dependencychangedfold-2026-09-11

The report is offline-complete: embedded CSS and static inline SVG replace the Tailwind and Mermaid CDN scripts in step 2 and throughout HTML-REPORT.md (the scaffold's stylesheet, the SVG graph pattern in place of the Mermaid workhorse, the utility-class mentions, the no-scripts rule), with a network-off check before handoff and the HTML-REPORT.md passed to any delegate; greenline's consumer must open the report with no network, and HTML-REPORT.md's intro line also names the tmp home the report lives in.

The report uses **Tailwind via CDN** for layout and styling, and **Mermaid via CDN** for diagrams where a graph/flow/sequence reliably communicates the structure. Mix Mermaid with hand-crafted CSS/SVG visuals: use Mermaid when relationships are graph-shaped (call graphs, dependencies, sequences), and hand-built divs/SVG when you want something more editorial (mass diagrams, cross-sections, collapse animations). Each candidate gets a **before/after visualisation**. Be visual.
The report is offline-complete: **embedded CSS** for layout and styling, and **static inline SVG** for diagrams where a graph/flow/sequence reliably communicates the structure, with no network-loaded script, style, font, or image needed to view it. Mix graph-shaped SVG with hand-crafted CSS/HTML visuals: draw relationships directly in SVG when they are graph-shaped (call graphs, dependencies, sequences), and use hand-built divs/SVG when you want something more editorial (mass diagrams, cross-sections, collapse animations). Each candidate gets a **before/after visualisation**. Be visual.
dependencychangedfold-2026-09-11

The report is offline-complete: embedded CSS and static inline SVG replace the Tailwind and Mermaid CDN scripts in step 2 and throughout HTML-REPORT.md (the scaffold's stylesheet, the SVG graph pattern in place of the Mermaid workhorse, the utility-class mentions, the no-scripts rule), with a network-off check before handoff and the HTML-REPORT.md passed to any delegate; greenline's consumer must open the report with no network, and HTML-REPORT.md's intro line also names the tmp home the report lives in.

See [HTML-REPORT.md](HTML-REPORT.md) for the full HTML scaffold, diagram patterns, and styling guidance.
See [HTML-REPORT.md](HTML-REPORT.md) for the full HTML scaffold, diagram patterns, and styling guidance, and pass it to any report-writing delegate. Before handing the report over, open it with network access disabled and confirm every diagram and label remains visible; if that check could not run, say so and call the report unverified offline.
harnesschangedfold-2026-09-11

Where upstream says 'call the Skill tool with' codebase-design, grilling or domain-modeling, the copy loads the method through the harness's native skill mechanism or reads its installed SKILL.md and required support, and carries the vocabulary into every delegated brief; greenline runs on Codex and Claude Code, neither of which is promised a tool by that name.

Once the user picks a candidate, call the Skill tool with "grilling" to walk the decision tree with them: constraints, dependencies, the shape of the deepened module, what sits behind the seam, what tests survive.
Once the user picks a candidate, load grilling (through the harness's native skill mechanism, or its installed SKILL.md) to walk the decision tree with them: constraints, dependencies, the shape of the deepened module, what sits behind the seam, what tests survive.
harnesschangedfold-2026-09-11

Where upstream says 'call the Skill tool with' codebase-design, grilling or domain-modeling, the copy loads the method through the harness's native skill mechanism or reads its installed SKILL.md and required support, and carries the vocabulary into every delegated brief; greenline runs on Codex and Claude Code, neither of which is promised a tool by that name.

Side effects happen inline as decisions crystallize; call the Skill tool with "domain-modeling" to keep the domain model current as you go:
Side effects happen inline as decisions crystallize; load domain-modeling to keep the domain model current as you go:
lifecyclechangedfold-2026-09-11

After the grilling loop the survey returns to the operator (a recommendation is not authorization, accepted work is linked to the report and becomes a compact ticket or an initiative, no planning program per observation) and the Handoff section the skills-handoff gate parses closes the skill: consumes the repository, the optional map snapshot, CONTEXT.md and the decision records; produces the offline report in tmp promoted only when taken up; next is implement or grill-with-docs. The hunk's first line is the same harness rewrite as the edit above, on the last 'call the Skill tool' sentence.

- **Want to explore alternative interfaces for the deepened module?** Call the Skill tool with "codebase-design" and use its design-it-twice parallel sub-agent pattern.
- **Want to explore alternative interfaces for the deepened module?** Load codebase-design and use its design-it-twice parallel sub-agent pattern.
 
The survey, its evidence and the grilled candidate return to the operator; a recommendation alone does not authorize implementation. Work the operator takes up stays linked to the survey's report and becomes a compact ticket for a bounded change, or an initiative where unresolved intent and dependent work warrant one. Do not manufacture a planning program for each observation.
 
## Handoff
 
Consumes: the repository; .greenline/map/snapshot.json when architecture-map (opt-in) has written it (optional); CONTEXT.md and the decision records
Produces: the offline HTML report under .greenline/tmp/improve-codebase-architecture/, promoted to .greenline/work/evidence/<work-id>/ only when a finding is taken up; the survey returns to the operator and a recommendation is not authorization
Next: accepted work becomes a compact ticket (implement) or an initiative (grill-with-docs)

2026-09-12 vocabulary-owner-2026-09-12

The workspace's person is the owner: the word operator became owner where the copy names the workspace's person, and request owner became request holder (the internal refactor's step 1, ruling 10, 2026-09-12); every earlier claim on a re-measured hunk is carried forward under its own kind, with its authority where it had one.

SKILL.md

scopechangedvocabulary-owner-2026-09-12

An opening paragraph after the title says when the skill fires, that it reads .greenline/map/snapshot.json when architecture-map (opt-in) has written it and that architecture-map (opt-in) is the refresh once a deepening lands, and that the survey is a report the operator decides on; greenline needs this because the consumer reads no prelude. (carried from fold-2026-09-11; the word operator became owner where the copy names the workspace's person, and request owner became request holder (the internal refactor's step 1, ruling 10, 2026-09-12))

This skill surveys a codebase for deepening opportunities: use it for "refactor what next", "tech debt", "this repo is a mess, where do I start", or a scoped architecture review. When `architecture-map` (opt-in) has written `.greenline/map/snapshot.json`, read it before walking the codebase; once a deepening lands, `architecture-map` (opt-in) is the refresh that folds it back into the map. The survey is a report, not implementation work: the owner decides what is taken up, and a taken-up finding becomes a compact ticket or an initiative.
 
lifecyclechangedvocabulary-owner-2026-09-12

After the grilling loop the survey returns to the operator (a recommendation is not authorization, accepted work is linked to the report and becomes a compact ticket or an initiative, no planning program per observation) and the Handoff section the skills-handoff gate parses closes the skill: consumes the repository, the optional map snapshot, CONTEXT.md and the decision records; produces the offline report in tmp promoted only when taken up; next is implement or grill-with-docs. The hunk's first line is the same harness rewrite as the edit above, on the last 'call the Skill tool' sentence. (carried from fold-2026-09-11; the word operator became owner where the copy names the workspace's person, and request owner became request holder (the internal refactor's step 1, ruling 10, 2026-09-12))

- **Want to explore alternative interfaces for the deepened module?** Call the Skill tool with "codebase-design" and use its design-it-twice parallel sub-agent pattern.
- **Want to explore alternative interfaces for the deepened module?** Load codebase-design and use its design-it-twice parallel sub-agent pattern.
 
The survey, its evidence and the grilled candidate return to the owner; a recommendation alone does not authorize implementation. Work the owner takes up stays linked to the survey's report and becomes a compact ticket for a bounded change, or an initiative where unresolved intent and dependent work warrant one. Do not manufacture a planning program for each observation.
 
## Handoff
 
Consumes: the repository; .greenline/map/snapshot.json when architecture-map (opt-in) has written it (optional); CONTEXT.md and the decision records
Produces: the offline HTML report under .greenline/tmp/improve-codebase-architecture/, promoted to .greenline/work/evidence/<work-id>/ only when a finding is taken up; the survey returns to the owner and a recommendation is not authorization
Next: accepted work becomes a compact ticket (implement) or an initiative (grill-with-docs)

2026-09-15 roster-keepers-2026-09-15

The inline CONTEXT.md update ran without the offer the block requires (J-2, from the audit J-1's findings 29 to 31); it now waits on the request's grant or an offer, a method edit on the operator's word of 2026-09-15 at the card J-8, with J-2 folded in.

SKILL.md

methodchangedroster-keepers-2026-09-15

the side-effect bullet updates CONTEXT.md right there only when the request's grant covers it, and otherwise offers the entry in one line, matching the block's situational-skill rule; the method edit is on the operator's word of 2026-09-15 at the card J-8, with J-2 folded in

- **Sharpening a fuzzy term during the conversation?** Update `CONTEXT.md` right there.
- **Sharpening a fuzzy term during the conversation?** Update `CONTEXT.md` right there when the request's grant covers it, or offer the entry in one line.

2026-09-15 roster-keepers-fix-2026-09-15

The review REV-J-8 (Spec 1) found the first inline write, adding a missing term to CONTEXT.md, still unguarded; it now waits on the request's grant or an offer like the second, a method edit on the operator's word of 2026-09-15 at the card J-8, with J-2 folded in. The earlier claim is carried forward.

SKILL.md

methodchangedroster-keepers-fix-2026-09-15

both side-effect bullets write CONTEXT.md only when the request's grant covers it and otherwise offer the entry in one line, matching the block's situational-skill rule; carried from roster-keepers-2026-09-15; the method edit is on the operator's word of 2026-09-15 at the card J-8, with J-2 folded in

- **Naming a deepened module after a concept not in `CONTEXT.md`?** Add the term to `CONTEXT.md`. Create the file lazily if it doesn't exist.
- **Naming a deepened module after a concept not in `CONTEXT.md`?** Add the term to `CONTEXT.md` when the request's grant covers it, creating the file lazily if it doesn't exist; otherwise offer the entry in one line.
- **Sharpening a fuzzy term during the conversation?** Update `CONTEXT.md` right there.
- **Sharpening a fuzzy term during the conversation?** Update `CONTEXT.md` right there when the request's grant covers it, or offer the entry in one line.