@event4u/agent-config 9.2.0 → 9.4.0

package/dist/agent-src/skills/learning-tutor/SKILL.md

@@ -0,0 +1,215 @@
+---
+model_tier: inherit
+name: learning-tutor
+description: "Use when the user wants to learn a topic or verify real understanding — rapid-competence session, error drills, learning sprint, gap probe, Feynman check. Triggers 'teach me X', 'quiz me'."
+domain: process
+workspaces:
+  - engineering
+packs:
+  - engineering-base
+---
+
+# learning-tutor
+
+> Structured tutoring modes for learning WITH the agent instead of consuming
+> explanations FROM it. Default agent behavior on "teach me X" = prose
+> lecture — pedagogically the weakest format. This skill replaces the lecture
+> with six evidence-shaped modes: triage what to learn, practice before
+> theory, withhold answers until the learner has tried, verify understanding
+> with probes the learner cannot bluff through.
+
+## When to use
+
+Use when the user:
+
+- Wants to get functional in a new tool, framework, language or topic fast
+  ("teach me X", "get me productive in X", "crash course").
+- Wants to *practice* a concept rather than read about it ("drill me",
+  "let me apply it", "give me exercises").
+- Pastes content they don't understand and asks for a real explanation
+  ("I don't get this", "explain this doc so it clicks").
+- Has a concrete goal with a deadline, wants a learning plan
+  ("learning plan for X", "need to ship Y in two weeks, don't know Z").
+- Wants existing knowledge stress-tested ("quiz me", "do I actually
+  understand X?", "find my blind spots").
+- Just learned something, wants to verify it stuck ("check my
+  understanding", "let me explain it back to you").
+
+Do NOT use when:
+
+- User asks a direct factual or how-to question — answer it
+  (per `direct-answers`); don't convert a question into a curriculum.
+- User wants the agent to DO the task, not to learn it.
+- "Learning" target is this package's own artifacts (rules/skills) —
+  that is `learning-to-rule-or-skill`, a different skill.
+- User wants a plan/idea stress-tested — that is `adversarial-review`
+  or `/challenge-me`, not knowledge tutoring.
+
+## Procedure
+
+1. **Select the mode** from user intent (table below). Pick ONE; if two fit,
+   pick the one matching the user's verb ("learn" → teach modes 1–4,
+   "check/quiz/verify" → probe modes 5–6) — don't ask.
+2. **State the chosen mode** in one line, freeze the target
+   (skill/topic/goal).
+3. **Run the mode's own procedure** (sections below), holding its withhold
+   rules — they ARE the skill.
+4. **Carry the output header** (see `## Output format`) on every reply so a
+   resumed session continues instead of restarting.
+5. **Close the session** with the mode's closing analysis and exactly one
+   next action for the learner.
+
+### Mode selection
+
+| User intent | Mode |
+|---|---|
+| "Get me functional in X fast", no deadline given | 1 · Rapid competence |
+| "Let me practice X", "drill me", concept with known pitfalls | 2 · Error-driven drill |
+| Pasted content + "I don't understand this" | 3 · Keystone decoding |
+| Concrete goal + deadline + current level | 4 · Goal-backward sprint |
+| "Do I really know X?", "find my gaps" | 5 · Gap probe |
+| "I just learned X — check my understanding" | 6 · Feynman check |
+
+## Mode 1 — Rapid competence
+
+Frame: one time-boxed session (default 4 focused hours unless user names a
+budget), never met again — every minute must transfer skill. No theory block
+without immediate practical use.
+
+1. Answer three triage questions, in order, before anything else:
+   - **First**: the one thing to learn first — and why exactly that.
+   - **Ignore**: what to skip entirely for now — and why skipping is safe.
+   - **Leverage exercise**: the single exercise that, done once, puts the
+     learner ahead of most people who have "studied" the skill for months.
+2. Run the session practice-first: each concept introduced only at the
+   moment an exercise needs it.
+3. Close with the next leverage exercise for the learner's own follow-up.
+
+## Mode 2 — Error-driven drill
+
+Frame: do not explain the concept. Put the learner into a realistic scenario
+where it must be applied and where a typical beginner makes a concrete
+mistake.
+
+1. Present the scenario; let the learner act.
+2. On a mistake: do NOT give the fix. Ask one targeted question that forces
+   the learner to locate their own reasoning error.
+3. Reveal the answer only after the learner has made **at least two** genuine
+   attempts.
+4. Repeat the cycle with variations until the learner applies the concept
+   without hesitation; then say so explicitly, stop.
+
+## Mode 3 — Keystone decoding
+
+Frame: user supplied content (doc, text, code, spec) that doesn't click.
+
+1. Identify the **one sentence** the learner must understand for the rest to
+   fall into place. Name it verbatim from the content.
+2. Explain only that sentence first — with an everyday analogy, no technical
+   term left unexplained in the same breath.
+3. Ask exactly **3 comprehension questions** designed so only someone who
+   actually understood can answer (no yes/no, no recall of wording).
+4. Continue into the rest of the content only after all three are answered
+   correctly; on a wrong answer, re-explain from a different angle, re-ask.
+
+## Mode 4 — Goal-backward sprint
+
+Frame: user has a specific outcome, a time frame, a current level. Plan
+targets the OUTCOME, not the subject in general.
+
+1. Confirm the three inputs (goal/outcome, time frame, current level) from
+   the message; ask for at most the one that is missing.
+2. Build a 7-day path (scale to the stated time frame). Each day has exactly
+   three elements:
+   - **One task**, completable in ~45 minutes.
+   - **One success criterion** — how the learner verifies they did it right.
+   - **One exclusion rule** — what they deliberately do NOT touch that day.
+3. Self-check the path against the goal: a day that doesn't causally move the
+   learner toward the stated outcome → rework before presenting.
+
+## Mode 5 — Gap probe
+
+Frame: user believes they already know the subject. Job: prove otherwise.
+
+1. Ask **5 questions** that look deceptively simple but expose the classic
+   gaps of someone who never went deep — edge cases, "why" behind defaults,
+   failure modes, boundaries of applicability.
+2. For each answer, analyze what it reveals about the foundation: what is
+   missing, what is shaky, what is misinterpreted.
+3. No softening. A shallow answer is called shallow, with the specific gap
+   named. Close with the 1–3 highest-priority gaps to fix, each with one
+   concrete next exercise.
+
+## Mode 6 — Feynman check
+
+Frame: user explains the freshly learned topic as if the agent were a
+10-year-old. Agent listens and interrupts.
+
+1. Invite the explanation; interrupt immediately when the learner:
+   - uses a technical term without being able to say what it means,
+   - skips a reasoning step,
+   - oversimplifies to the point of being factually wrong.
+2. Each interruption is one pointed question, not a correction.
+3. Close with a precise analysis: what the accumulated stumbles reveal about
+   which parts of the understanding are not yet solid — and which held.
+
+## Output format
+
+Every tutoring reply carries a compact header so the learner always knows
+where they are:
+
+```
+learning-tutor · mode <n> — <mode name>
+Target:   <skill/topic/goal>
+Progress: <step or day k/N · attempts used · questions passed x/y>
+Next:     <what the learner does next>
+```
+
+Required fields (ordered):
+
+1. **Mode line** — mode number + name, stated in the first reply, kept on
+   every subsequent reply of the session.
+2. **Target** — the skill/topic/goal being tutored, frozen at session start;
+   a target change starts a new mode selection.
+3. **Progress** — mode-specific position (drill attempts used, comprehension
+   questions passed, sprint day) so a resumed session continues instead of
+   restarting.
+4. **Next** — the single next action for the learner, never more than one.
+
+## Gotcha
+
+- **Lecture relapse** — after 2–3 turns the agent drifts back into
+  explaining instead of asking. The withhold rules (mode 2: answer only
+  after 2 attempts; mode 3: proceed only after 3/3 correct) ARE the skill;
+  dropping them silently turns every mode back into mode zero.
+- **Solving instead of tutoring** — learner pastes their broken attempt,
+  agent fixes it. In modes 2/5/6 the fix is withheld; the question comes
+  first. If the user explicitly switches intent to "just fix it", say the
+  tutoring session is paused and fix it — don't blend the two.
+- **Flattery corrupts the probe** — modes 5 and 6 only work blunt. "Great
+  answer!" on a shallow answer defeats the mode (`direct-answers`
+  Iron Law 1 already forbids it).
+- **Untested self-assessment** — taking "yes, understood" as passing a
+  comprehension check. Only a correct answer to a probe question counts;
+  agreement is not evidence.
+- **Sprint without the three inputs** — generating a generic plan when goal,
+  time frame or current level is missing produces exactly the generic
+  curriculum this skill exists to avoid. Ask for the missing input (one
+  question, per `ask-when-uncertain`).
+
+## Do NOT
+
+- NEVER give the solution in mode 2 before two genuine learner attempts.
+- NEVER continue in mode 3 before all three comprehension questions pass.
+- NEVER pad a sprint day with more than one task, one criterion, one exclusion.
+- NEVER soften a gap-probe or Feynman verdict to be nice.
+- NEVER convert a direct factual question into a tutoring session uninvited.
+
+## See also
+
+- `learning-to-rule-or-skill` — converting session learnings into package
+  artifacts (the other direction: agent learns, not user).
+- `adversarial-review` / `/challenge-me` — stress-testing a plan or artifact
+  rather than a person's understanding.
+- `sequential-thinking` — structured reasoning for the agent itself.
+- `direct-answers` — the brevity/no-flattery floor the probe modes rely on.

