@event4u/agent-config 1.9.1

package/.agent-src/guidelines/agent-infra/memory-access.md

@@ -0,0 +1,121 @@
+# Memory Access
+
+How a skill or command reads engineering memory without caring whether
+the optional `agent-memory` companion package is installed.
+
+Single entry point: the shared `retrieve(types, keys, limit)`
+abstraction backed by `scripts/memory_lookup.py` (file fallback) or the
+package adapter (when present). The status helper
+`scripts/memory_status.py` decides which path to take and caches the
+result for the session.
+
+Referenced by
+[`road-to-agent-memory-integration.md`](../../../agents/roadmaps/road-to-agent-memory-integration.md)
+Phase 0. The retrieval contract itself lives in
+[`agent-memory/road-to-retrieval-contract.md`](../../../agents/roadmaps/agent-memory/road-to-retrieval-contract.md).
+
+## The contract
+
+```python
+from scripts.memory_status import status
+from scripts.memory_lookup import retrieve as retrieve_file
+
+hits = retrieve_file(
+    types=["ownership", "historical-patterns"],
+    keys=["app/Http/Controllers/Billing/Checkout.php"],
+    limit=3,
+)
+```
+
+Every backend MUST return a list of `Hit` with:
+
+| Field | Meaning |
+|---|---|
+| `id` | Stable identifier |
+| `type` | One of the curated types (`ownership`, `historical-patterns`, `domain-invariants`, `architecture-decisions`, `incident-learnings`, `product-rules`) |
+| `source` | `"curated"` or `"intake"` |
+| `path` | File or logical source that produced the hit |
+| `score` | Float in `[0..1]`; higher is better |
+| `entry` | Full decoded entry — skills read what they need |
+
+Skills treat `source: "curated"` as higher-trust and `source: "intake"`
+as provisional (best-effort, agent-written, not human-reviewed).
+
+## The detection helper
+
+```python
+from scripts.memory_status import status
+r = status()          # cached; returns in 0ms on hit
+if r.status == "present":
+    ...               # route through agent-memory
+elif r.status == "misconfigured":
+    # surface a warning once per session, then fall back
+    ...
+else:
+    ...               # r.status == "absent" — file fallback, always works
+```
+
+Contract guarantees:
+
+- **Bounded** — cold probe capped at `_HEALTH_TIMEOUT_SECONDS` (2s).
+- **Cached** — subsequent calls in the same process return 0ms.
+- **Never raises on probe failure** — degrades to `absent` or
+  `misconfigured`. Bugs in the helper itself still propagate so they
+  get fixed.
+- **Stable** — the four fields (`status`, `backend`, `reason`,
+  `elapsed_ms`) never change shape between releases.
+
+## How skills should use it
+
+1. **Don't inline the branch.** Skills call the abstraction, not
+   `memory_status.status()` directly, unless they need the human-
+   readable reason (e.g., `review-routing` surfacing "backend
+   misconfigured" on the PR report).
+2. **Cap the load.** Respect `memory.retrieval.max_entries_per_task`
+   from `.agent-project-settings`. Over-retrieval pollutes the context
+   window without improving answers.
+3. **Log the source in the reply.** A reviewer skill citing memory
+   should say "per `ownership:team-payments` (curated) at
+   `agents/memory/ownership.yml:42`" — the reader verifies cheaply.
+4. **Treat intake as low-confidence.** Only promote intake findings
+   into the final reply when the user can act on them; otherwise keep
+   them as internal context.
+
+## Access policy per role mode
+
+Echoes `memory.retrieval.auto_load_shared_types` in
+`.agent-project-settings`:
+
+| Role mode | Auto-loaded types |
+|---|---|
+| Developer | `domain-invariants`, `ownership` |
+| Reviewer | `ownership`, `historical-patterns`, `incident-learnings` |
+| Tester | `historical-patterns`, `incident-learnings` |
+| PO / planner | `product-rules`, `architecture-decisions` |
+| Incident | `incident-learnings`, `ownership` |
+
+Other types remain accessible on demand via
+`/memory-full <type>` (not a skill choice).
+
+## Anti-patterns
+
+- **Do NOT** read `agents/memory/**` directly with ad-hoc globbing.
+  Skills lose the supersede-chain semantics and the `merge=union`
+  guarantees. Always go through `retrieve()`.
+- **Do NOT** cache hits across sessions. Curated files change; the
+  session cache in `status()` is specifically *only* for the detection
+  probe, not for entries.
+- **Do NOT** silently ignore `misconfigured`. Surface a one-liner once
+  per session so the user knows the package is installed but degraded.
+- **Do NOT** fall back to intake JSONL when the curated file *exists
+  but is empty*. That is a valid "no entries" answer, not a fallback
+  signal.
+
+## See also
+
+- [`engineering-memory-data-format.md`](engineering-memory-data-format.md)
+  — the on-disk schema
+- [`../../rules/context-hygiene.md`](../../rules/context-hygiene.md)
+  — token budget that `max_entries_per_task` protects
+- [`../../../agents/roadmaps/road-to-memory-merge-safety.md`](../../../agents/roadmaps/road-to-memory-merge-safety.md)
+  — why intake is append-only JSONL with `merge=union`

package/.agent-src/guidelines/agent-infra/naming.md

@@ -0,0 +1,69 @@
+---
+description: "Naming conventions for skills, rules, commands, and guidelines"
+source: package
+---
+
+# Naming Conventions
+
+## Principles
+
+1. **Name = purpose.** Reading the name tells you what it does.
+2. **No collisions across layers.** A rule and skill must NOT share the same name.
+3. **Consistent prefixes** for related items: `project-analysis-*`, `laravel-*`, `feature-*`.
+4. **Consistent suffixes** for similar roles: `-management`, `-integration`, `-config`.
+5. **No bare nouns** — `jira` says nothing, `jira-integration` says everything.
+
+## Naming patterns by layer
+
+### Skills
+
+| Pattern | When | Examples |
+|---|---|---|
+| `{domain}-{activity}` | Activity/workflow skills | `code-refactoring`, `sql-writing`, `pest-testing` |
+| `{domain}-{role}` | Domain-specific expertise | `php-coder`, `fe-design`, `api-design` |
+| `{domain}-{management}` | CRUD/lifecycle management | `module-management`, `override-management` |
+| `{domain}-{integration}` | External tool integration | `jira-integration`, `sentry-integration` |
+| `{domain}-{config}` | Configuration/setup | `copilot-config`, `devcontainer` |
+| `{framework}-{feature}` | Framework-specific | `laravel-validation`, `laravel-mail` |
+| `{scope}-analysis-{variant}` | Analysis skills | `project-analysis-laravel`, `performance-analysis` |
+| `{action}-{target}` | Action commands as skills | `bug-analyzer`, `skill-reviewer` |
+
+### Rules
+
+| Pattern | When | Examples |
+|---|---|---|
+| `{concern}` | Behavioral constraint | `scope-control`, `ask-when-uncertain` |
+| `{domain}-{concern}` | Domain-specific rule | `php-coding`, `e2e-testing` |
+| `{action}-{target}` | Trigger-based auto rule | `capture-learnings`, `downstream-changes` |
+
+### Commands
+
+| Pattern | When | Examples |
+|---|---|---|
+| `{verb}-{target}` | Action commands | `create-pr`, `fix-ci`, `commit` |
+| `{target}-{verb}` | Target-first grouping | `roadmap-create`, `roadmap-execute` |
+| `{scope}-{action}` | Scoped actions | `optimize-agents`, `review-changes` |
+
+### Guidelines
+
+| Pattern | When | Examples |
+|---|---|---|
+| `{language}/{topic}.md` | Language-specific | `php/general.md`, `php/naming.md` |
+| `{domain}/{topic}.md` | Domain-specific | `agent-infra/naming.md`, `e2e/locators.md` |
+
+## Anti-patterns
+
+| Don't | Why | Do instead |
+|---|---|---|
+| Single bare noun (`jira`, `sql`) | Ambiguous — could be anything | `jira-integration`, `sql-writing` |
+| Same name across layers | Routing confusion | `agent-docs` (rule) + `agent-docs-writing` (skill) |
+| `-er` suffix for skills | Skills are not agents | `-ing` or `-management` |
+| `{dir}/{dir}.md` for guidelines | Redundant | `php/general.md` not `php/php.md` |
+| Abbreviations alone (`rtk`, `mcp`) | Meaningless to new users | `rtk-output-filtering`, `mcp` (OK if well-known) |
+| Inconsistent prefix grouping | Hard to discover related items | All Laravel skills start with `laravel-*` |
+
+## Linter enforcement
+
+The skill linter (`scripts/skill_linter.py`) warns on:
+- **Bare-noun names** — single word without qualifier (e.g., `jira` instead of `jira-integration`)
+- **Layer collisions** — same name used for both a rule and a skill

package/.agent-src/guidelines/agent-infra/output-patterns.md

@@ -0,0 +1,117 @@
+# Output Patterns
+
+Reference patterns for token-efficient command execution and output handling.
+Referenced by the `token-efficiency` rule.
+
+## Pattern: Redirect, Summarize, Target
+
+Every command that MAY produce more than ~30 lines of output:
+
+### Step 1: Redirect to file
+
+```bash
+docker compose exec -T <service> <command> 2>&1 > /tmp/<tool>-output.txt
+echo "EXIT=$?"
+```
+
+### Step 2: Read ONLY the summary
+
+```bash
+tail -5 /tmp/<tool>-output.txt
+```
+
+### Step 3: If errors exist, read ONLY what you need to fix
+
+```bash
+# Read specific error lines
+grep "ERROR\|error\|✏️" /tmp/<tool>-output.txt | head -20
+
+# Read a specific file's errors
+grep "app/Services/MyService.php" /tmp/<tool>-output.txt
+```
+
+**NEVER** do:
+
+- `cat /tmp/<tool>-output.txt` (loads everything)
+- Read the full output of a passing command (waste)
+- Read diffs you don't plan to act on
+
+---
+
+## Targeted Operations
+
+Minimize scope. Never fetch more than you need.
+
+### Queries and lookups
+
+- **Single item over list**: query directly, don't fetch list to find one entry.
+- **Filtered queries**: always filter when listing unavoidable. `--filter=ClassName` not `--all`.
+- **Specific fields**: request only needed fields.
+- **JSON + jq**: use JSON output + `jq` to extract exactly what you need.
+
+### Testing
+
+- **During work**: ONLY the specific test affected (`--filter=ClassName`).
+- **Broader scope**: only if change could affect other tests.
+- **Full suite**: only at the very end.
+- **Decision tree**:
+  1. Changed one method → run that method's test
+  2. Changed a class → run that class's test file
+  3. Changed a shared service → run tests for all consumers
+  4. Changed config/infrastructure → full suite
+
+### API calls
+
+- Targeted endpoints over list endpoints
+- Small page sizes, stop after finding what you need
+- Don't re-fetch what you just received
+
+---
+
+## Tool-First, Script-Last
+
+**Prefer skills with CLI tools over custom scripts.**
+
+### Hierarchy
+
+1. **Existing skill** — use directly
+2. **Skill + CLI tool** (jq, grep, awk, sed) — compose
+3. **Python/Bash script** — only when no skill/tool combination exists
+
+### Scripts allowed only when
+
+- No skill covers the workflow
+- No CLI tool achieves the goal
+- Operation needs programmatic logic
+- Script is reusable
+
+### Scripts NOT allowed when
+
+- Skill exists for this workflow
+- `jq` can extract what you need
+- `grep` + `head` can filter output
+
+### Learning trigger
+
+When you write a script because no skill exists → capture learning → propose skill.
+
+---
+
+## General Rules
+
+For tool-specific commands → see the `quality-tools` skill.
+
+1. **ECS and Rector are trusted tools** — run with `--fix`, don't read diffs. Trust the config.
+   Verification: PHPStan + tests afterwards.
+
+2. **Both ECS and Rector always run with `--fix`** — dry-run diffs waste tokens.
+
+3. **Exit code first**: Check `$?` before reading ANY output. If 0, you're done.
+
+4. **Summary line**: Most tools print a summary as the last few lines. That's all you need.
+
+5. **Targeted grep**: `grep` for the specific file or error type. Never read full output "just in case".
+
+6. **Don't re-read**: Once read and acted on, don't re-load into context.
+
+7. **Iterative fixing**: Fix one error, re-run, check exit code. Output becomes stale after each fix.

package/.agent-src/guidelines/agent-infra/review-routing-data-format.md

@@ -0,0 +1,144 @@
+# Review Routing Data Format
+
+Schema and conventions for the two project-local YAML files that feed the
+[`review-routing-awareness`](../../rules/review-routing-awareness.md) rule
+and the [`review-routing`](../../skills/review-routing/SKILL.md) skill.
+
+Both files are **optional** and live in the consumer repository — never
+in package-shipped artifacts. Absence is handled gracefully: routing
+falls back to generic role-based reviewer suggestions.
+
+## File locations
+
+Primary (checked first):
+
+- `.github/ownership-map.yml`
+- `.github/historical-bug-patterns.yml`
+
+Fallback (checked if the `.github/` file does not exist):
+
+- `agents/ownership-map.yml`
+- `agents/historical-bug-patterns.yml`
+
+Choose one location per project and stick with it. Having both is not an
+error, but tools read only the first match.
+
+## ownership-map.yml
+
+Maps glob patterns → roles + optional focus + optional risk hint.
+
+```yaml
+# Required: the version field — breaks loudly if future schema changes.
+version: 1
+
+# Optional: last-reviewed timestamp. If > 6 months old, routing
+# flags the map as stale in its report.
+updated: 2026-02-01
+
+# Optional: defaults applied when no entry matches. If omitted,
+# unmatched paths fall through to reviewer-awareness defaults.
+defaults:
+  roles: [backend]
+
+# Required: list of entries, first match wins per file.
+entries:
+  - paths:
+      - "app/Billing/**"
+      - "app/Services/Payment*.php"
+    roles: [finance-engineering, security]
+    focus: "tax calculation + idempotency"
+    risk: "monetary correctness — regressions bill real customers"
+
+  - paths:
+      - "**/Tenant*.php"
+      - "app/Http/Middleware/TenantScope.php"
+    roles: [platform, security]
+    focus: "cross-tenant isolation"
+    risk: "data leak across customers"
+
+  - paths:
+      - "resources/views/**"
+      - "**/*.blade.php"
+    roles: [frontend]
+    focus: "a11y + responsive layout"
+```
+
+Field semantics:
+
+- **paths** (required, list) — fnmatch globs, same syntax as
+  `pr-risk-config.yml`. First match wins; later entries are ignored for
+  that path.
+- **roles** (required, list) — role identifiers from the common
+  vocabulary in [`reviewer-awareness`](../../rules/reviewer-awareness.md)
+  or project-custom roles.
+- **focus** (optional, string) — one-line description of what reviewers
+  should look at. Surfaced in the PR comment verbatim.
+- **risk** (optional, string) — one-line description of what goes wrong
+  when this area breaks. Used by routing to annotate high-risk matches.
+
+## historical-bug-patterns.yml
+
+Registry of recurring failure modes. Each pattern names a class of bug
+the project has paid for before, with the minimum control or test
+expected for similar new work.
+
+```yaml
+version: 1
+updated: 2026-02-01
+
+patterns:
+  - id: n-plus-one-tenant-listing
+    label: "N+1 on tenant-scoped listings"
+    severity: medium
+    paths:
+      - "app/Http/Controllers/**Listing*.php"
+      - "app/Services/**Query*.php"
+    required_test: "assert query count ≤ N for a multi-row fixture"
+    references:
+      - "PR #842 — production slowdown 2024-09"
+
+  - id: missing-policy-on-admin-route
+    label: "Admin-only route without Gate::allows"
+    severity: high
+    paths:
+      - "app/Http/Controllers/Admin/**"
+      - "routes/admin.php"
+    required_test: "negative test: non-admin gets 403"
+
+  - id: queue-job-not-idempotent
+    label: "Queue job without idempotency key"
+    severity: high
+    paths:
+      - "app/Jobs/**"
+    required_test: "asserting a retried job does not double-write"
+```
+
+Field semantics:
+
+- **id** (required, unique string) — stable slug; used in PR comments
+  and tests as a label.
+- **label** (required, string) — human-readable name.
+- **severity** (required, `low` | `medium` | `high`) — matched patterns
+  contribute this severity to overall PR routing.
+- **paths** (required, list) — fnmatch globs. A pattern matches the
+  diff when **any** changed file matches any glob.
+- **required_test** (required, string) — the specific assertion or
+  regression test the pattern demands. Feeds
+  [`verify-before-complete`](../../rules/verify-before-complete.md) and
+  [`judge-test-coverage`](../../skills/judge-test-coverage/SKILL.md).
+- **references** (optional, list) — links to prior PRs, incidents, or
+  postmortems. Agents quote these verbatim when warning about a match.
+
+## Maintenance
+
+- Both files are code. Review changes to them like code — PR + review.
+- Stale is worse than absent. Update the `updated` field or delete the
+  file when ownership or patterns have drifted.
+- Never auto-generate entries from agent sessions. Entries are curated,
+  not inferred.
+
+## See also
+
+- [`review-routing-awareness`](../../rules/review-routing-awareness.md)
+- [`reviewer-awareness`](../../rules/reviewer-awareness.md)
+- [`review-routing`](../../skills/review-routing/SKILL.md)

package/.agent-src/guidelines/agent-infra/role-contracts.md

@@ -0,0 +1,211 @@
+# Role Contracts
+
+Six named working modes with a fixed output contract per mode. Loading
+a role frame stabilizes smaller models: they stop inventing a frame per
+task and produce reproducible outputs on the same input.
+
+Referenced by `road-to-role-modes.md` Phase 1. Each contract is a
+*skeleton*, not a form — fields without evidence become questions via
+`ask-when-uncertain`, never fabrications.
+
+## The six modes
+
+| Mode | Entry signal | Default skills | Output contract |
+|---|---|---|---|
+| **Developer** | "implement X", `/jira-ticket`, `/bug-fix` | `php-coder`, `laravel`, `test-driven-development`, `quality-tools` | Goal / Plan / Changes / Tests / Open questions |
+| **Reviewer** | `/review-changes`, `/judge`, PR open on branch | `judge-bug-hunter`, `judge-code-quality`, `judge-security-auditor`, `judge-test-coverage` | Summary / Risks / Findings / Required actions / Verdict |
+| **Tester** | "add tests", "why does X fail", test output in context | `pest-testing`, `api-testing`, `e2e-plan`, `test-performance` | Behaviour under test / Edge cases / Negative paths / Reproduction / Coverage gaps |
+| **PO** | "I want a feature", `/feature-explore`, `/feature-plan` | `validate-feature-fit`, `api-design`, `threat-modeling` | Goal / Assumptions / Acceptance criteria / Impacted modules / Risks / Open questions for stakeholder |
+| **Incident** | "production is down", `break-glass: true`, hotfix branch | `bug-investigate`, `systematic-debugging`, `authz-review` | Symptom / Reproduction / Minimal reversible change / Deferred verification / Follow-up commitment / Incident learning |
+| **Planner** | "what's the strategy", `/feature-roadmap`, multi-step work with unclear order | `feature-plan`, `feature-roadmap`, `blast-radius-analyzer` | Goal / Constraints / Option set / Recommendation / Dependencies / Rollback |
+
+## Contract skeletons
+
+### Developer
+
+```
+**Goal:** <what the user asked for, one sentence>
+**Plan:** <ordered steps, ≤5>
+**Changes:** <files touched, one line each>
+**Tests:** <added/updated tests + how to run>
+**Open questions:** <unresolved items, none if blank>
+```
+
+### Reviewer
+
+```
+**Summary:** <one-paragraph overview of the diff>
+**Risks:** <ranked list: high/medium/low>
+**Findings:** <file:line → issue → fix suggestion>
+**Required actions:** <numbered list the author must address>
+**Verdict:** approve | request changes | block
+```
+
+### Tester
+
+```
+**Behaviour under test:** <the invariant, one sentence>
+**Edge cases:** <boundary + error paths covered>
+**Negative paths:** <expected failures, error types>
+**Reproduction:** <how to run a single failing case>
+**Coverage gaps:** <what stayed untested and why>
+```
+
+### PO
+
+```
+**Goal:** <user-facing outcome>
+**Assumptions:** <each marked `verify with: {name}` if unconfirmed>
+**Acceptance criteria:** <testable, numbered>
+**Impacted modules:** <paths, not speculation>
+**Risks:** <business + technical>
+**Open questions for stakeholder:** <blocking decisions only>
+```
+
+### Incident
+
+```
+**Symptom:** <what users see, not the hypothesis>
+**Reproduction:** <minimal steps or "not reproduced">
+**Minimal reversible change:** <the smallest fix>
+**Deferred verification:** <what was skipped under break-glass>
+**Follow-up commitment:** <PR/ticket for full verification, due date>
+**Incident learning:** <intake signal id, OR `/memory-add incident-learnings` draft ref>
+```
+
+**Memory-write is the final field, not a nice-to-have.** Before the
+mode exits, the agent MUST either emit an intake signal via
+[`memory-access`](memory-access.md) (`scripts/memory_signal.py`
+append — one line, fire-and-forget) or draft a curated entry with
+[`/memory-add incident-learnings`](../../commands/memory-add.md).
+Pattern + consequence + guardrail, redacted. Skipping this field
+means the incident did not produce a learning — log the absence,
+do not pretend verification happened.
+
+### Planner
+
+```
+**Goal:** <target state, one paragraph>
+**Constraints:** <hard limits: time, deps, policy>
+**Option set:** <2-4 options with trade-offs>
+**Recommendation:** <which option + one-line justification>
+**Dependencies:** <what must ship first>
+**Rollback:** <how to revert if it fails>
+```
+
+## Integration rules
+
+- **`ask-when-uncertain`** — any contract field without evidence becomes
+  a question, not a guess. The contract does not license fabrication.
+- **`scope-control`** — `Reviewer` mode forbids implementation work.
+  `Developer` mode forbids producing review verdicts on own code.
+  `PO` mode forbids committing to absent stakeholders' decisions.
+- **`preservation-guard`** — no mode justifies rewriting or removing
+  existing skills. Modes *compose* skills, they do not replace them.
+- **`verify-before-complete`** — the final field of every contract is
+  an evidence field (Tests, Verdict, Reproduction, Acceptance criteria,
+  Deferred verification, Rollback). No mode ships without it.
+
+## When to load a contract
+
+- **Explicit**: user invokes a command in the entry-signal column.
+- **Inferred**: first message matches a signal — surface one line
+  (`> entering {mode} mode — contract: {fields}`) and continue.
+- **Overridden**: user says "no mode" or invokes `/mode none` — drop
+  the frame and fall back to default conversation.
+
+## Structured mode markers
+
+Every contract output MUST begin with a one-line HTML comment so
+session captures, log scrapers, and the measurement hook in
+[`road-to-role-modes.md`](../../../agents/roadmaps/road-to-role-modes.md#phase-4--measurement-hook-closes-q2-of-master-frame)
+can count contract-conformant outputs per mode:
+
+```
+<!-- role-mode: developer | contract: goal,plan,changes,tests,open-questions -->
+```
+
+The marker is:
+
+- **Invisible** in rendered markdown — no UI noise.
+- **Greppable** with a stable prefix (`role-mode:`).
+- **Self-describing** — `contract:` lists the fields in kebab-case and
+  in the order they must appear, so a scraper can verify conformance
+  without hardcoding the mode→contract map.
+
+Reserved values for `role-mode`:
+
+- `developer` · `reviewer` · `tester` · `po` · `incident` · `planner`
+
+Any other value is treated as non-conformant. A reply with no marker
+counts as the default "no-mode" conversation and does not feed the
+mode statistics.
+
+## Personas (advisory pairings)
+
+Modes own the **workflow closing contract**. Personas own the
+**voice** a skill brings to the work. They compose: a skill invoked
+inside a mode can cite one or more personas to shape *how* it
+reviews, reasons, or pushes back — without changing the mode's
+output contract.
+
+This table is **advisory**, not enforcing. A skill may cite any
+persona inside any mode; the mapping below is just the most common
+fit. See [`../../personas/README.md`](../../personas/README.md) for
+the persona catalog and schema.
+
+| Mode | Typical persona companions | Why |
+|---|---|---|
+| **Developer** | `developer`, `ai-agent` | Implementation voice + automation-readiness check on the plan |
+| **Reviewer** | `critical-challenger`, `senior-engineer`, `qa` | Fake-clarity hunt, architectural lock-in, coverage gaps |
+| **Tester** | `qa`, `developer` | Testability lens + implementation-reality sanity check |
+| **PO** | `product-owner`, `stakeholder`, `critical-challenger` | Outcome/AC, business fit, challenge hidden assumptions |
+| **Incident** | `senior-engineer`, `developer` | Smallest reversible change + long-term risk on the hotfix |
+| **Planner** | `senior-engineer`, `stakeholder`, `critical-challenger` | Architecture impact, business framing, option-set honesty |
+
+### Invocation
+
+Skills cite personas in frontmatter:
+
+```yaml
+---
+name: requesting-code-review
+personas: [critical-challenger]
+---
+```
+
+Commands accept a CLI-style override that wins over the skill default:
+
+```
+/refine-ticket --personas=product-owner,senior-engineer,+qa
+```
+
+Prefix `+` adds a persona to the default cast; prefix `-` removes one.
+Omitting `--personas` uses the skill's documented default.
+
+### Conflict resolution
+
+If the active mode forbids an action and a persona would push for
+that action (e.g. Reviewer mode + `developer` persona suggesting an
+implementation fix), the agent surfaces a numbered-options prompt per
+[`agent-interaction-and-decision-quality.md`](agent-interaction-and-decision-quality.md) —
+never silently switches mode, never silently drops the persona
+finding. See the Q4 rule in `road-to-personas.md`.
+
+## Anti-patterns
+
+- **Do NOT** mix two contracts in one reply. If the task shifts
+  (review → fix), close the current contract first with its evidence
+  field, then enter the next mode.
+- **Do NOT** invent fields the contract does not list. The skeleton
+  is the maximum surface, not the minimum.
+- **Do NOT** hand-wave the final evidence field ("tests should pass").
+  Run the verification or mark it as deferred with a follow-up commit.
+- **Do NOT** treat the default-skills list as mandatory. The skills
+  are pre-loaded; the contract decides which get invoked.
+
+## See also
+
+- [`road-to-role-modes.md`](../../../agents/roadmaps/road-to-role-modes.md) — roadmap this guideline implements
+- [`output-patterns.md`](output-patterns.md) — generic output conventions modes inherit
+- [`agent-interaction-and-decision-quality.md`](agent-interaction-and-decision-quality.md) — how modes interact with the numbered-options protocol