@event4u/agent-config 1.9.1

package/.agent-src/contexts/documentation-hierarchy.md

@@ -0,0 +1,142 @@
+# Context: Documentation Hierarchy
+
+> The 8-layer documentation system — what lives where, reading order, and how layers interact.
+
+**Type:** Infrastructure
+**Created:** 2026-03-20
+**Last Updated:** 2026-03-25
+
+## Overview
+
+Documentation is organized in 8 layers, from shared/cross-project to module-specific.
+Each layer has a clear purpose and scope. Agents read them in order, with earlier layers
+providing the foundation for later ones.
+
+## The 8 Layers
+
+```
+Layer 1: .augment/                    ← Shared package (read-only)
+Layer 2: AGENTS.md                    ← Project entry point
+Layer 3: .github/copilot-instructions ← Coding standards
+Layer 4: agents/overrides/            ← Project customizations of Layer 1
+Layer 5: agents/                      ← Project-specific docs
+Layer 6: app/Modules/*/agents/        ← Module-specific docs
+Layer 7: Docs/                        ← Technical docs for humans
+Layer 8: {package}/agents/            ← Package-specific docs
+```
+
+### Layer 1: `.augment/` — Shared Package
+
+**Scope:** All projects
+**Delivered as:** Composer package (read-only at project level)
+**Contains:** Rules, skills, commands, guidelines, templates, contexts
+
+This is the agent's "operating system" — universal behavior that applies everywhere.
+**Never modify for project-specific needs** → use Layer 4 (overrides) instead.
+
+### Layer 2: `AGENTS.md` — Project Entry Point
+
+**Scope:** Single project
+**Location:** Project root
+**Contains:** Tech stack, setup, testing, quality tools, module overview
+
+First file an agent reads. Provides the full project context.
+Not every project has this — packages may only have `./agents/`.
+
+### Layer 3: `.github/copilot-instructions.md` — Coding Standards
+
+**Scope:** Single project
+**Location:** `.github/`
+**Contains:** Architecture rules, PHP standards, naming conventions
+
+Shared with GitHub Copilot and other AI tools. Complements `AGENTS.md`.
+
+### Layer 4: `agents/overrides/` — Project Customizations
+
+**Scope:** Single project
+**Location:** `agents/overrides/{rules,skills,commands,guidelines,templates}/`
+**Contains:** Override files that extend or replace Layer 1 resources
+
+The bridge between shared behavior (Layer 1) and project needs.
+See `.augment/contexts/override-system.md` for naming conventions and format.
+
+### Layer 5: `agents/` — Project-Specific Documentation
+
+**Scope:** Single project
+**Location:** `agents/`
+**Contains:** Architecture docs, features, roadmaps, contexts, overrides
+
+Project-specific knowledge that doesn't belong in the shared package.
+Structural docs live directly in `agents/`, organized content in subdirectories.
+
+### Layer 6: `app/Modules/*/agents/` — Module Documentation
+
+**Scope:** Single module
+**Location:** `app/Modules/{Module}/agents/`
+**Contains:** Module description, module-scoped features, roadmaps, contexts
+
+Created when a module has its own conventions or active development.
+Roadmaps are stored in `agents/roadmaps/`.
+
+### Layer 7: `Docs/` — Technical Documentation
+
+**Scope:** Project or module
+**Location:** `Docs/` or `app/Modules/*/Docs/`
+**Contains:** Setup guides, architecture diagrams, API docs
+
+For human readers. `agents/` is optimized for AI agents, `Docs/` for humans.
+
+### Layer 8: Package Documentation
+
+**Scope:** Single Composer package
+**Location:** `{package-root}/agents/`
+**Contains:** Package description, roadmaps
+
+Same structure as projects, but for library packages.
+
+## Reading Order
+
+When starting work, agents read in this order:
+
+| Step | Source | Purpose |
+|---|---|---|
+| 1 | `AGENTS.md` | Project overview |
+| 2 | `.github/copilot-instructions.md` | Coding standards |
+| 3 | `agents/roadmaps/` | Active roadmap context |
+| 4 | `agents/overrides/` | Project customizations |
+| 5 | `agents/` | Project-specific docs for the task |
+| 6 | `app/Modules/{Module}/agents/` | Module docs (if working on a module) |
+| 7 | `agents/features/` | Related feature plans |
+| 8 | `agents/roadmaps/` | Active roadmaps |
+
+## Layer Interactions
+
+### Override Resolution (Layer 1 + Layer 4)
+
+```
+.augment/skills/eloquent/SKILL.md          ← Original (Layer 1)
+agents/overrides/skills/eloquent.md        ← Override (Layer 4)
+                                            → Merged result used by agent
+```
+
+### Context Scoping (Layer 1 vs Layer 5 vs Layer 6)
+
+| Context location | Scope | Example |
+|---|---|---|
+| `.augment/contexts/` | Shared (about the agent system) | `augment-infrastructure.md` |
+| `agents/contexts/` | Project-wide | `import-pipeline.md` |
+| `app/Modules/*/agents/contexts/` | Module-specific | `client-api.md` |
+
+### Template Usage (Layer 1 → Layer 5/6)
+
+Templates in `.augment/templates/` define the structure.
+Documents created from templates live in `agents/` or module `agents/`.
+Overrides in `agents/overrides/` customize shared behavior per project.
+
+## Related
+
+- **Context:** `augment-infrastructure.md` — `.augment/` directory details
+- **Context:** `override-system.md` — override naming and format
+- **Context:** `skills-and-commands.md` — skill/command inventory
+- **Skill:** `agent-docs-writing` — canonical reading order and creation rules
+