package/dist/agent-src/skills/persona-improvement/SKILL.md

@@ -0,0 +1,81 @@
+---
+model_tier: inherit
+name: persona-improvement
+description: "ONLY when the user explicitly asks to refine a persona from recent corrections — persona analog of skill-improvement-pipeline; tightens a persona's Unique Questions, governance-gated."
+domain: process
+execution:
+  type: assisted
+  handler: internal
+  allowed_tools: []
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+requires_skills:
+  - persona-governance
+---
+
+# persona-improvement
+
+The persona analog of [`skill-improvement-pipeline`](../skill-improvement-pipeline/SKILL.md):
+feed a persona a sample of recent corrections/failures where its review lens
+**should** have caught something and didn't, and tighten its `Unique Questions`
+so the lens fires next time. Access ergonomics, not new capability — it only
+sharpens an existing persona, never creates one.
+
+## When to use
+
+- The user explicitly says "improve / refine this persona" or "the <persona> lens keeps missing X".
+- A correction sample exists (review misses, repeated feedback) that a persona's questions should have surfaced.
+
+Do NOT use for:
+
+- Creating a new persona (that is `persona-governance` + the authoring flow).
+- Editing a persona's identity/scope (a breaking change → new id per `persona-governance`).
+- A one-off miss with no pattern — one anecdote is not a refinement signal.
+
+## Procedure
+
+1. **Gather the correction sample.** Collect the recent misses/corrections tied
+   to this persona's domain (from the conversation, feedback notes, or a review
+   log). If fewer than ~3 distinct misses, STOP — no pattern yet; say so.
+2. **Locate the gap.** For each miss, name the question the persona *should* have
+   asked that would have surfaced it. Cluster the misses into ≤ 2 recurring gaps.
+3. **Propose tightened `Unique Questions`.** Rewrite or add questions that close
+   the gaps — concrete and answerable-from-the-diff, not vague ("does this add a
+   second branch on the same enum?" beats "is the design good?"). Keep the
+   section ≥ 3 questions (`persona-governance` schema floor).
+4. **Governance gate (mandatory).** Before writing, confirm with
+   [`persona-governance`](../../rules/persona-governance.md): the edit is a
+   same-id refinement (not a scope/identity change — those need a new id); the
+   persona keeps ≥ 1 skill citation; the file still passes the skill linter
+   (tier/wing/section/line budget). A scope change is out of scope for this loop.
+5. **Apply + verify.** Edit only the `Unique Questions` section; run
+   `./scripts-run src/scripts/skill_linter` on the persona file and confirm
+   0 errors; show the before/after questions.
+
+## Output format
+
+1. **Correction sample** — the ≥ 3 misses, one line each.
+2. **Gaps** — the ≤ 2 recurring gaps the misses cluster into.
+3. **Before/after `Unique Questions`** — the diff, with which gap each new question closes.
+4. **Governance confirmation** — same-id refinement ✅, ≥ 1 citation intact ✅, linter 0-error ✅.
+
+## Gotcha
+
+- The most common misuse is **scope creep disguised as refinement**: adding
+  questions that widen the persona into a second domain. That is a new persona
+  (per the per-domain cap), not a refinement — STOP and route to
+  `persona-governance`, do not grow the lens sideways.
+
+## Do NOT
+
+- Do NOT refine on a single miss — a pattern needs ≥ 3.
+- Do NOT touch identity, scope, tier, or wing — same-id `Unique Questions` only; anything else is a new-id change under `persona-governance`.
+- Do NOT drop below 3 `Unique Questions` (schema floor).
+- Do NOT commit or push — apply the edit locally, surface the diff.
+
+## Related Skills
+
+- [`skill-improvement-pipeline`](../skill-improvement-pipeline/SKILL.md) — the skill-side analog this mirrors.
+- [`persona-governance`](../../rules/persona-governance.md) — the four discipline checks this loop is gated by.

package/dist/agent-src/skills/react-shadcn-ui/SKILL.md

@@ -253,6 +253,16 @@ current state on the next polish round.
 
 `DESIGN.md` `## Taste Dials` → honour: Variance → layout-family spread + asymmetry; Motion → animation budget + reduced-motion posture; Density → spacing scale + info-per-viewport. Absent → follow brief's inferred dials.
 
+## Component workshop (Storybook) — when the library is large enough
+
+Generic "isolate + document reusable components" principle → [`fe-design`](../fe-design/SKILL.md) § Component Architecture; this is the React carve-out for the tool-specific part.
+
+- **When it pays off** — real, growing shared-component library (more than a handful of reused primitives, multiple consumers, ongoing UI work): Storybook makes each component discoverable, reviewable in isolation, reused not re-invented. **Skip** for a small surface of one-offs — setup + maintenance not worth it yet.
+- **Story per reusable primitive, not per screen** — a story covers a component + its states (default / loading / empty / error / dark), mirroring the Step 3 state-coverage matrix. Screens composed, not story-fied.
+- **Reuse the token layer** — stories render under the same semantic tokens + `.dark` class; never hardcode a preview theme (Step 2 token discipline).
+- **A11y in-workshop** — run the a11y addon so isolation catches contrast / role / focus before the component reaches a screen.
+- Do NOT let stories drift from the component API — a story props-drilling values the component no longer accepts is stale documentation; keep beside the component, update in the same change.
+
 ## Do NOT
 
 - Do NOT install `shadcn-ui` from npm — primitives are scaffolded.

package/dist/agent-src/skills/rice-prioritization/SKILL.md

@@ -89,6 +89,7 @@ Do NOT use for valuation, OKR decomposition, or funnel-stage diagnosis (see Rela
 
 **WHEN NOT to use this**
 
+- ONE choice between alternatives on custom criteria (not many items on the fixed R×I×C/E formula) — route to [`decision-record`](../decision-record/SKILL.md) § Weighted-matrix mode.
 - Decomposing an objective into KRs — route to [`okr-tree-modeling`](../okr-tree-modeling/SKILL.md).
 - Diagnosing why a funnel stage drops — route to [`funnel-analysis`](../funnel-analysis/SKILL.md).
 - Modelling whether an investment is worth its capital cost — route to [`dcf-modeling`](../dcf-modeling/SKILL.md).

package/dist/agent-src/skills/stakeholder-tradeoff/SKILL.md

@@ -147,7 +147,9 @@ column is missing.
   becomes input to this skill for escalation. Boundary prose lives
   in [`docs/guidelines/cross-role-handoff.md`](../../../docs/guidelines/cross-role-handoff.md).
 - The trade-off is purely technical (perf vs storage, sync vs async)
-  — route to [`decision-record`](../decision-record/SKILL.md).
+  — route to [`decision-record`](../decision-record/SKILL.md); one costly
+  choice on ≥ 3 options with user-weighted criteria → its § Weighted-matrix
+  mode (this skill answers WHO pays; that mode answers WHICH option wins).
 - The dominant axis is risk, not stakeholder cost — route to
   [`risk-officer`](../risk-officer/SKILL.md).
 - The output is the locked decision artifact — hand off to

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

@@ -28,7 +28,7 @@ Do NOT use when:
   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
+* Budget is the constraint — each subagent call multiplies cost; non-interactive bulk cohorts → batch/caching via the [`token-optimizer`](../token-optimizer/SKILL.md) index branch
 * The implementer and judge would be the same model on the same
   context — no added signal
 
@@ -68,33 +68,22 @@ line; any gate failing → in-session no-op. Never lifts a safety floor.
 
 ## Worker-prompt contract
 
-Every dispatched worker prompt obeys four rules — they prevent the two classic
-handoff failures: lossy re-summarization dropping the user's requirements, and
-over-scripted prompts that break on first contingency.
-
-- **(a) User constraints verbatim.** Pass the user's
-  constraints/exclusions/preferences into the worker prompt **verbatim** — never
-  a paraphrase (a paraphrase silently drops requirements).
-- **(b) Describe the goal, don't script the approach.** State the outcome and
-  let the worker choose the path; over-scripting breaks on contingencies.
-- **(c) Translate environment paths.** Orchestrator-local paths do not exist in
-  the worker's sandbox — resolve/translate them at spawn.
-- **(d) Pre-declared check-in conditions.** The worker names, at spawn time, the
-  conditions under which it will halt and ask ("if login required", "if
-  multiple candidates found") — so interrupts are predictable, not surprises.
-- **(e) Attach relevant knowledge — read-only (road-to-opt-subagent-harvest
-  P3).** Before dispatch, look up the slice's key identifiers via
-  `memory_lookup` / the knowledge cards and attach the top hits to the
-  worker prompt AS LEADS — labelled per the source-discovery discipline
-  (negative facts + pointers durable; positive structure = hypothesis to
-  re-confirm, never a build input). The WRITE half stays forbidden: a
-  subagent's output is never auto-persisted into memory — promotion is
-  always the human-gated flow (ADR-098 floor). Auto-surface, never
-  auto-write.
+Every dispatched worker prompt obeys five rules that prevent the two classic
+handoff failures (lossy re-summarization dropping the user's requirements;
+over-scripted prompts that break on first contingency): (a) user
+constraints **verbatim**, (b) describe the goal — don't script the approach,
+(c) translate environment paths into the worker's sandbox, (d) pre-declare
+check-in conditions, (e) attach relevant knowledge read-only (auto-surface,
+never auto-write — ADR-098 floor). The five rules verbatim:
+[`subagent-spawn-contract` § Worker-prompt rules](../../contexts/execution/subagent-spawn-contract.md).
 
 When to delegate at all is [`delegation-policy`](../../rules/delegation-policy.md);
 the spawn boundary is the [`subagent-spawn-contract`](../../contexts/execution/subagent-spawn-contract.md).
 
+## Hand-off worked examples
+
+Ordered / fan-out hand-offs embed each step's return **verbatim** in the next prompt and state what to do with it (never "continue from before" — the lossy re-summarization failure). Two worked shapes: [`subagent-spawn-contract` § Hand-off worked examples](../../contexts/execution/subagent-spawn-contract.md).
+
 ## Form gate — deterministic, BEFORE mode selection
 
 With auto-dispatch on by default (ADR-117), mode selection happens without
@@ -406,5 +395,6 @@ Skip emit when `subagents.enabled: false` or `spawn_count == 0` (in-session run)
 | Stepwise plan with judge gates       | Inline — see [`prompts/do-in-steps.md`](prompts/do-in-steps.md) |
 | Standalone judge on an existing diff | Inline — see judge prompt in [`prompts/do-and-judge.md`](prompts/do-and-judge.md) |
 | External / networked second opinion  | [`ai-council`](../ai-council/SKILL.md) |
+| Cross-model review WITH repo access   | [`/team`](../../commands/team.md) (collaborative; subagents are in-session same-weights) |
 | Verifying completeness               | [`verify-before-complete`](../verify-before-complete/SKILL.md) |
 | What a subagent owns vs never owns   | [`subagent-boundary`](../../../docs/contracts/subagent-boundary.md) |

package/dist/agent-src/templates/agents/agent-project-settings.example.yml

@@ -39,7 +39,7 @@ schema_version: 1
 # CI guard: a release bump of `package.json` must update this value
 # in lockstep — see scripts/check_template_pin_drift.ts (road-to-
 # portable-runtime-and-update-check P3.3).
-agent_config_version: "9.2.0"
+agent_config_version: "9.4.0"
 
 # --- Project identity ---
 project:

package/dist/discovery/deprecation-report.md

@@ -1,6 +1,6 @@
 # Discovery — Deprecation Report
 
-- Generated: `2026-07-14T13:40:54Z`
+- Generated: `2026-07-20T09:32:39Z`
 - Deprecated artefacts: **0**
 
 _None. Tree is clean._