Architecture, Planning & Code Review Discipline

Part of the engineering skill.

1. The 3-Artifact Architecture Standard

Every non-trivial system or integration maintains three living documents in the repository—each answering a distinct question:

Artifact	Question	Format & Mandatory Contents
ARCH.md	What are the system boundaries and trust zones?	C4 Model (System Context + Container diagrams in Mermaid) plus a concise component responsibility table.
DATAFLOW.md	How does data move, transform, and fail?	High-density Mermaid graph TB using subgraph blocks for system boundaries, followed by a mandatory Logic Q&A section answering non-obvious operational questions (idempotency keys, retry behavior, partial-failure recovery, negative overrides).
docs/adr/XXXX-title.md	Why did we choose this design, and when do we outgrow it?	Context, Decision, Consequences, and explicit Graduation Triggers (e.g., “When consumer count reaches 3, graduate from Tier 1 vendored copy to Tier 2 workspace package”).

Where Formal Methods (TLA+) Fit vs. Property Tests

• Do not apply formal methods (TLA+ / Lean) to I/O-bound integration glue: Glue bugs are boundary-shape and field-mapping bugs—solve them with Dual-Boundary (Reality-and-Oracle) Verification.
• Use TLA+ selectively at design time only when a subsystem has genuine multi-hop delivery safety/liveness invariants (“every privileged event produces at least one alert and zero silent drops”) or uncontrolled concurrent/at-least-once state transitions.
• Use Property-Based Testing (fast-check / Hypothesis) for complex pure data transformations, ciphers, and stateful store models—buying ~90% of proof confidence at ~5% of the effort.

---

2. Repo-First Specs & Plans (No Brain-Only Lock-In)

1. Commit Specs and Plans to the Repo:
   • Never leave design specs, discovery notes, or implementation plans trapped inside ephemeral AI session folders (.gemini/.../brain/, .claude/plans/).
   • Never use tool-specific vendor folder names like docs/superpowers/.
   • Use clean, tool-agnostic repository paths:
     • Design Specs: ./docs/specs/YYYY-MM-DD-<topic>-design.md
     • Implementation Plans: ./docs/plans/YYYY-MM-DD-<topic>.md
2. Sync Plan Deviations Back Before Merge:
   • Implementation always uncovers edge cases not anticipated in the initial plan. Before opening or merging a PR, update the spec/plan doc with a brief Deviations from Plan note so the committed document reflects reality, not an obsolete draft.

---

3. Two-Axis Code Review + Reviewer Probes

When reviewing a branch, PR, or deployed service:

Step 0: Confirm Scope & True-Up Against Deployed Reality

• Confirm the branch diff (git diff main...HEAD) and check that granular WIP commits have been squashed into logical categories.
• If reviewing a deployed service or brownfield integration: Do not trust local git alone. Check whether the live deployed artifact (Cloud Run revision, File Cabinet script, production config XML) has drifted from git.

Step 1: Walk the Two-Axis Review Sequence

Evaluate every change along Axis 1 (Engineering Standards) and Axis 2 (Spec Adherence) in this exact five-step order:

1. Contracts & Schemas: Do boundary inputs/outputs, store interfaces, and config schemas match captured reality (test/fixtures/) and the spec? Are dependencies injected via seams rather than hardcoded globals?
2. Core Logic: Is decision logic peeled out of hostile runtimes into pure transforms? Are mutations guarded by explicit dryRun and idempotent upsert?
3. Edge Cases & Failure Modes: Are errors classified (4xx fail-fast vs. 429/5xx bounded retry)? Are ERROR logs emitted at the failure site without leaking secrets or mutating live payloads? Does state survive across multiple instances?
4. Naming & Structure: Are files kebab-case, exports idiomatic (camelCase / PascalCase / UPPER_SNAKE_CASE), and directories grouped by domain?
5. Tests, Oracles & Invariants: Does every acceptance criterion trace to a Rank 1–5 Oracle? Is src/ free of internal module mocks? Does the afterEach invariant suite run across all boundary scenarios?

Step 2: Author Adversarial Reviewer Probes

• Write probes from the spec without trusting the implementation’s happy path: Unicode/long strings, pagination boundaries (100+ items), concurrent token refreshes, spoofed proxy headers (X-Forwarded-For), cold-start mid-flow, missing optional claims.
• Any probe that exposes a defect is promoted into a permanent scenario in the test suite.

---

4. Pentarch SDLC: Multi-Agent Persona & Model Tiering Architecture (master $\to$ worker $\to$ breaker + reviewer)

The Pentarch SDLC (derived from classical Greek πενταρχία, governance by five collegiate peers) replaces monolithic, autocratic prompt loops with five specialized agents governing code quality through mutual checks on power.

To maximize reasoning quality on architecture while preserving quota and speed during implementation, separate agent roles across two cognitive model tiers (with an on-demand Deep-Reasoning Escalation Tier):

Persona	Role Mandate	Antigravity (agy) Default	Claude Code (claude) Default	Budget-Permitting Escalation (-MaxBudget / -Deep)	Tool Boundary
master	Architect, Team Lead & Direct Orchestrator: Grills specs, runs Pugh matrices, writes docs/specs/ & docs/plans/, and directly spawns worker, breaker, reviewer.	model: pro (Gemini 4 Argon)	model: opus effort: xhigh	agy: --model gemini-4-argon-high --effort high claude: model: fable + effort: medium	Full write + shell + invoke_subagent + run_workflow (Soft Gate: plan-first before app code).
worker	Worktree TDD Builder: Executes approved spec phases inside .worktrees/<slug> with Dual-Boundary verification.	model: flash (Gemini 3.8 Flash)	model: sonnet effort: xhigh	agy: model: pro claude: model: opus + effort: high	Full write + shell; leaf executor (no subagent spawning).
reviewer	Defensive Pre-PR Gatekeeper: Runs test suite, inspects git diff, and audits the Test Oracle table + Skill Evals.	model: flash	model: sonnet effort: high	—	Hard Read-Only + Shell (view_file, run_command; no file writes).
breaker	Offensive Red-Team & Chaos Saboteur: Traces untrusted inputs to sinks (IDOR, injection, secret leaks, TOCTOU races).	model: pro	model: opus effort: xhigh	agy: gemini-4-argon-high claude: model: fable + effort: medium	Hard Read-Only + Shell (view_file, run_command; no file writes).
broker	Escalation Unblocker & Queue Deputy: Off the normal critical path; invoked only on stalled workers, >3 worktree sprawl, or background queue dispatch.	model: flash	model: sonnet effort: high	—	Full write + shell + spawns worker, reviewer.

Why This Split Works

1. Spec Precision Unlocks Fast Execution: When master (running on Argon / Opus / Fable) resolves every design ambiguity up front and writes exact file/line targets and scenario tables into docs/specs/, worker does not need frontier reasoning to type out the code and run pytest—Flash / Sonnet executes the 4-phase loop 3x faster at a fraction of the token budget.
2. Independent Adversarial Verification: Spawning breaker (Pro / Opus) and reviewer (Flash / Sonnet) in fresh context windows prevents the author (worker) from grading its own homework.

---

• Back to engineering
• All skills in yclian/skills