[architecture] Update architecture diagram - 2026-06-08

[github-actions]

Incremental update — 3 structural changes detected since last run (80265a5→6badeca5):

• cmd/linters — New entry-point binary running all custom Go vet-style linters
• pkg/workflow/compilerenv — New core sub-package for compiler environment management (used by cli + workflow)
• pkg/importinpututil — New utility for import path/sub-key resolution (used by workflow + parser)

Changes from previous diagram

• Added cmd/linters as a third entry point (alongside cmd/gh-aw and cmd/gh-aw-wasm)
• Added workflow/compilerenv to the core section (below workflow)
• Added importinpututil to the utility section
• Updated dependency arrows: workflow→importinpututil, parser→importinpututil, cli→compilerenv, workflow→compilerenv

New entries in Package Reference table

Package	Layer	Description
workflow/compilerenv	Core	Compiler environment management (used by cli + workflow)
importinpututil	Util	Import path/sub-key resolver

References: §27130523118

Generated by 🏗️ Architecture Diagram Generator · ⌖ 16.5 AIC · ⊞ 17.5K · ◷

• expires on Jun 15, 2026, 2:22 AM UTC-08:00

[github-actions]

🧠 Matt Pocock Skills Reviewer has completed the skills-based review. ✅

[github-actions]

✅ PR Code Quality Reviewer completed the code quality review.

[github-actions]

🧪 Test Quality Sentinel completed test quality analysis.

No test files were added or modified in this PR. The only changed file is scratchpad/architecture.md (48 additions, 47 deletions). Test Quality Sentinel skipped.

[github-actions]

✅ Design Decision Gate 🏗️ completed the design decision gate check.

No ADR enforcement needed: PR #37794 does not have the implementation label (has_implementation_label=false) and has 0 new lines of code in business logic directories (requires_adr_by_default_volume=false, threshold=100). No custom design-gate config present.

[Copilot]

Pull request overview

Updates the repository’s architecture diagram and package reference to reflect recent structural changes in gh-aw, keeping the high-level documentation aligned with the current codebase layout.

Changes:

• Refreshed the “Last updated” timestamp and workflow-run source link.
• Updated the ASCII architecture diagram to include cmd/linters and the new packages (workflow/compilerenv, importinpututil).
• Extended the Package Reference table with the new core/util entries.

Show a summary per file

File	Description
scratchpad/architecture.md	Updates the architecture diagram and package reference to reflect new entry points/packages and their intended placement in the layering model.

Copilot's findings

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

• Files reviewed: 1/1 changed files
• Comments generated: 2

[github-actions]

Skills-Based Review 🧠

Applied /grill-with-docs and /zoom-out — two non-blocking observations on the updated diagram.

📋 Key Themes & Highlights

Issues flagged

