update codebase discovery

.claude-plugin/marketplace.json

@@ -9,6 +9,7 @@
   "plugins": [
     {
       "name": "agent-toolkit",
+      "version": "0.1.0",
       "source": {
         "source": "github",
         "repo": "DiUS/agent-toolkit"

.claude-plugin/plugin.json

@@ -1,5 +1,6 @@
 {
   "name": "agent-toolkit",
+  "version": "0.1.0",
   "description": "A toolkit of DiUS agent skills, commands, agents and hooks for AI coding agents.",
   "author": {
     "name": "DiUS"

AGENTS.md

@@ -1,6 +1,6 @@
 # AGENTS.md
 
-Working context and rules for any AI agent (or human) contributing to **this** repository —
+Working context and rules for any AI agent (or human) contributing to **this** repository:
 the `agent-toolkit` repo itself, not the components it ships. `CLAUDE.md` imports this file and
 adds Claude-Code-specific notes. Keep it lean: it loads into an agent's context every session.
 
@@ -31,10 +31,10 @@ scripts/validate.js            Verification gate (run before committing).
 
 - **Host-agnostic first.** Components should run on any capable agent. Do **not** add hard
   dependencies on hooks, MCP servers, or a specific runtime. Optional integrations must degrade
-  gracefully — used when present, skipped cleanly when absent. Claude-specific wiring stays
+  gracefully: used when present, skipped cleanly when absent. Claude-specific wiring stays
   confined to `.claude-plugin/`, `commands/`, `agents/` and `hooks/`.
 - **Skills are self-contained.** Everything a skill's entry point references (playbooks,
-  references, templates) lives **inside its own `skills/<name>/` directory** — that directory is
+  references, templates) lives **inside its own `skills/<name>/` directory**, which is
   the unit `npx skills` and the plugin install. Never point a skill file at something outside
   its own directory.
 - **Lean docs.** Docs (including this file) earn their length by making a contributor
@@ -53,8 +53,8 @@ scripts/validate.js            Verification gate (run before committing).
   list scoped to the minimum it needs (read-only where the agent only inspects code). Add it to
   the `agents` array in `.claude-plugin/plugin.json` to ship it in the plugin.
 - **Hook** → new `hooks/<name>/` with a `hooks.json` and its script(s), following
-  [hooks/README.md](hooks/README.md). Do **not** wire it into `.claude-plugin/plugin.json` —
-  hooks stay opt-in; consumers copy them into their own project.
+  [hooks/README.md](hooks/README.md). Do **not** wire it into `.claude-plugin/plugin.json`;
+  hooks stay opt-in, and consumers copy them into their own project.
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for the full mechanics.
 
@@ -68,19 +68,25 @@ node scripts/validate.js
 
 It checks that the manifests are valid JSON with required keys, that every `SKILL.md`,
 `agents/*.md` and `commands/*.md` (except its README) has `name` + `description` frontmatter,
-that every path referenced by `plugin.json` exists, and that any `hooks/**/hooks.json` is valid
-JSON. CI runs the same script on every push and PR — a red gate blocks merge.
+that every path referenced by `plugin.json` exists, that relative markdown links resolve and a
+skill's links stay inside that skill, and that any `hooks/**/hooks.json` is valid JSON. CI runs the
+same script on every push and PR, and a red gate blocks merge.
+
+`validate.js` itself stays **component-agnostic**: it validates the repo's format, never one
+component's content. A component with its own invariants (a rule worded identically in several
+files, a closed vocabulary) puts them in `scripts/checks/<component>.js`, which the gate loads
+automatically. See [scripts/checks/README.md](scripts/checks/README.md).
 
 ## Do not
 
 - Add hooks/MCP as a hard requirement, or otherwise break host-agnostic behaviour.
 - Reference files outside a skill's own directory from within that skill.
-- Wire a hook into `.claude-plugin/plugin.json` — hooks are opt-in only.
+- Wire a hook into `.claude-plugin/plugin.json`; hooks are opt-in only.
 - Bloat the repo docs or this file.
 - Commit with a failing `scripts/validate.js`.
 
 ## Pointers
 
-- Repo overview & install: [README.md](README.md)
+- Repo overview and install: [README.md](README.md)
 - Per-tool setup: [docs/getting-started.md](docs/getting-started.md)
 - Adding a component: [CONTRIBUTING.md](CONTRIBUTING.md)

CLAUDE.md

@@ -1,7 +1,7 @@
 # CLAUDE.md
 
 Guidance for Claude Code when working on **this** repository. Everything in
-**[AGENTS.md](AGENTS.md)** applies — start there for the repo map, principles, and how to add
+**[AGENTS.md](AGENTS.md)** applies, so start there for the repo map, principles, and how to add
 each component type. This file only adds what's specific to Claude Code.
 
 @AGENTS.md
@@ -18,7 +18,7 @@ the primary target.
 - **Subagents** in `agents/` are Claude Code workers a skill can delegate to (for example, to
   keep the main context lean or to run an isolated pass). Each is registered in the `agents`
   array of `plugin.json`. On non-Claude hosts they're absent, and the skill falls back to a
-  generic sub-agent or inline work — keep that fallback path intact when editing skill
+  generic sub-agent or inline work. Keep that fallback path intact when editing skill
   behaviour.
 - **Commands** in `commands/` register as slash commands automatically via the plugin. They're
   a Claude Code convention; other agents fall back to reading the referenced skill directly.

CONTRIBUTING.md

@@ -1,6 +1,6 @@
 # Contributing
 
-Thanks for adding to `agent-toolkit`. Please read [AGENTS.md](AGENTS.md) first — it holds the
+Thanks for adding to `agent-toolkit`. Please read [AGENTS.md](AGENTS.md) first; it holds the
 working rules and principles this repo is built on. This file covers the mechanics of adding
 each component type.
 
@@ -16,11 +16,12 @@ each component type.
 - **Verify against the source, and mind the tone.** Reflect what the code does; never frame
   existing documentation as untrustworthy.
 
+
 ## Adding a skill
 
 1. Create `skills/<name>/SKILL.md` (or equivalent entry point) with YAML frontmatter
    containing at least `name` and `description` (the `description` drives auto-discovery and
-   triggering — make it specific).
+   triggering, so make it specific).
 2. Put any playbooks, references, and templates the skill needs inside `skills/<name>/`.
 3. Register it under `skills` in `.claude-plugin/plugin.json` (the `./skills` path already
    covers new directories, so usually no change is needed there).
@@ -29,36 +30,74 @@ each component type.
 
 ## Adding a command
 
-1. Create `commands/<name>.md` with `name` + `description` frontmatter — see
-   [commands/README.md](commands/README.md) for the convention and
-   [commands/codebase-discovery.md](commands/codebase-discovery.md) for a worked example.
+1. Create `commands/<name>.md` with `name` + `description` frontmatter. See
+   [commands/README.md](commands/README.md) for the convention.
 2. It ships automatically via the `commands` path already registered in
    `.claude-plugin/plugin.json`.
 3. Run the verification gate.
 
+Don't add a command that only wraps a skill: a `user-invocable` skill already provides
+`/<skill-name>`, and a same-named command collides with it. Commands must also never reference
+repo files by repo-relative path, because once installed the working directory is the consumer's
+repo. Use `${CLAUDE_PLUGIN_ROOT}/…` or invoke the skill by name.
+
 ## Adding an agent
 
 1. Create `agents/<name>.md` with `name` + `description` frontmatter and a `tools` list scoped
-   to only what the agent needs — prefer read-only tools for recon/verification-style workers.
+   to only what the agent needs, preferring read-only tools for recon/verification-style workers.
 2. Add it to the `agents` array in `.claude-plugin/plugin.json` if it should ship with the
    plugin.
 3. Run the verification gate.
 
 ## Adding a hook
 
-1. Create `hooks/<name>/` with a `hooks.json` and any script(s) it calls — see
+1. Create `hooks/<name>/` with a `hooks.json` and any script(s) it calls. See
    [hooks/README.md](hooks/README.md) and [hooks/examples/](hooks/examples/).
-2. Do **not** reference it from `.claude-plugin/plugin.json` — hooks stay opt-in; document how
+2. Do **not** reference it from `.claude-plugin/plugin.json`; hooks stay opt-in, so document how
    a consumer copies it into their own project.
 3. Run the verification gate; any `hooks/**/hooks.json` must be valid JSON.
 
+## State each rule once
+
+Skills are read by an agent that follows whatever it's told, so the same instruction in two files
+is a latent contradiction: someone relaxes one copy, the other still says the old thing, and which
+one wins depends on reading order. Copies also drift silently, because nothing fails.
+
+So, within a skill:
+
+| Kind of content | Where it lives |
+|---|---|
+| **Rules** — what must always be true of the output | one reference file, marked as the only statement of it |
+| **Procedure** — how to carry out a phase | that phase's playbook |
+| **Facts** — what was decided or found this run | the working-state file |
+| **Checks** — verify a rule was followed | the verification playbook, phrased as a check that *points at* the rule |
+
+Everything else links. A playbook that needs a rule says "apply the X in `references/y.md`" rather
+than repeating it, and a reference that owns a rule says so in its heading, so the next editor
+knows not to fork it.
+
+Two exceptions, both deliberate:
+
+- **Subagents** (`agents/*.md`) can't resolve a path into a skill, so they carry standalone copies.
+  Where the wording matters, pin it with a check under `scripts/checks/` so the copies can't
+  diverge.
+- **Templates** get rendered into someone else's repo, so a terse in-place reminder is fine,
+  but keep the rule itself in the reference and point at it.
+
 ## Editing the `codebase-discovery` skill
 
 - Behaviour lives in `skills/codebase-discovery/playbooks/*.md`. Preserve the five-phase flow
-  and the exception-only status model (`[unverified]` / `[assumption]` / `[outdated]` /
-  `[contradicted]`; accepted knowledge is unmarked).
+  and the exception-only status model (`[unchecked]` / `[unverified]` / `[assumption]` /
+  `[outdated]` / `[contradicted]`; accepted knowledge is unmarked). The flag vocabulary is closed:
+  `references/provenance-and-status.md` defines it, and `scripts/checks/codebase-discovery.js`
+  enforces the set.
 - Discovery/output conventions live in `skills/codebase-discovery/references/`.
 - Output scaffolds live in `skills/codebase-discovery/templates/`.
+- The **secrets rule** is normative in `SKILL.md` only; playbooks, references and templates link
+  it rather than restating it. The two bundled subagents keep a standalone copy because they
+  can't resolve a path into the skill, so change the rule in `SKILL.md`,
+  `agents/codebase-recon-scout.md` and `agents/codebase-doc-verifier.md` together, or the
+  verification gate fails.
 
 ## Verification gate (run before every commit)
 
@@ -68,8 +107,13 @@ node scripts/validate.js
 
 It checks that the manifests are valid JSON with required keys, that every `SKILL.md`,
 `agents/*.md` and `commands/*.md` (except its README) has `name` + `description` frontmatter,
-that every path referenced by `plugin.json` exists, and that any `hooks/**/hooks.json` is valid
-JSON. CI runs the same check on push and PR; a failing gate blocks merge.
+that every path referenced by `plugin.json` exists, that relative markdown links resolve and a
+skill's links stay inside that skill, and that any `hooks/**/hooks.json` is valid JSON. CI runs the
+same check on push and PR; a failing gate blocks merge.
+
+Keep `validate.js` component-agnostic: it validates format, not any one component's content. If
+your component needs its own invariants enforced, add `scripts/checks/<component>.js` and the gate
+loads it automatically. See [scripts/checks/README.md](scripts/checks/README.md).
 
 Optional smoke tests:
 
@@ -78,7 +122,7 @@ npx skills add . --list                 # confirm skill discovery
 claude --plugin-dir /path/to/this/repo  # load the plugin locally
 ```
 
-## Commits & PRs
+## Commits and PRs
 
 Keep changes small and atomic, with a clear message. Ensure `scripts/validate.js` passes and,
 if you changed behaviour or structure, update the relevant docs (`README.md`, a component's own

README.md

@@ -3,7 +3,7 @@
 **DiUS's shared toolkit of skills, commands, agents and hooks for AI coding agents.**
 
 `agent-toolkit` is a monorepo where DiUS consultants publish and reuse the working pieces they
-build for AI coding agents — day-to-day tools, not one-off prompts. It's a growing collection,
+build for AI coding agents: day-to-day tools, not one-off prompts. It's a growing collection,
 installable as a whole or one component at a time, that stays **tool-agnostic** wherever
 possible and installs as a **Claude Code plugin** in one command.
 
@@ -12,10 +12,10 @@ possible and installs as a **Claude Code plugin** in one command.
 ## Install
 
 <details open>
-<summary><b>Any agent — <code>npx skills</code> (recommended)</b></summary>
+<summary><b>Any agent: <code>npx skills</code> (recommended)</b></summary>
 
 Installs skills into any of ~55 supported agents (Claude Code, Cursor, Codex, OpenCode,
-Gemini, Copilot…) straight from GitHub — the most tool-agnostic route:
+Gemini, Copilot…) straight from GitHub, the most tool-agnostic route:
 
 ```bash
 # interactive — detects your agents and prompts, installs the whole toolkit
@@ -31,7 +31,7 @@ npx skills add DiUS/agent-toolkit --list
 </details>
 
 <details>
-<summary><b>Claude Code (plugin — skills + commands + agents)</b></summary>
+<summary><b>Claude Code (plugin: skills + commands + agents)</b></summary>
 
 ```
 /plugin marketplace add DiUS/agent-toolkit
@@ -58,7 +58,7 @@ and any other agent).
 |---|---|
 | [`codebase-discovery`](skills/codebase-discovery/) | Reverse-engineers domain, architecture, business rules, workflows and a business glossary from an existing codebase into lean onboarding docs — ready for harness engineering / Spec Kit. |
 
-New skills, commands, agents and hooks are added over time — see
+New skills, commands, agents and hooks are added over time; see
 [CONTRIBUTING.md](CONTRIBUTING.md) to add your own.
 
 ---
@@ -108,7 +108,7 @@ agent-toolkit/
 This repo is itself harness-ready: [AGENTS.md](AGENTS.md) gives any agent the context and
 guardrails to contribute (and [CLAUDE.md](CLAUDE.md) adds Claude Code specifics), while
 [CONTRIBUTING.md](CONTRIBUTING.md) covers the mechanics of adding a skill, command, agent or
-hook. Before committing, run the verification gate — also enforced in CI:
+hook. Before committing, run the verification gate, also enforced in CI:
 
 ```bash
 node scripts/validate.js

agents/codebase-doc-verifier.md

@@ -5,24 +5,52 @@ tools: Read, Grep, Glob
 ---
 
 You are an adversarial documentation verifier for the `codebase-discovery` skill. You did not
-write the docs under review — approach them skeptically and treat each claim as unproven until
+write the docs under review, so approach them skeptically and treat each claim as unproven until
 it traces to evidence.
 
 ## Operating rules
 
 - **Read-only.** You audit; you do not edit the docs. Report findings for the main agent to act on.
 - **Evidence or it's demoted.** For each substantive claim in `docs/`, confirm a matching entry
   in `docs/_discovery/traceability-index.md` pointing to real code (`path:line` / symbol) or a
-  named stakeholder — and spot-check that the cited code actually says what the doc claims.
+  named stakeholder, then spot-check that the cited code actually says what the doc claims.
 - **No invented rules.** Flag any statement with neither code evidence nor stakeholder
   confirmation; it must be demoted to `[assumption]` / `[unverified]` or removed.
+- **No leaked secrets.** The docs must record a credential **by name and location, never the value**:
+  no API keys, tokens, passwords, connection strings, URLs with embedded credentials, or
+  truncated/partial versions of any of these. Report any hit as a **blocking** finding: it must be
+  removed from the docs *and* raised with the user for rotation.
+  <!-- Synced copy of the normative rule in skills/codebase-discovery/SKILL.md; a subagent can't
+  resolve a path into the skill. Change both together; scripts/validate.js enforces it. -->
 - **Honest flags.** Verify that unflagged (accepted) statements really are settled, and that
   every known `[outdated]` / `[contradicted]` item is either resolved or clearly flagged in
-  both the doc and the assumptions register.
+  both the doc and the assumptions register. The vocabulary is closed to five flags:
+  `[unchecked]` (no current code check behind it, either never compared or the code has moved
+  since it was), `[unverified]` (looked at, but unconfirmed by a person), `[assumption]`,
+  `[outdated]`, `[contradicted]`. Flag anything outside that set.
 - **Onboarding-lean.** Flag bloat, duplication across docs, and any doc exceeding the length
-  guidance in `references/output-conventions.md`.
-- **Freshness & consistency.** Every doc has a `Last updated` date; terminology matches the
-  glossary across docs; the recon manifest reflects the files actually read.
+  guidance given in your assignment (the dispatching prompt carries the ceilings, or an
+  **absolute** path to the skill's `references/output-conventions.md`, since a skill-relative path
+  won't resolve from here).
+- **Scaffolding stripped.** Flag any leftover template scaffolding in the published docs:
+  `<!-- -->` guidance comments, or unfilled `<placeholder>` markers.
+- **Links resolve.** Check every link in the docs set, the project-root `README.md` and the agent
+  file points at a file that exists; documents that were skipped are the usual culprit.
+- **Freshness and consistency.** Every doc in the `docs/` set has a `Last updated` date; terminology
+  matches the glossary across docs; the recon manifest reflects the files actually read. The
+  project-root `README.md` and the agent onboarding file carry no discovery metadata by design, so
+  finding no date there is the intended state; don't report it.
+- **Names use the agreed language.** Area directories and concept filenames should be glossary
+  terms, not namespaces or codenames, and there should be no catch-alls (`misc`, `other`,
+  `general`). Your assignment carries the naming rules, or an absolute path to the skill's
+  `references/output-conventions.md`.
+- **Groupings are evidenced.** A cluster named in business language must trace to a stakeholder who
+  confirmed it; check the register and traceability index. Otherwise it should be named after the
+  code unit it came from and flagged `[unverified]`.
+- **Writes landed inside the agreed root.** Phase 0 records the output root, the docs-site nav
+  decision and the pre-existing files at the target paths in `docs/_discovery/discovery-state.md`;
+  check the output against them. **You cannot verify sign-off**, because an overwrite is approved
+  in conversation, not in a file. Report placement, not consent, and let the caller judge.
 
 ## Report format
 
@@ -34,5 +62,7 @@ Return a short verification report:
 4. Bloat/duplication to trim.
 5. Go / no-go for harness engineering / Spec Kit, with caveats.
 
-If material problems exist, recommend returning to synthesis or the interview rather than
-shipping docs built on unresolved assumptions.
+Mark each finding **blocking** (the docs shouldn't ship like this: an invented or unevidenced
+claim, a leaked credential, a claim carrying real weight with no traceability) or **fix-in-place**
+(bloat, duplication, a dead link, a missing date). Don't decide whether to rework: report, and let
+the caller apply its own threshold and iteration limit.