@event4u/agent-config 1.20.0 → 1.22.0

package/.agent-src/skills/performance-analysis/SKILL.md

@@ -80,7 +80,7 @@ Focus on code paths with high execution frequency or large data volumes:
 - Missing CDN for static assets
 - Missing response caching for read-heavy endpoints
 - Database connection pooling and limits
-- Queue worker concurrency vs database connection limits
+- Queue worker concurrency vs DB connection limits
 
 ## Output format
 
@@ -101,12 +101,12 @@ For each bottleneck:
 - **performance** — complementary: performance is about writing fast code, this is about finding slow code
 - **test-performance** — for test suite speed specifically
 - **bug-analyzer** — some performance issues are actually bugs (N+1, infinite loops)
-- **database** — for deep DB optimization guidance
+- **DB** — for deep DB optimization guidance
 
 ## Gotcha
 
 - Don't present raw numbers without context — "200ms" means nothing without knowing the baseline.
-- The model tends to focus on code-level optimization when the bottleneck is a database query.
+- The model tends to focus on code-level optimization when the bottleneck is a DB query.
 - Profiling in development differs from production — different data volumes, different query plans.
 
 ## Do NOT

package/.agent-src/skills/pest-testing/SKILL.md

@@ -53,9 +53,9 @@ For bug fixes and new features, prefer test-driven development:
 
 ### Why test-first matters
 
-Tests written **after** implementation pass immediately. Passing immediately proves nothing:
+Tests written **after** impl pass immediately. Passing immediately proves nothing:
 - The test might test the wrong thing.
-- The test might test implementation, not behavior.
+- The test might test impl, not behavior.
 - You never saw it catch the bug — so you don't know if it would.
 
 ### Bug fix TDD
@@ -120,7 +120,7 @@ The test proves the fix works AND prevents regression.
 - For JSON APIs, assert:
     - exact relevant fields
     - error structure when applicable
-    - database state after the request
+    - DB state after the request
 - Do not only assert `200` — verify meaningful behavior.
 
 ## Validation tests
@@ -258,7 +258,7 @@ When reviewing or auditing existing tests, check for these anti-patterns:
 
 - Do not test private methods directly.
 - Do not over-mock Laravel internals.
-- Do not assert implementation details when behavior assertions are enough.
+- Do not assert impl details when behavior assertions are enough.
 - Do not write brittle tests tied to formatting or irrelevant response noise.
 - Do not create giant tests that cover many behaviors at once.
 - Do not skip authorization or validation coverage for important endpoints.
@@ -285,7 +285,7 @@ When generating Pest tests:
 - Don't use `readonly` or `final` on Pest test helper classes — it breaks mocking.
 - Don't add `use` statements for global classes (`Exception`, `DateTimeImmutable`) in Pest files — they're auto-imported.
 - The model forgets `$this->travel(5)->seconds()` for time-dependent tests — never rely on `now()` differing between lines.
-- Parallel tests share the database — don't assume column values are null unless you explicitly set them.
+- Parallel tests share the DB — don't assume column values are null unless you explicitly set them.
 
 ## Do NOT
 
@@ -297,7 +297,7 @@ When generating Pest tests:
 When generating new tests, focus on:
 - **Business logic**: calculations, status transitions, validation rules, data transformations
 - **Edge cases**: null, empty string, zero, negative numbers, boundary values, max length
-- **Error paths**: invalid input, missing dependencies, exception handling
+- **Error paths**: invalid input, missing deps, exception handling
 - **Different code branches**: if/else, early returns, fallback behavior
 
 What NOT to test:

package/.agent-src/skills/php-service/SKILL.md

@@ -38,7 +38,7 @@ Do NOT use when:
 1. Location: `app/Services/{Domain}/` or `app/Modules/{Module}/App/Services/`.
 2. `declare(strict_types=1)`, proper namespace.
 3. Constructor inject dependencies (repositories, other services).
-4. Max 4 constructor dependencies — if more, split the service.
+4. Max 4 constructor deps — if more, split the service.
 
 ### Step 2: Implement methods
 
