@event4u/agent-config 1.32.0 → 1.34.0

package/docs/contracts/persona-schema.md

@@ -0,0 +1,136 @@
+---
+stability: beta
+---
+
+# Persona Schema — two-tier (Core / Specialist)
+
+> **Status:** active · **Stability:** beta · **Owner:** road-to-better-skills-and-profiles Block A
+> · **Linter:** `scripts/skill_linter.py § lint_persona`
+> · **Source-of-truth dir:** `.agent-src.uncompressed/personas/`
+> · **Council verdict:** iter-1 A-OQ1 (c) — hybrid
+
+Locks the canonical persona shape: a uniform frontmatter across both
+tiers, a 5-section spine for Core, and a 7-section spine for Specialist
+(Core-5 + Critical Rules + Workflows). Existing Core personas are
+**not migrated** — the schema accepts the v1 shape that already ships.
+
+## § 1 — Frontmatter (uniform across tiers)
+
+| Key | Type | Required | Notes |
+|---|---|---|---|
+| `id` | string | yes | lowercase-hyphenated, must match filename stem |
+| `role` | string | yes | human-readable role name |
+| `description` | string | yes | one sentence, ≤ 160 chars |
+| `tier` | enum | yes | `core` \| `specialist` |
+| `mode` | string | optional | advisory link to a role-contract workflow mode |
+| `version` | string | yes | semver; bump on breaking changes |
+| `source` | enum | yes | `package` \| `project` |
+
+`personas:` is the consumer-side citation key (used in skill
+frontmatter); it is **not** part of a persona's own frontmatter.
+
+## § 2 — Tier definitions
+
+### `core` — always-loaded cast
+
+The six lenses every multi-lens skill leans on by default:
+`developer` · `senior-engineer` · `product-owner` · `stakeholder`
+· `critical-challenger` · `ai-agent`. Stable v1 shape; council
+verdict explicitly forbids migration to the 7-section spine — it
+would dilute the always-loaded cost without adding signal.
+
+### `specialist` — opt-in lens
+
+Domain-narrow voices a skill cites only when its specific axis is in
+play (e.g. `qa` for testability, `backend-architect` for system
+boundaries). Specialists carry the 7-section spine because their
+narrower scope justifies — and benefits from — explicit Critical
+Rules and Workflows blocks (pattern adopted from
+`alirezarezvani/claude-skills`).
+
+## § 3 — Required sections per tier
+
+### Core (5 sections, ≤ 120 lines)
+
+1. **Focus** — one paragraph, the lens.
+2. **Mindset** — bullets, default assumptions and skepticism.
+3. **Unique Questions** — ≥ 3 questions no other persona asks verbatim.
+4. **Output Expectations** — how findings are phrased.
+5. **Anti-Patterns** — what this persona must refuse to do.
+
+### Specialist (7 sections, ≤ 100 lines)
+
+1. **Focus**
+2. **Mindset**
+3. **Unique Questions** — ≥ 3, same heuristic
+4. **Output Expectations**
+5. **Anti-Patterns**
+6. **Critical Rules** — non-negotiable invariants this lens enforces
+   (e.g. "every new branch needs a failing test before the fix").
+   Bulleted, declarative, ≤ 8 items.
+7. **Workflows** — concrete review / inspection steps the persona
+   runs against the skill's input. Numbered, deterministic, ≤ 6 steps.
+
+`Composes well with` is permitted as an additional section in either
+tier (kept for v1 personas that ship it; not required, not budget-counted
+beyond the global line cap).
+
+## § 4 — Size budgets
+
+| Tier | Section count | Line cap | Rationale |
+|---|---|---|---|
+| `core` | 5 | ≤ 120 | always-loaded, stay lean |
+| `specialist` | 7 | ≤ 100 | opt-in, denser per section |
+
+The line cap is enforced by `lint-skills` against the full file
+including frontmatter and trailing blank line.
+
+## § 5 — Schema enforcement
+
+The linter (A2 work) enforces:
+
+- frontmatter shape (table in § 1)
+- tier enum
+- required sections per tier (§ 3)
+- size budget per tier (§ 4)
+- ≥ 3 bullets in `Unique Questions`
+- `id` matches filename stem
+- description ≤ 160 chars
+
+Specialist authors must use the template at
+`.agent-src.uncompressed/personas/_template-specialist/persona.md`.
+Core authors continue to use
+`.agent-src.uncompressed/templates/persona.md` (unchanged).
+
+## § 6 — Persona inventory (v1 snapshot)
+
+| ID | Tier | Mode | Status |
+|---|---|---|---|
+| `developer` | core | developer | shipped |
+| `senior-engineer` | core | reviewer | shipped |
+| `product-owner` | core | product-owner | shipped |
+| `stakeholder` | core | planner | shipped |
+| `critical-challenger` | core | reviewer | shipped |
+| `ai-agent` | core | developer | shipped |
+| `qa` | specialist | tester | shipped (existing 6-section shape; A-track migration to 7-section spine planned alongside A3 batch) |
+
+A3 adds four specialists drafted natively against the 7-section
+spine: `backend-architect` · `eloquent-tamer` · `security-engineer`
+· `frontend-engineer`.
+
+## § 7 — Versioning
+
+Section rename / add / remove → ADR + linter update + persona migrations
+in the same PR. Tier rename or new tier is breaking and requires a
+major version bump in the package release notes. Size-cap tightening
+is breaking when it forces existing personas to lose content; size-cap
+loosening is non-breaking.
+
+## See also
+
+- [`skill-domains`](skill-domains.md) — sister taxonomy for skills
+- [`role-contracts`](../guidelines/agent-infra/role-contracts.md) — workflow-mode axis personas compose with
+- `.agent-src.uncompressed/personas/README.md` — authoring entry point + Core-6 cast
+- `.agent-src.uncompressed/personas/_template-specialist/persona.md` — specialist starter
+- `.agent-src.uncompressed/templates/persona.md` — core starter (v1, unchanged)
+- `road-to-better-skills-and-profiles.md` — Block A (schema lock + extension)

