arch-code-review
starsforks
How to install arch-code-review?
prinova/pi-agent-codebase-workflows/arch-code-review
$npx -y skills add PriNova/pi-agent-codebase-workflows --skill arch-code-reviewArchitecture-aware review against canonical structured YAML artifacts. Read-only workflow; no legacy prose docs.
SKILL.md
| 1 | # Architecture Code Review — Structured API Only |
| 2 | |
| 3 | Goal: review diffs for correctness, drift, data consistency, side-effect boundaries, contract compatibility, and tests using YAML artifacts from the resolved structured docs root. |
| 4 | |
| 5 | |
| 6 | ## Structured Artifact API Contract |
| 7 | |
| 8 | Legacy prose artifacts are deprecated. Do not create, update, or rely on `docs/agent/*.md`, scoped prose docs, or generated human-readable Markdown views. Use structured YAML for canonical artifacts. Root `AGENTS.md` remains a harness interoperability file and may be generated/updated only by workflows that explicitly say so. |
| 9 | |
| 10 | Resolved structured docs root: |
| 11 | |
| 12 | Treat `docs/agent/api` as a logical layout rooted at a resolved structured docs root, not a fixed repo path. |
| 13 | |
| 14 | Resolution rules: |
| 15 | 1. Resolve `workspace_root` with `git rev-parse --show-toplevel 2>/dev/null` or fallback to `pwd`. |
| 16 | 2. Canonicalize `workspace_root` before fingerprinting when possible (`realpath`, `pwd -P`, `Path(...).resolve()`, or equivalent). |
| 17 | 3. `safe-start` always creates and uses the initial repo-local root: `<workspace_root>/docs/agent/api`. |
| 18 | 4. Review reads repo-local only when `<workspace_root>/docs/agent/api` already exists. |
| 19 | 5. Otherwise read the global overlay root: `~/.pi/agent/workspaces/<workspace-fingerprint>/docs/agent/api`. |
| 20 | 6. Compute `<workspace-fingerprint>` exactly from canonical `workspace_root`: strip one leading slash/backslash, replace every slash, backslash, and colon with `-`, then wrap with `--`. This keeps the same workspace stable. |
| 21 | 7. Example: `/data/data/com.termux/files/home/CodeProjects/pi-mono` -> `--data-data-com.termux-files-home-CodeProjects-pi-mono--`. |
| 22 | 8. Do not create new repo-local structured docs in unadopted repos unless the user explicitly asks for repo-local adoption there. |
| 23 | |
| 24 | Logical structured layout under the resolved docs root: |
| 25 | |
| 26 | ```text |
| 27 | repo/ |
| 28 | scopes.yaml |
| 29 | repo-inventory.yaml |
| 30 | project-intent.yaml |
| 31 | architecture.yaml |
| 32 | data-flow.yaml |
| 33 | data-model.yaml |
| 34 | invariants.yaml |
| 35 | dependency-rules.yaml |
| 36 | design-issues.yaml |
| 37 | risk-register.yaml |
| 38 | change-guide.yaml |
| 39 | testing-strategy.yaml |
| 40 | validation-baseline.yaml |
| 41 | contracts.yaml |
| 42 | adr.yaml |
| 43 | agent-operating-guide.yaml |
| 44 | scopes/ |
| 45 | by-path/<repo-relative-path>/... |
| 46 | by-domain/<slug>/... |
| 47 | ``` |
| 48 | |
| 49 | Every structured artifact must conform to `../_shared/references/schemas/common.schema.json` plus its artifact-specific schema. Do not inline, invent, or vary envelope fields. |
| 50 | |
| 51 | Stable IDs required: `scope:*`, `component:*`, `entity:*`, `invariant:*`, `risk:*`, `contract:*`, `flow:*`, `command:*`, `issue:*`, `adr:*`, `testplan:*`. |
| 52 | |
| 53 | Ownership rules: |
| 54 | - `scopes`: scope routing, ownership, cross-scope discovery only. |
| 55 | - `repo-inventory`: file tree, commands index, entry points, external boundaries, configs. |
| 56 | - `validation-baseline`: command status, blockers, recommended validation order. |
| 57 | - `project-intent`: goals, users, journeys, non-goals, constraints, assumptions. |
| 58 | - `architecture`: components, architecture style, side-effect boundaries, high-level flow refs. |
| 59 | - `data-flow`: typed flow graph/steps, inputs, outputs, error states. |
| 60 | - `data-model`: entities, IDs, schemas, relationships, lifecycles, serialized formats. |
| 61 | - `invariants`: rules, forbidden states, enforcement locations, invariant-test refs. |
| 62 | - `dependency-rules`: layers, allowed/forbidden dependencies, violations, coupling hotspots. |
| 63 | - `design-issues`: structural drift, deferred decisions, ambiguity, ownership gaps. |
| 64 | - `risk-register`: failure modes, severity/confidence, affected refs, suggested tests/fixes. |
| 65 | - `contracts`: cross-scope APIs, schemas, events, generated clients, DB/file/deployment/env contracts. |
| 66 | - `testing-strategy`: test topology, coverage gaps, risk-to-test priorities. |
| 67 | - `change-guide`: workflow routing and checklists; references owner artifacts, duplicates no facts. |
| 68 | - `adr`: structured decision records with bounded prose fields. |
| 69 | - `agent-operating-guide`: structured source for agent operating rules. Root `AGENTS.md` may mirror this in compact harness-readable Markdown when produced by safe-start or codebase-recon Pass 6. |
| 70 | |
| 71 | Redundancy rule: define each fact in its owner artifact exactly once. Other artifacts reference IDs. |
| 72 | Prose rule: bounded prose allowed only in `summary`, `notes`, `rationale`, `context`, `decision`, `recommended_action`, and similar scalar fields. |
| 73 | Scope rule: if focus is path-like, read under `<docs-root>/scopes/by-path/<focus>/`; otherwise under `<docs-root>/scopes/by-domain/<slug>/`. Always resolve scope from `<docs-root>/repo/scopes.yaml` when present. |
| 74 | |
| 75 | |
| 76 | |
| 77 | ## Runtime Schema Loading |
| 78 | |
| 79 | When a workflow creates, updates, migrates, or validates structured artifacts, read `../_shared/references/artifact-api.md` first. Then read only the shared skill package schemas needed for the artifacts being written: |
| 80 | - `../_shared/references/schemas/common.schema.json` |
| 81 | - `../_shared/referenc |
People who liked this also viewed
6 picksType
- requesting-code-reviewUse when completing tasks, implementing major features, or before merging to verify work meets requirementsSkillsJul 2026
- code-reviewSkills for Real Engineers. Straight from my .agents directory.SkillsJul 2026
- receiving-code-reviewUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performativeSkillsJul 2026
- baoyu-format-markdownFormats plain text or markdown files with frontmatter, titles, summaries, headings, bold, lists, and code blocks. Use when user asks to "format markdown", "beautify article", "add formatting", or imprSkillsJul 2026
- code-review-excellenceMaster effective code review practices to provide constructive feedback, catch bugs early, and foster knowledge sharing while maintaining team morale. Use when reviewing pull requests, establishing reSkillsJul 2026
- code-review-and-qualityConducts multi-axis code review. Use before merging any change. Use when reviewing code written by yourself, another agent, or a human. Use when you need to assess code quality across multiple dimensiSkillsJul 2026