package/.agent-src/contexts/model-recommendations.md

@@ -0,0 +1,142 @@
+# Model Recommendations
+
+Loaded by the `model-recommendation` rule when the agent detects a task type mismatch.
+
+## Model Profiles (as of 2026-04)
+
+| Model | Alias | Strengths |
+|---|---|---|
+| Claude Opus | `opus` | Refactoring, architecture decisions, complex debugging, code review, multi-file changes, design patterns |
+| Claude Sonnet | `sonnet` | Daily coding, bug fixes, tests, simple features, quality checks, quick tasks |
+| GPT | `gpt` | Large-scale analysis, multi-step workflows, automation, research, planning |
+
+## Task → Model Mapping
+
+| Task Type | Recommended | Why |
+|---|---|---|
+| **Architecture / Refactoring** | `opus` | Deep structural reasoning, pattern recognition |
+| **Code review** | `opus` | Catches subtle issues, understands intent |
+| **Complex debugging** (unknown root cause, cross-layer) | `opus` | Follows chains across files and systems |
+| **Design decisions** | `opus` | Weighs trade-offs, considers long-term |
+| **Multi-file feature** (cross-domain / architecture relevant) | `opus` | Maintains coherence across layers |
+| **Debugging** (known issue, reproducible) | `sonnet` | Fast, efficient fixes |
+| **Write tests** | `sonnet` | Pattern-based, no deep reasoning required |
+| **Single-layer feature** (CRUD, same layer) | `sonnet` | Straightforward implementation |
+| **Quality checks** (PHPStan, ECS, Rector) | `sonnet` | Mechanical fixes, fast iteration |
+| **Config changes** | `sonnet` | Simple edits |
+| **Documentation** | `sonnet` | Clear writing, fast output |
+| **Implementation after Opus planning** | `sonnet` | Plan is done, execution is mechanical |
+| **Large codebase analysis** | `gpt` | Handles long context efficiently |
+| **Pattern search across files** | `gpt` | Efficient scanning and summarization |
+| **Agent workflows / automation** | `gpt` | Multi-step orchestration |
+| **Research / analysis** | `gpt` | Structured thinking, long context |
+| **Roadmap creation** | `gpt` | Planning and structured output |
+
+## Detection Heuristics
+
+| Signal | Task Type |
+|---|---|
+| "refactor", "restructure", "extract", "move to module" | Architecture / Refactoring |
+| PR review request | Code review |
+| "bug" with unclear cause or spanning multiple layers | Complex debugging |
+| "bug" with clear error and reproducible case | Debugging (known issue) |
+| "should I", "which approach", "what pattern" | Design decision |
+| Feature touching multiple domains/layers | Multi-file feature |
+| Feature within same layer (e.g. controller/service CRUD) | Single-layer feature |
+| "PHPStan", "ECS", "Rector" | Quality checks |
+| "config", "env", "docker", "CI" | Config changes |
+| "README", "docs", comments | Documentation |
+| "analyze project", "scan codebase" | Large codebase analysis |
+| /feature-plan, /roadmap-create, /project-analyze | Research / planning |
+| "automate", "workflow", "agent flow" | Agent workflows / automation |
+| Opus just finished architecture/refactoring/debugging | Implementation after Opus planning |
+
+## Senior Developer Mindset — for ALL models
+
+These instructions apply regardless of the model. They help Sonnet and GPT
+produce opus-level quality by enforcing habits that weaker models skip by default.
+
+### Before writing code
+
+- **Think before you type.** Read the surrounding code, understand the context, check conventions.
+  Do NOT start coding from the first line of the user's message.
+- **Check for existing patterns.** Search the codebase for how similar things are done.
+  Follow the existing pattern — do NOT invent a new one.
+- **Question assumptions.** If the user asks "add a method to X", verify that X is the right place.
+  A senior suggests a better location if appropriate.
+
+### While writing code
+
+- **Consider downstream impact.** Every change affects callers, tests, types, and imports.
+  Check them BEFORE presenting the result — not as an afterthought.
+- **Name things like a senior.** Variables, methods, classes — naming reveals understanding.
+  If you can't name it well, you don't understand it well enough yet.
+- **Handle edge cases.** Null checks, empty arrays, missing config — think about what can go wrong.
+  Don't write only the happy path.
+
+### After writing code
+
+- **Self-review.** Before presenting code to the user, re-read it as if reviewing someone else's PR.
+  Would you approve it? If not, fix it first.
+- **Verify, don't assume.** Run the test, check the output, read the error. "Should work" is not proof.
+
+### When stuck
+
+- **Stop after 2 failed attempts.** Don't loop — rethink the approach or ask the user.
+- **Admit uncertainty.** "I'm not sure about X" is better than a confident wrong answer.
+- **Ask one good question** instead of guessing three times.
+
+## Cost Optimization
+
+- **Default to `sonnet`** — it's the cost-efficient workhorse.
+- **Escalate to `opus`** only when architecture, refactoring, or unclear debugging is involved.
+- **After Opus work** (architecture plan, refactoring design, root cause found):
+  → Recommend switching back to `sonnet` for implementation.
+- **Use `gpt`** for large-scale analysis, searching across many files, or automation.
+
+## Recommendation Flow
+
+### When to check
+
+- **At conversation start**: detect model from system prompt identity
+- **When task type clearly changes**: user switches from one category to another
+- **NOT on every message** — only on clear task boundaries
+
+### When to recommend
+
+Only if ALL conditions are true:
+1. The detected task type maps to a DIFFERENT model than the detected model
+2. The mismatch is significant (e.g., sonnet doing architecture, not sonnet doing a slightly complex bug fix)
+3. You haven't already recommended for this task in this conversation
+
+### Switch confirmation flow
+
+When user says they switched:
+- Accept and continue. No follow-up question — trust the user.
+
+When user says they want to continue with the current model:
+- Accept immediately — no pushback.
+- Don't ask again until the task type changes significantly.
+
+### Downgrade reminder
+
+After completing an opus-level task (architecture plan done, refactoring complete, root cause found),
+remind the user to switch back to sonnet for the implementation phase:
+
+```
+> 💡 The {architecture/debugging/design} phase is done.
+> For implementation, **sonnet** is more cost-efficient.
+>
+> 1. I've switched to sonnet — continue
+> 2. Stay on opus
+```
+
+### Gemini warning
+
+If detected model is `gemini`: Gemini is **not recommended** for this project.
+The codebase relies heavily on structured agent rules, skills, and conventions
+that Gemini handles poorly compared to Claude/GPT models.
+
+- Suggest switching to the best model for the current task (opus/sonnet/gpt).
+- Show the same numbered options as for a regular mismatch.
+- If dismissed, repeat the warning **once more** — then accept the user's choice.

