@zigrivers/scaffold 2.28.1 → 2.38.1

package/knowledge/core/automated-review-tooling.md

@@ -0,0 +1,203 @@
+---
+name: automated-review-tooling
+description: Patterns for setting up automated PR code review using AI models (Codex, Gemini) via local CLI, including dual-model review, reconciliation, and CI integration
+topics: [code-review, automation, codex, gemini, pull-requests, ci-cd, review-tooling]
+---
+
+# Automated Review Tooling
+
+Automated PR review leverages AI models to provide consistent, thorough code review without manual reviewer bottlenecks. This knowledge covers the local CLI approach (no GitHub Actions), dual-model review patterns, and integration with the PR workflow.
+
+## Summary
+
+### Architecture: Local CLI Review
+
+The scaffold approach uses local CLI review rather than GitHub Actions:
+- **No CI secrets required** — models run locally via CLI tools
+- **Dual-model review** — run Codex and Gemini (when available) for independent perspectives
+- **Agent-managed loop** — Claude orchestrates the review-fix cycle locally
+
+Components:
+- `AGENTS.md` — reviewer instructions with project-specific rules
+- `docs/review-standards.md` — severity definitions (P0-P3) and criteria
+- `scripts/cli-pr-review.sh` — dual-model review script
+- `scripts/await-pr-review.sh` — polling script for external bot mode
+
+### Review Severity Levels
+
+Consistent with the pipeline's review step severity:
+- **P0 (blocking)** — must fix before merge (security, data loss, broken functionality)
+- **P1 (important)** — should fix before merge (bugs, missing tests, performance)
+- **P2 (suggestion)** — consider fixing (style, naming, documentation)
+- **P3 (nit)** — optional (personal preference, minor optimization)
+
+### Dual-Model Review Pattern
+
+When both Codex CLI and Gemini CLI are available:
+1. Run both reviewers independently on the PR diff
+2. Collect findings from each
+3. Reconcile: consensus findings get higher confidence
+4. Disagreements are flagged for the implementing agent to resolve
+
+### Integration with PR Workflow
+
+The review step integrates into the standard PR flow:
+1. Agent creates PR
+2. Agent runs `scripts/cli-pr-review.sh` (or review runs automatically)
+3. Review findings are posted as PR comments or written to a local file
+4. Agent addresses P0/P1 findings, pushes fixes
+5. Re-review until no P0/P1 findings remain
+6. PR is ready for merge
+
+## Deep Guidance
+
+### AGENTS.md Structure
+
+The `AGENTS.md` file provides reviewer instructions:
+
+```markdown
+# Code Review Instructions
+
+## Project Context
+[Brief description of what this project does]
+
+## Review Focus Areas
+- Security: [project-specific security concerns]
+- Performance: [known hot paths or constraints]
+- Testing: [coverage requirements, test patterns]
+
+## Coding Standards Reference
+See docs/coding-standards.md for:
+- Naming conventions
+- Error handling patterns
+- Logging standards
+
+## Known Patterns
+[Project-specific patterns reviewers should enforce]
+
+## Out of Scope
+[Things reviewers should NOT flag]
+```
+
+### CLI Review Script Pattern
+
+The `cli-pr-review.sh` script follows this structure:
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+# 1. Get the PR diff
+diff=$(gh pr diff "$PR_NUMBER")
+
+# 2. Run Codex review (if available)
+if command -v codex &>/dev/null; then
+  codex_findings=$(echo "$diff" | codex review --context AGENTS.md)
+fi
+
+# 3. Run Gemini review (if available)
+if command -v gemini &>/dev/null; then
+  gemini_findings=$(echo "$diff" | gemini review --context AGENTS.md)
+fi
+
+# 4. Reconcile findings
+# - Findings from both models: HIGH confidence
+# - Findings from one model: MEDIUM confidence
+# - Contradictions: flagged for human review
+```
+
+### Review Standards Document
+
+`docs/review-standards.md` should define:
+- Severity levels with concrete examples per project
+- What constitutes a blocking review (P0/P1 threshold)
+- Auto-approve criteria (when review can be skipped)
+- Review SLA (how long before auto-approve kicks in)
+
+### Fallback When Models Unavailable
+
+If neither Codex nor Gemini CLI is available:
+1. Claude performs an enhanced self-review of the diff
+2. Focus on the AGENTS.md review criteria
+3. Apply the same severity classification
+4. Document that the review was single-model
+
+### Updating Review Standards Over Time
+
+As the project evolves:
+- Add new review focus areas when new patterns emerge
+- Remove rules that linters now enforce automatically
+- Update AGENTS.md when architecture changes
+- Track false-positive rates and adjust thresholds
+
+### Review Finding Reconciliation
+
+When running dual-model review, reconcile findings systematically:
+
+```
+Finding Classification:
+┌─────────────────┬──────────┬──────────┬───────────────────┐
+│                 │ Codex    │ Gemini   │ Action            │
+├─────────────────┼──────────┼──────────┼───────────────────┤
+│ Same issue      │ Found    │ Found    │ HIGH confidence   │
+│ Unique finding  │ Found    │ -        │ MEDIUM confidence │
+│ Unique finding  │ -        │ Found    │ MEDIUM confidence │
+│ Contradiction   │ Fix X    │ Keep X   │ Flag for agent    │
+└─────────────────┴──────────┴──────────┴───────────────────┘
+```
+
+HIGH confidence findings are always addressed. MEDIUM confidence findings are addressed if P0/P1. Contradictions require the implementing agent to make a judgment call and document the reasoning.
+
+### Security-Focused Review Checklist
+
+Every automated review should check:
+- No secrets or credentials in the diff (API keys, passwords, tokens)
+- No `eval()` or equivalent unsafe operations introduced
+- SQL queries use parameterized queries (no string concatenation)
+- User input is validated before use
+- Authentication/authorization checks are present on new endpoints
+- Dependencies added are from trusted sources with known versions
+
+### Performance Review Patterns
+
+Look for these performance anti-patterns:
+- N+1 queries (loop with individual DB calls)
+- Missing pagination on list endpoints
+- Synchronous operations that should be async
+- Large objects passed by value instead of reference
+- Missing caching for expensive computations
+- Unbounded growth in arrays or maps
+
+### Integration with CLAUDE.md
+
+The workflow-audit step should add review commands to CLAUDE.md:
+
+```markdown
+## Code Review
+| Command | Purpose |
+|---------|---------|
+| `scripts/cli-pr-review.sh <PR#>` | Run dual-model review |
+| `scripts/await-pr-review.sh <PR#>` | Poll for external review |
+```
+
+This ensures agents always know how to trigger reviews without consulting separate docs.
+
+### Common False Positives
+
+Track and suppress recurring false positives:
+- Test files flagged for "hardcoded values" (test fixtures are intentional)
+- Migration files flagged for "raw SQL" (migrations must use raw SQL)
+- Generated files flagged for style issues (generated code has its own conventions)
+
+Add suppressions to AGENTS.md under "Out of Scope" to prevent repeated false findings.
+
+### Review Metrics and Continuous Improvement
+
+Track these metrics over time to improve review quality:
+- **False positive rate** — findings that are dismissed without action
+- **Escape rate** — bugs that reach production despite review
+- **Time to resolve** — average time between finding and fix
+- **Coverage** — percentage of PRs that receive automated review
+- **Model agreement rate** — how often Codex and Gemini agree
+
+Use these metrics to calibrate severity thresholds and update AGENTS.md focus areas.

package/knowledge/core/coding-conventions.md

@@ -1,7 +1,7 @@
 ---
 name: coding-conventions
 description: Universal coding standards patterns across languages and linter/formatter configuration
-topics: [coding-standards, linting, formatting, naming-conventions, error-handling, code-style]
+topics: [coding-standards, linting, formatting, naming, error-handling, code-style]
 ---
 
 # Coding Conventions

package/knowledge/core/database-design.md

@@ -4,6 +4,8 @@ description: Database schema design, normalization, indexing, and migration patt
 topics: [database, schema, sql, nosql, migrations, indexing, data-modeling]
 ---
 
+## Summary
+
 ## From Domain Models to Schema
 
 The domain model defines what the business cares about. The database schema defines how that information is stored. The mapping between them is deliberate, not automatic.
@@ -77,6 +79,8 @@ metadata JSONB NOT NULL DEFAULT '{}'
 
 **Lookup table** — Store value objects with limited valid values in a reference table. Best for enums with associated data (status codes with descriptions, country codes with names).
 
+## Deep Guidance
+
 ### Modeling Relationships
 
 **One-to-one:** Use a foreign key in either table (typically the dependent side). Consider: could this be columns in the same table instead?

package/knowledge/core/design-system-tokens.md

@@ -4,6 +4,8 @@ description: Design token definitions, base component visual specs, dark mode pa
 topics: [design-system, tokens, colors, typography, spacing, components, dark-mode, pattern-library]
 ---
 
+## Summary
+
 ## Design Tokens
 
 Design tokens are the atomic values that define the visual language. They are variables, not hard-coded values. Every visual property in the application references a token.
@@ -66,6 +68,8 @@ Design tokens are the atomic values that define the visual language. They are va
 --color-focus-ring: rgba(37,99,235,0.5)  // Focus indicator
 ```
 