• Layer inconsistency: pkg/linters/* is drawn inside the CORE PACKAGES visual region but classified as Domain in the Package Reference table (see inline comment at line 22). A reader scanning the diagram top-to-bottom would reasonably infer it belongs to the Core layer.
• Sub-package relationship not surfaced: workflow/compilerenv is rendered as a peer of types and constants, with no indication that it is a sub-package of workflow (see inline comment at line 39).
• Missing dependency arrows: The PR description lists four new dependency edges (workflow→importinpututil, parser→importinpututil, cli→compilerenv, workflow→compilerenv), but none of these arrows appear in the ASCII art. The old diagram had explicit directional arrows between packages; their absence makes the new packages look disconnected from the dependency graph.

Positive highlights

• ✅ All three new packages (cmd/linters, workflow/compilerenv, importinpututil) are now reflected in both the diagram and the Package Reference table.
• ✅ The updated description for workflow clarifies the target format (MD → GH Actions YAML) — a nice accuracy improvement.
• ✅ actionpins gets an expanded description (resolution & version mgmt) that better reflects what the package actually does.

🧠 Reviewed using Matt Pocock's skills by Matt Pocock Skills Reviewer · 170.2 AIC · ⌖ 13.6 AIC

[github-actions]

[/grill-with-docs] pkg/linters/* appears visually inside the CORE PACKAGES region, but the Package Reference table (below) correctly classifies linters as Domain. This mismatch could mislead readers into treating the linters package as a core abstraction.

💡 Suggestion

Move the pkg/linters/* label into the DOMAIN PACKAGES section of the ASCII art (below the ├─ DOMAIN PACKAGES ─┤ divider), or draw an arrow from cmd/linters directly to the linters box in the Domain section. This keeps the visual layer placement consistent with the Package Reference table.

[github-actions]

[/zoom-out] workflow/compilerenv is shown as a peer of types and constants in the Core row, but it is a sub-package of workflow. The diagram does not indicate this parent-child relationship, which may suggest it is a standalone Core package equal in rank to workflow itself.

💡 Suggestion

Consider either:

1. Nesting workflow/compilerenv visually beneath the workflow box (e.g., a sub-label inside or below it), or
2. Adding a brief note like (sub-package of workflow) in the ASCII art or the table description to make the ownership clear.

The Package Reference table entry already hints at this with "used by cli + workflow", but the visual layout does not reinforce it.

[github-actions]

Diagram accuracy issues in the updated architecture doc

This PR adds cmd/linters, workflow/compilerenv, and importinpututil to the architecture diagram — all real packages that were missing. The additions are correct. Three structural problems were introduced in the process:

🔎 Findings (3 non-blocking)

1. pkg/linters/* dual-layer confusion (line 22 vs line 47): The same pkg/linters/ directory is shown as a floating label in CORE PACKAGES and as the linters box in DOMAIN PACKAGES. The package table correctly lists it once under Domain. The diagram should reconcile this.

2. Disconnected arrows (line 21): The ▼ symbols for cmd/gh-aw and cmd/gh-aw-wasm have no vertical connector rows between them and the cli/workflow boxes below. The old diagram used ┼ in the separator bar to thread the arrows through; the new layout breaks that continuity.

3. console dependency edge dropped (line 36): The old diagram showed console → types; the new one severs this edge. Likely still a real dependency.

All three are documentation-accuracy issues, not code defects. Non-blocking, but the diagram generator should address them before this diagram is treated as authoritative.

🔎 Code quality review by PR Code Quality Reviewer · ⌖ 13.3 AIC

[github-actions]

pkg/linters/* is shown in two architectural layers — here in CORE PACKAGES and again as linters in DOMAIN PACKAGES (line 47). Both labels map to the same pkg/linters/ directory, making the diagram self-contradictory about which layer these analyzers belong to.

💡 Details

The intent appears to be showing cmd/linters → pkg/linters/*, but the result is:

• pkg/linters/* floating in the CORE section (this line)
• linters listed again as a DOMAIN package at line 47

The package reference table correctly classifies it once as Domain. The ASCII diagram should either:

1. Remove pkg/linters/* from the CORE area and draw a direct arrow from cmd/linters (entry point) down to the linters box in the DOMAIN section, or
2. Keep it here but remove the duplicate linters box from DOMAIN.

Also note the naming inconsistency: all other packages use short names (cli, workflow, etc.) without pkg/ prefix, but this label uses pkg/linters/* with the full path prefix.

[github-actions]

cmd/gh-aw and cmd/gh-aw-wasm arrows are visually disconnected from the cli/workflow boxes below — the ▼ symbols appear after the section separator but no vertical connector lines bridge them to the boxes at lines 24–29.

💡 Details

The old diagram threaded arrows through the section separator using ┼ connectors, preserving visual continuity:

│                 │         ...         │                           │
├─────────────────┼─────────...─────────┼───────────────────────────┤
│                 ▼    CORE PACKAGES    ▼                           │

The new design places ▼ symbols on the line immediately after the separator (line 21), then two blank rows, then the cli and workflow boxes (line 24) — with no connecting │ rows between them. As drawn, the arrows from cmd/gh-aw and cmd/gh-aw-wasm lead nowhere and the cli/workflow boxes appear to have no inputs. The ▼ for cmd/linters at least has pkg/linters/* on the next line as a target, making that connection marginally clearer.

To fix: add a row of │ characters between line 21 and line 24, aligned under the ▼ symbols, to reconnect the flow visually — or move the CORE PACKAGES label back into the separator bar.

[github-actions]

console lost its outgoing dependency edge — the old diagram showed console → types with an explicit connector (└────────┬─────────┘ → │ → ▼ → types). The new diagram closes the console box with a flat bottom and shows no outgoing edges.

💡 Details

If console still imports types (which is likely given it uses shared type definitions for message formatting), this dependency is now invisible in the diagram. The omission makes console look like a leaf package with no downstream dependencies, which may mislead readers about the layer structure.

Verify whether console depends on types and restore the edge if so. If the dependency was intentionally removed as part of a refactor, a note would help clarify the change.