package/.agent-src/contexts/override-system.md

@@ -0,0 +1,187 @@
+# Context: Override System
+
+> How project-level overrides customize shared `.augment/` behavior without modifying the package.
+
+**Type:** Infrastructure
+**Created:** 2026-03-20
+**Last Updated:** 2026-03-20
+
+## Overview
+
+The override system allows each project to customize the shared `.augment/` package behavior.
+Overrides live in `agents/overrides/` (project-specific, version-controlled) and layer on top of
+the originals in `.augment/` (shared package, read-only).
+
+## Resolution Order
+
+When an agent loads any skill, rule, command, guideline, or template:
+
+```
+1. Load original from .augment/{type}/{name}
+2. Check agents/overrides/{type}/{name} exists?
+   ├── YES → Read Mode header
+   │   ├── extend  → Apply original FIRST, then layer override on top
+   │   └── replace → Skip original entirely, use override only
+   └── NO  → Use original unchanged
+```
+
+## Directory Mapping
+
+```
+.augment/                          →  agents/overrides/
+├── rules/php-coding.md            →  rules/php-coding.md
+├── skills/eloquent/SKILL.md       →  skills/eloquent.md          (flattened)
+├── commands/feature-plan.md       →  commands/feature-plan.md
+├── guidelines/php/controllers.md  →  guidelines/php-controllers.md (flattened with prefix)
+└── templates/roadmaps.md          →  templates/roadmaps.md
+```
+
+### Flattening Rules
+
+| Original structure | Override file | Rule |
+|---|---|---|
+| `rules/{name}.md` | `rules/{name}.md` | Same filename |
+| `skills/{name}/SKILL.md` | `skills/{name}.md` | Directory → single file |
+| `commands/{name}.md` | `commands/{name}.md` | Same filename |
+| `guidelines/{lang}/{file}.md` | `guidelines/{lang}-{file}.md` | Path segments joined with `-` |
+| `templates/{name}.md` | `templates/{name}.md` | Same filename |
+
+## Override File Format
+
+Every override file **must** have this header:
+
+```markdown
+# Override: {Type} — {name}
+
+> Override for `.augment/{path-to-original}`
+
+---
+**Mode:** `extend`
+**Original:** `.augment/{path-to-original}`
+---
+```
+
+## Mode: extend
+
+The original is loaded first. The override adds, modifies, or removes specific parts.
+
+**Use when:**
+- Adding project-specific rules to a shared skill
+- Injecting extra steps into a command
+- Adding project-specific examples to a guideline
+- Adding fields to a template
+
+**Best practice:** Only write what changes. Reference original sections by heading name.
+
+**Example:** A project needs stricter Eloquent rules:
+
+```markdown
+# Override: Skill — eloquent
+
+> Override for `.augment/skills/eloquent/SKILL.md`
+
+---
+**Mode:** `extend`
+**Original:** `.augment/skills/eloquent/SKILL.md`
+---
+
+## Additional Rules
+
+- Always use `$connection` property in models (multi-tenant requirement)
+- Never use `DB::table()` — always use Eloquent models
+```
+
+## Mode: replace
+
+The original is completely ignored. The override is the sole source of truth.
+
+**Use when:**
+- The shared skill/rule fundamentally doesn't fit the project
+- The project needs a completely different workflow for a command
+
+**Best practice:** Must be self-contained and complete. No references to the original.
+
+## Agent Behavior
+
+Agents **must** check for overrides before applying any shared resource:
+
+1. Before executing a skill → check `agents/overrides/skills/{name}.md`
+2. Before applying a rule → check `agents/overrides/rules/{name}.md`
+3. Before running a command → check `agents/overrides/commands/{name}.md`
+4. Before reading a guideline → check `agents/overrides/guidelines/{lang}-{name}.md`
+5. Before using a template → check `agents/overrides/templates/{name}.md`
+
+## When to Create vs. When to Fix
+
+| Situation | Action |
+|---|---|
+| Project needs different behavior | Create override (`agents/overrides/`) |
+| Shared resource has a bug | Fix the original (in the `.augment/` package repo) |
+| Temporary experiment | Use branch-specific notes, not overrides |
+| New capability not in any shared resource | Create new skill/command in `.augment/` |
+| Project wants to improve a shared rule/skill | Override locally + PR upstream (see below) |
+
+## Improving Shared Rules/Skills from a Project
+
+When a project using this package wants to **optimize** a shared rule or skill:
+
+### Dual-write workflow
+
+1. **Apply locally as override** — create `agents/overrides/{type}/{name}.md` with mode `replace`
+   containing the full improved version. This gives the project the benefit immediately.
+
+2. **Create PR against upstream** — submit the improvement to the shared `agent-config` package repository.
+   The PR must contain:
+   - **Uncompressed version** in `.agent-src.uncompressed/{type}/{name}`
+   - **Compressed version** in `.augment/{type}/{name}`
+   - Both files must be the complete, updated file (not a diff or partial)
+
+3. **After PR is merged upstream** — remove the local override from `agents/overrides/`.
+   The next package update delivers the improvement to all projects.
+
+### Why both?
+
+- The **override** gives the project immediate benefit without waiting for upstream merge
+- The **PR** ensures the improvement flows back to all projects using the package
+- After merge, the override becomes redundant and must be removed to avoid drift
+
+### Rules for upstream PRs
+
+- The PR must contain **both** uncompressed and compressed versions (complete files)
+- The compressed version must be derived from the uncompressed version
+- Changes must pass the skill linter (`task lint-skills`)
+- Changes must not be project-specific (no domain assumptions)
+- Changes must pass the promotion gate (see `controlled-self-optimization.md`)
+
+### Anti-patterns
+
+- Keeping the override after upstream merge → causes drift
+- Submitting only the compressed version → breaks source-of-truth workflow
+- Submitting project-specific behavior as universal improvement
+- Forgetting to create the PR → improvement stays siloed
+
+## Commands
+
+| Command | Purpose |
+|---|---|
+| `/override-create` | Guided creation — picks type, lists originals, asks mode, creates file |
+| `/override-manage` | Inventory, review, edit, delete, sync, upgrade existing overrides |
+
+## Templates
+
+Override templates in `.augment/templates/overrides/`:
+
+| Template | For |
+|---|---|
+| `rule.md` | Rule overrides |
+| `skill.md` | Skill overrides |
+| `command.md` | Command overrides |
+| `guideline.md` | Guideline overrides |
+| `template.md` | Template overrides |
+
+## Related
+
+- **Skill:** `override-management` — full override system documentation
+- **Context:** `augment-infrastructure.md` — overall `.augment/` structure
+- **Context:** `documentation-hierarchy.md` — where overrides fit in the layer model
+