+## Deep Guidance
+
 ### Typography Tokens
 
 **Font families:**

package/knowledge/core/domain-modeling.md

@@ -4,6 +4,8 @@ description: Domain-driven design patterns for identifying and modeling project
 topics: [ddd, domain-modeling, entities, aggregates, bounded-contexts, domain-events, value-objects]
 ---
 
+## Summary
+
 ## Strategic DDD Patterns
 
 Strategic DDD operates at the system level, answering where domain boundaries fall and how domains communicate.
@@ -54,6 +56,8 @@ Not all parts of a system are equally important or complex. Classify domains by
 
 **Classification decisions matter because they drive resource allocation.** Over-investing in a generic domain (building a custom auth system when Auth0 exists) wastes effort. Under-investing in a core domain (using a generic CRUD framework for your competitive advantage) produces mediocre software.
 
+## Deep Guidance
+
 ## Tactical DDD Patterns
 
 Tactical DDD patterns structure the code within a bounded context.

package/knowledge/core/git-workflow-patterns.md

@@ -0,0 +1,200 @@
+---
+name: git-workflow-patterns
+description: Git branching strategies, commit conventions, PR workflows, merge policies, and CI integration patterns for AI-agent-driven development
+topics: [git, branching, commits, pull-requests, ci-cd, merge-strategy, worktrees]
+---
+
+# Git Workflow Patterns
+
+Structured git workflows for AI-agent-driven projects ensure consistent branching, meaningful commit history, automated quality gates, and smooth multi-agent collaboration via worktrees.
+
+## Summary
+
+### Branching Strategy
+
+The trunk-based development model works best for AI-agent workflows:
+
+- **Main branch** (`main`) — always deployable, protected by CI
+- **Feature branches** — short-lived, created per task or story (`feat/US-xxx-slug`, `fix/bug-description`)
+- **Worktree branches** — parallel agent execution using git worktrees (`agent/<name>/<task>`)
+
+Branch naming conventions:
+```
+feat/US-001-user-registration    # Feature work tied to a story
+fix/login-timeout-handling       # Bug fix
+chore/update-dependencies        # Maintenance
+docs/api-contract-updates        # Documentation only
+```
+
+### Commit Conventions
+
+Use Conventional Commits format for machine-parseable history:
+
+```
+<type>(<scope>): <description>
+
+[optional body]
+
+[optional footer(s)]
+```
+
+Types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`, `ci`
+
+AI agent commits should include the Co-Authored-By trailer for attribution and auditability.
+
+### Pull Request Workflow
+
+Standard PR lifecycle:
+1. Create branch from `main`
+2. Implement changes with passing tests
+3. Push branch, create PR with structured description
+4. CI runs all quality gates (`make check` or equivalent)
+5. Review (automated or manual)
+6. Squash-merge to maintain clean history
+7. Delete branch after merge
+
+## Deep Guidance
+
+### Merge Policies
+
+- **Squash merge** for feature branches — keeps main history clean
+- **Merge commit** for release branches — preserves the merge point
+- **Never force-push** to main or shared branches
+- **Delete branches** after merge to prevent clutter
+
+### CI Integration
+
+Minimum CI pipeline for scaffold projects:
+1. **Lint** — ShellCheck, ESLint, or language-appropriate linter
+2. **Test** — Full test suite including evals
+3. **Build** — Verify compilation/bundling succeeds
+4. **Type check** — For typed languages (TypeScript, etc.)
+
+### Worktree Patterns for Multi-Agent Work
+
+Git worktrees enable parallel agent execution on the same repository:
+
+```bash
+# Create a worktree for an agent
+scripts/setup-agent-worktree.sh agent-name
+
+# Each worktree gets its own branch and working directory
+# Agents can work simultaneously without conflicts
+```
+
+Key rules:
+- Each agent works in its own worktree with its own branch
+- Agents coordinate via the implementation plan task assignments
+- Merge conflicts are resolved by the agent whose branch is behind
+- The main worktree is the coordination point
+
+### Branch Protection Rules
+
+Configure branch protection for `main`:
+- Require status checks to pass before merge
+- Require branches to be up to date before merge
+- Do not allow direct pushes
+- Require squash merging for feature branches
+
+### Commit Message Quality
+
+Good commit messages for AI agents:
+```
+feat(auth): add JWT token refresh endpoint
+
+Implements automatic token refresh when the access token expires
+within 5 minutes. Refresh tokens are rotated on each use.
+
+Closes US-015
+```
+
+Bad commit messages to avoid:
+- `fix stuff` — no context
+- `WIP` — should never be pushed
+- `update` — what was updated?
+
+### PR Description Template
+
+```
+### What changed
+- [1-3 bullet points describing the change]
+
+### Files modified
+- [Specific files/components modified]
+
+### How to test
+- [How to verify the changes work]
+
+### Related
+- [Story ID, issue link, or ADR reference]
+```
+
+### Conflict Resolution Strategy
+
+When multiple agents work in parallel:
+1. Agent finishing first merges normally
+2. Agent finishing second rebases onto updated main
+3. If conflicts arise, the second agent resolves them
+4. Never force-push over another agent's work
+
+Conflict resolution checklist:
+- Pull latest main before starting any task
+- Rebase frequently on long-running branches (every few commits)
+- If a rebase produces conflicts in files you didn't modify, investigate — another agent may have refactored the same area
+- After resolving conflicts, re-run the full test suite before pushing
+- Document unusual conflict resolutions in the commit message body
+
+### Release Workflow
+
+For version-tagged releases:
+1. Ensure all PRs are merged to main
+2. Run full quality gates on main
+3. Create a version tag (`v1.2.3`)
+4. Generate changelog from conventional commits
+5. Push tag to trigger release pipeline
+
+### Semantic Versioning
+
+Follow semver for version tags:
+- **MAJOR** (`X.0.0`) — breaking API changes, incompatible migrations
+- **MINOR** (`0.X.0`) — new features, backward-compatible additions
+- **PATCH** (`0.0.X`) — bug fixes, documentation, internal refactors
+
+Pre-release versions for staging: `v1.2.3-rc.1`, `v1.2.3-beta.1`
+
+### Git Hooks
+
+Pre-commit hooks for quality enforcement:
+```bash
+# .husky/pre-commit or .git/hooks/pre-commit
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Run linter on staged files
+make lint
+
+# Validate frontmatter on changed command files
+./scripts/validate-frontmatter.sh $(git diff --cached --name-only -- 'commands/*.md')
+```
+
+Pre-push hooks for broader validation:
+```bash
+# .husky/pre-push or .git/hooks/pre-push
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Run full test suite before pushing
+make test
+```
+
+### Common Anti-Patterns
+
+Patterns to avoid in AI-agent git workflows:
+
+1. **Long-lived branches** — branches older than 1 day risk merge conflicts. Keep branches short-lived.
+2. **Giant PRs** — PRs with 500+ lines changed are hard to review. Split into smaller, focused PRs.
+3. **Skipping hooks** — `--no-verify` hides real issues. Fix the root cause instead.
+4. **Rebasing shared branches** — only rebase branches that only you use. Shared branches use merge commits.
+5. **Committing generated files** — lock files yes, build output no. Use `.gitignore` aggressively.
+6. **Force-pushing to main** — this is never acceptable. Even if CI is broken, create a fix branch.
+7. **Mixing concerns in one commit** — each commit should be atomic and focused on one change.

package/knowledge/core/operations-runbook.md

@@ -1,9 +1,11 @@
 ---
 name: operations-runbook
 description: Deployment pipeline, deployment strategies, monitoring, alerting, and incident response
-topics: [operations, cicd, deployment, monitoring, incident-response, alerting, rollback]
+topics: [operations, ci-cd, deployment, monitoring, incident-response, alerting, rollback]
 ---
 
+## Summary
+
 ## Dev Environment Reference
 
 Local development setup (prerequisites, env vars, one-command setup, database, hot reload, common commands, troubleshooting) is defined in `docs/dev-setup.md`, created by the Dev Setup prompt. The operations runbook should reference it rather than redefine it.
@@ -73,6 +75,8 @@ Operations adds (main branch only):
 - Tag artifacts with the git SHA for traceability
 - Set retention policies (keep last 30 days, keep releases forever)
 
+## Deep Guidance
+
 ## Deployment Strategies
 
 ### Blue-Green Deployment

package/knowledge/core/security-best-practices.md

@@ -4,6 +4,8 @@ description: OWASP Top 10, authentication, authorization, data protection, and t
 topics: [security, owasp, authentication, authorization, threat-modeling, secrets-management, dependency-auditing]
 ---
 
+## Summary
+
 ## OWASP Top 10
 
 The OWASP Top 10 represents the most critical security risks to web applications. Every project should evaluate each risk and implement appropriate mitigations.
@@ -55,6 +57,8 @@ Sensitive data exposed due to weak or missing encryption.
 - Hash passwords with bcrypt, scrypt, or Argon2 (NEVER MD5 or SHA-256 for passwords)
 - Don't store sensitive data you don't need — the safest data is data you don't have
 
+## Deep Guidance
+
 ### A03: Injection
 
 Untrusted data sent to an interpreter as part of a command or query, causing unintended execution.

package/knowledge/core/system-architecture.md

@@ -1,9 +1,11 @@
 ---
 name: system-architecture
 description: Architecture patterns, component design, and project structure
-topics: [architecture, components, modules, data-flows, project-structure, state-management]
+topics: [architecture, components, modules, data-flow, project-structure, state-management]
 ---
 
+## Summary
+
 ## Architecture Patterns
 
 ### Layered Architecture
@@ -81,6 +83,8 @@ For most scaffold pipeline projects:
 4. Use **microservices** only if you have multiple teams that need independent deployment, or specific services with dramatically different scaling needs.
 5. Avoid **layered** unless the application is genuinely simple (CRUD with minimal business logic).
 
+## Deep Guidance
+
 ## Component Design
 
 ### Identifying Components from Domain Models

package/knowledge/core/task-decomposition.md

@@ -16,7 +16,14 @@ User stories bridge PRD features and implementation tasks. Each story decomposes
 
 ### Task Sizing
 
-Each task should be completable in a single AI agent session (30-90 minutes of agent time). A well-sized task has a clear title (usable as commit message), touches 1-5 files, produces a testable result, and has no ambiguity about "done."
+Each task should be completable in a single AI agent session (30-90 minutes of agent time). A well-sized task has a clear title (usable as commit message), touches 1-3 application files (hard limit; justify exceptions), produces ~150 lines of net-new application code (excluding tests and generated files), and has no ambiguity about "done."
+
+Five rules govern agent-friendly task sizing:
+1. **Three-File Rule** — Max 3 application files modified (test files excluded)
+2. **150-Line Budget** — Max ~150 lines of net-new application code per task
+3. **Single-Concern Rule** — One task does one thing (no "and" connecting unrelated work)
+4. **Decision-Free Execution** — All design decisions resolved in the task description; agents implement, they don't architect
+5. **Test Co-location** — Tests live in the same task as the code they test; no deferred testing
 
 Split large tasks by layer (API, UI, DB, tests), by feature slice (happy path, validation, edge cases), or by entity. Combine tiny tasks that touch the same file and have no independent value.
 
@@ -157,8 +164,11 @@ Each task should be completable in a single AI agent session (typically 30-90 mi
 
 **A well-sized task:**
 - Has a clear, specific title that could be a commit message
-- Touches 1-5 files (not counting test files)
-- Produces a testable, verifiable result
+- Touches 1-3 application files (hard limit; test files excluded from count)
+- Produces ~150 lines of net-new application code (excluding tests and generated files)
+- Does exactly one thing (passes the single-concern test: describable without "and")
+- Requires no design decisions from the agent (all choices resolved in the description)
+- Includes co-located tests (the task isn't done until tests pass)
 - Has no ambiguity about what "done" means
 - Can be code-reviewed independently
 
@@ -376,6 +386,111 @@ Does NOT assume:
 - Any auth endpoints exist (this is the first)
 ```
 
