@event4u/agent-config 1.33.0 → 1.35.0

package/docs/decisions/ADR-005-subagent-worktrees.md

@@ -0,0 +1,120 @@
+---
+adr: 005
+status: accepted
+date: 2026-05-09
+decision: subagent-worktrees-no-auto-merge
+supersedes: —
+superseded_by: —
+phase: road-to-better-skills-and-profiles · A7
+---
+
+# ADR-005 — `do-in-worktrees` Mode: No Auto-Merge, Ranked Candidates
+
+## Status
+
+**Accepted** · 2026-05-09.
+
+## Context
+
+`road-to-better-skills-and-profiles` Block A introduces formal personas
+and specialist review lenses. Step A7 derives from council iter-1
+verdict **CC-OQ1 (a)** — adopt the AgentHub pattern from
+`claude-skills` (per-candidate git-worktree isolation) into the
+existing `subagent-orchestration` skill **without** weakening the
+[`non-destructive-by-default`](../../.agent-src.uncompressed/rules/non-destructive-by-default.md)
+Hard Floor.
+
+The AgentHub pattern in its native form is appealing: spawn N
+implementer subagents into N worktrees, let a judge rank, **auto-merge
+the winner**. The auto-merge step is where the Hard Floor objects:
+
+- A merge into a tracked branch is a destructive operation in the
+  agent-authority sense — it rewrites the working copy on a branch
+  that the user will later push.
+- "Standing autonomy" never lifts the Hard Floor. CC-OQ1 (a) is the
+  only variant that survives the floor.
+
+Mode 7 (`do-in-worktrees`) already covered the **chained handoff**
+pattern (cross-wing skill chain, each step in its own worktree).
+ADR-005 extends mode 7 with a **competitive variant** for parallel
+candidate isolation, with three guardrails that make the pattern
+Hard-Floor-safe.
+
+## Decision
+
+Augment `subagent-orchestration` mode 7 with the **competitive
+variant** under three Hard-Floor-derived rules:
+
+1. **No auto-merge.** The orchestrator never merges a candidate
+   branch into the integration branch. The user invokes the merge
+   explicitly (e.g. `/finishing-a-development-branch`), or the
+   orchestrator hands back with a numbered-options block per
+   [`user-interaction`](../../.agent-src.uncompressed/rules/user-interaction.md).
+2. **Ranked presentation.** Judge ranks candidates 1..N with a
+   one-line justification per rank. The judge does **not** apply
+   anything; ranking is the only output.
+3. **Loser worktrees stay.** The orchestrator does not delete
+   losing worktrees automatically. Cleanup happens via
+   [`finishing-a-development-branch`](../../.agent-src.uncompressed/skills/finishing-a-development-branch/SKILL.md)
+   on user request, after harvesting any salvageable partial idea.
+
+Mode 7's chained-handoff variant is unchanged. The two variants
+share the worktree-isolation primitive but differ in topology
+(sequential vs parallel) and selection (linear chain vs ranked).
+
+## Consequences
+
+### Accepted
+
+- The Hard Floor stands. No new override surface; no "auto-merge
+  under standing autonomy" branch.
+- AgentHub's exploratory benefit is preserved — N candidates run in
+  isolation, judge picks a winner, user can compare diffs.
+- `using-git-worktrees` remains the mechanics layer; mode 7 is the
+  dispatch layer. No duplication.
+
+### Trade-offs
+
+- **Higher final-step cost.** User-driven merge adds one round-trip
+  per `do-competitively`-in-worktrees run vs the AgentHub auto-merge
+  variant. This is the cost of preserving the Hard Floor.
+- **Disk usage.** Loser worktrees persist until the user cleans up.
+  The `finishing-a-development-branch` skill carries an explicit
+  worktree-prune step to bound this.
+
+## Alternatives considered
+
+- **Variant (b) — auto-merge winner under standing autonomy flag.**
+  Rejected. The Hard Floor is non-negotiable and the cost of a
+  user round-trip is small compared to the cost of merging the
+  wrong candidate. Standing autonomy narrows other rules; it does
+  not lift the Hard Floor (per `non-destructive-by-default` § Hard
+  Floor catalog).
+- **Variant (c) — keep AgentHub as a separate skill, do not touch
+  mode 7.** Rejected. The skill would duplicate the worktree
+  primitives in `using-git-worktrees` and the dispatch logic in
+  `subagent-orchestration`. Mode 7 already exists; extending it is
+  cheaper than spawning a parallel skill. Council CC-OQ1 (a)
+  agreed: *"adopts AgentHub pattern from claude-skills, respecting
+  Hard Floor"*.
+
+## Re-evaluation trigger
+
+Revisit this ADR when:
+
+- A surface-level user-research signal indicates the manual-merge
+  round-trip is the bottleneck (≥3 distinct user reports), AND
+- A reviewable proposal exists for narrowing the Hard Floor
+  (additional gates, audit trail, etc.) that does not weaken the
+  prod-data and prod-deploy floors.
+
+Both conditions must hold. Either alone is insufficient.
+
+## References
+
+- `agents/roadmaps/road-to-better-skills-and-profiles.md` § A7
+  (council iter-1 CC-OQ1 verdict (a))
+- `.agent-src.uncompressed/skills/subagent-orchestration/SKILL.md` § Mode 7
+- `.agent-src.uncompressed/skills/using-git-worktrees/SKILL.md` (mechanics layer)
+- `.agent-src.uncompressed/rules/non-destructive-by-default.md` § Hard Floor catalog
+- `.agent-src.uncompressed/skills/finishing-a-development-branch/SKILL.md` (cleanup path)

