@event4u/agent-config 1.9.1

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

@@ -0,0 +1,291 @@
+---
+name: skill-writing
+description: "Use when deciding 'should this be a skill or a rule?', creating/improving/reviewing agent skills, SKILL.md frontmatter, or procedure sections — even without saying 'skill-writing'."
+source: project
+---
+
+# skill-writing
+
+## When to use
+
+Use this skill when:
+
+* Creating a new skill from scratch
+* Improving an existing skill
+* Reviewing skill quality
+* Deciding what belongs in a skill vs a rule
+
+Typical examples:
+
+* "Create a skill for X"
+* "This skill needs improvement"
+* "Should this be a skill or a rule?"
+
+Do not use this skill when:
+
+* Writing rules (rules are constraints, not workflows)
+* Writing commands (commands are direct invocations)
+
+## Goal
+
+* Create executable skills, not documentation
+* Ensure every skill answers: When? How? What output?
+* Prevent common mistakes: too broad, too generic, missing validation
+
+## Preconditions
+
+* Clear understanding of the intended task
+* Distinction: rules = always apply, skills = triggered workflows
+* Access to a skill template or existing reference skill
+
+## Decision matrix: What goes where?
+
+Before creating anything, classify the content:
+
+| If the content is... | Then it is... | Action |
+|---|---|---|
+| An always-true constraint ("never X", "always Y") | **Rule** | Create/update `.augment/rules/` |
+| A step-by-step workflow with decisions and validation | **Skill** | Create/update `.augment/skills/` |
+| A coding convention or reference material | **Guideline** | Create/update `.augment/guidelines/` |
+| Baseline model knowledge (how jq works, what `docker exec` does) | **Nothing** | Do not create anything |
+| Simple tool usage without complex workflow | **Nothing** | Do not create anything |
+| Already covered by an existing skill/rule/guideline | **Update** | Extend the existing file |
+
+### The critical test
+
+Ask: **"Does the model need this to do its job correctly?"**
+
+* If the model already knows it → **Nothing**
+* If the model knows it but does it wrong in THIS project → **Rule or Guideline**
+* If the model needs a multi-step workflow to get it right → **Skill**
+
+### When "Nothing" is the right answer
+
+Do NOT create a skill or rule for:
+
+* Standard tool usage (jq, grep, docker exec, git commands)
+* Framework basics the model already knows
+* Single-command operations without decision logic
+* Knowledge that belongs in a skill's procedure as a step, not as its own skill
+
+### Size and structure hints
+
+→ See `guidelines/agent-infra/size-and-scope.md` for full limits.
+
+* Target: 300–900 words. Review for split above 1200 words. Strongly consider split above 1500 words.
+* If multiple workflows exist → split into multiple skills
+* If two skills overlap heavily → merge
+* If a skill becomes "read the guideline" → it lost its purpose, restore the workflow
+
+## Procedure
+
+### 0. Inspect, then run the Drafting Protocol
+
+Before writing, **inspect** the landscape: grep
+`.agent-src.uncompressed/skills/` and `rules/` for duplicates or
+near-matches, and **analyze** 1–2 gold-standard peers (e.g. `pest-testing`,
+`php-coder`) to anchor shape and tone. If requirements are unclear or
+incomplete, stop and ask — do not assume.
+
+Then run the Understand → Research → Draft sequence from the
+[`artifact-drafting-protocol`](../../rules/artifact-drafting-protocol.md)
+rule. Skip only on explicit *"just do it"* bypass or trivial edits
+(typo, link, single-line clarification).
+
+### 1. Define the trigger
+
+Write "When to use" first. This is the in-body trigger — it documents the
+workflow's entry conditions for anyone reading the skill.
+
+Good:
+Use when creating Laravel middleware for request filtering
+
+Bad:
+Use when working with Laravel
+
+### 1b. Write a pushy frontmatter description
+
+The `description:` field is what Claude reads at routing time. Polite or
+generic descriptions cause **undertriggering**. Normative source:
+`skill-quality` rule § *Description Triggering*.
+
+Three rules: name 2+ triggers (domains, symptoms, user phrasing), end with
+`... even if they don't explicitly ask for \`<skill-name>\`.`, and stay
+**≤ 200 characters** (`skill_linter.py` warns `description_too_long` above
+that). When trimming to fit, drop adjectives or the second example phrasing
+before you drop a trigger class or the `even if ...` tail.
+
+Canonical before/after (2026-04-21 audit baseline):
+
+```yaml
+# Bad (138 chars, polite, single trigger class):
+description: "Use when writing Playwright E2E tests — browser automation,
+  visual regression testing, Page Objects, fixtures, and reliable test
+  patterns."
+
+# Good (pushy, second trigger class, explicit tail):
+description: "Use when writing Playwright E2E tests — locators, assertions,
+  Page Objects, fixtures, CI, and flaky test prevention — even if the user
+  doesn't say Playwright."
+```
+
+The *good* version routes correctly on *"my E2E keeps flaking on CI"*
+without naming Playwright. Run `python3 scripts/audit_skill_descriptions.py`
+after writing; if flagged `too-short` or `no-trigger-prefix`, rewrite
+before commit.
+
+When iterating on phrasing with the user (e.g. "make this pushier",
+"will this ever fire"), delegate to the
+[`description-assist`](../description-assist/SKILL.md) skill — it runs the
+approval-gated propose / pick loop with at most two rounds.
+
+### 1c. Propose a trigger-eval stub (new skills only)
+
+When creating a new skill, propose a stub
+`.agent-src.uncompressed/skills/{name}/evals/triggers.json` before writing
+the body. Draw the queries from Phase A of the drafting protocol (the
+user's "should trigger" and "must not trigger" answers).
+
+Stub shape — 5 should-trigger + 5 should-not-trigger queries, first-person,
+single-sentence, **no leakage of the skill name** in the queries:
+
+```json
+{
+  "skill": "{name}",
+  "description": "5 should-trigger + 5 should-not-trigger queries. No query mentions '{name}' directly. Near-misses share domain vocabulary without being the actual task.",
+  "queries": [
+    {"q": "<phrasing from user Phase A that MUST route here>", "trigger": true},
+    {"q": "<another should-trigger phrasing>", "trigger": true},
+    {"q": "<...3 more>", "trigger": true},
+    {"q": "<near-miss sharing vocabulary but different task>", "trigger": false},
+    {"q": "<another near-miss>", "trigger": false},
+    {"q": "<...3 more>", "trigger": false}
+  ]
+}
+```
+
+Present the stub as a numbered-options prompt (per `user-interaction`):
+
+```
+> 1. Accept stub as drafted — commit alongside the skill
+> 2. Edit queries before commit
+> 3. Skip evals for now — create later
+```
+
+Nothing is committed without the user's pick. If the user picks *skip*,
+record it in the commit message (`Eval stub: deferred`). See
+[`road-to-trigger-evals.md`](../../../agents/roadmaps/archive/road-to-trigger-evals.md)
+Phase 1 for the runner and expected format; peer examples:
+`php-coder/evals/triggers.json`, `eloquent/evals/triggers.json`,
+`skill-writing/evals/triggers.json`.
+
+Rules / commands / guidelines do **not** get eval stubs — only skills
+route through the top-level catalogue.
+
+### 2. Write the procedure
+
+Use numbered, verifiable steps.
+
+Good:
+
+1. Check if middleware exists
+2. Create with artisan command
+3. Implement logic
+4. Register in route or kernel
+
+Bad:
+
+1. Create middleware
+2. Add logic
+
+### 3. Add validation
+
+End with concrete validation.
+
+Good:
+
+* Route returns expected status
+* Appears in route list
+* No static analysis errors
+
+Bad:
+
+* Vague statements like "see if outcome is correct" (no concrete command or assertion)
+
+### 4. Add safe/unsafe example
+
+Show minimal contrast.
+
+Good:
+
+* Typed middleware, correctly registered
+
+Bad:
+
+* Business logic inside middleware
+
+### 5. Define output format
+
+Control response structure.
+
+Example:
+
+1. Code snippet
+2. Registration location
+3. Gotcha (if relevant)
+
+### 6. Validate against quality checklist
+
+* K1: Description is a trigger ("Use when...")
+* K2: Not over-defined
+* K3: No obvious content
+* K4: Contains gotchas
+* K5: Has Output format (numbered, 2-4 deliverables)
+* K6: Not pointer-only (executable without opening guidelines)
+* K7: Created with analysis (not blind, expected behavior defined)
+* Size: Within limits (see size-and-scope guideline)
+
+## Output format
+
+1. Complete SKILL.md file
+2. No explanations outside the file
+3. Fully copyable
+4. No empty sections
+
+## Core rules
+
+* Skills are executable thinking processes
+* Always include: When to use, Procedure, Output format, Gotchas, Do NOT
+* Steps must be verifiable
+* Validation must be concrete
+* One skill = one job
+
+### Execution metadata (optional)
+
+Skills may declare an `execution` frontmatter block (`type`, `handler`,
+`timeout_seconds`, `safety_mode`, `allowed_tools`). Default is `manual`
+(instructional only). See `guidelines/agent-infra/runtime-layer.md` for
+the full specification and `assisted` / `automated` semantics.
+
+### When to create a `project-analysis-*` skill
+
+Only if the framework has its own lifecycle producing unique debugging
+patterns that `project-analysis-core` cannot explain (e.g. Laravel,
+Symfony, Express, React, Next.js). **Not** for Tailwind, CSS frameworks,
+utility libs, or simple state managers.
+
+## Gotchas
+
+* Writing documentation instead of executable steps
+* Skipping validation — every Procedure MUST end with a concrete verify step
+* Including baseline knowledge the model already has
+* Description too long or not a trigger
+* Renaming a heading to "Procedure:" without numbered steps or `###` sub-headings
+* **Always run `python3 scripts/skill_linter.py` before saving — 0 FAIL required**
+
+## Do NOT
+
+* Write documentation-style, pointer-only, or too-broad skills ("Laravel skill")
+* Skip Procedure or use vague validation
+* Exceed size limits (see `guidelines/agent-infra/size-and-scope.md`)
+* Duplicate rules

package/.agent-src/skills/skill-writing/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "skill": "skill-writing",
+  "description": "5 should-trigger + 5 should-not-trigger queries. No query mentions 'skill-writing' directly. Near-misses share 'skill' vocabulary but route to skill-management, lint-skills, or unrelated skills.",
+  "queries": [
+    {"q": "let's create a skill for database migrations", "trigger": true},
+    {"q": "this SKILL.md feels weak, can you tighten it?", "trigger": true},
+    {"q": "should this be a skill or a rule?", "trigger": true},
+    {"q": "the description says 'covers various things' — fix it", "trigger": true},
+    {"q": "add a proper procedure section to the graphql skill", "trigger": true},
+    {"q": "refactor my PHP controller", "trigger": false},
+    {"q": "run the skill linter on my branch", "trigger": false},
+    {"q": "compress this SKILL.md to half its length", "trigger": false},
+    {"q": "which skill handles git workflow?", "trigger": false},
+    {"q": "write a CONTRIBUTING.md for this repo", "trigger": false}
+  ]
+}

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

