architecture-review
Skill277 starsChanged 35 days agoMITView on GitHub
Use when reviewing a PR, branch, or staged diff in the openboot repo. Audits the change against project invariants from AGENTS.md — subprocess hygiene, HTTP wrapper usage, error wrapping, dry-run gating, UI helper usage, test placement. Trigger when user says "review this", "check this PR", "audit the diff", or asks about whether a change follows project conventions.
- Pipes a download into a shell
78 other projects use a version of this.
Adopted by
Most recently taken up by
- kinhluan/skillstheir own version, first seen Nov 8, 2026
- Smaui94/ClaudeSkillCollectiontheir own version, first seen Nov 8, 2026
- AndersonAndrad/skillstheir own version, first seen Nov 8, 2026
- frnkgns/Overgeared-Skillstheir own version, first seen Nov 8, 2026
- striderZA/OpenCodeGameStudiostheir own version, first seen Nov 4, 2026
- nledford/engineering-review-boardtheir own version, first seen Nov 3, 2026
Used with
Projects with it also use create-stories, story-done and 10 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
lilangMaxSkillcreate-stories
Break a single epic into implementable story files. Reads the epic, its GDD, governing ADRs, and control manifest. Each story embeds its GDD requirement TR-ID, ADR guidance, acceptance criteria, story type, and test evidence path. Run after /create-epics for each epic.
Also in 11 projects that use this
- lilangMaxSkill
story-done
End-of-story completion review. Reads the story file, verifies each acceptance criterion against the implementation, checks for GDD/ADR deviations, prompts code review, updates story status to Complete, and surfaces the next ready story from the sprint.
Also in 11 projects that use this
- +10 more from lilangMax
Other versions78 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 78
- Donchitos/Claude-Code-Game-Studios★ 27ksame name
- langwatch/langwatch★ 5ksame name
- ghuntley/loom★ 1.7ksame name
- microsoft/hve-core★ 1.6ksame name
- DataDog/dd-trace-js★ 840same name
- decebals/claude-code-java★ 763same name
- borgbase/vykar★ 722same name
- appdevforall/CodeOnTheGo★ 586same name
- getsentry/warden★ 423same name
- owainlewis/blueprint★ 423same name
68 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository4 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- bootstrap-featureSkill
- ship-prSkill
The file
We split this skill into the rules it gives an agent
7 rules. 0 are common, 3 are distinctive, and 4 are very specific to this project.
0
Common
Most of the 70 edited versions we read keep these.
3
Distinctive
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 8
Run this checklist on any diff before approving it.
- Distinctive: line 21
If the diff spans more than ~10 files or mixes feature + refactor + docs, call that out and suggest splitting — one thing per commit is a …
- Distinctive: line 61
If the change is small enough to land without tests (e.g.
- Very specific: line 87
Do not approve a change that adds an archtest violation without an updated baseline/ file and a justification in the commit message.
- Distinctive: line 89
Do not approve mixed-purpose commits — request a split.
- Very specific: line 90
Do not approve changes to .github/workflows/ without confirming the workflow still runs (act locally or trigger on a draft PR).
- Very specific: line 92
Do not approve direct edits to data/packages.yaml without confirming the source-of-truth is openboot.dev (see AGENTS.md "Where to look").
“Common” is measured: kept by at least 6 in 10 of the 70 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Architecture review for openboot
Run this checklist on any diff before approving it. The checks map 1:1 to
the rules in AGENTS.md → "Project-specific conventions" and the
fitness functions in internal/archtest.
Step 1 — Diff scope
Confirm what's changed:
git diff --stat main...HEAD # files
git diff main...HEAD -- 'internal/**/*.go' # production GoIf the diff spans more than ~10 files or mixes feature + refactor + docs, call that out and suggest splitting — one thing per commit is a project convention.
Step 2 — Run the mechanical checks first
go vet ./...
make test-unit # includes archtest
golangci-lint run ./... # if availableThese catch ~80% of what a human reviewer would otherwise comment on. If they don't pass, stop reviewing and ask the author to fix first.
Step 3 — Architecture invariants (manual review of the diff)
For each changed file under internal/ or cmd/:
| Check | Look for | If violated |
| Subprocess | New exec.Command / exec.CommandContext call | Should be in internal/system or wrapped in a Runner. Reject + suggest internal/system.RunCommand. |
| HTTP | New http.NewRequest, http.Get, http.DefaultClient | Should go through internal/httputil.Do. Reject + suggest wrapper. |
| Home dir | os.Getenv("HOME"), hardcoded /Users/..., hardcoded "~/" | Use os.UserHomeDir(). |
| Error wrap | return err without context | Should be fmt.Errorf("doing X: %w", err) unless the error is already wrapped one frame up. |
| UI output | fmt.Println, fmt.Printf in non-UI packages | Use ui.Info, ui.Success, etc. (legacy violations are baselined — only flag NEW ones). |
| Dry run | New destructive operation (mkdir, write, exec, network mutate) | Must check cfg.DryRun and print [DRY-RUN] Would X instead. |
| Embedded data | New data/*.yaml or schema change | Confirm fallback path still loads. |
| State path | New file under ~/.openboot/ | Confirm the path is created via os.UserHomeDir(), perms are 0o600 for secrets / 0o755 for dirs. |
Step 4 — Test layer check
For each non-trivial change:
- Pure logic → must have an L1 test in
internal/<pkg>/. If missing, request it. - Subprocess interaction → fake via Runner in
internal/<pkg>/OR add a real-subprocess test undertest/integration/(still L1, no build tag). - CLI flag parsing → table-driven L1 test.
- Destructive op → must run cleanly under
--dry-runin a test.
If the change is small enough to land without tests (e.g. comment rewording, typo fix), say so explicitly rather than letting it pass unmentioned.
Step 5 — Behaviour invariants
| Check | Why it matters |
| Does the change break the curl|bash install path? | scripts/install.sh is the primary install vector. The smoke test CI job covers this — make sure it still passes. |
| Does the change alter the contract schema (config / snapshot JSON)? | If yes, the schema needs updating in openboot-contract repo and bumping. Otherwise the L2 contract job will fail. |
| Does the change add or change a CLI flag? | Confirm --help output is updated, and old-cli compat job still passes (previous release × new mock server). |
Does the change touch data/presets.yaml? | Three presets must still parse and resolve. |
Does the change touch ~/.openboot/* file format? | Confirm backward compat with old files (snapshot, auth, state) or write a migration. |
Step 6 — Risk assessment
End the review with:
- Risk: low / medium / high (one sentence on blast radius).
- Rollback: how a user / operator would revert (CLI flag, file delete, brew downgrade).
- Observability: what would tell us this broke in production (telemetry, GitHub issue pattern, smoke job).
What the reviewer SHOULD NOT do
- Do not approve a change that adds an archtest violation without an
updated
baseline/file and a justification in the commit message. - Do not approve mixed-purpose commits — request a split.
- Do not approve changes to
.github/workflows/without confirming the workflow still runs (actlocally or trigger on a draft PR). - Do not approve direct edits to
data/packages.yamlwithout confirming the source-of-truth is openboot.dev (see AGENTS.md "Where to look").
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.