package/.agent-src/contexts/skills-and-commands.md

@@ -0,0 +1,154 @@
+# Context: Skills and Commands
+
+> How skills and commands relate to each other, when to use which, and how they form workflows.
+
+**Type:** Infrastructure
+**Created:** 2026-03-20
+**Last Updated:** 2026-03-25
+
+## Overview
+
+**Skills** define *how* an agent behaves in a domain (knowledge + rules).
+**Commands** define *what* an agent does step-by-step (interactive workflows).
+Commands reference skills to know which expertise to apply during execution.
+
+## Relationship Model
+
+```
+Command (workflow)
+  ├── uses Skill A (expertise)
+  ├── uses Skill B (expertise)
+  ├── reads Rule X (constraint)
+  ├── reads Guideline Y (convention)
+  └── creates file from Template Z (structure)
+```
+
+## Workflow Chains
+
+Commands often chain together. Here are the main workflows:
+
+### Feature Development
+
+```
+/feature-explore → /feature-plan → /feature-roadmap → /roadmap-execute
+     ↓                  ↓                ↓                    ↓
+  Brainstorm        Structure         Phases/Steps        Implement
+```
+
+**Skills used:** `feature-planning`, `agent-docs-writing`, `roadmap-management`
+
+### Bug Investigation & Fix
+
+```
+/bug-investigate → /bug-fix
+       ↓               ↓
+  Root cause        Implement + verify
+```
+
+**Skills used:** `bug-analyzer`, `php-coder`, `code-refactoring`, `pest-testing`
+
+### Module Work
+
+```
+/module-explore → /context-create → /feature-plan (if needed)
+       ↓                ↓
+  Understand        Document
+```
+
+**Skills used:** `module-management`, `context-create`, `feature-planning`
+
+### Quality & PR
+
+```
+/quality-fix → /review-changes → /create-pr → /fix-pr-comments
+      ↓              ↓                ↓              ↓
+  PHPStan/Rector  Self-review     Open PR       Address feedback
+```
+
+**Skills used:** `code-refactoring`, `code-review`, `git-workflow`
+
+### Agent Infrastructure
+
+```
+/agents-prepare → /agents-audit → /agents-cleanup
+       ↓                ↓                ↓
+  Scaffold dirs    Find issues      Fix issues
+```
+
+```
+```
+
+**Skills used:** `agents-audit`, `agent-docs-writing`
+
+## Skill Categories
+
+### Always Relevant (loaded for most tasks)
+
+| Skill | Why |
+|---|---|
+| `php-coder` | Core PHP coding behavior |
+| `laravel` | Framework conventions |
+| `agent-docs-writing` | Documentation awareness |
+
+### Domain-Specific (loaded when working in that area)
+
+| Area | Skills |
+|---|---|
+| API endpoints | `api-endpoint`, `api-design`, `api-versioning`, `api-testing`, `openapi`, `laravel-validation` |
+| Database | `eloquent`, `database`, `migration-creator`, `multi-tenancy`, `sql-writing` |
+| Background jobs | `jobs-events`, `laravel-horizon`, `laravel-scheduling`, `performance` |
+| Email/Notifications | `laravel-mail`, `laravel-notifications` |
+| Middleware/Auth | `laravel-middleware`, `security` |
+| Feature flags | `laravel-pennant` |
+| Monitoring | `laravel-pulse`, `logging-monitoring`, `grafana`, `sentry-integration` |
+| Real-time | `laravel-reverb`, `websocket` |
+| Testing | `pest-testing`, `test-generator`, `playwright-testing` |
+| Frontend | `livewire`, `flux`, `blade-ui`, `tailwind`, `vue`, `react`, `fe-design` |
+| Infrastructure | `docker`, `aws-infrastructure`, `terraform`, `terragrunt`, `cloudflare-workers`, `traefik` |
+
+### Meta-Skills (about the agent system itself)
+
+| Skill | Purpose |
+|---|---|
+| `agent-docs-writing` | Documentation hierarchy and reading order |
+| `agents-audit` | Agent docs quality and cleanup |
+| `commands` | Slash command handling |
+| `context-create` | Context document creation and maintenance |
+| `copilot-config` | GitHub Copilot behavior management |
+| `copilot-agents-optimization` | AGENTS.md and copilot-instructions optimization |
+| `feature-planning` | Feature plan structure and workflow |
+| `file-editor` | Auto-open files in user's IDE |
+| `guidelines` | Coding guideline management |
+| `module-management` | Module system understanding |
+| `naming` | Consistent naming conventions |
+| `override-management` | Override system for project customization |
+| `project-analyzer` | Full project analysis orchestration |
+| `project-docs` | Project-specific documentation mapping |
+| `roadmap-management` | Roadmap structure and execution |
+| `sequential-thinking` | Structured problem-solving |
+| `skill-reviewer` | Skill quality auditing (5 Killers checklist) |
+
+## Command Reference by Trigger
+
+| User says... | Command |
+|---|---|
+| "I want to build feature X" | `/feature-explore` or `/feature-plan` |
+| "There's a bug in..." | `/bug-investigate` |
+| "Fix this issue" | `/bug-fix` |
+| "Create a PR" | `/create-pr` |
+| "CI is failing" | `/fix-ci` |
+| "Run quality checks" | `/quality-fix` |
+| "What's the status of this module?" | `/module-explore` |
+| "Document this area" | `/context-create` |
+| "Where was I?" | `/agent-handoff` (start fresh chat with context) |
+| "Clean up agent docs" | `/agents-audit` |
+| "I need to customize a skill" | `/override-create` |
+| "Test a local package" | `/package-test` |
+| "Remove local package link" | `/package-reset` |
+
+## Related
+
+- **Context:** `augment-infrastructure.md` — directory structure overview
+- **Context:** `override-system.md` — how to customize skills/commands
+- **Context:** `documentation-hierarchy.md` — where docs live
+