package/docs/decisions/ADR-006-skill-tools-python-pilot.md

@@ -0,0 +1,114 @@
+---
+adr: 006
+status: accepted
+date: 2026-05-09
+decision: skill-tools-python-pilot-pass
+supersedes: —
+superseded_by: —
+phase: road-to-better-skills-and-profiles · Block D (D1–D5)
+---
+
+# ADR-006 — Skill-Tools Python Pilot: Outcome and Decision
+
+## Status
+
+**Accepted** · 2026-05-09 · pilot **PASSED** · tools kept under
+`scripts/skill_tools/`.
+
+## Context
+
+`road-to-better-skills-and-profiles` **Block D** introduced four
+Python tools for skill / persona corpus maintenance:
+
+| ID | Tool | Purpose |
+|---|---|---|
+| D1 | `lint_skill_tools.py` | Pilot-invariant gate (stdlib-only, ≤ 200 LOC, `--json`/`--help`, `_SAMPLE`) |
+| D2 | `score_skill_relevance.py` | Rank skills for a task by keyword overlap + persona match |
+| D3 | `audit_persona_coverage.py` | Tier-aware persona-citation matrix (specialist < 3, core < 5 → flag) |
+| D4 | `suggest_skill_for_task.py` | Top-N skill + persona combos with one-line justification (wraps D2 + D3) |
+
+The pilot was gated by **iter-1 AI-Council verdict** (members:
+claude-sonnet-4-5 + gpt-4o · 2 rounds · 2026-05-01) <!-- council-ref-allowed: ADR decision trace -->
+([`block-d-python-tools-pilot-verdict`](../../agents/council-responses/block-d-python-tools-pilot-verdict.md)) <!-- council-ref-allowed: ADR decision trace -->
+under strict invariants: stdlib-only (internal package imports
+allowed), ≤ 200 LOC per tool, machine-readable output (`--json`),
+embedded `_SAMPLE`, blind-labelled eval corpora, and a kill-switch if
+< 2 / 3 functional tools pass.
+
+## Eval Outcome (D5)
+
+Corpora at `agents/eval-corpora/block-d/`. Runner:
+`scripts/skill_tools/run_block_d_eval.py`. Report:
+[`agents/eval-corpora/block-d/report.json`](../../agents/eval-corpora/block-d/report.json).
+
+| Tool | Target | Result | Verdict |
+|---|---|---|---|
+| **D2** (relevance scorer) | ≥ 85 % top-3 hit on 10 blind tasks | **10 / 10 (100 %)** | ✅ pass |
+| **D3** (persona audit) | ≥ 2 under-cited personas surfaced | **5** (`ai-agent`, `developer`, `eloquent-tamer`, `qa`, `stakeholder`) | ✅ pass |
+| **D4** (skill suggester) | ≥ 3 / 5 top-1 hits on blind corpus | **3 / 5 (60 %)** | ✅ pass (at floor) |
+| **Pilot** | ≥ 2 / 3 functional tools pass | **3 / 3** | ✅ **PASS** |
+
+D4 misses are honest: B01 ranks `livewire` over the more specific
+`livewire-architect` (close cousins; both legitimate top-1 picks);
+B03 (`description-assist` for "review trigger quality") is partial
+overlap. Both surface as `confirm-with-reviewer`-grade suggestions,
+which matches the tool's design contract.
+
+## Decision
+
+1. **Keep** the four tools under `scripts/skill_tools/` and the meta
+   linter at `scripts/lint_skill_tools.py`.
+2. **Keep** `lint-skill-tools` in the CI pipeline (`task ci` →
+   `taskfiles/ci-fast.yml`).
+3. **Keep** the eval corpora and the runner at
+   `scripts/skill_tools/run_block_d_eval.py` for regression.
+4. **Defer** the v2 refinements (anthropic round-2):
+   - `--ratio-mode` flag for D3 (absolute thresholds proved adequate
+     on first run; no false alarms on real corpus).
+   - Token-frequency reweighting for D2 (100 % top-3 hit rate leaves
+     no signal to reweight against).
+   - Council `do-competitively` mode for skill-suggester (out of
+     scope; orthogonal to the pilot).
+5. **No** promotion to a `task` subcommand or kernel-rule citation.
+   Tools stay advisory; no agent rule references them yet.
+
+## Consequences
+
+**Positive:**
+- 4 advisory tools available for future skill / persona corpus work
+  without third-party dependencies.
+- Tier-aware persona thresholds are now mechanically enforced
+  (advisory, not gated).
+- Eval corpora become the regression baseline — any future heuristic
+  edit must keep ≥ 2 / 3 tools passing.
+
+**Neutral:**
+- Tools are advisory only; no rule cites them, so they cannot
+  silently drift into a Hard-Floor or auto-execution role.
+- `task ci` gains one cheap meta-lint step (~ 50 ms).
+
+**Negative:**
+- Four new files to maintain. Mitigation: pilot-invariants linter
+  gates structural drift; tests gate semantic drift.
+- D4's 3 / 5 floor result is not a comfortable margin. If a future
+  edit drops it below 3 / 5, kill-switch fires per the council
+  verdict and the tool is removed without further debate.
+
+## Reversibility
+
+**Trigger:** any single `run_block_d_eval.py` execution that returns
+< 2 / 3 tools passing on `main` for two consecutive commits.
+**Action:** delete `scripts/skill_tools/`,
+`scripts/lint_skill_tools.py`, `tests/test_*_skill*.py`, the corpora
+dir, and the `lint-skill-tools` task entry. Mark this ADR
+`superseded_by`. ~ 30 min mechanical revert.
+
+## References
+
+- Roadmap: [`road-to-better-skills-and-profiles`](../../agents/roadmaps/archive/road-to-better-skills-and-profiles.md) Block D.
+- Council: [`block-d-python-tools-pilot-verdict`](../../agents/council-responses/block-d-python-tools-pilot-verdict.md). <!-- council-ref-allowed: ADR decision trace -->
+
+- Tools: [`scripts/skill_tools/`](../../scripts/skill_tools/).
+- Linter: [`scripts/lint_skill_tools.py`](../../scripts/lint_skill_tools.py).
+- Corpora + report: [`agents/eval-corpora/block-d/`](../../agents/eval-corpora/block-d/).
+- Tests: `tests/test_lint_skill_tools.py`, `tests/test_score_skill_relevance.py`, `tests/test_audit_persona_coverage.py`, `tests/test_suggest_skill_for_task.py`.

