[architecture] Update architecture diagram - 2026-05-25

[github-actions]

PR #34623 — [architecture] Update architecture diagram - 2026-05-25

Repository: github/gh-aw

---

Summary

Refreshes the architecture diagram in scratchpad/architecture.md to reflect the current state of the codebase as of 2026-05-25. The update restructures the ASCII box diagram into a cleaner, narrower three-tier layout and brings package assignments, descriptions, and command listings into sync with recent structural changes.

---

Changes

File modified: scratchpad/architecture.md

This is a documentation-only change. No source code, configuration, or public API is affected.

What changed in the diagram

Area	Before	After
Timestamp / source link	2026-05-18 / run §26026605299	2026-05-25 / run §26394747908
Entry points shown	cmd/gh-aw, cmd/gh-aw-wasm, cmd/linters	cmd/gh-aw, cmd/gh-aw-wasm only
Core packages	cli, workflow, parser, console, agentdrain	cli, workflow, parser, console, types, constants
Domain packages tier	(not present)	actionpins, agentdrain, linters, stats
cli commands listed	compile, run, audit, logs, mcp, stats	compile, run, audit, mcp, logs, campaigns
Utility packages	15 packages	Same set + syncutil

Key structural decisions captured

• cmd/linters removed from entry points — it is now represented inside the new Domain Packages tier, reflecting its role as an internal tool rather than a top-level binary entry point.
• types and constants promoted to the Core layer — these were previously implicit; they are now explicitly called out as foundational Core packages.
• New "Domain Packages" tier introduced — actionpins, agentdrain, linters, and stats are broken out into their own tier between Core and Utility, acknowledging their domain-specific responsibilities distinct from general-purpose utilities.
• workflow description updated to note lock file generation; cli description updated to list campaigns as a supported command.
• syncutil added to the Utility package list.

---

Impact

Dimension	Assessment
Breaking change	No
Source code affected	No
Tests required	No
Review focus	Accuracy of package descriptions and tier assignments against the current codebase

---

Checklist

• Documentation only — no code changes
• Diagram reflects current package structure (2026-05-25)
• Package reference table updated to match diagram
• Reviewer: verify tier assignments match actual import graph

Generated by PR Description Updater for issue #34623 · sonnet46 839.7K · ◷

[github-actions]

⚠️ PR Code Quality Reviewer failed during code quality review.

[github-actions]

🧠 Matt Pocock Skills Reviewer has completed the skills-based 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 (an architecture diagram update). Test Quality Sentinel skipped.

[github-actions]

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

No ADR enforcement needed: PR #34623 does not have the 'implementation' label and has 0 new lines of code in business logic directories (well under the 100-line threshold).

[Copilot]

Pull request overview

Updates scratchpad/architecture.md with a regenerated architecture diagram and refreshed package reference intended to reflect the current layered dependency structure of the gh-aw codebase.

Changes:

• Replaced the previous ASCII architecture diagram with a new 4-layer layout (Entry Points → Core → Domain → Utility).
• Updated the package reference table with new layer assignments and one-line descriptions.
• Refreshed the “Last updated” timestamp and workflow run link.

Show a summary per file

File	Description
scratchpad/architecture.md	Regenerates the architecture diagram and package reference table to reflect the current package layering.

Copilot's findings

Tip

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

Comments suppressed due to low confidence (2)

scratchpad/architecture.md:46

• The horizontal separator line has an extra space before the closing border character ("...────── ┤"), which can cause misalignment in monospace rendering. Consider removing the trailing space so the border is consistent with the other separators.

├──────────────────────────────── DOMAIN PACKAGES ─────────────────────────────────────── ┤

scratchpad/architecture.md:54

• Same as above: the UTILITY PACKAGES separator line has a trailing space before the closing border character ("...───── ┤"), which can misalign the diagram in monospace rendering. Consider removing the extra space.

├──────────────────────────────── UTILITY PACKAGES ────────────────────────────────────── ┤

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

[github-actions]

Skills-Based Review 🧠

Applied /zoom-out and /grill-with-docs — requesting changes for one factual inaccuracy.

📋 Key Themes & Highlights

Key Issues

• Missing entry point: cmd/linters still exists in the repo but is absent from both the diagram and the table — factual gap that could mislead contributors
• Path prefix removal: Dropping pkg//cmd/ prefixes from the table trades navigational precision for brevity
• Minor rendering artifact: -─ mixed character on the workflow box border (cosmetic)

Positive Highlights

• ✅ The four-layer structure (Entry Points → Core → Domain → Utility) is cleaner and more accurate than the old three-layer model
• ✅ Adding syncutil to the table fills a real gap
• ✅ Moving agentdrain, linters, stats to a dedicated Domain layer reflects their actual role better
• ✅ Improved description of the overall pipeline flow in the Overview section

🧠 Reviewed using Matt Pocock's skills by Matt Pocock Skills Reviewer · sonnet46 1.2M

Comments that could not be inline-anchored

scratchpad/architecture.md:17

[/zoom-out] cmd/linters is missing from the new Entry Points section — it still exists at cmd/linters/ in the repo.

<details>
<summary>💡 Suggestion</summary>

The old diagram included cmd/linters as a third entry point alongside cmd/gh-aw and cmd/gh-aw-wasm. Since that binary still exists, omitting it makes the diagram inaccurate and could mislead developers about the codebase's binary surface.

Add it back to the Entry Points box, similar to:

│  ┌──────────────────┐  ┌─────…

</details>

<details><summary>scratchpad/architecture.md:170</summary>

**[/grill-with-docs]** Package names in the table dropped their `pkg/` and `cmd/` path prefixes — reducing precision for developers trying to navigate the repo.

&lt;details&gt;
&lt;summary&gt;💡 Suggestion&lt;/summary&gt;

Using bare names like `cli` or `workflow` is ambiguous; the full import paths (`pkg/cli`, `pkg/workflow`) are what developers type in `go list` queries, editor navigation, and import statements. Consider keeping the qualified names (e.g., `pkg/cli`) or at least adding a note that all paths ar…

</details>

<details><summary>scratchpad/architecture.md:96</summary>

**[/zoom-out]** Minor rendering artifact on the workflow box border: `-─` (hyphen followed by em-dash) instead of consistent `─` characters.

&lt;details&gt;
&lt;summary&gt;💡 Fix&lt;/summary&gt;

Line ends with `──────────────────-─┘` — replace the `-─` with `──` to match the rest of the box-drawing characters.

&lt;/details&gt;

</details>