@event4u/agent-config 2.11.0 → 2.13.0

package/.agent-src/skills/ai-council/SKILL.md

@@ -292,6 +292,65 @@ NEVER ships the host verdict as council output. Provider attribution
 stays visible in the per-member sections; host verdicts stay
 attributed to the host.
 
+## Synthesis templates (lens-aware)
+
+The **Convergence / Divergence** slot in `council:render` output is
+populated with a lens-specific synthesis prompt. The host agent reads
+this prompt and writes the summary in the shape it dictates. The five
+templates live in `scripts/ai_council/prompts.py::_SYNTHESIS_TABLE`
+and are exposed via `synthesis_template(mode)`.
+
+**R4 Q4 split** — decision lenses get a structured Karpathy-style
+template; creative lenses stay open-ended prose (bare slot):
+
+| Lens | Class | Synthesis sections |
+|---|---|---|
+| `default` | decision | Agreement · Clashes · Blind spots · Recommendation · Next step |
+| `pr` | decision | Consensus · Conflicts · Must-fix before merge · Recommendation |
+| `analysis` | decision | Top-10 by consensus · Supporting · Outliers |
+| `design` | creative | *(no template — open prose passthrough)* |
+| `optimize` | creative | *(no template — open prose passthrough)* |
+
+Input modes (`prompt` / `roadmap` / `diff` / `files`) inherit the
+`default` decision template — they are bundling shapes, not lenses.
+
+**Source citations:**
+* Template shape — Round 2 council verdict
+  (`agents/council-sessions/2026-05-14-ai-council-redesign/round-1.md`,
+  Opus's lens-adaptive synthesis proposal).
+* Decision/creative split — Round 4 Q4 verdict
+  (`agents/council-sessions/2026-05-14-ai-council-redesign/round-3-responses.json`).
+  R4 reframed `optimize` as creative because perf trade-offs resist
+  pre-templated shape — Performance-wins / Trade-offs /
+  Implementation-order is too rigid for the variety of optimize-lens
+  artefacts. R4 reframed `design` for the same reason — design
+  critiques are inherently narrative.
+
+### `--prose-synthesis` escape hatch (R4 Q4)
+
+Both `council:run` and `council:render` accept symmetric escape-hatch
+flags on top of the lens table:
+
+* `--prose-synthesis` — force creative-lens passthrough (bare slot)
+  regardless of lens. Use when the user on `default`/`pr`/`analysis`
+  prefers a narrative recommendation over the structured template.
+* `--no-prose-synthesis` — force the `default` structured template
+  even on a creative lens. Use when a `design` or `optimize` artefact
+  has a one-shot need for Karpathy-style structure.
+
+The flag is mutually exclusive — picking one disables the other on
+the same invocation. When `council:run` records either flag in the
+output JSON, `council:render` honours it unless the renderer is
+called with an explicit flag of its own.
+
+### Renderer lens resolution
+
+`council:render <responses.json>` resolves the active lens in this
+order: explicit `--prompt-mode` flag > `prompt_mode` field in the
+payload > `mode` field in the payload > `None` (default decision
+template). The `--prose-synthesis` / `--no-prose-synthesis` flag
+overrides the table regardless of how the lens resolved.
+
 ## Do NOT
 
 - Do NOT paraphrase council output into the host agent's voice — strip
@@ -435,8 +494,8 @@ prompt as `<original artefact> + <prior round, anonymised>` so each
 member can refine, agree, or push back on the previous critique
 without seeing which provider produced which point.
 
-The default round count comes from `ai_council.min_rounds` in
-`.agent-settings.yml` (default `2` so members critique each other
+The default round count comes from `defaults.min_rounds` in
+`agents/.ai-council.yml` (default `2` so members critique each other
 at least once before convergence). The host agent does **not** ask
 "how many rounds?" when the requested count is `<= min_rounds` —
 the settings owner already made that decision. Ask only when a
@@ -516,6 +575,121 @@ internal "more feedback" follow-up loop (1 / 2 / 3 menu) is
 **inside** a single member's chat thread and is orthogonal to the
 orchestrator-level rounds.
 
+### `/council debate` sub-command (progressive disclosure)
+
+`/council debate <artefact> [--rounds N] [--continue-as-debate <session>]`
+runs an **interactive** multi-round critique with a confirmation gate
+between every round so the user can stop the spend at any point.
+
+| Property | Behaviour |
+|---|---|
+| Round flow | Same orchestrator as `rounds:N` (`run_debate()`), but each round prints its responses then pauses on a y/n prompt before launching the next round. |
+| Cost gate | After every round the CLI prints `Spent so far: $X · Next round: ~$Y · Cap: $Z`. `n` exits cleanly with partial results; `y` continues. |
+| Hard cap | If the projected next-round cost would breach `max_total_usd`, `run_debate()` raises `DebateCapExceeded` and the CLI exits with the partial transcript. No silent overrun. |
+| `--continue-as-debate` | Seeds round 1 from an existing `/council default` (or analysis lens) session. No round-1 API calls are billed; round 2+ run normally. Member list must match. |
+| Session files | One file per round under `agents/council-sessions/<slug>/debate-round-NN.md`. |
+| Anonymisation | Identical to `rounds:N`. The continue-as-debate path also anonymises the seeded round-1 responses when building the round-2 prompt. |
+
+Use this when the artefact is genuinely contentious and the user
+wants to control depth interactively. For a fire-and-forget
+multi-round run, prefer `consult(..., rounds=N)` or `--rounds N` on
+`/council default`.
+
+
+## Karpathy peer-review (opt-in)
+
+After the final deliberation round, an optional **anonymous peer-review
+pass** lets each member critique the *other* members' responses for
+blind spots before synthesis. Inspired by Andrej Karpathy's "ask the
+strongest models to review each other anonymously" pattern; see his
+[talks / threads on inter-model critique](https://karpathy.ai/) and the
+internal verdict in
+`agents/council-sessions/2026-05-14-ai-council-redesign/round-2.md`
+(R2 split: one approve-as-flag, one reject-as-default → opt-in only).
+
+Pipeline order when every feature is active:
+
+```
+deliberation rounds → peer-review → consensus-scoring → synthesis
+```
+
+Activation — two equivalent paths:
+
+* CLI: `--peer-review` on `council:estimate` or `council:run`.
+* Config: `ai_council.peer_review.enabled: true` in
+  `agents/.ai-council.yml`. Default is `false`.
+
+Mechanics:
+
+1. The final deliberation round's outputs are anonymised into
+   `Response-A`, `Response-B`, … in stable input order. Provider /
+   model identity is stripped (Iron-Law neutrality holds); empty or
+   errored deliberation responses are skipped.
+2. Each member receives an N−1 view (its own response filtered out)
+   plus the Karpathy prompt: *strongest response*, *weakest blind
+   spot*, *what did everyone miss*, *refinement*.
+3. The N critiques flow back into synthesis through a
+   "Peer-Review-Surfaced Blind Spots" addendum on the lens template.
+4. **Advisor preserve-persona (R4 Q3, hard-coded):** when the
+   deliberation was an advisor-mode run (Phase 6), anonymisation
+   strips provider identity but **preserves the advisor persona
+   label**. Peer-review renders as `Response A (Contrarian)`, never
+   `Response A (Anthropic Opus)`. Plain-member runs strip identity
+   entirely.
+
+Cost — adds exactly N billable calls (one per member) at the same
+per-call cost as a deliberation call. The `council:estimate` table
+surfaces the delta as a `+peer-review: +N calls (~+$X)` row.
+
+Needs ≥ 2 distinct deliberation outputs; below that the round is a
+no-op and nothing extra is billed. Self-review is structurally
+impossible — a member never sees its own response.
+
+## Thinking-style advisors (replace-mode)
+
+Phase 6 introduces five **advisor personas** the council adopts in
+*replace-mode*: an enabled advisor substitutes its bound member's
+plain call with the same provider running the advisor's persona
+prompt. Total call count stays the same — only the system prompt
+swaps.
+
+| Advisor | Default bound member | Focus |
+|---|---|---|
+| **Contrarian** | `anthropic` | strongest counterargument, hidden assumptions |
+| **First-Principles** | `anthropic` | strip metaphor, derive from physics / math / cost |
+| **Expansionist** | `openai` | adjacent opportunities, second-order effects |
+| **Outsider** | `openai` | naive-but-sharp questions, beginner's-mind probes |
+| **Executor** | `anthropic` | what ships this quarter, what blocks delivery |
+
+Activation — edit `agents/.ai-council.yml` and flip the advisor's
+`enabled: true`. Optional `model: <name>` overrides the bound
+member's default model. An advisor referencing a disabled member
+fails closed at config load — never silently skipped.
+
+```yaml
+advisors:
+  contrarian:
+    enabled: true        # ← swap anthropic's plain call for contrarian
+    member: anthropic
+    # model: claude-opus-4   # optional pin
+```
+
+`council:estimate` surfaces every active swap on a dedicated line
+above the cost table:
+
+```
+council:estimate · mode=prompt · members=2 (billable=2)
+  advisor: Contrarian on anthropic via claude-sonnet-4-5
+anthropic/claude-sonnet-4-5: ~991 in + 256 out  =  $0.0068
+openai/gpt-4o: ~208 in + 256 out  =  $0.0031
+```
+
+Cost-bounded — replace-mode never adds calls. The persona prompt is
+larger than plain (~1k extra input tokens per swap); output tokens
+and call count are unaffected. Peer-review preserves the advisor
+label while stripping provider identity (`Response A (Contrarian)`).
+Two enabled advisors on the same member is a config error.
+
 ## See also
 
 - `/council` command — the user-facing entry point.
@@ -523,6 +697,10 @@ orchestrator-level rounds.
   network, no spend, but no diversity of weights either).
 - `scripts/ai_council/prompts.py` — neutrality preamble + per-mode
   system prompts.
+- `scripts/ai_council/advisors.py` — replace-mode planning + persona
+  resolution.
 - `scripts/ai_council/bundler.py` — redaction pattern set + size
   guard.
 - `docs/customization.md` § `ai_council.*` — settings reference.
+- `docs/contracts/ai-council-config.md` § advisors — schema + precedence
+  contract.

package/.agent-src/skills/canvas-design/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: canvas-design
+description: "Use when creating static visual art — posters, marketing visuals, brand assets, PDF/PNG design pieces — even if the user just says 'design a poster' or 'mach uns ein Visual'."
+source: package
+domain: product
+---
+
+# canvas-design
+
+## When to use
+
+Use when:
+
+* User asks for a poster, marketing visual, brand asset, social-media graphic, cover art
+* Output is a static `.pdf` or `.png` design piece (not a UI mockup, not a wireframe)
+* The deliverable is the visual artifact itself
+
+Do NOT use when:
+
+* Designing a UI component or app screen → `fe-design`, `ui-component-architect`, `react-shadcn-ui`, `blade-ui`, `flux`
+* Tailwind / shadcn / Flux component styling → `tailwind-engineer`
+* Brand voice / tone definition → `voice-and-tone-design`
+* Release announcement copy → `release-comms`
+
+## Goal
+
+Produce one finished visual artifact (`.pdf` or `.png`) backed by an original design philosophy. Both files ship together.
+
+The work emphasizes: visual expression over text · original direction (no artist mimicry) · composition that looks deliberated, not generated.
+
+## Preconditions
+
+* Brief from user (theme, intent, occasion, target medium, size constraint)
+* Output directory: `agents/design-assets/{slug}/` — create if missing
+* Image-generation tooling available (Python with Pillow / matplotlib / cairo, SVG → PNG conversion, or whatever the environment ships)
+
+## Procedure
+
+### 1. Brief intake
+
+One numbered-options block surfaces: theme / occasion · target medium + dimensions (web 1200×630? print A3? square 1080×1080?) · color & mood direction · hard constraints (logo required? color to avoid?) · single page or series.
+
+If the brief says "in the style of [living artist]", flag the copyright risk and propose an original direction.
+
+### 2. Design philosophy
+
+Author `agents/design-assets/{slug}/philosophy.md` — 4–6 paragraphs naming:
+
+* **Movement name** — 1–2 words ("Chromatic Silence", "Brutalist Joy", "Analog Meditation")
+* **Visual language** — how the philosophy manifests through space, form, color, scale, composition, rhythm
+* **Text role** — sparse, accent only; never paragraphs
+* **Craftsmanship anchor** — visible deliberation, not template polish
+
+Stay aesthetically specific but leave interpretive room for the canvas execution.
+
+### 3. Subtle conceptual thread
+
+Identify a single niche reference embedded in the work — not announced, woven into form / color / composition. A jazz musician quoting another song: those who know catch it, others enjoy the music.
+
+Document it in `philosophy.md` under `## Subtle reference`.
+
+### 4. Canvas execution
+
+Produce `agents/design-assets/{slug}/{slug}.{pdf|png}`:
+
+1. Pick the execution tool (Pillow, matplotlib, SVG, or framework-native)
+2. Limited palette — 2–5 colors, intentional and cohesive
+3. Geometric or organic forms per philosophy
+4. Text — sparse, design-forward, integrated as visual element; never overlapping, never falling off canvas
+5. Margins — every element contained, breathing room
+6. Repeating patterns, layered elements, systematic markers as the philosophy permits
+
+### 5. Refinement pass
+
+After the first render, **do not add more graphics**. Refine what exists:
+
+* Tighten composition cohesion
+* Adjust spacing, alignment, color balance
+* Replace fonts if they fight the philosophy
+* Remove any element that doesn't earn its place
+
+Render the refined version. Overwrite the artifact.
+
+### 6. Multi-page (optional)
+
+If the user requests a series, treat each page as a story beat — distinct but philosophically continuous. Bundle as a multi-page PDF or numbered PNGs (`{slug}-01.png`, `{slug}-02.png`, …).
+
+### 7. Validation
+
+* `philosophy.md` exists with movement name + 4–6 paragraphs + subtle-reference section
+* Artifact file exists at the expected path
+* Open and verify: nothing falls off canvas, no overlapping text, palette ≤ 5 distinct colors, every element has margin
+* Original work — no traceable artist-style copy
+
+## Output format
+
+1. `agents/design-assets/{slug}/philosophy.md`
+2. `agents/design-assets/{slug}/{slug}.{pdf|png}` (or numbered series for multi-page)
+3. One concluding line stating both file paths
+
+## Gotcha
+
+* **No artist mimicry** — copying a living artist's signature style is copyright risk and breaks the original-work mandate. Propose an original direction.
+* **Text discipline** — most pieces fail because text creeps in as paragraphs. Words are visual accents, not explanation.
+* **One canvas** — single page unless multi-page is explicitly requested.
+* **Font availability** — the environment may not ship your target font. Pick a fallback before render time, or download into the working dir first.
+* **Output location** — always `agents/design-assets/{slug}/`. Never write binary artifacts to the repo root or to source-of-truth dirs.
+* **Refinement loop is real** — first render is the draft, not the deliverable.
+
+## Frugality Standards
+
+Apply the [Frugality Charter](../../contexts/contracts/frugality-charter.md).
+
+* Per the default-terse rule, `philosophy.md` opens with the movement name — no "In this document I will describe …" frame.
+* Per the cheap-question check, numbered-options blocks only at brief intake (where consequences differ).
+* Per the post-action summary suppression, ship the files; skip an "## Artist statement" wrapper.
+
+**Pre-save self-check:**
+
+1. Does `philosophy.md` carry filler superlatives ("absolute pinnacle", "transcendent")?
+2. Does the canvas include explanatory text instead of visual-accent text?
+3. Are more than 5 distinct colors present without justification in the philosophy?
+4. Is the subtle reference announced explicitly in the visual, breaking the "those who know" principle?
+
+## Do NOT
+
+* Copy a living artist's signature visual style
+* Generate cartoony / amateur / template-store output
+* Add paragraphs of text — visuals communicate, words accent
+* Skip the philosophy file — the artifact without it is just an image
+* Skip the refinement pass
+* Write binary artifacts to the repo root or to source-of-truth dirs

package/.agent-src/skills/canvas-design/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "skill": "canvas-design",
+  "description": "5 should-trigger + 5 should-not-trigger queries. Should-trigger asks for static visual art (poster / cover / marketing visual). Should-not-trigger near-misses share design vocabulary but route elsewhere (fe-design, tailwind-engineer, voice-and-tone-design, release-comms).",
+  "queries": [
+    {"q": "Need a launch poster for next week's release announcement — A3 print, minimal style", "trigger": true},
+    {"q": "Design us a social-media visual for the v3.0 release, 1080x1080 for IG", "trigger": true},
+    {"q": "Mach mir bitte ein Cover-Bild für den Talk nächste Woche, 1200x630 fürs Web", "trigger": true},
+    {"q": "We want a single-page PDF brand visual for the conference booth handout", "trigger": true},
+    {"q": "Build a minimalist poster for the team-offsite invitation, square format", "trigger": true},
+    {"q": "Design a new component library for our app — buttons, inputs, cards", "trigger": false},
+    {"q": "What color palette should we standardize on in tailwind.config.js?", "trigger": false},
+    {"q": "Refactor the brand voice doc — make it less corporate and more direct", "trigger": false},
+    {"q": "Draft the release announcement blog post for the v3.0 launch", "trigger": false},
+    {"q": "Help me wireframe the new onboarding flow — three screens, mobile-first", "trigger": false}
+  ]
+}

package/.agent-src/skills/copilot-config/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: copilot-config
-description: "Use when configuring GitHub Copilot — copilot-instructions.md, PR review patterns, output optimization — even when the user just says 'tune Copilot' or 'why is Copilot commenting on X'."
+description: "Tune the GitHub Copilot AI — `copilot-instructions.md`, PR-review patterns, suggestion behavior, output verbosity. NOT for dev-environment setup (use `devcontainer`)."
 source: package
 domain: process
 ---

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

@@ -1,6 +1,6 @@
 ---
 name: devcontainer
-description: "Use when configuring DevContainers or GitHub Codespaces — devcontainer.json, custom images, secrets, VS Code features — even when the user just says 'why does my Codespace not start'."
+description: "Wire up DevContainers / GitHub Codespaces — `devcontainer.json`, container images, secrets, VS Code features, port forwarding. NOT for tuning Copilot itself (use `copilot-config`)."
 source: package
 domain: devops
 ---

package/.agent-src/skills/doc-coauthoring/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: doc-coauthoring
+description: "Use when co-authoring a PRD, design doc, RFC, decision doc, or technical spec — 3-stage flow (context → section-by-section → reader-test) — even if the user just says 'help me write this spec'."
+source: package
+domain: process
+---
+
+# doc-coauthoring
+
+## When to use
+
+Use this skill when:
+
+* User starts a substantial writing task — PRD, RFC, design doc, decision doc, technical spec, proposal
+* User says "help me write this up", "draft a proposal", "we need a doc for X"
+* The output is a structured prose document the user will own and ship
+
+Do NOT use when:
+
+* Authoring agent docs / module docs / AGENTS.md → `agent-docs-writing`
+* Writing a README → `readme-writing` / `readme-writing-package`
+* Writing an ADR (process is fixed, no co-authoring loop) → `adr-create`
+* Code documentation, inline comments, docstrings
+
+## Goal
+
+Move from a fuzzy ask to a complete document the user owns, by:
+
+1. Closing the context gap before drafting
+2. Building each section through brainstorm → curate → draft → refine
+3. Testing the draft with a fresh-context reader before declaring done
+
+## Preconditions
+
+* User explicitly wants a document (not a quick answer)
+* `save-file` and `str-replace-editor` available
+* Target path and filename agreed up front
+
+## Procedure
+
+### 0. Inspect existing material
+
+Before any drafting, **inspect** the landscape: search `agents/` and
+the repo for related prior docs (`grep -ril "{topic}" agents/ docs/`),
+check the user's named ticket / thread for context, and confirm no
+in-flight document already covers the ask. If a near-duplicate exists,
+surface it and ask whether to extend or supersede.
+
+### 1. Context gathering
+
+Close the gap between what the user knows and what you know.
+
+1. **Meta-questions** — one numbered-options block (per `user-interaction`): doc type? primary audience? desired impact? template/format constraint? existing related docs / threads / tickets?
+2. **Info dump** — invite stream-of-consciousness context: plain text, paths to existing docs, ticket links, thread paste.
+3. **Clarifying questions** — 5–10 numbered questions to fill remaining gaps. User answers shorthand (`1: yes`, `2: see #channel`, `3: backwards-compat reason`).
+4. **Exit gate** — ask "ready to draft, or more context?" — wait for confirmation. Do not start scaffolding the file until the user confirms.
+
+### 2. Refinement & structure
+
+Build the document section by section.
+
+1. **Agree on structure** — propose 3–5 sections based on doc type and context. Ask user to confirm or adjust.
+2. **Scaffold the file** — use `save-file` to create the doc with placeholder text per section (`[To be written]`). One commit-equivalent action; review with the user before populating.
+3. **Pick the starting section** — suggest the one with the most unknowns (usually the core decision / proposal). Never start with the summary.
+4. **Per-section loop** — repeat for each section:
+   - **Clarifying questions** — 5–10 numbered questions about what this section covers
+   - **Brainstorm** — 5–20 numbered options of what could go in. Offer "more options?" at the end.
+   - **Curation** — user picks: `keep 1,4,7,9` / `remove 3 (dupes 1)` / `combine 11+12`. Parse freeform feedback if the user gives `"looks good but ..."`.
+   - **Gap check** — "anything missing for this section?"
+   - **Draft** — `str-replace-editor` to replace the placeholder. Never reprint the whole doc.
+   - **Iterate** — user feedback in, surgical edits out. After 3 iterations with no substantial change, ask "anything to remove without losing value?"
+   - **Section exit gate** — "section done — move to next?"
+5. **Whole-doc review at 80% complete** — re-read the full file. Surface contradictions, redundancy, generic filler. Apply final edits.
+
+### 3. Reader test
+
+Verify the doc works for someone without your context.
+
+1. **Predict reader questions** — generate 5–10 questions a real reader would ask after reading.
+2. **Run the test** — pick one:
+   - **`ai-council` available** → invoke with the doc + predicted questions; treat each council member as a fresh reader.
+   - **Otherwise** → instruct the user to open a fresh Claude / ChatGPT, paste the doc, ask the questions one by one. Capture answers.
+3. **Additional fresh-reader checks** (always): "what is ambiguous?" · "what context does this doc assume readers have?" · "internal contradictions?"
+4. **Report** — surface where the fresh reader got it wrong, where assumptions break.
+5. **Loop back to Stage 2** for problematic sections until the fresh reader answers cleanly and surfaces no new gaps.
+
+### 4. Handover
+
+1. Final read-through by the user (they own the doc).
+2. Verify facts, links, technical details.
+3. Confirm intended impact achieved.
+4. Surface the final file path. Done.
+
+## Output format
+
+1. Target document file at the agreed path (e.g. `agents/proposals/{slug}.md`)
+2. One concluding line stating "Doc complete at {path} — ready for owner review"
+
+## Gotcha
+
+* **One question per turn** (Iron Law from `ask-when-uncertain`) — never bundle clarifying + brainstorm + curate prompts in one message.
+* **Never reprint the full doc** during iteration — always use `str-replace-editor`. Reprinting wastes tokens and creates merge drift.
+* **Reader test is not optional** — without it, you ship the version that makes sense to you, not to readers. Skip only on explicit user override.
+* **Sub-agent absence** — `ai-council` may not be configured. Have the manual fresh-Claude fallback ready (Stage 3 step 2).
+* **Image alt-text** — if the doc embeds images, add alt-text inline; without it, fresh-reader tools can't see them.
+* **Language discipline** — keep the doc body in English (per `language-and-tone`). For verbatim German user phrases or interview quotes, use `DE: … · EN: …` anchor blocks.
+
+## Frugality Standards
+
+Apply the [Frugality Charter](../../contexts/contracts/frugality-charter.md).
+
+* Per the default-terse rule, each section opens with content, not "In this section …".
+* Per the cheap-question check, numbered-options blocks only when consequences differ — skip "yes / no, continue?" type prompts.
+* Per the post-action summary suppression, the final output is the doc — no wrapping "Summary of what we did" block.
+
+**Pre-save self-check:**
+
+1. Does any section open with a narrative preamble instead of content?
+2. Are clarifying questions bundled when one-at-a-time would surface user priorities better?
+3. Is the reader-test stage skipped or merged into a "we're done" claim?
+4. Is non-English prose present outside `DE: / EN:` anchor blocks?
+
+## Do NOT
+
+* Skip Stage 1 — straight-to-drafting produces docs that miss audience and impact
+* Bundle 5+ questions into one numbered block — breaks one-question-per-turn
+* Reprint the whole doc on every iteration
+* Declare "done" without the Stage 3 reader test
+* Generate doc content from scratch when the user has existing context — gap-closing is the whole point

package/.agent-src/skills/doc-coauthoring/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "skill": "doc-coauthoring",
+  "description": "5 should-trigger + 5 should-not-trigger queries. Should-trigger phrasings reflect real co-authoring asks for PRDs / specs / decision docs. Should-not-trigger near-misses share doc-writing vocabulary but route elsewhere (agent-docs-writing, readme-writing, adr-create, code docs, translations).",
+  "queries": [
+    {"q": "Help me draft a PRD for the new analytics feature — I have a lot of context but no structure yet", "trigger": true},
+    {"q": "We need a design doc for the OAuth migration before next week's review. Can you walk me through writing it?", "trigger": true},
+    {"q": "I have to write up a decision doc about dropping Redis. Where do we start?", "trigger": true},
+    {"q": "Need an RFC for the data-export rate-limit change before tomorrow's architecture sync", "trigger": true},
+    {"q": "Lass uns einen Spec für das neue Webhook-Verfahren zusammenstellen — du fragst, ich antworte", "trigger": true},
+    {"q": "Add a section to AGENTS.md about the new env vars we just introduced", "trigger": false},
+    {"q": "Update the README with the new install instructions for the docker variant", "trigger": false},
+    {"q": "Write an ADR for the queue-broker switch from Redis to SQS", "trigger": false},
+    {"q": "Add docstrings to all public methods on the OrderService class", "trigger": false},
+    {"q": "Translate the lang/de strings to French for the new locale rollout", "trigger": false}
+  ]
+}

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