package/docs/decisions/INDEX.md

@@ -7,6 +7,9 @@ _Auto-generated by `scripts/adr/regenerate_index.py`. Do not edit._
 | [ADR-001](ADR-001-kernel-swap-deferred.md) | Kernel Swap Deferred | accepted | 2026-05-06 | — |
 | [ADR-002](ADR-002-kernel-bucket-overrides.md) | Kernel Bucket Overrides | — | — | — |
 | [ADR-003](ADR-003-flat-cluster-subs-and-colon-syntax.md) | Flat Cluster Subs And Colon Syntax | — | — | — |
+| [ADR-004](ADR-004-rule-governance-pruning.md) | Rule Governance Pruning | accepted | 2026-05-08 | — |
+| [ADR-005](ADR-005-subagent-worktrees.md) | Subagent Worktrees No Auto Merge | accepted | 2026-05-09 | — |
+| [ADR-006](ADR-006-skill-tools-python-pilot.md) | Skill Tools Python Pilot Pass | accepted | 2026-05-09 | — |
 
 ## Unnumbered (legacy)
 

package/docs/guidelines/cross-role-handoff.md

@@ -0,0 +1,127 @@
+# Cross-Role Handoff
+
+Wing-specific prose for senior-tier skills handing off across role
+boundaries. The mechanical contract — initiator → delegated(input) →
+output, lint rules, worktree boundary — lives in
+[`docs/contracts/cross-wing-handoff.md`](../contracts/cross-wing-handoff.md).
+This guideline covers **when a role hands off to another role**,
+**how to phrase the routing**, and the **L4 / C8 boundary**.
+
+## Wings at a glance
+
+The senior catalog spans four wings. Each wing owns a cognition
+cluster and emits artifacts the other wings can consume.
+
+| Wing | Cluster | Senior skills (anchor examples) |
+|---|---|---|
+| **1. Engineering** | Code, architecture, debugging, review | `architecture-review-lens`, `bug-analyzer`, `judge-bug-hunter`, `blast-radius-analyzer` |
+| **2. Product + Foundation** | Discovery, refinement, decisions | `po-discovery`, `refine-ticket`, `decision-record`, `rice-prioritization` |
+| **3. GTM + Growth** | Customers, comms, funnel, channels | `customer-research` (L1), `release-comms` (L2), `funnel-analysis` |
+| **4. Money + Strategy + Ops** | Unit economics, OKRs, capacity, risk | `unit-economics-modeling`, `okr-tree-modeling`, `dcf-modeling`, `risk-officer` |
+
+A handoff is **cross-role** when the initiator and the delegate live
+in different wings (or in different cognition clusters within the
+same wing). Same-cluster delegation is normal composition and does
+not need this guideline.
+
+## When to hand off
+
+A senior skill SHOULD hand off — not absorb — when any of the four
+fires:
+
+1. **Different cognition cluster.** The downstream step needs a
+   different mode of thinking (numbers vs. narrative; user vs.
+   system; risk vs. design). Absorbing it dilutes the skill.
+2. **Different artifact owner.** The output naturally lives under a
+   different role's catalog (e.g. `forecast-band.json` belongs to
+   Wing-4, not Wing-2).
+3. **Tier-mismatch risk.** Inlining the step would require
+   downgrading to a non-senior delegate; the cross-wing-handoff
+   linter blocks tier mismatches.
+4. **Re-use evidence.** The step is already cited by ≥ 2 other
+   senior skills; absorbing it duplicates cognition.
+
+If none fire, keep the step inline. Cross-role plumbing is not free.
+
+## How to phrase the handoff
+
+Two surfaces in the senior-skill template carry routing:
+
+- **`## Related Skills` § *WHEN NOT to use this*** — the routing
+  list. One bullet per peer that owns the cognition the user might
+  expect from this skill but is wrong to ask here. Format:
+  *"X is the actual question — route to [`<peer>`](../<peer>/SKILL.md)"*.
+- **`## Procedure` Composes line** — when the skill **does** call
+  another skill mid-procedure, declare it on a line beginning with
+  `Composes [`<peer>`](...)` so the linter can match the call site
+  to the delegate's `## Input` block.
+
+The delegated skill's `## Input` block names the fields the initiator
+must pass. Drift between the two is the failure the contract catches.
+
+## Decision tree
+
+```
+Need a downstream cognition step?
+├── Same wing + same cluster? → keep inline (normal composition).
+├── Different cluster, but no shipped senior peer?
+│   └── Implement inline; flag for next plate's audit (the cluster
+│       might need its own senior).
+├── Different cluster + shipped senior peer + ≥ 2 reuse citations?
+│   └── HAND OFF: declare in WHEN NOT block + Composes line.
+└── Cross-wing chain (≥ 3 senior steps, ≥ 30 min each)?
+    └── Use `subagent-orchestration` mode 6 (worktrees) per
+        cross-wing-handoff.md § 3.
+```
+
+## L4 / C8 composition boundary
+
+Council Q3 (2026-05-05) locks the disambiguation between L4
+`stakeholder-tradeoff` and the sibling C8 `code-review-multi-lens`:
+
+- **L4 fires** when a request crosses two stakeholder lenses
+  (engineering ↔ PO, PO ↔ ops, ops ↔ infra) and the trade-off is
+  **not yet code**. Output is a trade-off matrix + recommendation +
+  dissent log; the artifact is consumable by a roadmap or PR
+  description, not by a diff.
+- **C8 fires** when the request **is already code** — PR open, draft
+  branch under review, or a diff supplied as input. Output is a
+  multi-lens code review (security · architecture · tests · quality)
+  bound to file:line spans.
+- **C8 → L4 escalation.** A C8 verdict that surfaces a stakeholder
+  conflict — e.g. test-coverage judge fails but PO insists on
+  shipping — becomes **input to L4**. The escalation is one-way:
+  L4 produces the dissent log that decides whether C8's verdict
+  is overridden, with the override recorded in
+  [`decision-record`](../../.agent-src.uncompressed/skills/decision-record/SKILL.md).
+
+The boundary keeps the two skills sharp — neither absorbs the other —
+and gives the agent a deterministic rule for which one to load when
+both look applicable.
+
+## Worked example
+
+A PO refining a ticket (Wing-2) hits a sentence like *"the cheapest
+acquisition channel is paid search, but only if CAC payback < 6 months"*:
+
+1. Wing-2 is the initiator (`refine-ticket`).
+2. The CAC question is Wing-4 cognition — `unit-economics-modeling`.
+3. `refine-ticket` hands off via:
+   - WHEN NOT entry: *"CAC / payback questions — route to
+     [`unit-economics-modeling`](../unit-economics-modeling/SKILL.md)"*.
+   - Composes line in the procedure step that needs the answer.
+4. The delegate's `## Input` block lists the fields (channel,
+   cohort, time horizon); `refine-ticket` passes them.
+5. The output (`payback-band.md`) feeds the AC of the original ticket.
+
+No cluster collision, no tier mismatch, no untyped drift.
+
+## See also
+
+- [`docs/contracts/cross-wing-handoff.md`](../contracts/cross-wing-handoff.md)
+  — the mechanical contract this guideline cites.
+- [`docs/contracts/context-spine.md`](../contracts/context-spine.md)
+  — orthogonal context-slot mechanism, often used together with a
+  handoff (e.g. delegate reads `team` slot the initiator opted in to).
+- `.agent-src.uncompressed/skills/subagent-orchestration/SKILL.md` § mode 6
+  — when the chain runs in fresh worktrees.