+### Agent Executability Heuristics
+
+Five formalized rules for ensuring tasks are the right size for AI agent execution. These are hard rules with an escape hatch — tasks exceeding limits must be split unless the author provides explicit justification via `<!-- agent-size-exception: reason -->`.
+
+#### Rule 1: Three-File Rule
+
+A task modifies at most 3 application files (test files don't count toward this limit). If it would touch more, split by layer or concern.
+
+**Why 3:** Reading 3 files plus their context (imports, types, interfaces) consumes roughly 40-60% of a standard agent context window, leaving room for the task description, test code, and reasoning. At 5+ files, context pressure causes agents to lose track of cross-file consistency.
+
+**Splitting when exceeded:**
+- 4 files across 2 layers → split into one task per layer
+- 5 files in the same layer → split by entity or concern within the layer
+- Config files touched alongside application files → separate config task if non-trivial
+
+#### Rule 2: 150-Line Budget
+
+A task produces at most ~150 lines of net-new application code (excluding tests, generated files, and config). This keeps the entire change reviewable in one screen and within agent context budgets.
+
+**Why 150:** Agent output quality degrades measurably after ~200 lines of new code in a single session. At 150 lines, the agent can hold the entire change in context while writing tests and verifying correctness.
+
+**Estimating line count from task descriptions:**
+- A CRUD endpoint with validation: ~80-120 lines
+- A UI component with state management: ~100-150 lines
+- A database migration with seed data: ~50-80 lines
+- A full feature slice (API + UI + tests): ~300+ lines — MUST split
+
+#### Rule 3: Single-Concern Rule
+
+A task does exactly one thing. The test: can you describe what this task does in one sentence without "and"?
+
+**Passes the test:**
+- "Implement the user registration endpoint with input validation" (validation is part of the endpoint)
+- "Create the order model with database migration" (migration is part of model creation)
+
+**Fails the test:**
+- "Add the API endpoint AND update the dashboard" — two tasks
+- "Implement authentication AND set up the database" — two tasks
+- "Build the payment form AND integrate with Stripe AND add webhook handling" — three tasks
+
+**Splitting signals:**
+- Task description contains "and" connecting unrelated work
+- Task spans multiple architectural layers (API + frontend + database in one task)
+- Task affects multiple bounded contexts or feature domains
+- Task has acceptance criteria for two distinct user-facing behaviors
+
+#### Rule 4: Decision-Free Execution
+
+The task description must resolve all design decisions upfront. The agent implements, it doesn't architect. No task should require the agent to:
+
+- Choose between patterns (repository vs active record, REST vs GraphQL)
+- Select libraries or tools
+- Decide module structure or file organization
+- Determine API contract shapes (these come from upstream specs)
+
+**Red flags in task descriptions:**
+- "Choose the best approach for..."
+- "Determine whether to use X or Y"
+- "Decide how to structure..."
+- "Evaluate options for..."
+- "Select the most appropriate..."
+- "Figure out the best way to..."
+
+If a task contains any of these, the decision belongs in the task description — resolved by the plan author — not left to agent judgment. Local implementation choices (variable names, loop style, internal helper structure) are fine.
+
+#### Rule 5: Test Co-location
+
+Tests live in the same task as the code they test. The task follows TDD: write the failing test, then the implementation, then verify. The task isn't done until tests pass.
+
+**Anti-pattern:** "Tasks 1-8: implement features. Task 9: write tests for everything." This produces untestable code, violates TDD, and creates a single massive testing task that exceeds all size limits.
+
+**What co-location looks like:**
+```
+Task: Implement user registration endpoint
+  1. Write failing integration test (POST /register with valid data → 201)
+  2. Implement endpoint to make test pass
+  3. Write failing validation test (invalid email → 400)
+  4. Add validation to make test pass
+  5. Commit
+```
+
+#### Escape Hatch
+
+If a task genuinely can't be split further without creating tasks that have no independent value, add an explicit annotation in the task description: `<!-- agent-size-exception: [reason] -->`. The review pass flags unjustified exceptions but accepts reasoned ones.
+
+**Valid exception reasons:**
+- "Migration task touches 4 files but they're all trivial one-line renames"
+- "Config file changes across 4 files are mechanical and identical in structure"
+- "Test setup file is large but generated from a template"
+
+**Invalid exception reasons:**
+- "It's easier to do it all at once" (convenience is not a justification)
+- "The files are related" (related files can still be separate tasks)
+- "It would create too many tasks" (more small tasks > fewer large tasks)
+
+#### Concrete "Too Big" Examples
+
+| Task (Too Big) | Violations | Split Into |
+|---------------|-----------|------------|
+| "Implement user authentication" (8+ files, registration + login + reset + middleware) | Three-File, Single-Concern | 4 tasks: registration endpoint, login endpoint, password reset flow, auth middleware |
+| "Build the settings page with all preferences" (6 files, multiple forms + APIs) | Three-File, 150-Line, Single-Concern | Per-group: profile settings, notification settings, security settings |
+| "Set up database with all migrations and seed data" (10+ files, every entity) | Three-File, 150-Line | Per-entity: users table, orders table, products table, then seed data task |
+| "Create API client with retry, caching, and auth" (4 concerns in one module) | Single-Concern, Decision-Free | 3 tasks: base client with auth, retry middleware, cache layer |
+| "Implement the dashboard with charts, filters, and real-time updates" (5+ files, 300+ lines) | All five rules | 4 tasks: dashboard layout + routing, chart components, filter system, WebSocket integration |
+
 ### Common Pitfalls
 
 **Tasks too vague.** "Implement backend" or "Set up auth" with no acceptance criteria, no file paths, and no test requirements. An agent receiving this task will guess wrong about scope, structure, and conventions. Fix: every task must specify exact files to create/modify, acceptance criteria, and test requirements.