package/docs/contracts/skill-domains.md

@@ -0,0 +1,143 @@
+---
+stability: beta
+---
+
+# Skill Domains — 6-domain taxonomy
+
+> **Status:** active · **Stability:** beta · **Owner:** road-to-better-skills-and-profiles Block B
+> · **Linter:** `scripts/skill_linter.py` enforces the `domain:` field against this allow-list
+> · **Schema:** `scripts/schemas/skill.schema.json` § `domain`
+
+Locks the canonical 6-domain taxonomy that classifies every skill in
+`.agent-src.uncompressed/skills/`. Each skill MUST declare exactly one
+`domain:` value from the allow-list below in its `SKILL.md` frontmatter.
+
+## § 1 — Allow-list
+
+```
+engineering · product · quality · devops · process · discovery
+```
+
+Unknown values fail `lint-skills`. Missing `domain:` fails `lint-skills`.
+No multi-domain assignment — pick the dominant axis.
+
+## § 2 — Domain definitions
+
+### `engineering`
+
+Application and framework code authoring — controllers, models,
+services, jobs, validation, queues, mail, broadcasting, ORMs, and
+language-level idioms (PHP, async patterns, error handling). The
+"writing the app" axis. Where the agent ships features into the
+production codebase.
+
+**Examples:** `eloquent` · `laravel-validation` · `php-coder`
+
+### `product`
+
+Discovery, refinement, and ticket / prompt shaping before code is
+written. Turns a fuzzy ask into a refined backlog item, an estimated
+unit of work, or a model-ready prompt. The "what should we build"
+axis — upstream of engineering.
+
+**Examples:** `refine-ticket` · `estimate-ticket` · `refine-prompt`
+
+### `quality`
+
+Test authoring, review, and verification gates. Pest, Playwright,
+the judge family, code review, threat modelling, security audits,
+testing anti-patterns. The "is it correct, safe, and reviewable"
+axis — runs alongside or after engineering.
+
+**Examples:** `pest-testing` · `judge-bug-hunter` · `review-routing`
+
+### `devops`
+
+Infrastructure, deployment, runtime, and observability. AWS, Docker,
+Terraform, Terragrunt, CI pipelines, Traefik, Grafana, secrets,
+DevContainers, package publishing. The "how it runs in production"
+axis.
+
+**Examples:** `terraform` · `github-ci` · `docker`
+
+### `process`
+
+Workflow, orchestration, and meta-tooling. Git workflow, slash-command
+routing, subagent orchestration, agent docs, skill / rule / command
+authoring, learnings capture, branch finishing, PR mechanics. The
+"how the agent works the codebase" axis.
+
+**Examples:** `git-workflow` · `command-routing` · `subagent-orchestration`
+
+### `discovery`
+
+Audit, diagnostic, and investigative analysis. Bug hunting, blast
+radius mapping, data flow tracing, performance and security audits,
+framework-specific project analysis, hypothesis-driven debugging.
+The "understand what's there before changing it" axis.
+
+**Examples:** `bug-analyzer` · `blast-radius-analyzer` · `project-analysis-laravel`
+
+## § 3 — Boundary heuristics (when in doubt)
+
+- **engineering vs quality** — does the skill **write production code**
+  (engineering) or **assert / review** production code (quality)?
+- **engineering vs devops** — does the artifact run **inside the app**
+  (engineering) or **around the app** (devops)?
+- **product vs process** — does the skill produce a **work item**
+  (product) or **drive the workflow** that delivers work items
+  (process)?
+- **discovery vs quality** — discovery **reads to understand**;
+  quality **reads to gate / approve**. A judge skill is `quality`; a
+  blast-radius skill is `discovery`.
+- **discovery vs engineering** — if the skill ends in a production
+  edit, it's `engineering`; if it ends in a written analysis or
+  finding, it's `discovery`.
+
+Tiebreaker: pick the axis that matches the skill's **primary output
+artifact**, not its auxiliary side-effects.
+
+## § 4 — Skill assignment by domain
+
+Snapshot from B3 back-fill (regenerate via `python3 scripts/_emit_domain_table.py`).
+Source-of-truth for the assignment is each skill's `domain:` frontmatter —
+this table is a derived view, kept readable for reviewers.
+
+### engineering (36)
+
+`api-design`, `api-endpoint`, `artisan-commands`, `async-python-patterns`, `blade-ui`, `code-refactoring`, `composer-packages`, `database`, `dependency-upgrade`, `dto-creator`, `eloquent`, `error-handling-patterns`, `fe-design`, `flux`, `jobs-events`, `laravel`, `laravel-horizon`, `laravel-mail`, `laravel-middleware`, `laravel-notifications`, `laravel-pennant`, `laravel-pulse`, `laravel-reverb`, `laravel-scheduling`, `laravel-validation`, `livewire`, `migration-creator`, `multi-tenancy`, `openapi`, `performance`, `php-coder`, `php-debugging`, `php-service`, `react-shadcn-ui`, `sql-writing`, `websocket`
+
+### product (12)
+
+`dcf-modeling`, `estimate-ticket`, `feature-planning`, `funnel-analysis`, `okr-tree-modeling`, `prompt-engineering-patterns`, `prompt-optimizer`, `refine-prompt`, `refine-ticket`, `rice-prioritization`, `technical-specification`, `unit-economics-modeling`
+
+### quality (25)
+
+`adversarial-review`, `api-testing`, `authz-review`, `code-review`, `defense-in-depth`, `design-review`, `judge-bug-hunter`, `judge-code-quality`, `judge-security-auditor`, `judge-test-coverage`, `mobile-e2e-strategy`, `pest-testing`, `playwright-testing`, `quality-tools`, `readme-reviewer`, `review-routing`, `security`, `security-audit`, `skill-reviewer`, `test-driven-development`, `test-performance`, `testing-anti-patterns`, `threat-modeling`, `validate-feature-fit`, `verify-completion-evidence`
+
+### devops (13)
+
+`aws-infrastructure`, `dashboard-design`, `devcontainer`, `docker`, `github-ci`, `grafana`, `logging-monitoring`, `react-native-setup`, `secrets-management`, `sentry-integration`, `terraform`, `terragrunt`, `traefik`
+
+### process (48)
+
+`adr-create`, `agent-docs-writing`, `agents-md-thin-root`, `ai-council`, `check-refs`, `command-routing`, `command-writing`, `context-authoring`, `context-document`, `conventional-commits-writing`, `copilot-agents-optimization`, `copilot-config`, `description-assist`, `developer-like-execution`, `file-editor`, `finishing-a-development-branch`, `git-workflow`, `guideline-writing`, `jira-integration`, `learning-to-rule-or-skill`, `lint-skills`, `markitdown`, `mcp`, `mcp-builder`, `md-language-check`, `merge-conflicts`, `module-management`, `override-management`, `persona-writing`, `project-docs`, `readme-writing`, `readme-writing-package`, `receiving-code-review`, `repomix-packer`, `requesting-code-review`, `roadmap-management`, `roadmap-writing`, `rtk-output-filtering`, `rule-writing`, `script-writing`, `sequential-thinking`, `skill-improvement-pipeline`, `skill-management`, `skill-writing`, `subagent-orchestration`, `token-optimizer`, `upstream-contribute`, `using-git-worktrees`
+
+### discovery (19)
+
+`analysis-autonomous-mode`, `analysis-skill-router`, `blast-radius-analyzer`, `bug-analyzer`, `data-flow-mapper`, `deep-reading-analyst`, `existing-ui-audit`, `performance-analysis`, `project-analysis-core`, `project-analysis-hypothesis-driven`, `project-analysis-laravel`, `project-analysis-nextjs`, `project-analysis-node-express`, `project-analysis-react`, `project-analysis-symfony`, `project-analysis-zend-laminas`, `project-analyzer`, `systematic-debugging`, `universal-project-analysis`
+
+**Total: 153 skills.**
+
+## § 5 — Versioning
+
+Domain rename or new-domain proposal → ADR + lint-skills allow-list
+update + back-fill of affected skills in the same PR. Domain
+deletion is breaking and requires a major version bump in the package
+release notes.
+
+## See also
+
+- [`skill-quality`](../../.agent-src.uncompressed/rules/skill-quality.md) — frontmatter contract for skills
+- [`rule-classification`](rule-classification.md) — sister taxonomy for rules (kernel vs auto)
+- `road-to-better-skills-and-profiles.md` — Block B (taxonomy lock + back-fill + folder reorg)

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/getting-started.md

@@ -153,7 +153,7 @@ Your agent now understands slash commands:
 | `/quality-fix` | Run and fix all quality checks |
 | `/chat-history` | Inspect the persistent chat-history log (read-only `show`) |
 
-→ [Browse all 101 active commands](../.agent-src/commands/)
+→ [Browse all 103 active commands](../.agent-src/commands/)
 
 ---