package/docs/personas.md

@@ -0,0 +1,115 @@
+# Personas
+
+Personas are **review lenses** the host agent adopts when running a
+skill — not sub-agents, not execution modes. Each persona shapes
+*what* the agent looks for in a diff, plan, or artifact; the host
+identity, tools, and workflow stay the same.
+
+This page catalogs the 11 personas shipped with `event4u/agent-config`
+and explains how `personas:` (lens axis) interacts with `/mode`
+(role-mode axis).
+
+## Catalog
+
+| ID | Role | Tier | Lens summary |
+|---|---|---|---|
+| `developer` | Developer | core | Pragmatic implementer voice — what's the smallest correct change? |
+| `senior-engineer` | Senior Engineer | core | Long-horizon impact — what does this look like in 6 months? |
+| `product-owner` | Product Owner | core | Outcome over output — does this move the user metric? |
+| `stakeholder` | Stakeholder | core | Risk and politics — who owns the rollback if this fails? |
+| `critical-challenger` | Critical Challenger | core | Devil's-advocate voice — what assumption is load-bearing here? |
+| `ai-agent` | AI Agent | core | Tool-economy voice — token cost, prompt clarity, automation seam. |
+| `qa` | QA | specialist | Test coverage and regression gates. |
+| `backend-architect` | Backend Architect | specialist | Service-layer boundaries, transaction scope, contract changes. |
+| `eloquent-tamer` | Eloquent Tamer | specialist | N+1, query shape, ORM idioms that melt the database. |
+| `security-engineer` | Security Engineer | specialist | OWASP-shaped failure modes, secret leakage, trust boundaries. |
+| `frontend-engineer` | Frontend Engineer | specialist | Component lifecycle, reactive state, hydration boundaries. |
+
+Tier rules:
+
+- **Core (6)** — always-loaded cast. 5 sections (Focus · Mindset · Unique Questions · Output Expectations · Anti-Patterns), ≤ 120 lines.
+- **Specialist (5)** — opt-in lenses. 7 sections (Core-5 + Critical Rules + Workflows), ≤ 100 lines.
+
+Schema contract: [`docs/contracts/persona-schema.md`](contracts/persona-schema.md).
+
+## When to invoke a persona
+
+- **A skill cites it.** Skills declare `personas:` in frontmatter; the
+  agent adopts the listed personas while running the skill. No user
+  action needed. Example: `judge-security-auditor` cites
+  `security-engineer` — invoking the skill applies the lens.
+- **You want a second pass on existing work.** Pick the specialist
+  whose checklist matches the diff: `eloquent-tamer` for ORM heavy
+  changes, `frontend-engineer` for component changes,
+  `backend-architect` for service-seam changes.
+- **Adversarial review.** `critical-challenger` for the devil's-advocate
+  voice; `security-engineer` for abuse-case framing.
+
+Invocation example (when supported by the host tool):
+
+```text
+--personas=backend-architect,security-engineer
+```
+
+The host agent reads the persona's `Critical Rules` and `Workflows`
+sections (specialist tier) or `Mindset` and `Unique Questions` (core
+tier) and merges them into its review pass.
+
+## `personas:` vs `/mode` — two different axes
+
+| Axis | What it controls | Example |
+|---|---|---|
+| `/mode` (role-mode) | Which **contract** the agent operates under for a turn — what outputs are mandatory, what work is refused | `/mode reviewer` refuses to write production code |
+| `personas:` (lens) | Which **review checklists** the agent overlays on a skill's procedure | `personas: [security-engineer]` adds OWASP-shaped checks to whatever skill is running |
+
+The two compose. `/mode reviewer` + `personas: [security-engineer,
+backend-architect]` = a review-only turn that applies both the
+security-abuse-case lens and the service-seam lens on top of the
+review contract.
+
+Personas are **not** a replacement for `/mode`. A persona cannot
+refuse work or change output contracts; that is `/mode`'s job.
+
+## Skill citations
+
+Specialist personas need at least one skill citation to earn their
+slot. Current cite map:
+
+| Persona | Cited by |
+|---|---|
+| `qa` | `judge-test-coverage` |
+| `critical-challenger` | `adversarial-review`, `requesting-code-review`, `receiving-code-review` |
+| `developer` · `senior-engineer` · `product-owner` · `ai-agent` | `refine-ticket`, `refine-prompt`, `estimate-ticket` |
+| `backend-architect` | `authz-review`, `api-design`, `blast-radius-analyzer` |
+| `eloquent-tamer` | `eloquent`, `database` |
+| `security-engineer` | `judge-security-auditor`, `threat-modeling`, `authz-review` |
+| `frontend-engineer` | `existing-ui-audit`, `fe-design` |
+
+Add a citation by appending `personas: [<id>]` to the skill's
+frontmatter — never overwrite an existing list, append.
+
+## Override pattern
+
+Consumers can override any package-shipped persona via the standard
+override mechanism:
+
+- **Frontmatter override** — change `tier`, `mode`, `description`
+  while keeping the package body. Frontmatter wins.
+- **Body override** — full replace. Drop a same-named file under
+  `agents/personas/<id>.md`; the package version is shadowed.
+
+See [`override-management`](../.agent-src/skills/override-management/SKILL.md)
+for the mechanics.
+
+## Anti-patterns
+
+- **Personas as agents.** Personas are lenses, not sub-agents. They do
+  not spawn processes or run tools independently.
+- **Personas as modes.** They do not change the host's contract or
+  refuse work. Use `/mode` for that.
+- **Specialist sprawl.** Cap is "≤ 4 specialists per plate" by the
+  council A-OQ2 verdict. New specialists need ≥ 1 skill citation
+  before merging.
+- **Core-tier mutation.** Core personas are versioned (`version` in
+  frontmatter); breaking changes need a new ID, not an in-place
+  rewrite.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@event4u/agent-config",
-    "version": "1.33.0",
+    "version": "1.35.0",
     "description": "Shared agent configuration \u2014 skills, rules, commands, guidelines, and templates for AI coding tools",
     "license": "MIT",
     "private": false,