@@ -1,6 +1,6 @@
 ---
 name: laravel
-description: "Writes Laravel code following framework conventions, project architecture, and modern best practices for controllers, requests, services, jobs, events, policies, and application structure."
+description: "Writes Laravel PHP — Eloquent, Artisan controllers, FormRequests, jobs, events, policies, providers. For Symfony / Doctrine use `symfony-workflow`. For framework-free PHP use `php-coder`."
 source: package
 domain: engineering
 ---

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

@@ -1,6 +1,6 @@
 ---
 name: project-analysis-core
-description: "Use for the universal deep-analysis workflow: project discovery, version resolution, docs loading, architecture mapping, execution flow, and package research."
+description: "Raw discovery primitives — project discovery, version resolution, docs loading, architecture mapping, execution flow. Called by `universal-project-analysis`. Single-pass scan → `project-analyzer`."
 source: package
 domain: discovery
 ---

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

@@ -1,6 +1,6 @@
 ---
 name: project-analyzer
-description: "ONLY when user explicitly requests: full project analysis, tech stack detection, or structured analysis documents for agents/analysis/. NOT for regular feature work."
+description: "ONLY when user asks for single-pass tech-stack detection or `agents/analysis/` write-up. Deep multi-pass audit → `universal-project-analysis`. Raw primitives → `project-analysis-core`."
 source: package
 domain: discovery
 ---