@@ -69,7 +69,7 @@ public function __invoke(
 
 - Run PHPStan on the service — must pass at level 9.
 - Verify single responsibility: service does one thing, no mixed concerns.
-- Confirm all dependencies are constructor-injected (no `app()` or facades in service).
+- Confirm all deps are constructor-injected (no `app()` or facades in service).
 - Run affected tests — must pass.
 
 ## Output format

package/.agent-src/skills/project-analysis-hypothesis-driven/SKILL.md

@@ -11,7 +11,7 @@ source: package
 Use this skill when:
 
 * There is a concrete issue to explain
-* Multiple root causes are plausible
+* Multiple root → are plausible
 * The system spans several layers
 * A shallow single-explanation answer would be risky
 * `universal-project-analysis` or `bug-analyzer` routes here
@@ -27,7 +27,7 @@ Do NOT use when:
 * Never stop at the first plausible explanation
 * Code, docs, and evidence beat intuition
 * Rejected hypotheses matter
-* Multiple interacting causes are common
+* Multiple interacting → are common
 * Uncertainty must be marked explicitly
 
 ## Procedure
@@ -89,7 +89,7 @@ Ask:
 
 * does this fully explain the behavior?
 * what remains unexplained?
-* could multiple causes interact?
+* could multiple → interact?
 * does contradictory evidence exist?
 
 If anything major remains unexplained: continue analysis, do not present a final conclusion yet.

package/.agent-src/skills/project-analysis-react/SKILL.md

@@ -107,7 +107,7 @@ Check:
 ## Gotcha
 
 * React bugs often come from stale state, not broken logic.
-* Missing dependencies in hooks are one of the most common root causes.
+* Missing deps in hooks are one of the most common root causes.
 * Overusing memoization can make code harder to reason about without solving real problems.
 
 ## Do NOT

package/.agent-src/skills/project-analysis-symfony/SKILL.md

@@ -34,7 +34,7 @@ Do NOT use when:
 ### 1. Confirm Symfony version and app shape
 
 Check: `composer.lock`, `composer.json`, Symfony packages/components, PHP version, environment config structure.
-Validate: Symfony version is explicit, major bundles/components are identified, environment-specific config layout is known.
+Validate: Symfony version is explicit, major bundles/components are identified, env-specific config layout is known.
 
 ### 2. Analyze kernel and container boot
 

package/.agent-src/skills/project-analysis-zend-laminas/SKILL.md

@@ -44,7 +44,7 @@ Check:
 
 * merge order surprises
 * missing overrides
-* environment config mismatches
+* env config mismatches
 * heavy bootstrap logic
 
 ### 3. Analyze ServiceManager behavior
@@ -96,7 +96,7 @@ Check:
 ## Gotcha
 
 * Many Zend/Laminas issues are caused by config order and service resolution, not controller code.
-* Shared services and legacy migration remnants can create cross-request or environment-specific bugs.
+* Shared services and legacy migration remnants can create cross-request or env-specific bugs.
 * Old project behavior may depend on historical bootstrap side effects that are easy to miss.
 
 ## Do NOT

package/.agent-src/skills/project-analyzer/SKILL.md

@@ -233,7 +233,7 @@ Each module gets its own file in `agents/analysis/modules/`. Format:
 ### Phase 3: Data layer
 
 - List all models with their connections, tables, and key relationships
-- Map database schema: tables, foreign keys, indexes
+- Map DB schema: tables, foreign keys, indexes
 - Document multi-tenant split (which tables in which DB)
 - **Output:** `agents/analysis/models/api-database.md`, `customer-database.md`
 
@@ -242,7 +242,7 @@ Each module gets its own file in `agents/analysis/modules/`. Format:
 - Identify domains from models, services, routes, and directory structure
 - For each domain: map models → services → controllers → jobs → events
 - Document business rules and data flows
-- Document inter-domain dependencies
+- Document inter-domain deps
 - **Output:** `agents/analysis/domains/{domain}.md` (one per domain)
 
 ### Phase 5: API surface
@@ -254,7 +254,7 @@ Each module gets its own file in `agents/analysis/modules/`. Format:
 
 ### Phase 6: Service map
 
-- List all services with purpose, key methods, and dependencies
+- List all services with purpose, key methods, and deps
 - Map service → repository → model relationships
 - Identify God services (too many responsibilities)
 - **Output:** `agents/analysis/services/service-map.md`
@@ -315,7 +315,7 @@ Each module gets its own file in `agents/analysis/modules/`. Format:
 ## Output format
 
 1. Structured analysis document in agents/analysis/
-2. Tech stack inventory with versions and dependencies
+2. Tech stack inventory with versions and deps
 3. Architecture diagram or module map
 
 ## Auto-trigger keywords

package/.agent-src/skills/prompt-optimizer/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: prompt-optimizer
+description: "Use when the user wants a prompt optimized for ChatGPT, Claude, Gemini, or another AI — 'make this prompt better', 'optimize for ChatGPT', 'rewrite my prompt' — even without saying 'optimize'."
+source: package
+---
+
+# prompt-optimizer
+
+> Persona: **Lyra** — a master-level prompt-optimization specialist. Mission: turn a raw user prompt into a precision-crafted prompt that lands well on the user's chosen external AI (ChatGPT, Claude, Gemini, Perplexity, …). Sibling of [`refine-prompt`](../refine-prompt/SKILL.md) which is engine-inbound; this skill is engine-outbound (the polished prompt is text the user will paste elsewhere).
+
+## When to use
+
+- The user pastes a rough prompt and asks for it to be optimized, rewritten, sharpened, or "made better".
+- The user mentions a target AI (ChatGPT, Claude, Gemini, Perplexity, Copilot) and wants their prompt tuned for it.
+- The user invokes [`/optimize-prompt`](../../commands/optimize-prompt.md).
+- The user describes a goal ("I need a marketing-email prompt for ChatGPT") and the deliverable is a prompt, not the email itself.
+
+## When NOT to use (near-misses)
+
+| Phrasing | Route to |
+|---|---|
+| "refine this ticket / prompt for the engine" | [`refine-prompt`](../refine-prompt/SKILL.md) |
+| "make this skill description pushier" | [`description-assist`](../description-assist/SKILL.md) |
+| "write the marketing email itself" | direct execution — the user wants the artifact, not a prompt |
+| "review my code / commit" | [`review-changes`](../../commands/review-changes.md) and friends |
+
+## The 4-D Methodology
+
+1. **Deconstruct** — extract core intent, key entities, output shape, constraints; map what's provided vs missing.
+2. **Diagnose** — audit clarity gaps, ambiguity, missing specificity, missing structure; flag unstated assumptions.
+3. **Develop** — pick techniques by request type:
+   - *Creative* → multi-perspective + tone anchoring
+   - *Technical* → constraint-based + precision focus
+   - *Educational* → few-shot examples + clear structure
+   - *Complex* → chain-of-thought + systematic framing
+   - Assign an AI role/expertise; layer context; add logical structure.
+4. **Deliver** — output the optimized prompt + a short "what changed" + (DETAIL only) techniques applied + one pro-tip.
+
+## Modes — BASIC vs DETAIL
+
+**Auto-detect on first turn:**
+
+| Signal | Mode |
+|---|---|
+| User wrote "BASIC" or "DETAIL" verbatim | honor it |
+| One-line ask, common task (resume help, casual email, summary) | BASIC |
+| Multi-paragraph context, professional/technical scope, named audience, named tone | DETAIL |
+| Target AI not named AND request implies platform-sensitive output | DETAIL |
+| **Tiebreaker** — both BASIC and DETAIL signals fire | DETAIL (safer default) |
+
+**BASIC** — apply core 4-D fixes silently, return optimized prompt + 3-bullet "what changed". No questions.
+
+**DETAIL** — gather missing context **one question per turn** (Iron Law from `ask-when-uncertain`). Stop asking once Deconstruct + Diagnose are clean. Then deliver.
+
+**Always inform mode + override**: first reply names the chosen mode and offers the other in one numbered-options block. Re-pick is silent on subsequent turns.
+
+## Procedure
+
+### 1. Receive input
+
+Capture: (a) the rough prompt, (b) target AI if named, (c) explicit BASIC/DETAIL marker if present. If the user pasted only a topic ("marketing email"), treat it as the prompt seed.
+
+### 2. Auto-detect mode + announce
+
+Apply the table above. State: *"Running in BASIC — say `DETAIL` to switch."* (or vice-versa). Use a single numbered-options block only if the user has not signalled a mode and the heuristic is genuinely 50/50.
+
+### 3. Inspect + Diagnose (Deconstruct)
+
+Identify each slot in the rough prompt: intent · entities · output shape · constraints · target AI · tone · audience. List every missing slot. Check for ambiguity, unstated assumptions, and contradictory requirements.
+
+### 4a. BASIC path
+
+Fill missing slots with safe defaults (general audience, neutral tone, the named AI or "any modern LLM"). Skip to step 5.
+
+### 4b. DETAIL path
+
+Ask **one** question for the highest-leverage missing slot. Order: target AI → output shape → audience → tone → constraints. Stop asking once the prompt would land cleanly. Never batch. Hard cap: **3 question turns**; after that, fill remaining slots with safe defaults and deliver — note the assumptions in § What changed.
+
+### 5. Develop
+
+Pick techniques per request type (see § 4-D step 3). Assign role ("You are a senior X…"), layer context, add structure (numbered steps, bullet headers, output format spec, length cap), and inject specificity (concrete numbers, named formats, explicit success criteria — replace "good", "professional", "high-quality" with measurable criteria).
+
+### 6. Deliver
+
+Format per § Output format. Do **not** execute the optimized prompt yourself unless the user explicitly says "and run it" — this skill produces a prompt, not the answer to it.
+
+## Output format
+
+1. **Optimized prompt** — fenced code block, ready to copy. Top line names the target AI if known.
+2. **What changed** — 3-5 bullets, each ≤ 12 words.
+3. **Techniques applied** *(DETAIL only)* — bullet list naming the techniques (e.g. "few-shot", "chain-of-thought", "role assignment").
+4. **Pro tip** — one sentence, platform-specific when target AI is known (e.g. "Claude responds well to XML tags"; "ChatGPT honors length caps in the system message").
+
+## Gotcha
+
+- The model tends to **execute** the rough prompt instead of optimizing it — when the user pastes "write a marketing email", treat the whole line as the *seed*, not the *task*. Confirm by asking "optimize this prompt, or write the email?" if genuinely ambiguous.
+- The model tends to ask **multiple** clarifying questions in DETAIL mode — Iron Law is one per turn. Pick the highest-leverage missing slot and stop.
+- The model tends to invent platform tips that aren't true — only emit a pro-tip when the technique is well-known for the named AI; otherwise omit the section.
+- The model tends to over-engineer BASIC mode — for a one-line ask, the optimized prompt should still be short. No 800-word system prompts for "help with my resume".
+- Don't drift into German welcome text. The optimized prompt mirrors the user's source-language preference; the skill's own scaffolding stays English (per `language-and-tone` for `.md`).
+- The model tends to **mix languages** in the optimized prompt when the user wrote in German but named an English-speaking target audience — pick one language for the whole optimized prompt body (default: source-language of the rough prompt unless the user explicitly named the target audience's language).
+
+## Do NOT
+
+- Do NOT execute the optimized prompt and return its answer unless the user explicitly asks for both.
+- Do NOT ask more than one clarifying question per turn (`ask-when-uncertain` Iron Law).
+- Do NOT add an "I'm Lyra" preamble on every turn — the welcome belongs to the command entry point, not every reply.
+- Do NOT modify project files — this skill is conversational, no file writes, no commits.

package/.agent-src/skills/readme-reviewer/SKILL.md

@@ -54,7 +54,7 @@ Inspect truth-defining files:
 - Config files, tests, existing docs
 
 Verify: install steps exist, commands work, features are implemented,
-dependencies are real.
+deps are real.
 
 ### 3. Validate installation and setup
 

package/.agent-src/skills/roadmap-management/SKILL.md

@@ -9,8 +9,8 @@ source: package
 ## When to use
 
 Use this skill when:
-- Creating a new roadmap (`roadmap-create` command)
-- Executing a roadmap (`roadmap-execute` command)
+- Creating a new roadmap (`/roadmap:create` command)
+- Executing a roadmap (`/roadmap:process-step|phase|full` commands)
 - Checking roadmap progress
 - Updating roadmap status after completing work
 
@@ -119,8 +119,8 @@ Every roadmap follows this structure:
 
 Every roadmap implicitly includes the project's quality pipeline
 (static analysis, autofixes, tests). What's configurable is **when**
-the pipeline runs during `/roadmap execute`, controlled by
-`roadmap.quality_cadence` in `.agent-settings.yml`:
+the pipeline runs during `/roadmap:process-step|phase|full`,
+controlled by `roadmap.quality_cadence` in `.agent-settings.yml`:
 
 | Cadence | Pipeline runs | Trade-off |
 |---|---|---|
@@ -164,7 +164,7 @@ unfamiliar codebases.
    evidence-based reason (e.g. risky migration benefits from a spike).
    Never include release versions, deprecation dates, or git tags in
    the roadmap text. If the user declines, do **not** re-propose during
-   `roadmap-execute`. Decline = silence. See [`scope-control`](../../rules/scope-control.md#decline--silence--no-re-asking-on-the-same-task).
+   `/roadmap:process-*`. Decline = silence. See [`scope-control`](../../rules/scope-control.md#decline--silence--no-re-asking-on-the-same-task).
 5. Save with a kebab-case filename (e.g. `optimize-webhook-jobs.md`).
    **Before writing**, scan the entire roadmap namespace for a
    collision — active, `archive/`, `skipped/`, and nested subdirs —
@@ -289,8 +289,8 @@ is rewritten by `.augment/scripts/update_roadmap_progress.py`.
 **Always regenerate in the SAME response** after any of the following
 (enforced by [`roadmap-progress-sync`](../../rules/roadmap-progress-sync.md)):
 
-- Creating a new roadmap (`roadmap-create`)
-- Marking a step `[x]`, `[~]`, or `[-]` during `roadmap-execute`
+- Creating a new roadmap (`/roadmap:create`)
+- Marking a step `[x]`, `[~]`, or `[-]` during `/roadmap:process-*`
 - Archiving or moving a roadmap to `skipped/`
 - Adding, renaming, or removing a phase
 

package/.agent-src/skills/rule-writing/SKILL.md

@@ -82,6 +82,29 @@ no silent edits, max two rounds.
 * No numbered procedures — if you need steps, it is a skill.
 * Link out to guidelines for deep reference instead of inlining them.
 
+### 3b. Path conventions in frontmatter and body — load-bearing
+
+Three different surfaces, three different rules. Mixing them up will
+either fail the schema (`python3 scripts/validate_frontmatter.py`) or
+fail `python3 scripts/lint_load_context.py`. Canonical reference:
+[`templates/rule.md`](../../templates/rule.md) § Path conventions and
+[`docs/contracts/load-context-schema.md`](../../../docs/contracts/load-context-schema.md).
+
+| Field | Form | Example |
+|---|---|---|
+| `load_context:` / `load_context_eager:` | **Logical name** rooted at the source — never `.agent-src.uncompressed/` | `contexts/execution/verification-mechanics.md` |
+| `triggers[].path_prefix:` | **Literal match pattern** the host evaluates against the file the agent is editing — not rewritten | `.agent-src.uncompressed/skills/` (source-of-truth rules) or `agents/`, `app/`, `.augment/` |
+| Body links to guidelines / contracts | **Verbatim relative form** — `../../docs/...` works in any markdown viewer; rewriter handles depth | `[guideline](../../docs/guidelines/<group>/<name>.md)` |
+
+The compress-time rewriter (`scripts/compress.py::_rewrite_paths`) is
+idempotent and depth-aware — it resolves logical names and body links
+to the deployment-correct relative path at compress time, leaving
+`path_prefix:` literally as written. The schema regex
+(`scripts/schemas/rule.schema.json`) and `scripts/lint_load_context.py`
+both reject the `.agent-src.uncompressed/` prefix in `load_context:` /
+`load_context_eager:` with an error pointing at the canonical logical
+name.
+
 ### 4. Enforce the size budget
 
 Normative source: [`size-enforcement`](../../rules/size-enforcement.md) +
@@ -113,9 +136,19 @@ type: "auto"              # or "always"
 description: "Trigger-shaped sentence — domain + symptoms — soft cap 200 chars"
 alwaysApply: false        # true only if type: always
 source: package           # or project for consumer-local rules
+load_context:             # logical names only — `contexts/<area>/<file>.md`
+  - contexts/execution/verification-mechanics.md
+triggers:                 # path_prefix is literal, not rewritten
+  - path_prefix: ".agent-src.uncompressed/rules/"
+routes_to:
+  - "skill:related-skill"
 ---
 ```
 
+See § 3b above for the load-bearing distinction between `load_context:`
+(logical, rewritten), `triggers[].path_prefix:` (literal, verbatim),
+and body links (relative `../../docs/...`, rewriter handles depth).
+
 ## Output format
 
 1. Complete rule file at `.agent-src.uncompressed/rules/{name}.md`

package/.agent-src/skills/sentry-integration/SKILL.md

@@ -152,7 +152,7 @@ search_events(organizationSlug='my-org', naturalLanguageQuery='count of database
 
 ## Gotcha
 
-- Sentry groups errors by stacktrace — different root causes may appear as the same issue. Check multiple events.
+- Sentry groups errors by stacktrace — different root → may appear as the same issue. Check multiple events.
 - The model tends to analyze only the latest event — check the "Events" tab for patterns across time.
 - Don't use Sentry MCP tools for simple lookups — use the Sentry web UI link instead (saves tokens).
 

package/.agent-src/skills/skill-writing/SKILL.md

@@ -258,6 +258,20 @@ Example:
 * Validation must be concrete
 * One skill = one job
 
+### Cross-references and paths
+
+* Body links to guidelines / contracts use the verbatim relative form
+  (`../../docs/guidelines/<group>/<name>.md`,
+  `../../docs/contracts/<name>.md`). The compress-time rewriter
+  resolves them to depth-aware single-up form — do not pre-rewrite in
+  source.
+* Skills do **not** declare `load_context:` / `load_context_eager:`;
+  those frontmatter keys are rule-only. If a skill needs to point at a
+  context, link to it inline (`[context-name](../../contexts/<area>/<file>.md)`).
+* Never write `.agent-src.uncompressed/` in any skill body link or
+  example — it ships into `.augment/skills/` and breaks consumer
+  resolution. See `rule-writing` § 3b for the canonical reference.
+
 ### Execution metadata (optional)
 
 Skills may declare an `execution` frontmatter block (`type`, `handler`,

package/.agent-src/skills/systematic-debugging/SKILL.md

@@ -2,6 +2,7 @@
 name: systematic-debugging
 description: "Use when hitting a bug, test failure, crash, or unexpected behavior — enforces reproduce → isolate → hypothesize → verify before any fix — even when the user just says 'this is broken' or 'quick fix'."
 source: package
+council_depth: deep
 ---
 
 # systematic-debugging
@@ -35,10 +36,28 @@ papers over an unknown cause is a regression waiting to happen.
 
 ```
 NO FIX WITHOUT ROOT CAUSE. NO ROOT CAUSE WITHOUT EVIDENCE.
+NO BUG MARKED FIXED WITHOUT A REGRESSION TEST.
 ```
 
 "I think it's probably X" is not evidence. A log line, a stack trace, a
-diff, a reproduced failure — those are evidence.
+diff, a reproduced failure — those are evidence. A green run after a
+manual edit is not a regression test — a test that fails without the fix
+and passes with it, is.
+
+## The 6-phase loop (the spine)
+
+Every debug session walks these six phases in order. Treat them as a
+checklist — tick each box before claiming the bug fixed:
+
+- [ ] **1. Reproduce** — bug triggers on demand, smallest possible setup _(Phase 1)_
+- [ ] **2. Minimize** — smallest failing case isolated, irrelevant context stripped _(Phase 1, step 2)_
+- [ ] **3. Hypothesize** — one testable theory stated in one sentence _(Phase 3)_
+- [ ] **4. Instrument** — log / breakpoint / trace at the boundary where expected ≠ actual _(Phase 2)_
+- [ ] **5. Fix** — single, minimal change targeting the root cause _(Phase 4, step 2)_
+- [ ] **6. Regression-test** — failing test added that catches the bug returning **(MANDATORY — no exception)** _(Phase 4, step 1 + Validation checklist)_
+
+Skipping a box (especially #2 or #6) is the single biggest cause of
+wasted debug time and re-opened bugs.
 
 ## Procedure
 
@@ -242,10 +261,11 @@ When reporting debug findings to the user:
 
 Before declaring a bug fixed:
 
+* [ ] **6-phase loop** — all six boxes (Reproduce → Minimize → Hypothesize → Instrument → Fix → Regression-test) ticked
 * [ ] The failure was reproduced before any code changed
 * [ ] The root cause is named explicitly, not "probably"
 * [ ] Evidence (log, trace, diff) supports the named root cause
-* [ ] A failing test reproducing the bug was added or updated
+* [ ] **Regression test added — MANDATORY**: a test that fails without the fix and passes with it. No exception. "Manual reproduction confirmed gone" is not a regression test
 * [ ] The fix is minimal and targets the root cause, not the symptom
 * [ ] The regression test now passes
 * [ ] Adjacent tests still pass

package/.agent-src/skills/technical-specification/SKILL.md

@@ -1,7 +1,8 @@
 ---
 name: technical-specification
-description: "Use when the user says "write a spec", "create RFC", or "document this decision". Writes technical specifications, RFCs, and ADRs with clear structure."
+description: "Use when the user says "write a spec", "create RFC", "write a PRD", or "document this decision". Writes technical specifications, PRDs, RFCs, and ADRs with clear structure."
 source: package
+council_depth: deep
 ---
 
 # technical-specification
@@ -10,6 +11,7 @@ source: package
 
 Use this skill when:
 - Writing a technical specification for a new feature or system
+- Writing a Product Requirements Document (PRD) when user pain leads and solution shape follows
 - Creating an architecture decision record (ADR)
 - Documenting a technical RFC (Request for Comments)
 - Planning a significant technical change that needs team review
@@ -69,6 +71,59 @@ For complex features or systems. Stored in `agents/features/` or module `agents/
 - {Links to related docs, tickets, or external resources}
 ```
 
+### Product Requirements Document (PRD)
+
+For features whose **shape is product-driven** rather than implementation-driven —
+when "what users get" matters more than "how the code is wired". Use a PRD
+when a Technical Specification would over-index on internals and under-index
+on user value. Stored in `agents/features/` next to the technical spec when
+both exist.
+
+```markdown
+# PRD: {Title}
+
+## Status
+{ Draft | In Review | Approved | Shipped | Parked }
+
+## Problem
+{The user-visible pain. One paragraph. Cite evidence — support tickets,
+analytics, user quotes — not assumptions.}
+
+## Success Criteria
+- {Measurable outcome with a number and a timeframe}
+- {Another measurable outcome}
+
+## Non-Goals
+- {What this PRD explicitly does NOT cover — protect scope}
+
+## User Stories
+- As a {role}, I want to {action}, so that {outcome}.
+- As a {role}, I want to {action}, so that {outcome}.
+
+## Major Modules
+{The 3-7 functional building blocks the feature decomposes into. One
+sentence each — what it does, not how. Implementation lives in the
+technical spec, not here.}
+
+- **{Module name}** — {one-sentence responsibility}
+- **{Module name}** — {one-sentence responsibility}
+
+## Open Questions
+- [ ] {Unresolved product question — pricing, permission, copy, edge case}
+
+## References
+- {Links to research, related PRDs, technical spec when it exists}
+```
+
+**PRD vs Technical Specification — when to pick which:**
+
+- **PRD first** when the user pain is clear but the solution shape is not
+  ("users can't share dashboards" → PRD scopes the problem; spec follows).
+- **Spec first** when the solution shape is clear but the implementation
+  is non-trivial ("rebuild auth on OAuth2" → spec leads; PRD often skipped).
+- **Both** when the feature is large enough that product and engineering
+  decisions belong in different artifacts.
+
 ### Architecture Decision Record (ADR)
 
 For significant technical decisions. Stored in `agents/decisions/`.
@@ -161,6 +216,8 @@ If a developer reads only this document, they should be able to build it.
 ## Auto-trigger keywords
 
 - technical spec
+- PRD
+- product requirements
 - RFC
 - ADR
 - architecture decision

package/.agent-src/skills/terraform/SKILL.md

@@ -106,8 +106,8 @@ Used for workers and schedulers:
 
 ### GitHub OIDC IAM role
 
-Each environment has a GitHub IAM role with:
-- OIDC trust policy (scoped to repo + environment)
+Each env has a GitHub IAM role with:
+- OIDC trust policy (scoped to repo + env)
 - Policies for ECR push/pull, ECS deployment, Secrets Manager read, CloudWatch logs
 
 ## Output format

package/.agent-src/skills/terragrunt/SKILL.md

@@ -12,7 +12,7 @@ Use this skill when working with Terragrunt configurations (`.hcl` files), manag
 
 ## Procedure: Write Terragrunt config
 
-1. Read the `root.hcl` in the target environment (`environments/pro/root.hcl` or `environments/sta/root.hcl`).
+1. Read the `root.hcl` in the target env (`environments/pro/root.hcl` or `environments/sta/root.hcl`).
 2. Check existing `terragrunt.hcl` files in sibling directories for patterns.
 3. Read the target module's `variables.tf` to understand required inputs.
 
@@ -36,7 +36,7 @@ environments/
 
 ## Root configuration (`root.hcl`)
 
-The root HCL defines shared settings for all modules in an environment:
+The root HCL defines shared settings for all modules in an env:
 
 ### Environment variables
 
@@ -50,9 +50,9 @@ locals {
 }
 ```
 
-- `.env.yaml` — committed, shared environment config
+- `.env.yaml` — committed, shared env config
 - `.env.local.yaml` — gitignored, local overrides (AWS profiles, etc.)
-- Real environment variables take precedence over file values.
+- Real env variables take precedence over file values.
 
 ### Remote state
 
@@ -101,7 +101,7 @@ Each module directory contains a `terragrunt.hcl` that:
 1. **Loads module-specific variables** from a YAML file
 2. **Includes the root config** for backend and providers
 3. **Points to the Terraform module source**
-4. **Declares dependencies** on other modules
+4. **Declares deps** on other modules
 5. **Passes inputs** by merging dependency outputs with local variables
 
 ### Example pattern
@@ -183,19 +183,19 @@ devbox run d           # terragrunt destroy
 
 ## Output format
 
-1. Terragrunt HCL files with DRY environment configuration
+1. Terragrunt HCL files with DRY env configuration
 2. Dependency graph and remote state references
 
 ## Auto-trigger keywords
 
 - Terragrunt
-- multi-environment
+- multi-env
 - DRY config
 - remote state
 
 ## Gotcha
 
-- Terragrunt `dependency` blocks create implicit ordering — circular dependencies cause cryptic errors.
+- Terragrunt `dependency` blocks create implicit ordering — circular deps cause cryptic errors.
 - Don't duplicate Terraform variables in terragrunt.hcl — use `inputs` to pass them through.
 - The model tends to hardcode values that should come from `include` blocks — use DRY patterns.