package/scripts/_backfill_skill_domains.py

@@ -0,0 +1,140 @@
+#!/usr/bin/env python3
+"""One-shot back-fill: inject `domain:` frontmatter into every SKILL.md.
+
+Removed after B3 lands. Source-of-truth = SKILL_DOMAIN_MAP below.
+Fails loudly if the map and on-disk skill set diverge.
+"""
+from __future__ import annotations
+import re
+import sys
+from pathlib import Path
+
+SKILL_DOMAIN_MAP: dict[str, str] = {
+    "adr-create": "process", "adversarial-review": "quality",
+    "agent-docs-writing": "process", "agents-md-thin-root": "process",
+    "ai-council": "process", "analysis-autonomous-mode": "discovery",
+    "analysis-skill-router": "discovery", "api-design": "engineering",
+    "api-endpoint": "engineering", "api-testing": "quality",
+    "artisan-commands": "engineering", "async-python-patterns": "engineering",
+    "authz-review": "quality", "aws-infrastructure": "devops",
+    "blade-ui": "engineering", "blast-radius-analyzer": "discovery",
+    "bug-analyzer": "discovery", "check-refs": "process",
+    "code-refactoring": "engineering", "code-review": "quality",
+    "command-routing": "process", "command-writing": "process",
+    "composer-packages": "engineering", "context-authoring": "process",
+    "context-document": "process", "conventional-commits-writing": "process",
+    "copilot-agents-optimization": "process", "copilot-config": "process",
+    "dashboard-design": "devops", "data-flow-mapper": "discovery",
+    "database": "engineering", "dcf-modeling": "product",
+    "deep-reading-analyst": "discovery", "defense-in-depth": "quality",
+    "dependency-upgrade": "engineering", "description-assist": "process",
+    "design-review": "quality", "devcontainer": "devops",
+    "developer-like-execution": "process", "docker": "devops",
+    "dto-creator": "engineering", "eloquent": "engineering",
+    "error-handling-patterns": "engineering", "estimate-ticket": "product",
+    "existing-ui-audit": "discovery", "fe-design": "engineering",
+    "feature-planning": "product", "file-editor": "process",
+    "finishing-a-development-branch": "process", "flux": "engineering",
+    "funnel-analysis": "product", "git-workflow": "process",
+    "github-ci": "devops", "grafana": "devops",
+    "guideline-writing": "process", "jira-integration": "process",
+    "jobs-events": "engineering", "judge-bug-hunter": "quality",
+    "judge-code-quality": "quality", "judge-security-auditor": "quality",
+    "judge-test-coverage": "quality", "laravel": "engineering",
+    "laravel-horizon": "engineering", "laravel-mail": "engineering",
+    "laravel-middleware": "engineering", "laravel-notifications": "engineering",
+    "laravel-pennant": "engineering", "laravel-pulse": "engineering",
+    "laravel-reverb": "engineering", "laravel-scheduling": "engineering",
+    "laravel-validation": "engineering", "learning-to-rule-or-skill": "process",
+    "lint-skills": "process", "livewire": "engineering",
+    "logging-monitoring": "devops", "markitdown": "process",
+    "mcp": "process", "mcp-builder": "process",
+    "md-language-check": "process", "merge-conflicts": "process",
+    "migration-creator": "engineering", "mobile-e2e-strategy": "quality",
+    "module-management": "process", "multi-tenancy": "engineering",
+    "okr-tree-modeling": "product", "openapi": "engineering",
+    "override-management": "process", "performance": "engineering",
+    "performance-analysis": "discovery", "persona-writing": "process",
+    "pest-testing": "quality", "php-coder": "engineering",
+    "php-debugging": "engineering", "php-service": "engineering",
+    "playwright-testing": "quality", "project-analysis-core": "discovery",
+    "project-analysis-hypothesis-driven": "discovery",
+    "project-analysis-laravel": "discovery", "project-analysis-nextjs": "discovery",
+    "project-analysis-node-express": "discovery",
+    "project-analysis-react": "discovery", "project-analysis-symfony": "discovery",
+    "project-analysis-zend-laminas": "discovery", "project-analyzer": "discovery",
+    "project-docs": "process", "prompt-engineering-patterns": "product",
+    "prompt-optimizer": "product", "quality-tools": "quality",
+    "react-native-setup": "devops", "react-shadcn-ui": "engineering",
+    "readme-reviewer": "quality", "readme-writing": "process",
+    "readme-writing-package": "process", "receiving-code-review": "process",
+    "refine-prompt": "product", "refine-ticket": "product",
+    "repomix-packer": "process", "requesting-code-review": "process",
+    "review-routing": "quality", "rice-prioritization": "product",
+    "roadmap-management": "process", "roadmap-writing": "process",
+    "rtk-output-filtering": "process", "rule-writing": "process",
+    "script-writing": "process", "secrets-management": "devops",
+    "security": "quality", "security-audit": "quality",
+    "sentry-integration": "devops", "sequential-thinking": "process",
+    "skill-improvement-pipeline": "process", "skill-management": "process",
+    "skill-reviewer": "quality", "skill-writing": "process",
+    "sql-writing": "engineering", "subagent-orchestration": "process",
+    "systematic-debugging": "discovery", "technical-specification": "product",
+    "terraform": "devops", "terragrunt": "devops",
+    "test-driven-development": "quality", "test-performance": "quality",
+    "testing-anti-patterns": "quality", "threat-modeling": "quality",
+    "token-optimizer": "process", "traefik": "devops",
+    "unit-economics-modeling": "product", "universal-project-analysis": "discovery",
+    "upstream-contribute": "process", "using-git-worktrees": "process",
+    "validate-feature-fit": "quality", "verify-completion-evidence": "quality",
+    "websocket": "engineering",
+}
+VALID_DOMAINS = {"engineering", "product", "quality", "devops", "process", "discovery"}
+
+
+def main() -> int:
+    # Default: source-of-truth tree. Pass --target=compressed to mirror into .agent-src/.
+    target = ".agent-src.uncompressed/skills"
+    for arg in sys.argv[1:]:
+        if arg == "--target=compressed":
+            target = ".agent-src/skills"
+    skills_root = Path(target)
+    on_disk = sorted(p.name for p in skills_root.iterdir() if p.is_dir())
+    in_map = sorted(SKILL_DOMAIN_MAP.keys())
+    missing = set(on_disk) - set(in_map)
+    extra = set(in_map) - set(on_disk)
+    if missing or extra:
+        print(f"DRIFT: missing={sorted(missing)} extra={sorted(extra)}", file=sys.stderr)
+        return 2
+    bad = {k: v for k, v in SKILL_DOMAIN_MAP.items() if v not in VALID_DOMAINS}
+    if bad:
+        print(f"INVALID DOMAIN VALUES: {bad}", file=sys.stderr)
+        return 2
+
+    fm_pat = re.compile(r"^(---\n)(.*?)(\n---\n)", re.DOTALL)
+    domain_line_pat = re.compile(r"^domain:[ \t]*[A-Za-z]+[ \t]*$", re.MULTILINE)
+    source_line_pat = re.compile(r"^(source:[ \t]*\S+)$", re.MULTILINE)
+    edited = 0
+    for slug, domain in SKILL_DOMAIN_MAP.items():
+        skill_md = skills_root / slug / "SKILL.md"
+        text = skill_md.read_text()
+        m = fm_pat.match(text)
+        if not m:
+            print(f"NO FRONTMATTER: {skill_md}", file=sys.stderr)
+            return 2
+        fm_body = m.group(2)
+        if domain_line_pat.search(fm_body):
+            new_fm = domain_line_pat.sub(f"domain: {domain}", fm_body)
+        elif source_line_pat.search(fm_body):
+            new_fm = source_line_pat.sub(rf"\1\ndomain: {domain}", fm_body)
+        else:
+            new_fm = fm_body.rstrip("\n") + f"\ndomain: {domain}"
+        if new_fm != fm_body:
+            skill_md.write_text(m.group(1) + new_fm + m.group(3) + text[m.end():])
+            edited += 1
+    print(f"Back-filled {edited}/{len(SKILL_DOMAIN_MAP)} skills")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())