architecture-review
Skill45 starsChanged 53 days agoMITView on GitHub
Run Proqi's deliberate repository-wide architecture audit with independent Codex and Claude Fable reviews, synthesize evidence, and complete a behavior-preserving refactor on main. Use for a global architecture pass, not an ordinary feature or pull-request review.
85 other projects use a version of this.
Adopted by
Most recently taken up by
- lx-wnk/skillstheir own version, first seen Nov 16, 2026
- seancabalse/agentic-playbooktheir own version, first seen Nov 16, 2026
- erikperttu/steering-coding-agentstheir own version, first seen Nov 16, 2026
- Sequela02/canastatheir own version, first seen Nov 15, 2026
- OmarAlex24/audit-skillstheir own version, first seen Nov 15, 2026
- chuanglibs/Claude-Code-Game-Studios-Codextheir own version, first seen Nov 15, 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
lilangMaxSkillstory-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 versions85 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 85
- Donchitos/Claude-Code-Game-Studios★ 39ksame name
- langwatch/langwatch★ 5ksame name
- ghuntley/loom★ 1.7ksame name
- microsoft/hve-core★ 1.6ksame name
- DataDog/dd-trace-js★ 842same name
- decebals/claude-code-java★ 763same name
- borgbase/vykar★ 726same name
- appdevforall/CodeOnTheGo★ 621same name
- owainlewis/blueprint★ 432same name
- getsentry/warden★ 424same name
75 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 repository11 other files it gives its agents.
- AGENTS.mdAGENTS.md
- tests/AGENTS.mdAGENTS.md
- xtask/AGENTS.mdAGENTS.md
- claude-code-reviewSkill
- codex-reviewSkill
- implement-in-worktreeSkill
- proqi-screenshotSkill
- releaseSkill
- walkthroughSkill
- proqi-debugSkill
- proqiSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
16 rules. 0 are common, 12 are distinctive, and 4 are very specific to this project.
0
Common
Most of the 77 edited versions we read keep these.
12
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
- could be automatic: a setting could enforce it
- Very specific: line 19
Read every applicable AGENTS.md, then read context/PRODUCT.md and context/ARCHITECTURE.md completely before reviewing boundaries or …
- Distinctive: line 31
Do not remove, disable, redesign, or add product features.
- Distinctive: line 44
Use exactly one native subagent from the invoking harness and one CLI-dispatched reviewer from the other harness.
- Very specific: line 67
Do not dispatch codex exec from a Codex primary.
- Distinctive: line 86
Do not dispatch Claude CLI from a Claude primary.
- Very specific: line 92
Never create or split a Herdr pane, tab, workspace, or worktree for either reviewer, and never use herdr agent start or herdr agent prompt …
- Distinctive: line 98
Ask each lane for one complete independent review rather than splitting ownership into unrelated micro-audits.
- Distinctive: line 109
If the opposite harness is unavailable, exhaust its ordinary authenticated read-only launch path, report the exact blocker, and continue …
- Distinctive: line 121
use history and blame selectively to distinguish intentional seams from accidental extraction or linter-driven movement.
- Distinctive: line 156
keep constructors and private fields responsible for invariants, and retain injected time, filesystem, process, clipboard, path, and ID …
- Distinctive: line 158
do not weaken enforcement, delete meaningful coverage, accept snapshots automatically, or compact readable code to game a gate.
- Distinctive: line 161
When the review establishes a durable ownership rule that future contributors must follow, update the narrowest applicable AGENTS.md.
- Distinctive: line 167
Commit coherent architecture changes on main.
- Distinctive: line 173
Run focused tests while moving each responsibility.
- Very specific: line 175
Run cargo xtask check. For a global architecture milestone, also run cargo xtask audit and cargo xtask package.
- Distinctive: line 206
Delete only owned temporary prompts and review output after extracting the needed evidence.
“Common” is measured: kept by at least 6 in 10 of the 77 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
Re-run Proqi's full architecture-review workflow without turning it into a
feature project. The default is the original end-to-end workflow: independent
parallel reviews, evidence reconciliation, a behavior-preserving refactor on
main, instruction updates when justified, complete verification, commit,
push, and green CI. If the user explicitly asks for review-only output, stop
before repository edits, commits, or pushes.
Establish authority and a safe base
- Confirm this is the Proqi repository by locating
Cargo.toml,AGENTS.md,context/PRODUCT.md, andcontext/ARCHITECTURE.mdat the repository root. - Read every applicable
AGENTS.md, then readcontext/PRODUCT.mdandcontext/ARCHITECTURE.mdcompletely before reviewing boundaries or changing code. Read the review rubric completely. - Record the current branch, exact
HEAD, upstream, worktree list, status, and relevant active pull requests. Preserve every unrelated tracked or untracked user change. Never stash, reset, clean, overwrite, or absorb it into the architecture work. - The implementation phase runs directly on
main, matching the original workflow. Before editing, require localmainandorigin/mainto agree and require a clean tracked tree except for changes the user explicitly assigned to this review. A dirty or divergent checkout does not prevent read-only review, but it blocks implementation until the owner resolves it. - Do not remove, disable, redesign, or add product features. Visible behavior, public Rust paths, CLI/JSON spelling, durable encodings, snapshots, failure classification, and Herdr contracts remain unchanged unless the user separately authorizes a contract change.
An unqualified explicit invocation of this skill authorizes the complete local
review/refactor workflow and its ordinary commit, main push, and CI monitoring
steps. It does not authorize a release, tag, package publication, repository
setting change, destructive cleanup, or unrelated work. A user instruction such
as “review only,” “do not push,” or a narrower scope always wins.
Run independent reviews in parallel
Use exactly one native subagent from the invoking harness and one CLI-dispatched reviewer from the other harness. Never launch the invoking harness through its own CLI, never replace the native subagent with a second external process, and never run two reviewers from only one model family. Both reviewers inspect the same exact base without seeing each other's findings or a proposed answer. The primary also performs its own repository inspection; reports are evidence leads, not authority.
When the primary is Codex
- Spawn one native Codex subagent through Codex's subagent/collaboration mechanism. Give it the exact base, the complete repository rubric, and a strict read-only architecture-review assignment.
In parallel, dispatch Claude Code CLI using the project agent
.claude/agents/proqi-architecture-reviewer.md, the Fable model, plan permissions, no session persistence, and captured final output. A representative invocation is:claude -p --model fable --agent proqi-architecture-reviewer \ --permission-mode plan --no-session-persistence
Do not dispatch codex exec from a Codex primary. The native Codex subagent is
the Codex review lane.
When the primary is Claude Code
- Spawn the project
proqi-architecture-revieweras a native Claude Code subagent through Claude's agent/task mechanism. Its checked-in definition pins the Fable model and plan permissions. In parallel, dispatch one ephemeral Codex CLI review with the repository mounted read-only, for example:
codex exec --ephemeral --sandbox read-only -C REPOSITORY_ROOT -Provide the exact base and complete rubric through standard input or an owned temporary prompt file, never by interpolating untrusted repository text into a shell command.
Do not dispatch Claude CLI from a Claude primary. The native Fable subagent is the Claude review lane.
Shared dispatch rules
- Both reviewers must be non-interactive background workers relative to Herdr.
Never create or split a Herdr pane, tab, workspace, or worktree for either
reviewer, and never use
herdr agent startorherdr agent promptto host a review. Native reviewers use the invoking harness's subagent mechanism. CLI reviewers use the invoking harness's managed process runner in the existing review worktree. - Dispatch both lanes before waiting for either so they run concurrently.
- Ask each lane for one complete independent review rather than splitting ownership into unrelated micro-audits. A reviewer may use read-only helpers for evidence gathering when supported, but it returns one reconciled report.
- Supply a concise instruction to audit the exact recorded revision using the repository rubric and return findings without editing. Do not put source, secrets, credentials, or the other reviewer's conclusions in command-line arguments.
- CLI-dispatched harnesses may require network access. When the current sandbox restricts it, request normal outside-sandbox authorization rather than treating a network failure as an architectural result. Use existing user authentication and never print, copy, or persist credential values.
- If the opposite harness is unavailable, exhaust its ordinary authenticated read-only launch path, report the exact blocker, and continue the primary and native-agent inspections. Never fabricate a second review.
Inspect and reconcile
Inspect the repository directly while the independent lanes run:
- map the folder tree, domain/application/port/adapter/UI ownership, public import paths, durable schemas, and composition roots;
- inspect representative implementation and tests rather than inferring design from names;
- use history and blame selectively to distinguish intentional seams from accidental extraction or linter-driven movement;
- locate semantic duplication, magic compatibility strings, oversized responsibilities, dead paths, and tests whose placement obscures ownership;
- trace shared rendering, measurement, truncation, hit geometry, cursor, selection, folds, and annotation behavior through all consumers.
For every external finding, verify the cited code and contract yourself. Classify it as confirmed, partially confirmed, rejected with evidence, or a product decision requiring Oliver. Resolve disagreement from source evidence, not majority vote. Prefer no change over an abstraction without a clear owner or demonstrated drift risk.
Produce one ordered refactor plan with dependencies. Separate behavior-neutral architecture work from feature ideas and optional aesthetic preferences. Stop for user direction when a finding requires visible behavior, removal of a feature, a durable/public contract change, or a substantial prerequisite whose scope no longer resembles an architecture cleanup.
Refactor directly on main
Implement only confirmed behavior-neutral improvements:
- move responsibilities to the innermost correct owner and preserve canonical public re-exports where required;
- consolidate semantic rules and compatibility vocabularies at one source of truth, removing superseded paths in the same change;
- extract reuse when at least three consumers share a rule, or when two consumers drifting would be incorrect or unsafe;
- split modules and tests by responsibility, never merely to satisfy line or complexity limits;
- move behavior-owned tests beside their owner and keep cross-layer, process, persistence, and PTY contracts in top-level tests;
- replace known closed-set strings with typed identifiers, enums, or constants at the innermost valid boundary while preserving external spellings;
- keep constructors and private fields responsible for invariants, and retain injected time, filesystem, process, clipboard, path, and ID boundaries;
- do not weaken enforcement, delete meaningful coverage, accept snapshots automatically, or compact readable code to game a gate.
When the review establishes a durable ownership rule that future contributors
must follow, update the narrowest applicable AGENTS.md. Add a nested file only
for a genuine domain-specific rule set. Every AGENTS.md must retain its sibling
relative CLAUDE.md -> AGENTS.md symlink. Do not turn one refactor's incidental
shape into permanent policy.
Commit coherent architecture changes on main. Do not mix feature backlog,
generated review reports, temporary agent output, local paths, or credentials
into the commits.
Verify and challenge the result
- Run focused tests while moving each responsibility. Explicitly compare representative snapshots and outward fixtures before and after the refactor.
- Run
cargo xtask check. For a global architecture milestone, also runcargo xtask auditandcargo xtask package; use required host permissions for legitimate local socket, PTY, packaging, or platform tests rather than weakening them. - Inspect the final tree, diff, public paths, test placement, line counts, dependency direction, and working-tree status. Prove that behavior-neutral claims are reflected in unchanged outward fixtures and snapshots.
- Repeat the same harness pairing for the final pass: the invoking harness uses a fresh native subagent and the opposite harness is dispatched through its CLI. Give both reviewers the completed diff and relevant resulting files without the expected verdict. Reconcile and fix every confirmed regression, duplicate owner, misplaced test, or linter workaround they find, then rerun affected checks.
- Push the reviewed commits to
mainonly when the invocation authorizes the full workflow. Monitor the complete required CI result and fix failures caused by the refactor. Retry an evidenced infrastructure flake once; do not weaken a gate or make unrelated product changes to obtain green CI.
Report
Return a concise architecture handoff containing:
- exact base and final SHAs;
- the independent Codex and Fable verdicts and how disagreements were resolved;
- confirmed findings, implemented moves/deduplication/test restructuring, and explicit keep-as-is decisions;
- instruction files added or changed and the durable rule each captures;
- focused, canonical, audit, package, final-review, push, and CI evidence;
- any unresolved blocker or product decision, without presenting it as a completed refactor.
Delete only owned temporary prompts and review output after extracting the needed evidence. Never delete an agent session, worktree, user file, or review artifact whose ownership is uncertain.
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.