@@ -0,0 +1,74 @@
+---
+name: sql-writing
+description: "Use when writing raw SQL — MariaDB/MySQL syntax, parameterization, raw migrations, seeders with `DB::statement` — even when the user just pastes a query and asks 'why is this slow' without naming SQL."
+source: package
+---
+
+# sql
+
+## When to use
+
+Use when writing or reviewing raw SQL queries, migrations with raw statements, or seeders with raw SQL.
+
+Do NOT use when:
+- Eloquent/Query Builder queries (use `eloquent` or `database` skill)
+- Schema design (use `database` skill)
+
+## Procedure: Write raw SQL
+
+1. **Choose approach** — Use query builder when possible. Raw SQL only when query builder can't express the query.
+2. **Parameterize** — Every variable must use `?` binding or named `:param`. Never interpolate PHP variables into SQL strings.
+3. **Use MariaDB syntax** — Not PostgreSQL or MSSQL. Check `php/sql.md` for MariaDB-specific patterns.
+4. **Verify** — Run EXPLAIN on complex queries. Check that no PHP interpolation (`"$var"`, `'{$var}'`) appears in SQL.
+
+```
+NEVER build SQL strings with PHP variable interpolation or concatenation.
+ALWAYS use parameterized queries or query builder.
+```
+
+## Conventions
+
+→ See guideline `php/sql.md` for parameterization patterns, common mistakes, MariaDB syntax reference.
+
+## Quick reference
+
+```php
+// ✅ Safe
+DB::select('SELECT * FROM users WHERE email = ?', [$email]);
+
+// ❌ SQL injection
+DB::select("SELECT * FROM users WHERE email = '{$email}'");
+```
+
+### Validate
+
+1. Verify every variable in SQL uses parameter binding (`?` or named `:param`).
+2. Confirm MariaDB/MySQL syntax — not PostgreSQL or MSSQL.
+3. Run EXPLAIN on complex queries to check index usage.
+4. Check that no PHP variable interpolation (`"$var"`, `'{$var}'`) appears in SQL strings.
+
+## Output format
+
+1. Parameterized SQL query using MariaDB/MySQL syntax
+2. EXPLAIN output for performance-critical queries
+
+## Gotcha
+
+- MariaDB and MySQL have subtle syntax differences.
+- The model writes `$variable` in SQL strings instead of `?` placeholders.
+- `GROUP BY` with `ONLY_FULL_GROUP_BY` requires all non-aggregated columns.
+- Use SQL types (`NULL`, `1/0`, `JSON_ARRAY()`) — not PHP equivalents.
+
+## Do NOT
+
+- Do NOT interpolate PHP variables into SQL strings — always parameterize.
+- Do NOT use PHP syntax (arrays, booleans, null) in raw SQL — use SQL equivalents.
+- Do NOT write raw SQL when the query builder can express the same thing clearly.
+
+## Auto-trigger keywords
+
+- raw SQL
+- SQL query
+- parameterized query
+- MariaDB syntax
+- SQL injection

