@vpxa/aikit 0.1.1

package/scaffold/general/skills/lesson-learned/references/se-principles.md

@@ -0,0 +1,109 @@
+---
+description: Curated catalog of software engineering principles. Load this before analyzing code changes so you can map observations to named principles.
+---
+
+# Software Engineering Principles
+
+Use this as a lookup table. When you spot a pattern in a diff, find the matching principle here. Each entry includes **code signals** -- what to look for in actual changes.
+
+## Design Principles (SOLID)
+
+**Single Responsibility Principle (SRP)**
+A module should have one reason to change.
+Code signals: A class/file was split into two. A function was extracted. A component stopped handling both UI and data fetching.
+
+**Open/Closed Principle (OCP)**
+Open for extension, closed for modification.
+Code signals: New behavior added without changing existing code. A plugin/hook/callback system introduced. Strategy pattern or configuration used instead of conditionals.
+
+**Liskov Substitution Principle (LSP)**
+Subtypes must be substitutable for their base types.
+Code signals: An interface was introduced to unify implementations. A subclass override changed behavior in a way that broke callers (violation). Type narrowing or guards added.
+
+**Interface Segregation Principle (ISP)**
+No client should depend on methods it doesn't use.
+Code signals: A large interface was split into smaller ones. Optional methods removed from an interface. A "fat" props object was broken into focused ones.
+
+**Dependency Inversion Principle (DIP)**
+Depend on abstractions, not concretions.
+Code signals: A concrete dependency replaced with an interface/injection. A factory or provider pattern introduced. Import paths changed from specific implementations to abstract layers.
+
+**Composition over Inheritance**
+Favor object composition over class inheritance.
+Code signals: Inheritance hierarchy replaced with delegation. Mixins or HOCs replaced with hooks or composition. A "base class" was removed.
+
+## Simplicity Principles
+
+**DRY (Don't Repeat Yourself)**
+Every piece of knowledge should have a single representation.
+Code signals: Duplicate code extracted into a shared function. A constant replaced repeated literals. A template/generator replaced copy-pasted boilerplate.
+
+**KISS (Keep It Simple, Stupid)**
+The simplest solution that works is the best.
+Code signals: A complex abstraction replaced with a straightforward implementation. Unnecessary indirection removed. A clever one-liner replaced with readable code.
+
+**YAGNI (You Aren't Gonna Need It)**
+Don't build it until you actually need it.
+Code signals: Speculative features removed. Unused configuration options deleted. An over-engineered solution simplified to match actual requirements.
+
+**Rule of Three**
+Wait until the third duplication before abstracting.
+Code signals: Similar code exists in 2 places and was left alone (good). A premature abstraction was introduced after only one use (violation). Third occurrence triggered extraction (textbook application).
+
+**Principle of Least Surprise**
+Code should behave the way most users would expect.
+Code signals: A function renamed to better describe what it does. Return types made consistent. Side effects made explicit or removed.
+
+## Structural Principles
+
+**Separation of Concerns**
+Different responsibilities should live in different modules.
+Code signals: Business logic extracted from UI components. Data access separated from domain logic. Configuration separated from behavior. A "god file" split into focused modules.
+
+**High Cohesion**
+Related functionality should live together.
+Code signals: Scattered related functions gathered into one module. A utility file broken up so each piece lives near its consumers. A feature folder created.
+
+**Loose Coupling**
+Modules should depend on each other as little as possible.
+Code signals: Direct imports replaced with events/callbacks. A shared dependency removed. Modules communicate through well-defined interfaces instead of reaching into internals.
+
+**Encapsulation**
+Hide internal details, expose only what's necessary.
+Code signals: Public methods reduced. Internal helpers made private. A module's API surface shrunk. Implementation details hidden behind a facade.
+
+**Information Hiding**
+Modules should not expose their internal data structures.
+Code signals: Raw data structures wrapped in accessor methods. Internal state made private. A data transformation moved inside the module that owns the data.
+
+## Pragmatic Principles
+
+**Boy Scout Rule**
+Leave the code better than you found it.
+Code signals: Small cleanups alongside a feature change. A renamed variable for clarity. A dead code path removed. An outdated comment updated.
+
+**Fail Fast**
+Detect and report errors as early as possible.
+Code signals: Input validation added at entry points. Assertions added for invariants. Early returns replacing deep nesting. Error handling moved closer to the source.
+
+**Defensive Programming**
+Anticipate and handle unexpected inputs gracefully.
+Code signals: Null checks added. Default values provided. Edge cases handled. Error boundaries introduced.
+
+**Premature Optimization (avoiding it)**
+Don't optimize until you've measured.
+Code signals: A simple implementation chosen over a "faster" complex one. Readability prioritized over micro-performance. A profiling step added before optimization work.
+
+## Refactoring Patterns
+
+**Extract Method/Function**
+Code signals: A long function split into named sub-functions. Inline logic replaced with a well-named call.
+
+**Extract Class/Module**
+Code signals: A file split into multiple files. A class split into two with distinct responsibilities.
+
+**Replace Conditional with Polymorphism**
+Code signals: A switch/if-else chain replaced with a strategy pattern or subclass dispatch. A type map introduced.
+
+**Introduce Parameter Object**
+Code signals: Multiple related parameters grouped into a single options/config object. Function signatures simplified.

package/scaffold/general/skills/multi-agents-development/SKILL.md

@@ -0,0 +1,435 @@
+# Multi-Agent Development
+
+Comprehensive patterns for orchestrating multiple AI agents in parallel development workflows. Covers task decomposition, parallel dispatch, context crafting, status handling, review pipelines, and recovery.
+
+**Core Principle**: Dispatch multiple agents for focused tasks. Each subagent gets fresh, focused context with explicit scope — never inherited session state.
+
+Load this skill when orchestrating multi-agent work: planning parallel batches, crafting delegation prompts, handling implementer status, running review pipelines, or recovering from agent failures.
+
+---
+
+## §1 Agent Roles & Model Selection
+
+### Role Categories
+
+| Role | Agents | When to Use | Parallelizable |
+|------|--------|-------------|----------------|
+| **Orchestration** | Orchestrator, Planner | Workflow control, planning | No (sequential) |
+| **Implementation** | Implementer, Frontend, Refactor | Code creation/modification | Yes (disjoint files only) |
+| **Research** | Explorer, Researcher-Alpha/Beta/Gamma/Delta | Codebase exploration, decisions | Yes (always) |
+| **Review** | Code-Reviewer-Alpha/Beta, Architect-Reviewer-Alpha/Beta | Quality verification | Yes (always) |
+| **Diagnostics** | Debugger, Security | Issue tracing, vulnerability analysis | Yes (read-only) |
+| **Documentation** | Documenter | README, API docs, changelog | Yes (disjoint files) |
+
+### Model Selection by Task Complexity
+
+Choose the **least powerful model that can handle the role**:
+
+| Complexity Signal | Model Tier | Example Agents |
+|-------------------|-----------|----------------|
+| Mechanical (rename, move, add field) | Fast model | Explorer (Gemini Flash) |
+| Standard (implement spec, write tests) | Mid-tier | Implementer (GPT-5.4), Refactor (GPT-5.4) |
+| Judgment-heavy (architecture, security, debug) | Strongest | Debugger (Opus 4.6), Security (Opus 4.6) |
+| Multi-model cross-validation | Mixed | Researcher-Alpha/Beta/Gamma/Delta (all different) |
+
+**Upgrade signal**: If an agent returns `BLOCKED` or `DONE_WITH_CONCERNS` on a task classified as "Standard", consider re-dispatching to a stronger model.
+
+---
+
+## §2 Task Decomposition Rules
+
+### The Golden Rule
+> **One task = one focused problem domain = 1-3 files maximum.**
+
+### Decomposition Checklist
+
+For each task, specify ALL of:
+- [ ] **Target files** — exact paths to create or modify
+- [ ] **Acceptance criteria** — what "done" looks like (testable)
+- [ ] **Agent assignment** — which agent handles this
+- [ ] **Dependencies** — which tasks must complete first (if any)
+
+### Sizing Guide
+
+| Task Size | Files | Example | Agent |
+|-----------|-------|---------|-------|
+| **Micro** | 1 file | Add a utility function | Implementer |
+| **Small** | 1-2 files | New endpoint + test | Implementer |
+| **Standard** | 2-3 files | Feature with service + controller + test | Implementer |
+| **Too big** | 4+ files | **SPLIT IT** — decompose further | — |
+
+### Splitting Strategies
+- **By layer**: Service logic (Implementer) + UI component (Frontend) + tests (Implementer)
+- **By feature boundary**: Auth endpoints (Implementer A) + Profile endpoints (Implementer B)
+- **By concern**: Data model changes (Implementer) + API route changes (Implementer) + UI updates (Frontend)
+
+---
+
+## §3 Independence Decision Tree
+
+Before marking tasks as parallel, walk this tree:
+
+```
+Task A and Task B — can they run in parallel?
+│
+├─ Do they share ANY files? (create, modify, or delete the same file)
+│   ├─ YES → SEQUENTIAL (or merge into one task)
+│   └─ NO ↓
+│
+├─ Do they share mutable state? (env vars, globals, same DB table, shared config)
+│   ├─ YES → SEQUENTIAL
+│   └─ NO ↓
+│
+├─ Does B need A's output? (B reads a file A creates, B uses A's new export)
+│   ├─ YES → SEQUENTIAL (A before B)
+│   └─ NO ↓
+│
+├─ Would A's result change B's approach? (A discovers something that affects B)
+│   ├─ YES → SEQUENTIAL or single agent
+│   └─ NO ↓
+│
+├─ Resource contention? (same port, same build process, same lock file)
+│   ├─ YES → SEQUENTIAL
+│   └─ NO ↓
+│
+└─ ✅ SAFE TO PARALLELIZE
+```
+
+### Edge Cases
+
+| Situation | Verdict | Why |
+|-----------|---------|-----|
+| Both import from same module (read-only) | ✅ Parallel | Reading shared code is fine |
+| Both add exports to same index file | ❌ Sequential | Concurrent index.ts edits will conflict |
+| A creates a type, B uses that type | ❌ Sequential | B depends on A's output |
+| Both modify different test files | ✅ Parallel | Disjoint file sets |
+| Both touch package.json | ❌ Sequential | Shared file |
+| A adds a route, B adds middleware | ⚠️ Check | If B's middleware affects A's route → sequential |
+
+### Integration Verification (after parallel batch completes)
+
+1. **Conflict check**: Did any agent unexpectedly modify a file assigned to another agent?
+2. **Import check**: Do all new cross-references resolve?
+3. **Full suite**: `check({})` + `test_run({})` — everything must pass
+4. **Spot check**: Manually verify at least one task's output matches acceptance criteria
+
+---
+
+## §4 Parallel Dispatch Patterns
+
+### Dispatch Rules
+
+1. **Max 4 concurrent file-modifying agents** per batch
+2. **Read-only agents have no limit** — Explorer, Researcher*, Reviewer*, Security can always run in parallel
+3. **Build dependency graph first** — phases with no dependencies MUST be batched together
+4. **Never dispatch two implementers to the same file** — even different sections
+
+### Batch Strategy
+
+```
+Phase Plan:
+  Phase 1: [Task A, Task B, Task C]  ← no dependencies between A/B/C
+  Phase 2: [Task D, Task E]          ← D depends on A, E depends on B
+  Phase 3: [Task F]                  ← F depends on D and E
+
+Execution:
+  Batch 1: dispatch(A, B, C) in parallel → review → gate
+  Batch 2: dispatch(D, E) in parallel → review → gate
+  Batch 3: dispatch(F) → review → gate
+```
+
+### Anti-Patterns
+
+| ❌ Don't | ✅ Do Instead |
+|----------|--------------|
+| Dispatch 6 implementers at once | Max 4, queue the rest |
+| Give one agent 10 files | Split into 3-4 focused tasks |
+| Let agents read the full plan | Give each agent ONLY its task context |
+| Retry same prompt on failure | Diagnose first, then re-prompt with fix |
+| Skip review after parallel batch | ALWAYS review + integration verify |
+| Inherit session context to subagent | Build fresh, focused context per dispatch |
+
+---
+
+## §5 Context Crafting Guide
+
+### The Controller Principle
+> **The Orchestrator provides ALL context. Subagents never need to search for context themselves.**
+
+Each subagent gets a fresh, self-contained prompt. No inherited session state. No "read the plan first."
+
+### The 6-Point Prompt Template
+
+Every delegation prompt MUST include:
+
+```markdown
+## 1. Scope
+Files to create/modify: [exact paths]
+Files to NOT touch: [boundaries]
+
+## 2. Goal
+[What the code should do — acceptance criteria, testable outcomes]
+
+## 3. Architectural Context
+[Relevant patterns, conventions, existing code structure]
+[Include actual code snippets from compact/digest — don't tell agent to "go read X"]
+
+## 4. Constraints
+- Follow [pattern/convention]
+- Do NOT modify [boundary files]
+- Use [specific library/approach]
+
+## 5. FORGE Context
+Tier: [Floor/Standard/Critical]
+Evidence requirements: [what evidence to collect]
+
+## 6. Self-Review & Status
+Before declaring DONE, verify:
+- [ ] All acceptance criteria met
+- [ ] No files outside scope modified
+- [ ] Tests pass (if applicable)
+- [ ] Code follows stated conventions
+
+End with status: DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED
+```
+
+### What to Include vs Omit
+
+| ✅ Include | ❌ Omit |
+|-----------|---------|
+| Exact file paths and code snippets | Full session history |
+| Acceptance criteria | Other agents' tasks |
+| Relevant conventions (from KB) | Unrelated architecture context |
+| Compact/digest of relevant files | Raw file contents of large files |
+| Error messages (if fixing a bug) | Previous failed attempts (unless relevant) |
+| FORGE tier and ceremony | Full FORGE protocol explanation |
+
+### Context Size Budget
+
+| Task Complexity | Context Target | Approach |
+|-----------------|---------------|----------|
+| Micro (1 file) | ~500 tokens | Inline code snippet + goal |
+| Small (1-2 files) | ~1000 tokens | `compact` of target files + goal |
+| Standard (2-3 files) | ~2000 tokens | `digest` of related files + architectural context |
+| Complex (judgment-heavy) | ~3000 tokens | `digest` + relevant decisions from KB |
+
+---
+
+## §6 Subagent Execution Cycle
+
+### Lifecycle
+
+```
+Orchestrator                          Subagent (fresh instance)
+    │                                      │
+    ├─ Craft focused prompt ──────────────►│
+    │  (6-point template)                  │
+    │                                      ├─ Understand scope
+    │                                      ├─ Implement changes
+    │                                      ├─ Self-review (checklist)
+    │◄─────────────────── Return status ───┤
+    │                                      │ (DONE/CONCERNS/NEEDS/BLOCKED)
+    │                                      │
+    ├─ Handle status (see §7)              ×  (subagent terminates)
+    │
+    ├─ Automated gate (check/test_run)
+    │
+    ├─ Dispatch reviewers (see §8)
+    │
+    └─ FORGE evidence_map gate
+```
+
+### Key Rules
+
+1. **One subagent = one task**. Never reuse a subagent for a different task.
+2. **Controller provides context**. The subagent's prompt contains everything it needs — it should NOT need to search/explore the codebase.
+3. **Self-review before handoff**. Every implementer must complete the self-review checklist before declaring DONE.
+4. **Status is mandatory**. Every subagent response MUST end with exactly ONE status code.
+
+---
+
+## §7 Implementer Status Protocol
+
+### Status Codes
+
+Every implementer (Implementer, Frontend, Refactor) MUST end their response with exactly ONE:
+
+| Status | Meaning | Orchestrator Action |
+|--------|---------|-------------------|
+| **DONE** | All tasks complete, self-review passed | → Automated gate → Review pipeline |
+| **DONE_WITH_CONCERNS** | Complete but flagging issues: [list] | → Surface concerns as `Assumed` claims in evidence_map → Likely HOLD → Address before review |
+| **NEEDS_CONTEXT** | Cannot proceed without: [specific question] | → Provide missing context → Re-dispatch same task (counts as retry) |
+| **BLOCKED** | Hit a wall: [description] | → Diagnose (see below) |
+
+### BLOCKED Diagnosis Tree
+
+```
+Agent returned BLOCKED
+│
+├─ Missing context? (needs info not in prompt)
+│   → Provide context, re-dispatch
+│
+├─ Wrong model? (task too complex for assigned model)
+│   → Re-dispatch to stronger model (e.g., Implementer → Debugger)
+│
+├─ Scope too broad? (agent overwhelmed)
+│   → Split task further, re-dispatch smaller pieces
+│
+├─ Plan wrong? (implementation approach won't work)
+│   → Re-plan this phase, check KB for alternatives
+│
+└─ External blocker? (dependency not ready, API unavailable)
+    → Park task, proceed with independent work, revisit later
+```
+
+### FORGE Composition
+
+Status protocol and FORGE are **independent but composable**:
+
+- **Status** = subjective agent telemetry ("I think I'm done")
+- **FORGE** = objective quality evidence ("the evidence says it's done")
+
+```
+DONE              → proceed to automated gate → FORGE evidence_map
+DONE_WITH_CONCERNS → concerns become 'Assumed' claims → evidence_map likely HOLDs
+NEEDS_CONTEXT     → provide context, re-dispatch (no FORGE yet)
+BLOCKED           → diagnose:
+                     contract/security issue → HARD_BLOCK
+                     resource/scope issue → re-plan, no FORGE
+```
+
+**Critical rule**: Every `DONE` status MUST be followed by `evidence_map({ action: "gate" })` before proceeding to review. No shortcuts.
+
+---
+
+## §8 Review Pipeline
+
+### Four-Stage Pipeline
+
+```
+Stage 1: Implementer Self-Review (embedded in agent output)
+  └─ Checklist: scope respected, tests pass, conventions followed
+      │
+Stage 2: Orchestrator Automated Gate
+  └─ check({}) + test_run({}) MUST pass
+  └─ Validate self-review checklist present in output
+  └─ FAIL → bounce back to implementer with specific gap
+  └─ PASS ↓
+      │
+Stage 3: Dual Code Review (parallel)
+  ├─ Code-Reviewer-Alpha (GPT-5.4): code quality + Spec Alignment
+  └─ Code-Reviewer-Beta (Opus 4.6): code quality + Spec Alignment
+      │ Both review same code, different model perspectives
+      │ Spec Alignment = "Does this match what was asked?"
+      │
+Stage 4: Conditional Reviews (parallel if both needed)
+  ├─ Architecture Review — if boundary changes, new modules, pattern shifts
+  └─ Security Review — if auth, crypto, input handling, or external data
+      │
+FORGE Gate: evidence_map({ action: "gate" })
+  └─ YIELD → proceed to commit
+  └─ HOLD → address flagged items → re-gate (max 3 rounds)
+  └─ HARD_BLOCK → escalate to user
+```
+
+### Spec Alignment Dimension (for Code Reviewers)
+
+Both Code-Reviewer-Alpha and Code-Reviewer-Beta evaluate an explicit **Spec Alignment** dimension:
+
+1. Does the implementation match the acceptance criteria from the task?
+2. Are there over-builds (features not requested)?
+3. Are there under-builds (requirements missed)?
+4. Does the output match the expected file changes?
+
+This catches spec drift that automated tests might miss.
+
+### When to Skip Stages
+
+| Stage | Skip When |
+|-------|-----------|
+| Architecture Review | No new modules, no boundary changes, no new patterns |
+| Security Review | No auth, no crypto, no external input handling |
+| FORGE Gate | Floor-tier tasks only (simple, mechanical changes) |
+
+---
+
+## §9 Recovery & Escalation
+
+### Retry Policy
+
+- **Max 2 retries per agent per task** — after that, re-plan or escalate
+- Each retry MUST include the specific failure reason in the new prompt
+- Never retry with the same prompt — always add diagnostic context
+
+### Loop Detection
+
+If an agent returns the same error/status 2+ times:
+1. **STOP** — do not retry again
+2. Check if the approach is fundamentally wrong
+3. Consider: different agent, different model, different decomposition, or user escalation
+
+### Emergency Procedures
+
+When parallel batch causes cascading failures:
+
+```
+STOP    → Halt all running agents immediately
+ASSESS  → git diff --stat + check({}) — how bad is it?
+CONTAIN → Limited (1-3 files): fix or re-delegate
+           Widespread (10+ files): git stash to preserve for analysis
+RECOVER → Partial: git checkout -- {specific files}
+           Full: git stash (preserves) or git checkout . (discards)
+           Nuclear: git reset --hard HEAD (last resort)
+DOCUMENT → remember what went wrong, update plan
+```
+
+### Scope Tripwires
+
+| Signal | Action |
+|--------|--------|
+| Agent modified **2x more files** than planned | Pause, review before continuing |
+| Agent returns `ESCALATE` or `BLOCKED` repeatedly | Do NOT re-delegate unchanged. Diagnose first |
+| Agent's output contradicts the plan | Stop, compare with plan, re-align |
+| Tests that were passing now fail | Immediate rollback of that agent's changes |
+
+---
+
+## §10 Common Mistakes & Red Flags
+
+### Delegation Anti-Patterns
+
+| ❌ Mistake | Why It Fails | ✅ Fix |
+|-----------|-------------|--------|
+| **Too broad scope** — "implement the auth system" | Agent lacks clear boundaries, produces sprawling changes | Split: "add JWT middleware to auth.ts" + "add login endpoint to routes.ts" |
+| **No constraints** — "add a feature" | Agent invents architecture, conflicts with existing patterns | Include conventions, boundaries, existing patterns in prompt |
+| **Vague output** — "make it work" | No way to verify completion | Specific acceptance criteria: "endpoint returns 200 with {schema}" |
+| **Session context inheritance** — "continue from where we left off" | Subagent has stale/polluted context | Fresh prompt with 6-point template every time |
+| **Skipping reviews** — "it's a small change" | Small changes cause big regressions | ALWAYS run automated gate minimum |
+| **Parallel on shared files** — "both agents edit config.ts" | Merge conflicts, lost changes | Sequential, or merge into one task |
+| **Trusting the report** — "agent said DONE so it's done" | Agents are optimistic, miss edge cases | Automated gate + dual code review catches this |
+| **Brute-force retries** — same prompt 3 times | If it failed twice, it'll fail a third time | Diagnose, change approach, then retry |
+| **Orchestrator implements** — "just this one small fix" | Breaks the delegation contract, no review | ALWAYS delegate, no matter how small |
+
+### Red Flags in Agent Output
+
+| Flag | What It Means | Action |
+|------|--------------|--------|
+| Agent modified files outside its scope | Scope creep or misunderstanding | Rollback out-of-scope files, re-delegate with tighter constraints |
+| Agent added dependencies not in plan | Unauthorized architectural decision | Review necessity, likely rollback |
+| Agent skipped self-review checklist | Rushing, likely incomplete | Bounce back with checklist requirement |
+| Agent's DONE but tests fail | Didn't actually self-test | Bounce back with failing test output |
+| Agent asks questions in output instead of using NEEDS_CONTEXT | Misunderstands status protocol | Treat as NEEDS_CONTEXT, educate in next prompt |
+
+---
+
+## Prompt Template Reference
+
+Detailed prompt templates are provided as sidecar files:
+
+| Template | File | Use When |
+|----------|------|----------|
+| Implementer dispatch | [`implementer-prompt.md`](implementer-prompt.md) | Dispatching Implementer, Frontend, or Refactor agents |
+| Spec compliance review | [`spec-review-prompt.md`](spec-review-prompt.md) | Adversarial spec alignment check (Code-Reviewer-Alpha) |
+| Code quality review | [`code-quality-review-prompt.md`](code-quality-review-prompt.md) | Dual code quality review (Code-Reviewer-Beta) |
+| Architecture review | [`architecture-review-prompt.md`](architecture-review-prompt.md) | Boundary changes, pattern adherence review |
+| Parallel dispatch example | [`parallel-dispatch-example.md`](parallel-dispatch-example.md) | Worked example of decomposing a feature into parallel tasks |

package/scaffold/general/skills/multi-agents-development/architecture-review-prompt.md

@@ -0,0 +1,81 @@
+# Architecture Review Prompt Template
+
+Use this template when dispatching **Architect-Reviewer-Alpha** and **Architect-Reviewer-Beta** for architecture review. Only needed when changes cross module boundaries, introduce new patterns, or modify shared infrastructure.
+
+---
+
+## Prompt Template
+
+```markdown
+You are performing an architecture review. Focus on structural decisions, not code quality (that's handled separately).
+
+## Change Summary
+[What was changed and why — high-level description]
+
+## Files Changed
+[List of files with module/boundary information]
+
+## Architectural Context
+[Paste relevant architecture docs, module graph, dependency structure from compact/digest]
+
+---
+
+## Review Dimensions
+
+### 1. Boundary Integrity
+- Do changes respect existing module boundaries?
+- Are there new cross-module dependencies that shouldn't exist?
+- Is the dependency direction correct (inner → outer, not reverse)?
+
+### 2. Pattern Adherence
+- Do new components follow established architectural patterns?
+- Are there deviations from the documented architecture?
+- If a new pattern is introduced, is it justified and documented?
+
+### 3. Coupling & Cohesion
+- Are new dependencies minimal and well-justified?
+- Could any coupling be reduced with interfaces or inversion?
+- Are related concerns grouped together?
+
+### 4. Scalability Impact
+- Will this change create bottlenecks under load?
+- Are there single points of failure introduced?
+- Does this work with horizontal scaling?
+
+### 5. Migration & Evolution
+- Does this change make future changes harder?
+- Are there implicit assumptions that will break?
+- Is the change reversible if needed?
+
+### 6. API Surface
+- Are new public APIs minimal and well-designed?
+- Could any public surface be internal instead?
+- Are breaking changes flagged?
+
+---
+
+## Output Format
+
+### Verdict: [APPROVE | APPROVE_WITH_NOTES | REQUEST_CHANGES]
+
+**APPROVE** — Architecture is sound.
+**APPROVE_WITH_NOTES** — Acceptable, but track these concerns.
+**REQUEST_CHANGES** — Structural issues that must be resolved.
+
+### Findings:
+| # | Dimension | Severity | Description | Impact |
+|---|-----------|----------|-------------|--------|
+| 1 | [Dimension] | [Blocker/Concern/Note] | [Issue] | [What breaks/degrades] |
+
+### Recommendation:
+[Structural guidance for improvement]
+```
+
+---
+
+## Usage Notes
+
+- **Only trigger architecture review when**: changes cross module boundaries, new patterns are introduced, shared infrastructure is modified, or public API surface changes
+- Both Alpha and Beta reviewers run in parallel for multi-model perspective
+- Architecture blockers are HIGH priority — must resolve before merge
+- If both reviewers flag the same concern, it's almost certainly a real issue