package/.agent-src/contexts/subagent-configuration.md

@@ -0,0 +1,62 @@
+# Subagent Configuration
+
+Loaded by the `subagent-orchestration` skill and the `/do-and-judge`,
+`/do-in-steps`, and `/judge` commands. Describes how the three
+`subagents.*` keys in `.agent-settings.yml` are resolved at runtime.
+
+## Settings
+
+| Key | Default | Purpose |
+|---|---|---|
+| `subagents.implementer_model` | _(empty → session model)_ | Model alias used for implementer subagents |
+| `subagents.judge_model` | _(empty → one tier up)_ | Model alias used for judge subagents |
+| `subagents.max_parallel` | `3` | Hard cap on concurrent subagent invocations |
+
+## Model tier ladder
+
+The "one tier up" fallback walks this ladder. Session model is the
+starting point; judge picks the tier above.
+
+```
+haiku  →  sonnet  →  opus
+```
+
+If the session runs on **opus**, judge stays on opus (no higher tier
+available). If the session runs on **sonnet**, judge defaults to opus.
+If the session runs on **haiku**, judge defaults to sonnet.
+
+## Resolution order
+
+For both implementer and judge:
+
+1. If the `.agent-settings.yml` value is **non-empty**, use it verbatim
+2. If empty, apply the default (session tier for implementer, one tier
+   up for judge)
+3. Refuse to run if the resolved alias is unknown — list the known
+   aliases and ask the user to pick
+
+The agent must **never silently fall back** to a different model than
+the user configured. An unknown alias is a configuration error.
+
+## Parallelism
+
+`subagents.max_parallel: 1` serializes — pipelines run step-by-step with
+no concurrency. This is the recommended setting when debugging a new
+command or when cost is a concern.
+
+Values higher than 3 are allowed but cost scales linearly with
+concurrent subagents. The default 3 is the sweet spot from the PoC
+measurements: three parallel implementers with one judge typically
+completes a multi-step task 2-3x faster than serial at ~2x the cost.
+
+## When settings change
+
+The `/config-agent-settings` command detects changes and re-resolves
+on next invocation. There is no long-running process to restart — the
+commands read `.agent-settings.yml` on each run.
+
+## Related
+
+- [`subagent-orchestration`](../skills/subagent-orchestration/SKILL.md) — the skill
+- [`model-recommendations`](model-recommendations.md) — tier definitions
+- [`/do-and-judge`](../commands/do-and-judge.md), [`/do-in-steps`](../commands/do-in-steps.md), [`/judge`](../commands/judge.md) — commands that read these keys