package/.agent-src/skills/subagent-orchestration/SKILL.md

@@ -0,0 +1,190 @@
+---
+name: subagent-orchestration
+description: "Use when orchestrating implementer/judge subagents — five modes (do-and-judge, do-in-steps, do-in-parallel, do-competitively, judge-with-debate) — models from .agent-settings.yml."
+source: package
+---
+
+# subagent-orchestration
+
+## When to use
+
+* A task benefits from a second agent reviewing before apply — safety,
+  regression risk, cross-layer change
+* A plan has clear, independent slices that can be worked on in
+  parallel — unrelated bug fixes, multi-file migrations
+* A solution space is broad enough that multiple candidate
+  implementations are worth producing and comparing
+* The user explicitly asks "have a second agent review this" or "try
+  this two different ways"
+
+Do NOT use when:
+
+* The task is small and the overhead of a second agent exceeds the
+  value — single file, one-liner fix
+* The user is still exploring — route to brainstorming / planning
+  skills first
+* Budget is the constraint — each subagent call multiplies cost
+* The implementer and judge would be the same model on the same
+  context — no added signal
+
+## Goal
+
+Land a verified change (or set of changes) by combining implementer
+and judge subagents in a mode chosen deliberately, with model pairing
+read from `.agent-settings.yml` — never silently improvised.
+
+## The Iron Law
+
+```
+NO JUDGE ON THE SAME MODEL AS THE IMPLEMENTER ON THE SAME CONTEXT.
+```
+
+Same model + same context = same blind spots. The whole point of a
+judge is a fresh pair of eyes. If `.agent-settings.yml` resolves to
+identical implementer and judge models, surface the mismatch before
+running — do not silently continue.
+
+## The five modes
+
+Each mode has a decision row: when to use, when not, and the expected
+model pairing. Defaults come from
+[`subagent-configuration`](../../contexts/subagent-configuration.md).
+
+### 1. do-and-judge
+
+Implementer produces a diff; judge reviews; loop applies, revises, or
+hands off. Hard ceiling: **two revision cycles**, then stop and hand
+back to the user.
+
+| When to use | When not | Model pairing |
+|---|---|---|
+| Single-change task with non-trivial risk | Tiny fix, or spike/exploration | implementer = session; judge = one tier up |
+
+### 2. do-in-steps
+
+Plan is split into N steps; judge runs **between** steps. A step that
+fails judgment is revised before the next step starts. Used for
+multi-file changes where a mid-plan mistake would cascade.
+
+| When to use | When not | Model pairing |
+|---|---|---|
+| Multi-step plan with ordered dependencies | Single-step change, or when steps are independent (use `do-in-parallel`) | implementer = session; judge = one tier up |
+
+### 3. do-in-parallel
+
+Independent slices run concurrently. No judge per slice — judge runs
+once on the aggregated result. Parallelism capped by
+`subagents.max_parallel` in `.agent-settings.yml`.
+
+| When to use | When not | Model pairing |
+|---|---|---|
+| Independent slices (different files, non-overlapping) | Any slice touches shared state | implementer = session; judge = one tier up, run once |
+
+### 4. do-competitively
+
+Multiple implementers produce candidate diffs for the **same** slice.
+Judge picks the winner and rejects the losers. Expensive — use only
+when the solution space is genuinely broad.
+
+| When to use | When not | Model pairing |
+|---|---|---|
+| Broad solution space (algorithm choice, API shape) | Well-defined problem with one good answer | implementers = same tier (≥2 instances); judge = one tier up |
+
+### 5. judge-with-debate
+
+Two judges each produce a verdict; a meta-judge reconciles
+disagreements. Used for high-stakes changes (security, data
+migration, public API) where a single judge is too easy to fool.
+
+| When to use | When not | Model pairing |
+|---|---|---|
+| Security, data integrity, public API change | Routine internal refactor | judges = same tier (2x); meta-judge = one tier up |
+
+## Procedure
+
+### 1. Inspect the task shape
+
+Before picking a mode, check:
+
+* Is the task single-change or multi-step?
+* Are slices truly independent, or do they share state?
+* Is solution space narrow (one right answer) or broad (trade-offs)?
+* Is risk high enough to justify debate?
+
+Do not pick a mode until these four questions have concrete answers.
+
+### 2. Resolve models
+
+Read `.agent-settings.yml`:
+
+* `subagents.implementer_model` → empty = session model
+* `subagents.judge_model` → empty = one tier above implementer
+* `subagents.max_parallel` → integer, default 3
+
+If resolution produces an unknown alias or implementer == judge in the
+same context, **stop** and report. Do not improvise.
+
+### 3. Pick the mode
+
+Match task shape to one of the five modes. When two modes could fit,
+prefer the cheaper one (`do-and-judge` < `do-in-steps` < `do-in-parallel`
+< `do-competitively` < `judge-with-debate`).
+
+### 4. Dispatch
+
+Hand off to the matching command:
+
+* `do-and-judge` → [`/do-and-judge`](../../commands/do-and-judge.md)
+* `do-in-steps` → [`/do-in-steps`](../../commands/do-in-steps.md)
+* `judge` (standalone) → [`/judge`](../../commands/judge.md)
+
+Modes without a dedicated command (`do-in-parallel`,
+`do-competitively`, `judge-with-debate`) are orchestrated inline via
+the skill — describe the dispatch explicitly in chat so the user can
+follow it.
+
+### 5. Report
+
+Follow the output format below. Never merge a diff without reporting
+the judge verdict.
+
+## Gotcha
+
+* **Identical model both sides** — same blind spots. The Iron Law
+  blocks this before dispatch.
+* **Judge drifts off-task** — judge reviews *the diff*, not the task
+  description. Always attach the diff to the judge prompt.
+* **Infinite revision loop** — hard ceiling of two revisions in
+  `do-and-judge`; then hand back to the user.
+* **`do-in-parallel` on overlapping slices** — race conditions,
+  conflicting diffs. Verify independence before splitting.
+* **Cost surprise on `do-competitively`** — N implementers + 1 judge =
+  N+1 subagent calls for one slice. Confirm budget before dispatch.
+
+## Output format
+
+1. **Mode chosen** — one of the five, with the one-line reason
+2. **Model pairing** — implementer model / judge model (resolved)
+3. **Verdict** — applied / revised / handed back
+4. **Evidence** — diff summary, test output, or judge transcript
+5. **Next step** — what the user does now (review PR, pick winner, etc.)
+
+## Do NOT
+
+* NEVER run implementer and judge on the same model and same context
+* NEVER exceed the two-revision ceiling in `do-and-judge` without user
+  consent
+* NEVER run `do-in-parallel` on slices that touch shared files
+* NEVER apply a diff that the judge rejected without explicit user
+  override
+* NEVER silently resolve an unknown model alias to a fallback
+
+## Handover
+
+| Task                                 | Skill / command                      |
+|--------------------------------------|--------------------------------------|
+| Configuration reference              | [`subagent-configuration`](../../contexts/subagent-configuration.md) |
+| Do-and-judge loop                    | [`/do-and-judge`](../../commands/do-and-judge.md) |
+| Stepwise plan with judge gates       | [`/do-in-steps`](../../commands/do-in-steps.md) |
+| Standalone judge on an existing diff | [`/judge`](../../commands/judge.md)  |
+| Verifying completeness               | [`verify-before-complete`](../verify-before-complete/SKILL.md) |