@event4u/agent-config 9.8.0 → 9.9.0

package/docs/contracts/skill-distribution-channels.md

@@ -1,66 +0,0 @@
----
-stability: beta
-keep-beta-until: 2026-09-04
----
-
-# Skill Distribution Channels — canonical per AI tool
-
-**Status:** Active (locked 2026-05-25 via Phase A of `road-to-clean-skill-distribution-channels.md`)
-**Owner:** maintainer-team
-**Inputs:** [`agents/evidence/audits/2026-05-distribution-channels/`](../../agents/evidence/audits/2026-05-distribution-channels/) (audits 01 + 02), AI Council convergence on the canonical-channel question (claude-sonnet-4-5 + gpt-4o, 2026-05-25 — session artefact auto-pruned; the decision body is inlined in this contract)
-
-## Rule
-
-For every AI tool the package supports, **exactly one channel** is the canonical registration surface used by the consumer installer. The other channel (where one exists at the upstream tool level) is either:
-
-- not projected into the consumer install at all (default), or
-- projected behind the `--legacy-both` opt-in flag for users on older harnesses.
-
-## Per-tool matrix
-
-| Tool | Channels supported by host | Canonical (consumer install) | Other channel behaviour | Rationale |
-|---|---|---|---|---|
-| **Claude Code** | Plugin manifest (`.claude-plugin/marketplace.json`) + filesystem (`.claude/skills/`) | **filesystem** | Manifest not projected by default; use `--legacy-both` to opt in | Cross-tool consistency. Filesystem is the only channel all six tools share. The package's own `.claude-plugin/marketplace.json` stays at the source repo for users who run `claude plugin install <name>` directly. |
-| **Augment** | Manifest with `source: "."` (`.augment-plugin/marketplace.json`) + filesystem (`.augment/`) | **filesystem** | Manifest stays — it is metadata-only, not a second registry. No `--legacy-both` needed. | The manifest points at the same directory the harness scans; one source of truth on disk. |
-| **Cursor** | Filesystem only (`.cursor/rules/*.mdc`) | **filesystem** | n/a — no second channel exists | No host-level alternative. |
-| **Cline** | Filesystem only (`.clinerules/`) | **filesystem** | n/a | No host-level alternative. |
-| **Windsurf** | Filesystem only (`.windsurf/rules/`, `.windsurf/workflows/`) | **filesystem** | n/a | No host-level alternative. |
-| **Copilot** | Single file (`.github/copilot-instructions.md` or root `copilot-instructions.md`) | **filesystem** | n/a | Single file, not a registry. |
-
-## Decision drivers
-
-1. **Cross-tool consistency.** Four of six tools have only a filesystem channel. Picking filesystem for the other two makes one rule cover everything.
-2. **Same-install dual-registration is closed by default.** If `scripts/install.sh` does not project the Claude plugin manifest into the consumer install, the harness has only the filesystem to scan, so the manifest+filesystem double-register risk is eliminated regardless of how the host harness deduplicates.
-3. **Cross-scope drift is orthogonal.** The canonical-channel decision does NOT solve the actual 2026-05-25 bug (cross-scope user-global + project-local with different frontmatter). Phase B installer guard + Phase C runtime probe close that path. They are companions to this contract, not substitutes for it.
-4. **Publication surface preserved.** The source repo continues to ship `.claude-plugin/marketplace.json` for users who want to install via `claude plugin install <event4u/agent-config>`. Removing the manifest from the **consumer install** does not affect that path.
-5. **`--legacy-both` is opt-in only.** Users on harness versions that genuinely require both channels can request the legacy projection. Default is single-channel.
-
-## Council convergence (2026-05-25)
-
-Two-round debate on whether filesystem or plugin should be canonical for Claude. The transparently-merged verdict:
-
-- **Anthropic (R2):** "MIXED leaning DISAGREE on the proposal **as written**" — pointed out that the proposal does not address cross-scope drift by itself, and that the canonical-channel decision only matters if the Claude harness double-registers on same-install. Test scenarios surfaced as critical path before locking. Conclusion: if Claude does ambient filesystem discovery (it does, in practice), **filesystem becomes canonical not by choice but because manifest adds a second registration mechanism with no isolation benefit**.
-- **OpenAI (R2):** Endorsed filesystem-canonical with a fail-loud Phase C probe. Suggested user research on `--legacy-both` adoption.
-
-Both members agreed the decision is structurally correct **conditional on** the cross-scope drift fix landing in Phase B and the probe being fail-loud in Phase C. This contract is published with those follow-up commitments.
-
-## Acceptance criteria for follow-up phases
-
-Phase B and Phase C of `road-to-clean-skill-distribution-channels.md` MUST:
-
-- (Phase B) Add a pre-install guard that detects existing installs at the other scope and either refuses, warns, or upgrades — surfaced via numbered options.
-- (Phase C) Run a probe at `agent-config setup` time AND from `scripts/install.sh --strict` that fails the install on cross-scope drift findings (per the council convergence — fail-loud, not informational).
-- (Phase A Step 4) Update `scripts/install.sh` and `task generate-tools` so the canonical channel above is what lands in the consumer install. Document `--legacy-both` for opt-in.
-
-## Out of scope
-
-- Manifest format changes upstream (Claude Code's marketplace shape) — host-controlled.
-- Alternative install paths (vendored copies, git submodules, npm `--prefix`) — package's npm install is the supported path.
-- Re-litigating the channel pick after this lock — reopened only on a new audit that surfaces a structurally different shape (e.g. a host change that removes ambient filesystem discovery).
-
-## See also
-
-- [`docs/contracts/install-scopes.md`](install-scopes.md) — companion contract for cross-scope behaviour (authored in Phase B).
-- [`docs/contracts/harness-expectations.md`](harness-expectations.md) — Phase D companion documenting host-side behaviours that look like package bugs but are not.
-- [`agents/evidence/audits/2026-05-distribution-channels/`](../../agents/evidence/audits/2026-05-distribution-channels/) — the underlying audits (01 Claude, 02 Augment, 03 installer flow).
-- [`README.md § Installation`](../../README.md) — consumer-facing install path.

package/docs/contracts/skill-domains.md

@@ -1,144 +0,0 @@
----
-stability: beta
-keep-beta-until: 2026-08-12
----
-
-# 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.uncondensed/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 `./scripts-run src/scripts/_emit_domain_table`).
-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.uncondensed/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/contracts/skill-dry-run.md

@@ -1,47 +0,0 @@
----
-stability: experimental
----
-
-# Skill Dry-Run / Preview Contract
-
-> **Status** · v0 / design · 2026-05-30. Phase 5 of `road-to-leaner-core-and-discovery`.
-> The council's missing-item catch: with 220 skills, non-dev personas need a non-destructive way
-> to see what a skill/command will do **before** running it.
-
-## What "preview" means
-
-A preview reads a skill's **declared intent** — its frontmatter and `## Steps` body — and renders a
-plain-language "this skill will…" summary. It surfaces:
-
-- the skill's **declared steps** (the `## Steps` section headings);
-- its **execution type** (`manual` / `assisted` / `automated`, default `manual`) and **handler**
-  (`none` / `shell` / `php` / `node` / `internal`);
-- its declared **`allowed_tools`**;
-- any **file or command targets** named in the body (backtick paths, `./scripts-run src/scripts/…` invocations).
-
-## Explicit non-goals
-
-```
-PREVIEW IS NOT A SANDBOX. IT DOES NOT EXECUTE A FENCED COPY OF THE SKILL.
-IT IS NOT A GUARANTEE OF SIDE-EFFECT-FREENESS FOR SKILLS WITH AN `execution` BLOCK.
-```
-
-Preview reads declared intent — it does not run the skill, does not dry-run its commands, and cannot
-prove a skill is harmless. It tells you what the skill *says* it will touch, so you can decide whether
-to run it. For `execution: manual` skills (the default), it states plainly: **instructional only — no
-automatic execution** (per [`runtime-safety`](../../dist/agent-src/rules/runtime-safety.md): `manual` is
-instructional, `assisted` must propose before executing).
-
-## Surface
-
-- CLI / agent: `/skill:preview <name>` — plain-language summary by default; `--technical` shows the raw
-  frontmatter + step list.
-- Script: `scripts/skill_preview.py <name> [--technical] [--format text|json]`.
-
-Plain-language mode reuses the plain-explain tone (employee-roadmap Phase 6). A malformed or missing
-SKILL.md degrades to a **structured error**, never a crash.
-
-## Implementation
-
-`scripts/skill_preview.py` (≤ 250 LOC). Read-only over `dist/agent-src/skills/<name>/SKILL.md`. No network,
-no execution. Coverage: `tests/test_skill_preview.py`.