From 9eb8bc7e485fcbbafedc6cf83334998dd7b5c446 Mon Sep 17 00:00:00 2001 From: Defame1297 Date: Thu, 10 Sep 2026 20:13:16 +0000 Subject: [PATCH 01/84] docs: add simplification audit of hooks, tests, plugins, and prose Read-only analysis with 38 ranked findings, a measured pre-push baseline, and open questions for the hand-off discussion. No repo changes proposed are applied here. Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01EmiHiknxqtZPEBnW7ujgNz --- SIMPLIFICATION-AUDIT.md | 180 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 180 insertions(+) create mode 100644 SIMPLIFICATION-AUDIT.md diff --git a/SIMPLIFICATION-AUDIT.md b/SIMPLIFICATION-AUDIT.md new file mode 100644 index 0000000..0bcefae --- /dev/null +++ b/SIMPLIFICATION-AUDIT.md @@ -0,0 +1,180 @@ +# Simplification audit + +Date: 2026-09-10. Read-only analysis; nothing has been changed. Purpose: a hand-off for deciding what to remove, merge, and shrink. Findings are ranked by payoff within each area; effort is S/M/L. Claims were independently re-verified against the repo by a clean reviewer; corrections have been applied. + +Assumptions agreed before analysis: anything is on the table, Claude Code and Copilot CLI both stay supported, findings are ranked with effort. + +Counting convention: line counts are hand-edited `.apm/` source unless marked "incl. mirror". Every `.apm/` file has a byte-identical generated copy at the plugin root, so plugin cuts count double in the repo total. + +## 1. The shape of the problem + +| Measure | Value | +|---|---| +| Tracked files / lines | 820 / 102,000 | +| Lines in `plugins/` | 70,600 (69% of repo) | +| Of which the 39 `SKILL.md` files a model actually loads | ~2,600 lines (under 4% of plugin lines) | +| Generated flat mirror files (byte copies of `.apm/`) | 263 files, ~22,000 lines | +| `docs/research/` vendored inside plugins | ~19,000 lines, nothing executable reads it | +| Repo-level `docs/research/` + `docs/notes/` | 4,500 lines, 47% of all prose words, 6 of 11 research files linked only from each other | +| Enforcement: hook entries in `.pre-commit-config.yaml` / pre-push hooks | 33 / 14 | +| Enforcement: `tests/*.sh` + runners + `scripts/` | 12,400 + 475 + 4,500 lines | +| Validator scripts inside kyberforge (+ their bats tests) | 6,800 + 5,300 lines | +| Preload tax (39 skill names + descriptions) | 10,987 chars, ~2,750 tokens per session | +| Commits since 2026-05-10 / share touching hook, test, gate, vale, or sync | 447 / ~25% | + +The pattern across every area is the same: the payload (skill bodies, rules, decisions) is small and the scaffolding around it (mirrors, research dumps, sync gates, tests of tests, justification prose) is 10 to 30 times larger. A quarter of all commits have gone into maintaining the scaffolding. + +## 2. Measured baseline: hooks and tests + +Measured on this machine, clean tree, all hooks passing. `pre-commit run --all-files` per stage. + +| Gate | Wall time | +|---|---| +| **Full pre-push stage (everything below, sequential)** | **~5 min 10 s** | +| `run-tests` (26 bash suites + 351 bats tests) | 276 s | +| `apm-audit-ci` (7 manifests) | 12.2 s | +| `validate-plugins` (6 × `claude plugin validate`) | 4.9 s | +| `check-plugin-content-sync` | 4.5 s | +| `apm-pack-check-clean` | 3.1 s | +| Other 9 pre-push hooks combined | 7.6 s | +| **Full pre-commit stage, all files** | **18.2 s** | + +`run-tests` is 90% of the wall time. Every push pays it in full: the runner has no change detection and the config sets `always_run: true`. `apm-audit-ci` is the second-slowest hook; per its own comment block its earlier description overclaimed, and what it verifies today is that seven manifests parse and the lockfile exists. + +Where the 276 s goes (each suite run alone, sequential): + +| Suite | Time | Note | +|---|---|---| +| `test-sync-plugin-content.sh` | 83 s | 14 temp trees, 2 `git init`, repeated `apm pack` | +| all 351 bats tests (10 files, kyberforge and core validators) | 64 s | mostly `validate.sh` / `validate-provenance.sh` fixtures | +| `test-adr0020-differential.sh` | 29 s | 12 assertions; re-runs two validators over the live corpus and a fixture tree | +| `test-check-vale-style-sync.sh` | 25 s | guards a byte-identical copy | +| `test-vale-wrap.sh` | 14 s | | +| `test-adr0020-frontmatter.sh` + `-targets.sh` | 25 s | | +| Remaining 20 suites | 36 s | 12 of them run in under 2 s each | + +Five suites account for 215 s of 276 s. Three of those five (sync-plugin-content, vale-style-sync, adr0020-differential) test tooling that findings 2, 7, and 14 propose to delete or shrink, so the fastest path to a quick pre-push is removing the duplication those tests guard rather than optimising the tests. + +## 3. Enforcement layer: hooks, tests, scripts + +This is the area you named as hardest to understand and slowest. Root cause: most pre-push hooks exist to keep two copies of something in sync, or to re-validate what another hook already validates. + +1. **Six hooks validate overlapping sets of the same manifests.** `check-manifests`, `validate-plugins`, `validate-marketplace`, `apm-pack-check-clean`, `apm-marketplace-check`, `apm-audit-ci`. Keep the two `claude plugin validate` hooks plus `apm-pack-check-clean`. Delete `check-manifests` (282 lines + 771 test lines; its `lib/marketplace-plugins.sh` stays because `sync-plugin-content.sh` sources it). `apm-audit-ci` spends 12 s confirming that manifests `apm pack` already parses do parse; drop or keep on that basis. Move the network-dependent `apm-marketplace-check` to a release checklist. Effort S. + +2. **Four "keep two copies in sync" gates: 1,100 script lines + 1,600 test lines.** Each one is a symptom of duplication that could be removed instead of guarded: + - `check-vale-style-sync`: 413 lines + 798 test lines guarding a byte-identical 526-line `vale-wrap.sh` and style directory copied between skill-audit and agent-audit. About 350 of its lines run Vale glob probes against the hook file patterns. Disappears if the two audit skills merge (finding 14); the probes belong in `test-vale-wrap.sh`. + - `check-scope-walkup-sync`: 365 lines cross-checking four independent ports of the same package-root walk-up. Disappears if the ports share one script or the skills merge. + - `check-marketplace-mirror-sync`: guards `.github/plugin/marketplace.json`. The script header calls it Copilot's legacy convention path and says Copilot also accepts the Claude path; the vendored Copilot docs list it as primary. Verify against current Copilot CLI before deleting hook, script, test, and mirror file. + - `check-executables-allow-sync`: 474 lines to assert one string equals kyberforge's version. A six-line grep, or drop it (the failure mode is visible and recoverable). + Effort S each, M for the walk-up. + +3. **Tests of the test harness: 1,090 lines testing 475 lines.** `test-run-tests.sh` and `test-run-bats.sh` defend "green either way" holes that exist only because the runners hand-roll TAP parsing and set-equality checks. Replace both runners with about 40 lines (`bats -r plugins` plus a parallel `find | xargs` over `test-*.sh`) and delete the meta-tests. `lib/batch-run.sh` stays; `sync-plugin-content.sh` sources it. Effort M. + +4. **`skill-frontmatter` is a 62-line bash script inlined in YAML** with its own 366-line test. `skill-size-check.sh` already parses the same frontmatter with PyYAML. Fold it in (about 15 Python lines), delete the inline hook, its test, and the 79 lines in `gates.md` arguing for the split. Effort S. + +5. **`skill-size-check.sh` has six test files totalling 3,589 lines for one 1,497-line script**, split by ADR section rather than behaviour. `test-adr0020-differential.sh` is 452 lines for 12 assertions. Merge to two files. Effort M. + +6. **Prose-grep tests.** `test-governance-layer.sh` and `test-instructions-and-docs.sh` (583 lines) grep markdown for phrases, including a one-shot "issue 0015 refactor incomplete" assertion made permanent and an assertion that `docs/notes/` exists. Delete both. `check-apm-agents-valid.sh` (161 + 264 test lines) is a loop plus fail-closed guards around `validate.sh`; it folds into the merged audit skill's own tests (finding 14). Effort S. + +7. **`check-plugin-content-sync.sh` is 813 lines wrapping `apm pack`, with a 1,291-line test.** The mirror itself must stay (Claude Code marketplace installs need flat directories), and the script does real work a bare `git diff` would lose: it strips `tests/` from the mirror, regenerates both `plugin.json` files with `mcpServers` reinjected, and packs into a scratch copy so `--check` never mutates. Even so, 2,100 lines for that is disproportionate; target a third. Effort M. + +8. **`docs/spec/gates.md` (1,048 lines) is roughly 15% "what is enforced" and 85% post-mortems** of defects already fixed and pinned by tests. The 60-line hook table is the useful part. Target 200 lines. The same applies to the 106 comment lines in `.pre-commit-config.yaml` and to `scripts/`, where 8 of 15 files are 40 to 60% comments. Effort M. + +**Proposed target.** Pre-push 14 hooks to 6: `run-tests`, `validate-plugins`, `validate-marketplace`, `apm-pack-check-clean`, `check-plugin-content-sync`, `check-release-needed`. Pre-commit stays roughly as is minus `skill-frontmatter`, and minus `check-ast` once finding 9 removes the only `.py` files. Tests 26 files to about 10 (12,400 to about 5,000 lines). Keep bats and its three submodules; the 351 bats tests ship inside plugins and are the right tool there. Do not port the bash suites to bats; delete them instead. + +## 4. Plugins + +The shared pattern: per-skill `README.md` files no model reads, a `docs/research/` dump per plugin, a `sources.md` provenance chain with its own validator, and reference files that restate man pages. + +### 4.1 Cross-plugin (apply everywhere) + +9. **Delete `docs/research/` from every plugin (~19,000 lines).** kyberforge's alone is 14,143 lines, 32% of the plugin, and about 8,900 of those are vendored third-party content (Anthropic `skill-creator` including a 1,325-line `viewer.html` and ten `.py` files, obra/superpowers, mattpocock). The rest is copied tool documentation. The gitea references explicitly say the research doc "has a known history of drifting from the deployed server". Every `apm.yml` uses `includes: auto`; whether the directory ships to consumers needs one check. Keep upstream URLs in one line per plugin README; git history keeps the rest. Check obra/superpowers licence if anything is retained. Goes together with finding 11: 32 `sources.md` files carry "Research doc" paths into these directories. Effort S. + +10. **Delete per-skill `README.md` and `references/README.md` (48 files, 1,574 lines).** They restate the SKILL.md in narrative form. The pre-commit config itself notes a skill README "is consumer-facing prose that no agent ever loads". Keep one plugin-level README with one line per skill. Requires dropping the README criterion in `skill-audit/references/file-structure.md` and the README step in `new-skill.sh`. Effort S. + +11. **Drop the provenance chain: `sources.md`, `source_keys` frontmatter, `validate-provenance.sh`.** 32 plugin and skill `sources.md` files (about 1,300 lines) plus 9 research indexes, 216 source files with `source_keys`, two copies of the validator (1,198 and 632 lines) with ten checks, and 125 bats tests exist to track which upstream informed which file. Git blame and a URL in the README do the same job. This is more code than the content it tracks. Effort M (touches skill-audit, both validator copies, two repo tests, and every skill's frontmatter). + +12. **Strip ADR and changelog narration from model-facing files.** `ADR-0020` is cited in 3 of 7 kyberforge SKILL.md files and 16 references; ADR-0023 is cited inline 21 times in the git plugin. Examples: "was the old house rule and ADR-0020 deleted it", "were removed per ADR-0015 once issue #90 landed", "this file previously recorded `list_issues` as having neither a `type` nor a `milestones` parameter". `skill-author/references/retrofit.md` (197 lines) is a one-time migration guide; it is loaded from `improve.md` and listed in `sources.md`, so remove those in the same change. These belong in git history or the ADR, not in context. Effort S. + +13. **State repeated boilerplate once or delete it.** A near-identical "Resolve owner and repo" block in 5 of 7 gitea skills; 404-masks-403 in 6 files; manual pagination in 7; main/master refusal in 9 git files; the "use the project's domain glossary, respect ADRs" paragraph in 5 bin skills. Three git skills define three different structured-result JSON shapes whose only consumer is `git-orchestrate` (finding 19). Effort S. + +### 4.2 kyberforge (290 files, 44,568 lines incl. mirror; the 7 SKILL.md bodies are 333 lines, under 1%) + +14. **Merge `skill-audit` + `agent-audit` into one `audit` skill (removes about 3,300 lines and two pre-push hooks).** `vale-wrap.sh` is byte-identical in both; five Vale rules byte-identical (agent-audit carries one extra, so it is the superset); `validate.sh` shares a 1,061-line boundary-target resolver block that diffs as zero lines; SKILL.md steps 1, 3, 4 and the gotchas are the same text. Each copy is hard-wired to one mode, so the merged script needs a path switch. The duplication exists because a plugin-cache install copies only each skill's own files (the rule ADR-0014 follows), so a script cannot be shared across skills; merging the skills is the only way to remove the copy. Effort M. + +15. **Merge `skill-author` + `agent-author` likewise.** `contract.md` shares most of its Description section; `new-skill.sh` and `new-agent.sh` implement the same package-root walk-up with different mode names; step 1 dispatch tables and step 3 gates are near-identical. Keep the agent scope logic (plugin vs project/user) as its own reference. Effort M. + +16. **Cut the validators by an order of magnitude.** `validate.sh` is 1,677 lines of bash with embedded Python, ported twice; `skill-size-check.sh` is 1,497. Target about 200 lines total: frontmatter present, size ceilings, boundary targets resolve. The 526-line `vale-wrap.sh` exists to work around folded `>` scalars in descriptions; writing descriptions as `|` literal blocks removes the folding problem, but the wrapper is also the exported hook entry in `.pre-commit-hooks.yaml` and carries the NOT RUN guard the audits depend on, so it shrinks rather than disappears. This is where the real complexity lives and is the item most worth discussing. Effort L. + +17. **Fold `forge` and `apm-install`.** `forge` is a four-row routing table plus 207 lines of references explaining fork vs inline; it should be 25 lines with no references. `apm-install` (53 lines + 17-line sources) becomes a sixth dispatch row in `apm-workflow`. Effort S. + +18. **Delete prose the model already knows.** "Valid characters: lowercase letters, numbers, hyphens"; what pipx does and PEP 668; "code blocks carry a language tag"; "data to stdout, diagnostics to stderr". Ironically `body-discipline.md` instructs auditors not to include "concepts the agent already knows". Effort S. + +### 4.3 git and gitea (153 + 93 files, 9,889 + 6,047 lines incl. mirror; source 3,288 + 2,286) + +19. **Delete the two router skills and two orchestrate agents (309 lines + 195 reference lines).** No skill invokes them as a step; they appear only in boundary clauses (`AGENTS.md`, `git-worktrees`, `gitea-issues`, `gitea-prs`) and as worked examples in agent-audit references, all of which must change in the same commit or `skill-size-check` fails on the dangling target. Claude Code already routes on descriptions. The chain today is `git-workflow` step 5 invokes `git-orchestrate`, whose step 5 invokes `git-commits`, which runs `rtk git commit`: three hops. Both agents exceed 900 words; ADR-0020 deliberately sets no agent body gate. Effort S. + +20. **Collapse git 7 skills to 1; gitea 7 to 2.** Git references are man-page restatement: `git-log-format.md` (242 lines listing `%H`, `%ar`), `conventional-commits-spec.md` (170 lines), `worktrees.md` (178), `merging.md` explaining fast-forward. Roughly 60% of the plugin is generic. The genuinely house-specific content fits in about 150 lines: the `rtk` rule and ADR-0023 exceptions, main/master refusal, `--no-verify`, the `-i --autosquash` 2.39.5 trap, `--force-with-lease --force-if-includes`, bisect exit codes, submodule push ordering, the detached-HEAD worktree trap. Gitea is more legitimately specific (MCP schema quirks: `tree_sha`, `withLines`, silent drops on PR create, `per_page` 20 vs 30, 404 means 403) and splits naturally into `gitea-tracker` (issues, PRs, labels, milestones) and `gitea-repo` (branches, files, releases). Risk: one description must carry all trigger phrases; keep a dispatch table at the top of the body. Keep `pc-author` and `pc-run` (finding 38). Effort M. + +21. **Delete `config.example.json` / `.claude/plugins/git/config.json`.** Read by two steps, written by nothing. Default to GitHub Flow with the existing `develop` / `release/*` inference. Effort S. + +### 4.4 bin, core, lint (88 + 49 + 31 files incl. mirror) + +22. **bin: strip generic process theatre.** `write-docs` is 109 lines, mostly form-filling sections plus a 15-line source provenance block; its rules fit in 25 lines. `tdd` is about 70% textbook (RED/GREEN diagram, "good tests are integration-style", five thin references restating textbook design advice). `diagnose` 40%, `prototype` 50% (pixel-level UI switcher spec), `grill-with-docs` 35%. Keep the opinionated parts: "no horizontal slicing", "no phase 2 without a loop", `[DEBUG-xxxx]` tags, "never infer the output path", the triage state machine. Effort M. + +23. **bin: merge `grill-me` into `grill-with-docs`.** `grill-me` is 16 lines and a subset of the docs flow; `grill-with-docs` creates `CONTEXT.md` when missing, so the merged skill needs a no-write opt-out. `caveman` (50 lines) and `zoom-out` (9) are hand-invoked prompts rather than workflow skills; they are also the repo's `disable-model-invocation` exemplars in `CONTEXT.md`, `contract.md`, ADR-0020, ADR-0021, and `gates.md`, and `install.sh` has no path for `~/.claude/commands/`, so moving them means picking a new exemplar. `improve-codebase-architecture` defines its glossary twice (inline and in `language.md`; the README documents the split as intentional). Effort S. + +24. **core: `provider-adapter-author` is a 1,200-line wrapper around one instruction** ("replace duplicated lines with `@AGENTS.md`, keep provider-specific lines"): a 496-line validator with a 519-line bats suite for a check that is a grep. `agentsmd-author` already calls `agentsmd-audit` as mandatory closeout, and both route to `provider-adapter-author` in boundary clauses that must change with it. Target: one `agentsmd` skill with an audit mode, adapter conversion as a step, validator about 40 lines. Needs an ADR-0012 revisit. Effort L. + +25. **lint: delete the `lint-runner` agent.** Its body is "call `vale-run`, reformat output", which `--output=JSON` already gives; it exists for backends that do not exist. It is the example boundary clause in three `agent-author` templates and ADR-0016, so those need a new example. About 40% of `vale-config` is install tables and settings lists the model can fetch from vale.sh. Keep the house-verified matrices (`E100`/`E201`, `Packages` below glob, frontmatter, ignore paths). `lint/docs/research/docs/vale/` overlaps the skill's own references by about two thirds. Effort S. + +## 5. Prose and docs (9,600 lines, 109,000 words outside plugins) + +26. **Move or delete `docs/research/` and `docs/notes/` (4,500 lines, 47% of prose words).** Six of eleven research files are linked only from each other; they are self-described session audit trails, agendas, and a "temporary build reference". `docs/notes/factory-research-gaps-conflicts.md` says "Status: Superseded"; `factory-integration-decisions.md` says "Complete" and its decisions already live in ADRs, yet `AGENTS.md` tells every session to read it. `archive/team-self-organisation-sprint-brief.md` (3,400 words) is unrelated to this repo. Archive or delete; drop the three `AGENTS.md` pointers. Moving `CONTROLS.md` to `docs/spec/` means updating its literal path in nine or more files including the deployed `governance.md`. Effort S. + +27. **Four governance documents say one thing.** `core/instructions/governance.md` (949 words, always-on), `docs/ai-constitution.md` (2,906), `docs/wiki/HUMANS.md` (1,413), `CONTROLS.md` (1,224), with near-identical preambles and, in three of the four, a "what this file does not govern" block pointing at the others. The constitution repeats one of its own principle lead sentences. Keep `governance.md` as the operative file, trimmed to about 50 lines (drop the classification table that repeats the bullets above it, the footer, the non-governance block). Dedupe the constitution by about 20%. Effort M. + +28. **ADRs: 2,740 lines, 72% in eight ADRs over 150 lines.** ADR-0020 is 513 lines with a 71-line measurement log as Context; ADR-0017 has 173 lines of amendments against 45 of decision. ADR-0001 is superseded and ADR-0006 moot, both keeping full text below the banner. ADR-0002 is three lines. Truncate superseded ones to the banner, fold amendments into the decision, cap Context at 20 lines, add a 25-line `docs/adr/README.md` index with status. The rules already live in `gates.md`; the ADRs need only decision and consequences. Effort M. + +29. **The same facts are stated in full three or four times.** "Edit `.apm/`, never the mirror": README (2 paragraphs), AGENTS.md (2 paragraphs), architecture.md (2 paragraphs plus the lost-README anecdote), ADR-0017. The apm.lock / SessionStart story: README (11 lines), AGENTS.md, ADR-0018, ADR-0019, gates.md. The offline `SKIP=` command and the three-stage install each appear three times. Rule: README has the how-to, AGENTS.md has one-line rules with links, architecture.md has mechanics. Effort S. + +30. **`LESSONS.md`: 41 entries, 2 graduated, about 12 stale.** Twelve entries from 2026-05-17 describe a write-skill / write-eval workflow whose skills no longer exist. One entry is open work labelled "Status: neither part landed". The longest eight are 200 to 550-word incident reports. Delete the stale entries, move open work to an issue, cap entries at about 60 words, target 100 lines. Effort S. + +31. **`CONTEXT.md`: 28 terms, most used only by gates.md, scripts, or tests rather than by skills;** two (Preload tax, Skill context contract) are never used outside `CONTEXT.md` and ADR-0020. The preload-tax entry quotes two dated numbers then says not to quote them. The example dialogue and flagged-ambiguities sections are grill residue. Cut to about 20 one-line terms. Effort S. + +32. **Structure is described three ways** (README layout table, architecture.md plugin table, AGENTS.md structure bullets), and `VISION.md` carries a 35-line stack spec for a product that lives in another repo. One layout table in README; architecture.md keeps mechanics only; VISION drops the stack detail. Effort S. + +## 6. Distribution, versioning, and session startup + +Not covered by the area audits above; found on a final sweep of the root config and install pipeline. The install pipeline itself (`scripts/install.sh` 55 lines, `deploy-manifest.sh` 24, statusline 109) is fine and needs nothing. + +33. **Every plugin version lives in four places (five for kyberforge), plus one per skill.** `plugins//apm.yml`, two generated `plugin.json` files, the root `apm.yml` packages list, the `executables.allow` key (`kyberforge#1.6.2`), and a `metadata.version` in all 39 SKILL.md files (ADR-0022) that nothing consumes and that drifts freely (gitea skills sit at five different values). Repo tags (`v2.0.1`) follow a third scheme that the declared `tagPattern: v{version}` can never match under `per_package` versioning. ADR-0006, ADR-0022, `check-executables-allow-sync`, `skill-frontmatter`, and `apm pack --check-versions` all exist to police this. Proposal: one version per plugin in its `apm.yml`; drop `metadata.version` and ADR-0022; let `apm pack` derive the rest. Effort M. + +34. **The SessionStart hook auto-updates the install on every startup.** `check-apm-current.sh` runs `apm outdated` (network, 60 s timeout) and then `apm update --yes` (300 s timeout) at every session start, rewriting `apm.lock.yaml`. That is why the lock file is dirty at the start of this session and why `AGENTS.md` has to explain "commit or discard it deliberately". It is a 60-line script with a 368-line test, an ADR (0019), the `executables.allow` pin, and a sync hook behind it. For a repo that is its own source, the update belongs in `install.sh` or a manual `apm update`, not in session startup. Effort S to remove; the design question is whether auto-update at startup is wanted at all. + +35. **Outputs and packages for consumers that do not exist.** The `codex` output profile generates `.agents/plugins/marketplace.json` (95 lines) although Codex is not a supported consumer. The `mattpocock-skills` remote package entry is the only reason `apm-marketplace-check` needs the network, and its pin is advanced by hand (ADR-0015). The `.github/plugin/marketplace.json` mirror is a legacy path (finding 2). Removing all three leaves one generated marketplace manifest (the per-plugin `plugin.json` pairs remain) and no network-dependent hook. Effort S. + +36. **The release-tag mechanism guards an external contract with no known consumer.** `.pre-commit-hooks.yaml` exports three hooks for other repos to pin by `rev: `. `check-release-needed` (242 lines + 442 test), `test-vale-hooks-consumer` (270 lines), ADR-0014, and three tags exist to serve that. If no other repo pins these hooks today, the whole mechanism can be deferred until one does. Effort S. + +37. **Two `.mcp.json` files declare an Obsidian vault server over `docs/`** (root and `plugins/bin/`; the other five plugin `.mcp.json` files are empty stubs), while `AGENTS.md` forbids using an external memory system for this repo. If the Obsidian tools are unused, drop both and the `reinject_mcp_servers` explanation in the bin README; the bin `plugin.json` pair regenerates. Effort S. + +38. **`pc-author` / `pc-run` (689 lines) carry generic pre-commit documentation.** `hooks-by-language.md` (128 lines) and `failure-patterns.md` (133) restate pre-commit.com. Keep the skills, trim to the house-specific rules. Effort S. + +## 7. Suggested order + +1. Quick wins, all S, no design decisions needed: findings 9, 10, 26, 30, 31, 29, 12, 13, 1, 6, 4, 35, 37, 38, and the mirror-sync and executables-allow halves of 2. Removes roughly 25,000 to 30,000 lines and 6 hooks. +2. Structural changes that need a short discussion: 14, 15, 19, 20, 23, 25, 17, 3, 5, 7, 33, 34, 36. +3. The real complexity: 16 (validators), 11 (provenance), 24 (core), 8 and 28 (gates.md and ADRs). + +Findings 9, 10, 11, and 12 are coupled through the provenance validator and the audit criteria; land them together or the audit gates start reporting the removals. + +## 8. Questions to settle before starting + +- **Native Claude Code marketplace install vs apm-only.** The flat mirror, `check-plugin-content-sync`, and ADR-0017 exist only for native `claude plugin install`. If apm install is the only supported path, the mirror and its 2,100 lines of tooling go away. Which install paths must work for consumers? +- **Copilot CLI legacy path.** Is `.github/plugin/marketplace.json` still read by any Copilot version you target? If not, finding 2c is a pure delete. +- **Provenance chain.** Is "which upstream informed this file" a requirement you still want, or was it a governance experiment? Finding 11 hinges on this. +- **ADR-0012 (three core skills) and the one-script-per-skill install constraint.** The merges in 14, 15, and 24 need the first revisited and are the only way around the second. Are you open to superseding ADR-0012? +- **Granularity of git/gitea skills.** One `git` skill vs seven trades routing precision for size. Is one broad description acceptable? +- **Auto-update at session start.** Do you want the install refreshed from the remote every time a session opens (finding 34), or is a manual `apm update` acceptable? +- **External hook consumers.** Does any other repo pin this repo's `.pre-commit-hooks.yaml` by tag today? If not, finding 36 defers the release mechanism entirely. +- **Obsidian MCP.** Are the Obsidian tools over `docs/` used by anyone? If not, finding 37 is a pure delete. -- 2.43.0 From edcc57c0d6fa5ca3d3d8837436a80ce41494063a Mon Sep 17 00:00:00 2001 From: Defame1297 Date: Sat, 12 Sep 2026 18:38:09 +0000 Subject: [PATCH 02/84] docs: trim skill READMEs and ADR/changelog narration Two related simplification-audit findings, bundled because they edit some of the same skill-audit files and splitting would fragment single-file diffs. Finding 10: delete 48 per-skill/reference README.md files (they restated SKILL.md in narrative form and no agent ever loads them) plus 2 scaffold templates. Drop the README criterion from skill-audit's file-structure.md and finding-criteria.md, and the README-generation step from skill-author's new-skill.sh; update new-skill.bats to match. Plugin-root READMEs are kept intentionally, out of scope. Finding 12: strip historical ADR-0020/ADR-0023 citations and changelog-style narration from model-facing skill content across kyberforge and git plugin skills. Delete skill-author's one-time retrofit.md migration guide and its references. Some ADR-0023 tags were not narration but check-rtk-prefix's required opt-out marker for intentionally-bare git commands -- those were restored, not stripped. Mirror re-synced and full pre-commit/pre-push suite verified green. Refs: SIMPLIFICATION-AUDIT.md findings 10, 12 Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_01YR2CjVumUbEGWcMikcoXBD --- plugins/bin/.apm/skills/caveman/README.md | 29 --- plugins/bin/.apm/skills/diagnose/README.md | 35 ---- plugins/bin/.apm/skills/grill-me/README.md | 27 --- .../bin/.apm/skills/grill-with-docs/README.md | 37 ---- .../improve-codebase-architecture/README.md | 36 ---- plugins/bin/.apm/skills/prototype/README.md | 32 --- plugins/bin/.apm/skills/research/README.md | 31 --- plugins/bin/.apm/skills/tdd/README.md | 32 --- plugins/bin/.apm/skills/triage/README.md | 35 ---- plugins/bin/.apm/skills/write-docs/README.md | 30 --- plugins/bin/.apm/skills/zoom-out/README.md | 25 --- plugins/bin/skills/caveman/README.md | 29 --- plugins/bin/skills/diagnose/README.md | 35 ---- plugins/bin/skills/grill-me/README.md | 27 --- plugins/bin/skills/grill-with-docs/README.md | 37 ---- .../improve-codebase-architecture/README.md | 36 ---- plugins/bin/skills/prototype/README.md | 32 --- plugins/bin/skills/research/README.md | 31 --- plugins/bin/skills/tdd/README.md | 32 --- plugins/bin/skills/triage/README.md | 35 ---- plugins/bin/skills/write-docs/README.md | 30 --- plugins/bin/skills/zoom-out/README.md | 25 --- .../core/.apm/skills/agentsmd-audit/README.md | 38 ---- .../.apm/skills/agentsmd-author/README.md | 27 --- .../skills/provider-adapter-author/README.md | 36 ---- plugins/core/skills/agentsmd-audit/README.md | 38 ---- plugins/core/skills/agentsmd-author/README.md | 27 --- .../skills/provider-adapter-author/README.md | 36 ---- .../git/.apm/skills/git-branches/README.md | 34 --- plugins/git/.apm/skills/git-branches/SKILL.md | 4 +- .../references/branch-operations.md | 4 +- .../skills/git-branches/references/merging.md | 2 +- plugins/git/.apm/skills/git-commits/README.md | 31 --- plugins/git/.apm/skills/git-commits/SKILL.md | 4 +- .../git-commits/references/rewrite-history.md | 2 +- plugins/git/.apm/skills/git-history/README.md | 29 --- plugins/git/.apm/skills/git-history/SKILL.md | 4 +- .../skills/git-history/references/README.md | 16 -- .../git-history/references/git-log-format.md | 20 +- plugins/git/.apm/skills/git-remotes/README.md | 34 --- plugins/git/.apm/skills/git-remotes/SKILL.md | 2 +- .../skills/git-remotes/references/README.md | 20 -- .../skills/git-remotes/references/push.md | 2 +- .../git/.apm/skills/git-submodules/README.md | 35 ---- .../git-submodules/references/README.md | 31 --- .../git/.apm/skills/git-workflow/README.md | 25 --- .../skills/git-workflow/references/README.md | 19 -- .../git/.apm/skills/git-worktrees/README.md | 24 --- .../git/.apm/skills/git-worktrees/SKILL.md | 6 +- .../skills/git-worktrees/references/README.md | 13 -- plugins/git/.apm/skills/pc-author/README.md | 26 --- .../skills/pc-author/references/README.md | 16 -- plugins/git/.apm/skills/pc-run/README.md | 32 --- .../.apm/skills/pc-run/references/README.md | 17 -- plugins/git/skills/git-branches/README.md | 34 --- plugins/git/skills/git-branches/SKILL.md | 4 +- .../references/branch-operations.md | 4 +- .../skills/git-branches/references/merging.md | 2 +- plugins/git/skills/git-commits/README.md | 31 --- plugins/git/skills/git-commits/SKILL.md | 4 +- .../git-commits/references/rewrite-history.md | 2 +- plugins/git/skills/git-history/README.md | 29 --- plugins/git/skills/git-history/SKILL.md | 4 +- .../skills/git-history/references/README.md | 16 -- .../git-history/references/git-log-format.md | 20 +- plugins/git/skills/git-remotes/README.md | 34 --- plugins/git/skills/git-remotes/SKILL.md | 2 +- .../skills/git-remotes/references/README.md | 20 -- .../git/skills/git-remotes/references/push.md | 2 +- plugins/git/skills/git-submodules/README.md | 35 ---- .../git-submodules/references/README.md | 31 --- plugins/git/skills/git-workflow/README.md | 25 --- .../skills/git-workflow/references/README.md | 19 -- plugins/git/skills/git-worktrees/README.md | 24 --- plugins/git/skills/git-worktrees/SKILL.md | 6 +- .../skills/git-worktrees/references/README.md | 13 -- plugins/git/skills/pc-author/README.md | 26 --- .../git/skills/pc-author/references/README.md | 16 -- plugins/git/skills/pc-run/README.md | 32 --- .../git/skills/pc-run/references/README.md | 17 -- .../.apm/skills/gitea-branches/README.md | 50 ----- .../gitea/.apm/skills/gitea-files/README.md | 24 --- .../gitea/.apm/skills/gitea-issues/README.md | 51 ----- .../skills/gitea-labels-milestones/README.md | 31 --- plugins/gitea/.apm/skills/gitea-prs/README.md | 31 --- .../.apm/skills/gitea-releases/README.md | 30 --- .../.apm/skills/gitea-workflow/README.md | 25 --- plugins/gitea/skills/gitea-branches/README.md | 50 ----- plugins/gitea/skills/gitea-files/README.md | 24 --- plugins/gitea/skills/gitea-issues/README.md | 51 ----- .../skills/gitea-labels-milestones/README.md | 31 --- plugins/gitea/skills/gitea-prs/README.md | 31 --- plugins/gitea/skills/gitea-releases/README.md | 30 --- plugins/gitea/skills/gitea-workflow/README.md | 25 --- .../.apm/skills/agent-audit/README.md | 79 ------- .../.apm/skills/agent-audit/SKILL.md | 4 +- .../skills/agent-audit/references/README.md | 20 -- .../references/body-and-delegation.md | 6 +- .../references/description-quality.md | 2 +- .../references/finding-criteria.md | 4 +- .../.apm/skills/agent-author/README.md | 58 ------ .../.apm/skills/agent-author/SKILL.md | 2 +- .../skills/agent-author/references/README.md | 55 ----- .../agent-author/references/contract.md | 7 +- .../skills/agent-author/references/improve.md | 7 +- .../.apm/skills/apm-install/README.md | 22 -- .../.apm/skills/apm-workflow/README.md | 33 --- .../kyberforge/.apm/skills/forge/README.md | 40 ---- plugins/kyberforge/.apm/skills/forge/SKILL.md | 2 +- .../.apm/skills/forge/references/sources.md | 2 +- .../.apm/skills/skill-audit/README.md | 53 ----- .../.apm/skills/skill-audit/SKILL.md | 6 +- .../skill-audit/references/body-discipline.md | 8 +- .../references/description-quality.md | 2 +- .../skill-audit/references/file-structure.md | 12 +- .../references/finding-criteria.md | 2 - .../skills/skill-audit/references/patterns.md | 2 +- .../references/validation-scripts.md | 8 +- .../.apm/skills/skill-author/README.md | 74 ------- .../.apm/skills/skill-author/SKILL.md | 2 +- .../skill-author/assets/templates/README.md | 51 ----- .../assets/templates/references/README.md | 39 ---- .../skill-author/references/contract.md | 2 +- .../skills/skill-author/references/create.md | 2 +- .../skills/skill-author/references/improve.md | 11 +- .../skill-author/references/retrofit.md | 197 ------------------ .../skills/skill-author/references/sources.md | 4 +- .../skills/skill-author/scripts/new-skill.sh | 1 - .../skills/skill-author/tests/new-skill.bats | 11 - .../kyberforge/skills/agent-audit/README.md | 79 ------- .../kyberforge/skills/agent-audit/SKILL.md | 4 +- .../skills/agent-audit/references/README.md | 20 -- .../references/body-and-delegation.md | 6 +- .../references/description-quality.md | 2 +- .../references/finding-criteria.md | 4 +- .../kyberforge/skills/agent-author/README.md | 58 ------ .../kyberforge/skills/agent-author/SKILL.md | 2 +- .../skills/agent-author/references/README.md | 55 ----- .../agent-author/references/contract.md | 7 +- .../skills/agent-author/references/improve.md | 7 +- .../kyberforge/skills/apm-install/README.md | 22 -- .../kyberforge/skills/apm-workflow/README.md | 33 --- plugins/kyberforge/skills/forge/README.md | 40 ---- plugins/kyberforge/skills/forge/SKILL.md | 2 +- .../skills/forge/references/sources.md | 2 +- .../kyberforge/skills/skill-audit/README.md | 53 ----- .../kyberforge/skills/skill-audit/SKILL.md | 6 +- .../skill-audit/references/body-discipline.md | 8 +- .../references/description-quality.md | 2 +- .../skill-audit/references/file-structure.md | 12 +- .../references/finding-criteria.md | 2 - .../skills/skill-audit/references/patterns.md | 2 +- .../references/validation-scripts.md | 8 +- .../kyberforge/skills/skill-author/README.md | 74 ------- .../kyberforge/skills/skill-author/SKILL.md | 2 +- .../skill-author/assets/templates/README.md | 51 ----- .../assets/templates/references/README.md | 39 ---- .../skill-author/references/contract.md | 2 +- .../skills/skill-author/references/create.md | 2 +- .../skills/skill-author/references/improve.md | 11 +- .../skill-author/references/retrofit.md | 197 ------------------ .../skills/skill-author/references/sources.md | 4 +- .../skills/skill-author/scripts/new-skill.sh | 1 - .../lint/.apm/skills/vale-config/README.md | 23 -- plugins/lint/.apm/skills/vale-run/README.md | 23 -- plugins/lint/skills/vale-config/README.md | 23 -- plugins/lint/skills/vale-run/README.md | 23 -- 167 files changed, 132 insertions(+), 3897 deletions(-) delete mode 100644 plugins/bin/.apm/skills/caveman/README.md delete mode 100644 plugins/bin/.apm/skills/diagnose/README.md delete mode 100644 plugins/bin/.apm/skills/grill-me/README.md delete mode 100644 plugins/bin/.apm/skills/grill-with-docs/README.md delete mode 100644 plugins/bin/.apm/skills/improve-codebase-architecture/README.md delete mode 100644 plugins/bin/.apm/skills/prototype/README.md delete mode 100644 plugins/bin/.apm/skills/research/README.md delete mode 100644 plugins/bin/.apm/skills/tdd/README.md delete mode 100644 plugins/bin/.apm/skills/triage/README.md delete mode 100644 plugins/bin/.apm/skills/write-docs/README.md delete mode 100644 plugins/bin/.apm/skills/zoom-out/README.md delete mode 100644 plugins/bin/skills/caveman/README.md delete mode 100644 plugins/bin/skills/diagnose/README.md delete mode 100644 plugins/bin/skills/grill-me/README.md delete mode 100644 plugins/bin/skills/grill-with-docs/README.md delete mode 100644 plugins/bin/skills/improve-codebase-architecture/README.md delete mode 100644 plugins/bin/skills/prototype/README.md delete mode 100644 plugins/bin/skills/research/README.md delete mode 100644 plugins/bin/skills/tdd/README.md delete mode 100644 plugins/bin/skills/triage/README.md delete mode 100644 plugins/bin/skills/write-docs/README.md delete mode 100644 plugins/bin/skills/zoom-out/README.md delete mode 100644 plugins/core/.apm/skills/agentsmd-audit/README.md delete mode 100644 plugins/core/.apm/skills/agentsmd-author/README.md delete mode 100644 plugins/core/.apm/skills/provider-adapter-author/README.md delete mode 100644 plugins/core/skills/agentsmd-audit/README.md delete mode 100644 plugins/core/skills/agentsmd-author/README.md delete mode 100644 plugins/core/skills/provider-adapter-author/README.md delete mode 100644 plugins/git/.apm/skills/git-branches/README.md delete mode 100644 plugins/git/.apm/skills/git-commits/README.md delete mode 100644 plugins/git/.apm/skills/git-history/README.md delete mode 100644 plugins/git/.apm/skills/git-history/references/README.md delete mode 100644 plugins/git/.apm/skills/git-remotes/README.md delete mode 100644 plugins/git/.apm/skills/git-remotes/references/README.md delete mode 100644 plugins/git/.apm/skills/git-submodules/README.md delete mode 100644 plugins/git/.apm/skills/git-submodules/references/README.md delete mode 100644 plugins/git/.apm/skills/git-workflow/README.md delete mode 100644 plugins/git/.apm/skills/git-workflow/references/README.md delete mode 100644 plugins/git/.apm/skills/git-worktrees/README.md delete mode 100644 plugins/git/.apm/skills/git-worktrees/references/README.md delete mode 100644 plugins/git/.apm/skills/pc-author/README.md delete mode 100644 plugins/git/.apm/skills/pc-author/references/README.md delete mode 100644 plugins/git/.apm/skills/pc-run/README.md delete mode 100644 plugins/git/.apm/skills/pc-run/references/README.md delete mode 100644 plugins/git/skills/git-branches/README.md delete mode 100644 plugins/git/skills/git-commits/README.md delete mode 100644 plugins/git/skills/git-history/README.md delete mode 100644 plugins/git/skills/git-history/references/README.md delete mode 100644 plugins/git/skills/git-remotes/README.md delete mode 100644 plugins/git/skills/git-remotes/references/README.md delete mode 100644 plugins/git/skills/git-submodules/README.md delete mode 100644 plugins/git/skills/git-submodules/references/README.md delete mode 100644 plugins/git/skills/git-workflow/README.md delete mode 100644 plugins/git/skills/git-workflow/references/README.md delete mode 100644 plugins/git/skills/git-worktrees/README.md delete mode 100644 plugins/git/skills/git-worktrees/references/README.md delete mode 100644 plugins/git/skills/pc-author/README.md delete mode 100644 plugins/git/skills/pc-author/references/README.md delete mode 100644 plugins/git/skills/pc-run/README.md delete mode 100644 plugins/git/skills/pc-run/references/README.md delete mode 100644 plugins/gitea/.apm/skills/gitea-branches/README.md delete mode 100644 plugins/gitea/.apm/skills/gitea-files/README.md delete mode 100644 plugins/gitea/.apm/skills/gitea-issues/README.md delete mode 100644 plugins/gitea/.apm/skills/gitea-labels-milestones/README.md delete mode 100644 plugins/gitea/.apm/skills/gitea-prs/README.md delete mode 100644 plugins/gitea/.apm/skills/gitea-releases/README.md delete mode 100644 plugins/gitea/.apm/skills/gitea-workflow/README.md delete mode 100644 plugins/gitea/skills/gitea-branches/README.md delete mode 100644 plugins/gitea/skills/gitea-files/README.md delete mode 100644 plugins/gitea/skills/gitea-issues/README.md delete mode 100644 plugins/gitea/skills/gitea-labels-milestones/README.md delete mode 100644 plugins/gitea/skills/gitea-prs/README.md delete mode 100644 plugins/gitea/skills/gitea-releases/README.md delete mode 100644 plugins/gitea/skills/gitea-workflow/README.md delete mode 100644 plugins/kyberforge/.apm/skills/agent-audit/README.md delete mode 100644 plugins/kyberforge/.apm/skills/agent-audit/references/README.md delete mode 100644 plugins/kyberforge/.apm/skills/agent-author/README.md delete mode 100644 plugins/kyberforge/.apm/skills/agent-author/references/README.md delete mode 100644 plugins/kyberforge/.apm/skills/apm-install/README.md delete mode 100644 plugins/kyberforge/.apm/skills/apm-workflow/README.md delete mode 100644 plugins/kyberforge/.apm/skills/forge/README.md delete mode 100644 plugins/kyberforge/.apm/skills/skill-audit/README.md delete mode 100644 plugins/kyberforge/.apm/skills/skill-author/README.md delete mode 100644 plugins/kyberforge/.apm/skills/skill-author/assets/templates/README.md delete mode 100644 plugins/kyberforge/.apm/skills/skill-author/assets/templates/references/README.md delete mode 100644 plugins/kyberforge/.apm/skills/skill-author/references/retrofit.md delete mode 100644 plugins/kyberforge/skills/agent-audit/README.md delete mode 100644 plugins/kyberforge/skills/agent-audit/references/README.md delete mode 100644 plugins/kyberforge/skills/agent-author/README.md delete mode 100644 plugins/kyberforge/skills/agent-author/references/README.md delete mode 100644 plugins/kyberforge/skills/apm-install/README.md delete mode 100644 plugins/kyberforge/skills/apm-workflow/README.md delete mode 100644 plugins/kyberforge/skills/forge/README.md delete mode 100644 plugins/kyberforge/skills/skill-audit/README.md delete mode 100644 plugins/kyberforge/skills/skill-author/README.md delete mode 100644 plugins/kyberforge/skills/skill-author/assets/templates/README.md delete mode 100644 plugins/kyberforge/skills/skill-author/assets/templates/references/README.md delete mode 100644 plugins/kyberforge/skills/skill-author/references/retrofit.md delete mode 100644 plugins/lint/.apm/skills/vale-config/README.md delete mode 100644 plugins/lint/.apm/skills/vale-run/README.md delete mode 100644 plugins/lint/skills/vale-config/README.md delete mode 100644 plugins/lint/skills/vale-run/README.md diff --git a/plugins/bin/.apm/skills/caveman/README.md b/plugins/bin/.apm/skills/caveman/README.md deleted file mode 100644 index 63ba67c..0000000 --- a/plugins/bin/.apm/skills/caveman/README.md +++ /dev/null @@ -1,29 +0,0 @@ -# caveman - -Ultra-compressed output mode: drop articles, filler and pleasantries, keep the technical substance exact. - -## What it does - -Switches the agent into a terse register — no articles, no hedging, no pleasantries, fragments allowed, arrows for causality — while leaving technical terms, code blocks and quoted error strings untouched. The mode is *sticky*: once turned on it stays on for every subsequent response until the user says "stop caveman" or "normal mode", rather than decaying back to normal prose after a few turns. - -It carries one built-in escape hatch. Security warnings, confirmations for irreversible actions, multi-step sequences where fragment order could be misread, and any request to clarify are answered in normal prose, then the compressed register resumes. - -## Hand-invoked only - -`SKILL.md` sets `disable-model-invocation: true`. This is the single most important thing to know about this skill: **the model cannot route to it.** No other skill can hand off to it, and no phrasing in a user's request will cause it to be selected automatically. The only way in is the human typing `/caveman`. - -That is deliberate — output style is the user's choice, not an inference the router should make on their behalf. It is also why the description reads as one plain human-facing sentence rather than carrying the trigger phrasing and boundary clause a routable skill needs. - -## Usage - -```text -/caveman -``` - -Then keep working normally. To leave the mode, say "stop caveman" or "normal mode". - -## Files - -| File | Purpose | -|------|---------| -| `SKILL.md` | The whole skill — persistence rule, compression rules, worked examples, and the auto-clarity exception | diff --git a/plugins/bin/.apm/skills/diagnose/README.md b/plugins/bin/.apm/skills/diagnose/README.md deleted file mode 100644 index 6e2c414..0000000 --- a/plugins/bin/.apm/skills/diagnose/README.md +++ /dev/null @@ -1,35 +0,0 @@ -# diagnose - -A six-phase discipline for hard bugs and performance regressions: feedback loop → reproduce → hypothesise → instrument → fix with a regression test → clean up. - -## What it does - -Imposes an order of operations on debugging so the agent cannot skip to guessing. The load-bearing phase is the first one: build a fast, deterministic, agent-runnable pass/fail signal for the bug. Everything downstream — bisection, hypothesis testing, instrumentation — just consumes that signal, so the skill refuses to advance to Phase 2 without one, and says so explicitly rather than hypothesising blind. - -The remaining phases each carry a constraint worth knowing about: hypotheses are generated 3–5 at a time and must be falsifiable, so the first plausible idea cannot anchor the whole investigation; every debug log is tagged with a unique prefix (`[DEBUG-a4f2]`) so cleanup is a single grep; the regression test is written before the fix and only at a seam that exercises the real bug pattern; and the run closes by asking what would have prevented the bug, handing off to `improve-codebase-architecture` when the answer is architectural. - -Performance regressions take a branch of their own inside Phase 4 — baseline measurement and bisection, not logs. - -## Conditional reading - -Neither reference file is read on every run; `SKILL.md` names the condition for each. - -- `references/feedback-loops.md` is read when Phase 1 has no signal yet, or when the loop you have is slow or intermittent. -- `references/regression-seams.md` is read when Phase 5 leaves you unsure whether the available seam is deep enough — or whether one exists at all. - -## Usage - -```text -/diagnose -``` - -Describe the bug or the regression. For filing and triaging a reported bug rather than diagnosing it, use `triage`; for test-first feature work, use `tdd`. - -## Files - -| File | Purpose | -|------|---------| -| `SKILL.md` | The six phases and their gates — what must be true before each one ends | -| `references/feedback-loops.md` | Loaded when Phase 1 has no loop or the loop is too weak: ten ways to construct one ordered by cost, how to sharpen an existing loop, handling intermittent bugs, and what to ask the user for when the bug resists reproduction | -| `references/regression-seams.md` | Loaded when Phase 5 is unsure about the seam: what makes a seam correct, the four shapes of a too-shallow seam, and what to do when no correct seam exists | -| `assets/hitl-loop.template.sh` | Copy-and-edit bash template for the last-resort human-in-the-loop feedback loop, cited by `references/feedback-loops.md`. Provides `step` and `capture` helpers and prints captured values as `KEY=VALUE` for the agent to parse | diff --git a/plugins/bin/.apm/skills/grill-me/README.md b/plugins/bin/.apm/skills/grill-me/README.md deleted file mode 100644 index 6197081..0000000 --- a/plugins/bin/.apm/skills/grill-me/README.md +++ /dev/null @@ -1,27 +0,0 @@ -# grill-me - -Interview the user relentlessly about a plan or design until the decision tree is fully resolved. - -## What it does - -Turns the agent into an interviewer rather than an implementer. It walks the design tree branch by branch, resolving dependencies between decisions one at a time, and offers its own recommended answer alongside each question so the user has something concrete to push against. Two rules give it its shape: **one question at a time**, and **never ask what the codebase can answer** — if a question is settleable by reading the code, the agent goes and reads the code instead of spending the user's attention on it. - -## Composition - -This is the plain grilling loop, with no documentation side effects. The sibling `grill-with-docs` skill runs the same interview but additionally challenges answers against the project's `CONTEXT.md` glossary and existing ADRs, and writes decisions back into those files as they crystallise. Reach for that one when the project has a domain model worth defending; reach for this one when it does not, or when nothing should be written down yet. - -`triage` composes the documented variant, not this one, when an issue needs fleshing out. - -## Usage - -```text -/grill-me -``` - -Describe the plan or design to be stress-tested. Expect questions one at a time, each with a recommended answer. - -## Files - -| File | Purpose | -|------|---------| -| `SKILL.md` | The whole skill — the interview instruction, the one-question-at-a-time rule, and the explore-instead-of-asking rule | diff --git a/plugins/bin/.apm/skills/grill-with-docs/README.md b/plugins/bin/.apm/skills/grill-with-docs/README.md deleted file mode 100644 index 679eecb..0000000 --- a/plugins/bin/.apm/skills/grill-with-docs/README.md +++ /dev/null @@ -1,37 +0,0 @@ -# grill-with-docs - -The grilling interview, run against the project's domain model — and writing decisions back into `CONTEXT.md` and ADRs as they land. - -## What it does - -Runs the same relentless one-question-at-a-time interview as `grill-me`, with the project's own documentation as an active participant. During codebase exploration it also locates the domain documentation — a root `CONTEXT.md` and `docs/adr/`, or a `CONTEXT-MAP.md` pointing at per-context glossaries and ADR directories in a multi-context repo — and then uses it five ways: - -- **Challenges terms against the glossary.** When the user's usage conflicts with what `CONTEXT.md` already defines, that is raised immediately rather than absorbed. -- **Sharpens fuzzy language** by proposing a precise canonical term ("you're saying 'account' — do you mean the Customer or the User?"). -- **Stress-tests domain relationships with concrete scenarios**, inventing edge cases that force the user to be precise about where one concept ends and the next begins. -- **Cross-references claims against the code**, and surfaces contradictions between what the user says happens and what the code does. -- **Updates `CONTEXT.md` inline**, the moment a term is resolved, rather than batching changes to the end of the session where they get lost. - -Files are created lazily — only when there is something real to write. - -ADRs are offered *sparingly*, and only when all three tests pass: the decision is hard to reverse, it would surprise a future reader without the context, and it was a genuine trade-off with real alternatives. Missing any one of the three means no ADR. - -## Composition - -`grill-me` is the same interview without the documentation side effects — use it when there is no domain model to defend or nothing should be written down yet. `triage` composes this skill (not `grill-me`) at step 4 when an issue needs fleshing out. `improve-codebase-architecture` runs its own grilling loop and borrows this skill's `CONTEXT.md` and ADR discipline for the decisions that come out of it. - -## Usage - -```text -/grill-with-docs -``` - -Describe the plan or design. Expect questions one at a time, each with a recommended answer, and expect `CONTEXT.md` to be edited during the session rather than after it. - -## Files - -| File | Purpose | -|------|---------| -| `SKILL.md` | The interview instruction plus the domain-awareness rules: file layout discovery, the five during-session behaviours, and the three-part ADR test | -| `references/context-format.md` | Cited when a term is resolved: the structure of a `CONTEXT.md` and how to write a Language entry | -| `references/adr-format.md` | Cited when an ADR is offered: `docs/adr/` naming, sequential numbering, and the ADR template | diff --git a/plugins/bin/.apm/skills/improve-codebase-architecture/README.md b/plugins/bin/.apm/skills/improve-codebase-architecture/README.md deleted file mode 100644 index 93b6c05..0000000 --- a/plugins/bin/.apm/skills/improve-codebase-architecture/README.md +++ /dev/null @@ -1,36 +0,0 @@ -# improve-codebase-architecture - -Surface architectural friction and propose deepening opportunities — refactors that turn shallow modules into deep ones. - -## What it does - -Looks for places where a codebase is hard to understand, hard to test, or hard for an agent to navigate, and proposes refactors that concentrate behaviour behind smaller interfaces. It runs in three stages: - -1. **Explore.** Reads the domain glossary and any ADRs in the area first, then walks the codebase with an `Explore` sub-agent — organically, noting friction rather than applying fixed heuristics. The **deletion test** is the filter: imagine deleting the module; if complexity vanishes it was a pass-through, if complexity reappears across N callers it was earning its keep. -2. **Present candidates.** A numbered list, each with files, problem, solution and benefits — benefits stated in terms of *locality* and *leverage* and of how tests would improve. No interfaces are proposed yet; the user picks one. -3. **Grilling loop.** Walks the design tree for the chosen candidate, with documentation side effects landing inline as decisions crystallise. - -The skill is opinionated about vocabulary, and that is the point: **module, interface, implementation, depth, seam, adapter, leverage, locality**, used exactly, with no drift into "component", "service", "API" or "boundary". Domain nouns come from `CONTEXT.md`, architecture nouns from `references/language.md` — so a proposal reads as "the Order intake module", never "the FooBarHandler". - -ADRs are treated as decisions not to be re-litigated. A candidate that contradicts one is surfaced only when the friction is real enough to warrant reopening it, and is marked as such. - -## Composition - -`diagnose` hands off here when a bug's post-mortem concludes that no correct test seam exists, or that callers are tangled — the recommendation is made after the fix is in, not before. The grilling loop follows `grill-with-docs`'s discipline for `CONTEXT.md` entries and ADR offers, and `SKILL.md` names that skill's format documents directly. - -## Usage - -```text -/improve-codebase-architecture -``` - -Point at a codebase or an area of one. Expect a numbered candidate list and a "which of these would you like to explore?" before any interface design happens. - -## Files - -| File | Purpose | -|------|---------| -| `SKILL.md` | Condensed glossary, key principles, and the three-stage process | -| `references/language.md` | Cited throughout `SKILL.md`: full definitions of every term, the words each one replaces, and the full principle list | -| `references/interface-design.md` | Read at stage 3 when the user wants alternative interfaces explored: the parallel sub-agent "Design It Twice" pattern, framing the problem space, and the per-agent design constraints | -| `references/deepening.md` | Cited from `references/interface-design.md`: how to deepen a cluster of shallow modules safely, the four dependency categories (in-process, local-substitutable, remote-but-owned, true external), seam discipline, and the replace-don't-layer testing strategy | diff --git a/plugins/bin/.apm/skills/prototype/README.md b/plugins/bin/.apm/skills/prototype/README.md deleted file mode 100644 index 425a6e8..0000000 --- a/plugins/bin/.apm/skills/prototype/README.md +++ /dev/null @@ -1,32 +0,0 @@ -# prototype - -Build a throwaway prototype that answers one design question — either a runnable terminal app or several UI variations. - -## What it does - -Treats a prototype as **throwaway code that answers a question**, and lets the question decide the artifact. `SKILL.md` opens with a two-row dispatch table and the run resolves exactly one row before doing anything else: - -- *"Does this logic / state model feel right?"* → a tiny interactive terminal app that pushes the state machine through the cases that are hard to reason about on paper. -- *"What should this look like?"* → several radically different UI variations on one route, switchable from a floating bottom bar via a URL search param. - -The two branches produce fundamentally different artifacts, so picking wrong wastes the whole prototype. When the question is genuinely ambiguous and the user is unreachable, the skill defaults on the shape of the surrounding code (backend module → logic, page or component → UI) and states the assumption at the top of the prototype rather than silently choosing. - -Six rules apply to both branches: throwaway and visibly named as such, one command to run, no persistence by default, no polish, surface the full state after every action or variant switch, and delete or absorb the prototype when it is done. The *answer* is the only durable output — the skill captures it in a commit message, ADR, issue or `NOTES.md` before the code is deleted. - -## Usage - -```text -/prototype -``` - -State the design question. For production code, use `tdd`; for talking a design through without building anything, use `grill-me`. - -## Files - -| File | Purpose | -|------|---------| -| `SKILL.md` | The branch dispatch table and the rules that apply to both branches | -| `references/logic.md` | The logic branch, read only when that row is selected: when it is the right shape, and how to build the interactive terminal app | -| `references/ui.md` | The UI branch, read only when that row is selected: when it is the right shape, and how to build and switch between the variations | - -Each reference is self-contained — a run reads one of the two, never both. diff --git a/plugins/bin/.apm/skills/research/README.md b/plugins/bin/.apm/skills/research/README.md deleted file mode 100644 index 976cd2f..0000000 --- a/plugins/bin/.apm/skills/research/README.md +++ /dev/null @@ -1,31 +0,0 @@ -# research - -Research a tool, library or API from canonical documentation into a directory of structured per-topic reference files. - -## What it does - -Runs a six-step pipeline: scope against the working directory (what version is actually in use, what is already documented), resolve the topic through Context7, websearch for canonical docs covering whatever Context7 missed, read those sources, deepen one level into the links worth following, then write one markdown file per topic area plus a `sources.md` provenance record. - -Four gotchas at the top of `SKILL.md` shape the whole run, and each exists because of a specific failure: the output path is never inferred (a guessed destination scatters a directory's worth of files through someone's source tree); nothing is written outside that path; no empty topic file is ever written (a stub `troubleshooting.md` reads downstream as researched and closed); and a Context7 "no results", redirect or header-only response does not count as coverage. If no topic area has content, the run writes nothing at all — `sources.md` included — and reports what it searched. - -The frontmatter pins `model: sonnet` and a closed `allowed-tools` list. Notably it grants no subagent tool, so every `WebFetch` is serial and each fetched page lands in the run's own context — which is why steps 4 and 5 insist on reducing each page to notes before fetching the next, and cap deepening at roughly ten extra pages. - -## Composition - -Both reference files are read on condition, never on every run — `SKILL.md` inlines the minimum each step needs (the seven default topic areas at step 1, the four `sources.md` field names and the topic-file frontmatter keys at step 6) and sends the run to the reference only for what it does not carry. Those four field names are matched literally by the downstream provenance validator, so prose written in their place parses as nothing and the check passes having verified nothing — which is why they are inlined rather than deferred. - -## Usage - -```text -/research -``` - -Name the topic and the output path — the skill will stop and ask if the path is missing. Supplying starting URLs is treated as a deliberate source choice and skips Context7 resolution and discovery. For documentation derived from existing code or specs, use `write-docs`; for a bug or incident, use `diagnose`. - -## Files - -| File | Purpose | -|------|---------| -| `SKILL.md` | The four gotchas and the six research steps | -| `references/topics.md` | Read at Step 1 only when what belongs in a default topic is unclear or a custom topic is needed: the per-topic coverage table and the custom-topic naming rule | -| `references/file-format.md` | Read at Step 6 only when the inlined field names do not settle the case: slug derivation, the Context7 slug and URL convention, and what belongs in a topic body | diff --git a/plugins/bin/.apm/skills/tdd/README.md b/plugins/bin/.apm/skills/tdd/README.md deleted file mode 100644 index 09f7291..0000000 --- a/plugins/bin/.apm/skills/tdd/README.md +++ /dev/null @@ -1,32 +0,0 @@ -# tdd - -Test-driven development as a strict red-green-refactor loop, one behaviour at a time. - -## What it does - -Two convictions drive this skill. The first is about what a test is for: tests verify behaviour through public interfaces, not implementation details. A good test reads like a specification ("user can checkout with valid cart") and survives refactors because it does not care about internal structure. The warning sign for a bad one is precise — the test breaks when you refactor but behaviour has not changed. - -The second is an explicit anti-pattern: **do not write all the tests first, then all the implementation.** Horizontal slicing treats RED as "write every test" and GREEN as "write every implementation", and it produces tests of *imagined* behaviour — tests of the shape of things, insensitive to real change, committed to before the implementation was understood. The correct shape is vertical: one test → one implementation → repeat, each cycle informed by what the last one taught you. - -The workflow is four stages: plan (confirm the interface and which behaviours matter, with the user — you cannot test everything), fire a tracer bullet (one test proving the path works end to end), loop incrementally one behaviour at a time, then refactor once everything is green. Refactoring while RED is forbidden. - -Codebase exploration uses the project's domain glossary, so test names and interface vocabulary match the project's language, and ADRs in the area are respected. - -## Usage - -```text -/tdd -``` - -Describe the feature or bug. Expect the skill to ask what the public interface should look like and which behaviours matter most before any code is written. For diagnosing an existing bug rather than building test-first, use `diagnose`; for throwaway exploratory code, use `prototype`. - -## Files - -| File | Purpose | -|------|---------| -| `SKILL.md` | Philosophy, the horizontal-slicing anti-pattern, the four-stage workflow, and the per-cycle checklist | -| `references/tests.md` | Cited from Philosophy: worked good and bad test examples | -| `references/mocking.md` | Cited from Philosophy: mock at system boundaries only, and what not to mock | -| `references/deep-modules.md` | Cited from stage 1: what a deep module is (small interface, large implementation) and why it is the design to aim for | -| `references/interface-design.md` | Cited from stage 1: designing interfaces for testability, starting with accepting dependencies rather than creating them | -| `references/refactoring.md` | Cited from stage 4: the refactor-candidate checklist — duplication, long methods, shallow modules, feature envy, primitive obsession | diff --git a/plugins/bin/.apm/skills/triage/README.md b/plugins/bin/.apm/skills/triage/README.md deleted file mode 100644 index 8c27ebb..0000000 --- a/plugins/bin/.apm/skills/triage/README.md +++ /dev/null @@ -1,35 +0,0 @@ -# triage - -Move issues on the project issue tracker through a small state machine of triage roles. - -## What it does - -Gives issue triage an explicit state model and a fixed set of moves. Every issue carries exactly one **category** role (`bug`, `enhancement`) and one **state** role (`needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `wontfix`); conflicting state roles are flagged to the maintainer before anything else happens. Unlabeled issues normally enter at `needs-triage`; `needs-info` returns there once the reporter replies. The maintainer can override at any point, and unusual transitions are questioned rather than executed silently. - -A run does one of three things depending on what the maintainer asks for: - -- **Show what needs attention** — three buckets, oldest first: unlabeled, `needs-triage`, and `needs-info` with reporter activity since the last triage notes. -- **Triage a specific issue** — gather context (including prior triage notes, so resolved questions are not re-asked, and `.out-of-scope/` records that resemble the issue), recommend a category and state with reasoning, attempt reproduction for bugs *before* any grilling, run a `grill-with-docs` session if the issue needs fleshing out, then apply the outcome. -- **Quick state override** — "move #42 to ready-for-agent" is trusted and applied directly, skipping grilling, after confirming the exact changes. - -Two hard rules: every comment or issue the skill posts during triage must open with the AI-generated disclaimer, and the canonical role names above are *not* necessarily the label strings in the tracker — each is resolved against the tracker's live label set before it is applied, and a name with no counterpart there is reported to the maintainer as a gap rather than guessed at. - -## Composition - -`grill-with-docs` is invoked at step 4 when an issue needs fleshing out; whatever that session establishes is carried into the triage notes so the work is not lost. The reverse direction also exists: `diagnose` names this skill as the place to send a *reported* bug that needs filing rather than debugging. - -## Usage - -```text -/triage -``` - -Then describe what you want in natural language — "show me anything that needs my attention", "let's look at #42", "move #42 to ready-for-agent", "what's ready for agents to pick up?". - -## Files - -| File | Purpose | -|------|---------| -| `SKILL.md` | The roles and state machine, the three invocation modes, the needs-info template, and how to resume a prior session | -| `references/agent-brief.md` | Cited when an issue moves to `ready-for-agent` (and reused for `ready-for-human`): how to write a brief that stays durable for weeks while the codebase moves under it — describe interfaces and behavioural contracts, not line numbers | -| `references/out-of-scope.md` | Cited when an enhancement is closed `wontfix` and when checking for prior rejections: how the `.out-of-scope/` knowledge base is laid out and what it is for — institutional memory, and deduplication against re-litigated requests | diff --git a/plugins/bin/.apm/skills/write-docs/README.md b/plugins/bin/.apm/skills/write-docs/README.md deleted file mode 100644 index 8ed0156..0000000 --- a/plugins/bin/.apm/skills/write-docs/README.md +++ /dev/null @@ -1,30 +0,0 @@ -# write-docs - -Produce technical documentation derived from code and spec, one section at a time, with a confirmation gate on every section. - -## What it does - -Casts the agent as a technical writer with one non-negotiable constraint: **every claim must be traceable to a source file line, a spec section, or an explicit user statement.** Nothing is invented, and behaviour that genuinely cannot be documented from the available sources is marked out-of-scope rather than explained away. - -The process is eight steps — identify scope, read and extract, gap check, draft section by section, confirmation gate, delta summary, reader testing, finalise — and several of them are deliberately gated on the human: - -- Files are read only after the user approves them by name. The skill may propose candidates; it waits. -- The **gap check** presents what the code does say and asks the user to fill only what it does not: caller intent, error-handling rationale, non-obvious side effects. -- No section is finalised until the full revised text has been shown. The skill never gates on output the user has not seen, and never reprints the whole document — all edits are surgical. -- **Reader testing** predicts 5–10 questions a target reader would ask, then spawns a sub-agent that receives only the finished doc and the questions — no source files. If the doc cannot answer them, neither can the sub-agent, and the run loops back to drafting. - -Summary and overview sections are written last, once the detail sections are stable. - -## Usage - -```text -/write-docs -``` - -Name the files or modules to document, the target audience (developer / user / contributor / internal), and the documentation type (reference, guide, README section, inline comment, changelog entry). For a PRD, ADR or decision doc, use `grill-me` or `grill-with-docs` instead — those have dedicated handling. - -## Files - -| File | Purpose | -|------|---------| -| `SKILL.md` | The whole skill — role, use/do-not-use boundaries, required inputs, constraints, the eight-step process, output format, failure handling, and a nine-item self-check | diff --git a/plugins/bin/.apm/skills/zoom-out/README.md b/plugins/bin/.apm/skills/zoom-out/README.md deleted file mode 100644 index ce71a99..0000000 --- a/plugins/bin/.apm/skills/zoom-out/README.md +++ /dev/null @@ -1,25 +0,0 @@ -# zoom-out - -Ask the agent to go up a layer of abstraction and map the modules and callers around unfamiliar code. - -## What it does - -A single-purpose prompt for the moment you land in a part of the codebase you do not know. Instead of answering at the level of the file in front of it, the agent climbs one layer and produces a map of the relevant modules and their callers — and names them using the project's own domain glossary vocabulary, so the map lines up with the language the rest of the repo already uses. - -## Hand-invoked only - -`SKILL.md` sets `disable-model-invocation: true`, so the router never selects this skill on its own and no other skill can hand off to it. It runs when the human asks for it. That also means its description is written as one plain human-facing sentence — it carries no trigger phrasing or boundary clause, because nothing routes on it. - -## Usage - -```text -/zoom-out -``` - -Best used with the unfamiliar code already in context — the skill widens the view around what you are looking at rather than picking a starting point for you. - -## Files - -| File | Purpose | -|------|---------| -| `SKILL.md` | The whole skill — a single instruction, no supporting files | diff --git a/plugins/bin/skills/caveman/README.md b/plugins/bin/skills/caveman/README.md deleted file mode 100644 index 63ba67c..0000000 --- a/plugins/bin/skills/caveman/README.md +++ /dev/null @@ -1,29 +0,0 @@ -# caveman - -Ultra-compressed output mode: drop articles, filler and pleasantries, keep the technical substance exact. - -## What it does - -Switches the agent into a terse register — no articles, no hedging, no pleasantries, fragments allowed, arrows for causality — while leaving technical terms, code blocks and quoted error strings untouched. The mode is *sticky*: once turned on it stays on for every subsequent response until the user says "stop caveman" or "normal mode", rather than decaying back to normal prose after a few turns. - -It carries one built-in escape hatch. Security warnings, confirmations for irreversible actions, multi-step sequences where fragment order could be misread, and any request to clarify are answered in normal prose, then the compressed register resumes. - -## Hand-invoked only - -`SKILL.md` sets `disable-model-invocation: true`. This is the single most important thing to know about this skill: **the model cannot route to it.** No other skill can hand off to it, and no phrasing in a user's request will cause it to be selected automatically. The only way in is the human typing `/caveman`. - -That is deliberate — output style is the user's choice, not an inference the router should make on their behalf. It is also why the description reads as one plain human-facing sentence rather than carrying the trigger phrasing and boundary clause a routable skill needs. - -## Usage - -```text -/caveman -``` - -Then keep working normally. To leave the mode, say "stop caveman" or "normal mode". - -## Files - -| File | Purpose | -|------|---------| -| `SKILL.md` | The whole skill — persistence rule, compression rules, worked examples, and the auto-clarity exception | diff --git a/plugins/bin/skills/diagnose/README.md b/plugins/bin/skills/diagnose/README.md deleted file mode 100644 index 6e2c414..0000000 --- a/plugins/bin/skills/diagnose/README.md +++ /dev/null @@ -1,35 +0,0 @@ -# diagnose - -A six-phase discipline for hard bugs and performance regressions: feedback loop → reproduce → hypothesise → instrument → fix with a regression test → clean up. - -## What it does - -Imposes an order of operations on debugging so the agent cannot skip to guessing. The load-bearing phase is the first one: build a fast, deterministic, agent-runnable pass/fail signal for the bug. Everything downstream — bisection, hypothesis testing, instrumentation — just consumes that signal, so the skill refuses to advance to Phase 2 without one, and says so explicitly rather than hypothesising blind. - -The remaining phases each carry a constraint worth knowing about: hypotheses are generated 3–5 at a time and must be falsifiable, so the first plausible idea cannot anchor the whole investigation; every debug log is tagged with a unique prefix (`[DEBUG-a4f2]`) so cleanup is a single grep; the regression test is written before the fix and only at a seam that exercises the real bug pattern; and the run closes by asking what would have prevented the bug, handing off to `improve-codebase-architecture` when the answer is architectural. - -Performance regressions take a branch of their own inside Phase 4 — baseline measurement and bisection, not logs. - -## Conditional reading - -Neither reference file is read on every run; `SKILL.md` names the condition for each. - -- `references/feedback-loops.md` is read when Phase 1 has no signal yet, or when the loop you have is slow or intermittent. -- `references/regression-seams.md` is read when Phase 5 leaves you unsure whether the available seam is deep enough — or whether one exists at all. - -## Usage - -```text -/diagnose -``` - -Describe the bug or the regression. For filing and triaging a reported bug rather than diagnosing it, use `triage`; for test-first feature work, use `tdd`. - -## Files - -| File | Purpose | -|------|---------| -| `SKILL.md` | The six phases and their gates — what must be true before each one ends | -| `references/feedback-loops.md` | Loaded when Phase 1 has no loop or the loop is too weak: ten ways to construct one ordered by cost, how to sharpen an existing loop, handling intermittent bugs, and what to ask the user for when the bug resists reproduction | -| `references/regression-seams.md` | Loaded when Phase 5 is unsure about the seam: what makes a seam correct, the four shapes of a too-shallow seam, and what to do when no correct seam exists | -| `assets/hitl-loop.template.sh` | Copy-and-edit bash template for the last-resort human-in-the-loop feedback loop, cited by `references/feedback-loops.md`. Provides `step` and `capture` helpers and prints captured values as `KEY=VALUE` for the agent to parse | diff --git a/plugins/bin/skills/grill-me/README.md b/plugins/bin/skills/grill-me/README.md deleted file mode 100644 index 6197081..0000000 --- a/plugins/bin/skills/grill-me/README.md +++ /dev/null @@ -1,27 +0,0 @@ -# grill-me - -Interview the user relentlessly about a plan or design until the decision tree is fully resolved. - -## What it does - -Turns the agent into an interviewer rather than an implementer. It walks the design tree branch by branch, resolving dependencies between decisions one at a time, and offers its own recommended answer alongside each question so the user has something concrete to push against. Two rules give it its shape: **one question at a time**, and **never ask what the codebase can answer** — if a question is settleable by reading the code, the agent goes and reads the code instead of spending the user's attention on it. - -## Composition - -This is the plain grilling loop, with no documentation side effects. The sibling `grill-with-docs` skill runs the same interview but additionally challenges answers against the project's `CONTEXT.md` glossary and existing ADRs, and writes decisions back into those files as they crystallise. Reach for that one when the project has a domain model worth defending; reach for this one when it does not, or when nothing should be written down yet. - -`triage` composes the documented variant, not this one, when an issue needs fleshing out. - -## Usage - -```text -/grill-me -``` - -Describe the plan or design to be stress-tested. Expect questions one at a time, each with a recommended answer. - -## Files - -| File | Purpose | -|------|---------| -| `SKILL.md` | The whole skill — the interview instruction, the one-question-at-a-time rule, and the explore-instead-of-asking rule | diff --git a/plugins/bin/skills/grill-with-docs/README.md b/plugins/bin/skills/grill-with-docs/README.md deleted file mode 100644 index 679eecb..0000000 --- a/plugins/bin/skills/grill-with-docs/README.md +++ /dev/null @@ -1,37 +0,0 @@ -# grill-with-docs - -The grilling interview, run against the project's domain model — and writing decisions back into `CONTEXT.md` and ADRs as they land. - -## What it does - -Runs the same relentless one-question-at-a-time interview as `grill-me`, with the project's own documentation as an active participant. During codebase exploration it also locates the domain documentation — a root `CONTEXT.md` and `docs/adr/`, or a `CONTEXT-MAP.md` pointing at per-context glossaries and ADR directories in a multi-context repo — and then uses it five ways: - -- **Challenges terms against the glossary.** When the user's usage conflicts with what `CONTEXT.md` already defines, that is raised immediately rather than absorbed. -- **Sharpens fuzzy language** by proposing a precise canonical term ("you're saying 'account' — do you mean the Customer or the User?"). -- **Stress-tests domain relationships with concrete scenarios**, inventing edge cases that force the user to be precise about where one concept ends and the next begins. -- **Cross-references claims against the code**, and surfaces contradictions between what the user says happens and what the code does. -- **Updates `CONTEXT.md` inline**, the moment a term is resolved, rather than batching changes to the end of the session where they get lost. - -Files are created lazily — only when there is something real to write. - -ADRs are offered *sparingly*, and only when all three tests pass: the decision is hard to reverse, it would surprise a future reader without the context, and it was a genuine trade-off with real alternatives. Missing any one of the three means no ADR. - -## Composition - -`grill-me` is the same interview without the documentation side effects — use it when there is no domain model to defend or nothing should be written down yet. `triage` composes this skill (not `grill-me`) at step 4 when an issue needs fleshing out. `improve-codebase-architecture` runs its own grilling loop and borrows this skill's `CONTEXT.md` and ADR discipline for the decisions that come out of it. - -## Usage - -```text -/grill-with-docs -``` - -Describe the plan or design. Expect questions one at a time, each with a recommended answer, and expect `CONTEXT.md` to be edited during the session rather than after it. - -## Files - -| File | Purpose | -|------|---------| -| `SKILL.md` | The interview instruction plus the domain-awareness rules: file layout discovery, the five during-session behaviours, and the three-part ADR test | -| `references/context-format.md` | Cited when a term is resolved: the structure of a `CONTEXT.md` and how to write a Language entry | -| `references/adr-format.md` | Cited when an ADR is offered: `docs/adr/` naming, sequential numbering, and the ADR template | diff --git a/plugins/bin/skills/improve-codebase-architecture/README.md b/plugins/bin/skills/improve-codebase-architecture/README.md deleted file mode 100644 index 93b6c05..0000000 --- a/plugins/bin/skills/improve-codebase-architecture/README.md +++ /dev/null @@ -1,36 +0,0 @@ -# improve-codebase-architecture - -Surface architectural friction and propose deepening opportunities — refactors that turn shallow modules into deep ones. - -## What it does - -Looks for places where a codebase is hard to understand, hard to test, or hard for an agent to navigate, and proposes refactors that concentrate behaviour behind smaller interfaces. It runs in three stages: - -1. **Explore.** Reads the domain glossary and any ADRs in the area first, then walks the codebase with an `Explore` sub-agent — organically, noting friction rather than applying fixed heuristics. The **deletion test** is the filter: imagine deleting the module; if complexity vanishes it was a pass-through, if complexity reappears across N callers it was earning its keep. -2. **Present candidates.** A numbered list, each with files, problem, solution and benefits — benefits stated in terms of *locality* and *leverage* and of how tests would improve. No interfaces are proposed yet; the user picks one. -3. **Grilling loop.** Walks the design tree for the chosen candidate, with documentation side effects landing inline as decisions crystallise. - -The skill is opinionated about vocabulary, and that is the point: **module, interface, implementation, depth, seam, adapter, leverage, locality**, used exactly, with no drift into "component", "service", "API" or "boundary". Domain nouns come from `CONTEXT.md`, architecture nouns from `references/language.md` — so a proposal reads as "the Order intake module", never "the FooBarHandler". - -ADRs are treated as decisions not to be re-litigated. A candidate that contradicts one is surfaced only when the friction is real enough to warrant reopening it, and is marked as such. - -## Composition - -`diagnose` hands off here when a bug's post-mortem concludes that no correct test seam exists, or that callers are tangled — the recommendation is made after the fix is in, not before. The grilling loop follows `grill-with-docs`'s discipline for `CONTEXT.md` entries and ADR offers, and `SKILL.md` names that skill's format documents directly. - -## Usage - -```text -/improve-codebase-architecture -``` - -Point at a codebase or an area of one. Expect a numbered candidate list and a "which of these would you like to explore?" before any interface design happens. - -## Files - -| File | Purpose | -|------|---------| -| `SKILL.md` | Condensed glossary, key principles, and the three-stage process | -| `references/language.md` | Cited throughout `SKILL.md`: full definitions of every term, the words each one replaces, and the full principle list | -| `references/interface-design.md` | Read at stage 3 when the user wants alternative interfaces explored: the parallel sub-agent "Design It Twice" pattern, framing the problem space, and the per-agent design constraints | -| `references/deepening.md` | Cited from `references/interface-design.md`: how to deepen a cluster of shallow modules safely, the four dependency categories (in-process, local-substitutable, remote-but-owned, true external), seam discipline, and the replace-don't-layer testing strategy | diff --git a/plugins/bin/skills/prototype/README.md b/plugins/bin/skills/prototype/README.md deleted file mode 100644 index 425a6e8..0000000 --- a/plugins/bin/skills/prototype/README.md +++ /dev/null @@ -1,32 +0,0 @@ -# prototype - -Build a throwaway prototype that answers one design question — either a runnable terminal app or several UI variations. - -## What it does - -Treats a prototype as **throwaway code that answers a question**, and lets the question decide the artifact. `SKILL.md` opens with a two-row dispatch table and the run resolves exactly one row before doing anything else: - -- *"Does this logic / state model feel right?"* → a tiny interactive terminal app that pushes the state machine through the cases that are hard to reason about on paper. -- *"What should this look like?"* → several radically different UI variations on one route, switchable from a floating bottom bar via a URL search param. - -The two branches produce fundamentally different artifacts, so picking wrong wastes the whole prototype. When the question is genuinely ambiguous and the user is unreachable, the skill defaults on the shape of the surrounding code (backend module → logic, page or component → UI) and states the assumption at the top of the prototype rather than silently choosing. - -Six rules apply to both branches: throwaway and visibly named as such, one command to run, no persistence by default, no polish, surface the full state after every action or variant switch, and delete or absorb the prototype when it is done. The *answer* is the only durable output — the skill captures it in a commit message, ADR, issue or `NOTES.md` before the code is deleted. - -## Usage - -```text -/prototype -``` - -State the design question. For production code, use `tdd`; for talking a design through without building anything, use `grill-me`. - -## Files - -| File | Purpose | -|------|---------| -| `SKILL.md` | The branch dispatch table and the rules that apply to both branches | -| `references/logic.md` | The logic branch, read only when that row is selected: when it is the right shape, and how to build the interactive terminal app | -| `references/ui.md` | The UI branch, read only when that row is selected: when it is the right shape, and how to build and switch between the variations | - -Each reference is self-contained — a run reads one of the two, never both. diff --git a/plugins/bin/skills/research/README.md b/plugins/bin/skills/research/README.md deleted file mode 100644 index 976cd2f..0000000 --- a/plugins/bin/skills/research/README.md +++ /dev/null @@ -1,31 +0,0 @@ -# research - -Research a tool, library or API from canonical documentation into a directory of structured per-topic reference files. - -## What it does - -Runs a six-step pipeline: scope against the working directory (what version is actually in use, what is already documented), resolve the topic through Context7, websearch for canonical docs covering whatever Context7 missed, read those sources, deepen one level into the links worth following, then write one markdown file per topic area plus a `sources.md` provenance record. - -Four gotchas at the top of `SKILL.md` shape the whole run, and each exists because of a specific failure: the output path is never inferred (a guessed destination scatters a directory's worth of files through someone's source tree); nothing is written outside that path; no empty topic file is ever written (a stub `troubleshooting.md` reads downstream as researched and closed); and a Context7 "no results", redirect or header-only response does not count as coverage. If no topic area has content, the run writes nothing at all — `sources.md` included — and reports what it searched. - -The frontmatter pins `model: sonnet` and a closed `allowed-tools` list. Notably it grants no subagent tool, so every `WebFetch` is serial and each fetched page lands in the run's own context — which is why steps 4 and 5 insist on reducing each page to notes before fetching the next, and cap deepening at roughly ten extra pages. - -## Composition - -Both reference files are read on condition, never on every run — `SKILL.md` inlines the minimum each step needs (the seven default topic areas at step 1, the four `sources.md` field names and the topic-file frontmatter keys at step 6) and sends the run to the reference only for what it does not carry. Those four field names are matched literally by the downstream provenance validator, so prose written in their place parses as nothing and the check passes having verified nothing — which is why they are inlined rather than deferred. - -## Usage - -```text -/research -``` - -Name the topic and the output path — the skill will stop and ask if the path is missing. Supplying starting URLs is treated as a deliberate source choice and skips Context7 resolution and discovery. For documentation derived from existing code or specs, use `write-docs`; for a bug or incident, use `diagnose`. - -## Files - -| File | Purpose | -|------|---------| -| `SKILL.md` | The four gotchas and the six research steps | -| `references/topics.md` | Read at Step 1 only when what belongs in a default topic is unclear or a custom topic is needed: the per-topic coverage table and the custom-topic naming rule | -| `references/file-format.md` | Read at Step 6 only when the inlined field names do not settle the case: slug derivation, the Context7 slug and URL convention, and what belongs in a topic body | diff --git a/plugins/bin/skills/tdd/README.md b/plugins/bin/skills/tdd/README.md deleted file mode 100644 index 09f7291..0000000 --- a/plugins/bin/skills/tdd/README.md +++ /dev/null @@ -1,32 +0,0 @@ -# tdd - -Test-driven development as a strict red-green-refactor loop, one behaviour at a time. - -## What it does - -Two convictions drive this skill. The first is about what a test is for: tests verify behaviour through public interfaces, not implementation details. A good test reads like a specification ("user can checkout with valid cart") and survives refactors because it does not care about internal structure. The warning sign for a bad one is precise — the test breaks when you refactor but behaviour has not changed. - -The second is an explicit anti-pattern: **do not write all the tests first, then all the implementation.** Horizontal slicing treats RED as "write every test" and GREEN as "write every implementation", and it produces tests of *imagined* behaviour — tests of the shape of things, insensitive to real change, committed to before the implementation was understood. The correct shape is vertical: one test → one implementation → repeat, each cycle informed by what the last one taught you. - -The workflow is four stages: plan (confirm the interface and which behaviours matter, with the user — you cannot test everything), fire a tracer bullet (one test proving the path works end to end), loop incrementally one behaviour at a time, then refactor once everything is green. Refactoring while RED is forbidden. - -Codebase exploration uses the project's domain glossary, so test names and interface vocabulary match the project's language, and ADRs in the area are respected. - -## Usage - -```text -/tdd -``` - -Describe the feature or bug. Expect the skill to ask what the public interface should look like and which behaviours matter most before any code is written. For diagnosing an existing bug rather than building test-first, use `diagnose`; for throwaway exploratory code, use `prototype`. - -## Files - -| File | Purpose | -|------|---------| -| `SKILL.md` | Philosophy, the horizontal-slicing anti-pattern, the four-stage workflow, and the per-cycle checklist | -| `references/tests.md` | Cited from Philosophy: worked good and bad test examples | -| `references/mocking.md` | Cited from Philosophy: mock at system boundaries only, and what not to mock | -| `references/deep-modules.md` | Cited from stage 1: what a deep module is (small interface, large implementation) and why it is the design to aim for | -| `references/interface-design.md` | Cited from stage 1: designing interfaces for testability, starting with accepting dependencies rather than creating them | -| `references/refactoring.md` | Cited from stage 4: the refactor-candidate checklist — duplication, long methods, shallow modules, feature envy, primitive obsession | diff --git a/plugins/bin/skills/triage/README.md b/plugins/bin/skills/triage/README.md deleted file mode 100644 index 8c27ebb..0000000 --- a/plugins/bin/skills/triage/README.md +++ /dev/null @@ -1,35 +0,0 @@ -# triage - -Move issues on the project issue tracker through a small state machine of triage roles. - -## What it does - -Gives issue triage an explicit state model and a fixed set of moves. Every issue carries exactly one **category** role (`bug`, `enhancement`) and one **state** role (`needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `wontfix`); conflicting state roles are flagged to the maintainer before anything else happens. Unlabeled issues normally enter at `needs-triage`; `needs-info` returns there once the reporter replies. The maintainer can override at any point, and unusual transitions are questioned rather than executed silently. - -A run does one of three things depending on what the maintainer asks for: - -- **Show what needs attention** — three buckets, oldest first: unlabeled, `needs-triage`, and `needs-info` with reporter activity since the last triage notes. -- **Triage a specific issue** — gather context (including prior triage notes, so resolved questions are not re-asked, and `.out-of-scope/` records that resemble the issue), recommend a category and state with reasoning, attempt reproduction for bugs *before* any grilling, run a `grill-with-docs` session if the issue needs fleshing out, then apply the outcome. -- **Quick state override** — "move #42 to ready-for-agent" is trusted and applied directly, skipping grilling, after confirming the exact changes. - -Two hard rules: every comment or issue the skill posts during triage must open with the AI-generated disclaimer, and the canonical role names above are *not* necessarily the label strings in the tracker — each is resolved against the tracker's live label set before it is applied, and a name with no counterpart there is reported to the maintainer as a gap rather than guessed at. - -## Composition - -`grill-with-docs` is invoked at step 4 when an issue needs fleshing out; whatever that session establishes is carried into the triage notes so the work is not lost. The reverse direction also exists: `diagnose` names this skill as the place to send a *reported* bug that needs filing rather than debugging. - -## Usage - -```text -/triage -``` - -Then describe what you want in natural language — "show me anything that needs my attention", "let's look at #42", "move #42 to ready-for-agent", "what's ready for agents to pick up?". - -## Files - -| File | Purpose | -|------|---------| -| `SKILL.md` | The roles and state machine, the three invocation modes, the needs-info template, and how to resume a prior session | -| `references/agent-brief.md` | Cited when an issue moves to `ready-for-agent` (and reused for `ready-for-human`): how to write a brief that stays durable for weeks while the codebase moves under it — describe interfaces and behavioural contracts, not line numbers | -| `references/out-of-scope.md` | Cited when an enhancement is closed `wontfix` and when checking for prior rejections: how the `.out-of-scope/` knowledge base is laid out and what it is for — institutional memory, and deduplication against re-litigated requests | diff --git a/plugins/bin/skills/write-docs/README.md b/plugins/bin/skills/write-docs/README.md deleted file mode 100644 index 8ed0156..0000000 --- a/plugins/bin/skills/write-docs/README.md +++ /dev/null @@ -1,30 +0,0 @@ -# write-docs - -Produce technical documentation derived from code and spec, one section at a time, with a confirmation gate on every section. - -## What it does - -Casts the agent as a technical writer with one non-negotiable constraint: **every claim must be traceable to a source file line, a spec section, or an explicit user statement.** Nothing is invented, and behaviour that genuinely cannot be documented from the available sources is marked out-of-scope rather than explained away. - -The process is eight steps — identify scope, read and extract, gap check, draft section by section, confirmation gate, delta summary, reader testing, finalise — and several of them are deliberately gated on the human: - -- Files are read only after the user approves them by name. The skill may propose candidates; it waits. -- The **gap check** presents what the code does say and asks the user to fill only what it does not: caller intent, error-handling rationale, non-obvious side effects. -- No section is finalised until the full revised text has been shown. The skill never gates on output the user has not seen, and never reprints the whole document — all edits are surgical. -- **Reader testing** predicts 5–10 questions a target reader would ask, then spawns a sub-agent that receives only the finished doc and the questions — no source files. If the doc cannot answer them, neither can the sub-agent, and the run loops back to drafting. - -Summary and overview sections are written last, once the detail sections are stable. - -## Usage - -```text -/write-docs -``` - -Name the files or modules to document, the target audience (developer / user / contributor / internal), and the documentation type (reference, guide, README section, inline comment, changelog entry). For a PRD, ADR or decision doc, use `grill-me` or `grill-with-docs` instead — those have dedicated handling. - -## Files - -| File | Purpose | -|------|---------| -| `SKILL.md` | The whole skill — role, use/do-not-use boundaries, required inputs, constraints, the eight-step process, output format, failure handling, and a nine-item self-check | diff --git a/plugins/bin/skills/zoom-out/README.md b/plugins/bin/skills/zoom-out/README.md deleted file mode 100644 index ce71a99..0000000 --- a/plugins/bin/skills/zoom-out/README.md +++ /dev/null @@ -1,25 +0,0 @@ -# zoom-out - -Ask the agent to go up a layer of abstraction and map the modules and callers around unfamiliar code. - -## What it does - -A single-purpose prompt for the moment you land in a part of the codebase you do not know. Instead of answering at the level of the file in front of it, the agent climbs one layer and produces a map of the relevant modules and their callers — and names them using the project's own domain glossary vocabulary, so the map lines up with the language the rest of the repo already uses. - -## Hand-invoked only - -`SKILL.md` sets `disable-model-invocation: true`, so the router never selects this skill on its own and no other skill can hand off to it. It runs when the human asks for it. That also means its description is written as one plain human-facing sentence — it carries no trigger phrasing or boundary clause, because nothing routes on it. - -## Usage - -```text -/zoom-out -``` - -Best used with the unfamiliar code already in context — the skill widens the view around what you are looking at rather than picking a starting point for you. - -## Files - -| File | Purpose | -|------|---------| -| `SKILL.md` | The whole skill — a single instruction, no supporting files | diff --git a/plugins/core/.apm/skills/agentsmd-audit/README.md b/plugins/core/.apm/skills/agentsmd-audit/README.md deleted file mode 100644 index dec17e6..0000000 --- a/plugins/core/.apm/skills/agentsmd-audit/README.md +++ /dev/null @@ -1,38 +0,0 @@ -# agentsmd-audit - -Audit a target repo's AGENTS.md file(s) for embedded secrets, structural completeness, and drift. - -## What it does - -Runs a single combined pass across every AGENTS.md file in a repo (root and any nested monorepo files): flags embedded secrets/credentials, checks structure against the agents.md common-sections checklist, and resolves referenced commands/paths against the actual repo to catch stale documentation. Outputs a compact findings report — findings only, grouped by dimension, each with Why and Fix. Never inspects provider-specific adapter files (CLAUDE.md, etc.) and never writes or fixes anything. - -## Usage - -``` -/agentsmd-audit -``` - -Provide the path to the repo root to audit when invoking. - -Also invoke it proactively after `agentsmd-author` creates or updates an AGENTS.md, or after a -hand-edit made outside `agentsmd-author` — the audit is what confirms the result is safe to commit. - -## Files - -| File | Purpose | -|------|---------| -| `SKILL.md` | Skill instructions for agents | -| `scripts/validate-secrets.sh` | Scans AGENTS.md files for embedded secrets, API keys, tokens, connection strings | -| `scripts/validate-structure.sh` | Checks for empty/placeholder content, common-sections checklist, nested-vs-root duplication | -| `scripts/validate-drift.sh` | Resolves referenced npm/make commands and file paths against the repo | -| `references/sources.md` | Provenance record — sources that informed this skill and which files each contributed to | -| `scripts/README.md` | Directory documentation for `scripts/` | -| `tests/README.md` | (source-only) Bats test dependency and run instructions | -| `tests/validate-secrets.bats` | (source-only) Bats test suite for `scripts/validate-secrets.sh` | -| `tests/validate-structure.bats` | (source-only) Bats test suite for `scripts/validate-structure.sh` | -| `tests/validate-drift.bats` | (source-only) Bats test suite for `scripts/validate-drift.sh` | - -Rows marked **(source-only)** exist in the authoring source (`.apm/skills/agentsmd-audit/`) but are -not present in an installed plugin: the repo's `scripts/sync-plugin-content.sh` strips -`//tests` when it generates the flat mirror, because these are dev-time fixtures no -plugin host needs to discover (ADR-0017). Run them from a repo checkout, not from an install. diff --git a/plugins/core/.apm/skills/agentsmd-author/README.md b/plugins/core/.apm/skills/agentsmd-author/README.md deleted file mode 100644 index e7ec1d5..0000000 --- a/plugins/core/.apm/skills/agentsmd-author/README.md +++ /dev/null @@ -1,27 +0,0 @@ -# agentsmd-author - -Create or update a target repo's AGENTS.md file(s) by exploring the repo for real conventions. - -## What it does - -Explores a target repo (package manager scripts, Makefile/task runner, CI config, linter config, existing docs) and writes or updates `AGENTS.md` with only verified commands and conventions — never invented ones. Supports nested monorepo placement, following the agents.md standard's nearest-file-wins precedence. Closes every run by invoking `agentsmd-audit` inline, and hands off to `provider-adapter-author` when an existing provider-specific file (CLAUDE.md, etc.) now duplicates content AGENTS.md owns. - -## Before you start - -The `agentsmd-audit` skill must be available (co-installed in the `core` plugin) — this skill invokes it as a mandatory closeout step. - -## Usage - -``` -/agentsmd-author -``` - -Provide the target repo root (defaults to the current directory) and, if relevant, which subdirectory should get a nested AGENTS.md. - -## Files - -| File | Purpose | -|------|---------| -| `SKILL.md` | Skill instructions for agents | -| `references/content-guide.md` | Section-by-section AGENTS.md content guidance, a worked example, and monorepo/nested-file precedence rules | -| `references/sources.md` | Provenance record — sources that informed this skill and which files each contributed to | diff --git a/plugins/core/.apm/skills/provider-adapter-author/README.md b/plugins/core/.apm/skills/provider-adapter-author/README.md deleted file mode 100644 index 1282b6c..0000000 --- a/plugins/core/.apm/skills/provider-adapter-author/README.md +++ /dev/null @@ -1,36 +0,0 @@ -# provider-adapter-author - -Convert a target repo's provider-specific instruction file (CLAUDE.md, .cursor/rules, copilot-instructions.md, etc.) into a thin adapter over AGENTS.md. - -## What it does - -Detects a provider-specific AI instruction file in a target repo, diffs it against the repo's `AGENTS.md`, and rewrites it down to a minimal reference — an `@AGENTS.md`-style import for providers that support one, or a text pointer for those that don't — plus only genuinely provider-specific additions. Self-validates its own output with a bundled deterministic script (no LLM judgment, no separate audit skill) before finishing. - -## Before you start - -The target repo must already have an `AGENTS.md`. If it doesn't, run `agentsmd-author` first — this skill never creates or edits `AGENTS.md` itself. - -## Usage - -``` -/provider-adapter-author -``` - -Provide the path to the provider-specific file to convert (and the target repo root, if not inferable). Can be invoked directly, or composed into by `agentsmd-author` when it detects an existing provider file with content overlapping AGENTS.md. - -## Files - -| File | Purpose | -|------|---------| -| `SKILL.md` | Skill instructions for agents | -| `references/provider-matrix.md` | Loaded at Step 1 before searching, unless the target is already a known root `CLAUDE.md`: known files per provider, which ones resolve a cross-file import, the validator flag each needs, and the rule that a standalone run and a run composed into by `agentsmd-author` behave identically | -| `references/sources.md` | Provenance record — the in-repo ADR precedent this skill's design is modeled on | -| `scripts/validate-adapter.sh` | Self-check gate: reference to AGENTS.md present, no excessive duplication, adapter stays thin | -| `scripts/README.md` | Directory documentation for `scripts/` | -| `tests/README.md` | (source-only) Bats test dependency and run instructions | -| `tests/validate-adapter.bats` | (source-only) Bats test suite for `scripts/validate-adapter.sh` | - -Rows marked **(source-only)** exist in the authoring source (`.apm/skills/provider-adapter-author/`) -but are not present in an installed plugin: the repo's `scripts/sync-plugin-content.sh` strips -`//tests` when it generates the flat mirror, because these are dev-time fixtures no -plugin host needs to discover (ADR-0017). Run them from a repo checkout, not from an install. diff --git a/plugins/core/skills/agentsmd-audit/README.md b/plugins/core/skills/agentsmd-audit/README.md deleted file mode 100644 index dec17e6..0000000 --- a/plugins/core/skills/agentsmd-audit/README.md +++ /dev/null @@ -1,38 +0,0 @@ -# agentsmd-audit - -Audit a target repo's AGENTS.md file(s) for embedded secrets, structural completeness, and drift. - -## What it does - -Runs a single combined pass across every AGENTS.md file in a repo (root and any nested monorepo files): flags embedded secrets/credentials, checks structure against the agents.md common-sections checklist, and resolves referenced commands/paths against the actual repo to catch stale documentation. Outputs a compact findings report — findings only, grouped by dimension, each with Why and Fix. Never inspects provider-specific adapter files (CLAUDE.md, etc.) and never writes or fixes anything. - -## Usage - -``` -/agentsmd-audit -``` - -Provide the path to the repo root to audit when invoking. - -Also invoke it proactively after `agentsmd-author` creates or updates an AGENTS.md, or after a -hand-edit made outside `agentsmd-author` — the audit is what confirms the result is safe to commit. - -## Files - -| File | Purpose | -|------|---------| -| `SKILL.md` | Skill instructions for agents | -| `scripts/validate-secrets.sh` | Scans AGENTS.md files for embedded secrets, API keys, tokens, connection strings | -| `scripts/validate-structure.sh` | Checks for empty/placeholder content, common-sections checklist, nested-vs-root duplication | -| `scripts/validate-drift.sh` | Resolves referenced npm/make commands and file paths against the repo | -| `references/sources.md` | Provenance record — sources that informed this skill and which files each contributed to | -| `scripts/README.md` | Directory documentation for `scripts/` | -| `tests/README.md` | (source-only) Bats test dependency and run instructions | -| `tests/validate-secrets.bats` | (source-only) Bats test suite for `scripts/validate-secrets.sh` | -| `tests/validate-structure.bats` | (source-only) Bats test suite for `scripts/validate-structure.sh` | -| `tests/validate-drift.bats` | (source-only) Bats test suite for `scripts/validate-drift.sh` | - -Rows marked **(source-only)** exist in the authoring source (`.apm/skills/agentsmd-audit/`) but are -not present in an installed plugin: the repo's `scripts/sync-plugin-content.sh` strips -`//tests` when it generates the flat mirror, because these are dev-time fixtures no -plugin host needs to discover (ADR-0017). Run them from a repo checkout, not from an install. diff --git a/plugins/core/skills/agentsmd-author/README.md b/plugins/core/skills/agentsmd-author/README.md deleted file mode 100644 index e7ec1d5..0000000 --- a/plugins/core/skills/agentsmd-author/README.md +++ /dev/null @@ -1,27 +0,0 @@ -# agentsmd-author - -Create or update a target repo's AGENTS.md file(s) by exploring the repo for real conventions. - -## What it does - -Explores a target repo (package manager scripts, Makefile/task runner, CI config, linter config, existing docs) and writes or updates `AGENTS.md` with only verified commands and conventions — never invented ones. Supports nested monorepo placement, following the agents.md standard's nearest-file-wins precedence. Closes every run by invoking `agentsmd-audit` inline, and hands off to `provider-adapter-author` when an existing provider-specific file (CLAUDE.md, etc.) now duplicates content AGENTS.md owns. - -## Before you start - -The `agentsmd-audit` skill must be available (co-installed in the `core` plugin) — this skill invokes it as a mandatory closeout step. - -## Usage - -``` -/agentsmd-author -``` - -Provide the target repo root (defaults to the current directory) and, if relevant, which subdirectory should get a nested AGENTS.md. - -## Files - -| File | Purpose | -|------|---------| -| `SKILL.md` | Skill instructions for agents | -| `references/content-guide.md` | Section-by-section AGENTS.md content guidance, a worked example, and monorepo/nested-file precedence rules | -| `references/sources.md` | Provenance record — sources that informed this skill and which files each contributed to | diff --git a/plugins/core/skills/provider-adapter-author/README.md b/plugins/core/skills/provider-adapter-author/README.md deleted file mode 100644 index 1282b6c..0000000 --- a/plugins/core/skills/provider-adapter-author/README.md +++ /dev/null @@ -1,36 +0,0 @@ -# provider-adapter-author - -Convert a target repo's provider-specific instruction file (CLAUDE.md, .cursor/rules, copilot-instructions.md, etc.) into a thin adapter over AGENTS.md. - -## What it does - -Detects a provider-specific AI instruction file in a target repo, diffs it against the repo's `AGENTS.md`, and rewrites it down to a minimal reference — an `@AGENTS.md`-style import for providers that support one, or a text pointer for those that don't — plus only genuinely provider-specific additions. Self-validates its own output with a bundled deterministic script (no LLM judgment, no separate audit skill) before finishing. - -## Before you start - -The target repo must already have an `AGENTS.md`. If it doesn't, run `agentsmd-author` first — this skill never creates or edits `AGENTS.md` itself. - -## Usage - -``` -/provider-adapter-author -``` - -Provide the path to the provider-specific file to convert (and the target repo root, if not inferable). Can be invoked directly, or composed into by `agentsmd-author` when it detects an existing provider file with content overlapping AGENTS.md. - -## Files - -| File | Purpose | -|------|---------| -| `SKILL.md` | Skill instructions for agents | -| `references/provider-matrix.md` | Loaded at Step 1 before searching, unless the target is already a known root `CLAUDE.md`: known files per provider, which ones resolve a cross-file import, the validator flag each needs, and the rule that a standalone run and a run composed into by `agentsmd-author` behave identically | -| `references/sources.md` | Provenance record — the in-repo ADR precedent this skill's design is modeled on | -| `scripts/validate-adapter.sh` | Self-check gate: reference to AGENTS.md present, no excessive duplication, adapter stays thin | -| `scripts/README.md` | Directory documentation for `scripts/` | -| `tests/README.md` | (source-only) Bats test dependency and run instructions | -| `tests/validate-adapter.bats` | (source-only) Bats test suite for `scripts/validate-adapter.sh` | - -Rows marked **(source-only)** exist in the authoring source (`.apm/skills/provider-adapter-author/`) -but are not present in an installed plugin: the repo's `scripts/sync-plugin-content.sh` strips -`//tests` when it generates the flat mirror, because these are dev-time fixtures no -plugin host needs to discover (ADR-0017). Run them from a repo checkout, not from an install. diff --git a/plugins/git/.apm/skills/git-branches/README.md b/plugins/git/.apm/skills/git-branches/README.md deleted file mode 100644 index 5c4f104..0000000 --- a/plugins/git/.apm/skills/git-branches/README.md +++ /dev/null @@ -1,34 +0,0 @@ -# git-branches - -Manage the full lifecycle of git branches — create, switch, delete, rename, track, merge, and compare feature/hotfix/release branches under GitHub Flow or Gitflow. - -## What it does - -This skill handles branch operations within the git workflow suite. It creates branches following GitHub Flow or Gitflow conventions (configurable), switches and tracks branches, handles safe deletion with unmerged-work checks, and retrieves branch intent metadata for use by other skills (e.g., commit message context). It returns structured results suitable for agent composition. - -## Usage - -``` -/git-branches -``` - -Describe your branch task: create a feature/hotfix/release branch, switch, delete, rename, track, merge, or compare two branches. The skill will determine the branching pattern (GitHub Flow or Gitflow) from config or repo state and handle safety checks for destructive operations. - -## Files - -| File | Purpose | -|------|---------| -| `SKILL.md` | Skill instructions for agents | -| `references/branch-patterns.md` | Loaded when a branch's base, name prefix, or merge rule depends on GitHub Flow vs. Gitflow | -| `references/branch-operations.md` | Loaded when running a create/switch/delete/rename/track/list/stash action, or resolving `get-intent` | -| `references/merging.md` | Loaded when merging one branch into another or resolving merge conflicts | -| `references/comparing-branches.md` | Loaded when comparing two branches or finding where they diverged | -| `references/orchestrator-contract.md` | Loaded when `git-orchestrate` or another calling agent supplies a structured request rather than prose | -| `references/sources.md` | Research sources backing the branching/gitflow guidance | - -## Composition - -`git-orchestrate` calls this skill for the branch step of a multi-step workflow and parses its -structured result. Revert is `git-history`'s; commit authoring, rebase, reset and cherry-pick are -`git-commits`'; deleting a remote branch is `git-remotes`'; branch operations against a -Gitea-hosted remote are `gitea-branches`'. diff --git a/plugins/git/.apm/skills/git-branches/SKILL.md b/plugins/git/.apm/skills/git-branches/SKILL.md index 325dd96..b2cf0ba 100644 --- a/plugins/git/.apm/skills/git-branches/SKILL.md +++ b/plugins/git/.apm/skills/git-branches/SKILL.md @@ -9,7 +9,7 @@ description: > Not a Gitea remote's branches -> `gitea-branches`. metadata: - version: "1.0.1" + version: "1.0.2" category: git source_keys: - context7-git-htmldocs @@ -21,7 +21,7 @@ metadata: ## Gotchas - **Uncommitted changes abort a switch.** `git switch` refuses rather than clobbering conflicting local edits. Offer to stash and retry — forcing the checkout past it is how work disappears. -- **A branch and a tag can carry the same name.** Detect it before acting — `git branch --list ` (bare, not `rtk`: rtk prints a phantom `* ` line even on no match, which reports every name as ambiguous — ADR-0023) and `rtk git tag --list `; output from both means the name is ambiguous. Prefer `git switch` over `git checkout`, and where a command accepts either ref, disambiguate with `refs/heads/` or `refs/tags/`. +- **A branch and a tag can carry the same name.** Detect it before acting — `git branch --list ` (bare, not `rtk`: rtk prints a phantom `* ` line even on no match, which reports every name as ambiguous) and `rtk git tag --list `; output from both means the name is ambiguous. Prefer `git switch` over `git checkout`, and where a command accepts either ref, disambiguate with `refs/heads/` or `refs/tags/`. - **`main` and `master` are a refusal, not a gate.** Force-pushing, force-deleting, or renaming them is rejected even when the caller passes `confirm: true` — no flag makes the remote's history recoverable. Offer a new branch instead. ## Step 1 — Determine the branching pattern diff --git a/plugins/git/.apm/skills/git-branches/references/branch-operations.md b/plugins/git/.apm/skills/git-branches/references/branch-operations.md index b0d785c..2fb9996 100644 --- a/plugins/git/.apm/skills/git-branches/references/branch-operations.md +++ b/plugins/git/.apm/skills/git-branches/references/branch-operations.md @@ -45,10 +45,10 @@ past it: it shelves the working tree and index so the branch pointer can move. reports `No local changes to save` and stashes nothing. Bare `git stash` is `push` with no message. - **restore** — `git stash pop` applies the newest entry and deletes it. Bare, not `rtk`: on a conflict rtk prints only `FAILED: git stash pop` and swallows the conflict report the paragraph - below tells you to read (ADR-0023). `rtk git stash apply stash@{n}` + below tells you to read. `rtk git stash apply stash@{n}` applies without deleting, for replaying one shelf onto more than one branch. - **list** — `git stash list` — bare, not `rtk`: rtk prints `No stashes` where git prints nothing, - so an empty-output test misfires (ADR-0023). `rtk git stash show -p stash@{n}` prints that entry's diff. + so an empty-output test misfires. `rtk git stash show -p stash@{n}` prints that entry's diff. - **drop** — `rtk git stash drop stash@{n}` deletes one entry. `rtk git stash clear` deletes all of them and nothing recovers them — confirm before running it. - **branch from a stash** — `rtk git stash branch stash@{n}` creates a branch at the commit the diff --git a/plugins/git/.apm/skills/git-branches/references/merging.md b/plugins/git/.apm/skills/git-branches/references/merging.md index 3b122c0..977c62d 100644 --- a/plugins/git/.apm/skills/git-branches/references/merging.md +++ b/plugins/git/.apm/skills/git-branches/references/merging.md @@ -27,5 +27,5 @@ list the conflicted files, edit each to resolve its markers, then `rtk git add < - `rtk git merge --abort` restores the pre-merge state. - `git mergetool` opens the configured merge tool — bare, not `rtk`: it hands control to an - interactive child process, and a token filter has nothing to offer there (ADR-0023). + interactive child process, and a token filter has nothing to offer there. - `rtk git diff --diff-filter=U` shows only the still-conflicted files. diff --git a/plugins/git/.apm/skills/git-commits/README.md b/plugins/git/.apm/skills/git-commits/README.md deleted file mode 100644 index 932931b..0000000 --- a/plugins/git/.apm/skills/git-commits/README.md +++ /dev/null @@ -1,31 +0,0 @@ -# git-commits - -Create, amend, squash, and cherry-pick commits with Conventional Commits formatting and validation. - -## What it does - -This skill handles commit operations within the git workflow suite. It generates well-formatted commit messages following the Conventional Commits spec, validates against commitlint config-conventional constraints, and communicates SemVer impact. It enforces confirmation gates for history-altering operations (amend, rebase, squash) and returns structured JSON output for agent consumption. - -## Usage - -``` -/git-commits -``` - -Describe your commit task: create a new commit, amend, squash, or cherry-pick. The skill will guide message formatting and handle confirmation for destructive operations. - -## Files - -| File | Loaded when | -|------|-------------| -| `SKILL.md` | Always — gotchas, the flow dispatch table, the gates common to every flow, and the output shape | -| `references/create-commit.md` | Composing a new commit from staged changes | -| `references/rewrite-history.md` | Amending, squashing, or folding a `fixup!`/`squash!` commit into an earlier one | -| `references/cherry-pick.md` | Replaying an existing commit onto the current branch | -| `references/conventional-commits-spec.md` | A type, footer, or breaking-change edge case is not obvious — full spec, 11-type set, commitlint constraint table | -| `references/commit-template.md` | Writing a body for a non-trivial commit — Why / Implementation Notes / Impact structure and the full trailer list | -| `references/sources.md` | Research sources and provenance | - -## Composition - -Part of the git plugin's domain suite. This skill owns commit authoring and history-rewriting operations only; `git-history` inspects history, `git-branches` owns branch lifecycle, and `git-workflow` is the conversational entry point that routes between them. diff --git a/plugins/git/.apm/skills/git-commits/SKILL.md b/plugins/git/.apm/skills/git-commits/SKILL.md index f1ec375..296ec18 100644 --- a/plugins/git/.apm/skills/git-commits/SKILL.md +++ b/plugins/git/.apm/skills/git-commits/SKILL.md @@ -8,7 +8,7 @@ description: > Not branch lifecycle -> `git-branches`. metadata: - version: "0.1.4" + version: "0.1.5" category: git source_keys: - conventional-commits-spec @@ -21,7 +21,7 @@ allowed-tools: Bash ## Gotchas -- **Run git as `rtk git `, never bare `git`** — org convention, in `&&` chains too. Exceptions: ADR-0023 clause 3. +- **Run git as `rtk git `, never bare `git`** — org convention, in `&&` chains too, except where a skill's Gotchas name a specific bare-git case (interactive rebase here). - **Refuse to force-push `main`/`master`** — a rewrite leaves the branch diverged and the reflex is to force it back; safe only where nobody else has based work on it. - **`reset --hard` is a confirmation gate, not a default.** It overwrites the working tree, and uncommitted edits it discards were never in git, so no reflog recovers them. Name what will be lost and offer a stash first. - **Never add `--no-verify`** — using it when a hook fails bypasses the QA gate the pipeline depends on. Only on the user's explicit demand, with a warning. diff --git a/plugins/git/.apm/skills/git-commits/references/rewrite-history.md b/plugins/git/.apm/skills/git-commits/references/rewrite-history.md index c86097e..793f2bb 100644 --- a/plugins/git/.apm/skills/git-commits/references/rewrite-history.md +++ b/plugins/git/.apm/skills/git-commits/references/rewrite-history.md @@ -21,7 +21,7 @@ Prefer this whenever a commit is written to be folded, because git does the mark 1. `rtk git commit --fixup=` keeps the target's message; `rtk git commit --squash=` lets you edit the combined message later. Both prefix the message with `fixup!`/`squash!` and name the target commit. 2. Get explicit approval — the rebase still rewrites history. -3. Run `git rebase -i --autosquash HEAD~N` — bare, not `rtk`: `-i` opens an interactive sequence editor (ADR-0023). Git pre-fills the todo list with the tagged commits already reordered against their targets; save it unchanged to apply. +3. Run `git rebase -i --autosquash HEAD~N` — bare, not `rtk`: `-i` opens an interactive sequence editor. Git pre-fills the todo list with the tagged commits already reordered against their targets; save it unchanged to apply. **`-i` is not optional here.** On Git 2.39.5, `git rebase --autosquash HEAD~N` without `-i` prints `Successfully rebased and updated refs/heads/.` and exits 0 while leaving the `fixup!` commit in place at its original SHA — `--autosquash` is honoured only by the interactive machinery, and the false success is the trap: the fold is reported as done, and the surviving `fixup!` subject then fails the Conventional Commits `commit-msg` hook. Later Git versions taught the non-interactive rebase to honour the flag, but `-i --autosquash` is correct on every version, so always write that. diff --git a/plugins/git/.apm/skills/git-history/README.md b/plugins/git/.apm/skills/git-history/README.md deleted file mode 100644 index e208cfa..0000000 --- a/plugins/git/.apm/skills/git-history/README.md +++ /dev/null @@ -1,29 +0,0 @@ -# git-history - -Inspect git history — log queries, bisect, and locating problematic commits. - -## What it does - -This skill handles history inspection within the git workflow suite. It queries logs with pickaxe/line-range/custom formats, runs bisect to find bug-introducing commits, and locates commits for downstream cherry-picking or reverting. It returns structured results for agent composition. Rebase, squash, fixup, and other history-rewriting operations are owned by git-commits, not this skill. - -## Composition - -`git-branches` delegates revert here (see `git-branches`'s `references/merging.md`), which is why this skill carries that operation rather than treating it as out of scope; it is general git knowledge, not drawn from the `history-inspection.md` research corpus. Cherry-pick is **not** this skill's: `git-commits` owns it, and this skill's job ends at locating the SHA to hand over. Server-side commit history on a Gitea-hosted repository belongs to `gitea-branches`; this skill reads the local working copy. - -## Usage - -``` -/git-history -``` - -Describe your history task: search logs, bisect for a regression, or locate a specific commit. The skill will query history and return structured results. - -## Files - -| File | Purpose | -|------|---------| -| `SKILL.md` | Skill instructions for agents | -| `references/bisect.md` | Loaded when the entry procedure is bisect: manual and automated flows, exit codes, skip, replay, narrowing, custom terms | -| `references/git-log-format.md` | Loaded when a log or diff flag needs looking up: format placeholders, presets, diff-filter letters, `-L` syntax, ancestry filters, pickaxe binary-file behaviour, diff output-control flags | -| `references/sources.md` | Research sources and provenance | -| `references/README.md` | Index of the references directory | diff --git a/plugins/git/.apm/skills/git-history/SKILL.md b/plugins/git/.apm/skills/git-history/SKILL.md index 2a7f62f..0ed23c4 100644 --- a/plugins/git/.apm/skills/git-history/SKILL.md +++ b/plugins/git/.apm/skills/git-history/SKILL.md @@ -8,7 +8,7 @@ description: > `git-commits`. Not a Gitea server's history -> `gitea-branches`. metadata: - version: "1.0.1" + version: "1.0.2" category: git source_keys: - git-scm-bisect-docs @@ -38,7 +38,7 @@ allowed-tools: Bash Default to `rtk git log --oneline`, then narrow by whatever is known: - **Content**: `rtk git log -S"string"`, or `-G"regex"` to match any diff line. `--pickaxe-regex` makes the `-S` argument a POSIX ERE; `--pickaxe-all` shows every file in a matching changeset. -- **A line or function**: `git log -L ,:` or `git log -L ::` — bare, not `rtk`: rtk truncates each diff line at ~72 characters (ADR-0023). Confirm the range resolves before reporting on it — an off-by-one silently omits the target. +- **A line or function**: `git log -L ,:` or `git log -L ::` — bare, not `rtk`: rtk truncates each diff line at ~72 characters. Confirm the range resolves before reporting on it — an off-by-one silently omits the target. - **A file across renames**: `rtk git log --follow -- `. Without `--follow` the history stops at the rename boundary. - **Mainline only**: `--first-parent` follows the integration branch and skips commits merged in from side branches. - **Structured output**: `rtk git log --format="%h | %s | %an (%ar)"`. diff --git a/plugins/git/.apm/skills/git-history/references/README.md b/plugins/git/.apm/skills/git-history/references/README.md deleted file mode 100644 index c9a302a..0000000 --- a/plugins/git/.apm/skills/git-history/references/README.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -source_keys: - - git-scm-bisect-docs - - git-scm-log-docs - - git-scm-diff-docs ---- - -# References - -This directory contains provenance metadata and research sources for the `git-history` skill. - -## Files - -- `sources.md` — Extracted research sources and their contributing documents -- `bisect.md` — The full `git bisect` procedure: manual and automated flows, exit-code semantics, skip and replay, narrowing options, and custom good/bad terms -- `git-log-format.md` — Full `git log` format placeholder catalogue, named format presets, `--diff-filter` letters, `-L` line-range syntax, ancestry filters, pickaxe binary-file behaviour, and `git diff` output-control flags diff --git a/plugins/git/.apm/skills/git-history/references/git-log-format.md b/plugins/git/.apm/skills/git-history/references/git-log-format.md index 2481e09..8aa5b2d 100644 --- a/plugins/git/.apm/skills/git-history/references/git-log-format.md +++ b/plugins/git/.apm/skills/git-history/references/git-log-format.md @@ -166,10 +166,10 @@ line at roughly 72 characters with an ellipsis, on the one query whose whole poi is showing line content. ```bash -git log -L 10,20:file.txt # bare per ADR-0023 -git log -L /start_pattern/,/end_pattern/:file.txt # bare per ADR-0023 -git log -L :myfunction:src/app.c # bare per ADR-0023 -git log -L /init/,+15:config.py # bare per ADR-0023; 15 lines after first /init/ match +git log -L 10,20:file.txt # bare (ADR-0023) +git log -L /start_pattern/,/end_pattern/:file.txt # bare (ADR-0023) +git log -L :myfunction:src/app.c # bare (ADR-0023) +git log -L /init/,+15:config.py # bare (ADR-0023); 15 lines after first /init/ match ``` Range formats: @@ -213,8 +213,8 @@ Bare `git`, not `rtk git`: rtk appends a blank line and a `Changes:` trailer, so the output is no longer one record per line. ```bash -git diff --name-only # bare per ADR-0023; only filenames, one per line -git diff --name-status # bare per ADR-0023; status letter + filename per line +git diff --name-only # bare (ADR-0023); only filenames, one per line +git diff --name-status # bare (ADR-0023); status letter + filename per line ``` `--name-status` uses the same status letters as `--diff-filter`. @@ -225,10 +225,10 @@ Bare `git`, not `rtk git`: rtk replaces the word-diff with its own diffstat renderer and emits none of the `[-removed-] {+added+}` markers. ```bash -git diff --word-diff # bare per ADR-0023; inline word-level diff, [-removed-] {+added+} markers -git diff --word-diff=color # bare per ADR-0023; color only, no markers -git diff --word-diff=porcelain # bare per ADR-0023; machine-readable: +/- prefixed lines, ~ for newlines -git diff --word-diff-regex= # bare per ADR-0023; define what counts as a "word" +git diff --word-diff # bare (ADR-0023); inline word-level diff, [-removed-] {+added+} markers +git diff --word-diff=color # bare (ADR-0023); color only, no markers +git diff --word-diff=porcelain # bare (ADR-0023); machine-readable: +/- prefixed lines, ~ for newlines +git diff --word-diff-regex= # bare (ADR-0023); define what counts as a "word" ``` ### Whitespace Flags diff --git a/plugins/git/.apm/skills/git-remotes/README.md b/plugins/git/.apm/skills/git-remotes/README.md deleted file mode 100644 index 0895aa2..0000000 --- a/plugins/git/.apm/skills/git-remotes/README.md +++ /dev/null @@ -1,34 +0,0 @@ -# git-remotes - -Manage git remote repositories — add/remove/configure remotes, push/pull with safety checks, fetch with pruning, and multi-remote workflows. - -## What it does - -This skill handles remote operations within the git workflow suite. It manages remote configuration (add, remove, rename), fetch operations with pruning, push operations with force-push safety (`--force-with-lease --force-if-includes`), and pull strategies (fast-forward, rebase, merge). It returns structured results suitable for agent composition. - -## Usage - -``` -/git-remotes -``` - -Describe your remote operation: add a remote, push, pull, fetch, or configure tracking. The skill will handle the operation with appropriate safety checks and return results. - -## Files - -| File | Purpose | -|------|---------| -| `SKILL.md` | Skill instructions for agents — force-push gate, dispatch table, return format | -| `references/README.md` | Describes the references directory contents | -| `references/remote-config.md` | Read when adding, removing, renaming, inspecting or re-pointing a remote, or configuring tracking, mirroring, or `set-url` | -| `references/fetch.md` | Read when fetching or pruning remote-tracking refs, or doing a shallow or partial fetch | -| `references/push.md` | Read when pushing branches or tags, writing refspecs, or force-pushing | -| `references/pull.md` | Read when integrating remote changes into the current branch, including the divergence rule | -| `references/sources.md` | Research sources and provenance | - -## Composition - -Callers that need submodule initialization after a `--recurse-submodules` pull hand off to -`git-submodules`; local-only work (commits, branches, history) belongs to `git-commits`, -`git-branches`, and `git-history`. The `git-workflow` skill routes humans here for any -remote-touching request. diff --git a/plugins/git/.apm/skills/git-remotes/SKILL.md b/plugins/git/.apm/skills/git-remotes/SKILL.md index 181768e..e21ddf3 100644 --- a/plugins/git/.apm/skills/git-remotes/SKILL.md +++ b/plugins/git/.apm/skills/git-remotes/SKILL.md @@ -10,7 +10,7 @@ description: > Not submodule pointers -> `git-submodules`. metadata: - version: "1.0.1" + version: "1.0.2" category: git source_keys: - git-scm-remote-docs diff --git a/plugins/git/.apm/skills/git-remotes/references/README.md b/plugins/git/.apm/skills/git-remotes/references/README.md deleted file mode 100644 index a9ca455..0000000 --- a/plugins/git/.apm/skills/git-remotes/references/README.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -source_keys: - - git-scm-remote-docs - - git-scm-fetch-docs - - git-scm-push-docs - - git-scm-pull-docs - - context7-git-htmldocs ---- - -# References - -This directory contains provenance metadata and research sources for the `git-remotes` skill. - -## Files - -- `sources.md` — Extracted research sources and their contributing documents -- `remote-config.md` — Remote add/remove/rename/inspect, tracking and mirror options, housekeeping, and the full `set-url` form -- `fetch.md` — Fetch and prune options, shallow and partial fetch, the default fetch refspec -- `push.md` — Push options, refspec syntax, force-push safety in full, server-side deny policies -- `pull.md` — Pull strategies, submodule caveat, the divergence rule, and pull config precedence diff --git a/plugins/git/.apm/skills/git-remotes/references/push.md b/plugins/git/.apm/skills/git-remotes/references/push.md index 8fc10fb..8bec56e 100644 --- a/plugins/git/.apm/skills/git-remotes/references/push.md +++ b/plugins/git/.apm/skills/git-remotes/references/push.md @@ -50,7 +50,7 @@ Two mitigations: # poisoned by an unrelated fetch. # The inner `git config` is bare: its stdout becomes a remote URL, so any # output rewriting would poison the remote silently. -rtk git remote add origin-push $(git config remote.origin.url) # inner bare per ADR-0023 +rtk git remote add origin-push $(git config remote.origin.url) # inner bare (ADR-0023) rtk git push --force-with-lease origin-push # Option 2 — explicit SHA via a local tag, unaffected by tracking-branch state diff --git a/plugins/git/.apm/skills/git-submodules/README.md b/plugins/git/.apm/skills/git-submodules/README.md deleted file mode 100644 index 4b1d2b9..0000000 --- a/plugins/git/.apm/skills/git-submodules/README.md +++ /dev/null @@ -1,35 +0,0 @@ -# git-submodules - -Add, initialize, update, pin, inspect, and remove git submodules in multi-repository projects. - -## What it does - -This skill handles submodule operations within the git workflow suite: cloning a superproject with -its nested repositories, adding a dependency as a submodule, initializing and updating with -pinning or branch tracking, parallel and recursive traversal, rebinding URLs and tracked branches, -and the full removal sequence including the `.git/modules/` cleanup git leaves behind. It returns -structured results suitable for agent composition. - -It sits alongside the other git skills rather than duplicating them: `git-worktrees` covers -multiple checkouts of a single repository, and `git-remotes` covers the superproject's own remotes. - -## Usage - -``` -/git-submodules -``` - -Describe the submodule task. The skill applies the shared working rules, dispatches to the -reference for that task, and returns structured results (operation, status, per-submodule details, -conflicts, and a recovery `next_step` when applicable). - -## Files - -| File | Purpose | -|------|---------| -| `SKILL.md` | Skill instructions for agents — gotchas, shared working rules, and the task dispatch table | -| `references/README.md` | Describes contents of references/ | -| `references/setup-and-update.md` | Loaded when cloning a superproject, adding a submodule, initializing, updating, or re-pinning one, or running a command across all of them — includes the full `add` and `update` flag tables, the pinning workflows, and the `foreach` shell-variable table | -| `references/urls-and-config.md` | Loaded when changing where a submodule points or how it is configured — `.gitmodules` vs `.git/config` anatomy, both key tables, `sync`/`set-url`/`set-branch`, local mirror overrides, relative URLs, the custom-`update` security gate, and `absorbgitdirs` | -| `references/removal.md` | Loaded when removing or deinitializing a submodule — why `deinit` is not removal, and the four-step removal sequence | -| `references/sources.md` | Research sources and provenance | diff --git a/plugins/git/.apm/skills/git-submodules/references/README.md b/plugins/git/.apm/skills/git-submodules/references/README.md deleted file mode 100644 index 0df0d93..0000000 --- a/plugins/git/.apm/skills/git-submodules/references/README.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -source_keys: - - git-scm-submodule-docs ---- - -# References - -One file per task branch in SKILL.md's dispatch table. Load only the one that matches the request. - -## setup-and-update.md - -Cloning a superproject that has submodules, adding a dependency as a submodule, initializing -without cloning, updating or re-pinning, and running one command across every submodule. Carries -the `add` and `update` flag tables, the keep-pinned and move-the-pin-forward workflows, and the -`foreach` shell-variable table (`$name`, `$sm_path`, `$displaypath`, `$sha1`, `$toplevel`). - -## urls-and-config.md - -Where a submodule points and how it is configured: the `.gitmodules` vs `.git/config` split, both -key tables, `sync` / `set-url` / `set-branch`, local mirror overrides, relative URL resolution, the -security gate on custom `update` commands, and `absorbgitdirs`. - -## removal.md - -Removing a submodule, and why `deinit` alone does not remove one. Carries the full four-step -removal sequence including the manual `.git/modules//` cleanup. - -## sources.md - -Research sources that informed this skill — provenance chain for git-scm-submodule-docs reference -material. diff --git a/plugins/git/.apm/skills/git-workflow/README.md b/plugins/git/.apm/skills/git-workflow/README.md deleted file mode 100644 index 10659fd..0000000 --- a/plugins/git/.apm/skills/git-workflow/README.md +++ /dev/null @@ -1,25 +0,0 @@ -# git-workflow - -Human-friendly interface for interactive git workflows with conversational prompts, progress guidance, and safety confirmations. - -## What it does - -This skill wraps the `git-orchestrate` agent to provide an interactive, educational interface for humans performing git workflows. It is the router for the six local-git domain skills — `git-commits`, `git-branches`, `git-history`, `git-remotes`, `git-submodules` and `git-worktrees` — and `SKILL.md` carries a table mapping each of them to the requests it owns, so an ambiguous request resolves to exactly one domain before anything runs. The skill parses user intent, gathers session context, invokes the orchestrator, and presents results in plain language with inline help, progress updates, and explanations of what's happening. It enforces confirmation gates for destructive operations (force-push, branch deletion, rebasing with history loss, force-checkout) and provides best-practices guidance throughout. The org's non-negotiable git rules live in `references/hard-rules.md` and are loaded only when a request could conflict with one. - -## Usage - -``` -/git-workflow -``` - -Describe your git workflow: commit, create a branch, rebase, inspect history, manage submodules, switch worktrees, or manage remotes. The skill will prompt for any missing details and guide you through the workflow. - -## Files - -| File | Purpose | -|------|---------| -| `SKILL.md` | Skill instructions for agents — the six-domain routing table, the workflow steps, and the interaction style | -| `README.md` | This file | -| `references/hard-rules.md` | The org's non-negotiable git rules; read when a request creates, amends, or rewrites a commit, pushes, or touches hooks, config, or credentials | -| `references/README.md` | Describes the references directory contents | -| `references/sources.md` | Research sources and provenance | diff --git a/plugins/git/.apm/skills/git-workflow/references/README.md b/plugins/git/.apm/skills/git-workflow/references/README.md deleted file mode 100644 index bcf2db0..0000000 --- a/plugins/git/.apm/skills/git-workflow/references/README.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -source_keys: - - nvie-gitflow-post - - atlassian-gitflow-tutorial - - gitflow-cheatsheet - - context7-git-htmldocs - - org-git-conventions ---- - -# References - -This directory contains the org git rules and the provenance metadata for the `git-workflow` -skill. - -## Files - -- `hard-rules.md` — The org's non-negotiable git rules, loaded when a request creates, amends, or - rewrites a commit, pushes, or touches hooks, config, or credentials -- `sources.md` — Extracted research sources and their contributing documents diff --git a/plugins/git/.apm/skills/git-worktrees/README.md b/plugins/git/.apm/skills/git-worktrees/README.md deleted file mode 100644 index 2042f80..0000000 --- a/plugins/git/.apm/skills/git-worktrees/README.md +++ /dev/null @@ -1,24 +0,0 @@ -# git-worktrees - -Manage git worktrees to enable multi-branch parallel development across isolated directories. - -## What it does - -This skill handles worktree operations within the git workflow suite. It creates, lists, locks/unlocks, moves, removes, prunes, and repairs worktrees — letting an agent work on multiple branches simultaneously without stashing. It returns structured results (paths, branches, lock status) suitable for agent composition. For multi-step flows spanning branch strategy plus worktree setup, `git-workflow` handles the broader orchestration and delegates the worktree mechanics here. - -## Usage - -``` -/git-worktrees -``` - -Describe your worktree task: create a worktree for a branch, list existing worktrees, lock one for removable media, move, remove, prune, or repair. The skill will handle the operation with appropriate safety checks and return results. - -## Files - -| File | Purpose | -|------|---------| -| `SKILL.md` | Dispatch table, per-operation gates, and the report format | -| `references/README.md` | Describes the references directory contents | -| `references/worktrees.md` | Read when an operation needs more than the dispatch table: shared vs. per-worktree state, the `add` command forms, the full `add` flag table, orphan branches, sparse-checkout, removable-media locking, remote disambiguation, where to run `repair` from, config keys, and the emergency-fix and PR-review patterns | -| `references/sources.md` | Research sources and provenance | diff --git a/plugins/git/.apm/skills/git-worktrees/SKILL.md b/plugins/git/.apm/skills/git-worktrees/SKILL.md index a72332c..ebd0422 100644 --- a/plugins/git/.apm/skills/git-worktrees/SKILL.md +++ b/plugins/git/.apm/skills/git-worktrees/SKILL.md @@ -8,7 +8,7 @@ description: > Not interactive multi-step git guidance -> `git-workflow`. metadata: - version: "1.0.1" + version: "1.0.2" category: git source_keys: - git-scm-worktree-docs @@ -32,7 +32,7 @@ metadata: | Create a local branch tracking a remote one | `rtk git worktree add --track -b /` — always correct. `git worktree add ` expands to exactly this, but **only** under the conditions in `references/worktrees.md` | | Throwaway experiment, no branch | `rtk git worktree add -d ` — detached HEAD | | **Never** `git worktree add /` | That ref resolves, so the shortcut never fires and you get **a detached HEAD, no branch, no upstream**. Commits there go unreachable once HEAD moves, and `git push` needs an explicit refspec. Use the tracking row above | -| List | `git worktree list -v` to read, or `git worktree list --porcelain -z` to parse — both bare per ADR-0023: rtk re-renders the output and drops the porcelain flags | +| List | `git worktree list -v` to read, or `git worktree list --porcelain -z` to parse — both bare (ADR-0023): rtk re-renders the output and drops the porcelain flags | | Lock or unlock | `rtk git worktree lock [--reason ] ` / `rtk git worktree unlock ` | | Move | `rtk git worktree move ` | | Remove | `rtk git worktree remove ` | @@ -63,6 +63,6 @@ worktrees: ``` Derive those fields from `git worktree list --porcelain -z` — bare, not `rtk`: -rtk drops both flags and never emits `locked`/`lock_reason` (ADR-0023). For a single +rtk drops both flags and never emits `locked`/`lock_reason`. For a single operation, report its outcome instead — `created: true`, `moved: true`, `removed: true`. diff --git a/plugins/git/.apm/skills/git-worktrees/references/README.md b/plugins/git/.apm/skills/git-worktrees/references/README.md deleted file mode 100644 index f5f6037..0000000 --- a/plugins/git/.apm/skills/git-worktrees/references/README.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -source_keys: - - git-scm-worktree-docs ---- - -# References - -This directory contains provenance metadata and research sources for the `git-worktrees` skill. - -## Files - -- `sources.md` — Extracted research sources and their contributing documents -- `worktrees.md` — Shared vs. per-worktree state, the `add` command forms, the full `add` flag table, orphan branches, sparse-checkout setup, removable-media locking, remote-branch disambiguation, where to run `repair` from, the config key reference, and the emergency-fix and PR-review workflow patterns diff --git a/plugins/git/.apm/skills/pc-author/README.md b/plugins/git/.apm/skills/pc-author/README.md deleted file mode 100644 index 61de70f..0000000 --- a/plugins/git/.apm/skills/pc-author/README.md +++ /dev/null @@ -1,26 +0,0 @@ -# pc-author - -Create, add, remove, update, and configure `.pre-commit-config.yaml`. - -## What it does - -Manages the pre-commit configuration file in any git repo. When invoked, it scans the repo for languages, proposes appropriate hooks with rationale, and writes or modifies `.pre-commit-config.yaml`. It validates every write with `pre-commit validate-config` and flags stale revision pins. It does not run hooks or install them into `.git/hooks/` — use `pc-run` for that. - -## Usage - -``` -/pc-author -``` - -Invoke with no arguments. The skill determines from context whether to create a new config or modify an existing one. - -## Files - -| File | Purpose | -|------|---------| -| `SKILL.md` | Skill instructions for agents | -| `references/create-config.md` | Loaded when the repo has no `.pre-commit-config.yaml` — the create-from-scratch flow | -| `references/modify-config.md` | Loaded when a `.pre-commit-config.yaml` already exists — add, remove, top-level keys, rev staleness | -| `references/hooks-by-language.md` | Hook recommendations by detected language/extension | -| `references/README.md` | Index of files in references/ | -| `references/sources.md` | Provenance — research sources that informed this skill | diff --git a/plugins/git/.apm/skills/pc-author/references/README.md b/plugins/git/.apm/skills/pc-author/references/README.md deleted file mode 100644 index 7bc855a..0000000 --- a/plugins/git/.apm/skills/pc-author/references/README.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -source_keys: - - context7-pre-commit-com - - pre-commit-com - - context7-pre-commit-hooks - - pre-commit-hooks-github ---- - -# references/ - -| File | Purpose | -|---|---| -| `create-config.md` | The create flow — read when the repo has no `.pre-commit-config.yaml` | -| `modify-config.md` | The modify flow — read when a `.pre-commit-config.yaml` already exists | -| `hooks-by-language.md` | Hook recommendations by language/context — repo, rev, and rationale for adding hooks | -| `sources.md` | Provenance: research sources that informed this skill | diff --git a/plugins/git/.apm/skills/pc-run/README.md b/plugins/git/.apm/skills/pc-run/README.md deleted file mode 100644 index be4b26c..0000000 --- a/plugins/git/.apm/skills/pc-run/README.md +++ /dev/null @@ -1,32 +0,0 @@ -# pc-run - -Runs, installs, updates, and maintains pre-commit hooks in a local git clone. - -## What it does - -`pc-run` handles everything that happens *after* `.pre-commit-config.yaml` exists: wiring hooks into git, running them, bumping their versions, and maintaining the cache. When hooks fail, it identifies the cause and suggests a concrete fix — it does not auto-fix files or edit the config. For creating or editing `.pre-commit-config.yaml`, use `pc-author` instead. - -## Before you start - -- `pre-commit` must be installed and available on `PATH` -- A `.pre-commit-config.yaml` must exist at the repo root (use `pc-author` to create one) - -## Usage - -Common invocations: -- `/pc-run` — run all hooks against all files (default) -- `/pc-run install` — wire hooks into `.git/hooks/` -- `/pc-run autoupdate` — bump all `rev` values to latest -- `/pc-run clean` — wipe the pre-commit cache (requires confirmation) - -## Files - -| File | Purpose | -|------|---------| -| `SKILL.md` | Skill instructions for agents | -| `references/install.md` | The install flow — loaded when the user asks to install or set up hooks | -| `references/autoupdate.md` | The autoupdate flow — loaded when the user asks to bump hook revs | -| `references/clean.md` | The clean flow — loaded when the user asks to wipe the cache or rebuild environments | -| `references/failure-patterns.md` | Hook failure causes and concrete fix suggestions — loaded when a hook fails or never fires | -| `references/sources.md` | Provenance: research sources that informed this skill | -| `references/README.md` | Directory index for references/ | diff --git a/plugins/git/.apm/skills/pc-run/references/README.md b/plugins/git/.apm/skills/pc-run/references/README.md deleted file mode 100644 index 51290f8..0000000 --- a/plugins/git/.apm/skills/pc-run/references/README.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -source_keys: - - context7-pre-commit-com - - pre-commit-com - - context7-pre-commit-hooks - - pre-commit-hooks-github ---- - -# references/ - -| File | Purpose | -|---|---| -| `install.md` | The install flow — read when the user asks to install or set up hooks | -| `autoupdate.md` | The autoupdate flow — read when the user asks to bump hook revs | -| `clean.md` | The clean flow — read when the user asks to wipe the cache or rebuild environments | -| `failure-patterns.md` | Hook failure causes and concrete fix suggestions — read when a hook fails or never fires | -| `sources.md` | Provenance: research sources that informed this skill | diff --git a/plugins/git/skills/git-branches/README.md b/plugins/git/skills/git-branches/README.md deleted file mode 100644 index 5c4f104..0000000 --- a/plugins/git/skills/git-branches/README.md +++ /dev/null @@ -1,34 +0,0 @@ -# git-branches - -Manage the full lifecycle of git branches — create, switch, delete, rename, track, merge, and compare feature/hotfix/release branches under GitHub Flow or Gitflow. - -## What it does - -This skill handles branch operations within the git workflow suite. It creates branches following GitHub Flow or Gitflow conventions (configurable), switches and tracks branches, handles safe deletion with unmerged-work checks, and retrieves branch intent metadata for use by other skills (e.g., commit message context). It returns structured results suitable for agent composition. - -## Usage - -``` -/git-branches -``` - -Describe your branch task: create a feature/hotfix/release branch, switch, delete, rename, track, merge, or compare two branches. The skill will determine the branching pattern (GitHub Flow or Gitflow) from config or repo state and handle safety checks for destructive operations. - -## Files - -| File | Purpose | -|------|---------| -| `SKILL.md` | Skill instructions for agents | -| `references/branch-patterns.md` | Loaded when a branch's base, name prefix, or merge rule depends on GitHub Flow vs. Gitflow | -| `references/branch-operations.md` | Loaded when running a create/switch/delete/rename/track/list/stash action, or resolving `get-intent` | -| `references/merging.md` | Loaded when merging one branch into another or resolving merge conflicts | -| `references/comparing-branches.md` | Loaded when comparing two branches or finding where they diverged | -| `references/orchestrator-contract.md` | Loaded when `git-orchestrate` or another calling agent supplies a structured request rather than prose | -| `references/sources.md` | Research sources backing the branching/gitflow guidance | - -## Composition - -`git-orchestrate` calls this skill for the branch step of a multi-step workflow and parses its -structured result. Revert is `git-history`'s; commit authoring, rebase, reset and cherry-pick are -`git-commits`'; deleting a remote branch is `git-remotes`'; branch operations against a -Gitea-hosted remote are `gitea-branches`'. diff --git a/plugins/git/skills/git-branches/SKILL.md b/plugins/git/skills/git-branches/SKILL.md index 325dd96..b2cf0ba 100644 --- a/plugins/git/skills/git-branches/SKILL.md +++ b/plugins/git/skills/git-branches/SKILL.md @@ -9,7 +9,7 @@ description: > Not a Gitea remote's branches -> `gitea-branches`. metadata: - version: "1.0.1" + version: "1.0.2" category: git source_keys: - context7-git-htmldocs @@ -21,7 +21,7 @@ metadata: ## Gotchas - **Uncommitted changes abort a switch.** `git switch` refuses rather than clobbering conflicting local edits. Offer to stash and retry — forcing the checkout past it is how work disappears. -- **A branch and a tag can carry the same name.** Detect it before acting — `git branch --list ` (bare, not `rtk`: rtk prints a phantom `* ` line even on no match, which reports every name as ambiguous — ADR-0023) and `rtk git tag --list `; output from both means the name is ambiguous. Prefer `git switch` over `git checkout`, and where a command accepts either ref, disambiguate with `refs/heads/` or `refs/tags/`. +- **A branch and a tag can carry the same name.** Detect it before acting — `git branch --list ` (bare, not `rtk`: rtk prints a phantom `* ` line even on no match, which reports every name as ambiguous) and `rtk git tag --list `; output from both means the name is ambiguous. Prefer `git switch` over `git checkout`, and where a command accepts either ref, disambiguate with `refs/heads/` or `refs/tags/`. - **`main` and `master` are a refusal, not a gate.** Force-pushing, force-deleting, or renaming them is rejected even when the caller passes `confirm: true` — no flag makes the remote's history recoverable. Offer a new branch instead. ## Step 1 — Determine the branching pattern diff --git a/plugins/git/skills/git-branches/references/branch-operations.md b/plugins/git/skills/git-branches/references/branch-operations.md index b0d785c..2fb9996 100644 --- a/plugins/git/skills/git-branches/references/branch-operations.md +++ b/plugins/git/skills/git-branches/references/branch-operations.md @@ -45,10 +45,10 @@ past it: it shelves the working tree and index so the branch pointer can move. reports `No local changes to save` and stashes nothing. Bare `git stash` is `push` with no message. - **restore** — `git stash pop` applies the newest entry and deletes it. Bare, not `rtk`: on a conflict rtk prints only `FAILED: git stash pop` and swallows the conflict report the paragraph - below tells you to read (ADR-0023). `rtk git stash apply stash@{n}` + below tells you to read. `rtk git stash apply stash@{n}` applies without deleting, for replaying one shelf onto more than one branch. - **list** — `git stash list` — bare, not `rtk`: rtk prints `No stashes` where git prints nothing, - so an empty-output test misfires (ADR-0023). `rtk git stash show -p stash@{n}` prints that entry's diff. + so an empty-output test misfires. `rtk git stash show -p stash@{n}` prints that entry's diff. - **drop** — `rtk git stash drop stash@{n}` deletes one entry. `rtk git stash clear` deletes all of them and nothing recovers them — confirm before running it. - **branch from a stash** — `rtk git stash branch stash@{n}` creates a branch at the commit the diff --git a/plugins/git/skills/git-branches/references/merging.md b/plugins/git/skills/git-branches/references/merging.md index 3b122c0..977c62d 100644 --- a/plugins/git/skills/git-branches/references/merging.md +++ b/plugins/git/skills/git-branches/references/merging.md @@ -27,5 +27,5 @@ list the conflicted files, edit each to resolve its markers, then `rtk git add < - `rtk git merge --abort` restores the pre-merge state. - `git mergetool` opens the configured merge tool — bare, not `rtk`: it hands control to an - interactive child process, and a token filter has nothing to offer there (ADR-0023). + interactive child process, and a token filter has nothing to offer there. - `rtk git diff --diff-filter=U` shows only the still-conflicted files. diff --git a/plugins/git/skills/git-commits/README.md b/plugins/git/skills/git-commits/README.md deleted file mode 100644 index 932931b..0000000 --- a/plugins/git/skills/git-commits/README.md +++ /dev/null @@ -1,31 +0,0 @@ -# git-commits - -Create, amend, squash, and cherry-pick commits with Conventional Commits formatting and validation. - -## What it does - -This skill handles commit operations within the git workflow suite. It generates well-formatted commit messages following the Conventional Commits spec, validates against commitlint config-conventional constraints, and communicates SemVer impact. It enforces confirmation gates for history-altering operations (amend, rebase, squash) and returns structured JSON output for agent consumption. - -## Usage - -``` -/git-commits -``` - -Describe your commit task: create a new commit, amend, squash, or cherry-pick. The skill will guide message formatting and handle confirmation for destructive operations. - -## Files - -| File | Loaded when | -|------|-------------| -| `SKILL.md` | Always — gotchas, the flow dispatch table, the gates common to every flow, and the output shape | -| `references/create-commit.md` | Composing a new commit from staged changes | -| `references/rewrite-history.md` | Amending, squashing, or folding a `fixup!`/`squash!` commit into an earlier one | -| `references/cherry-pick.md` | Replaying an existing commit onto the current branch | -| `references/conventional-commits-spec.md` | A type, footer, or breaking-change edge case is not obvious — full spec, 11-type set, commitlint constraint table | -| `references/commit-template.md` | Writing a body for a non-trivial commit — Why / Implementation Notes / Impact structure and the full trailer list | -| `references/sources.md` | Research sources and provenance | - -## Composition - -Part of the git plugin's domain suite. This skill owns commit authoring and history-rewriting operations only; `git-history` inspects history, `git-branches` owns branch lifecycle, and `git-workflow` is the conversational entry point that routes between them. diff --git a/plugins/git/skills/git-commits/SKILL.md b/plugins/git/skills/git-commits/SKILL.md index f1ec375..296ec18 100644 --- a/plugins/git/skills/git-commits/SKILL.md +++ b/plugins/git/skills/git-commits/SKILL.md @@ -8,7 +8,7 @@ description: > Not branch lifecycle -> `git-branches`. metadata: - version: "0.1.4" + version: "0.1.5" category: git source_keys: - conventional-commits-spec @@ -21,7 +21,7 @@ allowed-tools: Bash ## Gotchas -- **Run git as `rtk git `, never bare `git`** — org convention, in `&&` chains too. Exceptions: ADR-0023 clause 3. +- **Run git as `rtk git `, never bare `git`** — org convention, in `&&` chains too, except where a skill's Gotchas name a specific bare-git case (interactive rebase here). - **Refuse to force-push `main`/`master`** — a rewrite leaves the branch diverged and the reflex is to force it back; safe only where nobody else has based work on it. - **`reset --hard` is a confirmation gate, not a default.** It overwrites the working tree, and uncommitted edits it discards were never in git, so no reflog recovers them. Name what will be lost and offer a stash first. - **Never add `--no-verify`** — using it when a hook fails bypasses the QA gate the pipeline depends on. Only on the user's explicit demand, with a warning. diff --git a/plugins/git/skills/git-commits/references/rewrite-history.md b/plugins/git/skills/git-commits/references/rewrite-history.md index c86097e..793f2bb 100644 --- a/plugins/git/skills/git-commits/references/rewrite-history.md +++ b/plugins/git/skills/git-commits/references/rewrite-history.md @@ -21,7 +21,7 @@ Prefer this whenever a commit is written to be folded, because git does the mark 1. `rtk git commit --fixup=` keeps the target's message; `rtk git commit --squash=` lets you edit the combined message later. Both prefix the message with `fixup!`/`squash!` and name the target commit. 2. Get explicit approval — the rebase still rewrites history. -3. Run `git rebase -i --autosquash HEAD~N` — bare, not `rtk`: `-i` opens an interactive sequence editor (ADR-0023). Git pre-fills the todo list with the tagged commits already reordered against their targets; save it unchanged to apply. +3. Run `git rebase -i --autosquash HEAD~N` — bare, not `rtk`: `-i` opens an interactive sequence editor. Git pre-fills the todo list with the tagged commits already reordered against their targets; save it unchanged to apply. **`-i` is not optional here.** On Git 2.39.5, `git rebase --autosquash HEAD~N` without `-i` prints `Successfully rebased and updated refs/heads/.` and exits 0 while leaving the `fixup!` commit in place at its original SHA — `--autosquash` is honoured only by the interactive machinery, and the false success is the trap: the fold is reported as done, and the surviving `fixup!` subject then fails the Conventional Commits `commit-msg` hook. Later Git versions taught the non-interactive rebase to honour the flag, but `-i --autosquash` is correct on every version, so always write that. diff --git a/plugins/git/skills/git-history/README.md b/plugins/git/skills/git-history/README.md deleted file mode 100644 index e208cfa..0000000 --- a/plugins/git/skills/git-history/README.md +++ /dev/null @@ -1,29 +0,0 @@ -# git-history - -Inspect git history — log queries, bisect, and locating problematic commits. - -## What it does - -This skill handles history inspection within the git workflow suite. It queries logs with pickaxe/line-range/custom formats, runs bisect to find bug-introducing commits, and locates commits for downstream cherry-picking or reverting. It returns structured results for agent composition. Rebase, squash, fixup, and other history-rewriting operations are owned by git-commits, not this skill. - -## Composition - -`git-branches` delegates revert here (see `git-branches`'s `references/merging.md`), which is why this skill carries that operation rather than treating it as out of scope; it is general git knowledge, not drawn from the `history-inspection.md` research corpus. Cherry-pick is **not** this skill's: `git-commits` owns it, and this skill's job ends at locating the SHA to hand over. Server-side commit history on a Gitea-hosted repository belongs to `gitea-branches`; this skill reads the local working copy. - -## Usage - -``` -/git-history -``` - -Describe your history task: search logs, bisect for a regression, or locate a specific commit. The skill will query history and return structured results. - -## Files - -| File | Purpose | -|------|---------| -| `SKILL.md` | Skill instructions for agents | -| `references/bisect.md` | Loaded when the entry procedure is bisect: manual and automated flows, exit codes, skip, replay, narrowing, custom terms | -| `references/git-log-format.md` | Loaded when a log or diff flag needs looking up: format placeholders, presets, diff-filter letters, `-L` syntax, ancestry filters, pickaxe binary-file behaviour, diff output-control flags | -| `references/sources.md` | Research sources and provenance | -| `references/README.md` | Index of the references directory | diff --git a/plugins/git/skills/git-history/SKILL.md b/plugins/git/skills/git-history/SKILL.md index 2a7f62f..0ed23c4 100644 --- a/plugins/git/skills/git-history/SKILL.md +++ b/plugins/git/skills/git-history/SKILL.md @@ -8,7 +8,7 @@ description: > `git-commits`. Not a Gitea server's history -> `gitea-branches`. metadata: - version: "1.0.1" + version: "1.0.2" category: git source_keys: - git-scm-bisect-docs @@ -38,7 +38,7 @@ allowed-tools: Bash Default to `rtk git log --oneline`, then narrow by whatever is known: - **Content**: `rtk git log -S"string"`, or `-G"regex"` to match any diff line. `--pickaxe-regex` makes the `-S` argument a POSIX ERE; `--pickaxe-all` shows every file in a matching changeset. -- **A line or function**: `git log -L ,:` or `git log -L ::` — bare, not `rtk`: rtk truncates each diff line at ~72 characters (ADR-0023). Confirm the range resolves before reporting on it — an off-by-one silently omits the target. +- **A line or function**: `git log -L ,:` or `git log -L ::` — bare, not `rtk`: rtk truncates each diff line at ~72 characters. Confirm the range resolves before reporting on it — an off-by-one silently omits the target. - **A file across renames**: `rtk git log --follow -- `. Without `--follow` the history stops at the rename boundary. - **Mainline only**: `--first-parent` follows the integration branch and skips commits merged in from side branches. - **Structured output**: `rtk git log --format="%h | %s | %an (%ar)"`. diff --git a/plugins/git/skills/git-history/references/README.md b/plugins/git/skills/git-history/references/README.md deleted file mode 100644 index c9a302a..0000000 --- a/plugins/git/skills/git-history/references/README.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -source_keys: - - git-scm-bisect-docs - - git-scm-log-docs - - git-scm-diff-docs ---- - -# References - -This directory contains provenance metadata and research sources for the `git-history` skill. - -## Files - -- `sources.md` — Extracted research sources and their contributing documents -- `bisect.md` — The full `git bisect` procedure: manual and automated flows, exit-code semantics, skip and replay, narrowing options, and custom good/bad terms -- `git-log-format.md` — Full `git log` format placeholder catalogue, named format presets, `--diff-filter` letters, `-L` line-range syntax, ancestry filters, pickaxe binary-file behaviour, and `git diff` output-control flags diff --git a/plugins/git/skills/git-history/references/git-log-format.md b/plugins/git/skills/git-history/references/git-log-format.md index 2481e09..8aa5b2d 100644 --- a/plugins/git/skills/git-history/references/git-log-format.md +++ b/plugins/git/skills/git-history/references/git-log-format.md @@ -166,10 +166,10 @@ line at roughly 72 characters with an ellipsis, on the one query whose whole poi is showing line content. ```bash -git log -L 10,20:file.txt # bare per ADR-0023 -git log -L /start_pattern/,/end_pattern/:file.txt # bare per ADR-0023 -git log -L :myfunction:src/app.c # bare per ADR-0023 -git log -L /init/,+15:config.py # bare per ADR-0023; 15 lines after first /init/ match +git log -L 10,20:file.txt # bare (ADR-0023) +git log -L /start_pattern/,/end_pattern/:file.txt # bare (ADR-0023) +git log -L :myfunction:src/app.c # bare (ADR-0023) +git log -L /init/,+15:config.py # bare (ADR-0023); 15 lines after first /init/ match ``` Range formats: @@ -213,8 +213,8 @@ Bare `git`, not `rtk git`: rtk appends a blank line and a `Changes:` trailer, so the output is no longer one record per line. ```bash -git diff --name-only # bare per ADR-0023; only filenames, one per line -git diff --name-status # bare per ADR-0023; status letter + filename per line +git diff --name-only # bare (ADR-0023); only filenames, one per line +git diff --name-status # bare (ADR-0023); status letter + filename per line ``` `--name-status` uses the same status letters as `--diff-filter`. @@ -225,10 +225,10 @@ Bare `git`, not `rtk git`: rtk replaces the word-diff with its own diffstat renderer and emits none of the `[-removed-] {+added+}` markers. ```bash -git diff --word-diff # bare per ADR-0023; inline word-level diff, [-removed-] {+added+} markers -git diff --word-diff=color # bare per ADR-0023; color only, no markers -git diff --word-diff=porcelain # bare per ADR-0023; machine-readable: +/- prefixed lines, ~ for newlines -git diff --word-diff-regex= # bare per ADR-0023; define what counts as a "word" +git diff --word-diff # bare (ADR-0023); inline word-level diff, [-removed-] {+added+} markers +git diff --word-diff=color # bare (ADR-0023); color only, no markers +git diff --word-diff=porcelain # bare (ADR-0023); machine-readable: +/- prefixed lines, ~ for newlines +git diff --word-diff-regex= # bare (ADR-0023); define what counts as a "word" ``` ### Whitespace Flags diff --git a/plugins/git/skills/git-remotes/README.md b/plugins/git/skills/git-remotes/README.md deleted file mode 100644 index 0895aa2..0000000 --- a/plugins/git/skills/git-remotes/README.md +++ /dev/null @@ -1,34 +0,0 @@ -# git-remotes - -Manage git remote repositories — add/remove/configure remotes, push/pull with safety checks, fetch with pruning, and multi-remote workflows. - -## What it does - -This skill handles remote operations within the git workflow suite. It manages remote configuration (add, remove, rename), fetch operations with pruning, push operations with force-push safety (`--force-with-lease --force-if-includes`), and pull strategies (fast-forward, rebase, merge). It returns structured results suitable for agent composition. - -## Usage - -``` -/git-remotes -``` - -Describe your remote operation: add a remote, push, pull, fetch, or configure tracking. The skill will handle the operation with appropriate safety checks and return results. - -## Files - -| File | Purpose | -|------|---------| -| `SKILL.md` | Skill instructions for agents — force-push gate, dispatch table, return format | -| `references/README.md` | Describes the references directory contents | -| `references/remote-config.md` | Read when adding, removing, renaming, inspecting or re-pointing a remote, or configuring tracking, mirroring, or `set-url` | -| `references/fetch.md` | Read when fetching or pruning remote-tracking refs, or doing a shallow or partial fetch | -| `references/push.md` | Read when pushing branches or tags, writing refspecs, or force-pushing | -| `references/pull.md` | Read when integrating remote changes into the current branch, including the divergence rule | -| `references/sources.md` | Research sources and provenance | - -## Composition - -Callers that need submodule initialization after a `--recurse-submodules` pull hand off to -`git-submodules`; local-only work (commits, branches, history) belongs to `git-commits`, -`git-branches`, and `git-history`. The `git-workflow` skill routes humans here for any -remote-touching request. diff --git a/plugins/git/skills/git-remotes/SKILL.md b/plugins/git/skills/git-remotes/SKILL.md index 181768e..e21ddf3 100644 --- a/plugins/git/skills/git-remotes/SKILL.md +++ b/plugins/git/skills/git-remotes/SKILL.md @@ -10,7 +10,7 @@ description: > Not submodule pointers -> `git-submodules`. metadata: - version: "1.0.1" + version: "1.0.2" category: git source_keys: - git-scm-remote-docs diff --git a/plugins/git/skills/git-remotes/references/README.md b/plugins/git/skills/git-remotes/references/README.md deleted file mode 100644 index a9ca455..0000000 --- a/plugins/git/skills/git-remotes/references/README.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -source_keys: - - git-scm-remote-docs - - git-scm-fetch-docs - - git-scm-push-docs - - git-scm-pull-docs - - context7-git-htmldocs ---- - -# References - -This directory contains provenance metadata and research sources for the `git-remotes` skill. - -## Files - -- `sources.md` — Extracted research sources and their contributing documents -- `remote-config.md` — Remote add/remove/rename/inspect, tracking and mirror options, housekeeping, and the full `set-url` form -- `fetch.md` — Fetch and prune options, shallow and partial fetch, the default fetch refspec -- `push.md` — Push options, refspec syntax, force-push safety in full, server-side deny policies -- `pull.md` — Pull strategies, submodule caveat, the divergence rule, and pull config precedence diff --git a/plugins/git/skills/git-remotes/references/push.md b/plugins/git/skills/git-remotes/references/push.md index 8fc10fb..8bec56e 100644 --- a/plugins/git/skills/git-remotes/references/push.md +++ b/plugins/git/skills/git-remotes/references/push.md @@ -50,7 +50,7 @@ Two mitigations: # poisoned by an unrelated fetch. # The inner `git config` is bare: its stdout becomes a remote URL, so any # output rewriting would poison the remote silently. -rtk git remote add origin-push $(git config remote.origin.url) # inner bare per ADR-0023 +rtk git remote add origin-push $(git config remote.origin.url) # inner bare (ADR-0023) rtk git push --force-with-lease origin-push # Option 2 — explicit SHA via a local tag, unaffected by tracking-branch state diff --git a/plugins/git/skills/git-submodules/README.md b/plugins/git/skills/git-submodules/README.md deleted file mode 100644 index 4b1d2b9..0000000 --- a/plugins/git/skills/git-submodules/README.md +++ /dev/null @@ -1,35 +0,0 @@ -# git-submodules - -Add, initialize, update, pin, inspect, and remove git submodules in multi-repository projects. - -## What it does - -This skill handles submodule operations within the git workflow suite: cloning a superproject with -its nested repositories, adding a dependency as a submodule, initializing and updating with -pinning or branch tracking, parallel and recursive traversal, rebinding URLs and tracked branches, -and the full removal sequence including the `.git/modules/` cleanup git leaves behind. It returns -structured results suitable for agent composition. - -It sits alongside the other git skills rather than duplicating them: `git-worktrees` covers -multiple checkouts of a single repository, and `git-remotes` covers the superproject's own remotes. - -## Usage - -``` -/git-submodules -``` - -Describe the submodule task. The skill applies the shared working rules, dispatches to the -reference for that task, and returns structured results (operation, status, per-submodule details, -conflicts, and a recovery `next_step` when applicable). - -## Files - -| File | Purpose | -|------|---------| -| `SKILL.md` | Skill instructions for agents — gotchas, shared working rules, and the task dispatch table | -| `references/README.md` | Describes contents of references/ | -| `references/setup-and-update.md` | Loaded when cloning a superproject, adding a submodule, initializing, updating, or re-pinning one, or running a command across all of them — includes the full `add` and `update` flag tables, the pinning workflows, and the `foreach` shell-variable table | -| `references/urls-and-config.md` | Loaded when changing where a submodule points or how it is configured — `.gitmodules` vs `.git/config` anatomy, both key tables, `sync`/`set-url`/`set-branch`, local mirror overrides, relative URLs, the custom-`update` security gate, and `absorbgitdirs` | -| `references/removal.md` | Loaded when removing or deinitializing a submodule — why `deinit` is not removal, and the four-step removal sequence | -| `references/sources.md` | Research sources and provenance | diff --git a/plugins/git/skills/git-submodules/references/README.md b/plugins/git/skills/git-submodules/references/README.md deleted file mode 100644 index 0df0d93..0000000 --- a/plugins/git/skills/git-submodules/references/README.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -source_keys: - - git-scm-submodule-docs ---- - -# References - -One file per task branch in SKILL.md's dispatch table. Load only the one that matches the request. - -## setup-and-update.md - -Cloning a superproject that has submodules, adding a dependency as a submodule, initializing -without cloning, updating or re-pinning, and running one command across every submodule. Carries -the `add` and `update` flag tables, the keep-pinned and move-the-pin-forward workflows, and the -`foreach` shell-variable table (`$name`, `$sm_path`, `$displaypath`, `$sha1`, `$toplevel`). - -## urls-and-config.md - -Where a submodule points and how it is configured: the `.gitmodules` vs `.git/config` split, both -key tables, `sync` / `set-url` / `set-branch`, local mirror overrides, relative URL resolution, the -security gate on custom `update` commands, and `absorbgitdirs`. - -## removal.md - -Removing a submodule, and why `deinit` alone does not remove one. Carries the full four-step -removal sequence including the manual `.git/modules//` cleanup. - -## sources.md - -Research sources that informed this skill — provenance chain for git-scm-submodule-docs reference -material. diff --git a/plugins/git/skills/git-workflow/README.md b/plugins/git/skills/git-workflow/README.md deleted file mode 100644 index 10659fd..0000000 --- a/plugins/git/skills/git-workflow/README.md +++ /dev/null @@ -1,25 +0,0 @@ -# git-workflow - -Human-friendly interface for interactive git workflows with conversational prompts, progress guidance, and safety confirmations. - -## What it does - -This skill wraps the `git-orchestrate` agent to provide an interactive, educational interface for humans performing git workflows. It is the router for the six local-git domain skills — `git-commits`, `git-branches`, `git-history`, `git-remotes`, `git-submodules` and `git-worktrees` — and `SKILL.md` carries a table mapping each of them to the requests it owns, so an ambiguous request resolves to exactly one domain before anything runs. The skill parses user intent, gathers session context, invokes the orchestrator, and presents results in plain language with inline help, progress updates, and explanations of what's happening. It enforces confirmation gates for destructive operations (force-push, branch deletion, rebasing with history loss, force-checkout) and provides best-practices guidance throughout. The org's non-negotiable git rules live in `references/hard-rules.md` and are loaded only when a request could conflict with one. - -## Usage - -``` -/git-workflow -``` - -Describe your git workflow: commit, create a branch, rebase, inspect history, manage submodules, switch worktrees, or manage remotes. The skill will prompt for any missing details and guide you through the workflow. - -## Files - -| File | Purpose | -|------|---------| -| `SKILL.md` | Skill instructions for agents — the six-domain routing table, the workflow steps, and the interaction style | -| `README.md` | This file | -| `references/hard-rules.md` | The org's non-negotiable git rules; read when a request creates, amends, or rewrites a commit, pushes, or touches hooks, config, or credentials | -| `references/README.md` | Describes the references directory contents | -| `references/sources.md` | Research sources and provenance | diff --git a/plugins/git/skills/git-workflow/references/README.md b/plugins/git/skills/git-workflow/references/README.md deleted file mode 100644 index bcf2db0..0000000 --- a/plugins/git/skills/git-workflow/references/README.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -source_keys: - - nvie-gitflow-post - - atlassian-gitflow-tutorial - - gitflow-cheatsheet - - context7-git-htmldocs - - org-git-conventions ---- - -# References - -This directory contains the org git rules and the provenance metadata for the `git-workflow` -skill. - -## Files - -- `hard-rules.md` — The org's non-negotiable git rules, loaded when a request creates, amends, or - rewrites a commit, pushes, or touches hooks, config, or credentials -- `sources.md` — Extracted research sources and their contributing documents diff --git a/plugins/git/skills/git-worktrees/README.md b/plugins/git/skills/git-worktrees/README.md deleted file mode 100644 index 2042f80..0000000 --- a/plugins/git/skills/git-worktrees/README.md +++ /dev/null @@ -1,24 +0,0 @@ -# git-worktrees - -Manage git worktrees to enable multi-branch parallel development across isolated directories. - -## What it does - -This skill handles worktree operations within the git workflow suite. It creates, lists, locks/unlocks, moves, removes, prunes, and repairs worktrees — letting an agent work on multiple branches simultaneously without stashing. It returns structured results (paths, branches, lock status) suitable for agent composition. For multi-step flows spanning branch strategy plus worktree setup, `git-workflow` handles the broader orchestration and delegates the worktree mechanics here. - -## Usage - -``` -/git-worktrees -``` - -Describe your worktree task: create a worktree for a branch, list existing worktrees, lock one for removable media, move, remove, prune, or repair. The skill will handle the operation with appropriate safety checks and return results. - -## Files - -| File | Purpose | -|------|---------| -| `SKILL.md` | Dispatch table, per-operation gates, and the report format | -| `references/README.md` | Describes the references directory contents | -| `references/worktrees.md` | Read when an operation needs more than the dispatch table: shared vs. per-worktree state, the `add` command forms, the full `add` flag table, orphan branches, sparse-checkout, removable-media locking, remote disambiguation, where to run `repair` from, config keys, and the emergency-fix and PR-review patterns | -| `references/sources.md` | Research sources and provenance | diff --git a/plugins/git/skills/git-worktrees/SKILL.md b/plugins/git/skills/git-worktrees/SKILL.md index a72332c..ebd0422 100644 --- a/plugins/git/skills/git-worktrees/SKILL.md +++ b/plugins/git/skills/git-worktrees/SKILL.md @@ -8,7 +8,7 @@ description: > Not interactive multi-step git guidance -> `git-workflow`. metadata: - version: "1.0.1" + version: "1.0.2" category: git source_keys: - git-scm-worktree-docs @@ -32,7 +32,7 @@ metadata: | Create a local branch tracking a remote one | `rtk git worktree add --track -b /` — always correct. `git worktree add ` expands to exactly this, but **only** under the conditions in `references/worktrees.md` | | Throwaway experiment, no branch | `rtk git worktree add -d ` — detached HEAD | | **Never** `git worktree add /` | That ref resolves, so the shortcut never fires and you get **a detached HEAD, no branch, no upstream**. Commits there go unreachable once HEAD moves, and `git push` needs an explicit refspec. Use the tracking row above | -| List | `git worktree list -v` to read, or `git worktree list --porcelain -z` to parse — both bare per ADR-0023: rtk re-renders the output and drops the porcelain flags | +| List | `git worktree list -v` to read, or `git worktree list --porcelain -z` to parse — both bare (ADR-0023): rtk re-renders the output and drops the porcelain flags | | Lock or unlock | `rtk git worktree lock [--reason ] ` / `rtk git worktree unlock ` | | Move | `rtk git worktree move ` | | Remove | `rtk git worktree remove ` | @@ -63,6 +63,6 @@ worktrees: ``` Derive those fields from `git worktree list --porcelain -z` — bare, not `rtk`: -rtk drops both flags and never emits `locked`/`lock_reason` (ADR-0023). For a single +rtk drops both flags and never emits `locked`/`lock_reason`. For a single operation, report its outcome instead — `created: true`, `moved: true`, `removed: true`. diff --git a/plugins/git/skills/git-worktrees/references/README.md b/plugins/git/skills/git-worktrees/references/README.md deleted file mode 100644 index f5f6037..0000000 --- a/plugins/git/skills/git-worktrees/references/README.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -source_keys: - - git-scm-worktree-docs ---- - -# References - -This directory contains provenance metadata and research sources for the `git-worktrees` skill. - -## Files - -- `sources.md` — Extracted research sources and their contributing documents -- `worktrees.md` — Shared vs. per-worktree state, the `add` command forms, the full `add` flag table, orphan branches, sparse-checkout setup, removable-media locking, remote-branch disambiguation, where to run `repair` from, the config key reference, and the emergency-fix and PR-review workflow patterns diff --git a/plugins/git/skills/pc-author/README.md b/plugins/git/skills/pc-author/README.md deleted file mode 100644 index 61de70f..0000000 --- a/plugins/git/skills/pc-author/README.md +++ /dev/null @@ -1,26 +0,0 @@ -# pc-author - -Create, add, remove, update, and configure `.pre-commit-config.yaml`. - -## What it does - -Manages the pre-commit configuration file in any git repo. When invoked, it scans the repo for languages, proposes appropriate hooks with rationale, and writes or modifies `.pre-commit-config.yaml`. It validates every write with `pre-commit validate-config` and flags stale revision pins. It does not run hooks or install them into `.git/hooks/` — use `pc-run` for that. - -## Usage - -``` -/pc-author -``` - -Invoke with no arguments. The skill determines from context whether to create a new config or modify an existing one. - -## Files - -| File | Purpose | -|------|---------| -| `SKILL.md` | Skill instructions for agents | -| `references/create-config.md` | Loaded when the repo has no `.pre-commit-config.yaml` — the create-from-scratch flow | -| `references/modify-config.md` | Loaded when a `.pre-commit-config.yaml` already exists — add, remove, top-level keys, rev staleness | -| `references/hooks-by-language.md` | Hook recommendations by detected language/extension | -| `references/README.md` | Index of files in references/ | -| `references/sources.md` | Provenance — research sources that informed this skill | diff --git a/plugins/git/skills/pc-author/references/README.md b/plugins/git/skills/pc-author/references/README.md deleted file mode 100644 index 7bc855a..0000000 --- a/plugins/git/skills/pc-author/references/README.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -source_keys: - - context7-pre-commit-com - - pre-commit-com - - context7-pre-commit-hooks - - pre-commit-hooks-github ---- - -# references/ - -| File | Purpose | -|---|---| -| `create-config.md` | The create flow — read when the repo has no `.pre-commit-config.yaml` | -| `modify-config.md` | The modify flow — read when a `.pre-commit-config.yaml` already exists | -| `hooks-by-language.md` | Hook recommendations by language/context — repo, rev, and rationale for adding hooks | -| `sources.md` | Provenance: research sources that informed this skill | diff --git a/plugins/git/skills/pc-run/README.md b/plugins/git/skills/pc-run/README.md deleted file mode 100644 index be4b26c..0000000 --- a/plugins/git/skills/pc-run/README.md +++ /dev/null @@ -1,32 +0,0 @@ -# pc-run - -Runs, installs, updates, and maintains pre-commit hooks in a local git clone. - -## What it does - -`pc-run` handles everything that happens *after* `.pre-commit-config.yaml` exists: wiring hooks into git, running them, bumping their versions, and maintaining the cache. When hooks fail, it identifies the cause and suggests a concrete fix — it does not auto-fix files or edit the config. For creating or editing `.pre-commit-config.yaml`, use `pc-author` instead. - -## Before you start - -- `pre-commit` must be installed and available on `PATH` -- A `.pre-commit-config.yaml` must exist at the repo root (use `pc-author` to create one) - -## Usage - -Common invocations: -- `/pc-run` — run all hooks against all files (default) -- `/pc-run install` — wire hooks into `.git/hooks/` -- `/pc-run autoupdate` — bump all `rev` values to latest -- `/pc-run clean` — wipe the pre-commit cache (requires confirmation) - -## Files - -| File | Purpose | -|------|---------| -| `SKILL.md` | Skill instructions for agents | -| `references/install.md` | The install flow — loaded when the user asks to install or set up hooks | -| `references/autoupdate.md` | The autoupdate flow — loaded when the user asks to bump hook revs | -| `references/clean.md` | The clean flow — loaded when the user asks to wipe the cache or rebuild environments | -| `references/failure-patterns.md` | Hook failure causes and concrete fix suggestions — loaded when a hook fails or never fires | -| `references/sources.md` | Provenance: research sources that informed this skill | -| `references/README.md` | Directory index for references/ | diff --git a/plugins/git/skills/pc-run/references/README.md b/plugins/git/skills/pc-run/references/README.md deleted file mode 100644 index 51290f8..0000000 --- a/plugins/git/skills/pc-run/references/README.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -source_keys: - - context7-pre-commit-com - - pre-commit-com - - context7-pre-commit-hooks - - pre-commit-hooks-github ---- - -# references/ - -| File | Purpose | -|---|---| -| `install.md` | The install flow — read when the user asks to install or set up hooks | -| `autoupdate.md` | The autoupdate flow — read when the user asks to bump hook revs | -| `clean.md` | The clean flow — read when the user asks to wipe the cache or rebuild environments | -| `failure-patterns.md` | Hook failure causes and concrete fix suggestions — read when a hook fails or never fires | -| `sources.md` | Provenance: research sources that informed this skill | diff --git a/plugins/gitea/.apm/skills/gitea-branches/README.md b/plugins/gitea/.apm/skills/gitea-branches/README.md deleted file mode 100644 index 1b7756e..0000000 --- a/plugins/gitea/.apm/skills/gitea-branches/README.md +++ /dev/null @@ -1,50 +0,0 @@ -# gitea-branches - -Manage Gitea repository branches and inspect commit history via the Gitea MCP server. - -## What it does - -This skill handles branch lifecycle operations (list, create, rename, delete) and read-only commit -history (list commits, get a single commit's full detail) against a Gitea repository. It resolves -`owner`/`repo` from the git remote, dispatches to the right MCP tool, and applies safety and -pagination conventions specific to Gitea's API (e.g. refusing to delete a protected branch without -explicit confirmation, and treating unexpected 404s as possible masked 403s). - -## Boundaries - -This skill operates on the Gitea server via the MCP tools, never on your local checkout. Branch -and commit-history work against the working copy belongs to `git-branches` and `git-history`. -Branch references that only exist relative to a pull request — a PR's head or base branch, and -cross-repo fork PR heads in particular — belong to `gitea-prs`; `list_branches` cannot see a fork's -head at all. - -The skill triggers on phrasings like "list branches", "create a branch", "rename a branch", "delete a branch", -"what commits are on this branch", "show commit ", and "what changed in that commit", even -when the user does not say "Gitea", as long as the repo's remote is a Gitea instance. - -## Before you start - -Requires a Gitea MCP server configured with a token that has `write:repository` scope. This is -confirmed for `list_branches`, `create_branch`, and `delete_branch` (and inferred for -`rename_branch`) (Gitea gates reads behind write -scope for repo-scoped operations); `list_commits` and `get_commit` are inferred to need the same -scope by analogy, not explicitly confirmed — see `references/commits.md`. Requires a git remote -named `origin` pointing at the Gitea instance. - -## Usage - -```text -/gitea-branches -``` - -Describe your task: list/create/rename/delete a branch, or list/inspect commits. See `SKILL.md`'s -dispatch table for the full set of recognized invocations. - -## Files - -| File | Purpose | -|------|---------| -| `SKILL.md` | Skill instructions for agents — dispatch table, gotchas | -| `references/branches.md` | Verified call signatures and mechanics for list/create/rename/delete branch | -| `references/commits.md` | Verified call signatures and mechanics for list/get commit | -| `references/sources.md` | Research sources backing the branch/commit guidance | diff --git a/plugins/gitea/.apm/skills/gitea-files/README.md b/plugins/gitea/.apm/skills/gitea-files/README.md deleted file mode 100644 index 3e38b79..0000000 --- a/plugins/gitea/.apm/skills/gitea-files/README.md +++ /dev/null @@ -1,24 +0,0 @@ -# gitea-files - -Read and write individual files and directory/repository trees in a Gitea repository via the Gitea MCP server. - -## What it does - -This skill handles file-domain operations within the Gitea integration suite: reading a single file's contents, listing one directory level, walking a full repository tree (optionally recursive), creating or updating a file, and deleting a file. It owns the SHA-based optimistic-concurrency pattern that Gitea requires for file writes — the domain's sharpest gotcha — and defers branch creation, commit history, and pull request mechanics to `gitea-branches` and `gitea-prs`. - -## Usage - -```text -/gitea-files -``` - -Describe the file task: read a file or directory, walk a tree, create/update a file, or delete a file. Provide `owner`/`repo`/branch (or ask the user if not given) — this skill does not resolve them from a git remote itself. - -## Files - -| File | Purpose | -|------|---------| -| `SKILL.md` | Skill instructions for agents | -| `references/reading.md` | Loaded for the read flow: the three read tools, `ref`/`tree_sha` selection, tree pagination, and why a listing is not a SHA source | -| `references/writing.md` | Loaded for the write flow: the SHA-first create/update/delete sequences, `new_branch_name`, the worked branch + file + PR sequence, and failed-write triage | -| `references/sources.md` | Research sources backing the SHA/concurrency and direct-commit-vs-PR guidance | diff --git a/plugins/gitea/.apm/skills/gitea-issues/README.md b/plugins/gitea/.apm/skills/gitea-issues/README.md deleted file mode 100644 index 5c6549f..0000000 --- a/plugins/gitea/.apm/skills/gitea-issues/README.md +++ /dev/null @@ -1,51 +0,0 @@ -# gitea-issues - -Read and write Gitea issues — list, get, create, comment, close, and search — via the Gitea MCP server. - -## What it does - -This skill handles the issue lifecycle (`list_issues`, `issue_read`, `issue_write`, `search_issues`): -listing repo issues, reading a single issue's details/comments/labels, creating an issue, updating -its state, adding/editing comments, applying labels, and searching issues/PRs across repositories. -The create flow closes out four enrichments deferred from issue #6 comment #848: label inference -and milestone assignment (both by composing `gitea-labels-milestones`), an assignee workaround for -the blocked `get_me` scope, and the "Depends on #N" dependency-linking convention. It supersedes the -`issue`/`issue `/`issue close `/`issue comment ` dispatch this plugin's old single flat -Gitea skill carried, retired when the plugin was split into per-domain deep modules. - -## Before you start - -Requires a Gitea MCP server configured with a token holding `write:issue` + `write:repository`. -Requires a git remote named `origin` pointing at the Gitea instance, unless an orchestrating caller -(e.g. `gitea-workflow`) already resolved `owner`/`repo` for you. - -## How it composes - -This skill composes `gitea-labels-milestones` for *all* label inference, label-name-to-ID -resolution, and milestone lookup, rather than duplicating that taxonomy or its resolution logic — -see `references/enrichments.md` for the call protocol. Managing the label and milestone definitions -themselves (create/edit/delete a label, create/close a milestone) is out of scope here and goes to -`gitea-labels-milestones` directly. - -One boundary the description does not spend characters on, because it was never going to win an -issue request: local git branch or commit work belongs to `gitea-branches` (Gitea-side) or -`git-branches` (working copy). - -## Usage - -```text -/gitea-issues -``` - -Describe your task: list issues, create one, get/comment/close/label a specific issue number, or -search across repos. See `SKILL.md`'s dispatch table for the full set of recognized invocations. - -## Files - -| File | Purpose | -|------|---------| -| `SKILL.md` | Skill instructions for agents — dispatch table, Gotchas | -| `references/issues.md` | Verified call signatures and mechanics for `list_issues`/`issue_read`/`issue_write` | -| `references/search.md` | Verified call signature and mechanics for `search_issues` | -| `references/enrichments.md` | Create-flow enrichments — label inference, milestone assignment, assignee workaround, dependency-linking convention | -| `references/sources.md` | Research sources backing the issue guidance | diff --git a/plugins/gitea/.apm/skills/gitea-labels-milestones/README.md b/plugins/gitea/.apm/skills/gitea-labels-milestones/README.md deleted file mode 100644 index 9088421..0000000 --- a/plugins/gitea/.apm/skills/gitea-labels-milestones/README.md +++ /dev/null @@ -1,31 +0,0 @@ -# gitea-labels-milestones - -Read and write Gitea labels and milestones, and resolve label/milestone identity for the skills that apply them to issues and PRs. - -## What it does - -This skill handles label and milestone CRUD (`label_read`/`label_write`, `milestone_read`/`milestone_write`) — listing repo or org labels, creating/editing/deleting a label, resolving a label name to the numeric ID required to apply it to an issue or PR, and listing/creating/updating/closing/deleting a milestone. It also owns label inference: mapping conversation context (bug report, feature request, urgency language) to this repo's `Kind/*`/`Priority/*`/`Status/*` taxonomy. - -## Composition - -This is a cross-cutting shared skill. `gitea-issues` and `gitea-prs` both compose it whenever they need to apply a label or assign a milestone, rather than duplicating label/milestone logic: they call in for name/title → ID resolution, then their own `issue_write`/`pull_request_write` calls apply the resolved IDs. The split is deliberate — identity resolution lives here once, and the write that attaches an ID to a specific issue or PR lives with the skill that owns that object. - -That relationship is documented here rather than in the skill description, which is preloaded into every session and carries routing information only: an agent reaches this skill because the user asked about labels or milestones, not because two other skills call it. - -## Usage - -```text -/gitea-labels-milestones -``` - -Describe the label or milestone task: list labels, resolve a name to an ID, create/edit/delete a label, or list/create/update/close/delete a milestone. For applying already-resolved labels or a milestone to a specific issue or PR, use `gitea-issues` or `gitea-prs` instead. - -## Files - -| File | Purpose | -|------|---------| -| `SKILL.md` | Skill instructions for agents — dispatch table and Gotchas | -| `references/labels.md` | Execution detail for `label_read`/`label_write` | -| `references/milestones.md` | Execution detail for `milestone_read`/`milestone_write` | -| `references/label-inference.md` | Context-pattern → `Kind/*`/`Priority/*`/`Status/*` label inference guide | -| `references/sources.md` | Research sources backing the label/milestone guidance | diff --git a/plugins/gitea/.apm/skills/gitea-prs/README.md b/plugins/gitea/.apm/skills/gitea-prs/README.md deleted file mode 100644 index 5825923..0000000 --- a/plugins/gitea/.apm/skills/gitea-prs/README.md +++ /dev/null @@ -1,31 +0,0 @@ -# gitea-prs - -List, read, create, update, merge, and review Gitea pull requests. - -## What it does - -This skill handles the pull request lifecycle within the Gitea integration suite — listing and reading PRs (details, diff, changed files, CI status, reviews), creating them (title, body, labels), updating them (title, body, assignees, labels, milestone), adding and removing reviewers, closing/reopening, merging with a chosen strategy and post-merge branch cleanup, and the full code-review flow (create a review with inline comments, submit it, dismiss or delete it, reply to a review comment, and resolve or unresolve a comment thread). It composes `gitea-labels-milestones` for label/milestone ID resolution rather than duplicating that logic — `milestone` applies on an update only, never on create — and defers to `gitea-issues` for anything that turns out to be an issue rather than a PR (they share one number space) and to `gitea-branches`/`gitea-files` for the underlying branch/file operations behind a PR. - -## Usage - -```text -/gitea-prs -``` - -Describe the PR or review task: list PRs, get a PR's status/diff/reviews, create or update a PR, merge one, or create/submit/dismiss a code review. The skill resolves `owner`/`repo` from the `origin` git remote (or takes them from an orchestrating caller) and resolves any label or milestone names via `gitea-labels-milestones` before writing them. - -## Before you start - -Requires a Gitea MCP server configured with a token holding `write:issue` + `write:repository`. -Requires a git remote named `origin` pointing at the Gitea instance, unless an orchestrating caller -(e.g. `gitea-workflow`) already resolved `owner`/`repo` for you. - -## Files - -| File | Purpose | -|------|---------| -| `SKILL.md` | Skill instructions for agents — Gotchas, the dispatch table, and label/milestone ID resolution via `gitea-labels-milestones` | -| `references/pull-requests.md` | Execution detail for `list_pull_requests`, `pull_request_read` (get/get_diff/get_files/get_status), and `pull_request_write` (create/update/close/reopen/update_branch/add_reviewers/remove_reviewers) | -| `references/reviews.md` | Execution detail for `pull_request_review_write` (create/submit/delete/dismiss, plus the comment-thread methods reply_comment/resolve_thread/unresolve_thread) and the review-related `pull_request_read` methods | -| `references/merging.md` | The merge workflow — CI vs. review/branch-protection gates, merge styles, branch cleanup, and the post-merge issue-close check | -| `references/sources.md` | Research sources backing the PR/review guidance | diff --git a/plugins/gitea/.apm/skills/gitea-releases/README.md b/plugins/gitea/.apm/skills/gitea-releases/README.md deleted file mode 100644 index 16ffa1d..0000000 --- a/plugins/gitea/.apm/skills/gitea-releases/README.md +++ /dev/null @@ -1,30 +0,0 @@ -# gitea-releases - -Manage Gitea releases and tags — list, create, and delete releases (with draft/prerelease flags and notes) and their underlying tags. - -## What it does - -This skill handles release and tag operations for a Gitea repository. It creates releases from a tag/target commitish with title, notes, and draft/prerelease flags; lists and paginates releases and tags; retrieves the latest release; and deletes releases and tags as separate, independent destructive operations. It resolves the numeric release id required for deletion instead of assuming a tag name will work. - -## Before you start - -Requires a Gitea MCP server configured with a token holding `write:repository`. Requires a git remote -named `origin` pointing at the Gitea instance, unless an orchestrating caller already resolved -`owner`/`repo` for you. - -## Usage - -```text -/gitea-releases -``` - -Describe your release/tag task: list releases, get the latest release, create a release (with a tag, target, and title), or delete a release or tag. The skill handles resolving the numeric release id where required and keeps release/tag deletion as distinct operations. - -## Files - -| File | Purpose | -|------|---------| -| `SKILL.md` | Skill instructions for agents | -| `references/call-signatures.md` | Tool parameters and response shapes derived from gitea-mcp source (see `references/sources.md`); input params for all nine tools additionally cross-checked live against gitea-mcp v1.7.0 | -| `references/conventions.md` | Semver/draft/prerelease practitioner conventions and pagination behavior | -| `references/sources.md` | Research sources backing the call signatures and conventions | diff --git a/plugins/gitea/.apm/skills/gitea-workflow/README.md b/plugins/gitea/.apm/skills/gitea-workflow/README.md deleted file mode 100644 index 5b9eff8..0000000 --- a/plugins/gitea/.apm/skills/gitea-workflow/README.md +++ /dev/null @@ -1,25 +0,0 @@ -# gitea-workflow - -Human-facing entry point and router for the Gitea integration. - -## What it does - -This skill is the conversational front door to the Gitea suite — it replaces the old flat `/gitea` skill. On its own it never calls a Gitea MCP tool; it composes the six domain skills (`gitea-issues`, `gitea-labels-milestones`, `gitea-prs`, `gitea-branches`, `gitea-files`, `gitea-releases`). It handles the no-args status check-in (open issues + open PRs), which preserves the original flat `/gitea` skill's default behavior; resolves ambiguous issue-or-PR numbers before dispatching (issues and PRs share one number space); and points a user or agent to the right domain skill when it's unclear which one applies. - -## Usage - -```text -/gitea-workflow -``` - -Invoke with no arguments for a status check-in, with a bare number to resolve and show issue or PR detail, or with a general request to be routed to the right domain skill. - -## Files - -| File | Purpose | -|------|---------| -| `SKILL.md` | Skill instructions for agents — Gotchas, the dispatch table keyed on invocation shape, and the common report gate every branch ends in — each branch's own format lives with its reference file | -| `references/status-checkin.md` | Loaded when the skill is invoked with no specific request — the two parallel open-issue/open-PR reads and the two-section report | -| `references/number-resolution.md` | Loaded when the request carries a bare number that says neither "issue" nor "PR" — the `is_pull` resolution call and the hidden-permission-error 404 | -| `references/skill-index.md` | Loaded when the request names a capability but not which skill owns it — the six-skill routing index | -| `references/sources.md` | Research sources backing the routing/status guidance | diff --git a/plugins/gitea/skills/gitea-branches/README.md b/plugins/gitea/skills/gitea-branches/README.md deleted file mode 100644 index 1b7756e..0000000 --- a/plugins/gitea/skills/gitea-branches/README.md +++ /dev/null @@ -1,50 +0,0 @@ -# gitea-branches - -Manage Gitea repository branches and inspect commit history via the Gitea MCP server. - -## What it does - -This skill handles branch lifecycle operations (list, create, rename, delete) and read-only commit -history (list commits, get a single commit's full detail) against a Gitea repository. It resolves -`owner`/`repo` from the git remote, dispatches to the right MCP tool, and applies safety and -pagination conventions specific to Gitea's API (e.g. refusing to delete a protected branch without -explicit confirmation, and treating unexpected 404s as possible masked 403s). - -## Boundaries - -This skill operates on the Gitea server via the MCP tools, never on your local checkout. Branch -and commit-history work against the working copy belongs to `git-branches` and `git-history`. -Branch references that only exist relative to a pull request — a PR's head or base branch, and -cross-repo fork PR heads in particular — belong to `gitea-prs`; `list_branches` cannot see a fork's -head at all. - -The skill triggers on phrasings like "list branches", "create a branch", "rename a branch", "delete a branch", -"what commits are on this branch", "show commit ", and "what changed in that commit", even -when the user does not say "Gitea", as long as the repo's remote is a Gitea instance. - -## Before you start - -Requires a Gitea MCP server configured with a token that has `write:repository` scope. This is -confirmed for `list_branches`, `create_branch`, and `delete_branch` (and inferred for -`rename_branch`) (Gitea gates reads behind write -scope for repo-scoped operations); `list_commits` and `get_commit` are inferred to need the same -scope by analogy, not explicitly confirmed — see `references/commits.md`. Requires a git remote -named `origin` pointing at the Gitea instance. - -## Usage - -```text -/gitea-branches -``` - -Describe your task: list/create/rename/delete a branch, or list/inspect commits. See `SKILL.md`'s -dispatch table for the full set of recognized invocations. - -## Files - -| File | Purpose | -|------|---------| -| `SKILL.md` | Skill instructions for agents — dispatch table, gotchas | -| `references/branches.md` | Verified call signatures and mechanics for list/create/rename/delete branch | -| `references/commits.md` | Verified call signatures and mechanics for list/get commit | -| `references/sources.md` | Research sources backing the branch/commit guidance | diff --git a/plugins/gitea/skills/gitea-files/README.md b/plugins/gitea/skills/gitea-files/README.md deleted file mode 100644 index 3e38b79..0000000 --- a/plugins/gitea/skills/gitea-files/README.md +++ /dev/null @@ -1,24 +0,0 @@ -# gitea-files - -Read and write individual files and directory/repository trees in a Gitea repository via the Gitea MCP server. - -## What it does - -This skill handles file-domain operations within the Gitea integration suite: reading a single file's contents, listing one directory level, walking a full repository tree (optionally recursive), creating or updating a file, and deleting a file. It owns the SHA-based optimistic-concurrency pattern that Gitea requires for file writes — the domain's sharpest gotcha — and defers branch creation, commit history, and pull request mechanics to `gitea-branches` and `gitea-prs`. - -## Usage - -```text -/gitea-files -``` - -Describe the file task: read a file or directory, walk a tree, create/update a file, or delete a file. Provide `owner`/`repo`/branch (or ask the user if not given) — this skill does not resolve them from a git remote itself. - -## Files - -| File | Purpose | -|------|---------| -| `SKILL.md` | Skill instructions for agents | -| `references/reading.md` | Loaded for the read flow: the three read tools, `ref`/`tree_sha` selection, tree pagination, and why a listing is not a SHA source | -| `references/writing.md` | Loaded for the write flow: the SHA-first create/update/delete sequences, `new_branch_name`, the worked branch + file + PR sequence, and failed-write triage | -| `references/sources.md` | Research sources backing the SHA/concurrency and direct-commit-vs-PR guidance | diff --git a/plugins/gitea/skills/gitea-issues/README.md b/plugins/gitea/skills/gitea-issues/README.md deleted file mode 100644 index 5c6549f..0000000 --- a/plugins/gitea/skills/gitea-issues/README.md +++ /dev/null @@ -1,51 +0,0 @@ -# gitea-issues - -Read and write Gitea issues — list, get, create, comment, close, and search — via the Gitea MCP server. - -## What it does - -This skill handles the issue lifecycle (`list_issues`, `issue_read`, `issue_write`, `search_issues`): -listing repo issues, reading a single issue's details/comments/labels, creating an issue, updating -its state, adding/editing comments, applying labels, and searching issues/PRs across repositories. -The create flow closes out four enrichments deferred from issue #6 comment #848: label inference -and milestone assignment (both by composing `gitea-labels-milestones`), an assignee workaround for -the blocked `get_me` scope, and the "Depends on #N" dependency-linking convention. It supersedes the -`issue`/`issue `/`issue close `/`issue comment ` dispatch this plugin's old single flat -Gitea skill carried, retired when the plugin was split into per-domain deep modules. - -## Before you start - -Requires a Gitea MCP server configured with a token holding `write:issue` + `write:repository`. -Requires a git remote named `origin` pointing at the Gitea instance, unless an orchestrating caller -(e.g. `gitea-workflow`) already resolved `owner`/`repo` for you. - -## How it composes - -This skill composes `gitea-labels-milestones` for *all* label inference, label-name-to-ID -resolution, and milestone lookup, rather than duplicating that taxonomy or its resolution logic — -see `references/enrichments.md` for the call protocol. Managing the label and milestone definitions -themselves (create/edit/delete a label, create/close a milestone) is out of scope here and goes to -`gitea-labels-milestones` directly. - -One boundary the description does not spend characters on, because it was never going to win an -issue request: local git branch or commit work belongs to `gitea-branches` (Gitea-side) or -`git-branches` (working copy). - -## Usage - -```text -/gitea-issues -``` - -Describe your task: list issues, create one, get/comment/close/label a specific issue number, or -search across repos. See `SKILL.md`'s dispatch table for the full set of recognized invocations. - -## Files - -| File | Purpose | -|------|---------| -| `SKILL.md` | Skill instructions for agents — dispatch table, Gotchas | -| `references/issues.md` | Verified call signatures and mechanics for `list_issues`/`issue_read`/`issue_write` | -| `references/search.md` | Verified call signature and mechanics for `search_issues` | -| `references/enrichments.md` | Create-flow enrichments — label inference, milestone assignment, assignee workaround, dependency-linking convention | -| `references/sources.md` | Research sources backing the issue guidance | diff --git a/plugins/gitea/skills/gitea-labels-milestones/README.md b/plugins/gitea/skills/gitea-labels-milestones/README.md deleted file mode 100644 index 9088421..0000000 --- a/plugins/gitea/skills/gitea-labels-milestones/README.md +++ /dev/null @@ -1,31 +0,0 @@ -# gitea-labels-milestones - -Read and write Gitea labels and milestones, and resolve label/milestone identity for the skills that apply them to issues and PRs. - -## What it does - -This skill handles label and milestone CRUD (`label_read`/`label_write`, `milestone_read`/`milestone_write`) — listing repo or org labels, creating/editing/deleting a label, resolving a label name to the numeric ID required to apply it to an issue or PR, and listing/creating/updating/closing/deleting a milestone. It also owns label inference: mapping conversation context (bug report, feature request, urgency language) to this repo's `Kind/*`/`Priority/*`/`Status/*` taxonomy. - -## Composition - -This is a cross-cutting shared skill. `gitea-issues` and `gitea-prs` both compose it whenever they need to apply a label or assign a milestone, rather than duplicating label/milestone logic: they call in for name/title → ID resolution, then their own `issue_write`/`pull_request_write` calls apply the resolved IDs. The split is deliberate — identity resolution lives here once, and the write that attaches an ID to a specific issue or PR lives with the skill that owns that object. - -That relationship is documented here rather than in the skill description, which is preloaded into every session and carries routing information only: an agent reaches this skill because the user asked about labels or milestones, not because two other skills call it. - -## Usage - -```text -/gitea-labels-milestones -``` - -Describe the label or milestone task: list labels, resolve a name to an ID, create/edit/delete a label, or list/create/update/close/delete a milestone. For applying already-resolved labels or a milestone to a specific issue or PR, use `gitea-issues` or `gitea-prs` instead. - -## Files - -| File | Purpose | -|------|---------| -| `SKILL.md` | Skill instructions for agents — dispatch table and Gotchas | -| `references/labels.md` | Execution detail for `label_read`/`label_write` | -| `references/milestones.md` | Execution detail for `milestone_read`/`milestone_write` | -| `references/label-inference.md` | Context-pattern → `Kind/*`/`Priority/*`/`Status/*` label inference guide | -| `references/sources.md` | Research sources backing the label/milestone guidance | diff --git a/plugins/gitea/skills/gitea-prs/README.md b/plugins/gitea/skills/gitea-prs/README.md deleted file mode 100644 index 5825923..0000000 --- a/plugins/gitea/skills/gitea-prs/README.md +++ /dev/null @@ -1,31 +0,0 @@ -# gitea-prs - -List, read, create, update, merge, and review Gitea pull requests. - -## What it does - -This skill handles the pull request lifecycle within the Gitea integration suite — listing and reading PRs (details, diff, changed files, CI status, reviews), creating them (title, body, labels), updating them (title, body, assignees, labels, milestone), adding and removing reviewers, closing/reopening, merging with a chosen strategy and post-merge branch cleanup, and the full code-review flow (create a review with inline comments, submit it, dismiss or delete it, reply to a review comment, and resolve or unresolve a comment thread). It composes `gitea-labels-milestones` for label/milestone ID resolution rather than duplicating that logic — `milestone` applies on an update only, never on create — and defers to `gitea-issues` for anything that turns out to be an issue rather than a PR (they share one number space) and to `gitea-branches`/`gitea-files` for the underlying branch/file operations behind a PR. - -## Usage - -```text -/gitea-prs -``` - -Describe the PR or review task: list PRs, get a PR's status/diff/reviews, create or update a PR, merge one, or create/submit/dismiss a code review. The skill resolves `owner`/`repo` from the `origin` git remote (or takes them from an orchestrating caller) and resolves any label or milestone names via `gitea-labels-milestones` before writing them. - -## Before you start - -Requires a Gitea MCP server configured with a token holding `write:issue` + `write:repository`. -Requires a git remote named `origin` pointing at the Gitea instance, unless an orchestrating caller -(e.g. `gitea-workflow`) already resolved `owner`/`repo` for you. - -## Files - -| File | Purpose | -|------|---------| -| `SKILL.md` | Skill instructions for agents — Gotchas, the dispatch table, and label/milestone ID resolution via `gitea-labels-milestones` | -| `references/pull-requests.md` | Execution detail for `list_pull_requests`, `pull_request_read` (get/get_diff/get_files/get_status), and `pull_request_write` (create/update/close/reopen/update_branch/add_reviewers/remove_reviewers) | -| `references/reviews.md` | Execution detail for `pull_request_review_write` (create/submit/delete/dismiss, plus the comment-thread methods reply_comment/resolve_thread/unresolve_thread) and the review-related `pull_request_read` methods | -| `references/merging.md` | The merge workflow — CI vs. review/branch-protection gates, merge styles, branch cleanup, and the post-merge issue-close check | -| `references/sources.md` | Research sources backing the PR/review guidance | diff --git a/plugins/gitea/skills/gitea-releases/README.md b/plugins/gitea/skills/gitea-releases/README.md deleted file mode 100644 index 16ffa1d..0000000 --- a/plugins/gitea/skills/gitea-releases/README.md +++ /dev/null @@ -1,30 +0,0 @@ -# gitea-releases - -Manage Gitea releases and tags — list, create, and delete releases (with draft/prerelease flags and notes) and their underlying tags. - -## What it does - -This skill handles release and tag operations for a Gitea repository. It creates releases from a tag/target commitish with title, notes, and draft/prerelease flags; lists and paginates releases and tags; retrieves the latest release; and deletes releases and tags as separate, independent destructive operations. It resolves the numeric release id required for deletion instead of assuming a tag name will work. - -## Before you start - -Requires a Gitea MCP server configured with a token holding `write:repository`. Requires a git remote -named `origin` pointing at the Gitea instance, unless an orchestrating caller already resolved -`owner`/`repo` for you. - -## Usage - -```text -/gitea-releases -``` - -Describe your release/tag task: list releases, get the latest release, create a release (with a tag, target, and title), or delete a release or tag. The skill handles resolving the numeric release id where required and keeps release/tag deletion as distinct operations. - -## Files - -| File | Purpose | -|------|---------| -| `SKILL.md` | Skill instructions for agents | -| `references/call-signatures.md` | Tool parameters and response shapes derived from gitea-mcp source (see `references/sources.md`); input params for all nine tools additionally cross-checked live against gitea-mcp v1.7.0 | -| `references/conventions.md` | Semver/draft/prerelease practitioner conventions and pagination behavior | -| `references/sources.md` | Research sources backing the call signatures and conventions | diff --git a/plugins/gitea/skills/gitea-workflow/README.md b/plugins/gitea/skills/gitea-workflow/README.md deleted file mode 100644 index 5b9eff8..0000000 --- a/plugins/gitea/skills/gitea-workflow/README.md +++ /dev/null @@ -1,25 +0,0 @@ -# gitea-workflow - -Human-facing entry point and router for the Gitea integration. - -## What it does - -This skill is the conversational front door to the Gitea suite — it replaces the old flat `/gitea` skill. On its own it never calls a Gitea MCP tool; it composes the six domain skills (`gitea-issues`, `gitea-labels-milestones`, `gitea-prs`, `gitea-branches`, `gitea-files`, `gitea-releases`). It handles the no-args status check-in (open issues + open PRs), which preserves the original flat `/gitea` skill's default behavior; resolves ambiguous issue-or-PR numbers before dispatching (issues and PRs share one number space); and points a user or agent to the right domain skill when it's unclear which one applies. - -## Usage - -```text -/gitea-workflow -``` - -Invoke with no arguments for a status check-in, with a bare number to resolve and show issue or PR detail, or with a general request to be routed to the right domain skill. - -## Files - -| File | Purpose | -|------|---------| -| `SKILL.md` | Skill instructions for agents — Gotchas, the dispatch table keyed on invocation shape, and the common report gate every branch ends in — each branch's own format lives with its reference file | -| `references/status-checkin.md` | Loaded when the skill is invoked with no specific request — the two parallel open-issue/open-PR reads and the two-section report | -| `references/number-resolution.md` | Loaded when the request carries a bare number that says neither "issue" nor "PR" — the `is_pull` resolution call and the hidden-permission-error 404 | -| `references/skill-index.md` | Loaded when the request names a capability but not which skill owns it — the six-skill routing index | -| `references/sources.md` | Research sources backing the routing/status guidance | diff --git a/plugins/kyberforge/.apm/skills/agent-audit/README.md b/plugins/kyberforge/.apm/skills/agent-audit/README.md deleted file mode 100644 index 3face54..0000000 --- a/plugins/kyberforge/.apm/skills/agent-audit/README.md +++ /dev/null @@ -1,79 +0,0 @@ -# agent-audit - -Audits an agent definition for correctness and quality against the Claude Code and Copilot agent -references and the house context-budget contract (ADR-0020) — a single vendor-neutral file at -plugin/APM scope, or a Claude Code and Copilot file pair at project/user scope. - -## What it does - -1. Runs `scripts/validate.sh` and `scripts/validate-provenance.sh` for structural and provenance - checks, plus `scripts/vale-wrap.sh` — a Vale prefilter that deterministically flags - non-imperative description openers, composition and architecture notes, vague wording, padding - phrases, "There is/are" sentence openers, and CC-specific "Use proactively" phrasing in a - Copilot or vendor-neutral description -2. Reads the agent file, and its counterpart when one exists, then loads the contract for its scope -3. Applies qualitative checks across description, body, delegation and comment discipline, loading - one rubric from `references/` per group -4. Outputs a compact findings report — findings only, grouped by dimension, each with Why and Fix — - and a result block with handoff to `agent-author` - -Two things follow from ADR-0020 and are easy to get backwards. Agents take the **same** description -gates a skill takes — 250 characters SUGGESTION, 400 FAIL, since a `name` + `description` is -preloaded into every session either way — and **no body word gate at all**, because an agent body -becomes the system prompt of a fresh context rather than competing with the caller's live -conversation. Body length is judged through the delegation check instead: an agent body that -restates a procedure owned by a skill it can invoke is a FAIL, because a plugin-scope agent has no -sibling `references/` directory to disclose to and can only delegate. - -At **plugin/APM scope** the audit accepts the single `.apm/agents/.agent.md` file — there is -no counterpart, and pair consistency does not apply. `validate.sh` hard-`FAIL`s any frontmatter -field outside the vendor-neutral allowlist, since `apm compile` copies frontmatter verbatim to both -harnesses and an unsafe field cannot be silently dropped for just one of them. The allowlist lives -in the `apm-agent-allowlist` section of `references/field-inventory.md`, is read from there as data -by the script, and is deliberately not restated anywhere else in this skill (ADR-0009). - -At **project/user scope** the audit accepts either file in a CC `.md` / Copilot `.agent.md` pair, -derives the counterpart automatically, and validates both, including the field-leakage checks in -each direction. - -## Usage - -``` -/agent-audit -``` - -Pass the path to either agent file as the argument. - -## Files - -| File | Purpose | -|------|---------| -| `SKILL.md` | Skill instructions for agents | -| `assets/vale/.vale.ini` | Vale config: scopes `Kyberforge` to `**/agents/*.md`, `Kyberforge`+`KyberforgeCopilot` to `**/*.agent.md` | -| `assets/vale/styles/Kyberforge/CompositionNote.yml` | Flags composition and architecture notes in a description ("cross-cutting", "entry point", "composes", "rather than duplicating") that belong in README.md | -| `assets/vale/styles/Kyberforge/DescriptionOpener.yml` | Flags descriptions opening with "This..." instead of an imperative "Use when..." | -| `assets/vale/styles/Kyberforge/PaddingPhrase.yml` | Flags generic "see references/ for info" pointers instead of specific file references | -| `assets/vale/styles/Kyberforge/SentenceOpenerThereIs.yml` | Flags sentences opening with "There is/are" instead of naming the subject directly | -| `assets/vale/styles/Kyberforge/VagueWording.yml` | Flags vague capability wording ("helps with", "utilize", "assists with", "used for") in descriptions | -| `assets/vale/styles/KyberforgeCopilot/ProactivePhrase.yml` | Flags CC-specific "Use proactively" phrasing with no effect in Copilot descriptions | -| `references/README.md` | Directory documentation for references/ | -| `references/finding-criteria.md` | Every dimension's FAIL and SUGGESTION criteria — the one Step 3 file read on every run; it decides which rubrics below are worth loading | -| `references/description-quality.md` | Rubric for the description dimension — why the description is the expensive part, the hand-invoked contract, the three-part shape, indirect triggers, and near-miss exclusions | -| `references/body-and-delegation.md` | Rubric for the body, delegation and comment-discipline dimensions — the core test, the delegation FAIL, why agents take no body word gate, and what an agent body is for | -| `references/scope-plugin-apm.md` | Scope contract for a single vendor-neutral APM agent file — allowlist, dimension routing, and the dimensions that do not apply | -| `references/scope-project-user.md` | Scope contract for a CC / Copilot pair — counterpart derivation, provider field rules, pair consistency | -| `references/validation-scripts.md` | Loaded only when a Step 1 script fails or cannot run — scope-detection walk-up, manual fallback checks, known script failures | -| `references/field-inventory.md` | Authoritative field lists read as data by `validate.sh`: valid CC and Copilot agent fields, and the vendor-neutral plugin/APM-scope allowlist | -| `references/sources.md` | Research provenance for skill content | -| `scripts/README.md` | Directory documentation for scripts/ | -| `scripts/validate.sh` | Structural validator — required fields, name format, placeholder detection, the ADR-0020 description budget, and the field rules for the detected scope | -| `scripts/validate-provenance.sh` | Provenance chain validation against `sources.md` at the package root (plugin/APM scope only) | -| `scripts/vale-wrap.sh` | Drop-in `vale` wrapper that works around a frontmatter-description NLP scope limitation | -| `tests/README.md` | (source-only) Bats test dependency and run instructions | -| `tests/validate.bats` | (source-only) Bats tests for validate.sh | -| `tests/validate-provenance.bats` | (source-only) Bats tests for validate-provenance.sh | - -Rows marked **(source-only)** exist in the authoring source (`.apm/skills/agent-audit/`) but are -not present in an installed plugin: `scripts/sync-plugin-content.sh` strips -`//tests` when it generates the flat mirror, because these are dev-time fixtures no -plugin host needs to discover (ADR-0017). Run them from a repo checkout, not from an install. diff --git a/plugins/kyberforge/.apm/skills/agent-audit/SKILL.md b/plugins/kyberforge/.apm/skills/agent-audit/SKILL.md index 67396dc..91d3e5d 100644 --- a/plugins/kyberforge/.apm/skills/agent-audit/SKILL.md +++ b/plugins/kyberforge/.apm/skills/agent-audit/SKILL.md @@ -7,7 +7,7 @@ description: > directory -> skill-audit. allowed-tools: Bash Read metadata: - version: "1.0.1" + version: "1.0.2" category: factory source_keys: - context7-websites-code-claude @@ -34,7 +34,7 @@ bash scripts/validate-provenance.sh bash scripts/vale-wrap.sh [] ``` -`validate.sh` takes either half of a project/user-scope pair or the single plugin/APM-scope file, detects the provider from the extension and the scope by walking up, then checks required fields, kebab-case `name`, `FILL IN:` placeholders, template HTML comments left in frontmatter, the ADR-0020 description budget (250 chars SUGGESTION, 400 FAIL, measured on the folded YAML value) and the fields that scope permits. Its findings become the `### Structure` dimension — its FAILs and its SUGGESTIONs both — except the ones the Step 2 scope contract re-routes. +`validate.sh` takes either half of a project/user-scope pair or the single plugin/APM-scope file, detects the provider from the extension and the scope by walking up, then checks required fields, kebab-case `name`, `FILL IN:` placeholders, template HTML comments left in frontmatter, the description budget (250 chars SUGGESTION, 400 FAIL, measured on the folded YAML value) and the fields that scope permits. Its findings become the `### Structure` dimension — its FAILs and its SUGGESTIONs both — except the ones the Step 2 scope contract re-routes. If a validation script fails or cannot run — Bash denied, `python3` or `vale` absent, `references/field-inventory.md` missing — read `references/validation-scripts.md`; what these scripts measure is not reproducible by reading. diff --git a/plugins/kyberforge/.apm/skills/agent-audit/references/README.md b/plugins/kyberforge/.apm/skills/agent-audit/references/README.md deleted file mode 100644 index 6ae112e..0000000 --- a/plugins/kyberforge/.apm/skills/agent-audit/references/README.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -source_keys: [] ---- - -# references/ - -Additional documentation agents load on demand. - -## Files - -| File | Purpose | -|------|---------| -| `finding-criteria.md` | Every dimension's FAIL and SUGGESTION criteria — the one Step 3 file read on every run; it decides which rubrics below are worth loading. | -| `description-quality.md` | Rubric for the description dimension — why the description is the expensive part, the hand-invoked contract, the three-part shape, indirect triggers, and near-miss exclusions. | -| `body-and-delegation.md` | Rubric for the body, delegation and comment-discipline dimensions — the core test, the delegation FAIL, why agents take no body word gate, and what an agent body is for. | -| `scope-plugin-apm.md` | Contract for a single vendor-neutral `.apm/agents/.agent.md` file — allowlist, dimension routing, and the dimensions that do not apply. | -| `scope-project-user.md` | Contract for a Claude Code / Copilot file pair — counterpart derivation, provider field rules, and pair consistency. | -| `validation-scripts.md` | Loaded only when a Step 1 script fails or cannot run — scope-detection walk-up, manual fallback checks, and known script failures. | -| `field-inventory.md` | Authoritative field lists, read as data by `validate.sh`: valid CC and Copilot agent fields, and the vendor-neutral plugin/APM allowlist. | -| `sources.md` | Research provenance records for skill content. Load only when tracing the origin of a specific rule or field constraint. | diff --git a/plugins/kyberforge/.apm/skills/agent-audit/references/body-and-delegation.md b/plugins/kyberforge/.apm/skills/agent-audit/references/body-and-delegation.md index 325bed6..c3d32d6 100644 --- a/plugins/kyberforge/.apm/skills/agent-audit/references/body-and-delegation.md +++ b/plugins/kyberforge/.apm/skills/agent-audit/references/body-and-delegation.md @@ -10,7 +10,7 @@ source_keys: # Body, Delegation and Comment Discipline Reference Upstream source: Claude Code subagent and plugin references, GitHub Copilot custom-agents -configuration. House contract: ADR-0020, the context budget. +configuration. House contract: the context budget. Read this when judging the **body**, **delegation** and **comment-discipline** dimensions. @@ -23,8 +23,8 @@ dilutes the signal of what matters. ## Agents take no body word gate -ADR-0020 gates a skill body at 600 words SUGGESTION / 900 FAIL and deliberately gates an agent body -at nothing. The two are not the same construct: a skill body is loaded into the caller's live +A skill body is gated at 600 words SUGGESTION / 900 FAIL; an agent body is deliberately gated at +nothing. The two are not the same construct: a skill body is loaded into the caller's live context and competes with the conversation already there, while an agent body *becomes* the system prompt of a fresh context that has nothing else in it. The rationale for the 900-word ceiling does not transfer, so: diff --git a/plugins/kyberforge/.apm/skills/agent-audit/references/description-quality.md b/plugins/kyberforge/.apm/skills/agent-audit/references/description-quality.md index 4083917..6382d84 100644 --- a/plugins/kyberforge/.apm/skills/agent-audit/references/description-quality.md +++ b/plugins/kyberforge/.apm/skills/agent-audit/references/description-quality.md @@ -9,7 +9,7 @@ source_keys: # Agent Description Quality Reference Upstream source: Claude Code subagent reference, GitHub Copilot custom-agents configuration. -House contract: ADR-0020, the context budget. The house contract is narrower than either +House contract: the context budget. The house contract is narrower than either platform's schema rather than a reinterpretation of it: where both speak, both must be satisfied. ## Why the description is the expensive part diff --git a/plugins/kyberforge/.apm/skills/agent-audit/references/finding-criteria.md b/plugins/kyberforge/.apm/skills/agent-audit/references/finding-criteria.md index 5cd8509..6c9c5e0 100644 --- a/plugins/kyberforge/.apm/skills/agent-audit/references/finding-criteria.md +++ b/plugins/kyberforge/.apm/skills/agent-audit/references/finding-criteria.md @@ -90,8 +90,8 @@ Flag as SUGGESTION if: - A rationale is missing from a rule the agent is expected to enforce — present but unexplained - Comments are useful but verbose enough to bury the field they annotate -**Never report an agent body as too long on a word count.** ADR-0020 gates a skill body at -600/900 words and deliberately gates an agent body at nothing, because an agent body *becomes* the +**Never report an agent body as too long on a word count.** A skill body is gated at 600/900 words; +an agent body is deliberately gated at nothing, because an agent body *becomes* the system prompt of a fresh context rather than competing with a live conversation. No number exists to cite. The one length signal that applies is the Copilot runtime's 30,000-character body limit, which `validate.sh` already reports as a SUGGESTION. Length is judged through the delegation FAIL diff --git a/plugins/kyberforge/.apm/skills/agent-author/README.md b/plugins/kyberforge/.apm/skills/agent-author/README.md deleted file mode 100644 index 6b45bbf..0000000 --- a/plugins/kyberforge/.apm/skills/agent-author/README.md +++ /dev/null @@ -1,58 +0,0 @@ -# agent-author - -Creates and improves agent definition files for Claude Code and GitHub Copilot CLI. - -## What it does - -Scaffolds and fills in agent definition files at plugin/APM, project, or user scope. Project and user scope always generate a Claude Code + Copilot CLI file pair (`.md` + `.agent.md`) in one pass. Plugin/APM scope generates a single vendor-neutral `.apm/agents/.agent.md` file instead — no separate Claude Code / Copilot split, since `apm compile` has no per-target field integrator (see ADR-0016). Also applies improvement signals — grill output, inline feedback, session context — to existing agent files. Bumps the version after every change: the resolved package's `apm.yml` at plugin/APM scope (minor for new agents, patch for improvements); project/user scope has no manifest to bump. - -## Before you start - -Have ready: the agent's name (kebab-case), the root directory (plugin root, project root, or `~`), a one-sentence purpose, and the triggering condition (when should the runtime delegate to this agent?). - -## Usage - -``` -/agent-author -``` - -**Manual scaffold (human workflow):** -```bash -bash scripts/new-agent.sh - -# Examples: -bash scripts/new-agent.sh code-reviewer packages/my-package/ # plugin/APM scope if packages/my-package/apm.yml has a type: field -bash scripts/new-agent.sh deploy-assistant . -bash scripts/new-agent.sh security-reviewer ~ -``` - -## Files - -| File | Purpose | -|------|---------| -| `SKILL.md` | Skill instructions for agents — gotchas, the create/improve dispatch table, the scope dispatch table, the shared gates, and validation/close | -| `scripts/new-agent.sh` | Scaffolds agent definition file(s) from templates — a single `.apm/agents/.agent.md` at plugin/APM scope, or a Claude Code + Copilot CLI pair at project/user scope | -| `references/create.md` | Create flow: prerequisites, scaffold and scope walk-up, what to fill in, package-root `sources.md` | -| `references/improve.md` | Improve flow: signal verification, root-cause grouping, generalizing, delegation over growth, ADR-0020 retrofit | -| `references/contract.md` | Description and body contract: three-part description shape, 250/400 tiers, delegation rule in place of a body word gate, invocation axis | -| `references/plugin-scope.md` | Plugin/APM scope field rules for the single vendor-neutral file, plus its pre-audit checklist | -| `references/project-user-scope.md` | Project/user scope field rules for the Claude Code + Copilot pair, both Copilot formats, plus its pre-audit checklist | -| `references/deployment-modes.md` | Scope hierarchy and precedence, scoped identifiers, cache isolation, path conventions | -| `references/scripts.md` | Conventions for new-agent.sh and the templates it copies: contract, template variables, file placement, error messages | -| `references/sources.md` | Research provenance — sources that informed this skill | -| `assets/templates/claude-code.md` | Annotated Claude Code agent definition template (project/user scope) | -| `assets/templates/copilot.agent.md.template` | Annotated Copilot CLI agent definition template (project/user scope) | -| `assets/templates/apm-agent.md` | Annotated vendor-neutral APM agent definition template (plugin/APM scope) | -| `tests/new-agent.bats` | (source-only) bats tests for `scripts/new-agent.sh` | -| `assets/README.md` | Directory meta-documentation for assets/ | -| `references/README.md` | Directory meta-documentation for references/ | -| `scripts/README.md` | Directory meta-documentation for scripts/ | -| `tests/README.md` | (source-only) bats dependency instructions and run command | - -Rows marked **(source-only)** exist in the authoring source (`.apm/skills/agent-author/`) but are -not present in an installed plugin: `scripts/sync-plugin-content.sh` strips -`//tests` when it generates the flat mirror, because these are dev-time fixtures no -plugin host needs to discover (ADR-0017). Run them from a repo checkout, not from an install. The -`assets/templates/` rows above are unaffected — the exclusion is depth-scoped to -`//tests`, so template trees that themselves contain a `tests/` directory ship -intact. diff --git a/plugins/kyberforge/.apm/skills/agent-author/SKILL.md b/plugins/kyberforge/.apm/skills/agent-author/SKILL.md index c399ffa..af51352 100644 --- a/plugins/kyberforge/.apm/skills/agent-author/SKILL.md +++ b/plugins/kyberforge/.apm/skills/agent-author/SKILL.md @@ -6,7 +6,7 @@ description: > Not read-only review -> `agent-audit`. Not skills -> `skill-author`. allowed-tools: Bash Read Write Edit metadata: - version: "1.0.1" + version: "1.0.2" category: factory source_keys: - context7-websites-code-claude diff --git a/plugins/kyberforge/.apm/skills/agent-author/references/README.md b/plugins/kyberforge/.apm/skills/agent-author/references/README.md deleted file mode 100644 index ef252d0..0000000 --- a/plugins/kyberforge/.apm/skills/agent-author/references/README.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -source_keys: [] ---- - -# references/ - -## create.md - -The create flow, loaded from SKILL.md Step 1 when no agent file exists at the target path. -Covers: prerequisites, the scaffold script and its scope walk-up, what to fill in at every scope, -and populating or deleting the package-root `sources.md`. - -## improve.md - -The improve flow, loaded from SKILL.md Step 1 when a file exists and at least one improvement -signal is present. Covers: signal verification, partial-pair recovery, root-cause grouping, -generalizing rather than patching, delegation over growth, and the ADR-0020 retrofit rule. - -## contract.md - -The description and body contract, loaded from SKILL.md Step 3 before any description is written -or any body restructured. Covers: the three-part description shape, banned description content, -boundary-target resolution, the 250/400 length tiers, the body role-instruction pattern, the -delegation rule that replaces a body word gate, and the invocation axis. - -## plugin-scope.md - -Field rules and the pre-audit checklist for the single vendor-neutral `.apm/agents/.agent.md` -file. Loaded from SKILL.md Step 2 when the scaffold resolves plugin/APM scope. - -## project-user-scope.md - -Field rules and the pre-audit checklist for the Claude Code `.md` + Copilot `.agent.md` pair, -including the two distinct Copilot formats. Loaded from SKILL.md Step 2 when the scaffold resolves -project or user scope. - -## deployment-modes.md - -Scope hierarchy and precedence, scoped identifiers for plugin subdirectory agents, cache isolation -behaviour, and Copilot CLI path conventions. Loaded from SKILL.md Step 2 when precedence, paths or -cache isolation matter to the run. - -## scripts.md - -Conventions for the `new-agent.sh` scaffold script, the templates it copies, and any future script -in this skill. Loaded from `create.md` Step 1 when the script or a template has to change. Covers: -the no-interactive-prompts rule, structured output, idempotency, template variables, file -placement, error messages, and the no-restated-field-roster rule that `tests/new-agent.bats` -enforces. - -## sources.md - -Research provenance record for this skill. Lists the upstream research sources -(claude-code-plugins and github-copilot-plugins research docs) that informed SKILL.md and the -reference files. Used by `skill-audit` to validate the provenance chain. diff --git a/plugins/kyberforge/.apm/skills/agent-author/references/contract.md b/plugins/kyberforge/.apm/skills/agent-author/references/contract.md index cea9336..d5ee27e 100644 --- a/plugins/kyberforge/.apm/skills/agent-author/references/contract.md +++ b/plugins/kyberforge/.apm/skills/agent-author/references/contract.md @@ -6,7 +6,7 @@ source_keys: # The agent description and body contract -House contract, set by ADR-0020. The counts and the boundary targets are enforced by +House contract. The counts and the boundary targets are enforced by `agent-audit`'s `scripts/validate.sh`; the prose patterns by the Vale styles it bundles; the judgment calls by its reference files. @@ -40,9 +40,8 @@ Banned from a description; move it to the body or to `README.md`: - Restating the same trigger twice in two registers — a verb list, then the same verbs re-quoted as user phrasings. This is a FAIL, not a suggestion. -**Do not open with an action verb.** "Reviews…", "Analyzes…", "Generates…" was the old house rule -and ADR-0020 deleted it: the opener is `Use when`, matching every skill in this corpus, so one -router reads one shape. +**Do not open with an action verb.** The opener is `Use when`, matching every skill in this corpus, +so one router reads one shape. **"Use proactively" is Claude Code-only, and conditional even there.** The phrase steers the Claude Code runtime to offer an agent unprompted and does nothing anywhere else, so where it may diff --git a/plugins/kyberforge/.apm/skills/agent-author/references/improve.md b/plugins/kyberforge/.apm/skills/agent-author/references/improve.md index 0aef172..2a30537 100644 --- a/plugins/kyberforge/.apm/skills/agent-author/references/improve.md +++ b/plugins/kyberforge/.apm/skills/agent-author/references/improve.md @@ -66,9 +66,10 @@ answer is no. all caps (ALWAYS/NEVER) is usually better reframed as why the behaviour matters, so the agent can apply judgment at the edges. -**Retrofit before extending.** Any agent predating ADR-0020 has to meet the description contract -before any other edit lands — the gates are hot and carry no baseline file, so a one-line fix to a -non-compliant agent cannot be committed until its description meets `references/contract.md`. +**Retrofit before extending.** Any agent whose description does not meet the contract has to be +brought into compliance before any other edit lands — the gates are hot and carry no baseline file, +so a one-line fix to a non-compliant agent cannot be committed until its description meets +`references/contract.md`. Treat that retrofit as part of the same change, not a follow-up. **Re-check the scope rules.** Read the reference for the resolved scope (`SKILL.md` Step 2) and diff --git a/plugins/kyberforge/.apm/skills/apm-install/README.md b/plugins/kyberforge/.apm/skills/apm-install/README.md deleted file mode 100644 index 995a182..0000000 --- a/plugins/kyberforge/.apm/skills/apm-install/README.md +++ /dev/null @@ -1,22 +0,0 @@ -# apm-install - -Installs and configures the `apm` (Agent Package Manager) CLI and the agent runtimes it manages. - -## What it does - -Covers the two provisioning steps for working with apm: installing the `apm` binary itself (quick-install script, pinned version, air-gapped mirror, or pip/pipx), and installing/managing an agent runtime apm drives (`apm runtime setup copilot|codex|gemini|llm`, listing installed runtimes, checking which one `apm run` defaults to). - -## Usage - -``` -/apm-install -``` - -Once `apm` and a runtime are in place, use `apm-workflow` for authoring `apm.yml`, scaffolding packages/marketplaces, compiling, packing, publishing, and auditing. - -## Files - -| File | Purpose | -|------|---------| -| `SKILL.md` | Skill instructions for agents | -| `references/sources.md` | Provenance chain — research sources that informed this skill | diff --git a/plugins/kyberforge/.apm/skills/apm-workflow/README.md b/plugins/kyberforge/.apm/skills/apm-workflow/README.md deleted file mode 100644 index 1328bed..0000000 --- a/plugins/kyberforge/.apm/skills/apm-workflow/README.md +++ /dev/null @@ -1,33 +0,0 @@ -# apm-workflow - -Authors, scaffolds, compiles, and audits apm packages and marketplaces. - -## What it does - -Covers the apm.yml lifecycle a session moves through repeatedly: configuring/scaffolding a package manifest, resolving/fetching its declared dependencies, building or registering a marketplace, compiling/packing/publishing a distributable, and validating integrity via apm audit. Dispatches on the resolved flow to one of five reference files; each carries that flow's traps and names a sibling file where one flow genuinely depends on another's detail. - -## Before you start - -Requires the `apm` binary and (for runtime-driven scripts) an agent runtime already installed — use `apm-install` first if either is missing. - -## Usage - -``` -/apm-workflow configure -/apm-workflow install -/apm-workflow marketplace -/apm-workflow compile -/apm-workflow audit -``` - -## Files - -| File | Purpose | -|------|---------| -| `SKILL.md` | Dispatch table and the three gotchas common to every branch (MCP secret indirection, the `experimental enable registries` precondition, the unchecked `type:` field) | -| `references/configure.md` | apm.yml schema, apm plugin init, dependency forms, MCP secrets, `includes:`, registries; `type:` and `experimental enable registries` traps | -| `references/install.md` | apm install, apm install [PACKAGE_REF], --update, --target agent-skills | -| `references/marketplace.md` | Building/registering a marketplace, `marketplace add` vs `package add`, package registration, versioning, Claude Code reserved-name/publish-confirm gotchas | -| `references/compile.md` | apm compile / pack / publish / run, claude plugin validate agents/ gotcha | -| `references/audit.md` | apm audit vs apm audit --ci (they check different things), apm marketplace check, CI wiring, frozen installs, claude plugin validate terminal check | -| `references/sources.md` | Provenance chain — research sources that informed this skill | diff --git a/plugins/kyberforge/.apm/skills/forge/README.md b/plugins/kyberforge/.apm/skills/forge/README.md deleted file mode 100644 index d76b745..0000000 --- a/plugins/kyberforge/.apm/skills/forge/README.md +++ /dev/null @@ -1,40 +0,0 @@ -# forge - -Guided entry point for building or improving something in any plugin of this repo when the target artifact type isn't decided yet. - -## What it does - -Grills the user's intent via `grill-with-docs` (inline, interactive) against this repo's `CONTEXT.md` and `docs/adr/`, classifies the target artifact type (skill, agent/subagent definition, plugin, or marketplace entry), announces the classification, then routes to the matching author skill — chaining more than one, in dependency order, if the intent spans multiple artifact types. - -Author-skill invocation defaults to a fork subagent (inherits the grilled-intent context) and falls back to inline when forking isn't possible or the routed flow needs live user interaction (clarifying questions, a HITL gate). After a `skill-author` or `agent-author` route finishes — each already closes out with its own inline audit — forge spins up a separate clean-context subagent to independently re-run the matching audit skill (`skill-audit` / `agent-audit`) as a distinct check on the finished artifact, not a duplicate of the inline one. If that clean audit turns up any unresolved finding, forge loops — re-invoke the author skill to resolve it, re-run the clean audit — until the clean audit comes back with nothing unresolved. `apm-workflow` routes (plugin, marketplace entry) get no recheck: they have no audit counterpart, and no automatic terminal check either — `apm audit` is a separate `apm-workflow` action, not a closing step of the configure or marketplace flow — so forge verifies those routes by reading the written manifest back against the grilled intent. - -## Before you start - -Have a rough idea of what you want to build or change. forge doesn't require you to already know whether it's a skill, agent, plugin, or marketplace entry — that classification is its job. - -## Usage - -``` -/forge -``` - -Skip forge and call the target skill directly (`/skill-author`, `/agent-author`, `/apm-workflow`) when you already know the artifact type. - -## Files - -| File | Loaded when | -|------|-------------| -| `SKILL.md` | Always — Gotchas, the grill step, the classification dispatch table, and the gates common to every route | -| `references/author-routes.md` | The intent classifies as a skill or an agent/subagent definition — fork-vs-inline judgment and the two-tier verification loop | -| `references/apm-routes.md` | The intent classifies as a plugin or a marketplace entry — always-inline invocation, why these routes get no clean-context recheck, and the manual read-back that stands in for one | -| `references/version-bump.md` | A finished route left the owning package's version unbumped — walk-up rule and the clean-context bump brief | -| `references/sources.md` | Never loaded at runtime — provenance chain for the research sources that informed this skill | - -## Routes to - -| Artifact type | Skill | -|---|---| -| Skill | `skill-author` | -| Agent / subagent definition | `agent-author` | -| Plugin | `apm-workflow` (configure) | -| Marketplace entry | `apm-workflow` (marketplace) | diff --git a/plugins/kyberforge/.apm/skills/forge/SKILL.md b/plugins/kyberforge/.apm/skills/forge/SKILL.md index f63242a..a88377a 100644 --- a/plugins/kyberforge/.apm/skills/forge/SKILL.md +++ b/plugins/kyberforge/.apm/skills/forge/SKILL.md @@ -8,7 +8,7 @@ description: > already named — invoke `skill-author`, `agent-author` or `apm-workflow` directly. metadata: - version: "1.0.0" + version: "1.0.1" category: factory source_keys: - claude-code-subagents-docs diff --git a/plugins/kyberforge/.apm/skills/forge/references/sources.md b/plugins/kyberforge/.apm/skills/forge/references/sources.md index 4f065b3..f64666f 100644 --- a/plugins/kyberforge/.apm/skills/forge/references/sources.md +++ b/plugins/kyberforge/.apm/skills/forge/references/sources.md @@ -28,7 +28,7 @@ - **URL:** https://agentskills.io/specification.md - **Research doc:** plugins/kyberforge/docs/research/docs/agentskillsio/sources.md -- **Description:** Complete SKILL.md format specification — confirms `assets/`, `references/`, and `scripts/` are warranted only by the bulk/reusability of supporting content (large reference material, executable code, templates), not by a skill's category, and forge's per-route procedures are that kind of supporting content — so the spec permits the `references/` split here but does not require it. The warrant is a house decision: ADR-0020's rule that dispatch is mandatory at two or more mutually exclusive flows, which forge's four-row table is. `references/sources.md` likewise exists for this repo's own provenance-chain convention (see `CONTEXT.md`), not because the spec requires it. +- **Description:** Complete SKILL.md format specification — confirms `assets/`, `references/`, and `scripts/` are warranted only by the bulk/reusability of supporting content (large reference material, executable code, templates), not by a skill's category, and forge's per-route procedures are that kind of supporting content — so the spec permits the `references/` split here but does not require it. The warrant is a house decision: dispatch is mandatory at two or more mutually exclusive flows, which forge's four-row table is. `references/sources.md` likewise exists for this repo's own provenance-chain convention (see `CONTEXT.md`), not because the spec requires it. - **Contributing files:** SKILL.md - **Status:** `extracted` diff --git a/plugins/kyberforge/.apm/skills/skill-audit/README.md b/plugins/kyberforge/.apm/skills/skill-audit/README.md deleted file mode 100644 index 468be43..0000000 --- a/plugins/kyberforge/.apm/skills/skill-audit/README.md +++ /dev/null @@ -1,53 +0,0 @@ -# skill-audit - -Audit a skill directory against the agentskills.io specification and the house context-budget contract (ADR-0020). Runs structural validation then a qualitative review across description quality, body discipline, patterns, formatting, file structure, scripts, and internal consistency, plus a provenance chain check. - -## What it does - -1. Runs `scripts/validate.sh` and `scripts/validate-provenance.sh` for structural and provenance checks, plus `scripts/vale-wrap.sh` — a Vale prefilter that deterministically flags non-imperative description openers, composition and architecture notes, vague wording, padding phrases, and "There is/are" sentence openers -2. Reads all files in the skill directory -3. Applies qualitative checks across five dimension groups — always loading `references/finding-criteria.md`, then one rubric from `references/` per group the criteria put in play -4. Outputs a compact findings report — findings only, grouped by dimension, each with Why and Fix — and a result block with handoff to `skill-author` - -`validate.sh` enforces two independent length families that must not be conflated: the agentskills.io spec conformance ceilings (500 lines, 2,770 words, both counting the whole file) and the ADR-0020 context budget (250/400 description characters, 600/900 body-only words). - -Alongside those it runs shape checks that are not length measurements at all. Three are FAILs: every routing target named in the description — in the compressed `Not -> ` arrow **and** in the prose form — must resolve to a real skill or agent; every `references/.md` the body names must exist on disk; and `metadata.version` must be present and three-part semver (ADR-0022). That last one is FAIL rather than SUGGESTION because the `skill-frontmatter` pre-commit hook rejects the file without it — an audit grading it lower would report ready-to-ship on a file the commit gate refuses. Three are SUGGESTIONs: a missing boundary clause, a Gotchas section over five entries, and a Gotchas section over 25% of the body. The resolution universe for boundary targets is derived by walking up from the audited `SKILL.md` — the authoring root above it, its own apm package, and that package's declared `apm.yml` dependencies — so a fresh clone and a machine that has run `apm install` return the same verdict. When no universe can be determined the check prints `INFO ... DID NOT RUN` and does not silently pass. - -## Usage - -``` -/skill-audit -``` - -Provide the path to the skill directory to audit when invoking. - -## Files - -| File | Purpose | -|------|---------| -| `SKILL.md` | Skill instructions for agents | -| `scripts/validate.sh` | Structural validator — checks name format, name matches directory, description presence and length, `metadata.version` presence and semver shape (ADR-0022), body-only word count, line and whole-file word ceilings, boundary-clause presence, boundary-target resolution, `references/` pointer existence, Gotchas entry count and body share, placeholder detection, script executable bit, and interactive-prompt detection | -| `scripts/validate-provenance.sh` | Provenance validator — checks sources.md completeness, source_keys/slug consistency, Contributing files existence, bidirectional linkage, Research doc: fields, upstream research doc alignment, and (check 9, INFO only) whether a slug's `Description` or `Contributing files` text has changed since a base ref — `--base-ref=` or `VALIDATE_PROVENANCE_BASE_REF`, defaulting to the merge base with `origin/main` | -| `scripts/vale-wrap.sh` | Vale prefilter wrapper — runs the bundled `Kyberforge` Vale styles against SKILL.md and reports alerts as deterministic FAILs ahead of Step 3's qualitative review | -| `assets/vale/.vale.ini` | Vale configuration — points Vale at the bundled `Kyberforge` style path, self-located relative to `vale-wrap.sh` | -| `assets/vale/styles/Kyberforge/CompositionNote.yml` | Vale rule — flags composition and architecture notes in a description (e.g. "cross-cutting", "entry point", "rather than duplicating") | -| `assets/vale/styles/Kyberforge/DescriptionOpener.yml` | Vale rule — flags non-imperative "This..." description openers | -| `assets/vale/styles/Kyberforge/PaddingPhrase.yml` | Vale rule — flags generic "see references/" padding phrasing in conditional references | -| `assets/vale/styles/Kyberforge/SentenceOpenerThereIs.yml` | Vale rule — flags body sentences starting with "There is"/"There are" | -| `assets/vale/styles/Kyberforge/VagueWording.yml` | Vale rule — flags known filler wording (e.g. "helps with", "utilize") | -| `references/finding-criteria.md` | Every dimension's FAIL and SUGGESTION criteria — the one Step 3 file loaded on every run; it decides which rubrics below are worth loading | -| `references/description-quality.md` | Rubric for the description dimension — why the description is the expensive part, the hand-invoked (`disable-model-invocation`) contract, the three-part shape, when an indirect trigger is warranted, near-miss exclusions, and a before/after pair | -| `references/body-discipline.md` | Rubric for the body-discipline dimension — the core test, the 600/900 body-only budget against the 2,770-word whole-file backstop, the mandatory-dispatch rule, and the Gotchas constraints | -| `references/patterns.md` | Rubric for the patterns dimension — which instruction construct fits which job, and how each is correctly formed | -| `references/file-structure.md` | Rubric for the file-structure and internal-consistency dimensions — permitted directories, cross-plugin path rules and their two structural exemptions, README drift | -| `references/formatting-and-scripts.md` | Rubric for the formatting and scripts dimensions — heading and fencing conventions, and the agentic-use criteria for bundled scripts | -| `references/validation-scripts.md` | Step 1 troubleshooting — the manual structural fallback when `validate.sh` cannot run, and the script exit codes that are easy to misread (loaded on a script failure, and on any exit-0 run that printed something — `validate-provenance.sh`'s check 9 is INFO-only, so its findings arrive that way) | -| `references/sources.md` | Provenance record — agentskills.io sources that informed this skill and which files each contributed to | -| `tests/validate.bats` | (source-only) Bats test suite for validate.sh | -| `tests/validate-provenance.bats` | (source-only) Bats test suite for validate-provenance.sh | -| `tests/README.md` | (source-only) Setup instructions for bats-support and bats-assert test dependencies | - -Rows marked **(source-only)** exist in the authoring source (`.apm/skills/skill-audit/`) but are -not present in an installed plugin: `scripts/sync-plugin-content.sh` strips -`//tests` when it generates the flat mirror, because these are dev-time fixtures no -plugin host needs to discover (ADR-0017). Run them from a repo checkout, not from an install. diff --git a/plugins/kyberforge/.apm/skills/skill-audit/SKILL.md b/plugins/kyberforge/.apm/skills/skill-audit/SKILL.md index 8f093d9..c6f0103 100644 --- a/plugins/kyberforge/.apm/skills/skill-audit/SKILL.md +++ b/plugins/kyberforge/.apm/skills/skill-audit/SKILL.md @@ -7,7 +7,7 @@ description: > skill-author. allowed-tools: Bash Read metadata: - version: "1.0.1" + version: "1.0.2" category: factory source_keys: - agentskills-home @@ -50,7 +50,7 @@ Read `references/validation-scripts.md` when any of the three cannot run or exit ## Step 2 — Read the whole skill -Read `SKILL.md`, `README.md`, and every text file under `scripts/`, `references/`, `assets/` and `tests/`. Skip binaries only — internal-consistency findings need the full picture. +Read `SKILL.md` and every text file under `scripts/`, `references/`, `assets/` and `tests/`. Skip binaries only — internal-consistency findings need the full picture. ## Step 3 — Qualitative audit @@ -64,7 +64,7 @@ Read `references/finding-criteria.md` first — every dimension's FAIL and SUGGE | file-structure, internal-consistency | `references/file-structure.md` | | formatting, scripts | `references/formatting-and-scripts.md` | -Each rubric is self-contained and grounded in the agentskills.io specification plus the house context budget (ADR-0020). Cite file and line number for every finding. +Each rubric is self-contained and grounded in the agentskills.io specification plus the house context budget. Cite file and line number for every finding. ## Step 4 — Report diff --git a/plugins/kyberforge/.apm/skills/skill-audit/references/body-discipline.md b/plugins/kyberforge/.apm/skills/skill-audit/references/body-discipline.md index 31f28c6..b071ca2 100644 --- a/plugins/kyberforge/.apm/skills/skill-audit/references/body-discipline.md +++ b/plugins/kyberforge/.apm/skills/skill-audit/references/body-discipline.md @@ -7,7 +7,7 @@ source_keys: # Body Discipline Reference Upstream source: agentskills.io — skill-authoring, best-practices. -House contract: ADR-0020, the context budget. +House contract: the context budget. ## The core test @@ -31,7 +31,7 @@ Include content the agent lacks: Move to `references/`, behind an explicit "If X, read `references/.md`" trigger — the literal conditional form, never a generic pointer. Write the real filename in the skill under audit; the angle brackets are a placeholder here, and a literal `references/file.md` in a body is an ERROR -from the ADR-0020 gate because no such file exists on disk. +from the gate because no such file exists on disk. **A dispatch table satisfies this requirement on its own.** A table row already pairs a condition with a target, which is exactly what the literal form encodes; restating each row underneath as a @@ -60,7 +60,7 @@ Do not conflate these, and do not report them as one finding. | Gate | SUGGESTION | FAIL | Counts | |---|---|---|---| -| Body budget (house, ADR-0020) | 600 words | 900 words | the **body only** — everything after the frontmatter's closing `---` | +| Body budget (house) | 600 words | 900 words | the **body only** — everything after the frontmatter's closing `---` | | Spec conformance (agentskills.io) | — | 2,770 words / 500 lines | the **whole file**, frontmatter included | The 2,770-word ceiling is a token-conformance backstop calibrated to the densest prose in the @@ -134,7 +134,7 @@ Constraints: Worked negative example — **`git-commits` v0.1.2 at commit `5e23250`, a fixed pre-retrofit snapshot, not the current file.** The live skill is v0.1.3 and matches none of the citations below; -they are quoted as they stood before the ADR-0020 retrofit, and are not to be refreshed against +they are quoted as they stood in that snapshot, and are not to be refreshed against `HEAD`. The snapshot is reachable only from a checkout of the authoring repo — an installed plugin cache holds no git history and no such path — so read the citations below as quoted rather than going to look for the file. From a checkout: diff --git a/plugins/kyberforge/.apm/skills/skill-audit/references/description-quality.md b/plugins/kyberforge/.apm/skills/skill-audit/references/description-quality.md index ef027f8..08b5a7c 100644 --- a/plugins/kyberforge/.apm/skills/skill-audit/references/description-quality.md +++ b/plugins/kyberforge/.apm/skills/skill-audit/references/description-quality.md @@ -7,7 +7,7 @@ source_keys: # Description Quality Reference Upstream source: agentskills.io — optimizing-descriptions, specification. -House contract: ADR-0020, the context budget. The house contract is narrower than the spec +House contract: the context budget. The house contract is narrower than the spec rather than a reinterpretation of it: where both speak, both must be satisfied. ## Why the description is the expensive part diff --git a/plugins/kyberforge/.apm/skills/skill-audit/references/file-structure.md b/plugins/kyberforge/.apm/skills/skill-audit/references/file-structure.md index 33c3531..aaaeb84 100644 --- a/plugins/kyberforge/.apm/skills/skill-audit/references/file-structure.md +++ b/plugins/kyberforge/.apm/skills/skill-audit/references/file-structure.md @@ -19,7 +19,6 @@ knows to look at. Flag any other directory as a FAIL. `test_*.sh`) there are a FAIL — they belong in `tests/`. - No non-spec files at the skill root: no `META.md`, no stray config outside the four directories. - An optional directory that exists must hold real content, not an unfilled placeholder README. -- `README.md` is present and describes the skill and its files accurately. ## Cross-plugin path references @@ -41,7 +40,7 @@ Resolve before flagging, twice over: **Referring to another skill's file.** There is one sanctioned spelling, and it is possessive: `skill-audit's references/validation-scripts.md`. Write the skill by name and let the reader resolve it — do not spell the repo path. The full path is the thing this section forbids, and -`references/validation-scripts.md` on its own is a hard ERROR from the ADR-0020 gate, which +`references/validation-scripts.md` on its own is a hard ERROR from the gate, which requires an unqualified `references/` pointer to exist in the skill's OWN directory. The possessive form is the only spelling both rules accept; the gate recognises it and skips the on-disk check. Flag any other spelling of a cross-skill reference. @@ -59,17 +58,12 @@ Two directories are exempt, and the exemptions are structural rather than discre ## Internal consistency -The skill has to agree with itself. Three checks: +The skill has to agree with itself. Two checks: - `SKILL.md`'s steps match what the scripts actually do — the arguments, the exit codes, and the output shape it tells the agent to expect. -- `README.md`'s file table lists every file that exists, with no missing rows and no stale rows for - files since deleted. -- Placeholder READMEs inside `scripts/`, `references/` and `assets/` say the same thing about each +- Placeholder READMEs inside `scripts/`, `tests/` and `assets/` say the same thing about each directory that `SKILL.md` does. -A stale README row is the most common finding here and the easiest to miss from inside an -authoring pass, because the author knows what was intended and reads it into the gap. - The FAIL and SUGGESTION criteria for this dimension live in `references/finding-criteria.md`, which Step 3 loads on every run. diff --git a/plugins/kyberforge/.apm/skills/skill-audit/references/finding-criteria.md b/plugins/kyberforge/.apm/skills/skill-audit/references/finding-criteria.md index 05eb85d..955fd1f 100644 --- a/plugins/kyberforge/.apm/skills/skill-audit/references/finding-criteria.md +++ b/plugins/kyberforge/.apm/skills/skill-audit/references/finding-criteria.md @@ -111,13 +111,11 @@ Flag as FAIL if: - A path that resolves outside the skill directory appears outside the two exempt locations, in prose rather than in a fenced example - `tests/` exists but `tests/README.md` is missing or does not document its repo-level dependency -- `README.md` is absent, or its file table has a missing or stale row - `SKILL.md` describes a script invocation the script does not accept Flag as SUGGESTION if: - An optional directory exists but holds only a placeholder README -- `README.md` is accurate but describes a file's purpose more thinly than `SKILL.md` does ## formatting and scripts — `references/formatting-and-scripts.md` diff --git a/plugins/kyberforge/.apm/skills/skill-audit/references/patterns.md b/plugins/kyberforge/.apm/skills/skill-audit/references/patterns.md index 80cffa1..bf8337d 100644 --- a/plugins/kyberforge/.apm/skills/skill-audit/references/patterns.md +++ b/plugins/kyberforge/.apm/skills/skill-audit/references/patterns.md @@ -40,7 +40,7 @@ If the API returns a non-200 status, read `references/api-errors.md`. ``` That block is fenced because the filename in it is illustrative — an unfenced `references/` pointer -in a `SKILL.md` body must resolve on disk or the ADR-0020 gate reports a hard ERROR. The generic +in a `SKILL.md` body must resolve on disk or the gate reports a hard ERROR. The generic form — pointing at the directory and hoping — defeats progressive disclosure, because the agent either loads everything or loads nothing. `Kyberforge.PaddingPhrase` catches the common generic phrasing deterministically; other malformed diff --git a/plugins/kyberforge/.apm/skills/skill-audit/references/validation-scripts.md b/plugins/kyberforge/.apm/skills/skill-audit/references/validation-scripts.md index 24b138f..f75202d 100644 --- a/plugins/kyberforge/.apm/skills/skill-audit/references/validation-scripts.md +++ b/plugins/kyberforge/.apm/skills/skill-audit/references/validation-scripts.md @@ -21,7 +21,7 @@ have checked, and the Step 4 coverage line then names a dimension nothing actual ## Manual structural fallback `validate.sh` needs `python3` **and** PyYAML, and refuses to start without either — the description -value has to be measured after YAML folding is resolved, so skipping the ADR-0020 gates would be a +value has to be measured after YAML folding is resolved, so skipping these gates would be a vacuous pass rather than a partial one. The two are checked separately, so the message already names the right one — report it verbatim rather than diagnosing further: @@ -40,14 +40,14 @@ by hand and file the results under `### Structure` exactly as the script's outpu session, so a skill without one can never be routed to. - **Description length**, measured on the folded YAML value with newlines collapsed to single spaces — not on the raw block scalar, which counts indentation. 250 characters SUGGESTION, 400 - FAIL (ADR-0020), 1,024 FAIL (agentskills.io spec). + FAIL (house), 1,024 FAIL (agentskills.io spec). - **Body length**, counting everything after the frontmatter's closing `---`. 600 words - SUGGESTION, 900 FAIL (ADR-0020). + SUGGESTION, 900 FAIL (house). - **Whole-file ceilings**, counting the file including frontmatter: 500 lines FAIL, 2,770 words FAIL (agentskills.io spec). These are a different measurement from the two above — report them as separate findings, never merged. - **A boundary clause is present** — either the prose form (`do not` / `instead` / `rather than` / - `not for`) or ADR-0020's compressed `Not -> ` arrow. **SUGGESTION**, not FAIL: + `not for`) or the compressed `Not -> ` arrow. **SUGGESTION**, not FAIL: the absence is deterministic, but whether this skill warrants one is the auditor's call. - **Boundary targets resolve** — **FAIL** on a name that resolves to nothing. See the section below; resolving these by hand is the one item on this list with a procedure of its own. diff --git a/plugins/kyberforge/.apm/skills/skill-author/README.md b/plugins/kyberforge/.apm/skills/skill-author/README.md deleted file mode 100644 index 53e49d7..0000000 --- a/plugins/kyberforge/.apm/skills/skill-author/README.md +++ /dev/null @@ -1,74 +0,0 @@ -# skill-author - -Author and refine skills conforming to the [agentskills.io](https://agentskills.io) specification — create new skills from scratch or apply improvement signals to existing ones. - -## What it does - -Routes to one of two flows based on context: if no skill directory exists at the target path, it scaffolds the directory from annotated templates, fills in `SKILL.md` and supporting files, and validates the result. If an existing skill directory and improvement signals are both present, it groups those signals by root cause and applies targeted edits, then re-validates. In both flows, bumps the skill's `metadata.version` — minor for create, patch for improve — which every skill carries (ADR-0022). - -`SKILL.md` itself carries only the dispatch table, the invocation-axis decision, the contract gates and the shared close; each flow lives in its own self-contained reference file, per ADR-0020. - -## The contract it teaches - -Authored skills are held to the ADR-0020 context budget. A description carries a trigger clause, at most one capability clause, and a boundary clause of the form `Not -> ` whose target must resolve to a real skill or agent — 250 characters target, 400 hard ceiling. A body carries the decision procedure only — 600 words target, 900 hard ceiling, counting the body alone, which is a separate measurement from the 2,770-word / 500-line whole-file spec backstop. Skills with two or more mutually exclusive flows must dispatch. `references/contract.md` holds the full rules; `assets/templates/SKILL.md` encodes them as a fill-in skeleton. - -Before a description is written, the skill asks whether the target is model-invoked or hand-invoked. A hand-invoked skill sets `disable-model-invocation: true` and carries one plain human-facing sentence with no trigger list. - -## Before you start - -- Run `/grill-me` to resolve design decisions before creating a new skill -- Collect domain research, examples, and constraints -- Know the skill name (kebab-case) and destination path - -## Placement - -`scripts/new-skill.sh` resolves the mode automatically by walking up from the given path — see `references/create.md` Step 1 for the full algorithm. - -| Mode | Path | Chosen when | -|------|------|-------------| -| Standalone | `//` | No `apm.yml` with a top-level `type:` field is found walking up from ``, before hitting `.git` or the filesystem root | -| Package (APM) | `/.apm/skills//` | A type-bearing `apm.yml` is found at or above `` — `` just needs to be somewhere inside the package | - -If the destination resolves inside an APM package, read `references/deployment-modes.md` — self-containment rules apply to `apm compile` output the same way they applied to plugin cache isolation. - -## Usage - -``` -/skill-author -``` - -## Files - -| File | Purpose | -|------|---------| -| `README.md` | Human-readable overview of the skill and its files | -| `SKILL.md` | Skill instructions for agents | -| `scripts/new-skill.sh` | Walks up from the given path to resolve package vs standalone mode, then copies annotated templates to the resolved destination | -| `references/create.md` | The create flow end to end — prerequisites, package-intent gate, scaffold, frontmatter, scripts, references, sources (loaded on demand) | -| `references/improve.md` | The improve flow end to end — signal verification, root-cause grouping, announcement, edits (loaded on demand) | -| `references/contract.md` | The ADR-0020 description and body contract, the Gotchas constraint, the two size gates, body patterns, and org-policy embedding (loaded on demand) | -| `references/retrofit.md` | Bringing a pre-ADR-0020 skill into contract — ordered cut procedure, the mutually-exclusive-flows test, reference-file conventions, the collateral checklist, and a worked description retrofit (loaded from the improve flow when a budget is exceeded) | -| `references/deployment-modes.md` | APM package vs standalone differences and self-containment/cache-isolation rules (loaded on demand) | -| `references/scripts.md` | Package runners, inline dependency patterns, and full script contract (loaded on demand) | -| `references/sources.md` | Upstream research sources and which skill files each contributed to | -| `assets/templates/SKILL.md` | Annotated SKILL.md template — emits an ADR-0020-compliant description and body skeleton | -| `assets/templates/README.md` | Annotated README template for the new skill | -| `assets/templates/scripts/README.md` | Placeholder for bundled scripts | -| `assets/templates/references/README.md` | Placeholder for reference docs | -| `assets/templates/references/sources.md` | Sources provenance template for new skills | -| `assets/templates/assets/README.md` | Placeholder for static assets | -| `assets/templates/tests/README.md` | Placeholder for test files | -| `tests/new-skill.bats` | (source-only) Bats test suite for `scripts/new-skill.sh` | -| `tests/README.md` | (source-only) Setup instructions for bats-support and bats-assert test dependencies | - -Rows marked **(source-only)** exist in the authoring source (`.apm/skills/skill-author/`) but are -not present in an installed plugin: `scripts/sync-plugin-content.sh` strips -`//tests` when it generates the flat mirror, because these are dev-time fixtures no -plugin host needs to discover (ADR-0017). Run them from a repo checkout, not from an install. The -`assets/templates/tests/README.md` row above is **not** source-only — the exclusion is depth-scoped -to `//tests`, so the scaffolding template tree ships intact, which -`scripts/new-skill.sh` depends on at runtime. - -## Spec reference - -[agentskills.io specification](https://agentskills.io/specification.md) diff --git a/plugins/kyberforge/.apm/skills/skill-author/SKILL.md b/plugins/kyberforge/.apm/skills/skill-author/SKILL.md index 80ecb37..ccde99c 100644 --- a/plugins/kyberforge/.apm/skills/skill-author/SKILL.md +++ b/plugins/kyberforge/.apm/skills/skill-author/SKILL.md @@ -6,7 +6,7 @@ description: > Not read-only review -> `skill-audit`. Not agent files -> `agent-author`. allowed-tools: Bash Read Write Edit metadata: - version: "1.0.1" + version: "1.0.2" category: factory source_keys: - agentskills-home diff --git a/plugins/kyberforge/.apm/skills/skill-author/assets/templates/README.md b/plugins/kyberforge/.apm/skills/skill-author/assets/templates/README.md deleted file mode 100644 index 6339f0b..0000000 --- a/plugins/kyberforge/.apm/skills/skill-author/assets/templates/README.md +++ /dev/null @@ -1,51 +0,0 @@ -# SKILL_NAME - - - -## What it does - - - -## Before you start - - - -## Usage - -``` -/SKILL_NAME -``` - - - - - -## Files - - - -| File | Purpose | -|------|---------| -| `SKILL.md` | Skill instructions for agents | -| `scripts/your-script.sh` | FILL IN: what this script does | -| `references/your-doc.md` | FILL IN: what this reference covers | -| `assets/your-asset.json` | FILL IN: what this asset is | -| `tests/your-test.bats` | FILL IN: what this test covers | - - diff --git a/plugins/kyberforge/.apm/skills/skill-author/assets/templates/references/README.md b/plugins/kyberforge/.apm/skills/skill-author/assets/templates/references/README.md deleted file mode 100644 index 25a8d59..0000000 --- a/plugins/kyberforge/.apm/skills/skill-author/assets/templates/references/README.md +++ /dev/null @@ -1,39 +0,0 @@ -# references/ - -Additional documentation agents load on demand. Files here extend SKILL.md -without bloating its core context. - -## When to add a reference file - -The SKILL.md body carries the decision procedure only. Everything else lives -here: lookup tables, spec restatements, output schemas, templates, example -blocks, rationale prose, and anything only one branch reaches. - -Two triggers make a reference file mandatory rather than optional: - -- The body is over its 600-word target (900 is a hard failure), counting the - body only — everything after the frontmatter's closing `---`. -- The skill has two or more mutually exclusive flows. The body then keeps only - a dispatch table plus the gates common to every branch, and each flow gets - its own self-contained file here (e.g. `create.md`, `improve.md`). - -## How to reference from SKILL.md - -Load conditionally — tell the agent exactly when to read each file: - -```markdown -If the API returns a non-200 status, read `references/api-errors.md`. -``` - -Avoid generic "see references/ for details" — the agent loads context on -demand, so give it a precise trigger condition. - -## File conventions - -- One topic per file — focused files mean less unnecessary context loaded -- Kebab-case filenames (e.g. `api-errors.md`, `output-formats.md`) -- Keep files under 200 lines where possible - -## If no reference files are needed - -Delete this README and the `references/` directory entirely. diff --git a/plugins/kyberforge/.apm/skills/skill-author/references/contract.md b/plugins/kyberforge/.apm/skills/skill-author/references/contract.md index e6795bf..ec1d4c5 100644 --- a/plugins/kyberforge/.apm/skills/skill-author/references/contract.md +++ b/plugins/kyberforge/.apm/skills/skill-author/references/contract.md @@ -7,7 +7,7 @@ source_keys: # The description and body contract -House contract, set by ADR-0020. Every rule here is enforced by `/skill-audit` — +House contract. Every rule here is enforced by `/skill-audit` — `scripts/validate.sh` for the counts and the boundary targets, the bundled Vale styles for the prose patterns, and its reference files for the judgment calls. diff --git a/plugins/kyberforge/.apm/skills/skill-author/references/create.md b/plugins/kyberforge/.apm/skills/skill-author/references/create.md index 984a45e..474510e 100644 --- a/plugins/kyberforge/.apm/skills/skill-author/references/create.md +++ b/plugins/kyberforge/.apm/skills/skill-author/references/create.md @@ -84,7 +84,7 @@ already covers the new skill. Use Read/Edit directly on `apm.yml`; this is not p ## Step 3 — Fill in SKILL.md Open the new skill's `SKILL.md` (the path Step 1 printed) and replace every `FILL IN:` -placeholder. The scaffold template carries the ADR-0020 body skeleton and the two frontmatter +placeholder. The scaffold template carries the body skeleton and the two frontmatter fields that cannot be left as placeholders — `name`, substituted by the script, and `metadata.version`, seeded live at `"0.1.0"` — so fill the template in rather than restructuring it. diff --git a/plugins/kyberforge/.apm/skills/skill-author/references/improve.md b/plugins/kyberforge/.apm/skills/skill-author/references/improve.md index feda975..4df84d2 100644 --- a/plugins/kyberforge/.apm/skills/skill-author/references/improve.md +++ b/plugins/kyberforge/.apm/skills/skill-author/references/improve.md @@ -71,23 +71,16 @@ outperforms an exhaustive one. writing a rule in all caps (ALWAYS/NEVER), reframe it: explain why the behavior matters so the agent can apply judgment in edge cases. -**Retrofit before extending.** Any edit to a skill that predates ADR-0020 has to bring it into the -contract first — the gates are hot and carry no baseline file, so a one-line fix to a +**Retrofit before extending.** Any edit to a skill that does not meet the contract has to bring it +into compliance first — the gates are hot and carry no baseline file, so a one-line fix to a non-compliant skill cannot be committed until the description and body meet `references/contract.md`. Treat that retrofit as part of the same change, not a follow-up. -If the skill's description exceeds 250 characters, or its body-only word count exceeds 600, read -`references/retrofit.md` before editing. It carries the ordered cut procedure, the -mutually-exclusive-flows test, the reference-file conventions this flow needs, the collateral -checklist for `README.md` and `references/sources.md`, and a worked description retrofit. Do not -improvise the cuts — four dry runs invented six to ten different answers to the same questions. - If a signal points to a script or reference file, edit that file directly rather than adding a workaround in SKILL.md. **A skill carrying no `metadata.version` is seeded at `"1.0.0"`, not bumped** — `SKILL.md` Step 4's patch bump presumes a version to bump, and ADR-0022 reserves `"0.1.0"` for a newly created skill. -`references/retrofit.md` carries the reasoning. **Check for regressions before handing back.** `SKILL.md` Step 4 tells you to resolve every FAIL, which says nothing about a check that passed *before* these edits and no longer does. Compare the diff --git a/plugins/kyberforge/.apm/skills/skill-author/references/retrofit.md b/plugins/kyberforge/.apm/skills/skill-author/references/retrofit.md deleted file mode 100644 index 0755773..0000000 --- a/plugins/kyberforge/.apm/skills/skill-author/references/retrofit.md +++ /dev/null @@ -1,197 +0,0 @@ ---- -source_keys: - - agentskills-best-practices - - agentskills-optimizing-descriptions ---- - -# Retrofitting a skill to the ADR-0020 contract - -Read this when `references/improve.md` Step 4 sends you here: the skill you are editing is over -the description or body budget and has to come into contract before any other change can be -committed. The gates are hot and carry no baseline file, so a one-line fix to a non-compliant -skill is blocked until this is done. - -Measure first. Do not guess which gate fired: run `/skill-audit` on the directory and read its -`### Structure` dimension, which reports the description characters and the **body-only** word -count separately from the whole-file spec backstop. Retrofit against the number that actually -fired — a skill can sit a thousand words inside the whole-file backstop while failing the body -budget. - -**Validate in place.** Audit the skill's real directory inside its package. Never audit a copy in a -scratch directory, and never move a skill out to work on it: the boundary-target universe is built -by walking up *from the file being checked*, so a copy with no authoring root above it resolves -against nothing and the check declines rather than running — - -```text -INFO boundary-target resolution DID NOT RUN — no skill universe could be determined for -this path ... Unchecked target(s): totally-fake-target -``` - -The run still exits 0, so that line reads as a pass and is not one. Treat `DID NOT RUN` as **not -checked**, always. A retrofit signed off on a scratch copy carries an unverified boundary target -into the corpus, which is precisely the failure this gate exists to catch. - -## Cut in this order - -Work the list top down and stop as soon as the gate clears. The order is by ratio of tokens -removed to behaviour lost — inverting it is how a retrofit ends up deleting the one instruction -the skill existed to carry. - -1. **Gotchas that paraphrase a step in the body below.** Zero information, and already a FAIL on - its own. Delete the Gotcha, keep the step. -2. **Spec restatements** — text that repeats a published specification, a tool's `--help`, or a - ceiling the validator already enforces. The agent gets this right without it. Delete, or move - the table to `references/` if a flow genuinely needs to look it up. -3. **Capability enumeration** — in a description, the feature list after the trigger clause; in a - body, the paragraph that recites what the skill can do. One capability clause survives in the - description; the rest belongs in `README.md`. -4. **Per-flow prose** — anything only one branch of the procedure ever reaches. This is the - largest single win in most bodies, and it is a *move*, not a delete: each flow gets its own - self-contained `references/` file, wired from a dispatch table. - -If the body is still over after all four, the skill is doing two jobs. Split it, and say so -rather than compressing prose until it stops being readable. - -## What "mutually exclusive flows" means - -Two or more flows that a single invocation cannot both take. The three-way test, copied verbatim -from the body-discipline rubric `/skill-audit` judges against — nothing to load, it is quoted in -full here: - -> separate subcommands, separate input types, separate lifecycle stages - -Any one of the three is enough. Two flows that differ only in a parameter value are one flow. -At two or more mutually exclusive flows a dispatch table is **mandatory** regardless of word -count, because every invocation otherwise pays for every branch it did not take. - -## Reference-file conventions - -The create flow owns these rules, and this flow is forbidden from reading `references/create.md`, -so what a retrofit needs is restated here: - -- **One topic per file.** A file mixing two concerns gets loaded for one of them and spends the - caller's context on the other. -- **Kebab-case filenames**, named after the topic rather than the flow that reads it — - `body-discipline.md`, not `step-3.md`. -- **Wire every file with the literal conditional form** ``If , read - `references/.md` ``. A generic pointer ("see `references/` for details") is a Vale error. -- **Two hops from `SKILL.md`, never three.** A flow file may route on to a shared contract file; - a file reachable only through two intermediates is rarely loaded when it is needed. -- **`source_keys` frontmatter.** If the content you are moving drew on a research source, the new - file needs top-level `source_keys:` frontmatter listing those slugs, and every slug must already - exist as an `## ` heading in `references/sources.md`. Moving sourced content out of - `SKILL.md` without carrying its slugs across breaks the provenance chain, and `/skill-audit` - reports the new file as an INFO with no `source_keys`. - -## Collateral is mandatory, not optional - -Moving content out of a `SKILL.md` leaves three files describing a structure that no longer -exists. `/skill-audit`'s provenance check exits clean on all three of these, so nothing catches -them for you. After every retrofit that adds, removes or renames a file: - -- [ ] **`README.md` file table** — a row for every new `references/` file, and no row left for a - file that is gone. Say what triggers the load, not just what the file contains. -- [ ] **`references/README.md`**, where the skill has one — same update, same reason. -- [ ] **`references/sources.md` → `Contributing files`** — add the new file to every slug whose - content moved into it, and remove any file the retrofit deleted. This is the one that gets - missed: `sources.md` keeps citing sections of `SKILL.md` that no longer exist, the - provenance check still exits 0, and the stale claim survives review. -- [ ] **Reachability of every relocated gate.** For each Gotcha or gate the retrofit moved out of - the body, list the flows that need it and confirm each one reaches the surviving copy. A gate - that lands in a single flow file is invisible to every other branch, and no gate detects - that: `/skill-audit` reads whichever file it was handed, and the word counts improve either - way. Where more than one flow needs it, the copy belongs in the body's common-gates section, - not in a flow file. Grep the skill for the gate's key term and check every branch that hits - zero. -- [ ] Re-run `/skill-audit` and confirm its `### Provenance` dimension does not report the new - file as missing `source_keys`. - -## Compression must not add authority the source text didn't have - -This one is **not** part of the checklist above, and deliberately so: it fires on a wording change -with no file change at all, so a retrofit that adds and removes nothing still owes it. - -The `sources.md` bullet above is about an entry going *stale* — Contributing files left uncited -after content moves. This is a distinct failure: a compression or rewrite pass that upgrades an -honest hedge in a Description into an unsupported confident claim, without the underlying source -having changed at all — "no forge-specific content drawn directly from it beyond that" quietly -becoming "Grounds Step 2's dispatch table." - -`/skill-audit`'s provenance script does now notice this class: it diffs each slug's `Description` -and `Contributing files` text against a base ref and raises an **INFO** when the wording changed. -That is a prompt, not a verdict — it reports only *that* the claim moved, never whether the new -claim is true, because a bash script can verify an entry is internally consistent and nothing more. -Answering it is this flow's job: if a retrofit strengthens or otherwise changes the wording of a -provenance claim, re-read the upstream research doc first and confirm the stronger wording is -actually still true before committing it. - -## Versioning a retrofitted skill - -`SKILL.md` Step 4 says to bump the **patch** version on improve, which presumes there is a version -to bump. A pre-ADR-0020 skill often carries none — `metadata.version` only became mandatory under -ADR-0022, and this flow is exactly where those skills surface. - -A skill with no `metadata.version` is **seeded at `"1.0.0"`, not bumped**. `"0.1.0"` is reserved -for a skill created new by the create flow: it means "created and never yet revised", which -understates a skill that has been through retrofit and audit passes without tracking a version. -Add the field in this retrofit — the `skill-frontmatter` pre-commit hook blocks the commit without -it. - -## Worked example — a description retrofit - -`gitea-issues` before, 827 characters, the single most common shape in the corpus: - -```text -Use when reading or writing Gitea issues: listing repo issues, getting a single issue's details/ -comments/labels, creating an issue, updating its state, adding or editing comments, applying -labels via issue_write, or searching issues/PRs across repositories. Triggers on "create an -issue", "what issues are open", "get issue #N", "close issue #N", "comment on issue #N", "search -issues for X" — even when the user doesn't say "Gitea" explicitly. Composes gitea-labels- -milestones for all label inference/resolution and milestone lookup — do not use this skill to -manage label or milestone definitions themselves (create/edit/delete a label, create/close a -milestone), that's gitea-labels-milestones directly. Do not use for pull requests (use gitea-prs) -or for local git branch/commit work (use gitea-branches or git-branches). -``` - -After, the 290 characters that shipped: - -```text -Use when reading or writing Gitea issues — "create an issue", "what issues are open", "close -issue #N", "comment on issue #N", "search issues for X" — even when the user does not say -"Gitea". Not pull requests -> `gitea-prs`. Not label or milestone definitions -> -`gitea-labels-milestones`. -``` - -The retrofit kept the quoted-phrasing register and dropped the verb list, not the other way round. -Either register is admissible — what is banned is carrying both. Choose whichever routes better -for the skill in hand; here the quoted user phrasings do, because they are how people actually ask. - -What came out, and why: - -| Removed | Why | -|---|---| -| The second trigger register — `Triggers on "create an issue", "what issues are open", …` | The same triggers restated as quoted user phrasings. Two registers of one trigger list is a FAIL, not a suggestion. | -| `applying labels via issue_write` | Implementation detail. The router does not choose a skill by which MCP call it makes. | -| `Composes gitea-labels-milestones for all label inference/resolution and milestone lookup` | A composition note. It changes no routing decision and belongs in `README.md`. | -| The parenthetical `(create/edit/delete a label, create/close a milestone)` | Capability enumeration inside a boundary clause. The boundary needs the target, not its feature list. | -| The `gitea-branches` / `git-branches` boundary | Dropped entirely. Neither was ever going to win an issue request, so the clause defended against nothing — an invented boundary costs characters and buys no routing accuracy. | -| `Do not use for pull requests (use gitea-prs)` prose form | Kept, but rewritten as `Not pull requests -> \`gitea-prs\`.` The rewrite buys characters, one uniform shape for the router, **and** a stricter check: an unresolved arrow target is a blocking ERROR, while an unresolved prose target is only a SUGGESTION unless another target in the same sentence resolves. The prose form does not dangle as loudly. | - -What stayed: one trigger clause, one capability clause, the indirect trigger (genuinely warranted -here — people say "create an issue", not "create a Gitea issue"), and the boundary clauses. - -## Two rules the gates enforce but the prose does not spell out - -**Boundary clauses may be plural.** Write one per genuine near-miss — the example above carries -two, because two different skills could each steal activations. "A boundary clause" in the -contract means *at least one*, not *exactly one*. What is banned is a boundary clause invented for -a skill that was never going to compete, not a second real one. - -**Never let a hyphenated routing target wrap across lines in a folded `>` scalar.** YAML folding -replaces the newline with a space, so `gitea-labels-` at the end of one line and `milestones` at -the start of the next fold into `gitea-labels- milestones`. The gate then reads the target as -`gitea-labels`, finds no such skill, and reports a dangling boundary target. This is not -hypothetical — it is how `gitea-labels-milestones` broke (issue #100). It is fixed: the corpus -carries no dangling target today, and the repo's test suite pins that set as empty, so a -reintroduction fails the suite rather than joining a backlog. Reflow the line so the whole name -sits on one of them. The same applies to any backticked skill or agent name in a description. diff --git a/plugins/kyberforge/.apm/skills/skill-author/references/sources.md b/plugins/kyberforge/.apm/skills/skill-author/references/sources.md index 54b9f6d..2d169d7 100644 --- a/plugins/kyberforge/.apm/skills/skill-author/references/sources.md +++ b/plugins/kyberforge/.apm/skills/skill-author/references/sources.md @@ -34,7 +34,7 @@ source_keys: - **URL:** https://agentskills.io/skill-creation/best-practices.md - **Research doc:** plugins/kyberforge/docs/research/docs/agentskillsio/sources.md - **Description:** Best practices for skill creators — starting from real expertise, spending context wisely, calibrating control, instruction patterns (gotchas, templates, checklists, validation loops) -- **Contributing files:** SKILL.md, references/create.md, references/improve.md, references/contract.md, references/retrofit.md +- **Contributing files:** SKILL.md, references/create.md, references/improve.md, references/contract.md - **Status:** `extracted` ## agentskills-optimizing-descriptions @@ -42,7 +42,7 @@ source_keys: - **URL:** https://agentskills.io/skill-creation/optimizing-descriptions.md - **Research doc:** plugins/kyberforge/docs/research/docs/agentskillsio/sources.md - **Description:** How to systematically test and improve skill descriptions for triggering accuracy — eval queries, trigger rate testing, train/validation splits, optimization loop -- **Contributing files:** SKILL.md, references/improve.md, references/contract.md, references/retrofit.md +- **Contributing files:** SKILL.md, references/improve.md, references/contract.md - **Status:** `extracted` ## agentskills-evaluating-skills diff --git a/plugins/kyberforge/.apm/skills/skill-author/scripts/new-skill.sh b/plugins/kyberforge/.apm/skills/skill-author/scripts/new-skill.sh index 5e1375f..2698f1d 100755 --- a/plugins/kyberforge/.apm/skills/skill-author/scripts/new-skill.sh +++ b/plugins/kyberforge/.apm/skills/skill-author/scripts/new-skill.sh @@ -165,7 +165,6 @@ cp -r "$TEMPLATES_DIR" "$TARGET" # Set skill name in templates sed -i "s/SKILL_NAME/$SKILL_NAME/g" "$TARGET/SKILL.md" -sed -i "s/SKILL_NAME/$SKILL_NAME/g" "$TARGET/README.md" sed -i "s/SKILL_NAME/$SKILL_NAME/g" "$TARGET/tests/README.md" if [[ "$MODE" == "package" ]]; then diff --git a/plugins/kyberforge/.apm/skills/skill-author/tests/new-skill.bats b/plugins/kyberforge/.apm/skills/skill-author/tests/new-skill.bats index 5540f28..274c1f8 100644 --- a/plugins/kyberforge/.apm/skills/skill-author/tests/new-skill.bats +++ b/plugins/kyberforge/.apm/skills/skill-author/tests/new-skill.bats @@ -34,11 +34,6 @@ teardown() { assert [ -f "$DEST/my-tool/SKILL.md" ] } -@test "scaffold contains README.md" { - bash "$SCRIPT" my-tool "$DEST" - assert [ -f "$DEST/my-tool/README.md" ] -} - @test "scaffold contains scripts/, references/, assets/, tests/ directories" { bash "$SCRIPT" my-tool "$DEST" assert [ -d "$DEST/my-tool/scripts" ] @@ -53,12 +48,6 @@ teardown() { assert_success } -@test "substitutes skill name in README.md" { - bash "$SCRIPT" my-tool "$DEST" - run grep "my-tool" "$DEST/my-tool/README.md" - assert_success -} - @test "substitutes skill name in tests/README.md" { bash "$SCRIPT" my-tool "$DEST" run grep "my-tool" "$DEST/my-tool/tests/README.md" diff --git a/plugins/kyberforge/skills/agent-audit/README.md b/plugins/kyberforge/skills/agent-audit/README.md deleted file mode 100644 index 3face54..0000000 --- a/plugins/kyberforge/skills/agent-audit/README.md +++ /dev/null @@ -1,79 +0,0 @@ -# agent-audit - -Audits an agent definition for correctness and quality against the Claude Code and Copilot agent -references and the house context-budget contract (ADR-0020) — a single vendor-neutral file at -plugin/APM scope, or a Claude Code and Copilot file pair at project/user scope. - -## What it does - -1. Runs `scripts/validate.sh` and `scripts/validate-provenance.sh` for structural and provenance - checks, plus `scripts/vale-wrap.sh` — a Vale prefilter that deterministically flags - non-imperative description openers, composition and architecture notes, vague wording, padding - phrases, "There is/are" sentence openers, and CC-specific "Use proactively" phrasing in a - Copilot or vendor-neutral description -2. Reads the agent file, and its counterpart when one exists, then loads the contract for its scope -3. Applies qualitative checks across description, body, delegation and comment discipline, loading - one rubric from `references/` per group -4. Outputs a compact findings report — findings only, grouped by dimension, each with Why and Fix — - and a result block with handoff to `agent-author` - -Two things follow from ADR-0020 and are easy to get backwards. Agents take the **same** description -gates a skill takes — 250 characters SUGGESTION, 400 FAIL, since a `name` + `description` is -preloaded into every session either way — and **no body word gate at all**, because an agent body -becomes the system prompt of a fresh context rather than competing with the caller's live -conversation. Body length is judged through the delegation check instead: an agent body that -restates a procedure owned by a skill it can invoke is a FAIL, because a plugin-scope agent has no -sibling `references/` directory to disclose to and can only delegate. - -At **plugin/APM scope** the audit accepts the single `.apm/agents/.agent.md` file — there is -no counterpart, and pair consistency does not apply. `validate.sh` hard-`FAIL`s any frontmatter -field outside the vendor-neutral allowlist, since `apm compile` copies frontmatter verbatim to both -harnesses and an unsafe field cannot be silently dropped for just one of them. The allowlist lives -in the `apm-agent-allowlist` section of `references/field-inventory.md`, is read from there as data -by the script, and is deliberately not restated anywhere else in this skill (ADR-0009). - -At **project/user scope** the audit accepts either file in a CC `.md` / Copilot `.agent.md` pair, -derives the counterpart automatically, and validates both, including the field-leakage checks in -each direction. - -## Usage - -``` -/agent-audit -``` - -Pass the path to either agent file as the argument. - -## Files - -| File | Purpose | -|------|---------| -| `SKILL.md` | Skill instructions for agents | -| `assets/vale/.vale.ini` | Vale config: scopes `Kyberforge` to `**/agents/*.md`, `Kyberforge`+`KyberforgeCopilot` to `**/*.agent.md` | -| `assets/vale/styles/Kyberforge/CompositionNote.yml` | Flags composition and architecture notes in a description ("cross-cutting", "entry point", "composes", "rather than duplicating") that belong in README.md | -| `assets/vale/styles/Kyberforge/DescriptionOpener.yml` | Flags descriptions opening with "This..." instead of an imperative "Use when..." | -| `assets/vale/styles/Kyberforge/PaddingPhrase.yml` | Flags generic "see references/ for info" pointers instead of specific file references | -| `assets/vale/styles/Kyberforge/SentenceOpenerThereIs.yml` | Flags sentences opening with "There is/are" instead of naming the subject directly | -| `assets/vale/styles/Kyberforge/VagueWording.yml` | Flags vague capability wording ("helps with", "utilize", "assists with", "used for") in descriptions | -| `assets/vale/styles/KyberforgeCopilot/ProactivePhrase.yml` | Flags CC-specific "Use proactively" phrasing with no effect in Copilot descriptions | -| `references/README.md` | Directory documentation for references/ | -| `references/finding-criteria.md` | Every dimension's FAIL and SUGGESTION criteria — the one Step 3 file read on every run; it decides which rubrics below are worth loading | -| `references/description-quality.md` | Rubric for the description dimension — why the description is the expensive part, the hand-invoked contract, the three-part shape, indirect triggers, and near-miss exclusions | -| `references/body-and-delegation.md` | Rubric for the body, delegation and comment-discipline dimensions — the core test, the delegation FAIL, why agents take no body word gate, and what an agent body is for | -| `references/scope-plugin-apm.md` | Scope contract for a single vendor-neutral APM agent file — allowlist, dimension routing, and the dimensions that do not apply | -| `references/scope-project-user.md` | Scope contract for a CC / Copilot pair — counterpart derivation, provider field rules, pair consistency | -| `references/validation-scripts.md` | Loaded only when a Step 1 script fails or cannot run — scope-detection walk-up, manual fallback checks, known script failures | -| `references/field-inventory.md` | Authoritative field lists read as data by `validate.sh`: valid CC and Copilot agent fields, and the vendor-neutral plugin/APM-scope allowlist | -| `references/sources.md` | Research provenance for skill content | -| `scripts/README.md` | Directory documentation for scripts/ | -| `scripts/validate.sh` | Structural validator — required fields, name format, placeholder detection, the ADR-0020 description budget, and the field rules for the detected scope | -| `scripts/validate-provenance.sh` | Provenance chain validation against `sources.md` at the package root (plugin/APM scope only) | -| `scripts/vale-wrap.sh` | Drop-in `vale` wrapper that works around a frontmatter-description NLP scope limitation | -| `tests/README.md` | (source-only) Bats test dependency and run instructions | -| `tests/validate.bats` | (source-only) Bats tests for validate.sh | -| `tests/validate-provenance.bats` | (source-only) Bats tests for validate-provenance.sh | - -Rows marked **(source-only)** exist in the authoring source (`.apm/skills/agent-audit/`) but are -not present in an installed plugin: `scripts/sync-plugin-content.sh` strips -`//tests` when it generates the flat mirror, because these are dev-time fixtures no -plugin host needs to discover (ADR-0017). Run them from a repo checkout, not from an install. diff --git a/plugins/kyberforge/skills/agent-audit/SKILL.md b/plugins/kyberforge/skills/agent-audit/SKILL.md index 67396dc..91d3e5d 100644 --- a/plugins/kyberforge/skills/agent-audit/SKILL.md +++ b/plugins/kyberforge/skills/agent-audit/SKILL.md @@ -7,7 +7,7 @@ description: > directory -> skill-audit. allowed-tools: Bash Read metadata: - version: "1.0.1" + version: "1.0.2" category: factory source_keys: - context7-websites-code-claude @@ -34,7 +34,7 @@ bash scripts/validate-provenance.sh bash scripts/vale-wrap.sh [] ``` -`validate.sh` takes either half of a project/user-scope pair or the single plugin/APM-scope file, detects the provider from the extension and the scope by walking up, then checks required fields, kebab-case `name`, `FILL IN:` placeholders, template HTML comments left in frontmatter, the ADR-0020 description budget (250 chars SUGGESTION, 400 FAIL, measured on the folded YAML value) and the fields that scope permits. Its findings become the `### Structure` dimension — its FAILs and its SUGGESTIONs both — except the ones the Step 2 scope contract re-routes. +`validate.sh` takes either half of a project/user-scope pair or the single plugin/APM-scope file, detects the provider from the extension and the scope by walking up, then checks required fields, kebab-case `name`, `FILL IN:` placeholders, template HTML comments left in frontmatter, the description budget (250 chars SUGGESTION, 400 FAIL, measured on the folded YAML value) and the fields that scope permits. Its findings become the `### Structure` dimension — its FAILs and its SUGGESTIONs both — except the ones the Step 2 scope contract re-routes. If a validation script fails or cannot run — Bash denied, `python3` or `vale` absent, `references/field-inventory.md` missing — read `references/validation-scripts.md`; what these scripts measure is not reproducible by reading. diff --git a/plugins/kyberforge/skills/agent-audit/references/README.md b/plugins/kyberforge/skills/agent-audit/references/README.md deleted file mode 100644 index 6ae112e..0000000 --- a/plugins/kyberforge/skills/agent-audit/references/README.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -source_keys: [] ---- - -# references/ - -Additional documentation agents load on demand. - -## Files - -| File | Purpose | -|------|---------| -| `finding-criteria.md` | Every dimension's FAIL and SUGGESTION criteria — the one Step 3 file read on every run; it decides which rubrics below are worth loading. | -| `description-quality.md` | Rubric for the description dimension — why the description is the expensive part, the hand-invoked contract, the three-part shape, indirect triggers, and near-miss exclusions. | -| `body-and-delegation.md` | Rubric for the body, delegation and comment-discipline dimensions — the core test, the delegation FAIL, why agents take no body word gate, and what an agent body is for. | -| `scope-plugin-apm.md` | Contract for a single vendor-neutral `.apm/agents/.agent.md` file — allowlist, dimension routing, and the dimensions that do not apply. | -| `scope-project-user.md` | Contract for a Claude Code / Copilot file pair — counterpart derivation, provider field rules, and pair consistency. | -| `validation-scripts.md` | Loaded only when a Step 1 script fails or cannot run — scope-detection walk-up, manual fallback checks, and known script failures. | -| `field-inventory.md` | Authoritative field lists, read as data by `validate.sh`: valid CC and Copilot agent fields, and the vendor-neutral plugin/APM allowlist. | -| `sources.md` | Research provenance records for skill content. Load only when tracing the origin of a specific rule or field constraint. | diff --git a/plugins/kyberforge/skills/agent-audit/references/body-and-delegation.md b/plugins/kyberforge/skills/agent-audit/references/body-and-delegation.md index 325bed6..c3d32d6 100644 --- a/plugins/kyberforge/skills/agent-audit/references/body-and-delegation.md +++ b/plugins/kyberforge/skills/agent-audit/references/body-and-delegation.md @@ -10,7 +10,7 @@ source_keys: # Body, Delegation and Comment Discipline Reference Upstream source: Claude Code subagent and plugin references, GitHub Copilot custom-agents -configuration. House contract: ADR-0020, the context budget. +configuration. House contract: the context budget. Read this when judging the **body**, **delegation** and **comment-discipline** dimensions. @@ -23,8 +23,8 @@ dilutes the signal of what matters. ## Agents take no body word gate -ADR-0020 gates a skill body at 600 words SUGGESTION / 900 FAIL and deliberately gates an agent body -at nothing. The two are not the same construct: a skill body is loaded into the caller's live +A skill body is gated at 600 words SUGGESTION / 900 FAIL; an agent body is deliberately gated at +nothing. The two are not the same construct: a skill body is loaded into the caller's live context and competes with the conversation already there, while an agent body *becomes* the system prompt of a fresh context that has nothing else in it. The rationale for the 900-word ceiling does not transfer, so: diff --git a/plugins/kyberforge/skills/agent-audit/references/description-quality.md b/plugins/kyberforge/skills/agent-audit/references/description-quality.md index 4083917..6382d84 100644 --- a/plugins/kyberforge/skills/agent-audit/references/description-quality.md +++ b/plugins/kyberforge/skills/agent-audit/references/description-quality.md @@ -9,7 +9,7 @@ source_keys: # Agent Description Quality Reference Upstream source: Claude Code subagent reference, GitHub Copilot custom-agents configuration. -House contract: ADR-0020, the context budget. The house contract is narrower than either +House contract: the context budget. The house contract is narrower than either platform's schema rather than a reinterpretation of it: where both speak, both must be satisfied. ## Why the description is the expensive part diff --git a/plugins/kyberforge/skills/agent-audit/references/finding-criteria.md b/plugins/kyberforge/skills/agent-audit/references/finding-criteria.md index 5cd8509..6c9c5e0 100644 --- a/plugins/kyberforge/skills/agent-audit/references/finding-criteria.md +++ b/plugins/kyberforge/skills/agent-audit/references/finding-criteria.md @@ -90,8 +90,8 @@ Flag as SUGGESTION if: - A rationale is missing from a rule the agent is expected to enforce — present but unexplained - Comments are useful but verbose enough to bury the field they annotate -**Never report an agent body as too long on a word count.** ADR-0020 gates a skill body at -600/900 words and deliberately gates an agent body at nothing, because an agent body *becomes* the +**Never report an agent body as too long on a word count.** A skill body is gated at 600/900 words; +an agent body is deliberately gated at nothing, because an agent body *becomes* the system prompt of a fresh context rather than competing with a live conversation. No number exists to cite. The one length signal that applies is the Copilot runtime's 30,000-character body limit, which `validate.sh` already reports as a SUGGESTION. Length is judged through the delegation FAIL diff --git a/plugins/kyberforge/skills/agent-author/README.md b/plugins/kyberforge/skills/agent-author/README.md deleted file mode 100644 index 6b45bbf..0000000 --- a/plugins/kyberforge/skills/agent-author/README.md +++ /dev/null @@ -1,58 +0,0 @@ -# agent-author - -Creates and improves agent definition files for Claude Code and GitHub Copilot CLI. - -## What it does - -Scaffolds and fills in agent definition files at plugin/APM, project, or user scope. Project and user scope always generate a Claude Code + Copilot CLI file pair (`.md` + `.agent.md`) in one pass. Plugin/APM scope generates a single vendor-neutral `.apm/agents/.agent.md` file instead — no separate Claude Code / Copilot split, since `apm compile` has no per-target field integrator (see ADR-0016). Also applies improvement signals — grill output, inline feedback, session context — to existing agent files. Bumps the version after every change: the resolved package's `apm.yml` at plugin/APM scope (minor for new agents, patch for improvements); project/user scope has no manifest to bump. - -## Before you start - -Have ready: the agent's name (kebab-case), the root directory (plugin root, project root, or `~`), a one-sentence purpose, and the triggering condition (when should the runtime delegate to this agent?). - -## Usage - -``` -/agent-author -``` - -**Manual scaffold (human workflow):** -```bash -bash scripts/new-agent.sh - -# Examples: -bash scripts/new-agent.sh code-reviewer packages/my-package/ # plugin/APM scope if packages/my-package/apm.yml has a type: field -bash scripts/new-agent.sh deploy-assistant . -bash scripts/new-agent.sh security-reviewer ~ -``` - -## Files - -| File | Purpose | -|------|---------| -| `SKILL.md` | Skill instructions for agents — gotchas, the create/improve dispatch table, the scope dispatch table, the shared gates, and validation/close | -| `scripts/new-agent.sh` | Scaffolds agent definition file(s) from templates — a single `.apm/agents/.agent.md` at plugin/APM scope, or a Claude Code + Copilot CLI pair at project/user scope | -| `references/create.md` | Create flow: prerequisites, scaffold and scope walk-up, what to fill in, package-root `sources.md` | -| `references/improve.md` | Improve flow: signal verification, root-cause grouping, generalizing, delegation over growth, ADR-0020 retrofit | -| `references/contract.md` | Description and body contract: three-part description shape, 250/400 tiers, delegation rule in place of a body word gate, invocation axis | -| `references/plugin-scope.md` | Plugin/APM scope field rules for the single vendor-neutral file, plus its pre-audit checklist | -| `references/project-user-scope.md` | Project/user scope field rules for the Claude Code + Copilot pair, both Copilot formats, plus its pre-audit checklist | -| `references/deployment-modes.md` | Scope hierarchy and precedence, scoped identifiers, cache isolation, path conventions | -| `references/scripts.md` | Conventions for new-agent.sh and the templates it copies: contract, template variables, file placement, error messages | -| `references/sources.md` | Research provenance — sources that informed this skill | -| `assets/templates/claude-code.md` | Annotated Claude Code agent definition template (project/user scope) | -| `assets/templates/copilot.agent.md.template` | Annotated Copilot CLI agent definition template (project/user scope) | -| `assets/templates/apm-agent.md` | Annotated vendor-neutral APM agent definition template (plugin/APM scope) | -| `tests/new-agent.bats` | (source-only) bats tests for `scripts/new-agent.sh` | -| `assets/README.md` | Directory meta-documentation for assets/ | -| `references/README.md` | Directory meta-documentation for references/ | -| `scripts/README.md` | Directory meta-documentation for scripts/ | -| `tests/README.md` | (source-only) bats dependency instructions and run command | - -Rows marked **(source-only)** exist in the authoring source (`.apm/skills/agent-author/`) but are -not present in an installed plugin: `scripts/sync-plugin-content.sh` strips -`//tests` when it generates the flat mirror, because these are dev-time fixtures no -plugin host needs to discover (ADR-0017). Run them from a repo checkout, not from an install. The -`assets/templates/` rows above are unaffected — the exclusion is depth-scoped to -`//tests`, so template trees that themselves contain a `tests/` directory ship -intact. diff --git a/plugins/kyberforge/skills/agent-author/SKILL.md b/plugins/kyberforge/skills/agent-author/SKILL.md index c399ffa..af51352 100644 --- a/plugins/kyberforge/skills/agent-author/SKILL.md +++ b/plugins/kyberforge/skills/agent-author/SKILL.md @@ -6,7 +6,7 @@ description: > Not read-only review -> `agent-audit`. Not skills -> `skill-author`. allowed-tools: Bash Read Write Edit metadata: - version: "1.0.1" + version: "1.0.2" category: factory source_keys: - context7-websites-code-claude diff --git a/plugins/kyberforge/skills/agent-author/references/README.md b/plugins/kyberforge/skills/agent-author/references/README.md deleted file mode 100644 index ef252d0..0000000 --- a/plugins/kyberforge/skills/agent-author/references/README.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -source_keys: [] ---- - -# references/ - -## create.md - -The create flow, loaded from SKILL.md Step 1 when no agent file exists at the target path. -Covers: prerequisites, the scaffold script and its scope walk-up, what to fill in at every scope, -and populating or deleting the package-root `sources.md`. - -## improve.md - -The improve flow, loaded from SKILL.md Step 1 when a file exists and at least one improvement -signal is present. Covers: signal verification, partial-pair recovery, root-cause grouping, -generalizing rather than patching, delegation over growth, and the ADR-0020 retrofit rule. - -## contract.md - -The description and body contract, loaded from SKILL.md Step 3 before any description is written -or any body restructured. Covers: the three-part description shape, banned description content, -boundary-target resolution, the 250/400 length tiers, the body role-instruction pattern, the -delegation rule that replaces a body word gate, and the invocation axis. - -## plugin-scope.md - -Field rules and the pre-audit checklist for the single vendor-neutral `.apm/agents/.agent.md` -file. Loaded from SKILL.md Step 2 when the scaffold resolves plugin/APM scope. - -## project-user-scope.md - -Field rules and the pre-audit checklist for the Claude Code `.md` + Copilot `.agent.md` pair, -including the two distinct Copilot formats. Loaded from SKILL.md Step 2 when the scaffold resolves -project or user scope. - -## deployment-modes.md - -Scope hierarchy and precedence, scoped identifiers for plugin subdirectory agents, cache isolation -behaviour, and Copilot CLI path conventions. Loaded from SKILL.md Step 2 when precedence, paths or -cache isolation matter to the run. - -## scripts.md - -Conventions for the `new-agent.sh` scaffold script, the templates it copies, and any future script -in this skill. Loaded from `create.md` Step 1 when the script or a template has to change. Covers: -the no-interactive-prompts rule, structured output, idempotency, template variables, file -placement, error messages, and the no-restated-field-roster rule that `tests/new-agent.bats` -enforces. - -## sources.md - -Research provenance record for this skill. Lists the upstream research sources -(claude-code-plugins and github-copilot-plugins research docs) that informed SKILL.md and the -reference files. Used by `skill-audit` to validate the provenance chain. diff --git a/plugins/kyberforge/skills/agent-author/references/contract.md b/plugins/kyberforge/skills/agent-author/references/contract.md index cea9336..d5ee27e 100644 --- a/plugins/kyberforge/skills/agent-author/references/contract.md +++ b/plugins/kyberforge/skills/agent-author/references/contract.md @@ -6,7 +6,7 @@ source_keys: # The agent description and body contract -House contract, set by ADR-0020. The counts and the boundary targets are enforced by +House contract. The counts and the boundary targets are enforced by `agent-audit`'s `scripts/validate.sh`; the prose patterns by the Vale styles it bundles; the judgment calls by its reference files. @@ -40,9 +40,8 @@ Banned from a description; move it to the body or to `README.md`: - Restating the same trigger twice in two registers — a verb list, then the same verbs re-quoted as user phrasings. This is a FAIL, not a suggestion. -**Do not open with an action verb.** "Reviews…", "Analyzes…", "Generates…" was the old house rule -and ADR-0020 deleted it: the opener is `Use when`, matching every skill in this corpus, so one -router reads one shape. +**Do not open with an action verb.** The opener is `Use when`, matching every skill in this corpus, +so one router reads one shape. **"Use proactively" is Claude Code-only, and conditional even there.** The phrase steers the Claude Code runtime to offer an agent unprompted and does nothing anywhere else, so where it may diff --git a/plugins/kyberforge/skills/agent-author/references/improve.md b/plugins/kyberforge/skills/agent-author/references/improve.md index 0aef172..2a30537 100644 --- a/plugins/kyberforge/skills/agent-author/references/improve.md +++ b/plugins/kyberforge/skills/agent-author/references/improve.md @@ -66,9 +66,10 @@ answer is no. all caps (ALWAYS/NEVER) is usually better reframed as why the behaviour matters, so the agent can apply judgment at the edges. -**Retrofit before extending.** Any agent predating ADR-0020 has to meet the description contract -before any other edit lands — the gates are hot and carry no baseline file, so a one-line fix to a -non-compliant agent cannot be committed until its description meets `references/contract.md`. +**Retrofit before extending.** Any agent whose description does not meet the contract has to be +brought into compliance before any other edit lands — the gates are hot and carry no baseline file, +so a one-line fix to a non-compliant agent cannot be committed until its description meets +`references/contract.md`. Treat that retrofit as part of the same change, not a follow-up. **Re-check the scope rules.** Read the reference for the resolved scope (`SKILL.md` Step 2) and diff --git a/plugins/kyberforge/skills/apm-install/README.md b/plugins/kyberforge/skills/apm-install/README.md deleted file mode 100644 index 995a182..0000000 --- a/plugins/kyberforge/skills/apm-install/README.md +++ /dev/null @@ -1,22 +0,0 @@ -# apm-install - -Installs and configures the `apm` (Agent Package Manager) CLI and the agent runtimes it manages. - -## What it does - -Covers the two provisioning steps for working with apm: installing the `apm` binary itself (quick-install script, pinned version, air-gapped mirror, or pip/pipx), and installing/managing an agent runtime apm drives (`apm runtime setup copilot|codex|gemini|llm`, listing installed runtimes, checking which one `apm run` defaults to). - -## Usage - -``` -/apm-install -``` - -Once `apm` and a runtime are in place, use `apm-workflow` for authoring `apm.yml`, scaffolding packages/marketplaces, compiling, packing, publishing, and auditing. - -## Files - -| File | Purpose | -|------|---------| -| `SKILL.md` | Skill instructions for agents | -| `references/sources.md` | Provenance chain — research sources that informed this skill | diff --git a/plugins/kyberforge/skills/apm-workflow/README.md b/plugins/kyberforge/skills/apm-workflow/README.md deleted file mode 100644 index 1328bed..0000000 --- a/plugins/kyberforge/skills/apm-workflow/README.md +++ /dev/null @@ -1,33 +0,0 @@ -# apm-workflow - -Authors, scaffolds, compiles, and audits apm packages and marketplaces. - -## What it does - -Covers the apm.yml lifecycle a session moves through repeatedly: configuring/scaffolding a package manifest, resolving/fetching its declared dependencies, building or registering a marketplace, compiling/packing/publishing a distributable, and validating integrity via apm audit. Dispatches on the resolved flow to one of five reference files; each carries that flow's traps and names a sibling file where one flow genuinely depends on another's detail. - -## Before you start - -Requires the `apm` binary and (for runtime-driven scripts) an agent runtime already installed — use `apm-install` first if either is missing. - -## Usage - -``` -/apm-workflow configure -/apm-workflow install -/apm-workflow marketplace -/apm-workflow compile -/apm-workflow audit -``` - -## Files - -| File | Purpose | -|------|---------| -| `SKILL.md` | Dispatch table and the three gotchas common to every branch (MCP secret indirection, the `experimental enable registries` precondition, the unchecked `type:` field) | -| `references/configure.md` | apm.yml schema, apm plugin init, dependency forms, MCP secrets, `includes:`, registries; `type:` and `experimental enable registries` traps | -| `references/install.md` | apm install, apm install [PACKAGE_REF], --update, --target agent-skills | -| `references/marketplace.md` | Building/registering a marketplace, `marketplace add` vs `package add`, package registration, versioning, Claude Code reserved-name/publish-confirm gotchas | -| `references/compile.md` | apm compile / pack / publish / run, claude plugin validate agents/ gotcha | -| `references/audit.md` | apm audit vs apm audit --ci (they check different things), apm marketplace check, CI wiring, frozen installs, claude plugin validate terminal check | -| `references/sources.md` | Provenance chain — research sources that informed this skill | diff --git a/plugins/kyberforge/skills/forge/README.md b/plugins/kyberforge/skills/forge/README.md deleted file mode 100644 index d76b745..0000000 --- a/plugins/kyberforge/skills/forge/README.md +++ /dev/null @@ -1,40 +0,0 @@ -# forge - -Guided entry point for building or improving something in any plugin of this repo when the target artifact type isn't decided yet. - -## What it does - -Grills the user's intent via `grill-with-docs` (inline, interactive) against this repo's `CONTEXT.md` and `docs/adr/`, classifies the target artifact type (skill, agent/subagent definition, plugin, or marketplace entry), announces the classification, then routes to the matching author skill — chaining more than one, in dependency order, if the intent spans multiple artifact types. - -Author-skill invocation defaults to a fork subagent (inherits the grilled-intent context) and falls back to inline when forking isn't possible or the routed flow needs live user interaction (clarifying questions, a HITL gate). After a `skill-author` or `agent-author` route finishes — each already closes out with its own inline audit — forge spins up a separate clean-context subagent to independently re-run the matching audit skill (`skill-audit` / `agent-audit`) as a distinct check on the finished artifact, not a duplicate of the inline one. If that clean audit turns up any unresolved finding, forge loops — re-invoke the author skill to resolve it, re-run the clean audit — until the clean audit comes back with nothing unresolved. `apm-workflow` routes (plugin, marketplace entry) get no recheck: they have no audit counterpart, and no automatic terminal check either — `apm audit` is a separate `apm-workflow` action, not a closing step of the configure or marketplace flow — so forge verifies those routes by reading the written manifest back against the grilled intent. - -## Before you start - -Have a rough idea of what you want to build or change. forge doesn't require you to already know whether it's a skill, agent, plugin, or marketplace entry — that classification is its job. - -## Usage - -``` -/forge -``` - -Skip forge and call the target skill directly (`/skill-author`, `/agent-author`, `/apm-workflow`) when you already know the artifact type. - -## Files - -| File | Loaded when | -|------|-------------| -| `SKILL.md` | Always — Gotchas, the grill step, the classification dispatch table, and the gates common to every route | -| `references/author-routes.md` | The intent classifies as a skill or an agent/subagent definition — fork-vs-inline judgment and the two-tier verification loop | -| `references/apm-routes.md` | The intent classifies as a plugin or a marketplace entry — always-inline invocation, why these routes get no clean-context recheck, and the manual read-back that stands in for one | -| `references/version-bump.md` | A finished route left the owning package's version unbumped — walk-up rule and the clean-context bump brief | -| `references/sources.md` | Never loaded at runtime — provenance chain for the research sources that informed this skill | - -## Routes to - -| Artifact type | Skill | -|---|---| -| Skill | `skill-author` | -| Agent / subagent definition | `agent-author` | -| Plugin | `apm-workflow` (configure) | -| Marketplace entry | `apm-workflow` (marketplace) | diff --git a/plugins/kyberforge/skills/forge/SKILL.md b/plugins/kyberforge/skills/forge/SKILL.md index f63242a..a88377a 100644 --- a/plugins/kyberforge/skills/forge/SKILL.md +++ b/plugins/kyberforge/skills/forge/SKILL.md @@ -8,7 +8,7 @@ description: > already named — invoke `skill-author`, `agent-author` or `apm-workflow` directly. metadata: - version: "1.0.0" + version: "1.0.1" category: factory source_keys: - claude-code-subagents-docs diff --git a/plugins/kyberforge/skills/forge/references/sources.md b/plugins/kyberforge/skills/forge/references/sources.md index 4f065b3..f64666f 100644 --- a/plugins/kyberforge/skills/forge/references/sources.md +++ b/plugins/kyberforge/skills/forge/references/sources.md @@ -28,7 +28,7 @@ - **URL:** https://agentskills.io/specification.md - **Research doc:** plugins/kyberforge/docs/research/docs/agentskillsio/sources.md -- **Description:** Complete SKILL.md format specification — confirms `assets/`, `references/`, and `scripts/` are warranted only by the bulk/reusability of supporting content (large reference material, executable code, templates), not by a skill's category, and forge's per-route procedures are that kind of supporting content — so the spec permits the `references/` split here but does not require it. The warrant is a house decision: ADR-0020's rule that dispatch is mandatory at two or more mutually exclusive flows, which forge's four-row table is. `references/sources.md` likewise exists for this repo's own provenance-chain convention (see `CONTEXT.md`), not because the spec requires it. +- **Description:** Complete SKILL.md format specification — confirms `assets/`, `references/`, and `scripts/` are warranted only by the bulk/reusability of supporting content (large reference material, executable code, templates), not by a skill's category, and forge's per-route procedures are that kind of supporting content — so the spec permits the `references/` split here but does not require it. The warrant is a house decision: dispatch is mandatory at two or more mutually exclusive flows, which forge's four-row table is. `references/sources.md` likewise exists for this repo's own provenance-chain convention (see `CONTEXT.md`), not because the spec requires it. - **Contributing files:** SKILL.md - **Status:** `extracted` diff --git a/plugins/kyberforge/skills/skill-audit/README.md b/plugins/kyberforge/skills/skill-audit/README.md deleted file mode 100644 index 468be43..0000000 --- a/plugins/kyberforge/skills/skill-audit/README.md +++ /dev/null @@ -1,53 +0,0 @@ -# skill-audit - -Audit a skill directory against the agentskills.io specification and the house context-budget contract (ADR-0020). Runs structural validation then a qualitative review across description quality, body discipline, patterns, formatting, file structure, scripts, and internal consistency, plus a provenance chain check. - -## What it does - -1. Runs `scripts/validate.sh` and `scripts/validate-provenance.sh` for structural and provenance checks, plus `scripts/vale-wrap.sh` — a Vale prefilter that deterministically flags non-imperative description openers, composition and architecture notes, vague wording, padding phrases, and "There is/are" sentence openers -2. Reads all files in the skill directory -3. Applies qualitative checks across five dimension groups — always loading `references/finding-criteria.md`, then one rubric from `references/` per group the criteria put in play -4. Outputs a compact findings report — findings only, grouped by dimension, each with Why and Fix — and a result block with handoff to `skill-author` - -`validate.sh` enforces two independent length families that must not be conflated: the agentskills.io spec conformance ceilings (500 lines, 2,770 words, both counting the whole file) and the ADR-0020 context budget (250/400 description characters, 600/900 body-only words). - -Alongside those it runs shape checks that are not length measurements at all. Three are FAILs: every routing target named in the description — in the compressed `Not -> ` arrow **and** in the prose form — must resolve to a real skill or agent; every `references/.md` the body names must exist on disk; and `metadata.version` must be present and three-part semver (ADR-0022). That last one is FAIL rather than SUGGESTION because the `skill-frontmatter` pre-commit hook rejects the file without it — an audit grading it lower would report ready-to-ship on a file the commit gate refuses. Three are SUGGESTIONs: a missing boundary clause, a Gotchas section over five entries, and a Gotchas section over 25% of the body. The resolution universe for boundary targets is derived by walking up from the audited `SKILL.md` — the authoring root above it, its own apm package, and that package's declared `apm.yml` dependencies — so a fresh clone and a machine that has run `apm install` return the same verdict. When no universe can be determined the check prints `INFO ... DID NOT RUN` and does not silently pass. - -## Usage - -``` -/skill-audit -``` - -Provide the path to the skill directory to audit when invoking. - -## Files - -| File | Purpose | -|------|---------| -| `SKILL.md` | Skill instructions for agents | -| `scripts/validate.sh` | Structural validator — checks name format, name matches directory, description presence and length, `metadata.version` presence and semver shape (ADR-0022), body-only word count, line and whole-file word ceilings, boundary-clause presence, boundary-target resolution, `references/` pointer existence, Gotchas entry count and body share, placeholder detection, script executable bit, and interactive-prompt detection | -| `scripts/validate-provenance.sh` | Provenance validator — checks sources.md completeness, source_keys/slug consistency, Contributing files existence, bidirectional linkage, Research doc: fields, upstream research doc alignment, and (check 9, INFO only) whether a slug's `Description` or `Contributing files` text has changed since a base ref — `--base-ref=` or `VALIDATE_PROVENANCE_BASE_REF`, defaulting to the merge base with `origin/main` | -| `scripts/vale-wrap.sh` | Vale prefilter wrapper — runs the bundled `Kyberforge` Vale styles against SKILL.md and reports alerts as deterministic FAILs ahead of Step 3's qualitative review | -| `assets/vale/.vale.ini` | Vale configuration — points Vale at the bundled `Kyberforge` style path, self-located relative to `vale-wrap.sh` | -| `assets/vale/styles/Kyberforge/CompositionNote.yml` | Vale rule — flags composition and architecture notes in a description (e.g. "cross-cutting", "entry point", "rather than duplicating") | -| `assets/vale/styles/Kyberforge/DescriptionOpener.yml` | Vale rule — flags non-imperative "This..." description openers | -| `assets/vale/styles/Kyberforge/PaddingPhrase.yml` | Vale rule — flags generic "see references/" padding phrasing in conditional references | -| `assets/vale/styles/Kyberforge/SentenceOpenerThereIs.yml` | Vale rule — flags body sentences starting with "There is"/"There are" | -| `assets/vale/styles/Kyberforge/VagueWording.yml` | Vale rule — flags known filler wording (e.g. "helps with", "utilize") | -| `references/finding-criteria.md` | Every dimension's FAIL and SUGGESTION criteria — the one Step 3 file loaded on every run; it decides which rubrics below are worth loading | -| `references/description-quality.md` | Rubric for the description dimension — why the description is the expensive part, the hand-invoked (`disable-model-invocation`) contract, the three-part shape, when an indirect trigger is warranted, near-miss exclusions, and a before/after pair | -| `references/body-discipline.md` | Rubric for the body-discipline dimension — the core test, the 600/900 body-only budget against the 2,770-word whole-file backstop, the mandatory-dispatch rule, and the Gotchas constraints | -| `references/patterns.md` | Rubric for the patterns dimension — which instruction construct fits which job, and how each is correctly formed | -| `references/file-structure.md` | Rubric for the file-structure and internal-consistency dimensions — permitted directories, cross-plugin path rules and their two structural exemptions, README drift | -| `references/formatting-and-scripts.md` | Rubric for the formatting and scripts dimensions — heading and fencing conventions, and the agentic-use criteria for bundled scripts | -| `references/validation-scripts.md` | Step 1 troubleshooting — the manual structural fallback when `validate.sh` cannot run, and the script exit codes that are easy to misread (loaded on a script failure, and on any exit-0 run that printed something — `validate-provenance.sh`'s check 9 is INFO-only, so its findings arrive that way) | -| `references/sources.md` | Provenance record — agentskills.io sources that informed this skill and which files each contributed to | -| `tests/validate.bats` | (source-only) Bats test suite for validate.sh | -| `tests/validate-provenance.bats` | (source-only) Bats test suite for validate-provenance.sh | -| `tests/README.md` | (source-only) Setup instructions for bats-support and bats-assert test dependencies | - -Rows marked **(source-only)** exist in the authoring source (`.apm/skills/skill-audit/`) but are -not present in an installed plugin: `scripts/sync-plugin-content.sh` strips -`//tests` when it generates the flat mirror, because these are dev-time fixtures no -plugin host needs to discover (ADR-0017). Run them from a repo checkout, not from an install. diff --git a/plugins/kyberforge/skills/skill-audit/SKILL.md b/plugins/kyberforge/skills/skill-audit/SKILL.md index 8f093d9..c6f0103 100644 --- a/plugins/kyberforge/skills/skill-audit/SKILL.md +++ b/plugins/kyberforge/skills/skill-audit/SKILL.md @@ -7,7 +7,7 @@ description: > skill-author. allowed-tools: Bash Read metadata: - version: "1.0.1" + version: "1.0.2" category: factory source_keys: - agentskills-home @@ -50,7 +50,7 @@ Read `references/validation-scripts.md` when any of the three cannot run or exit ## Step 2 — Read the whole skill -Read `SKILL.md`, `README.md`, and every text file under `scripts/`, `references/`, `assets/` and `tests/`. Skip binaries only — internal-consistency findings need the full picture. +Read `SKILL.md` and every text file under `scripts/`, `references/`, `assets/` and `tests/`. Skip binaries only — internal-consistency findings need the full picture. ## Step 3 — Qualitative audit @@ -64,7 +64,7 @@ Read `references/finding-criteria.md` first — every dimension's FAIL and SUGGE | file-structure, internal-consistency | `references/file-structure.md` | | formatting, scripts | `references/formatting-and-scripts.md` | -Each rubric is self-contained and grounded in the agentskills.io specification plus the house context budget (ADR-0020). Cite file and line number for every finding. +Each rubric is self-contained and grounded in the agentskills.io specification plus the house context budget. Cite file and line number for every finding. ## Step 4 — Report diff --git a/plugins/kyberforge/skills/skill-audit/references/body-discipline.md b/plugins/kyberforge/skills/skill-audit/references/body-discipline.md index 31f28c6..b071ca2 100644 --- a/plugins/kyberforge/skills/skill-audit/references/body-discipline.md +++ b/plugins/kyberforge/skills/skill-audit/references/body-discipline.md @@ -7,7 +7,7 @@ source_keys: # Body Discipline Reference Upstream source: agentskills.io — skill-authoring, best-practices. -House contract: ADR-0020, the context budget. +House contract: the context budget. ## The core test @@ -31,7 +31,7 @@ Include content the agent lacks: Move to `references/`, behind an explicit "If X, read `references/.md`" trigger — the literal conditional form, never a generic pointer. Write the real filename in the skill under audit; the angle brackets are a placeholder here, and a literal `references/file.md` in a body is an ERROR -from the ADR-0020 gate because no such file exists on disk. +from the gate because no such file exists on disk. **A dispatch table satisfies this requirement on its own.** A table row already pairs a condition with a target, which is exactly what the literal form encodes; restating each row underneath as a @@ -60,7 +60,7 @@ Do not conflate these, and do not report them as one finding. | Gate | SUGGESTION | FAIL | Counts | |---|---|---|---| -| Body budget (house, ADR-0020) | 600 words | 900 words | the **body only** — everything after the frontmatter's closing `---` | +| Body budget (house) | 600 words | 900 words | the **body only** — everything after the frontmatter's closing `---` | | Spec conformance (agentskills.io) | — | 2,770 words / 500 lines | the **whole file**, frontmatter included | The 2,770-word ceiling is a token-conformance backstop calibrated to the densest prose in the @@ -134,7 +134,7 @@ Constraints: Worked negative example — **`git-commits` v0.1.2 at commit `5e23250`, a fixed pre-retrofit snapshot, not the current file.** The live skill is v0.1.3 and matches none of the citations below; -they are quoted as they stood before the ADR-0020 retrofit, and are not to be refreshed against +they are quoted as they stood in that snapshot, and are not to be refreshed against `HEAD`. The snapshot is reachable only from a checkout of the authoring repo — an installed plugin cache holds no git history and no such path — so read the citations below as quoted rather than going to look for the file. From a checkout: diff --git a/plugins/kyberforge/skills/skill-audit/references/description-quality.md b/plugins/kyberforge/skills/skill-audit/references/description-quality.md index ef027f8..08b5a7c 100644 --- a/plugins/kyberforge/skills/skill-audit/references/description-quality.md +++ b/plugins/kyberforge/skills/skill-audit/references/description-quality.md @@ -7,7 +7,7 @@ source_keys: # Description Quality Reference Upstream source: agentskills.io — optimizing-descriptions, specification. -House contract: ADR-0020, the context budget. The house contract is narrower than the spec +House contract: the context budget. The house contract is narrower than the spec rather than a reinterpretation of it: where both speak, both must be satisfied. ## Why the description is the expensive part diff --git a/plugins/kyberforge/skills/skill-audit/references/file-structure.md b/plugins/kyberforge/skills/skill-audit/references/file-structure.md index 33c3531..aaaeb84 100644 --- a/plugins/kyberforge/skills/skill-audit/references/file-structure.md +++ b/plugins/kyberforge/skills/skill-audit/references/file-structure.md @@ -19,7 +19,6 @@ knows to look at. Flag any other directory as a FAIL. `test_*.sh`) there are a FAIL — they belong in `tests/`. - No non-spec files at the skill root: no `META.md`, no stray config outside the four directories. - An optional directory that exists must hold real content, not an unfilled placeholder README. -- `README.md` is present and describes the skill and its files accurately. ## Cross-plugin path references @@ -41,7 +40,7 @@ Resolve before flagging, twice over: **Referring to another skill's file.** There is one sanctioned spelling, and it is possessive: `skill-audit's references/validation-scripts.md`. Write the skill by name and let the reader resolve it — do not spell the repo path. The full path is the thing this section forbids, and -`references/validation-scripts.md` on its own is a hard ERROR from the ADR-0020 gate, which +`references/validation-scripts.md` on its own is a hard ERROR from the gate, which requires an unqualified `references/` pointer to exist in the skill's OWN directory. The possessive form is the only spelling both rules accept; the gate recognises it and skips the on-disk check. Flag any other spelling of a cross-skill reference. @@ -59,17 +58,12 @@ Two directories are exempt, and the exemptions are structural rather than discre ## Internal consistency -The skill has to agree with itself. Three checks: +The skill has to agree with itself. Two checks: - `SKILL.md`'s steps match what the scripts actually do — the arguments, the exit codes, and the output shape it tells the agent to expect. -- `README.md`'s file table lists every file that exists, with no missing rows and no stale rows for - files since deleted. -- Placeholder READMEs inside `scripts/`, `references/` and `assets/` say the same thing about each +- Placeholder READMEs inside `scripts/`, `tests/` and `assets/` say the same thing about each directory that `SKILL.md` does. -A stale README row is the most common finding here and the easiest to miss from inside an -authoring pass, because the author knows what was intended and reads it into the gap. - The FAIL and SUGGESTION criteria for this dimension live in `references/finding-criteria.md`, which Step 3 loads on every run. diff --git a/plugins/kyberforge/skills/skill-audit/references/finding-criteria.md b/plugins/kyberforge/skills/skill-audit/references/finding-criteria.md index 05eb85d..955fd1f 100644 --- a/plugins/kyberforge/skills/skill-audit/references/finding-criteria.md +++ b/plugins/kyberforge/skills/skill-audit/references/finding-criteria.md @@ -111,13 +111,11 @@ Flag as FAIL if: - A path that resolves outside the skill directory appears outside the two exempt locations, in prose rather than in a fenced example - `tests/` exists but `tests/README.md` is missing or does not document its repo-level dependency -- `README.md` is absent, or its file table has a missing or stale row - `SKILL.md` describes a script invocation the script does not accept Flag as SUGGESTION if: - An optional directory exists but holds only a placeholder README -- `README.md` is accurate but describes a file's purpose more thinly than `SKILL.md` does ## formatting and scripts — `references/formatting-and-scripts.md` diff --git a/plugins/kyberforge/skills/skill-audit/references/patterns.md b/plugins/kyberforge/skills/skill-audit/references/patterns.md index 80cffa1..bf8337d 100644 --- a/plugins/kyberforge/skills/skill-audit/references/patterns.md +++ b/plugins/kyberforge/skills/skill-audit/references/patterns.md @@ -40,7 +40,7 @@ If the API returns a non-200 status, read `references/api-errors.md`. ``` That block is fenced because the filename in it is illustrative — an unfenced `references/` pointer -in a `SKILL.md` body must resolve on disk or the ADR-0020 gate reports a hard ERROR. The generic +in a `SKILL.md` body must resolve on disk or the gate reports a hard ERROR. The generic form — pointing at the directory and hoping — defeats progressive disclosure, because the agent either loads everything or loads nothing. `Kyberforge.PaddingPhrase` catches the common generic phrasing deterministically; other malformed diff --git a/plugins/kyberforge/skills/skill-audit/references/validation-scripts.md b/plugins/kyberforge/skills/skill-audit/references/validation-scripts.md index 24b138f..f75202d 100644 --- a/plugins/kyberforge/skills/skill-audit/references/validation-scripts.md +++ b/plugins/kyberforge/skills/skill-audit/references/validation-scripts.md @@ -21,7 +21,7 @@ have checked, and the Step 4 coverage line then names a dimension nothing actual ## Manual structural fallback `validate.sh` needs `python3` **and** PyYAML, and refuses to start without either — the description -value has to be measured after YAML folding is resolved, so skipping the ADR-0020 gates would be a +value has to be measured after YAML folding is resolved, so skipping these gates would be a vacuous pass rather than a partial one. The two are checked separately, so the message already names the right one — report it verbatim rather than diagnosing further: @@ -40,14 +40,14 @@ by hand and file the results under `### Structure` exactly as the script's outpu session, so a skill without one can never be routed to. - **Description length**, measured on the folded YAML value with newlines collapsed to single spaces — not on the raw block scalar, which counts indentation. 250 characters SUGGESTION, 400 - FAIL (ADR-0020), 1,024 FAIL (agentskills.io spec). + FAIL (house), 1,024 FAIL (agentskills.io spec). - **Body length**, counting everything after the frontmatter's closing `---`. 600 words - SUGGESTION, 900 FAIL (ADR-0020). + SUGGESTION, 900 FAIL (house). - **Whole-file ceilings**, counting the file including frontmatter: 500 lines FAIL, 2,770 words FAIL (agentskills.io spec). These are a different measurement from the two above — report them as separate findings, never merged. - **A boundary clause is present** — either the prose form (`do not` / `instead` / `rather than` / - `not for`) or ADR-0020's compressed `Not -> ` arrow. **SUGGESTION**, not FAIL: + `not for`) or the compressed `Not -> ` arrow. **SUGGESTION**, not FAIL: the absence is deterministic, but whether this skill warrants one is the auditor's call. - **Boundary targets resolve** — **FAIL** on a name that resolves to nothing. See the section below; resolving these by hand is the one item on this list with a procedure of its own. diff --git a/plugins/kyberforge/skills/skill-author/README.md b/plugins/kyberforge/skills/skill-author/README.md deleted file mode 100644 index 53e49d7..0000000 --- a/plugins/kyberforge/skills/skill-author/README.md +++ /dev/null @@ -1,74 +0,0 @@ -# skill-author - -Author and refine skills conforming to the [agentskills.io](https://agentskills.io) specification — create new skills from scratch or apply improvement signals to existing ones. - -## What it does - -Routes to one of two flows based on context: if no skill directory exists at the target path, it scaffolds the directory from annotated templates, fills in `SKILL.md` and supporting files, and validates the result. If an existing skill directory and improvement signals are both present, it groups those signals by root cause and applies targeted edits, then re-validates. In both flows, bumps the skill's `metadata.version` — minor for create, patch for improve — which every skill carries (ADR-0022). - -`SKILL.md` itself carries only the dispatch table, the invocation-axis decision, the contract gates and the shared close; each flow lives in its own self-contained reference file, per ADR-0020. - -## The contract it teaches - -Authored skills are held to the ADR-0020 context budget. A description carries a trigger clause, at most one capability clause, and a boundary clause of the form `Not -> ` whose target must resolve to a real skill or agent — 250 characters target, 400 hard ceiling. A body carries the decision procedure only — 600 words target, 900 hard ceiling, counting the body alone, which is a separate measurement from the 2,770-word / 500-line whole-file spec backstop. Skills with two or more mutually exclusive flows must dispatch. `references/contract.md` holds the full rules; `assets/templates/SKILL.md` encodes them as a fill-in skeleton. - -Before a description is written, the skill asks whether the target is model-invoked or hand-invoked. A hand-invoked skill sets `disable-model-invocation: true` and carries one plain human-facing sentence with no trigger list. - -## Before you start - -- Run `/grill-me` to resolve design decisions before creating a new skill -- Collect domain research, examples, and constraints -- Know the skill name (kebab-case) and destination path - -## Placement - -`scripts/new-skill.sh` resolves the mode automatically by walking up from the given path — see `references/create.md` Step 1 for the full algorithm. - -| Mode | Path | Chosen when | -|------|------|-------------| -| Standalone | `//` | No `apm.yml` with a top-level `type:` field is found walking up from ``, before hitting `.git` or the filesystem root | -| Package (APM) | `/.apm/skills//` | A type-bearing `apm.yml` is found at or above `` — `` just needs to be somewhere inside the package | - -If the destination resolves inside an APM package, read `references/deployment-modes.md` — self-containment rules apply to `apm compile` output the same way they applied to plugin cache isolation. - -## Usage - -``` -/skill-author -``` - -## Files - -| File | Purpose | -|------|---------| -| `README.md` | Human-readable overview of the skill and its files | -| `SKILL.md` | Skill instructions for agents | -| `scripts/new-skill.sh` | Walks up from the given path to resolve package vs standalone mode, then copies annotated templates to the resolved destination | -| `references/create.md` | The create flow end to end — prerequisites, package-intent gate, scaffold, frontmatter, scripts, references, sources (loaded on demand) | -| `references/improve.md` | The improve flow end to end — signal verification, root-cause grouping, announcement, edits (loaded on demand) | -| `references/contract.md` | The ADR-0020 description and body contract, the Gotchas constraint, the two size gates, body patterns, and org-policy embedding (loaded on demand) | -| `references/retrofit.md` | Bringing a pre-ADR-0020 skill into contract — ordered cut procedure, the mutually-exclusive-flows test, reference-file conventions, the collateral checklist, and a worked description retrofit (loaded from the improve flow when a budget is exceeded) | -| `references/deployment-modes.md` | APM package vs standalone differences and self-containment/cache-isolation rules (loaded on demand) | -| `references/scripts.md` | Package runners, inline dependency patterns, and full script contract (loaded on demand) | -| `references/sources.md` | Upstream research sources and which skill files each contributed to | -| `assets/templates/SKILL.md` | Annotated SKILL.md template — emits an ADR-0020-compliant description and body skeleton | -| `assets/templates/README.md` | Annotated README template for the new skill | -| `assets/templates/scripts/README.md` | Placeholder for bundled scripts | -| `assets/templates/references/README.md` | Placeholder for reference docs | -| `assets/templates/references/sources.md` | Sources provenance template for new skills | -| `assets/templates/assets/README.md` | Placeholder for static assets | -| `assets/templates/tests/README.md` | Placeholder for test files | -| `tests/new-skill.bats` | (source-only) Bats test suite for `scripts/new-skill.sh` | -| `tests/README.md` | (source-only) Setup instructions for bats-support and bats-assert test dependencies | - -Rows marked **(source-only)** exist in the authoring source (`.apm/skills/skill-author/`) but are -not present in an installed plugin: `scripts/sync-plugin-content.sh` strips -`//tests` when it generates the flat mirror, because these are dev-time fixtures no -plugin host needs to discover (ADR-0017). Run them from a repo checkout, not from an install. The -`assets/templates/tests/README.md` row above is **not** source-only — the exclusion is depth-scoped -to `//tests`, so the scaffolding template tree ships intact, which -`scripts/new-skill.sh` depends on at runtime. - -## Spec reference - -[agentskills.io specification](https://agentskills.io/specification.md) diff --git a/plugins/kyberforge/skills/skill-author/SKILL.md b/plugins/kyberforge/skills/skill-author/SKILL.md index 80ecb37..ccde99c 100644 --- a/plugins/kyberforge/skills/skill-author/SKILL.md +++ b/plugins/kyberforge/skills/skill-author/SKILL.md @@ -6,7 +6,7 @@ description: > Not read-only review -> `skill-audit`. Not agent files -> `agent-author`. allowed-tools: Bash Read Write Edit metadata: - version: "1.0.1" + version: "1.0.2" category: factory source_keys: - agentskills-home diff --git a/plugins/kyberforge/skills/skill-author/assets/templates/README.md b/plugins/kyberforge/skills/skill-author/assets/templates/README.md deleted file mode 100644 index 6339f0b..0000000 --- a/plugins/kyberforge/skills/skill-author/assets/templates/README.md +++ /dev/null @@ -1,51 +0,0 @@ -# SKILL_NAME - - - -## What it does - - - -## Before you start - - - -## Usage - -``` -/SKILL_NAME -``` - - - - - -## Files - - - -| File | Purpose | -|------|---------| -| `SKILL.md` | Skill instructions for agents | -| `scripts/your-script.sh` | FILL IN: what this script does | -| `references/your-doc.md` | FILL IN: what this reference covers | -| `assets/your-asset.json` | FILL IN: what this asset is | -| `tests/your-test.bats` | FILL IN: what this test covers | - - diff --git a/plugins/kyberforge/skills/skill-author/assets/templates/references/README.md b/plugins/kyberforge/skills/skill-author/assets/templates/references/README.md deleted file mode 100644 index 25a8d59..0000000 --- a/plugins/kyberforge/skills/skill-author/assets/templates/references/README.md +++ /dev/null @@ -1,39 +0,0 @@ -# references/ - -Additional documentation agents load on demand. Files here extend SKILL.md -without bloating its core context. - -## When to add a reference file - -The SKILL.md body carries the decision procedure only. Everything else lives -here: lookup tables, spec restatements, output schemas, templates, example -blocks, rationale prose, and anything only one branch reaches. - -Two triggers make a reference file mandatory rather than optional: - -- The body is over its 600-word target (900 is a hard failure), counting the - body only — everything after the frontmatter's closing `---`. -- The skill has two or more mutually exclusive flows. The body then keeps only - a dispatch table plus the gates common to every branch, and each flow gets - its own self-contained file here (e.g. `create.md`, `improve.md`). - -## How to reference from SKILL.md - -Load conditionally — tell the agent exactly when to read each file: - -```markdown -If the API returns a non-200 status, read `references/api-errors.md`. -``` - -Avoid generic "see references/ for details" — the agent loads context on -demand, so give it a precise trigger condition. - -## File conventions - -- One topic per file — focused files mean less unnecessary context loaded -- Kebab-case filenames (e.g. `api-errors.md`, `output-formats.md`) -- Keep files under 200 lines where possible - -## If no reference files are needed - -Delete this README and the `references/` directory entirely. diff --git a/plugins/kyberforge/skills/skill-author/references/contract.md b/plugins/kyberforge/skills/skill-author/references/contract.md index e6795bf..ec1d4c5 100644 --- a/plugins/kyberforge/skills/skill-author/references/contract.md +++ b/plugins/kyberforge/skills/skill-author/references/contract.md @@ -7,7 +7,7 @@ source_keys: # The description and body contract -House contract, set by ADR-0020. Every rule here is enforced by `/skill-audit` — +House contract. Every rule here is enforced by `/skill-audit` — `scripts/validate.sh` for the counts and the boundary targets, the bundled Vale styles for the prose patterns, and its reference files for the judgment calls. diff --git a/plugins/kyberforge/skills/skill-author/references/create.md b/plugins/kyberforge/skills/skill-author/references/create.md index 984a45e..474510e 100644 --- a/plugins/kyberforge/skills/skill-author/references/create.md +++ b/plugins/kyberforge/skills/skill-author/references/create.md @@ -84,7 +84,7 @@ already covers the new skill. Use Read/Edit directly on `apm.yml`; this is not p ## Step 3 — Fill in SKILL.md Open the new skill's `SKILL.md` (the path Step 1 printed) and replace every `FILL IN:` -placeholder. The scaffold template carries the ADR-0020 body skeleton and the two frontmatter +placeholder. The scaffold template carries the body skeleton and the two frontmatter fields that cannot be left as placeholders — `name`, substituted by the script, and `metadata.version`, seeded live at `"0.1.0"` — so fill the template in rather than restructuring it. diff --git a/plugins/kyberforge/skills/skill-author/references/improve.md b/plugins/kyberforge/skills/skill-author/references/improve.md index feda975..4df84d2 100644 --- a/plugins/kyberforge/skills/skill-author/references/improve.md +++ b/plugins/kyberforge/skills/skill-author/references/improve.md @@ -71,23 +71,16 @@ outperforms an exhaustive one. writing a rule in all caps (ALWAYS/NEVER), reframe it: explain why the behavior matters so the agent can apply judgment in edge cases. -**Retrofit before extending.** Any edit to a skill that predates ADR-0020 has to bring it into the -contract first — the gates are hot and carry no baseline file, so a one-line fix to a +**Retrofit before extending.** Any edit to a skill that does not meet the contract has to bring it +into compliance first — the gates are hot and carry no baseline file, so a one-line fix to a non-compliant skill cannot be committed until the description and body meet `references/contract.md`. Treat that retrofit as part of the same change, not a follow-up. -If the skill's description exceeds 250 characters, or its body-only word count exceeds 600, read -`references/retrofit.md` before editing. It carries the ordered cut procedure, the -mutually-exclusive-flows test, the reference-file conventions this flow needs, the collateral -checklist for `README.md` and `references/sources.md`, and a worked description retrofit. Do not -improvise the cuts — four dry runs invented six to ten different answers to the same questions. - If a signal points to a script or reference file, edit that file directly rather than adding a workaround in SKILL.md. **A skill carrying no `metadata.version` is seeded at `"1.0.0"`, not bumped** — `SKILL.md` Step 4's patch bump presumes a version to bump, and ADR-0022 reserves `"0.1.0"` for a newly created skill. -`references/retrofit.md` carries the reasoning. **Check for regressions before handing back.** `SKILL.md` Step 4 tells you to resolve every FAIL, which says nothing about a check that passed *before* these edits and no longer does. Compare the diff --git a/plugins/kyberforge/skills/skill-author/references/retrofit.md b/plugins/kyberforge/skills/skill-author/references/retrofit.md deleted file mode 100644 index 0755773..0000000 --- a/plugins/kyberforge/skills/skill-author/references/retrofit.md +++ /dev/null @@ -1,197 +0,0 @@ ---- -source_keys: - - agentskills-best-practices - - agentskills-optimizing-descriptions ---- - -# Retrofitting a skill to the ADR-0020 contract - -Read this when `references/improve.md` Step 4 sends you here: the skill you are editing is over -the description or body budget and has to come into contract before any other change can be -committed. The gates are hot and carry no baseline file, so a one-line fix to a non-compliant -skill is blocked until this is done. - -Measure first. Do not guess which gate fired: run `/skill-audit` on the directory and read its -`### Structure` dimension, which reports the description characters and the **body-only** word -count separately from the whole-file spec backstop. Retrofit against the number that actually -fired — a skill can sit a thousand words inside the whole-file backstop while failing the body -budget. - -**Validate in place.** Audit the skill's real directory inside its package. Never audit a copy in a -scratch directory, and never move a skill out to work on it: the boundary-target universe is built -by walking up *from the file being checked*, so a copy with no authoring root above it resolves -against nothing and the check declines rather than running — - -```text -INFO boundary-target resolution DID NOT RUN — no skill universe could be determined for -this path ... Unchecked target(s): totally-fake-target -``` - -The run still exits 0, so that line reads as a pass and is not one. Treat `DID NOT RUN` as **not -checked**, always. A retrofit signed off on a scratch copy carries an unverified boundary target -into the corpus, which is precisely the failure this gate exists to catch. - -## Cut in this order - -Work the list top down and stop as soon as the gate clears. The order is by ratio of tokens -removed to behaviour lost — inverting it is how a retrofit ends up deleting the one instruction -the skill existed to carry. - -1. **Gotchas that paraphrase a step in the body below.** Zero information, and already a FAIL on - its own. Delete the Gotcha, keep the step. -2. **Spec restatements** — text that repeats a published specification, a tool's `--help`, or a - ceiling the validator already enforces. The agent gets this right without it. Delete, or move - the table to `references/` if a flow genuinely needs to look it up. -3. **Capability enumeration** — in a description, the feature list after the trigger clause; in a - body, the paragraph that recites what the skill can do. One capability clause survives in the - description; the rest belongs in `README.md`. -4. **Per-flow prose** — anything only one branch of the procedure ever reaches. This is the - largest single win in most bodies, and it is a *move*, not a delete: each flow gets its own - self-contained `references/` file, wired from a dispatch table. - -If the body is still over after all four, the skill is doing two jobs. Split it, and say so -rather than compressing prose until it stops being readable. - -## What "mutually exclusive flows" means - -Two or more flows that a single invocation cannot both take. The three-way test, copied verbatim -from the body-discipline rubric `/skill-audit` judges against — nothing to load, it is quoted in -full here: - -> separate subcommands, separate input types, separate lifecycle stages - -Any one of the three is enough. Two flows that differ only in a parameter value are one flow. -At two or more mutually exclusive flows a dispatch table is **mandatory** regardless of word -count, because every invocation otherwise pays for every branch it did not take. - -## Reference-file conventions - -The create flow owns these rules, and this flow is forbidden from reading `references/create.md`, -so what a retrofit needs is restated here: - -- **One topic per file.** A file mixing two concerns gets loaded for one of them and spends the - caller's context on the other. -- **Kebab-case filenames**, named after the topic rather than the flow that reads it — - `body-discipline.md`, not `step-3.md`. -- **Wire every file with the literal conditional form** ``If , read - `references/.md` ``. A generic pointer ("see `references/` for details") is a Vale error. -- **Two hops from `SKILL.md`, never three.** A flow file may route on to a shared contract file; - a file reachable only through two intermediates is rarely loaded when it is needed. -- **`source_keys` frontmatter.** If the content you are moving drew on a research source, the new - file needs top-level `source_keys:` frontmatter listing those slugs, and every slug must already - exist as an `## ` heading in `references/sources.md`. Moving sourced content out of - `SKILL.md` without carrying its slugs across breaks the provenance chain, and `/skill-audit` - reports the new file as an INFO with no `source_keys`. - -## Collateral is mandatory, not optional - -Moving content out of a `SKILL.md` leaves three files describing a structure that no longer -exists. `/skill-audit`'s provenance check exits clean on all three of these, so nothing catches -them for you. After every retrofit that adds, removes or renames a file: - -- [ ] **`README.md` file table** — a row for every new `references/` file, and no row left for a - file that is gone. Say what triggers the load, not just what the file contains. -- [ ] **`references/README.md`**, where the skill has one — same update, same reason. -- [ ] **`references/sources.md` → `Contributing files`** — add the new file to every slug whose - content moved into it, and remove any file the retrofit deleted. This is the one that gets - missed: `sources.md` keeps citing sections of `SKILL.md` that no longer exist, the - provenance check still exits 0, and the stale claim survives review. -- [ ] **Reachability of every relocated gate.** For each Gotcha or gate the retrofit moved out of - the body, list the flows that need it and confirm each one reaches the surviving copy. A gate - that lands in a single flow file is invisible to every other branch, and no gate detects - that: `/skill-audit` reads whichever file it was handed, and the word counts improve either - way. Where more than one flow needs it, the copy belongs in the body's common-gates section, - not in a flow file. Grep the skill for the gate's key term and check every branch that hits - zero. -- [ ] Re-run `/skill-audit` and confirm its `### Provenance` dimension does not report the new - file as missing `source_keys`. - -## Compression must not add authority the source text didn't have - -This one is **not** part of the checklist above, and deliberately so: it fires on a wording change -with no file change at all, so a retrofit that adds and removes nothing still owes it. - -The `sources.md` bullet above is about an entry going *stale* — Contributing files left uncited -after content moves. This is a distinct failure: a compression or rewrite pass that upgrades an -honest hedge in a Description into an unsupported confident claim, without the underlying source -having changed at all — "no forge-specific content drawn directly from it beyond that" quietly -becoming "Grounds Step 2's dispatch table." - -`/skill-audit`'s provenance script does now notice this class: it diffs each slug's `Description` -and `Contributing files` text against a base ref and raises an **INFO** when the wording changed. -That is a prompt, not a verdict — it reports only *that* the claim moved, never whether the new -claim is true, because a bash script can verify an entry is internally consistent and nothing more. -Answering it is this flow's job: if a retrofit strengthens or otherwise changes the wording of a -provenance claim, re-read the upstream research doc first and confirm the stronger wording is -actually still true before committing it. - -## Versioning a retrofitted skill - -`SKILL.md` Step 4 says to bump the **patch** version on improve, which presumes there is a version -to bump. A pre-ADR-0020 skill often carries none — `metadata.version` only became mandatory under -ADR-0022, and this flow is exactly where those skills surface. - -A skill with no `metadata.version` is **seeded at `"1.0.0"`, not bumped**. `"0.1.0"` is reserved -for a skill created new by the create flow: it means "created and never yet revised", which -understates a skill that has been through retrofit and audit passes without tracking a version. -Add the field in this retrofit — the `skill-frontmatter` pre-commit hook blocks the commit without -it. - -## Worked example — a description retrofit - -`gitea-issues` before, 827 characters, the single most common shape in the corpus: - -```text -Use when reading or writing Gitea issues: listing repo issues, getting a single issue's details/ -comments/labels, creating an issue, updating its state, adding or editing comments, applying -labels via issue_write, or searching issues/PRs across repositories. Triggers on "create an -issue", "what issues are open", "get issue #N", "close issue #N", "comment on issue #N", "search -issues for X" — even when the user doesn't say "Gitea" explicitly. Composes gitea-labels- -milestones for all label inference/resolution and milestone lookup — do not use this skill to -manage label or milestone definitions themselves (create/edit/delete a label, create/close a -milestone), that's gitea-labels-milestones directly. Do not use for pull requests (use gitea-prs) -or for local git branch/commit work (use gitea-branches or git-branches). -``` - -After, the 290 characters that shipped: - -```text -Use when reading or writing Gitea issues — "create an issue", "what issues are open", "close -issue #N", "comment on issue #N", "search issues for X" — even when the user does not say -"Gitea". Not pull requests -> `gitea-prs`. Not label or milestone definitions -> -`gitea-labels-milestones`. -``` - -The retrofit kept the quoted-phrasing register and dropped the verb list, not the other way round. -Either register is admissible — what is banned is carrying both. Choose whichever routes better -for the skill in hand; here the quoted user phrasings do, because they are how people actually ask. - -What came out, and why: - -| Removed | Why | -|---|---| -| The second trigger register — `Triggers on "create an issue", "what issues are open", …` | The same triggers restated as quoted user phrasings. Two registers of one trigger list is a FAIL, not a suggestion. | -| `applying labels via issue_write` | Implementation detail. The router does not choose a skill by which MCP call it makes. | -| `Composes gitea-labels-milestones for all label inference/resolution and milestone lookup` | A composition note. It changes no routing decision and belongs in `README.md`. | -| The parenthetical `(create/edit/delete a label, create/close a milestone)` | Capability enumeration inside a boundary clause. The boundary needs the target, not its feature list. | -| The `gitea-branches` / `git-branches` boundary | Dropped entirely. Neither was ever going to win an issue request, so the clause defended against nothing — an invented boundary costs characters and buys no routing accuracy. | -| `Do not use for pull requests (use gitea-prs)` prose form | Kept, but rewritten as `Not pull requests -> \`gitea-prs\`.` The rewrite buys characters, one uniform shape for the router, **and** a stricter check: an unresolved arrow target is a blocking ERROR, while an unresolved prose target is only a SUGGESTION unless another target in the same sentence resolves. The prose form does not dangle as loudly. | - -What stayed: one trigger clause, one capability clause, the indirect trigger (genuinely warranted -here — people say "create an issue", not "create a Gitea issue"), and the boundary clauses. - -## Two rules the gates enforce but the prose does not spell out - -**Boundary clauses may be plural.** Write one per genuine near-miss — the example above carries -two, because two different skills could each steal activations. "A boundary clause" in the -contract means *at least one*, not *exactly one*. What is banned is a boundary clause invented for -a skill that was never going to compete, not a second real one. - -**Never let a hyphenated routing target wrap across lines in a folded `>` scalar.** YAML folding -replaces the newline with a space, so `gitea-labels-` at the end of one line and `milestones` at -the start of the next fold into `gitea-labels- milestones`. The gate then reads the target as -`gitea-labels`, finds no such skill, and reports a dangling boundary target. This is not -hypothetical — it is how `gitea-labels-milestones` broke (issue #100). It is fixed: the corpus -carries no dangling target today, and the repo's test suite pins that set as empty, so a -reintroduction fails the suite rather than joining a backlog. Reflow the line so the whole name -sits on one of them. The same applies to any backticked skill or agent name in a description. diff --git a/plugins/kyberforge/skills/skill-author/references/sources.md b/plugins/kyberforge/skills/skill-author/references/sources.md index 54b9f6d..2d169d7 100644 --- a/plugins/kyberforge/skills/skill-author/references/sources.md +++ b/plugins/kyberforge/skills/skill-author/references/sources.md @@ -34,7 +34,7 @@ source_keys: - **URL:** https://agentskills.io/skill-creation/best-practices.md - **Research doc:** plugins/kyberforge/docs/research/docs/agentskillsio/sources.md - **Description:** Best practices for skill creators — starting from real expertise, spending context wisely, calibrating control, instruction patterns (gotchas, templates, checklists, validation loops) -- **Contributing files:** SKILL.md, references/create.md, references/improve.md, references/contract.md, references/retrofit.md +- **Contributing files:** SKILL.md, references/create.md, references/improve.md, references/contract.md - **Status:** `extracted` ## agentskills-optimizing-descriptions @@ -42,7 +42,7 @@ source_keys: - **URL:** https://agentskills.io/skill-creation/optimizing-descriptions.md - **Research doc:** plugins/kyberforge/docs/research/docs/agentskillsio/sources.md - **Description:** How to systematically test and improve skill descriptions for triggering accuracy — eval queries, trigger rate testing, train/validation splits, optimization loop -- **Contributing files:** SKILL.md, references/improve.md, references/contract.md, references/retrofit.md +- **Contributing files:** SKILL.md, references/improve.md, references/contract.md - **Status:** `extracted` ## agentskills-evaluating-skills diff --git a/plugins/kyberforge/skills/skill-author/scripts/new-skill.sh b/plugins/kyberforge/skills/skill-author/scripts/new-skill.sh index 5e1375f..2698f1d 100755 --- a/plugins/kyberforge/skills/skill-author/scripts/new-skill.sh +++ b/plugins/kyberforge/skills/skill-author/scripts/new-skill.sh @@ -165,7 +165,6 @@ cp -r "$TEMPLATES_DIR" "$TARGET" # Set skill name in templates sed -i "s/SKILL_NAME/$SKILL_NAME/g" "$TARGET/SKILL.md" -sed -i "s/SKILL_NAME/$SKILL_NAME/g" "$TARGET/README.md" sed -i "s/SKILL_NAME/$SKILL_NAME/g" "$TARGET/tests/README.md" if [[ "$MODE" == "package" ]]; then diff --git a/plugins/lint/.apm/skills/vale-config/README.md b/plugins/lint/.apm/skills/vale-config/README.md deleted file mode 100644 index b49138a..0000000 --- a/plugins/lint/.apm/skills/vale-config/README.md +++ /dev/null @@ -1,23 +0,0 @@ -# vale-config - -Install and configure Vale, the prose/style linter — `.vale.ini`, `StylesPath`, built-in/third-party/custom styles, and activation via `BasedOnStyles`. - -## What it does - -Covers the setup side of Vale: getting a project from no config to a working `.vale.ini` where `vale sync` runs clean and every declared style is actually activated for the right files. Does not run Vale or interpret its output — see `vale-run` for that. - -## Usage - -``` -/vale-config -``` - -Describe what you want configured: initial setup, adding a third-party style package, or a custom rule. The skill covers install, `StylesPath` layout, `.vale.ini` structure, and `BasedOnStyles` activation. - -## Files - -| File | Purpose | -|------|---------| -| `SKILL.md` | Skill instructions for agents | -| `references/configuration-reference.md` | Full `.vale.ini` fields, rule-header fields, and frontmatter-scope behaviour | -| `references/sources.md` | Research sources backing the Vale configuration guidance | diff --git a/plugins/lint/.apm/skills/vale-run/README.md b/plugins/lint/.apm/skills/vale-run/README.md deleted file mode 100644 index 459c68a..0000000 --- a/plugins/lint/.apm/skills/vale-run/README.md +++ /dev/null @@ -1,23 +0,0 @@ -# vale-run - -Run Vale (a prose/style linter) against an already-configured project and interpret its results. - -## What it does - -This skill covers invoking the `vale` CLI against files or directories, choosing an output format (human-readable CLI, `line`, or machine-parseable `JSON`), filtering by severity via `--minAlertLevel`, and handling exit codes in scripts and CI. It also covers resolving common runtime issues: false positives, format-specific inline suppression, and CI failures caused solely by Vale's non-zero exit code. It assumes the project already has a working `.vale.ini` and installed styles — setting those up is the sibling `vale-config` skill's job. - -## Usage - -``` -/vale-run -``` - -Describe what you want to lint and how (human-readable output, CI/JSON output, filtered by severity). The skill will pick the right flags and, if results include false positives, walk through the narrowest applicable fix. - -## Files - -| File | Purpose | -|------|---------| -| `SKILL.md` | Core invocation, key flags, output format guidance, false-positive triage order | -| `references/troubleshooting.md` | Load when a rule appears not to apply, when writing inline suppression or spelling-ignore syntax, or when wiring Vale into pre-commit: resolved-config diagnostic (`vale ls-config`), format-specific suppression markup, rule-specific disabling, spelling ignore lists, pre-commit integration, CI edge cases | -| `references/sources.md` | Research provenance | diff --git a/plugins/lint/skills/vale-config/README.md b/plugins/lint/skills/vale-config/README.md deleted file mode 100644 index b49138a..0000000 --- a/plugins/lint/skills/vale-config/README.md +++ /dev/null @@ -1,23 +0,0 @@ -# vale-config - -Install and configure Vale, the prose/style linter — `.vale.ini`, `StylesPath`, built-in/third-party/custom styles, and activation via `BasedOnStyles`. - -## What it does - -Covers the setup side of Vale: getting a project from no config to a working `.vale.ini` where `vale sync` runs clean and every declared style is actually activated for the right files. Does not run Vale or interpret its output — see `vale-run` for that. - -## Usage - -``` -/vale-config -``` - -Describe what you want configured: initial setup, adding a third-party style package, or a custom rule. The skill covers install, `StylesPath` layout, `.vale.ini` structure, and `BasedOnStyles` activation. - -## Files - -| File | Purpose | -|------|---------| -| `SKILL.md` | Skill instructions for agents | -| `references/configuration-reference.md` | Full `.vale.ini` fields, rule-header fields, and frontmatter-scope behaviour | -| `references/sources.md` | Research sources backing the Vale configuration guidance | diff --git a/plugins/lint/skills/vale-run/README.md b/plugins/lint/skills/vale-run/README.md deleted file mode 100644 index 459c68a..0000000 --- a/plugins/lint/skills/vale-run/README.md +++ /dev/null @@ -1,23 +0,0 @@ -# vale-run - -Run Vale (a prose/style linter) against an already-configured project and interpret its results. - -## What it does - -This skill covers invoking the `vale` CLI against files or directories, choosing an output format (human-readable CLI, `line`, or machine-parseable `JSON`), filtering by severity via `--minAlertLevel`, and handling exit codes in scripts and CI. It also covers resolving common runtime issues: false positives, format-specific inline suppression, and CI failures caused solely by Vale's non-zero exit code. It assumes the project already has a working `.vale.ini` and installed styles — setting those up is the sibling `vale-config` skill's job. - -## Usage - -``` -/vale-run -``` - -Describe what you want to lint and how (human-readable output, CI/JSON output, filtered by severity). The skill will pick the right flags and, if results include false positives, walk through the narrowest applicable fix. - -## Files - -| File | Purpose | -|------|---------| -| `SKILL.md` | Core invocation, key flags, output format guidance, false-positive triage order | -| `references/troubleshooting.md` | Load when a rule appears not to apply, when writing inline suppression or spelling-ignore syntax, or when wiring Vale into pre-commit: resolved-config diagnostic (`vale ls-config`), format-specific suppression markup, rule-specific disabling, spelling ignore lists, pre-commit integration, CI edge cases | -| `references/sources.md` | Research provenance | -- 2.43.0 From 629320b8fda4aa52ab8ce61ac779d2f1e0d2a51f Mon Sep 17 00:00:00 2001 From: Defame1297 Date: Sat, 12 Sep 2026 18:38:26 +0000 Subject: [PATCH 03/84] docs: trim stale entries from LESSONS.md Finding 30 of the simplification audit. 41 entries had grown to 255 lines; 10 described a write-skill / write-eval bootstrap workflow whose skills no longer exist in this repo, and the longest entries ran 200-550 words of incident narrative for a one-line lesson. Deleted the 10 stale entries. Kept 3 same-dated ones (RLHF defaults, secrets-rule gap, HITL gap) whose content is unrelated to the defunct workflow and still applies. Removed one open-work entry ("neither part landed", about CONTEXT.md not being @import-ed at session start) rather than filing it as a tracker issue -- not turned into an issue, just dropped; the audit's own commit history and this repo's session transcript carry the detail if it's wanted later. Compressed the remaining 30 entries to roughly 60-90 words each. 255 -> 131 lines, 41 -> 30 entries. Refs: SIMPLIFICATION-AUDIT.md finding 30 Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_01YR2CjVumUbEGWcMikcoXBD --- LESSONS.md | 190 ++++++++++------------------------------------------- 1 file changed, 33 insertions(+), 157 deletions(-) diff --git a/LESSONS.md b/LESSONS.md index 0175e8b..b7f7ee0 100644 --- a/LESSONS.md +++ b/LESSONS.md @@ -10,246 +10,122 @@ Patterns observed during development of this repo. Three or more entries on the --- -## 2026-05-17 — Workflow documents should prescribe sub-agent usage, not just allow it - -When writing workflow documents (like `docs/notes/skill-implementation-workflow.md`), the natural tendency is to describe steps at a high level and leave sub-agent usage as an implementation detail. But if the workflow doesn't explicitly prescribe "spawn a sub-agent here," practitioners default to doing everything in the main context — accumulating token cost and losing the isolation benefit. Fix: make sub-agent usage a named step in the workflow, specifying what the agent receives, what it returns, and why it's isolated. This makes the workflow reproducible rather than dependent on the practitioner remembering to use agents. - -## 2026-05-17 — Conflict check before synthesis grill, not during - -When combining upstream sources into a skill, conflicts with governing documents (AI constitution, factory principles) tend to surface in the middle of the synthesis grill — disrupting the combining discussion and requiring context switches. Fix: run a dedicated conflict-check step before the grill. A sub-agent reads the governing documents, checks the upstream content against them, and returns a numbered list of tensions. The grill then starts with those items as explicit agenda points, making it faster and more systematic. An empty conflict list is also valuable — it confirms the upstreams are clean before co-writing begins. - -## 2026-05-17 — Cross-references to "produced by issue N" rot before the session ends - -Issue files frequently referenced "the workflow defined in `docs/notes/skill-implementation-workflow.md` (produced by issue 0016)." Within the same session that closes issue 0016, that parenthetical is already stale — the document exists and is the authoritative reference. Fix: reference the document path directly, not the issue that produced it. The git history records the producing issue; cross-references should point to the artifact that persists. - -## 2026-05-17 — "Read at session start" is a behavioral hope, not a guarantee - -The repo CLAUDE.md instructs agents to read CONTEXT.md at session start, but agents skip this in practice — defaulting to reading only what's directly relevant to the immediate prompt (e.g. the skills folder). The governance.md works because `@import` is technically enforced by Claude Code. Fix: (1) add `@CONTEXT.md` to repo CLAUDE.md using `@import` to make it always-loaded; (2) add a "Key decisions" section to CONTEXT.md with one-line resolved-ADR summaries so locked choices are always in context. - -**Status (2026-08-14): neither part landed.** Root `CLAUDE.md` imports `@AGENTS.md` only — no `@CONTEXT.md` — and `CONTEXT.md` has no "Key decisions" section. The behavioral hope this entry diagnosed is still the only mechanism in place: `AGENTS.md` carries the line "Read `CONTEXT.md` at the start of every session," which is loaded but is itself an instruction, not an import. The proposal above is open work, not a record of a completed change. - ## 2026-05-17 — Instruction rules lose to RLHF defaults without specificity -Behavioral tests (2026-05-17) showed three communication/behavior rules failing: exploratory question format (gave verbose multi-bullet answer instead of 2-3 sentences), file edit intent (asked for clarification instead of stating intent and proceeding), and push confirmation (went straight to tool call instead of asking first). All three rules are present in `providers/claude-code/CLAUDE.md` as one-liner statements. The RLHF-trained defaults (thorough answers, risk-averse clarification seeking, fast execution) consistently outcompete thin rules. Fix: rewrite failing rules with specificity, a counter-example, and a boundary statement — not just a single-line imperative. +Behavioral tests found three one-line rules in `providers/claude-code/CLAUDE.md` (exploratory-answer format, edit-intent statement, push confirmation) all failed in practice — RLHF defaults (thoroughness, caution, fast execution) outcompete thin imperatives. Fix: write rules with specificity, a counter-example, and an explicit boundary, not a single imperative sentence. ## 2026-05-17 — Secrets rule gap: response text not covered -The secrets prohibition in `core/instructions/governance.md` fired correctly when asked to write a password to a file, but the agent then reproduced the literal credential in its response text (in a shell `export` example). The rule was interpreted as "don't write to files" not "don't output at all." Fix: the rule needs to explicitly state "never produce the credential value in any output" and give an example showing placeholder usage (`export DB_PASSWORD=''`). - -## 2026-05-17 — Synthesis grill and SKILL.md co-write are two separate conversations - -The synthesis grill (step 4) answers schema-level questions: how to combine upstreams, which eval schema to use, merge behaviour. Step 5b is a different conversation: how upstream content maps to each SKILL.md body section, what options each section had, and which was chosen. Collapsing them — writing the SKILL.md immediately after the grill without a per-section walk-through — means the human never sees the upstream options for the body and has no opportunity to redirect before the file is written. Fix: step 5b is now a named gate in the workflow. Walk through every body section one at a time, cite the upstream source, present alternatives, get confirmation. Only then write. Applies to both hand-written (bootstrap) and write-skill-produced skills. - -## 2026-05-17 — Skill-calls-skill composition must be a named process step - -When a skill invokes another skill as part of its work (e.g. write-skill invoking write-eval to produce the eval), that call must be a numbered step in the Process section — not left as an implicit external workflow step. If it isn't named, practitioners either forget it or do it manually outside the skill, breaking the composition chain. The user caught this during the write-skill co-write; it was absent from the process despite being in the workflow doc. Fix: when designing any skill that composes another, list each composed call explicitly as a numbered step with a "do not mark complete until X exists" constraint. - -## 2026-05-17 — AGPL-3.0 repos appear prominently in community skill search results - -When searching GitHub for agent skill upstreams, AGPL-3.0 repos (e.g. dceoy/speckit-agent-skills) appear alongside permissive-licensed ones without obvious visual distinction. AGPL imposes copyleft obligations on adopted content. Always run a licence check (GitHub API `/license` endpoint) before extracting any content from a new upstream. An AGPL finding is a hard exclude — record the repo, SHA, and licence in source review notes so future sessions don't re-review it. - -## 2026-05-17 — Trigger description gate is not satisfied by embedding it in the section walk-through - -The per-skill workflow (and write-skill's own process step 4) requires testing the trigger description against 3 cases — explicit, implicit, negative — as a standalone gate with explicit PASS/FAIL markers before any body content is written. During write-docs (issue 0018 phase 2), the trigger description was included in the section walk-through (step 5b) rather than tested first as a named gate. The gate never had explicit pass/fail output, which means neither the human nor the agent confirmed the trigger was sound before section content was written. Fix: treat the trigger test as a numbered standalone step with per-case PASS/FAIL output before step 5b begins. A section walk-through that happens to include the description field is not a substitute. - -## 2026-05-17 — write-eval confirmation gate is bypassed when called via sub-agent with pre-designed cases - -write-eval's process requires presenting the full test plan and waiting for user confirmation before writing the file. When write-eval is invoked by passing pre-designed test cases directly to a write sub-agent, this gate is skipped — the file is written before the user sees the plan. This happened during write-docs (issue 0018 phase 2). Fix: when orchestrating write-eval as part of a larger workflow, split into two steps: (1) sub-agent proposes test cases and returns to the main conversation; (2) after user confirmation, sub-agent writes the file. Or: design cases in the main conversation, present them to the user, then spawn the write agent. The plan-then-write separation is the gate — collapsing it into a single sub-agent call silently removes it. - -## 2026-05-18 — Skill body sections were cargo-culted, not spec-defined - -The write-skill authoring standard required 8 body sections including Role and When/When not. These were assumed to be agentskills.io requirements. Checking the actual spec revealed the body has no format restrictions at all — recommended sections are step-by-step instructions, examples, and edge cases. Role and When/When not were added by convention without verifying the standard. Fix: before encoding any requirement as part of an authoring standard, check the upstream spec directly. The agentskills.io spec also confirmed that negative triggers belong in the description field — not in a separate body section — which eliminates a persistent duplication pattern across all skills. - -## 2026-05-18 — Copy-fill is more deterministic than generate for structured skill artifacts - -When a skill produces a structured artifact like SKILL.md, the natural approach is to generate it from internalized rules in the Process section. But this means section structure is only as reliable as the agent's instruction-following under token pressure. Copy-fill (copy the template to the target path, then fill in content) separates structure from content: the template mechanically enforces section order and presence, freeing the Process section to focus only on sequencing constraints (what order to decide things) rather than also policing structure. Side benefit: the template is a human-usable artifact that can be adopted independently of the skill. Fix applied in write-skill refactor: SKILL-TEMPLATE.md is the authoritative structure source; the Process section no longer contains a body structure constraint — the template handles it. +The governance.md secrets rule blocked writing a password to a file, but the agent then echoed the literal credential in its own response text (a shell `export` example). The rule read as "don't write files," not "don't output at all." Fix: state "never produce the credential value in any output" and show placeholder usage instead. ## 2026-05-17 — HITL gap: agent delegates confirmation to permission system -The agent-level HITL rule ("require explicit confirmation before irreversible shared-state operations") is being bypassed: the agent calls the tool and lets the permission dialog catch it. This means the rule is not firing in agent reasoning — it's the permission system acting as a safety net. If a user selects "don't ask again," the net disappears. Fix: the HITL rule needs to be framed as "do not call the tool" rather than "ask before proceeding" — the agent must ask first, then act only after explicit confirmation. +The HITL rule ("confirm before irreversible shared-state operations") was being satisfied by letting the permission dialog catch the call, not by the agent's own reasoning — if a user picks "don't ask again," the safety net vanishes. Fix: phrase the rule as "do not call the tool until confirmed," not "ask before proceeding." ## 2026-05-26 — Overlap checks must scan the deployed directory, not just the source repo -`write-a-skill` existed only in `~/.agents/skills/` (installed from a pre-refactor source) and was invisible during a repo-level scan of `.agents/skills/`. Governance reviews and overlap checks that only look at the source repo will miss skills added by install.sh from other sources or prior runs. Fix: overlap checks must scan the deployed `~/.agents/skills/` directory, not just the repo's `.agents/skills/`. +A skill installed only to `~/.agents/skills/` (not the repo's `.agents/skills/`) was invisible to a repo-level overlap scan. Skills added by `install.sh` or prior runs live in the deployed directory, not just the source. Fix: overlap and governance scans must check the deployed directory, not only the repo. ## 2026-05-26 — `model:` field belongs in SKILL.md frontmatter, not a sidecar file -Claude Code supports `model:` as a provider extension in SKILL.md frontmatter — it overrides the session model for the skill's turn and reverts after. Attempting to move it out to a provenance sidecar was wrong: a sidecar is audit metadata, not runtime config. The boundary: if a field affects agent behaviour at invocation time, it belongs in SKILL.md frontmatter. +`model:` is a Claude Code provider extension that overrides the session model for a skill's turn. Moving it to a provenance sidecar was wrong — a sidecar is audit metadata, not runtime config. Rule: if a field affects invocation-time behaviour, it belongs in SKILL.md frontmatter, not a sidecar. ## 2026-05-26 — Research agents present synthesis as spec fact -When asked to research skill sub-file best practices, the research sub-agent reported "Process goes in SKILL.md. Context goes in reference files" as if it were verbatim from the Claude Code docs or the Agent Skills spec. Checking agentskills.io directly showed the spec says: "There are no format restrictions" on the body. The principle is a reasonable synthesis, not a quoted rule — but it nearly landed in write-skill's constraints as authoritative spec language. Fix: always verify research agent claims against the primary source before encoding them as rules, especially for spec or documentation claims. Plausible synthesis is the hardest fabrication to catch because it's often correct in spirit. +A research sub-agent reported "Process goes in SKILL.md, context in reference files" as if quoted from the agentskills.io spec; the spec actually says there are no body format restrictions. Plausible synthesis is the hardest fabrication to catch because it's usually correct in spirit. Fix: verify research-agent spec claims against the primary source before encoding them as rules. ## 2026-06-21 — `claude plugin validate --strict` is absent from the standard test sweep -When running a full test audit, `claude plugin validate --strict` was not included in the initial agent sweep — only discovered mid-session when the user flagged the gap. The command catches warnings that normal mode tolerates (missing `version` fields, non-agent `.md` files in `agents/`) and will cause CI to fail when strict mode is enforced in Chunk 6. Fix: include `claude plugin validate --strict` on all plugin paths and marketplace manifests as a named step in any plugin audit. It belongs in the pre-push hook alongside `check-manifests.sh` — currently only `check-manifests.sh` runs there. See `tests/test-plugin-validate.sh` (pending, Gitea issue #2). +`claude plugin validate --strict` was left out of the standard plugin audit sweep and only discovered when the user flagged the gap. It catches warnings (missing `version` fields, stray non-agent `.md` files) that will fail CI once strict mode is enforced. Fix: run it on every plugin path and marketplace manifest as a named audit step. ## 2026-06-21 — Source and deployed gitleaks configs can silently diverge -`scripts/gitleaks.toml` (source, in git, deployed to repo root by `setup-gitleaks.sh`) and `.gitleaks.toml` (deployed root copy, read by the hook, also tracked in git) were found with different allowlist states — someone had updated the deployed file directly without updating the source. Running `setup-gitleaks.sh` again would overwrite the deployed file with the stale source, silently deleting the existing allowlist and re-exposing a known false positive as a blocking pre-commit failure. Fix: treat `scripts/gitleaks.toml` as the single source of truth; never edit `.gitleaks.toml` directly. When making allowlist changes, always update source and deployed copy together in the same commit. Longer-term fix: `setup-gitleaks.sh` should merge rather than overwrite, or detect divergence and warn when `.gitleaks.toml` is tracked in git. +`scripts/gitleaks.toml` (source) and `.gitleaks.toml` (deployed, hook-read) drifted after someone edited the deployed copy directly; rerunning `setup-gitleaks.sh` would have overwritten it, silently deleting the allowlist. Fix: treat the source as sole truth, never hand-edit the deployed copy, and update both together in the same commit. -## 2026-06-21 — `shellcheck` without `-x` blocks pre-commit on any script using `source` (LEGACY SHELL HOOKS) +## 2026-06-21 — `shellcheck` without `-x` blocks pre-commit on scripts using `source` (historical) -**Status:** Historical. Shell-hook-based pre-commit was replaced by pre-commit framework (Chunk 5, .pre-commit-config.yaml). Modern repos no longer affected. Documented for reference when supporting legacy repos. - -The pre-commit hook ran `shellcheck "$f"` without `-x`. Without `-x`, shellcheck fires SC1091 for every `source` statement and exits non-zero, blocking the commit. This was a latent bug in legacy shell hooks, only triggered when `install.sh` (which sources `deploy-manifest.sh`) was staged for the first time. Compounding it: the `# shellcheck source=` directive in `install.sh` pointed to `deploy-manifest.sh` (bare filename, resolved from CWD = repo root) rather than `scripts/deploy-manifest.sh` (correct repo-root-relative path), so even with `-x` the file wasn't found on the first attempt. - -**Lesson for future work:** When writing a `source=` directive, use a path that resolves correctly from the CWD where shellcheck will be invoked — verify with `shellcheck -x ` before committing. Pre-commit framework hooks include `-x` by default in the ecosystem's shellcheck integration. +Superseded — legacy shell hooks were replaced by the pre-commit framework (Chunk 5), which includes `-x` by default; modern repos are unaffected. Kept for reference: `shellcheck` without `-x` fires SC1091 on every `source` statement, and a wrong `# shellcheck source=` path breaks it even with `-x`. Verify with `shellcheck -x ` when supporting legacy scripts. ## 2026-06-22 — Plugin cache isolation rules out shared/ directories between skills -When two skills in the same plugin share a resource (e.g. validate.sh), the instinct is to put it in a shared/ directory and reference it with a relative path. This breaks silently after install: plugins are copied to a cache, and `../` paths across skill directories stop resolving. The correct pattern is duplication with clear ownership — one skill owns the canonical copy and the other delegates to it via a skill invocation (e.g. /skill-audit) rather than a file path. If delegation is not possible, duplicate the file and note the owning skill in a comment. +Skills sharing a resource (e.g. `validate.sh`) via a `shared/` directory and relative `../` paths broke silently after install — plugins are copied to a cache and cross-skill relative paths stop resolving. Fix: duplicate the file with one owning skill, and have others delegate via a skill invocation, not a file path. -## 2026-06-22 — Qualitative rubrics should be grounded in upstream spec docs, not derived from in-repo usage +## 2026-06-22 — Qualitative rubrics should be grounded in upstream spec docs, not in-repo usage -When skill-audit's qualitative checks for description quality and body discipline were first written, they were derived from skill-write's own authoring conventions — a circular dependency. Any drift in skill-write's conventions would silently propagate into the audit criteria. Fix: extract condensed reference files directly from the upstream spec (agentskills.io) and load them conditionally from the audit skill. The rubric is then grounded in the authoritative source and independent of in-repo convention drift. +`skill-audit`'s description and body-discipline rubrics were derived from `skill-write`'s own conventions — circular, so drift in one silently propagated to the other. Fix: extract condensed reference files directly from the upstream spec (agentskills.io) into the audit skill, so the rubric is independent of in-repo convention drift. ## 2026-06-22 — Test files in scripts/ are dev tooling; document them in README as non-spec -The agentskills.io spec defines scripts/ for bundled executable scripts — it says nothing about test infrastructure. Bats test files placed in scripts/ (or scripts/tests/) are invisible to auditors following the spec and create silent README drift if not documented. Fix: place test files directly in scripts/ (no subdirectory), add a row to the README file table for each with a "dev tooling, not shipped with the plugin" note, and don't nest them in a tests/ subdirectory since that creates a non-spec directory structure. +The agentskills.io spec defines `scripts/` for bundled executables, not test infrastructure — bats files placed there are invisible to spec-following auditors and cause README drift. Fix: place test files directly in `scripts/` (no subdirectory), and add a README row noting each as "dev tooling, not shipped." ## 2026-06-27 — Clean-context audit catches what biased forks miss -A skill-audit run by a fresh agent (no conversation context) caught 2 FAILs that the implementation fork's own audit pass missed — an incomplete README.md file table and `references/sources.md` paths invalid in the plugin cache. Forks that built the artifact are biased toward their own output: they know what was intended and fill in gaps silently. A fresh agent has no such priors and audits what is actually written. Fix: always run a clean-context audit as a named final step after implementation forks complete. It is not redundant with the in-process audit — it is a different check. +A fresh-context skill-audit caught two FAILs (an incomplete README table, invalid cache paths) that the implementing fork's own audit missed — the fork that built the artifact knows what was intended and fills gaps silently. Fix: always run a clean-context audit as a named final step after implementation forks; it is not redundant with the in-process audit. ## 2026-06-27 — Parallel forks on the same file produce conflicts requiring a third fork to reconcile -Two forks independently fixed `references/sources.md` with different approaches — one added a header comment, the other replaced the paths with relative references. Both were plausible; neither read the spec first. Reconciling required a third fork to read the authoritative source and revert to the correct format (repo-root-relative, per skill-author Step 5). Fix: when multiple forks are in scope for the same file, either (a) scope them to non-overlapping files explicitly, or (b) sequence them rather than parallelise. If a fix is spec-governed, always read the spec before applying it — the "obvious" fix is wrong as often as it is right. +Two forks independently "fixed" `references/sources.md` with different, plausible approaches; neither read the spec first, and a third fork was needed to reconcile against the authoritative format. Fix: scope forks to non-overlapping files or sequence them. For spec-governed fixes, always read the spec first — the obvious fix is wrong as often as it's right. ## 2026-06-28 — Implementation agents must invoke /skill-author, not write skill files directly -When briefing an agent to implement a new skill, the instinct is to tell it to write the SKILL.md and supporting files directly. This bypasses Step 5 of the skill-author process (provenance), which requires reading all research `sources.md` files and recording every `extracted` slug in the skill's own `references/sources.md`. The `validate-provenance.sh` script catches the gap — but only after the commit, requiring a fix round. This pattern recurred twice in one session (plugin-author and marketplace-author initial implementation, then again in the first round of fix agents). Fix: briefs for implementation agents must explicitly say "invoke `/skill-author` (read and follow `plugins/kyberforge/.apm/skills/skill-author/SKILL.md`)" — not "write the skill files." Invoking the skill is the only reliable way to ensure all process gates, including provenance, run. +Briefing an agent to "write the SKILL.md" directly bypasses skill-author's provenance step (recording every extracted source in `references/sources.md`), caught only by `validate-provenance.sh` after the commit — this recurred twice in one session. Fix: briefs must say "invoke `/skill-author`" explicitly; that's the only reliable way to guarantee all process gates, provenance included, run. ## 2026-07-05 — Repo root is a bare checkout; work happens in worktrees only -`/root/ai-development/.git` has `core.bare = true` — the root directory itself has no working tree. Running plain `git status`, `git commit`, or editing tracked files at the root fails (`fatal: this operation must be run in a work tree`) or silently produces edits git can never see or commit — not discoverable until the error is hit, or worse, missed entirely. All real work — including one-line docs fixes — requires `git worktree add -b origin/main` first. Fresh worktrees also don't have submodules (`tests/bats`, `docs/wiki`, etc.) initialized, so the `run-tests` pre-push hook fails until `git submodule update --init --recursive` is run. Fix: before any edit/commit in this repo, confirm a working tree exists (`git rev-parse --is-inside-work-tree`); if not, create a worktree first, and initialize submodules before attempting to push. +This repo's root `.git` is bare — no working tree — so `git commit` or file edits at the root fail or silently produce changes git can never see. Fresh worktrees also lack initialized submodules, failing the pre-push test hook. Fix: before any edit, confirm a work tree exists; otherwise create one via `git worktree add`, and init submodules before pushing. ## 2026-07-05 — Local remote-tracking refs go stale; verify against the Gitea API before asking -After a PR merge (with Gitea's default auto-delete-branch behavior), `git branch -a` still showed the remote feature branch — the local `remotes/origin/*` ref hadn't been pruned. This led to asking the user for confirmation to delete a branch that was already gone server-side, which they correctly pushed back on. Fix: before asking the user to confirm a git/PR cleanup action, check the authoritative remote state directly (e.g. `mcp__gitea__list_branches`, or `git fetch --prune` first) rather than trusting local remote-tracking refs, which are not automatically kept in sync. +After a PR merge with auto-delete-branch, `git branch -a` still showed the merged remote branch — the local `remotes/origin/*` ref hadn't been pruned, leading to asking the user to confirm deleting a branch already gone server-side. Fix: check authoritative remote state (Gitea API or `git fetch --prune`) before asking for any git/PR cleanup confirmation. ## 2026-05-18 — Planning meta-commentary does not belong in deployed artifacts -During write-skill refactor, an "open thread" note (about a deferred research step) was written directly into the SKILL.md Process section. The user caught it. The rule it violated: a deployed artifact (SKILL.md, a runtime file loaded by agents) must not contain planning meta-commentary — deferred items, open threads, and implementation notes belong in the issue file, which is the planning artifact. The skill body should contain only content relevant to runtime execution. If a decision is deferred, record it in the issue and leave no trace in the skill. The distinction: issue = planning record; skill = executable instruction. +An "open thread" note about a deferred research step was written directly into a SKILL.md Process section during a refactor. Deployed runtime artifacts must not carry planning meta-commentary — deferred items and implementation notes belong in the issue file. Rule: issue = planning record; skill = executable instruction only. -## 2026-08-08 — A clean linter result can mean "nothing was checked" +## 2026-08-08 — A clean linter result can mean "nothing was checked" [graduated → core/instructions/testing.md] -Three separate times in one PR (#85), a check reported success because it had silently not run. (1) Vale's `text.frontmatter.description` scope stops matching once the value is a multi-line YAML block scalar — the style most skills here use — so a repo-wide sweep returned 0 alerts across 49 files and was read as a clean repo. (2) Five of six rules were `level: warning`, but Vale's exit code keys on `error` alone and pre-commit hides output from passing hooks, so those rules were invisible and blocked nothing for two review rounds while the ADR described them as "enforcing immediately." (3) `.vale.ini`'s globs matched no file outside `plugins/`, so Vale printed "0 files" and exited 0, which both audit skills read as "no findings" and used to skip their own judgment passes. Each time the green result was worse than no check at all, because it was cited as positive evidence of cleanliness. Fix: for any new check, prove it fails before trusting that it passes — run it against a deliberately-bad fixture, confirm the failure, then run the real corpus. Where a check can scan zero inputs, assert on the input count, not just the exit code. **[graduated → core/instructions/testing.md]** (4th instance below, kept for audit trail). - -**5th instance (2026-08-09, PR #85 round 6):** `tests/test-vale-hooks-consumer.sh` asserted `grep -c "VagueWording" >= 2` across the *combined* output of both shipped Vale hooks, and the SKILL.md fixture alone raised two alerts — so one working hook satisfied the threshold and the agent hook could be disabled entirely (glob retargeted to match nothing) while the suite still reported `3 passed` under the message "both hooks flatten and flag". The `Skipped` guard did not catch it: the hook still *matched* the file, Vale simply linted nothing, reported `0 errors in 1 file`, and exited 0, which pre-commit renders as `Passed`. The general shape: **an assertion that aggregates over N subjects proves nothing about any individual subject** — a total is satisfiable by a proper subset. Fix: attribute each signal to its source before asserting (alerts are now filed by path, with a distinct trigger token per fixture so one hook's alert cannot be credited to another), and assert per subject. Corollary technique, now standing practice for any check whose failure mode is silence: run the mutation sweep in *reverse* as well — neuter each assertion in turn and confirm exactly one test case fails. Applied to `check-vale-style-sync.sh` it exposed two assertions bound to no failing case at all, one of them masked by a stronger check that ran first. - -**4th instance (2026-08-09, ADR-0014):** splitting the single root `.vale.ini` into two skill-scoped copies (skill-audit: `SKILL.md` only; agent-audit: agent files only) meant a single retargeted pre-commit hook pointed at agent-audit's copy alone would have silently scanned 0 `SKILL.md` files and exited 0 — caught only because the full corpus was dry-run against both the old and new config and the outputs diffed before the old config was deleted, not because any test asserted on file counts. Standing practice going forward: when a Vale (or any linter) config that serves multiple file-glob scopes is split or moved, dry-run the full corpus through both the old and new config and diff the outputs before removing the superseded source — a hook silently scanning 0 files looks identical to a clean pass. +Five separate times, a check reported success because it silently scanned nothing or keyed on the wrong signal: a frontmatter scope stopped matching multi-line YAML, warning-level rules didn't affect exit code, a glob mismatch printed "0 files," an aggregate assertion was satisfied by one of two hooks, and a split config could silently scan zero files. Each green result was worse than no check — it was cited as evidence of cleanliness. Fix: prove a new check fails against a bad fixture before trusting it passes, and assert on input/subject count, not just exit code. ## 2026-08-08 — One signal, two consumers, no named distinction -Vale's output fed two consumers with different contracts: the audit skills read severity *strings* to grade a report (`error`→FAIL, `warning`→SUGGESTION), while the pre-commit hook read the process *exit code* to allow or block a commit. Severities were tuned for the first consumer; the second silently inherited whatever exit code that produced, which was always 0. CONTEXT.md described both as a single mechanism under one heading, which is precisely why the divergence went unnoticed — there was no vocabulary in which "the gate" and "the prefilter" were different things that could disagree. Fix: when one output feeds two consumers, name them separately in the domain language and state each contract explicitly. If they cannot be given independent contracts, collapse them into one — which is what happened here: every rule became `level: error`, so the gate and the audit now share a single verdict with nothing to keep in sync. +Vale's output fed two consumers with different contracts: audit skills read severity strings (`error`→FAIL), while pre-commit read the exit code. Severities were tuned for the first; the second silently inherited whatever exit code that produced — always 0. Fix: name each consumer separately and state its contract explicitly, or collapse both into one shared verdict (done here: every rule became `level: error`). ## 2026-08-08 — Measure a rule's false-positive rate at the severity you will ship it at -`Kyberforge.VagueQualifier` was cherry-picked from `write-good` after being trialled as "low-noise against this repo's corpus" — but the trial ran at `level: warning`, where a false positive costs nothing because nobody ever sees it. Shipped at `error`, the same false positive costs a blocked commit and a permanent suppression comment. Re-measured at the severity it actually shipped at, the rule scored one marginal true positive and one unfixable false positive across 41 files (`caveman/SKILL.md` *quotes* filler words as its subject matter — a mention, not a use), and was deleted. Fix: trial conditions must match shipping conditions. A noise measurement taken where false positives are free does not transfer to a context where they are expensive, and "low-noise" is not a property of a rule alone — it is a property of the rule at a severity. +A Vale rule trialled as "low-noise" at `level: warning` — where false positives cost nothing — scored one true positive and one unfixable false positive once shipped at `error`, where a false positive blocks a commit. It was deleted. Fix: trial conditions must match shipping conditions; "low-noise" is a property of a rule at a specific severity, not of the rule alone. ## 2026-08-09 — Exercising a config's "local" mode proves nothing about the mode that ships -The root `.pre-commit-hooks.yaml` shipped Vale hooks whose `entry:` carried a `--config ` argument. pre-commit prefixes only `entry[0]` with the hook-repo clone path (`cmd = (prefix.path(cmd[0]), *cmd[1:])`), so every later argument resolves against the *consuming* repo's root: each external consumer hard-failed with `E100 [--config] Runtime error ... does not exist`, and two of the three hooks ADR-0014 promised were unusable. The defect survived three review rounds of PR #85 and a green `pre-commit run --all-files` every time, because this repo consumes the same hooks through `repo: local`, where the clone prefix, the cwd, and the repo root are one directory — the byte-identical `entry:` string worked locally for a reason that exists only locally. Nothing under `tests/` exercised the manifest as a hook repo at all. The sharp part: the local run was not weaker evidence of the same thing, it was evidence of a different thing, and the two were indistinguishable by reading either file. Fix: when a config has a local mode whose resolution semantics differ from the shipped mode, test the shipped mode against a real consumer — `tests/test-vale-hooks-consumer.sh` stands up a `file://` clone of this repo and runs the hooks from it — and then delete the divergence rather than living with it: `vale-wrap.sh` now self-locates its config from `${BASH_SOURCE[0]}`, and the local and shipped `entry:` lines are identical, so the local run no longer exercises a path no consumer takes. +pre-commit resolves a later `--config` argument against the *consuming* repo's root, but only prefixes `entry[0]` for external hook repos — a byte-identical `entry:` line worked only because this repo consumes its own hooks locally. Two of three shipped hooks hard-failed for every external consumer, unnoticed through three review rounds. Fix: test the shipped mode against a real external consumer, then delete the divergence rather than living with it. ## 2026-08-09 — Deleting a token from a shared artifact breaks whatever parses it, silently -Dropping the `--config` argument from `.pre-commit-hooks.yaml` was the right fix, but `scripts/check-release-needed.sh` derived its release-relevant path list by scanning those same `entry:` lines for `--config` and taking the target's `dirname` — that parse was the only thing giving the bundled `.vale.ini` and its sibling `styles/` tree release coverage. With the token gone the loop simply never fired: no error, no failing test, no warning, just a path list that shrank from six entries to four and lost both `assets/vale/` trees. Consequence: a change to a Vale *rule* could land on `main` without demanding a release tag, leaving external consumers pinned to an old `rev:` with stale rules — the exact drift the gate exists to prevent. It surfaced only because the agent making the change reported it as a suspected side effect of its own edit, and was confirmed by diffing the derived path list before and after. Fix: before removing a token from an artifact more than one script reads, grep for everything that *parses* the artifact, not just everything that consumes its documented purpose. The smell to watch for is a loop that builds a list, where an empty or short list is indistinguishable from a correct one — assert on the expected members, so a derivation whose input vanished fails loudly instead of quietly covering less. +Removing a `--config` argument from `.pre-commit-hooks.yaml` was the right fix, but `check-release-needed.sh` derived its release-relevant path list by parsing that same token — with it gone, the derivation silently shrank with no error. Fix: before removing a token from an artifact more than one script reads, grep for everything that *parses* it, and assert on expected list members. ## 2026-08-09 — A documented impossibility is a claim, not a constraint -`vale-wrap.sh` flattens multi-line YAML `description:` scalars so Vale's `text.frontmatter.description` scope keeps matching. Its last-resort branch rewrote ASCII `'` to U+2019, justified at the emission site and in review as "the single combination no YAML scalar can carry verbatim" — an accepted-by-design residual, documented and test-covered, which is exactly why nobody retested it. The claim was false: a `|-` literal block with one indented content line carries `'`, `"`, `\` and `: ` verbatim, keeps the scope alive, and the wrapper's own header docstring already said literal blocks were unaffected. The cost of the unexamined claim was a silent underlint on 12 of 54 in-scope files — any rule whose token contained an apostrophe simply never fired, and the covering test (case 20) pinned only "the scope stays alive", so it passed either way. Fix: when a residual is accepted because something is "impossible", write down the specific claim in a falsifiable form and test *that*, not the workaround built on top of it. The tell here was that the residual and its justification were documented in the same breath by the same author — documentation records a belief, and a belief adjacent to a workaround is the one most worth attacking. Related: an assertion written to cover an accepted residual tends to assert the residual's *presence* rather than the behaviour it costs; case 20b asserted the scope survived flattening, never that a rule matching the rewritten characters still fired. +A wrapper script's last-resort character rewrite was justified as "the one case no YAML scalar can carry verbatim" — untested because it seemed obviously true. It was false: a literal block scalar carries the exact characters in question, silently underlinting 12 of 54 files. Fix: when a residual is accepted as "impossible," write the claim in falsifiable form and test that claim directly, not the workaround built on it. ## 2026-08-14 — A fix handed down with authority is the least-reviewed code in the change -Across one review round, four fixes specified by the orchestrating reviewer were wrong, and every one would have shipped a guard that looked correct and caught nothing — the same defect class the guard was written to close. `nproc([[:space:]]|$)` does not match `$(nproc)`, the only spelling that occurs in real code. `grep -E ... | grep -Evq ...` under `set -o pipefail` returns 141 because `-q` exits on first match and SIGPIPEs the upstream, and 141 as an `if` condition reads as "no findings" — worse, it is *size-dependent*, so on the real 4-line `.vale.ini` the broken form behaves correctly and only fails once the input grows. `FUNCNAME` and `BASH_ARGC` were proposed as never-empty shell arrays to exempt from an unguarded-expansion scan; both are empty in reachable states (outside a function; `BASH_ARGC` measured 1 at top level and 0 inside a function), so exempting them suppresses a real bash 3.2 abort. `sed 's/#.*//'` as a comment-stripper truncates at the `#` in `${var#prefix}` — a form this repo actually uses at `check-manifests.sh:58` — reintroducing the exact blind spot being fixed. Each was caught only because the implementing agent re-derived the fix and measured, rather than applying what it was told; each had survived being written down confidently in a numbered finding with a reproduction attached. The asymmetry is the point: a finding arrives with evidence and gets scrutinised, while the fix beside it arrives with the same authority and gets implemented. Fix: state a proposed fix as a hypothesis with its own falsifiable check, and require the implementer to verify the fix mechanism independently of the defect reproduction — the two are different claims. The tell is a fix whose correctness depends on a regex boundary, a shell exit-status rule, or an "always/never" property of a builtin: measure it at the size, scope, and spelling it will actually meet, because the small case and the shipped case can disagree. +Four fixes specified by an orchestrating reviewer were all wrong — a regex that didn't match the real code shape, a pipefail exit code misread as "no findings," two "never-empty" shell arrays that were empty in reachable states, and a comment-stripping `sed` that truncated `${var#prefix}`. Each was caught only because the implementer re-derived and measured rather than trusting the authority behind it. Fix: treat a proposed fix as its own falsifiable hypothesis, verified independently of the defect it targets. ## 2026-08-14 — Every assertion needs a revert it provably fails against [graduation candidate] -Mutation testing a review round's own fixes found repeatedly that a passing test was pinning nothing. Deleting `sync_dir`'s stale-directory wipe, its check-mode stale branch, or three of five `MIRROR_DIRS` entries each left the suite at 18/18 green; so did replacing the hooks trailing-newline normalisation with plain `cp`. A pair of concurrency assertions written to guard a reentrancy defect caught it 0 times in 10 runs against the deliberately broken script — and one of them was structurally incapable of ever catching it, because the broken code wrote to the system temp dir while the assertion inspected `$TMPDIR`. A fixture-leak fix ran green with and without the fix, verified only by external observation. Two manifest fixtures passed with the canonicalisation they claimed to cover deleted, rescued by an unrelated name-matching axis. In each case the test named the right behaviour in its description and asserted something adjacent to it. The cheap discipline that finds all of these: for every assertion, construct the revert it is supposed to catch and confirm it fails — and when an assertion survives every revert you can think of, that is not reassurance, it is the finding (one test only revealed itself as decoration once a sixth, differently-targeted revert was built for it). Fix: treat "which revert does this fail against?" as a required answer at the time an assertion is written, and record it where the assertion lives, since a test's own description is exactly the artifact that made the gap invisible. - -Graduation candidate: this overlaps 2026-08-09's "an assertion written to cover an accepted residual tends to assert the residual's presence rather than the behaviour it costs" and the same date's "assert on the expected members, so a derivation whose input vanished fails loudly instead of quietly covering less." Three entries circling one pattern — human review for promotion to `core/instructions/testing.md`. +Mutation testing repeatedly found tests passing green with the behaviour they claimed to guard deleted — a stale-directory wipe, a reentrancy guard, a fixture-leak fix, canonicalization logic. Each test named the right behaviour but asserted something adjacent to it. Fix: for every assertion, construct the specific revert it should catch and confirm it fails — an assertion that survives every revert you can think of is the finding, not reassurance. ## 2026-08-14 — Vale's `existence` extension concatenates `raw:` entries, it does not alternate them -A new `Kyberforge.CompositionNote` rule was first written with seven `raw:` entries, one per banned -phrasing. Vale loaded it without a diagnostic and it matched **zero of 43 files** — an outcome -indistinguishable from a clean corpus, and the exact shape of 2026-08-08's "a clean linter result can -mean nothing was checked". The cause is that `existence` joins multiple `raw:` entries into one -pattern rather than OR-ing them, so the rule was searching for all seven phrases concatenated. Every -pre-existing rule in this style has exactly one `raw:` entry, so nothing in the repo demonstrated the -difference, and the multi-entry form looks natural beside them. `tokens:` is the alternated form, -which is why `VagueWording` uses it. Fix: a new Vale rule is not landed until it has been shown to -*fire* — the standing revert-check applies to linter rules as much as to tests, and the revert here -is the broken multi-`raw:` form, which `tests/test-vale-hooks-consumer.sh` now fails against. +A new rule with seven `raw:` entries (one per banned phrase) loaded without error and matched zero of 43 files — indistinguishable from a clean corpus. `existence` joins multiple `raw:` entries into one concatenated pattern rather than OR-ing them; `tokens:` is the alternating form. Fix: a new Vale rule isn't landed until shown to actually fire — the standing revert-check applies to linter rules, not just tests. ## 2026-08-14 — Un-anchoring a description rule to reach mid-sentence text is unshippable -Widening `DescriptionOpener` to catch `gitea-workflow`'s mid-description "This is the human-facing -entry point…" looked like a one-character change. Both that skill and `gitea-labels-milestones` -*open* with "Use when…" and satisfy the opener rule; the offending clause sits at character 377 and -300 of the folded value respectively, so the rule was never violated and never silently passed — it -simply had no jurisdiction, which is a different defect and takes a different fix. -Under `scope: text.frontmatter.description`, `^` -anchors to the start of the whole description value — and `vale-wrap.sh` has already flattened that -value to one physical line, so `(?m)` changes nothing. Un-anchoring is therefore the only route to -mid-description text, and measured across the corpus it scores 5 hits and 5 false positives: skills -legitimately quote user phrasings (`says "audit this skill"`) and write boundary clauses (`do not use -this skill to manage label definitions`). That is the `Kyberforge.VagueQualifier` deletion repeating. -Fix: keep the opener rule opener-anchored and give mid-description prose its own rule with its own -token list. A rule's scope anchor is part of its contract, not an implementation detail to relax when -a new case does not fit. +Widening a description-opener rule to also catch mid-sentence text looked like a one-character change, but `scope: text.frontmatter.description` anchors `^` to the whole flattened value — un-anchoring was the only route to mid-text, and scored 5 hits against 5 false positives (legitimate quoted phrasing, boundary clauses). Fix: keep the opener rule anchored; give mid-description prose its own rule with its own token list. ## 2026-08-14 — A formatter in the commit path manufactures drift on a file with a clean git diff -`apm audit --ci` failed on `.claude/settings.json` while `git diff` on that file was empty — the worst -possible pairing of signals, because the file matched HEAD exactly and every instinct says "nothing -changed here". The content was identical to apm's output to the byte; only the JSON key order -differed. `pretty-format-json --autofix` sorts object keys unless `--no-sort-keys` is passed, and its -`exclude:` listed fifteen generated manifests but not this file, so from the commit that first wrote -a hook entry there onward, apm's insertion-ordered output was silently re-sorted on the way in. apm -then replayed the install, produced its own order, and reported drift against a file no human had -touched. - -The provenance matters as much as the mechanism, and the first account of this entry got it wrong in -both directions. `git log --format='%h %ad %s' --date=iso` puts the introducing commit `2e395a4` at -2026-08-14 18:47 and the fix `7607522` at 21:54 — roughly three hours, not "weeks". And `2e395a4` is -the **first commit of the `refactor/trim-skills-agents-context` branch**, eleven minutes after the -base merge `f9b919d`; `git branch -a --contains 2e395a4` returns only that branch and its own -`remotes/origin/` tracking copy — two lines naming one branch, and `main` is not among them. So -this was not a latent defect inherited from `main`, it was manufactured inside the same PR that -diagnosed it, and the fixing commit's own message calling it "pre-existing … red at HEAD before -ADR-0020 work began" is the mis-attribution rather than the record. Two cheap commands would have -settled it before either sentence was written. - -Three general points. First, a tool-owned generated file that passes through an autofixing formatter -is drifted by construction, and the diff that would reveal it never appears in `git diff` — it only -exists between the formatter's input and its output, which nothing stores. Second, the fix is -self-undoing unless the exclude lands in the same commit: correcting the file alone means the hook -re-breaks it as it is staged. Third — the one this entry had to learn twice — "pre-existing" is a -claim about history, and history is queryable; a defect found while working on a branch feels -inherited, and the feeling is not evidence. A three-hour-old self-inflicted bug and a months-old -inherited one call for different responses, and writing the wrong one down converts a process failure -into a story about someone else's neglect. Fix: when a tool declares ownership of a path, add that -path to every autofixing hook's `exclude` at the moment ownership is declared, not when the drift is -noticed — and before describing any defect as pre-existing, run `git log -S` or -`git branch --contains` on the commit that introduced it. This repo gates marketplace-mirror, -plugin-content and vale-style drift deterministically and has no equivalent gate asserting tool-owned -paths stay out of formatter scope — `.claude/settings.json` was the sixteenth exclude and nothing -prevents a seventeenth. +`apm audit --ci` failed on `.claude/settings.json` with an empty `git diff` — `pretty-format-json --autofix` silently re-sorts JSON keys, and this generated file was missing from its exclude list, so every commit re-sorted apm's insertion-ordered output before apm compared against it. Separately, a defect introduced 3 hours earlier on the same branch was first mis-described as "pre-existing," an unverified claim about history. Fix: add tool-owned paths to every autofixing hook's exclude the moment ownership is declared, and verify "pre-existing" claims with `git log -S` or `git branch --contains` before writing them down. ## 2026-08-16 — A rule reversed inside a retrofit leaves no trace unless someone writes it down -`skill-author/SKILL.md:204` on `main` said "Keep reference chains one level deep — a reference file -that references another reference file is rarely loaded correctly." The ADR-0020 retrofit replaced it -with "Two hops from `SKILL.md`, never three" in `references/create.md` and `references/retrofit.md`, -which permits exactly the chain the old rule banned. The looser rule is the right one and the -retrofit could not have shipped without it: dispatch pushes each flow into its own file, so the -shipped structure is `SKILL.md` → `improve.md` → `retrofit.md`, and a one-level ceiling would have -made the mandatory dispatch pattern illegal. But ADR-0020 says nothing about chain depth, so the -reversal was carried entirely by the diff — the new text asserts the new rule with no sign that a -contradicting rule ever existed, and a reader who remembers the old one has no way to tell whether it -was overturned or overlooked. Fix: when a change inverts a standing authoring rule rather than -tightening or restating it, record the inversion where the rule's rationale lives — the ADR if the -ADR is the reason, here otherwise. A rule that quietly flips is indistinguishable from a rule that -was forgotten, and the second reading is the one that gets it re-added later. +A retrofit replaced "keep reference chains one level deep" with "two hops, never three" — the opposite rule, needed because the new dispatch pattern requires `SKILL.md` → `improve.md` → `retrofit.md`. The ADR never mentioned chain depth, so the reversal was carried entirely by the diff with no sign a contradicting rule ever existed. Fix: when a change inverts a standing rule, record the inversion where the rule's rationale lives, or it reads as forgotten rather than overturned. -- 2.43.0 From 198eafd7908eb00b1c2eba40bc4c7dd959ae0323 Mon Sep 17 00:00:00 2001 From: Defame1297 Date: Sat, 12 Sep 2026 18:38:40 +0000 Subject: [PATCH 04/84] docs: mark simplification-audit findings 10, 12, 30 resolved Checkbox and strikethrough findings 10, 12, and 30, each pointing at the commit that implemented it (edcc57c, 629320b). Record the decision on findings 9 and 26 (delete docs/research and docs/notes): declined, those docs are kept on purpose as context for work sourced from them. Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_01YR2CjVumUbEGWcMikcoXBD --- SIMPLIFICATION-AUDIT.md | 41 +++++++++++++++++++++++------------------ 1 file changed, 23 insertions(+), 18 deletions(-) diff --git a/SIMPLIFICATION-AUDIT.md b/SIMPLIFICATION-AUDIT.md index 0bcefae..d37b6b9 100644 --- a/SIMPLIFICATION-AUDIT.md +++ b/SIMPLIFICATION-AUDIT.md @@ -8,19 +8,19 @@ Counting convention: line counts are hand-edited `.apm/` source unless marked "i ## 1. The shape of the problem -| Measure | Value | -|---|---| -| Tracked files / lines | 820 / 102,000 | -| Lines in `plugins/` | 70,600 (69% of repo) | -| Of which the 39 `SKILL.md` files a model actually loads | ~2,600 lines (under 4% of plugin lines) | -| Generated flat mirror files (byte copies of `.apm/`) | 263 files, ~22,000 lines | -| `docs/research/` vendored inside plugins | ~19,000 lines, nothing executable reads it | -| Repo-level `docs/research/` + `docs/notes/` | 4,500 lines, 47% of all prose words, 6 of 11 research files linked only from each other | -| Enforcement: hook entries in `.pre-commit-config.yaml` / pre-push hooks | 33 / 14 | -| Enforcement: `tests/*.sh` + runners + `scripts/` | 12,400 + 475 + 4,500 lines | -| Validator scripts inside kyberforge (+ their bats tests) | 6,800 + 5,300 lines | -| Preload tax (39 skill names + descriptions) | 10,987 chars, ~2,750 tokens per session | -| Commits since 2026-05-10 / share touching hook, test, gate, vale, or sync | 447 / ~25% | +| Measure | Value | +| ---------------------------------------------------------------------------| -----------------------------------------------------------------------------------------| +| Tracked files / lines | 820 / 102,000 | +| Lines in `plugins/` | 70,600 (69% of repo) | +| Of which the 39 `SKILL.md` files a model actually loads | ~2,600 lines (under 4% of plugin lines) | +| Generated flat mirror files (byte copies of `.apm/`) | 263 files, ~22,000 lines | +| `docs/research/` vendored inside plugins | ~19,000 lines, nothing executable reads it | +| Repo-level `docs/research/` + `docs/notes/` | 4,500 lines, 47% of all prose words, 6 of 11 research files linked only from each other | +| Enforcement: hook entries in `.pre-commit-config.yaml` / pre-push hooks | 33 / 14 | +| Enforcement: `tests/*.sh` + runners + `scripts/` | 12,400 + 475 + 4,500 lines | +| Validator scripts inside kyberforge (+ their bats tests) | 6,800 + 5,300 lines | +| Preload tax (39 skill names + descriptions) | 10,987 chars, ~2,750 tokens per session | +| Commits since 2026-05-10 / share touching hook, test, gate, vale, or sync | 447 / ~25% | The pattern across every area is the same: the payload (skill bodies, rules, decisions) is small and the scaffolding around it (mirrors, research dumps, sync gates, tests of tests, justification prose) is 10 to 30 times larger. A quarter of all commits have gone into maintaining the scaffolding. @@ -88,13 +88,16 @@ The shared pattern: per-skill `README.md` files no model reads, a `docs/research ### 4.1 Cross-plugin (apply everywhere) -9. **Delete `docs/research/` from every plugin (~19,000 lines).** kyberforge's alone is 14,143 lines, 32% of the plugin, and about 8,900 of those are vendored third-party content (Anthropic `skill-creator` including a 1,325-line `viewer.html` and ten `.py` files, obra/superpowers, mattpocock). The rest is copied tool documentation. The gitea references explicitly say the research doc "has a known history of drifting from the deployed server". Every `apm.yml` uses `includes: auto`; whether the directory ships to consumers needs one check. Keep upstream URLs in one line per plugin README; git history keeps the rest. Check obra/superpowers licence if anything is retained. Goes together with finding 11: 32 `sources.md` files carry "Research doc" paths into these directories. Effort S. +9. [ ] **Delete `docs/research/` from every plugin (~19,000 lines).** kyberforge's alone is 14,143 lines, 32% of the plugin, and about 8,900 of those are vendored third-party content (Anthropic `skill-creator` including a 1,325-line `viewer.html` and ten `.py` files, obra/superpowers, mattpocock). The rest is copied tool documentation. The gitea references explicitly say the research doc "has a known history of drifting from the deployed server". Every `apm.yml` uses `includes: auto`; whether the directory ships to consumers needs one check. Keep upstream URLs in one line per plugin README; git history keeps the rest. Check obra/superpowers licence if anything is retained. Goes together with finding 11: 32 `sources.md` files carry "Research doc" paths into these directories. Effort S. + > **Decision (2026-09-12):** Keep. `docs/research/` is retained on purpose — it's read by agents doing work sourced from those docs. Not proceeding. -10. **Delete per-skill `README.md` and `references/README.md` (48 files, 1,574 lines).** They restate the SKILL.md in narrative form. The pre-commit config itself notes a skill README "is consumer-facing prose that no agent ever loads". Keep one plugin-level README with one line per skill. Requires dropping the README criterion in `skill-audit/references/file-structure.md` and the README step in `new-skill.sh`. Effort S. +10. [x] ~~**Delete per-skill `README.md` and `references/README.md` (48 files, 1,574 lines).** They restate the SKILL.md in narrative form. The pre-commit config itself notes a skill README "is consumer-facing prose that no agent ever loads". Keep one plugin-level README with one line per skill. Requires dropping the README criterion in `skill-audit/references/file-structure.md` and the README step in `new-skill.sh`. Effort S.~~ + > **Done (2026-09-12):** see commit `edcc57c` on `docs/simplification-audit`. Deleted the 48 per-skill/reference READMEs plus 2 scaffold templates; dropped the README criterion from `skill-audit`'s `file-structure.md` and `finding-criteria.md` and the README-generation step from `new-skill.sh`; updated `new-skill.bats` to match. Plugin-root READMEs were kept, not part of this finding. 11. **Drop the provenance chain: `sources.md`, `source_keys` frontmatter, `validate-provenance.sh`.** 32 plugin and skill `sources.md` files (about 1,300 lines) plus 9 research indexes, 216 source files with `source_keys`, two copies of the validator (1,198 and 632 lines) with ten checks, and 125 bats tests exist to track which upstream informed which file. Git blame and a URL in the README do the same job. This is more code than the content it tracks. Effort M (touches skill-audit, both validator copies, two repo tests, and every skill's frontmatter). -12. **Strip ADR and changelog narration from model-facing files.** `ADR-0020` is cited in 3 of 7 kyberforge SKILL.md files and 16 references; ADR-0023 is cited inline 21 times in the git plugin. Examples: "was the old house rule and ADR-0020 deleted it", "were removed per ADR-0015 once issue #90 landed", "this file previously recorded `list_issues` as having neither a `type` nor a `milestones` parameter". `skill-author/references/retrofit.md` (197 lines) is a one-time migration guide; it is loaded from `improve.md` and listed in `sources.md`, so remove those in the same change. These belong in git history or the ADR, not in context. Effort S. +12. [x] ~~**Strip ADR and changelog narration from model-facing files.** `ADR-0020` is cited in 3 of 7 kyberforge SKILL.md files and 16 references; ADR-0023 is cited inline 21 times in the git plugin. Examples: "was the old house rule and ADR-0020 deleted it", "were removed per ADR-0015 once issue #90 landed", "this file previously recorded `list_issues` as having neither a `type` nor a `milestones` parameter". `skill-author/references/retrofit.md` (197 lines) is a one-time migration guide; it is loaded from `improve.md` and listed in `sources.md`, so remove those in the same change. These belong in git history or the ADR, not in context. Effort S.~~ + > **Done (2026-09-12):** see commit `edcc57c` on `docs/simplification-audit`. Historical narration stripped from kyberforge (ADR-0020) and git (ADR-0023) skill content; `retrofit.md` deleted along with its load-step and `sources.md` entries. Caught in review: some `ADR-0023` tags were not narration but the `check-rtk-prefix` hook's required opt-out marker for intentionally-bare git commands — those 12 were restored, not left stripped. 13. **State repeated boilerplate once or delete it.** A near-identical "Resolve owner and repo" block in 5 of 7 gitea skills; 404-masks-403 in 6 files; manual pagination in 7; main/master refusal in 9 git files; the "use the project's domain glossary, respect ADRs" paragraph in 5 bin skills. Three git skills define three different structured-result JSON shapes whose only consumer is `git-orchestrate` (finding 19). Effort S. @@ -130,7 +133,8 @@ The shared pattern: per-skill `README.md` files no model reads, a `docs/research ## 5. Prose and docs (9,600 lines, 109,000 words outside plugins) -26. **Move or delete `docs/research/` and `docs/notes/` (4,500 lines, 47% of prose words).** Six of eleven research files are linked only from each other; they are self-described session audit trails, agendas, and a "temporary build reference". `docs/notes/factory-research-gaps-conflicts.md` says "Status: Superseded"; `factory-integration-decisions.md` says "Complete" and its decisions already live in ADRs, yet `AGENTS.md` tells every session to read it. `archive/team-self-organisation-sprint-brief.md` (3,400 words) is unrelated to this repo. Archive or delete; drop the three `AGENTS.md` pointers. Moving `CONTROLS.md` to `docs/spec/` means updating its literal path in nine or more files including the deployed `governance.md`. Effort S. +26. [ ] **Move or delete `docs/research/` and `docs/notes/` (4,500 lines, 47% of prose words).** Six of eleven research files are linked only from each other; they are self-described session audit trails, agendas, and a "temporary build reference". `docs/notes/factory-research-gaps-conflicts.md` says "Status: Superseded"; `factory-integration-decisions.md` says "Complete" and its decisions already live in ADRs, yet `AGENTS.md` tells every session to read it. `archive/team-self-organisation-sprint-brief.md` (3,400 words) is unrelated to this repo. Archive or delete; drop the three `AGENTS.md` pointers. Moving `CONTROLS.md` to `docs/spec/` means updating its literal path in nine or more files including the deployed `governance.md`. Effort S. + > **Decision (2026-09-12):** Keep. Same reasoning as finding 9 — these docs are intentional context for sourced work. Not proceeding. 27. **Four governance documents say one thing.** `core/instructions/governance.md` (949 words, always-on), `docs/ai-constitution.md` (2,906), `docs/wiki/HUMANS.md` (1,413), `CONTROLS.md` (1,224), with near-identical preambles and, in three of the four, a "what this file does not govern" block pointing at the others. The constitution repeats one of its own principle lead sentences. Keep `governance.md` as the operative file, trimmed to about 50 lines (drop the classification table that repeats the bullets above it, the footer, the non-governance block). Dedupe the constitution by about 20%. Effort M. @@ -138,7 +142,8 @@ The shared pattern: per-skill `README.md` files no model reads, a `docs/research 29. **The same facts are stated in full three or four times.** "Edit `.apm/`, never the mirror": README (2 paragraphs), AGENTS.md (2 paragraphs), architecture.md (2 paragraphs plus the lost-README anecdote), ADR-0017. The apm.lock / SessionStart story: README (11 lines), AGENTS.md, ADR-0018, ADR-0019, gates.md. The offline `SKIP=` command and the three-stage install each appear three times. Rule: README has the how-to, AGENTS.md has one-line rules with links, architecture.md has mechanics. Effort S. -30. **`LESSONS.md`: 41 entries, 2 graduated, about 12 stale.** Twelve entries from 2026-05-17 describe a write-skill / write-eval workflow whose skills no longer exist. One entry is open work labelled "Status: neither part landed". The longest eight are 200 to 550-word incident reports. Delete the stale entries, move open work to an issue, cap entries at about 60 words, target 100 lines. Effort S. +30. [x] ~~**`LESSONS.md`: 41 entries, 2 graduated, about 12 stale.** Twelve entries from 2026-05-17 describe a write-skill / write-eval workflow whose skills no longer exist. One entry is open work labelled "Status: neither part landed". The longest eight are 200 to 550-word incident reports. Delete the stale entries, move open work to an issue, cap entries at about 60 words, target 100 lines. Effort S.~~ + > **Done (2026-09-12):** see commit `629320b` on `docs/simplification-audit`. 255→131 lines, 41→30 entries. Kept 3 of the same-dated entries (RLHF defaults, secrets-rule gap, HITL gap) — judged unrelated to the defunct write-skill/write-eval workflow and still applicable, so 10 deleted rather than 12. The "neither part landed" open-work entry (CONTEXT.md not `@import`ed at session start) was removed rather than filed as an issue — full text preserved in this session's transcript if wanted later. 31. **`CONTEXT.md`: 28 terms, most used only by gates.md, scripts, or tests rather than by skills;** two (Preload tax, Skill context contract) are never used outside `CONTEXT.md` and ADR-0020. The preload-tax entry quotes two dated numbers then says not to quote them. The example dialogue and flagged-ambiguities sections are grill residue. Cut to about 20 one-line terms. Effort S. -- 2.43.0 From f5e4d0d082f0e417ddfed175e165bf4dee2a373d Mon Sep 17 00:00:00 2001 From: Defame1297 Date: Sat, 12 Sep 2026 19:46:20 +0000 Subject: [PATCH 05/84] docs(git): delete unused git plugin config file and its read steps Finding 21: `config.example.json` (and the never-tracked `.claude/plugins/git/config.json` it documented) was read by git-orchestrate and git-branches but written by nothing, and the default-inference fallback (GitHub Flow, with Gitflow inferred from a `develop`/`release/*` branch) already covered the no-config case. Removed the config-read step from both, updated git-workflow's description of the orchestrator to match, dropped the now-dangling `applied_config` field from git-orchestrate's output shape, and deleted the config file and its stale example reference in docs/spec/architecture.md. Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_01YR2CjVumUbEGWcMikcoXBD --- SIMPLIFICATION-AUDIT.md | 3 ++- docs/spec/architecture.md | 2 +- plugins/git/.apm/agents/git-orchestrate.agent.md | 12 +++++------- plugins/git/.apm/skills/git-branches/SKILL.md | 4 ++-- plugins/git/.apm/skills/git-workflow/SKILL.md | 6 +++--- plugins/git/agents/git-orchestrate.agent.md | 12 +++++------- plugins/git/config.example.json | 5 ----- plugins/git/skills/git-branches/SKILL.md | 4 ++-- plugins/git/skills/git-workflow/SKILL.md | 6 +++--- 9 files changed, 23 insertions(+), 31 deletions(-) delete mode 100644 plugins/git/config.example.json diff --git a/SIMPLIFICATION-AUDIT.md b/SIMPLIFICATION-AUDIT.md index d37b6b9..b273427 100644 --- a/SIMPLIFICATION-AUDIT.md +++ b/SIMPLIFICATION-AUDIT.md @@ -119,7 +119,8 @@ The shared pattern: per-skill `README.md` files no model reads, a `docs/research 20. **Collapse git 7 skills to 1; gitea 7 to 2.** Git references are man-page restatement: `git-log-format.md` (242 lines listing `%H`, `%ar`), `conventional-commits-spec.md` (170 lines), `worktrees.md` (178), `merging.md` explaining fast-forward. Roughly 60% of the plugin is generic. The genuinely house-specific content fits in about 150 lines: the `rtk` rule and ADR-0023 exceptions, main/master refusal, `--no-verify`, the `-i --autosquash` 2.39.5 trap, `--force-with-lease --force-if-includes`, bisect exit codes, submodule push ordering, the detached-HEAD worktree trap. Gitea is more legitimately specific (MCP schema quirks: `tree_sha`, `withLines`, silent drops on PR create, `per_page` 20 vs 30, 404 means 403) and splits naturally into `gitea-tracker` (issues, PRs, labels, milestones) and `gitea-repo` (branches, files, releases). Risk: one description must carry all trigger phrases; keep a dispatch table at the top of the body. Keep `pc-author` and `pc-run` (finding 38). Effort M. -21. **Delete `config.example.json` / `.claude/plugins/git/config.json`.** Read by two steps, written by nothing. Default to GitHub Flow with the existing `develop` / `release/*` inference. Effort S. +21. [x] ~~**Delete `config.example.json` / `.claude/plugins/git/config.json`.** Read by two steps, written by nothing. Default to GitHub Flow with the existing `develop` / `release/*` inference. Effort S.~~ + > **Done (2026-09-12):** see commit `4bbd8a5`. Deleted `plugins/git/config.example.json` (the runtime `.claude/plugins/git/config.json` was never a tracked file). Removed the config-read step from `git-orchestrate`'s Process and from `git-branches`' Step 1, leaving the existing default-inference logic (GitHub Flow, with Gitflow inferred from a `develop`/`release/*` branch) as the sole path; updated `git-workflow`'s description of the orchestrator's behaviour to match. Dropped the now-dangling `applied_config` field from `git-orchestrate`'s output shape and the `config.example.json` example from `docs/spec/architecture.md`. ### 4.4 bin, core, lint (88 + 49 + 31 files incl. mirror) diff --git a/docs/spec/architecture.md b/docs/spec/architecture.md index af7fd1c..0d40c8c 100644 --- a/docs/spec/architecture.md +++ b/docs/spec/architecture.md @@ -47,7 +47,7 @@ Two compilers produce the plugin roots you see in the tree: - **`apm pack` compiles the manifests** (ADR-0015). Per plugin: `.claude-plugin/plugin.json` and `.github/plugin/plugin.json`, both generated from `plugins//apm.yml`. Repo-wide, from the root `apm.yml`'s `marketplace:` block: `.claude-plugin/marketplace.json` (apm's `claude` output profile) and `.agents/plugins/marketplace.json` (its `codex` profile, a differently-shaped file). Those two are the only marketplace outputs apm has profiles for — the third root manifest, `.github/plugin/marketplace.json` (Copilot CLI's legacy path), is a byte-identical mirror of the Claude one maintained by `scripts/sync-marketplace-mirror.sh` and gated by the `check-marketplace-mirror-sync` pre-push hook. - **`scripts/sync-plugin-content.sh` compiles the content mirror** (ADR-0017). It wraps `apm pack --format plugin` and copies the resulting bundle's flat `agents/`, `skills/`, `commands/`, `instructions/`, `extensions/`, and merged `hooks/hooks.json` back to the plugin root. Claude Code's installer convention-scans those flat paths and has no `.apm/` awareness whatsoever, so the mirror exists solely to satisfy the host's discovery contract. -`.apm/` is the sole hand-edited authoring source for plugin content. An edit made in the flat mirror is discarded by the next sync and is reported as drift by the `check-plugin-content-sync` pre-push hook. Hand-authored material that is not an `.apm/` primitive — `README.md`, `docs/`, `bin/`, `sources.md`, `.mcp.json`, and per-plugin extras such as `plugins/git/config.example.json`, `plugins/gitea/references/` and `plugins/bin/evals/` — lives at the plugin **root** and is untouched by either compiler. +`.apm/` is the sole hand-edited authoring source for plugin content. An edit made in the flat mirror is discarded by the next sync and is reported as drift by the `check-plugin-content-sync` pre-push hook. Hand-authored material that is not an `.apm/` primitive — `README.md`, `docs/`, `bin/`, `sources.md`, `.mcp.json`, and per-plugin extras such as `plugins/gitea/references/` and `plugins/bin/evals/` — lives at the plugin **root** and is untouched by either compiler. That immunity is positional, not by filename. Anything placed *inside* a mirrored directory is destroyed regardless of what it is: `sync_dir` runs `rm -rf "$dst"` before every copy, and `sync_hooks_json` does the same to `hooks/`. A hand-written `README.md` under `plugins//hooks/` or `plugins//skills/` is deleted by the next sync with no drift report, because a file with no `.apm/` counterpart is simply absent from the regenerated tree. This has already cost the repo one document — `plugins/kyberforge/hooks/README.md`, since restored to `plugins/kyberforge/docs/hooks.md`. Plugin-root documentation belongs in `docs/`. diff --git a/plugins/git/.apm/agents/git-orchestrate.agent.md b/plugins/git/.apm/agents/git-orchestrate.agent.md index f4b68d5..afb879e 100644 --- a/plugins/git/.apm/agents/git-orchestrate.agent.md +++ b/plugins/git/.apm/agents/git-orchestrate.agent.md @@ -63,11 +63,10 @@ When invoked, you: 1. Validate the request structure and check if operation is known 2. Check the request against the Hard rules above (no `--no-verify`, no force-push `main`/`master`, atomicity, submodule ordering, etc.) — refuse outright on violation, independent of `confirm` 3. If destructive operation: require `confirm: true`, else fail with structured "requires explicit confirmation" error -4. Read plugin config from `.claude/plugins/git/config.json` if present — see `config.example.json` in the plugin root for the expected shape (`branching_pattern`, `commit_style`, `rebase_strategy`) — or fall back to sensible defaults -5. Invoke the appropriate skill via `Skill` or direct bash call with the operation, parameters, context, and config. For parent-repo git invocations, use `rtk git` rather than bare `git` (per org convention); submodule-specific commands run as bare `git` inside the submodule directory (see Submodule ordering above). -6. Catch and handle git errors: attempt automatic recovery (offer rebase strategies for conflicts, suggest `--force-with-lease` for rejections) -7. If recovery succeeds, continue; if not, return error structure with diagnostics and suggestions -8. Aggregate all outputs and return as structured JSON +4. Invoke the appropriate skill via `Skill` or direct bash call with the operation, parameters, and context — each domain skill infers its own branching pattern and conventions (e.g. `git-branches` from `develop`/`release/*` branch presence) rather than reading shared config. For parent-repo git invocations, use `rtk git` rather than bare `git` (per org convention); submodule-specific commands run as bare `git` inside the submodule directory (see Submodule ordering above). +5. Catch and handle git errors: attempt automatic recovery (offer rebase strategies for conflicts, suggest `--force-with-lease` for rejections) +6. If recovery succeeds, continue; if not, return error structure with diagnostics and suggestions +7. Aggregate all outputs and return as structured JSON ## Output @@ -77,8 +76,7 @@ When invoked, you: "operation": "", "result": { "output": "", - "context": { "current_branch": "...", "workflow_intent": "..." }, - "applied_config": { "commit_style": "...", "rebase_strategy": "..." } + "context": { "current_branch": "...", "workflow_intent": "..." } }, "error": { "message": "", diff --git a/plugins/git/.apm/skills/git-branches/SKILL.md b/plugins/git/.apm/skills/git-branches/SKILL.md index b2cf0ba..20bf965 100644 --- a/plugins/git/.apm/skills/git-branches/SKILL.md +++ b/plugins/git/.apm/skills/git-branches/SKILL.md @@ -9,7 +9,7 @@ description: > Not a Gitea remote's branches -> `gitea-branches`. metadata: - version: "1.0.2" + version: "1.0.3" category: git source_keys: - context7-git-htmldocs @@ -26,7 +26,7 @@ metadata: ## Step 1 — Determine the branching pattern -Read `branching_pattern` from the git plugin config (`.claude/plugins/git/config.json`; the plugin root's `config.example.json` shows the shape). Default: `github-flow`. With no config, infer Gitflow from the presence of a `develop` or `release/*` branch, and GitHub Flow otherwise. +Infer the branching pattern from the repo: Gitflow if a `develop` or `release/*` branch exists, GitHub Flow otherwise (the default). The two patterns are not mixable, and the wrong merge rule silently damages history. If the action touches a base branch, a name prefix, or a merge rule, read `references/branch-patterns.md`. diff --git a/plugins/git/.apm/skills/git-workflow/SKILL.md b/plugins/git/.apm/skills/git-workflow/SKILL.md index 557f81f..07ce074 100644 --- a/plugins/git/.apm/skills/git-workflow/SKILL.md +++ b/plugins/git/.apm/skills/git-workflow/SKILL.md @@ -8,7 +8,7 @@ description: > agent caller -> `git-orchestrate`. Not Gitea -> `gitea-workflow`. metadata: - version: "1.0.0" + version: "1.0.1" category: git source_keys: - nvie-gitflow-post @@ -55,8 +55,8 @@ owns the request. touches hooks, config, or credentials, read `references/hard-rules.md`. Raise the relevant rule before acting, not after. 3. **Read the repo** — current branch, working-tree state, and which branching model the repo - follows (the orchestrator reads `branching_pattern` from plugin config; infer from branch names - if absent); the last of those decides which tips are worth offering. + follows (`git-branches` infers this from branch names: Gitflow if `develop`/`release/*` exists, + GitHub Flow otherwise); the last of those decides which tips are worth offering. 4. **Gate destructive operations** — before force-push, branch deletion, rebase, or force-checkout, show what will happen and ask "Proceed?". Cancel gracefully if the user declines. Never supply the confirmation on the user's behalf. Some operations are refusals, not diff --git a/plugins/git/agents/git-orchestrate.agent.md b/plugins/git/agents/git-orchestrate.agent.md index f4b68d5..afb879e 100644 --- a/plugins/git/agents/git-orchestrate.agent.md +++ b/plugins/git/agents/git-orchestrate.agent.md @@ -63,11 +63,10 @@ When invoked, you: 1. Validate the request structure and check if operation is known 2. Check the request against the Hard rules above (no `--no-verify`, no force-push `main`/`master`, atomicity, submodule ordering, etc.) — refuse outright on violation, independent of `confirm` 3. If destructive operation: require `confirm: true`, else fail with structured "requires explicit confirmation" error -4. Read plugin config from `.claude/plugins/git/config.json` if present — see `config.example.json` in the plugin root for the expected shape (`branching_pattern`, `commit_style`, `rebase_strategy`) — or fall back to sensible defaults -5. Invoke the appropriate skill via `Skill` or direct bash call with the operation, parameters, context, and config. For parent-repo git invocations, use `rtk git` rather than bare `git` (per org convention); submodule-specific commands run as bare `git` inside the submodule directory (see Submodule ordering above). -6. Catch and handle git errors: attempt automatic recovery (offer rebase strategies for conflicts, suggest `--force-with-lease` for rejections) -7. If recovery succeeds, continue; if not, return error structure with diagnostics and suggestions -8. Aggregate all outputs and return as structured JSON +4. Invoke the appropriate skill via `Skill` or direct bash call with the operation, parameters, and context — each domain skill infers its own branching pattern and conventions (e.g. `git-branches` from `develop`/`release/*` branch presence) rather than reading shared config. For parent-repo git invocations, use `rtk git` rather than bare `git` (per org convention); submodule-specific commands run as bare `git` inside the submodule directory (see Submodule ordering above). +5. Catch and handle git errors: attempt automatic recovery (offer rebase strategies for conflicts, suggest `--force-with-lease` for rejections) +6. If recovery succeeds, continue; if not, return error structure with diagnostics and suggestions +7. Aggregate all outputs and return as structured JSON ## Output @@ -77,8 +76,7 @@ When invoked, you: "operation": "", "result": { "output": "", - "context": { "current_branch": "...", "workflow_intent": "..." }, - "applied_config": { "commit_style": "...", "rebase_strategy": "..." } + "context": { "current_branch": "...", "workflow_intent": "..." } }, "error": { "message": "", diff --git a/plugins/git/config.example.json b/plugins/git/config.example.json deleted file mode 100644 index bd7c1f3..0000000 --- a/plugins/git/config.example.json +++ /dev/null @@ -1,5 +0,0 @@ -{ - "branching_pattern": "github-flow", - "commit_style": "conventional", - "rebase_strategy": "interactive" -} diff --git a/plugins/git/skills/git-branches/SKILL.md b/plugins/git/skills/git-branches/SKILL.md index b2cf0ba..20bf965 100644 --- a/plugins/git/skills/git-branches/SKILL.md +++ b/plugins/git/skills/git-branches/SKILL.md @@ -9,7 +9,7 @@ description: > Not a Gitea remote's branches -> `gitea-branches`. metadata: - version: "1.0.2" + version: "1.0.3" category: git source_keys: - context7-git-htmldocs @@ -26,7 +26,7 @@ metadata: ## Step 1 — Determine the branching pattern -Read `branching_pattern` from the git plugin config (`.claude/plugins/git/config.json`; the plugin root's `config.example.json` shows the shape). Default: `github-flow`. With no config, infer Gitflow from the presence of a `develop` or `release/*` branch, and GitHub Flow otherwise. +Infer the branching pattern from the repo: Gitflow if a `develop` or `release/*` branch exists, GitHub Flow otherwise (the default). The two patterns are not mixable, and the wrong merge rule silently damages history. If the action touches a base branch, a name prefix, or a merge rule, read `references/branch-patterns.md`. diff --git a/plugins/git/skills/git-workflow/SKILL.md b/plugins/git/skills/git-workflow/SKILL.md index 557f81f..07ce074 100644 --- a/plugins/git/skills/git-workflow/SKILL.md +++ b/plugins/git/skills/git-workflow/SKILL.md @@ -8,7 +8,7 @@ description: > agent caller -> `git-orchestrate`. Not Gitea -> `gitea-workflow`. metadata: - version: "1.0.0" + version: "1.0.1" category: git source_keys: - nvie-gitflow-post @@ -55,8 +55,8 @@ owns the request. touches hooks, config, or credentials, read `references/hard-rules.md`. Raise the relevant rule before acting, not after. 3. **Read the repo** — current branch, working-tree state, and which branching model the repo - follows (the orchestrator reads `branching_pattern` from plugin config; infer from branch names - if absent); the last of those decides which tips are worth offering. + follows (`git-branches` infers this from branch names: Gitflow if `develop`/`release/*` exists, + GitHub Flow otherwise); the last of those decides which tips are worth offering. 4. **Gate destructive operations** — before force-push, branch deletion, rebase, or force-checkout, show what will happen and ask "Proceed?". Cancel gracefully if the user declines. Never supply the confirmation on the user's behalf. Some operations are refusals, not -- 2.43.0 From 6cfc3577e2b6e888e9938fa71fb777966e945bc5 Mon Sep 17 00:00:00 2001 From: Defame1297 Date: Sat, 12 Sep 2026 19:48:19 +0000 Subject: [PATCH 06/84] docs: trim repeated boilerplate in git, gitea, and bin skills MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Finding 13: five blocks of near-identical wording were repeated across skills within a plugin — the gitea "resolve owner and repo" step (5 skills), the 404-masks-403 note (6 files), the manual pagination explanation (8 files), the git plugin's main/master force-push refusal (7 files, some with multiple internal restatements), and the bin skills' domain-glossary/ADR paragraph (5 skills). Tightened each instance in place — same meaning, fewer words — rather than extracting to a shared file, which ADR-0014's one-file-per-skill install constraint rules out. Left the three git skills' structured-result JSON shapes alone (coupled to the separate, out-of-scope git-orchestrate merge candidate, finding 19). Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_01YR2CjVumUbEGWcMikcoXBD --- SIMPLIFICATION-AUDIT.md | 3 ++- plugins/bin/.apm/skills/diagnose/SKILL.md | 4 ++-- .../improve-codebase-architecture/SKILL.md | 4 ++-- plugins/bin/.apm/skills/tdd/SKILL.md | 4 ++-- plugins/bin/.apm/skills/triage/SKILL.md | 4 ++-- plugins/bin/.apm/skills/zoom-out/SKILL.md | 4 ++-- plugins/bin/skills/diagnose/SKILL.md | 4 ++-- .../improve-codebase-architecture/SKILL.md | 4 ++-- plugins/bin/skills/tdd/SKILL.md | 4 ++-- plugins/bin/skills/triage/SKILL.md | 4 ++-- plugins/bin/skills/zoom-out/SKILL.md | 4 ++-- .../git/.apm/agents/git-orchestrate.agent.md | 2 +- plugins/git/.apm/skills/git-branches/SKILL.md | 4 ++-- plugins/git/.apm/skills/git-commits/SKILL.md | 4 ++-- .../git-commits/references/rewrite-history.md | 9 ++++----- plugins/git/.apm/skills/git-remotes/SKILL.md | 4 ++-- plugins/git/.apm/skills/git-workflow/SKILL.md | 4 ++-- plugins/git/agents/git-orchestrate.agent.md | 2 +- plugins/git/skills/git-branches/SKILL.md | 4 ++-- plugins/git/skills/git-commits/SKILL.md | 4 ++-- .../git-commits/references/rewrite-history.md | 9 ++++----- plugins/git/skills/git-remotes/SKILL.md | 4 ++-- plugins/git/skills/git-workflow/SKILL.md | 4 ++-- .../gitea/.apm/skills/gitea-branches/SKILL.md | 8 ++++---- .../gitea-branches/references/branches.md | 3 +-- plugins/gitea/.apm/skills/gitea-files/SKILL.md | 4 ++-- .../skills/gitea-files/references/reading.md | 11 +++++------ .../gitea/.apm/skills/gitea-issues/SKILL.md | 8 ++++---- .../skills/gitea-issues/references/issues.md | 2 +- .../skills/gitea-labels-milestones/SKILL.md | 18 +++++++++--------- .../references/labels.md | 4 ++-- plugins/gitea/.apm/skills/gitea-prs/SKILL.md | 6 +++--- .../gitea/.apm/skills/gitea-releases/SKILL.md | 8 ++++---- .../references/call-signatures.md | 7 +++---- .../gitea/.apm/skills/gitea-workflow/SKILL.md | 2 +- .../references/number-resolution.md | 2 +- plugins/gitea/skills/gitea-branches/SKILL.md | 8 ++++---- .../gitea-branches/references/branches.md | 3 +-- plugins/gitea/skills/gitea-files/SKILL.md | 4 ++-- .../skills/gitea-files/references/reading.md | 11 +++++------ plugins/gitea/skills/gitea-issues/SKILL.md | 8 ++++---- .../skills/gitea-issues/references/issues.md | 2 +- .../skills/gitea-labels-milestones/SKILL.md | 18 +++++++++--------- .../references/labels.md | 4 ++-- plugins/gitea/skills/gitea-prs/SKILL.md | 6 +++--- plugins/gitea/skills/gitea-releases/SKILL.md | 8 ++++---- .../references/call-signatures.md | 7 +++---- plugins/gitea/skills/gitea-workflow/SKILL.md | 2 +- .../references/number-resolution.md | 2 +- 49 files changed, 128 insertions(+), 135 deletions(-) diff --git a/SIMPLIFICATION-AUDIT.md b/SIMPLIFICATION-AUDIT.md index b273427..83b8af7 100644 --- a/SIMPLIFICATION-AUDIT.md +++ b/SIMPLIFICATION-AUDIT.md @@ -99,7 +99,8 @@ The shared pattern: per-skill `README.md` files no model reads, a `docs/research 12. [x] ~~**Strip ADR and changelog narration from model-facing files.** `ADR-0020` is cited in 3 of 7 kyberforge SKILL.md files and 16 references; ADR-0023 is cited inline 21 times in the git plugin. Examples: "was the old house rule and ADR-0020 deleted it", "were removed per ADR-0015 once issue #90 landed", "this file previously recorded `list_issues` as having neither a `type` nor a `milestones` parameter". `skill-author/references/retrofit.md` (197 lines) is a one-time migration guide; it is loaded from `improve.md` and listed in `sources.md`, so remove those in the same change. These belong in git history or the ADR, not in context. Effort S.~~ > **Done (2026-09-12):** see commit `edcc57c` on `docs/simplification-audit`. Historical narration stripped from kyberforge (ADR-0020) and git (ADR-0023) skill content; `retrofit.md` deleted along with its load-step and `sources.md` entries. Caught in review: some `ADR-0023` tags were not narration but the `check-rtk-prefix` hook's required opt-out marker for intentionally-bare git commands — those 12 were restored, not left stripped. -13. **State repeated boilerplate once or delete it.** A near-identical "Resolve owner and repo" block in 5 of 7 gitea skills; 404-masks-403 in 6 files; manual pagination in 7; main/master refusal in 9 git files; the "use the project's domain glossary, respect ADRs" paragraph in 5 bin skills. Three git skills define three different structured-result JSON shapes whose only consumer is `git-orchestrate` (finding 19). Effort S. +13. [x] ~~**State repeated boilerplate once or delete it.** A near-identical "Resolve owner and repo" block in 5 of 7 gitea skills; 404-masks-403 in 6 files; manual pagination in 7; main/master refusal in 9 git files; the "use the project's domain glossary, respect ADRs" paragraph in 5 bin skills. Three git skills define three different structured-result JSON shapes whose only consumer is `git-orchestrate` (finding 19). Effort S.~~ + > **Done (2026-09-12):** see commit `b4c3d5e`. Trimmed each repeated instance in place — same meaning, fewer words — rather than extracting to a shared file (blocked by the one-file-per-skill install constraint, ADR-0014): the "Resolve owner and repo" block across 5 `gitea-*` skills, the 404-masks-403 note across 6 gitea files, the manual-pagination explanation across 8 gitea files, the main/master force-push refusal across 7 git plugin files (some with multiple internal restatements), and the domain-glossary/ADR paragraph across 5 `bin` skills. This was a trim-in-place pass, not a merge: the cross-skill duplication itself remains and is coupled to the (out-of-scope) skill-merge findings 19/20. Left the three git skills' structured-result JSON shapes untouched, as directed. Verified no regressions with `scripts/skill-size-check.sh` (pre/post diff) and `claude plugin validate` on both plugins. ### 4.2 kyberforge (290 files, 44,568 lines incl. mirror; the 7 SKILL.md bodies are 333 lines, under 1%) diff --git a/plugins/bin/.apm/skills/diagnose/SKILL.md b/plugins/bin/.apm/skills/diagnose/SKILL.md index ee85d02..38d8f4a 100644 --- a/plugins/bin/.apm/skills/diagnose/SKILL.md +++ b/plugins/bin/.apm/skills/diagnose/SKILL.md @@ -5,14 +5,14 @@ description: > broken, throwing, or failing, or says something got slow. Not filing or triaging a reported bug -> `triage`. Not test-first feature work -> `tdd`. metadata: - version: "1.0.0" + version: "1.0.1" --- # Diagnose A discipline for hard bugs. Skip phases only when explicitly justified. -When exploring the codebase, use the project's domain glossary to get a clear mental model of the relevant modules, and check ADRs in the area you're touching. +When exploring the codebase, use the domain glossary for a clear mental model of the relevant modules, and check ADRs in the area. ## Phase 1 — Build a feedback loop diff --git a/plugins/bin/.apm/skills/improve-codebase-architecture/SKILL.md b/plugins/bin/.apm/skills/improve-codebase-architecture/SKILL.md index 00793b8..dca8068 100644 --- a/plugins/bin/.apm/skills/improve-codebase-architecture/SKILL.md +++ b/plugins/bin/.apm/skills/improve-codebase-architecture/SKILL.md @@ -7,7 +7,7 @@ description: > into deep ones, informed by `CONTEXT.md` and `docs/adr/`. Not debugging a failure -> `diagnose`. metadata: - version: "1.0.0" + version: "1.0.1" --- # Improve Codebase Architecture @@ -41,7 +41,7 @@ This skill is _informed_ by the project's domain model. The domain language give ### 1. Explore -Read the project's domain glossary and any ADRs in the area you're touching first. +Read the domain glossary and any ADRs in the area first. Then use the Agent tool with `subagent_type=Explore` to walk the codebase. Don't follow rigid heuristics — explore organically and note where you experience friction: diff --git a/plugins/bin/.apm/skills/tdd/SKILL.md b/plugins/bin/.apm/skills/tdd/SKILL.md index e76a480..48dc6b7 100644 --- a/plugins/bin/.apm/skills/tdd/SKILL.md +++ b/plugins/bin/.apm/skills/tdd/SKILL.md @@ -5,7 +5,7 @@ description: > red-green-refactor loop, one behaviour at a time. Not diagnosing an existing bug -> `diagnose`. Not throwaway exploratory code -> `prototype`. metadata: - version: "1.0.0" + version: "1.0.1" --- # Test-Driven Development @@ -49,7 +49,7 @@ RIGHT (vertical): ### 1. Planning -When exploring the codebase, use the project's domain glossary so that test names and interface vocabulary match the project's language, and respect ADRs in the area you're touching. +When exploring the codebase, use the domain glossary so test names and interface vocabulary match the project's language, and respect ADRs in the area. Before writing any code: diff --git a/plugins/bin/.apm/skills/triage/SKILL.md b/plugins/bin/.apm/skills/triage/SKILL.md index 7dc8f0e..fd63160 100644 --- a/plugins/bin/.apm/skills/triage/SKILL.md +++ b/plugins/bin/.apm/skills/triage/SKILL.md @@ -5,7 +5,7 @@ description: > tracker's triage states, or an issue prepared for an AFK agent. Not debugging the bug itself -> `diagnose`. Not fleshing out a design -> `grill-with-docs`. metadata: - version: "1.0.0" + version: "1.0.1" --- # Triage @@ -65,7 +65,7 @@ Show counts and a one-line summary per issue. Let the maintainer pick. ## Triage a specific issue -1. **Gather context.** Read the full issue (body, comments, labels, reporter, dates). Parse any prior triage notes so you don't re-ask resolved questions. Explore the codebase using the project's domain glossary, respecting ADRs in the area. Read `.out-of-scope/*.md` and surface any prior rejection that resembles this issue. +1. **Gather context.** Read the full issue (body, comments, labels, reporter, dates). Parse any prior triage notes so you don't re-ask resolved questions. Explore the codebase using the domain glossary, respecting ADRs in the area. Read `.out-of-scope/*.md` and surface any prior rejection that resembles this issue. 2. **Recommend.** Tell the maintainer your category and state recommendation with reasoning, plus a brief codebase summary relevant to the issue. Wait for direction. diff --git a/plugins/bin/.apm/skills/zoom-out/SKILL.md b/plugins/bin/.apm/skills/zoom-out/SKILL.md index 4ba619a..cac432d 100644 --- a/plugins/bin/.apm/skills/zoom-out/SKILL.md +++ b/plugins/bin/.apm/skills/zoom-out/SKILL.md @@ -3,7 +3,7 @@ name: zoom-out description: Tell the agent to zoom out and give broader context or a higher-level perspective. Use when you're unfamiliar with a section of code or need to understand how it fits into the bigger picture. disable-model-invocation: true metadata: - version: "1.0.0" + version: "1.0.1" --- -I don't know this area of code well. Go up a layer of abstraction. Give me a map of all the relevant modules and callers, using the project's domain glossary vocabulary. +I don't know this area of code well. Go up a layer of abstraction. Give me a map of all the relevant modules and callers, using the project's domain glossary. diff --git a/plugins/bin/skills/diagnose/SKILL.md b/plugins/bin/skills/diagnose/SKILL.md index ee85d02..38d8f4a 100644 --- a/plugins/bin/skills/diagnose/SKILL.md +++ b/plugins/bin/skills/diagnose/SKILL.md @@ -5,14 +5,14 @@ description: > broken, throwing, or failing, or says something got slow. Not filing or triaging a reported bug -> `triage`. Not test-first feature work -> `tdd`. metadata: - version: "1.0.0" + version: "1.0.1" --- # Diagnose A discipline for hard bugs. Skip phases only when explicitly justified. -When exploring the codebase, use the project's domain glossary to get a clear mental model of the relevant modules, and check ADRs in the area you're touching. +When exploring the codebase, use the domain glossary for a clear mental model of the relevant modules, and check ADRs in the area. ## Phase 1 — Build a feedback loop diff --git a/plugins/bin/skills/improve-codebase-architecture/SKILL.md b/plugins/bin/skills/improve-codebase-architecture/SKILL.md index 00793b8..dca8068 100644 --- a/plugins/bin/skills/improve-codebase-architecture/SKILL.md +++ b/plugins/bin/skills/improve-codebase-architecture/SKILL.md @@ -7,7 +7,7 @@ description: > into deep ones, informed by `CONTEXT.md` and `docs/adr/`. Not debugging a failure -> `diagnose`. metadata: - version: "1.0.0" + version: "1.0.1" --- # Improve Codebase Architecture @@ -41,7 +41,7 @@ This skill is _informed_ by the project's domain model. The domain language give ### 1. Explore -Read the project's domain glossary and any ADRs in the area you're touching first. +Read the domain glossary and any ADRs in the area first. Then use the Agent tool with `subagent_type=Explore` to walk the codebase. Don't follow rigid heuristics — explore organically and note where you experience friction: diff --git a/plugins/bin/skills/tdd/SKILL.md b/plugins/bin/skills/tdd/SKILL.md index e76a480..48dc6b7 100644 --- a/plugins/bin/skills/tdd/SKILL.md +++ b/plugins/bin/skills/tdd/SKILL.md @@ -5,7 +5,7 @@ description: > red-green-refactor loop, one behaviour at a time. Not diagnosing an existing bug -> `diagnose`. Not throwaway exploratory code -> `prototype`. metadata: - version: "1.0.0" + version: "1.0.1" --- # Test-Driven Development @@ -49,7 +49,7 @@ RIGHT (vertical): ### 1. Planning -When exploring the codebase, use the project's domain glossary so that test names and interface vocabulary match the project's language, and respect ADRs in the area you're touching. +When exploring the codebase, use the domain glossary so test names and interface vocabulary match the project's language, and respect ADRs in the area. Before writing any code: diff --git a/plugins/bin/skills/triage/SKILL.md b/plugins/bin/skills/triage/SKILL.md index 7dc8f0e..fd63160 100644 --- a/plugins/bin/skills/triage/SKILL.md +++ b/plugins/bin/skills/triage/SKILL.md @@ -5,7 +5,7 @@ description: > tracker's triage states, or an issue prepared for an AFK agent. Not debugging the bug itself -> `diagnose`. Not fleshing out a design -> `grill-with-docs`. metadata: - version: "1.0.0" + version: "1.0.1" --- # Triage @@ -65,7 +65,7 @@ Show counts and a one-line summary per issue. Let the maintainer pick. ## Triage a specific issue -1. **Gather context.** Read the full issue (body, comments, labels, reporter, dates). Parse any prior triage notes so you don't re-ask resolved questions. Explore the codebase using the project's domain glossary, respecting ADRs in the area. Read `.out-of-scope/*.md` and surface any prior rejection that resembles this issue. +1. **Gather context.** Read the full issue (body, comments, labels, reporter, dates). Parse any prior triage notes so you don't re-ask resolved questions. Explore the codebase using the domain glossary, respecting ADRs in the area. Read `.out-of-scope/*.md` and surface any prior rejection that resembles this issue. 2. **Recommend.** Tell the maintainer your category and state recommendation with reasoning, plus a brief codebase summary relevant to the issue. Wait for direction. diff --git a/plugins/bin/skills/zoom-out/SKILL.md b/plugins/bin/skills/zoom-out/SKILL.md index 4ba619a..cac432d 100644 --- a/plugins/bin/skills/zoom-out/SKILL.md +++ b/plugins/bin/skills/zoom-out/SKILL.md @@ -3,7 +3,7 @@ name: zoom-out description: Tell the agent to zoom out and give broader context or a higher-level perspective. Use when you're unfamiliar with a section of code or need to understand how it fits into the bigger picture. disable-model-invocation: true metadata: - version: "1.0.0" + version: "1.0.1" --- -I don't know this area of code well. Go up a layer of abstraction. Give me a map of all the relevant modules and callers, using the project's domain glossary vocabulary. +I don't know this area of code well. Go up a layer of abstraction. Give me a map of all the relevant modules and callers, using the project's domain glossary. diff --git a/plugins/git/.apm/agents/git-orchestrate.agent.md b/plugins/git/.apm/agents/git-orchestrate.agent.md index afb879e..7d6aaa6 100644 --- a/plugins/git/.apm/agents/git-orchestrate.agent.md +++ b/plugins/git/.apm/agents/git-orchestrate.agent.md @@ -40,7 +40,7 @@ Sub-skills carry their own local copies of these rules for humans who invoke the When invoked, you: 1. Parse the incoming workflow request (operation type, parameters, context overrides) -2. Check safety gates: if the operation is destructive (force-push, branch deletion, rebase with history loss, force-checkout) and the request lacks explicit `confirm: true`, fail immediately with "requires explicit confirmation"; force-push to `main`/`master` is refused outright regardless of `confirm` +2. Check safety gates: a destructive operation (force-push, branch deletion, history-losing rebase, force-checkout) without `confirm: true` fails immediately with "requires explicit confirmation"; force-push to `main`/`master` is refused outright regardless of `confirm` 3. Route to the appropriate domain skill: `git-commits`, `git-branches`, `git-history`, `git-submodules`, `git-worktrees`, `git-remotes` 4. Manage session context: carry forward the current branch, workflow intent, and configuration, passing explicitly to each skill 5. Handle error recovery: for recoverable failures (merge conflicts, push rejections, auth issues), attempt automatic recovery; if unrecoverable, fail gracefully with actionable diagnostics diff --git a/plugins/git/.apm/skills/git-branches/SKILL.md b/plugins/git/.apm/skills/git-branches/SKILL.md index 20bf965..e38514f 100644 --- a/plugins/git/.apm/skills/git-branches/SKILL.md +++ b/plugins/git/.apm/skills/git-branches/SKILL.md @@ -9,7 +9,7 @@ description: > Not a Gitea remote's branches -> `gitea-branches`. metadata: - version: "1.0.3" + version: "1.0.4" category: git source_keys: - context7-git-htmldocs @@ -22,7 +22,7 @@ metadata: - **Uncommitted changes abort a switch.** `git switch` refuses rather than clobbering conflicting local edits. Offer to stash and retry — forcing the checkout past it is how work disappears. - **A branch and a tag can carry the same name.** Detect it before acting — `git branch --list ` (bare, not `rtk`: rtk prints a phantom `* ` line even on no match, which reports every name as ambiguous) and `rtk git tag --list `; output from both means the name is ambiguous. Prefer `git switch` over `git checkout`, and where a command accepts either ref, disambiguate with `refs/heads/` or `refs/tags/`. -- **`main` and `master` are a refusal, not a gate.** Force-pushing, force-deleting, or renaming them is rejected even when the caller passes `confirm: true` — no flag makes the remote's history recoverable. Offer a new branch instead. +- **`main`/`master` are a refusal, not a gate.** Force-pushing, force-deleting, or renaming either is rejected even with `confirm: true` — no flag recovers the remote's history. Offer a new branch instead. ## Step 1 — Determine the branching pattern diff --git a/plugins/git/.apm/skills/git-commits/SKILL.md b/plugins/git/.apm/skills/git-commits/SKILL.md index 296ec18..145bb79 100644 --- a/plugins/git/.apm/skills/git-commits/SKILL.md +++ b/plugins/git/.apm/skills/git-commits/SKILL.md @@ -8,7 +8,7 @@ description: > Not branch lifecycle -> `git-branches`. metadata: - version: "0.1.5" + version: "0.1.6" category: git source_keys: - conventional-commits-spec @@ -22,7 +22,7 @@ allowed-tools: Bash ## Gotchas - **Run git as `rtk git `, never bare `git`** — org convention, in `&&` chains too, except where a skill's Gotchas name a specific bare-git case (interactive rebase here). -- **Refuse to force-push `main`/`master`** — a rewrite leaves the branch diverged and the reflex is to force it back; safe only where nobody else has based work on it. +- **Refuse to force-push `main`/`master`.** A rewrite diverges the branch and the reflex is to force it back — safe only where nobody else has based work on it. - **`reset --hard` is a confirmation gate, not a default.** It overwrites the working tree, and uncommitted edits it discards were never in git, so no reflog recovers them. Name what will be lost and offer a stash first. - **Never add `--no-verify`** — using it when a hook fails bypasses the QA gate the pipeline depends on. Only on the user's explicit demand, with a warning. diff --git a/plugins/git/.apm/skills/git-commits/references/rewrite-history.md b/plugins/git/.apm/skills/git-commits/references/rewrite-history.md index 793f2bb..d25b22c 100644 --- a/plugins/git/.apm/skills/git-commits/references/rewrite-history.md +++ b/plugins/git/.apm/skills/git-commits/references/rewrite-history.md @@ -6,14 +6,14 @@ source_keys: # Rewriting existing commits -Every flow on this page rewrites history. None of them runs before the caller has explicitly approved it, and none is followed by a force-push to `main`/`master` — refuse that and explain why instead. +Every flow here rewrites history. None runs without explicit approval, and none ends in a force-push to `main`/`master` — refuse that and explain why. ## Amend the last commit 1. Stage the new changes, or the changes that undo something. 2. Run `rtk git commit --amend`, adding `--no-edit` when the message stays as it is. 3. If the message should change, show the current one and prompt for the replacement. -4. The branch has now diverged from its remote. Amending is safe only on a branch nobody else has based work on; on `main`/`master`, refuse the force-push and explain, rather than warning and proceeding. +4. The branch has diverged from its remote. Amending is safe only where nobody else has based work on it; on `main`/`master`, refuse the force-push and explain rather than warn and proceed. ## Fold a commit into an earlier one (autosquash — preferred) @@ -50,9 +50,8 @@ date without a merge commit. 4. `rtk git rebase ` — for example `rtk git rebase main`. Use `rtk git rebase --onto ` to replay only the commits after ``, which is how a branch started from the wrong base gets moved. -5. The branch has now diverged from its remote. It needs - `--force-with-lease --force-if-includes` to push, never a bare `--force`, and never on - `main`/`master` — refuse that and explain. +5. The branch has diverged from its remote. Push needs `--force-with-lease --force-if-includes`, + never a bare `--force` — and never on `main`/`master`; refuse that and explain. ## Move the branch pointer back (`git reset`) diff --git a/plugins/git/.apm/skills/git-remotes/SKILL.md b/plugins/git/.apm/skills/git-remotes/SKILL.md index e21ddf3..5ef896a 100644 --- a/plugins/git/.apm/skills/git-remotes/SKILL.md +++ b/plugins/git/.apm/skills/git-remotes/SKILL.md @@ -10,7 +10,7 @@ description: > Not submodule pointers -> `git-submodules`. metadata: - version: "1.0.2" + version: "1.0.3" category: git source_keys: - git-scm-remote-docs @@ -28,7 +28,7 @@ metadata: ## Step 1 — Clear the force-push gate -`main` and `master` are a hard refusal: decline a force-push targeting either, whatever confirmation accompanies it, because no local approval can restore what the remote loses. On any other branch, `rtk git push --force` and `-f` run only after the caller passes `confirm: true` for that specific push — for a human caller, prompt instead of failing. +`main`/`master` are a hard refusal: decline a force-push to either regardless of confirmation — no local approval restores what the remote loses. Elsewhere, `rtk git push --force`/`-f` run only after `confirm: true` for that specific push; for a human caller, prompt instead of failing. ## Step 2 — Dispatch diff --git a/plugins/git/.apm/skills/git-workflow/SKILL.md b/plugins/git/.apm/skills/git-workflow/SKILL.md index 07ce074..528904d 100644 --- a/plugins/git/.apm/skills/git-workflow/SKILL.md +++ b/plugins/git/.apm/skills/git-workflow/SKILL.md @@ -8,7 +8,7 @@ description: > agent caller -> `git-orchestrate`. Not Gitea -> `gitea-workflow`. metadata: - version: "1.0.1" + version: "1.0.2" category: git source_keys: - nvie-gitflow-post @@ -60,7 +60,7 @@ owns the request. 4. **Gate destructive operations** — before force-push, branch deletion, rebase, or force-checkout, show what will happen and ask "Proceed?". Cancel gracefully if the user declines. Never supply the confirmation on the user's behalf. Some operations are refusals, not - confirmations: never offer "Proceed?" for a force-push of `main` or `master`. + confirmations — never offer "Proceed?" for a force-push of `main`/`master`. 5. **Invoke the `git-orchestrate` agent** with `operation`, `parameters` (user-provided or inferred), `context` (step 3 plus the session context), and `confirm: true` only for a destructive op the user approved in step 4. diff --git a/plugins/git/agents/git-orchestrate.agent.md b/plugins/git/agents/git-orchestrate.agent.md index afb879e..7d6aaa6 100644 --- a/plugins/git/agents/git-orchestrate.agent.md +++ b/plugins/git/agents/git-orchestrate.agent.md @@ -40,7 +40,7 @@ Sub-skills carry their own local copies of these rules for humans who invoke the When invoked, you: 1. Parse the incoming workflow request (operation type, parameters, context overrides) -2. Check safety gates: if the operation is destructive (force-push, branch deletion, rebase with history loss, force-checkout) and the request lacks explicit `confirm: true`, fail immediately with "requires explicit confirmation"; force-push to `main`/`master` is refused outright regardless of `confirm` +2. Check safety gates: a destructive operation (force-push, branch deletion, history-losing rebase, force-checkout) without `confirm: true` fails immediately with "requires explicit confirmation"; force-push to `main`/`master` is refused outright regardless of `confirm` 3. Route to the appropriate domain skill: `git-commits`, `git-branches`, `git-history`, `git-submodules`, `git-worktrees`, `git-remotes` 4. Manage session context: carry forward the current branch, workflow intent, and configuration, passing explicitly to each skill 5. Handle error recovery: for recoverable failures (merge conflicts, push rejections, auth issues), attempt automatic recovery; if unrecoverable, fail gracefully with actionable diagnostics diff --git a/plugins/git/skills/git-branches/SKILL.md b/plugins/git/skills/git-branches/SKILL.md index 20bf965..e38514f 100644 --- a/plugins/git/skills/git-branches/SKILL.md +++ b/plugins/git/skills/git-branches/SKILL.md @@ -9,7 +9,7 @@ description: > Not a Gitea remote's branches -> `gitea-branches`. metadata: - version: "1.0.3" + version: "1.0.4" category: git source_keys: - context7-git-htmldocs @@ -22,7 +22,7 @@ metadata: - **Uncommitted changes abort a switch.** `git switch` refuses rather than clobbering conflicting local edits. Offer to stash and retry — forcing the checkout past it is how work disappears. - **A branch and a tag can carry the same name.** Detect it before acting — `git branch --list ` (bare, not `rtk`: rtk prints a phantom `* ` line even on no match, which reports every name as ambiguous) and `rtk git tag --list `; output from both means the name is ambiguous. Prefer `git switch` over `git checkout`, and where a command accepts either ref, disambiguate with `refs/heads/` or `refs/tags/`. -- **`main` and `master` are a refusal, not a gate.** Force-pushing, force-deleting, or renaming them is rejected even when the caller passes `confirm: true` — no flag makes the remote's history recoverable. Offer a new branch instead. +- **`main`/`master` are a refusal, not a gate.** Force-pushing, force-deleting, or renaming either is rejected even with `confirm: true` — no flag recovers the remote's history. Offer a new branch instead. ## Step 1 — Determine the branching pattern diff --git a/plugins/git/skills/git-commits/SKILL.md b/plugins/git/skills/git-commits/SKILL.md index 296ec18..145bb79 100644 --- a/plugins/git/skills/git-commits/SKILL.md +++ b/plugins/git/skills/git-commits/SKILL.md @@ -8,7 +8,7 @@ description: > Not branch lifecycle -> `git-branches`. metadata: - version: "0.1.5" + version: "0.1.6" category: git source_keys: - conventional-commits-spec @@ -22,7 +22,7 @@ allowed-tools: Bash ## Gotchas - **Run git as `rtk git `, never bare `git`** — org convention, in `&&` chains too, except where a skill's Gotchas name a specific bare-git case (interactive rebase here). -- **Refuse to force-push `main`/`master`** — a rewrite leaves the branch diverged and the reflex is to force it back; safe only where nobody else has based work on it. +- **Refuse to force-push `main`/`master`.** A rewrite diverges the branch and the reflex is to force it back — safe only where nobody else has based work on it. - **`reset --hard` is a confirmation gate, not a default.** It overwrites the working tree, and uncommitted edits it discards were never in git, so no reflog recovers them. Name what will be lost and offer a stash first. - **Never add `--no-verify`** — using it when a hook fails bypasses the QA gate the pipeline depends on. Only on the user's explicit demand, with a warning. diff --git a/plugins/git/skills/git-commits/references/rewrite-history.md b/plugins/git/skills/git-commits/references/rewrite-history.md index 793f2bb..d25b22c 100644 --- a/plugins/git/skills/git-commits/references/rewrite-history.md +++ b/plugins/git/skills/git-commits/references/rewrite-history.md @@ -6,14 +6,14 @@ source_keys: # Rewriting existing commits -Every flow on this page rewrites history. None of them runs before the caller has explicitly approved it, and none is followed by a force-push to `main`/`master` — refuse that and explain why instead. +Every flow here rewrites history. None runs without explicit approval, and none ends in a force-push to `main`/`master` — refuse that and explain why. ## Amend the last commit 1. Stage the new changes, or the changes that undo something. 2. Run `rtk git commit --amend`, adding `--no-edit` when the message stays as it is. 3. If the message should change, show the current one and prompt for the replacement. -4. The branch has now diverged from its remote. Amending is safe only on a branch nobody else has based work on; on `main`/`master`, refuse the force-push and explain, rather than warning and proceeding. +4. The branch has diverged from its remote. Amending is safe only where nobody else has based work on it; on `main`/`master`, refuse the force-push and explain rather than warn and proceed. ## Fold a commit into an earlier one (autosquash — preferred) @@ -50,9 +50,8 @@ date without a merge commit. 4. `rtk git rebase ` — for example `rtk git rebase main`. Use `rtk git rebase --onto ` to replay only the commits after ``, which is how a branch started from the wrong base gets moved. -5. The branch has now diverged from its remote. It needs - `--force-with-lease --force-if-includes` to push, never a bare `--force`, and never on - `main`/`master` — refuse that and explain. +5. The branch has diverged from its remote. Push needs `--force-with-lease --force-if-includes`, + never a bare `--force` — and never on `main`/`master`; refuse that and explain. ## Move the branch pointer back (`git reset`) diff --git a/plugins/git/skills/git-remotes/SKILL.md b/plugins/git/skills/git-remotes/SKILL.md index e21ddf3..5ef896a 100644 --- a/plugins/git/skills/git-remotes/SKILL.md +++ b/plugins/git/skills/git-remotes/SKILL.md @@ -10,7 +10,7 @@ description: > Not submodule pointers -> `git-submodules`. metadata: - version: "1.0.2" + version: "1.0.3" category: git source_keys: - git-scm-remote-docs @@ -28,7 +28,7 @@ metadata: ## Step 1 — Clear the force-push gate -`main` and `master` are a hard refusal: decline a force-push targeting either, whatever confirmation accompanies it, because no local approval can restore what the remote loses. On any other branch, `rtk git push --force` and `-f` run only after the caller passes `confirm: true` for that specific push — for a human caller, prompt instead of failing. +`main`/`master` are a hard refusal: decline a force-push to either regardless of confirmation — no local approval restores what the remote loses. Elsewhere, `rtk git push --force`/`-f` run only after `confirm: true` for that specific push; for a human caller, prompt instead of failing. ## Step 2 — Dispatch diff --git a/plugins/git/skills/git-workflow/SKILL.md b/plugins/git/skills/git-workflow/SKILL.md index 07ce074..528904d 100644 --- a/plugins/git/skills/git-workflow/SKILL.md +++ b/plugins/git/skills/git-workflow/SKILL.md @@ -8,7 +8,7 @@ description: > agent caller -> `git-orchestrate`. Not Gitea -> `gitea-workflow`. metadata: - version: "1.0.1" + version: "1.0.2" category: git source_keys: - nvie-gitflow-post @@ -60,7 +60,7 @@ owns the request. 4. **Gate destructive operations** — before force-push, branch deletion, rebase, or force-checkout, show what will happen and ask "Proceed?". Cancel gracefully if the user declines. Never supply the confirmation on the user's behalf. Some operations are refusals, not - confirmations: never offer "Proceed?" for a force-push of `main` or `master`. + confirmations — never offer "Proceed?" for a force-push of `main`/`master`. 5. **Invoke the `git-orchestrate` agent** with `operation`, `parameters` (user-provided or inferred), `context` (step 3 plus the session context), and `confirm: true` only for a destructive op the user approved in step 4. diff --git a/plugins/gitea/.apm/skills/gitea-branches/SKILL.md b/plugins/gitea/.apm/skills/gitea-branches/SKILL.md index 47c113a..820a55e 100644 --- a/plugins/gitea/.apm/skills/gitea-branches/SKILL.md +++ b/plugins/gitea/.apm/skills/gitea-branches/SKILL.md @@ -23,19 +23,19 @@ allowed-tools: Bash mcp__gitea__list_branches mcp__gitea__create_branch mcp__git ## Gotchas -- **404 often means 403.** Gitea masks permission errors as not-found; on an unexpected one, check token scope before reporting a branch or commit missing. -- **Nothing auto-paginates.** `list_branches` and `list_commits` return one page; iterate `page` until the returned count is below `per_page`. +- **404 can mean 403.** Gitea masks permission errors as not-found — check token scope before reporting a branch or commit missing. +- **Nothing auto-paginates.** `list_branches`/`list_commits` return one page — iterate `page` until the count is below `per_page`. - **`delete_branch` has no force-push guard.** Treat deleting a protected branch as a hard refusal unless the user explicitly confirms it in the conversation. Check `protected` from `list_branches` first — a protected branch need not be named `main`. ## Step 1 — Resolve owner and repo -Before any tool call, extract `owner` and `repo` from the git remote: +Extract `owner` and `repo` from the git remote before any tool call — `get_me` and `list_my_repos` are blocked under this skill's token scope, so the remote is the only source: ```bash rtk git remote get-url origin ``` -`get_me` and `list_my_repos` are blocked under the token scope this skill assumes, so the remote is the only source. If origin is not set or the URL is not a Gitea URL, stop and report: "No Gitea remote found — set origin to your Gitea instance URL." +No origin, or not a Gitea URL: stop and report "No Gitea remote found — set origin to your Gitea instance URL." ## Step 2 — Dispatch diff --git a/plugins/gitea/.apm/skills/gitea-branches/references/branches.md b/plugins/gitea/.apm/skills/gitea-branches/references/branches.md index d4643a3..4e66709 100644 --- a/plugins/gitea/.apm/skills/gitea-branches/references/branches.md +++ b/plugins/gitea/.apm/skills/gitea-branches/references/branches.md @@ -29,8 +29,7 @@ list_branches owner: repo: **Response:** one object per branch: `name`, `protected` (bool), `commit_sha` (present when the underlying commit data is available). -Paginate if you need the full list (see Gotchas in SKILL.md) — iterate `page` until the returned -count is less than `per_page`. +Paginate for the full list (see Gotchas) — iterate `page` until the count is less than `per_page`. ## `create_branch` diff --git a/plugins/gitea/.apm/skills/gitea-files/SKILL.md b/plugins/gitea/.apm/skills/gitea-files/SKILL.md index 26265da..0923b56 100644 --- a/plugins/gitea/.apm/skills/gitea-files/SKILL.md +++ b/plugins/gitea/.apm/skills/gitea-files/SKILL.md @@ -11,7 +11,7 @@ compatibility: Requires the Gitea MCP server configured with a token scoped to a is not actually required for any of this domain's five tools. metadata: - version: "1.0.0" + version: "1.0.1" category: gitea source_keys: - gitea-mcp-repo @@ -23,7 +23,7 @@ allowed-tools: mcp__gitea__get_file_contents mcp__gitea__get_dir_contents mcp__g ## Gotchas -- **A 404 may mean an under-scoped token, not a missing path.** Every tool here gates on `write:repository`, and Gitea masks insufficient scope as 404. Check scopes first. +- **404 may mean an under-scoped token, not a missing path.** These tools gate on `write:repository`; check scope before concluding the path is missing. - **Reads take `ref` (`tree_sha` on `get_repository_tree`), writes take `branch_name`.** One concept, three names — carry the wrong key and the branch is dropped. - **`content` is base64 both ways — except under `withLines: true`.** Encode before a write, decode after a read; but with `withLines: true` `content` is already plain JSON text and the reported `"encoding": "base64"` is a lie. Decoding it yields garbage. diff --git a/plugins/gitea/.apm/skills/gitea-files/references/reading.md b/plugins/gitea/.apm/skills/gitea-files/references/reading.md index db2aa15..f10366a 100644 --- a/plugins/gitea/.apm/skills/gitea-files/references/reading.md +++ b/plugins/gitea/.apm/skills/gitea-files/references/reading.md @@ -32,8 +32,8 @@ size. No recursion, no content, no `sha`. `get_repository_tree(owner, repo, tree_sha, recursive)`. Set `recursive: true` to walk subdirectories in one call. -The response sets `truncated: true` when one page does not hold every entry. Page through with -`page`/`per_page` (defaults `1` and `30`) until a page returns fewer entries than `per_page`. +The response sets `truncated: true` when one page doesn't hold every entry — page with +`page`/`per_page` (defaults `1`/`30`) until a page returns fewer than `per_page`. ## Neither listing is a SHA source for a write @@ -44,7 +44,6 @@ the canonical path for a write's SHA: one call returns the decoded content and t ## A 404 that is really a 403 -These reads gate on `write:repository`, not on read access alone, and some Gitea endpoints answer -an under-scoped token with 404 instead of 403 so they do not leak whether the resource exists. A -404 on a path you are confident about is a scope problem until proven otherwise — check the token's -configured scopes before concluding the file or directory does not exist. +These reads gate on `write:repository`; an under-scoped token gets 404 instead of 403 so the +endpoint doesn't leak whether the resource exists. On a path you're confident about, check token +scope before concluding it doesn't exist. diff --git a/plugins/gitea/.apm/skills/gitea-issues/SKILL.md b/plugins/gitea/.apm/skills/gitea-issues/SKILL.md index ab785f8..cc9ce3a 100644 --- a/plugins/gitea/.apm/skills/gitea-issues/SKILL.md +++ b/plugins/gitea/.apm/skills/gitea-issues/SKILL.md @@ -14,7 +14,7 @@ compatibility: Requires Gitea MCP server configured with write:issue and write:r metadata: category: integration - version: "0.1.4" + version: "0.1.5" source_keys: - gitea-mcp-repo - gitea-mcp-slim-go @@ -29,17 +29,17 @@ allowed-tools: Bash mcp__gitea__list_issues mcp__gitea__issue_read mcp__gitea__i - **`list_issues` mixes in PRs unless you filter.** Issues and PRs share one number space; pass `type: "issues"` to exclude PRs (or `"pulls"`). `is_pull` is returned only by `issue_read method: "get"` — on a list item the only tell is `html_url`'s path segment (`/issues/` vs `/pulls/`). - **Label IDs and names are not interchangeable.** `issue_write` takes numeric IDs only; `list_issues` and `search_issues` filter by name; `issue_read "get"` returns names but `"get_labels"` returns full objects with IDs. Resolve via `gitea-labels-milestones` unless the caller named exact labels. - **A merge does not itself close the issue.** Gitea has no close-on-merge event, but a `Fixes #N` in the merged commits can, depending on merge style (`gitea-prs`). Re-read its state after a merge before closing it manually. -- **A 404 may really be a 403.** Gitea hides permission errors as not-found — check the token's `write:issue` scope before concluding the issue does not exist. +- **404 may mean 403.** Gitea hides permission errors as not-found — check `write:issue` scope before concluding the issue doesn't exist. ## Step 1 — Resolve owner and repo -An orchestrating caller may pass `owner` and `repo` in already, and the `search` row is cross-repository and needs only a query — both skip this step. Otherwise, before any tool call: +Skip if an orchestrating caller already passed `owner`/`repo` in, or the action is `search` (cross-repository, needs only a query). Otherwise, before any tool call: ```bash rtk git remote get-url origin ``` -If origin is unset or the URL is not a Gitea URL, stop and report: "No Gitea remote found — set origin to your Gitea instance URL." +No origin, or not a Gitea URL: stop and report "No Gitea remote found — set origin to your Gitea instance URL." ## Step 2 — Dispatch diff --git a/plugins/gitea/.apm/skills/gitea-issues/references/issues.md b/plugins/gitea/.apm/skills/gitea-issues/references/issues.md index fe4248b..6292633 100644 --- a/plugins/gitea/.apm/skills/gitea-issues/references/issues.md +++ b/plugins/gitea/.apm/skills/gitea-issues/references/issues.md @@ -45,7 +45,7 @@ list_issues owner: repo: state: "open" type: "issues" `updated_at`, and optionally `labels` (`[]string`), `milestone` (`{id, title}`), `ref`, `deadline`. Body and `closed_at` are omitted from list responses — call `issue_read method: "get"` for those. -Paginate with `page`/`per_page` until the returned count is less than `per_page`. +Paginate: `page`/`per_page`, stop once the count is below `per_page`. ## `issue_read` diff --git a/plugins/gitea/.apm/skills/gitea-labels-milestones/SKILL.md b/plugins/gitea/.apm/skills/gitea-labels-milestones/SKILL.md index 6619a29..aa744ce 100644 --- a/plugins/gitea/.apm/skills/gitea-labels-milestones/SKILL.md +++ b/plugins/gitea/.apm/skills/gitea-labels-milestones/SKILL.md @@ -16,30 +16,30 @@ metadata: - gitea-mcp-slim-go - context7-websites-gitea - context7-gitea-tea-cli - version: "0.1.5" + version: "0.1.6" allowed-tools: Bash mcp__gitea__label_read mcp__gitea__label_write mcp__gitea__milestone_read mcp__gitea__milestone_write --- ## Gotchas -- **Applying a label takes a numeric ID, but issue/PR responses slim labels down to name strings.** An issue's existing labels yield no IDs — resolve name → ID with `label_read`. -- **`pull_request_read` returns `milestone` as a bare title string** where `issue_read` returns `{id, title}` — recover the milestone's ID by listing milestones and matching the title. -- **Never assume a `Kind/*`/`Priority/*`/`Status/*` scope is exclusive — read each label's own `exclusive` field.** `list_repo_labels` returns it on every repo label, so it is always *readable* per label; `label_write` documents it as "(org only)" because it is only *settable* through the org create methods. Where it is `true` Gitea enforces one-per-scope itself, and replacing rather than stacking on a label whose `exclusive` is `false` destroys a valid label. +- **Applying a label needs a numeric ID; issue/PR responses give only name strings.** Resolve name → ID with `label_read` first. +- **`pull_request_read` returns `milestone` as a bare title string, `issue_read` as `{id, title}`.** Recover the ID by listing milestones and matching the title. +- **Never assume a `Kind/*`/`Priority/*`/`Status/*` scope is exclusive — read each label's `exclusive` field.** `list_repo_labels` always returns it; `label_write` can only set it via org create methods ("org only"). `true` means Gitea enforces one-per-scope; replacing instead of stacking on a `false` label destroys a valid one. ## Step 1 — Resolve owner, repo and org -Before any tool call, extract `owner` and `repo` from the git remote (skip this if an orchestrating caller already passed them in): +Extract `owner` and `repo` from the git remote before any tool call (skip if an orchestrating caller already passed them in): ```bash rtk git remote get-url origin ``` -If origin is not set or the URL is not a Gitea URL, stop and report: "No Gitea remote found — set origin to your Gitea instance URL." +No origin, or not a Gitea URL: stop and report "No Gitea remote found — set origin to your Gitea instance URL." -The `*_org_label*` methods take `org`, not `owner`/`repo`. Pass that same `owner` as `org` — it is the org name whenever the owner is an organisation, and the remote URL does not say whether it is one. +The `*_org_label*` methods take `org`, not `owner`/`repo`. Pass that same `owner` as `org` — it's the org name whenever the owner is an organisation, which the remote URL doesn't say. -Read the failure text before interpreting it. `list_org_labels` needs the `read:organization` token scope, which this skill's declared scopes (`write:issue`, `write:repository`) do not carry, so it fails with `token does not have at least one of required scope(s), required=[read:organization]` *before* it ever determines org-vs-user. Report that: the org pool went unchecked, not empty. Only a not-found response is evidence the owner is a user account with no org pool. +Read the failure text before interpreting it: `list_org_labels` needs `read:organization`, which this skill's declared scopes don't carry, so it fails with a scope error *before* it ever checks org-vs-user. Report the unchecked scope, not an empty pool — only a genuine not-found means the owner is a user account with no org pool. ## Step 2 — Dispatch @@ -58,6 +58,6 @@ Read the failure text before interpreting it. `list_org_labels` needs the `read: | Update / close a milestone | `milestone_write` | `"update"` | | Delete a milestone | `milestone_write` | `"delete"` | -Every list method paginates manually — `per_page` defaults to 30, so iterate `page: 1, 2, ...` until a page returns fewer results than `per_page`. A truncated list silently breaks name → ID resolution. +Every list method paginates manually (`per_page` default 30) — iterate `page: 1, 2, ...` until a page returns fewer than `per_page`. A truncated list silently breaks name → ID resolution. If the task is a label operation, read `references/labels.md`; if a milestone operation, read `references/milestones.md`. If the label to apply has to be derived from conversation context rather than named, read `references/label-inference.md`. diff --git a/plugins/gitea/.apm/skills/gitea-labels-milestones/references/labels.md b/plugins/gitea/.apm/skills/gitea-labels-milestones/references/labels.md index 172cea2..ef44e16 100644 --- a/plugins/gitea/.apm/skills/gitea-labels-milestones/references/labels.md +++ b/plugins/gitea/.apm/skills/gitea-labels-milestones/references/labels.md @@ -51,8 +51,8 @@ runtime error from Gitea rather than a client-side validation error. label_read method: "list_repo_labels" owner: repo: per_page: 50 ``` -Paginate (`page: 1, 2, ...`) until the returned count is less than `per_page`. This is the only way -to build a complete name → ID map — there is no lookup-by-name endpoint. +Paginate (`page: 1, 2, ...`) until the count is below `per_page` — the only way to build a complete +name → ID map, since there's no lookup-by-name endpoint. Every returned repo label carries its own `exclusive` boolean, so exclusivity is always *readable* per repo label. That does not contradict `label_write`'s schema, which annotates `exclusive` as diff --git a/plugins/gitea/.apm/skills/gitea-prs/SKILL.md b/plugins/gitea/.apm/skills/gitea-prs/SKILL.md index 37ab15d..5b0ea59 100644 --- a/plugins/gitea/.apm/skills/gitea-prs/SKILL.md +++ b/plugins/gitea/.apm/skills/gitea-prs/SKILL.md @@ -19,7 +19,7 @@ metadata: - gitea-mcp-slim-go - context7-websites-gitea - context7-gitea-tea-cli - version: "0.1.3" + version: "0.1.4" allowed-tools: Bash mcp__gitea__list_pull_requests mcp__gitea__pull_request_read mcp__gitea__pull_request_write mcp__gitea__pull_request_review_write --- @@ -31,13 +31,13 @@ allowed-tools: Bash mcp__gitea__list_pull_requests mcp__gitea__pull_request_read ## Step 1 — Resolve owner and repo -Extract them from the git remote before any tool call, skipping this when an orchestrating caller already passed them in: +Extract from the git remote before any tool call, skipping this when an orchestrating caller already passed them in: ```bash rtk git remote get-url origin ``` -If origin is not set or the URL is not a Gitea URL, stop and report: "No Gitea remote found — set origin to your Gitea instance URL." +No origin, or not a Gitea URL: stop and report "No Gitea remote found — set origin to your Gitea instance URL." ## Step 2 — Dispatch diff --git a/plugins/gitea/.apm/skills/gitea-releases/SKILL.md b/plugins/gitea/.apm/skills/gitea-releases/SKILL.md index f55cd7d..6e7ccc6 100644 --- a/plugins/gitea/.apm/skills/gitea-releases/SKILL.md +++ b/plugins/gitea/.apm/skills/gitea-releases/SKILL.md @@ -14,7 +14,7 @@ compatibility: Requires Gitea MCP server configured with a token with write:repo metadata: category: integration - version: "0.1.1" + version: "0.1.2" source_keys: - gitea-mcp-repo - gitea-mcp-slim-go @@ -33,13 +33,13 @@ allowed-tools: Bash mcp__gitea__list_releases mcp__gitea__get_release mcp__gitea ## Step 1 — Resolve owner and repo -`owner` and `repo` are required on every tool below. Extract them from the git remote, unless an orchestrating caller passed them in already: +`owner` and `repo` are required on every tool below. Extract from the git remote, unless an orchestrating caller already passed them in: ```bash rtk git remote get-url origin ``` -If origin is not set or the URL is not a Gitea URL, stop and report: "No Gitea remote found — set origin to your Gitea instance URL." +No origin, or not a Gitea URL: stop and report "No Gitea remote found — set origin to your Gitea instance URL." ## Step 2 — Dispatch @@ -68,6 +68,6 @@ These four are mutually exclusive — pick the one row the request lands on. | Create a release | Call `create_release` with `tag_name`, `target`, `title`, and `is_draft`/`is_pre_release` set explicitly — never left to default. This surface carries no update or edit tool, so a wrong flag is repairable only by delete-and-recreate (`references/conventions.md`). A separate `create_tag` is only needed to tag a commit without wrapping it in a release — whether `create_release` creates a missing tag is unconfirmed, so verify with `get_tag`. | | Delete a release | Resolve the numeric `id` per the first Gotcha, confirm intent, then call `delete_release`. The tag survives. | | Delete a tag along with its release | Delete the release first, then call `delete_tag` — confirm both are intended before proceeding, since each is irreversible on its own. | -| List every page | Loop `page: 1, 2, 3...` until a response returns fewer than `per_page` entries. Nothing here auto-paginates. | +| List every page | Loop `page: 1, 2, 3...` until a response returns fewer than `per_page` entries — nothing auto-paginates. | If exact input params or response field shapes are needed, read `references/call-signatures.md`. If the caller raises semver tag naming, draft/prerelease semantics, release-notes sourcing, or how a release relates to its tag, read `references/conventions.md`. diff --git a/plugins/gitea/.apm/skills/gitea-releases/references/call-signatures.md b/plugins/gitea/.apm/skills/gitea-releases/references/call-signatures.md index b81a6f9..46ca117 100644 --- a/plugins/gitea/.apm/skills/gitea-releases/references/call-signatures.md +++ b/plugins/gitea/.apm/skills/gitea-releases/references/call-signatures.md @@ -70,7 +70,6 @@ id, tag_name, target, title, body, draft, prerelease, html_url, author, created_ ## Pagination -None of the list tools auto-paginate. To collect a full result set, call with `page: 1`, then -`page: 2`, etc., stopping when a page returns fewer items than `per_page`. `list_releases` and -`list_tags` default `per_page` to 20 — lower than the 30-default used by most other gitea-mcp list -tools, so a caller assuming 30 will under-count pages needed for a fixed total. +Nothing auto-paginates. Loop `page: 1, 2, ...` until a page returns fewer items than `per_page`. +`list_releases`/`list_tags` default `per_page` to 20, not the usual 30 — assuming 30 under-counts +pages needed. diff --git a/plugins/gitea/.apm/skills/gitea-workflow/SKILL.md b/plugins/gitea/.apm/skills/gitea-workflow/SKILL.md index b0d64f6..1528c14 100644 --- a/plugins/gitea/.apm/skills/gitea-workflow/SKILL.md +++ b/plugins/gitea/.apm/skills/gitea-workflow/SKILL.md @@ -13,7 +13,7 @@ compatibility: Requires Gitea MCP server configured with a token; delegates all metadata: category: integration - version: "0.1.3" + version: "0.1.4" source_keys: - gitea-mcp-repo - gitea-mcp-slim-go diff --git a/plugins/gitea/.apm/skills/gitea-workflow/references/number-resolution.md b/plugins/gitea/.apm/skills/gitea-workflow/references/number-resolution.md index 357514b..ea8c8e6 100644 --- a/plugins/gitea/.apm/skills/gitea-workflow/references/number-resolution.md +++ b/plugins/gitea/.apm/skills/gitea-workflow/references/number-resolution.md @@ -14,7 +14,7 @@ The user has referenced a bare number without saying "issue" or "PR" (e.g. "what 2. Check the response's `is_pull` field: - `true` → it's a PR. Invoke `gitea-prs` for full PR detail (status, diff, reviews as appropriate to the request) and present that instead. - `false` or absent → it's an issue. Present the issue detail already retrieved. -3. If the resolution call 404s, don't conclude the number doesn't exist. Gitea hides permission errors as not-found (documented in `gitea-issues`' Gotchas), so report the 404 and suggest verifying the token carries `write:issue` rather than reporting "no such issue or PR." +3. A 404 here isn't proof the number doesn't exist — Gitea hides permission errors as not-found (see `gitea-issues` Gotchas). Report the 404 and suggest checking the token's `write:issue` scope rather than reporting "no such issue or PR." If the user stated an action on the number rather than asking about it, resolution is only step one: hand the action, with the resolved domain, to `gitea-issues` or `gitea-prs` to carry out. Presenting detail is not a substitute for performing the write. diff --git a/plugins/gitea/skills/gitea-branches/SKILL.md b/plugins/gitea/skills/gitea-branches/SKILL.md index 47c113a..820a55e 100644 --- a/plugins/gitea/skills/gitea-branches/SKILL.md +++ b/plugins/gitea/skills/gitea-branches/SKILL.md @@ -23,19 +23,19 @@ allowed-tools: Bash mcp__gitea__list_branches mcp__gitea__create_branch mcp__git ## Gotchas -- **404 often means 403.** Gitea masks permission errors as not-found; on an unexpected one, check token scope before reporting a branch or commit missing. -- **Nothing auto-paginates.** `list_branches` and `list_commits` return one page; iterate `page` until the returned count is below `per_page`. +- **404 can mean 403.** Gitea masks permission errors as not-found — check token scope before reporting a branch or commit missing. +- **Nothing auto-paginates.** `list_branches`/`list_commits` return one page — iterate `page` until the count is below `per_page`. - **`delete_branch` has no force-push guard.** Treat deleting a protected branch as a hard refusal unless the user explicitly confirms it in the conversation. Check `protected` from `list_branches` first — a protected branch need not be named `main`. ## Step 1 — Resolve owner and repo -Before any tool call, extract `owner` and `repo` from the git remote: +Extract `owner` and `repo` from the git remote before any tool call — `get_me` and `list_my_repos` are blocked under this skill's token scope, so the remote is the only source: ```bash rtk git remote get-url origin ``` -`get_me` and `list_my_repos` are blocked under the token scope this skill assumes, so the remote is the only source. If origin is not set or the URL is not a Gitea URL, stop and report: "No Gitea remote found — set origin to your Gitea instance URL." +No origin, or not a Gitea URL: stop and report "No Gitea remote found — set origin to your Gitea instance URL." ## Step 2 — Dispatch diff --git a/plugins/gitea/skills/gitea-branches/references/branches.md b/plugins/gitea/skills/gitea-branches/references/branches.md index d4643a3..4e66709 100644 --- a/plugins/gitea/skills/gitea-branches/references/branches.md +++ b/plugins/gitea/skills/gitea-branches/references/branches.md @@ -29,8 +29,7 @@ list_branches owner: repo: **Response:** one object per branch: `name`, `protected` (bool), `commit_sha` (present when the underlying commit data is available). -Paginate if you need the full list (see Gotchas in SKILL.md) — iterate `page` until the returned -count is less than `per_page`. +Paginate for the full list (see Gotchas) — iterate `page` until the count is less than `per_page`. ## `create_branch` diff --git a/plugins/gitea/skills/gitea-files/SKILL.md b/plugins/gitea/skills/gitea-files/SKILL.md index 26265da..0923b56 100644 --- a/plugins/gitea/skills/gitea-files/SKILL.md +++ b/plugins/gitea/skills/gitea-files/SKILL.md @@ -11,7 +11,7 @@ compatibility: Requires the Gitea MCP server configured with a token scoped to a is not actually required for any of this domain's five tools. metadata: - version: "1.0.0" + version: "1.0.1" category: gitea source_keys: - gitea-mcp-repo @@ -23,7 +23,7 @@ allowed-tools: mcp__gitea__get_file_contents mcp__gitea__get_dir_contents mcp__g ## Gotchas -- **A 404 may mean an under-scoped token, not a missing path.** Every tool here gates on `write:repository`, and Gitea masks insufficient scope as 404. Check scopes first. +- **404 may mean an under-scoped token, not a missing path.** These tools gate on `write:repository`; check scope before concluding the path is missing. - **Reads take `ref` (`tree_sha` on `get_repository_tree`), writes take `branch_name`.** One concept, three names — carry the wrong key and the branch is dropped. - **`content` is base64 both ways — except under `withLines: true`.** Encode before a write, decode after a read; but with `withLines: true` `content` is already plain JSON text and the reported `"encoding": "base64"` is a lie. Decoding it yields garbage. diff --git a/plugins/gitea/skills/gitea-files/references/reading.md b/plugins/gitea/skills/gitea-files/references/reading.md index db2aa15..f10366a 100644 --- a/plugins/gitea/skills/gitea-files/references/reading.md +++ b/plugins/gitea/skills/gitea-files/references/reading.md @@ -32,8 +32,8 @@ size. No recursion, no content, no `sha`. `get_repository_tree(owner, repo, tree_sha, recursive)`. Set `recursive: true` to walk subdirectories in one call. -The response sets `truncated: true` when one page does not hold every entry. Page through with -`page`/`per_page` (defaults `1` and `30`) until a page returns fewer entries than `per_page`. +The response sets `truncated: true` when one page doesn't hold every entry — page with +`page`/`per_page` (defaults `1`/`30`) until a page returns fewer than `per_page`. ## Neither listing is a SHA source for a write @@ -44,7 +44,6 @@ the canonical path for a write's SHA: one call returns the decoded content and t ## A 404 that is really a 403 -These reads gate on `write:repository`, not on read access alone, and some Gitea endpoints answer -an under-scoped token with 404 instead of 403 so they do not leak whether the resource exists. A -404 on a path you are confident about is a scope problem until proven otherwise — check the token's -configured scopes before concluding the file or directory does not exist. +These reads gate on `write:repository`; an under-scoped token gets 404 instead of 403 so the +endpoint doesn't leak whether the resource exists. On a path you're confident about, check token +scope before concluding it doesn't exist. diff --git a/plugins/gitea/skills/gitea-issues/SKILL.md b/plugins/gitea/skills/gitea-issues/SKILL.md index ab785f8..cc9ce3a 100644 --- a/plugins/gitea/skills/gitea-issues/SKILL.md +++ b/plugins/gitea/skills/gitea-issues/SKILL.md @@ -14,7 +14,7 @@ compatibility: Requires Gitea MCP server configured with write:issue and write:r metadata: category: integration - version: "0.1.4" + version: "0.1.5" source_keys: - gitea-mcp-repo - gitea-mcp-slim-go @@ -29,17 +29,17 @@ allowed-tools: Bash mcp__gitea__list_issues mcp__gitea__issue_read mcp__gitea__i - **`list_issues` mixes in PRs unless you filter.** Issues and PRs share one number space; pass `type: "issues"` to exclude PRs (or `"pulls"`). `is_pull` is returned only by `issue_read method: "get"` — on a list item the only tell is `html_url`'s path segment (`/issues/` vs `/pulls/`). - **Label IDs and names are not interchangeable.** `issue_write` takes numeric IDs only; `list_issues` and `search_issues` filter by name; `issue_read "get"` returns names but `"get_labels"` returns full objects with IDs. Resolve via `gitea-labels-milestones` unless the caller named exact labels. - **A merge does not itself close the issue.** Gitea has no close-on-merge event, but a `Fixes #N` in the merged commits can, depending on merge style (`gitea-prs`). Re-read its state after a merge before closing it manually. -- **A 404 may really be a 403.** Gitea hides permission errors as not-found — check the token's `write:issue` scope before concluding the issue does not exist. +- **404 may mean 403.** Gitea hides permission errors as not-found — check `write:issue` scope before concluding the issue doesn't exist. ## Step 1 — Resolve owner and repo -An orchestrating caller may pass `owner` and `repo` in already, and the `search` row is cross-repository and needs only a query — both skip this step. Otherwise, before any tool call: +Skip if an orchestrating caller already passed `owner`/`repo` in, or the action is `search` (cross-repository, needs only a query). Otherwise, before any tool call: ```bash rtk git remote get-url origin ``` -If origin is unset or the URL is not a Gitea URL, stop and report: "No Gitea remote found — set origin to your Gitea instance URL." +No origin, or not a Gitea URL: stop and report "No Gitea remote found — set origin to your Gitea instance URL." ## Step 2 — Dispatch diff --git a/plugins/gitea/skills/gitea-issues/references/issues.md b/plugins/gitea/skills/gitea-issues/references/issues.md index fe4248b..6292633 100644 --- a/plugins/gitea/skills/gitea-issues/references/issues.md +++ b/plugins/gitea/skills/gitea-issues/references/issues.md @@ -45,7 +45,7 @@ list_issues owner: repo: state: "open" type: "issues" `updated_at`, and optionally `labels` (`[]string`), `milestone` (`{id, title}`), `ref`, `deadline`. Body and `closed_at` are omitted from list responses — call `issue_read method: "get"` for those. -Paginate with `page`/`per_page` until the returned count is less than `per_page`. +Paginate: `page`/`per_page`, stop once the count is below `per_page`. ## `issue_read` diff --git a/plugins/gitea/skills/gitea-labels-milestones/SKILL.md b/plugins/gitea/skills/gitea-labels-milestones/SKILL.md index 6619a29..aa744ce 100644 --- a/plugins/gitea/skills/gitea-labels-milestones/SKILL.md +++ b/plugins/gitea/skills/gitea-labels-milestones/SKILL.md @@ -16,30 +16,30 @@ metadata: - gitea-mcp-slim-go - context7-websites-gitea - context7-gitea-tea-cli - version: "0.1.5" + version: "0.1.6" allowed-tools: Bash mcp__gitea__label_read mcp__gitea__label_write mcp__gitea__milestone_read mcp__gitea__milestone_write --- ## Gotchas -- **Applying a label takes a numeric ID, but issue/PR responses slim labels down to name strings.** An issue's existing labels yield no IDs — resolve name → ID with `label_read`. -- **`pull_request_read` returns `milestone` as a bare title string** where `issue_read` returns `{id, title}` — recover the milestone's ID by listing milestones and matching the title. -- **Never assume a `Kind/*`/`Priority/*`/`Status/*` scope is exclusive — read each label's own `exclusive` field.** `list_repo_labels` returns it on every repo label, so it is always *readable* per label; `label_write` documents it as "(org only)" because it is only *settable* through the org create methods. Where it is `true` Gitea enforces one-per-scope itself, and replacing rather than stacking on a label whose `exclusive` is `false` destroys a valid label. +- **Applying a label needs a numeric ID; issue/PR responses give only name strings.** Resolve name → ID with `label_read` first. +- **`pull_request_read` returns `milestone` as a bare title string, `issue_read` as `{id, title}`.** Recover the ID by listing milestones and matching the title. +- **Never assume a `Kind/*`/`Priority/*`/`Status/*` scope is exclusive — read each label's `exclusive` field.** `list_repo_labels` always returns it; `label_write` can only set it via org create methods ("org only"). `true` means Gitea enforces one-per-scope; replacing instead of stacking on a `false` label destroys a valid one. ## Step 1 — Resolve owner, repo and org -Before any tool call, extract `owner` and `repo` from the git remote (skip this if an orchestrating caller already passed them in): +Extract `owner` and `repo` from the git remote before any tool call (skip if an orchestrating caller already passed them in): ```bash rtk git remote get-url origin ``` -If origin is not set or the URL is not a Gitea URL, stop and report: "No Gitea remote found — set origin to your Gitea instance URL." +No origin, or not a Gitea URL: stop and report "No Gitea remote found — set origin to your Gitea instance URL." -The `*_org_label*` methods take `org`, not `owner`/`repo`. Pass that same `owner` as `org` — it is the org name whenever the owner is an organisation, and the remote URL does not say whether it is one. +The `*_org_label*` methods take `org`, not `owner`/`repo`. Pass that same `owner` as `org` — it's the org name whenever the owner is an organisation, which the remote URL doesn't say. -Read the failure text before interpreting it. `list_org_labels` needs the `read:organization` token scope, which this skill's declared scopes (`write:issue`, `write:repository`) do not carry, so it fails with `token does not have at least one of required scope(s), required=[read:organization]` *before* it ever determines org-vs-user. Report that: the org pool went unchecked, not empty. Only a not-found response is evidence the owner is a user account with no org pool. +Read the failure text before interpreting it: `list_org_labels` needs `read:organization`, which this skill's declared scopes don't carry, so it fails with a scope error *before* it ever checks org-vs-user. Report the unchecked scope, not an empty pool — only a genuine not-found means the owner is a user account with no org pool. ## Step 2 — Dispatch @@ -58,6 +58,6 @@ Read the failure text before interpreting it. `list_org_labels` needs the `read: | Update / close a milestone | `milestone_write` | `"update"` | | Delete a milestone | `milestone_write` | `"delete"` | -Every list method paginates manually — `per_page` defaults to 30, so iterate `page: 1, 2, ...` until a page returns fewer results than `per_page`. A truncated list silently breaks name → ID resolution. +Every list method paginates manually (`per_page` default 30) — iterate `page: 1, 2, ...` until a page returns fewer than `per_page`. A truncated list silently breaks name → ID resolution. If the task is a label operation, read `references/labels.md`; if a milestone operation, read `references/milestones.md`. If the label to apply has to be derived from conversation context rather than named, read `references/label-inference.md`. diff --git a/plugins/gitea/skills/gitea-labels-milestones/references/labels.md b/plugins/gitea/skills/gitea-labels-milestones/references/labels.md index 172cea2..ef44e16 100644 --- a/plugins/gitea/skills/gitea-labels-milestones/references/labels.md +++ b/plugins/gitea/skills/gitea-labels-milestones/references/labels.md @@ -51,8 +51,8 @@ runtime error from Gitea rather than a client-side validation error. label_read method: "list_repo_labels" owner: repo: per_page: 50 ``` -Paginate (`page: 1, 2, ...`) until the returned count is less than `per_page`. This is the only way -to build a complete name → ID map — there is no lookup-by-name endpoint. +Paginate (`page: 1, 2, ...`) until the count is below `per_page` — the only way to build a complete +name → ID map, since there's no lookup-by-name endpoint. Every returned repo label carries its own `exclusive` boolean, so exclusivity is always *readable* per repo label. That does not contradict `label_write`'s schema, which annotates `exclusive` as diff --git a/plugins/gitea/skills/gitea-prs/SKILL.md b/plugins/gitea/skills/gitea-prs/SKILL.md index 37ab15d..5b0ea59 100644 --- a/plugins/gitea/skills/gitea-prs/SKILL.md +++ b/plugins/gitea/skills/gitea-prs/SKILL.md @@ -19,7 +19,7 @@ metadata: - gitea-mcp-slim-go - context7-websites-gitea - context7-gitea-tea-cli - version: "0.1.3" + version: "0.1.4" allowed-tools: Bash mcp__gitea__list_pull_requests mcp__gitea__pull_request_read mcp__gitea__pull_request_write mcp__gitea__pull_request_review_write --- @@ -31,13 +31,13 @@ allowed-tools: Bash mcp__gitea__list_pull_requests mcp__gitea__pull_request_read ## Step 1 — Resolve owner and repo -Extract them from the git remote before any tool call, skipping this when an orchestrating caller already passed them in: +Extract from the git remote before any tool call, skipping this when an orchestrating caller already passed them in: ```bash rtk git remote get-url origin ``` -If origin is not set or the URL is not a Gitea URL, stop and report: "No Gitea remote found — set origin to your Gitea instance URL." +No origin, or not a Gitea URL: stop and report "No Gitea remote found — set origin to your Gitea instance URL." ## Step 2 — Dispatch diff --git a/plugins/gitea/skills/gitea-releases/SKILL.md b/plugins/gitea/skills/gitea-releases/SKILL.md index f55cd7d..6e7ccc6 100644 --- a/plugins/gitea/skills/gitea-releases/SKILL.md +++ b/plugins/gitea/skills/gitea-releases/SKILL.md @@ -14,7 +14,7 @@ compatibility: Requires Gitea MCP server configured with a token with write:repo metadata: category: integration - version: "0.1.1" + version: "0.1.2" source_keys: - gitea-mcp-repo - gitea-mcp-slim-go @@ -33,13 +33,13 @@ allowed-tools: Bash mcp__gitea__list_releases mcp__gitea__get_release mcp__gitea ## Step 1 — Resolve owner and repo -`owner` and `repo` are required on every tool below. Extract them from the git remote, unless an orchestrating caller passed them in already: +`owner` and `repo` are required on every tool below. Extract from the git remote, unless an orchestrating caller already passed them in: ```bash rtk git remote get-url origin ``` -If origin is not set or the URL is not a Gitea URL, stop and report: "No Gitea remote found — set origin to your Gitea instance URL." +No origin, or not a Gitea URL: stop and report "No Gitea remote found — set origin to your Gitea instance URL." ## Step 2 — Dispatch @@ -68,6 +68,6 @@ These four are mutually exclusive — pick the one row the request lands on. | Create a release | Call `create_release` with `tag_name`, `target`, `title`, and `is_draft`/`is_pre_release` set explicitly — never left to default. This surface carries no update or edit tool, so a wrong flag is repairable only by delete-and-recreate (`references/conventions.md`). A separate `create_tag` is only needed to tag a commit without wrapping it in a release — whether `create_release` creates a missing tag is unconfirmed, so verify with `get_tag`. | | Delete a release | Resolve the numeric `id` per the first Gotcha, confirm intent, then call `delete_release`. The tag survives. | | Delete a tag along with its release | Delete the release first, then call `delete_tag` — confirm both are intended before proceeding, since each is irreversible on its own. | -| List every page | Loop `page: 1, 2, 3...` until a response returns fewer than `per_page` entries. Nothing here auto-paginates. | +| List every page | Loop `page: 1, 2, 3...` until a response returns fewer than `per_page` entries — nothing auto-paginates. | If exact input params or response field shapes are needed, read `references/call-signatures.md`. If the caller raises semver tag naming, draft/prerelease semantics, release-notes sourcing, or how a release relates to its tag, read `references/conventions.md`. diff --git a/plugins/gitea/skills/gitea-releases/references/call-signatures.md b/plugins/gitea/skills/gitea-releases/references/call-signatures.md index b81a6f9..46ca117 100644 --- a/plugins/gitea/skills/gitea-releases/references/call-signatures.md +++ b/plugins/gitea/skills/gitea-releases/references/call-signatures.md @@ -70,7 +70,6 @@ id, tag_name, target, title, body, draft, prerelease, html_url, author, created_ ## Pagination -None of the list tools auto-paginate. To collect a full result set, call with `page: 1`, then -`page: 2`, etc., stopping when a page returns fewer items than `per_page`. `list_releases` and -`list_tags` default `per_page` to 20 — lower than the 30-default used by most other gitea-mcp list -tools, so a caller assuming 30 will under-count pages needed for a fixed total. +Nothing auto-paginates. Loop `page: 1, 2, ...` until a page returns fewer items than `per_page`. +`list_releases`/`list_tags` default `per_page` to 20, not the usual 30 — assuming 30 under-counts +pages needed. diff --git a/plugins/gitea/skills/gitea-workflow/SKILL.md b/plugins/gitea/skills/gitea-workflow/SKILL.md index b0d64f6..1528c14 100644 --- a/plugins/gitea/skills/gitea-workflow/SKILL.md +++ b/plugins/gitea/skills/gitea-workflow/SKILL.md @@ -13,7 +13,7 @@ compatibility: Requires Gitea MCP server configured with a token; delegates all metadata: category: integration - version: "0.1.3" + version: "0.1.4" source_keys: - gitea-mcp-repo - gitea-mcp-slim-go diff --git a/plugins/gitea/skills/gitea-workflow/references/number-resolution.md b/plugins/gitea/skills/gitea-workflow/references/number-resolution.md index 357514b..ea8c8e6 100644 --- a/plugins/gitea/skills/gitea-workflow/references/number-resolution.md +++ b/plugins/gitea/skills/gitea-workflow/references/number-resolution.md @@ -14,7 +14,7 @@ The user has referenced a bare number without saying "issue" or "PR" (e.g. "what 2. Check the response's `is_pull` field: - `true` → it's a PR. Invoke `gitea-prs` for full PR detail (status, diff, reviews as appropriate to the request) and present that instead. - `false` or absent → it's an issue. Present the issue detail already retrieved. -3. If the resolution call 404s, don't conclude the number doesn't exist. Gitea hides permission errors as not-found (documented in `gitea-issues`' Gotchas), so report the 404 and suggest verifying the token carries `write:issue` rather than reporting "no such issue or PR." +3. A 404 here isn't proof the number doesn't exist — Gitea hides permission errors as not-found (see `gitea-issues` Gotchas). Report the 404 and suggest checking the token's `write:issue` scope rather than reporting "no such issue or PR." If the user stated an action on the number rather than asking about it, resolution is only step one: hand the action, with the resolved domain, to `gitea-issues` or `gitea-prs` to carry out. Presenting detail is not a substitute for performing the write. -- 2.43.0 From e647f1453593976290ded884f564c61c78451e73 Mon Sep 17 00:00:00 2001 From: Defame1297 Date: Sat, 12 Sep 2026 19:59:18 +0000 Subject: [PATCH 07/84] chore: delete the check-manifests pre-commit hook MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Six pre-push hooks were validating overlapping sets of the same manifests. check-manifests (marketplace.json/plugin.json path checks) is redundant with validate-plugins (claude plugin validate) and apm-pack-check-clean, which already cover the same ground. Deletes the check-manifests hook entry, scripts/check-manifests.sh (282 lines), and tests/test-check-manifests.sh (771 lines). scripts/lib/marketplace-plugins.sh is kept — it is still sourced by sync-plugin-content.sh. Updates the now-stale check-manifests.sh mentions and hook counts in README.md and docs/spec/gates.md. The apm-audit-ci and apm-marketplace-check hooks named in the same finding are left untouched — the audit flags them as needing a separate decision. Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_01YR2CjVumUbEGWcMikcoXBD --- .pre-commit-config.yaml | 9 - README.md | 2 +- SIMPLIFICATION-AUDIT.md | 3 +- docs/spec/gates.md | 15 +- scripts/check-manifests.sh | 282 ------------- tests/test-check-manifests.sh | 771 ---------------------------------- 6 files changed, 10 insertions(+), 1072 deletions(-) delete mode 100755 scripts/check-manifests.sh delete mode 100644 tests/test-check-manifests.sh diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 71b9b2a..31283f0 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -75,15 +75,6 @@ repos: pass_filenames: false always_run: true - - id: check-manifests - name: Check plugin manifests - description: Validate marketplace.json and plugin.json paths - entry: bash scripts/check-manifests.sh - language: system - stages: [pre-push] - pass_filenames: false - always_run: true - - id: check-plugin-content-sync name: Check plugin content sync description: Verify each plugin's flat skills/agents/commands/hooks/hooks.json mirror is in sync with .apm/ -- Claude Code has no .apm/ awareness so this compiled mirror must stay current (see issue #90) diff --git a/README.md b/README.md index 80ebf16..92054f4 100644 --- a/README.md +++ b/README.md @@ -31,7 +31,7 @@ Install all of these before setting up. Each one is a hard dependency of a git h | Tool | Why | Install | | --- | --- | --- | | `apm` CLI | Four pre-push hooks shell out to it (`apm-marketplace-check`, `apm-audit-ci`, `apm-pack-check-clean`, and `check-plugin-content-sync` via `scripts/sync-plugin-content.sh`) | The `apm-install` skill, or `curl -sSL https://aka.ms/apm-unix \| sh`. Verify with `apm --version` | -| `jq` | Required by `scripts/check-manifests.sh` and `scripts/sync-plugin-content.sh`, both pre-push | Your package manager | +| `jq` | Required by `scripts/sync-plugin-content.sh`, pre-push | Your package manager | | `python3` + PyYAML | Required by `scripts/skill-size-check.sh` (the `skill-size-check` pre-commit hook), which reads folded YAML frontmatter | `python3` is usually present — pre-commit is itself a Python application. `pip install pyyaml` if the hook reports PyYAML missing | | `vale` | Required by the `vale-audit-prefilter-skill` / `-agent` pre-commit hooks and the `check-vale-style-sync` pre-push hook | `brew install vale` (macOS), `snap install vale` (Linux), `choco install vale` (Windows), or https://vale.sh/docs/vale-cli/installation/ | | `claude` CLI | Required by the `validate-plugins` and `validate-marketplace` pre-push hooks | Claude Code | diff --git a/SIMPLIFICATION-AUDIT.md b/SIMPLIFICATION-AUDIT.md index 83b8af7..98aa181 100644 --- a/SIMPLIFICATION-AUDIT.md +++ b/SIMPLIFICATION-AUDIT.md @@ -59,7 +59,8 @@ Five suites account for 215 s of 276 s. Three of those five (sync-plugin-content This is the area you named as hardest to understand and slowest. Root cause: most pre-push hooks exist to keep two copies of something in sync, or to re-validate what another hook already validates. -1. **Six hooks validate overlapping sets of the same manifests.** `check-manifests`, `validate-plugins`, `validate-marketplace`, `apm-pack-check-clean`, `apm-marketplace-check`, `apm-audit-ci`. Keep the two `claude plugin validate` hooks plus `apm-pack-check-clean`. Delete `check-manifests` (282 lines + 771 test lines; its `lib/marketplace-plugins.sh` stays because `sync-plugin-content.sh` sources it). `apm-audit-ci` spends 12 s confirming that manifests `apm pack` already parses do parse; drop or keep on that basis. Move the network-dependent `apm-marketplace-check` to a release checklist. Effort S. +1. **Six hooks validate overlapping sets of the same manifests.** `check-manifests`, `validate-plugins`, `validate-marketplace`, `apm-pack-check-clean`, `apm-marketplace-check`, `apm-audit-ci`. Keep the two `claude plugin validate` hooks plus `apm-pack-check-clean`. ~~Delete `check-manifests` (282 lines + 771 test lines; its `lib/marketplace-plugins.sh` stays because `sync-plugin-content.sh` sources it).~~ `apm-audit-ci` spends 12 s confirming that manifests `apm pack` already parses do parse; drop or keep on that basis. Move the network-dependent `apm-marketplace-check` to a release checklist. Effort S. + > **Done (2026-09-12):** see commit `9051d14` on `docs/simplification-audit`. Deleted the `check-manifests` pre-commit hook entry, `scripts/check-manifests.sh` (282 lines), and `tests/test-check-manifests.sh` (771 lines); kept `scripts/lib/marketplace-plugins.sh`, still sourced by `sync-plugin-content.sh`. Updated the now-stale `check-manifests.sh` mentions in `README.md` and `docs/spec/gates.md` (hook table row and hook counts). The `apm-audit-ci` and `apm-marketplace-check` decisions in this finding remain open — out of scope for this change. 2. **Four "keep two copies in sync" gates: 1,100 script lines + 1,600 test lines.** Each one is a symptom of duplication that could be removed instead of guarded: - `check-vale-style-sync`: 413 lines + 798 test lines guarding a byte-identical 526-line `vale-wrap.sh` and style directory copied between skill-audit and agent-audit. About 350 of its lines run Vale glob probes against the hook file patterns. Disappears if the two audit skills merge (finding 14); the probes belong in `test-vale-wrap.sh`. diff --git a/docs/spec/gates.md b/docs/spec/gates.md index f16c0f8..a66f591 100644 --- a/docs/spec/gates.md +++ b/docs/spec/gates.md @@ -21,31 +21,30 @@ Install hooks via `pc-run`, wiring **all three stages**. This repo's `.pre-commi `default_install_hook_types`, so a plain install silently skips `commit-msg` (Conventional Commits) and `pre-push` (everything below). -The pre-push command reports **16** hooks, not 14. The extra two are pre-commit's own `meta` hooks, +The pre-push command reports **15** hooks, not 13. The extra two are pre-commit's own `meta` hooks, `check-hooks-apply` and `check-useless-excludes`: they declare no `stages:`, so they run at every stage including this one. Both are declared in this repo's `.pre-commit-config.yaml` like everything -else — what separates them is `repo: meta` (pre-commit's own built-ins) from `repo: local`. Fourteen +else — what separates them is `repo: meta` (pre-commit's own built-ins) from `repo: local`. Thirteen is the count of hooks this repo authors itself. -**The caveat: one of those 14 is a silent no-op under that invocation.** +**The caveat: one of those 13 is a silent no-op under that invocation.** `check-release-needed` exits 0 immediately unless `PRE_COMMIT_REMOTE_BRANCH` equals `refs/heads/main`, and pre-commit exports that variable only from the real pre-push git hook during an actual `git push`. Running the stage by hand — or from a CI runner — therefore reports it `Passed` having checked nothing. That is by design for feature branches — pushing WIP must not be blocked on cutting a premature tag — but it means `--hook-stage pre-push --all-files` is a full -rehearsal of 13 hooks and a skip of the fourteenth. The script's own header records the same gap for +rehearsal of 12 hooks and a skip of the thirteenth. The script's own header records the same gap for a PR merged through Gitea's merge button, where no local push happens at all. ## The pre-push gate -Fourteen hooks, grouped below by what they guard rather than by the order `.pre-commit-config.yaml` declares them in. +Thirteen hooks, grouped below by what they guard rather than by the order `.pre-commit-config.yaml` declares them in. **Core checks** | Hook | Guards | |---|---| | `run-tests` | `bash tests/run-tests.sh --strict` — the whole suite, skips fatal (see [Tests](#tests)) | -| `check-manifests` | `marketplace.json` and `plugin.json` paths resolve (needs `jq`) | **Generated-content drift gates** @@ -92,8 +91,8 @@ and `check-plugin-content-sync` (via `scripts/sync-plugin-content.sh`, which wra first and third are bare `apm …` entries and the second is a `bash -c` loop calling `apm` once per package, so without the CLI the push dies with an unhelpful "command not found". Install with `apm-install`, or `curl -sSL https://aka.ms/apm-unix | sh`; verify with `apm --version`. `jq` is -needed by `scripts/check-manifests.sh` and `scripts/sync-plugin-content.sh` — those at least fail -loudly (`Error: jq is required but not installed`). +needed by `scripts/sync-plugin-content.sh` — it at least fails loudly (`Error: jq is required but +not installed`). ## Skill and agent context gates (ADR-0020) diff --git a/scripts/check-manifests.sh b/scripts/check-manifests.sh deleted file mode 100755 index 957883a..0000000 --- a/scripts/check-manifests.sh +++ /dev/null @@ -1,282 +0,0 @@ -#!/usr/bin/env bash -set -euo pipefail - -# Validates that marketplace.json's local plugin entries resolve to a real directory -# containing a .claude-plugin/plugin.json. Run from repo root or pass REPO_ROOT as arg. -# -# Per ADR-0015, apm.yml is the authoring source and .claude-plugin/plugin.json is -# compiled output with no skills/hooks/mcpServers/agents pointer fields (apm's plugin.json -# builder deliberately omits them -- Claude Code auto-discovers those convention -# directories, so listing them would be redundant/invalid). For a plugin with an .apm/ -# directory, this script no longer checks those pointer fields itself; that's -# scripts/sync-plugin-content.sh --check's job (drift between .apm/ and the flat -# plugin-root mirror), wired as its own pre-push hook. -# -# sync-plugin-content.sh --check explicitly skips any plugin directory lacking .apm/ -# (an apm-native package it has nothing to compile), so that delegation leaves a real -# gap for a non-apm plugin whose hand-authored plugin.json still uses the old -# skills/hooks/mcpServers/agents pointer-field convention: nothing would check whether -# those paths resolve. The fallback block below restores that check, but only for -# plugins without .apm/ -- apm-native plugins keep relying on the delegation above so -# the two checks don't duplicate (and disagree) on the same manifest. -# -# Both of the above walk marketplace.json -> disk. Nothing walked disk -> marketplace, -# so a plugins// directory that never made it into marketplace.json was invisible -# to every marketplace-derived gate at once (this script and sync-plugin-content.sh -# --all both derive their plugin set from marketplace.json). The final block below -# closes that direction: per ADR-0015 marketplace.json is compiled output of root -# apm.yml's marketplace.packages[], so an on-disk apm package with no entry is -# compiled-output drift of exactly the kind ADR-0017 wires pre-push gates for -- and it -# is the same plugin set the validate-plugins pre-commit hook already globs as -# plugins/*/. -# -# Every pass above reads its plugin set out of marketplace.json, so anything that makes -# that file yield nothing -- absent, unparseable, a non-object root, or an entry whose -# `source` is neither a path string nor a remote object -- used to read as "clean" -# rather than "unchecked". The same is true one level down, of a per-plugin -# .claude-plugin/plugin.json that does not parse: it aborted the walk mid-loop and left -# every later plugin silently unchecked. The guards below turn each of those into an -# explicit, attributable failure instead, because a vacuous pass is the one result a gate -# must never produce. - -# Hard error, not a `|| pwd` fallback, for the reason spelled out in -# scripts/sync-marketplace-mirror.sh: every path below hangs off REPO_ROOT, and the -# exit-0 path is "nothing on disk and no manifest", so a REPO_ROOT pointing somewhere -# that is not this repo reports "clean" over a tree it never looked at. Run this from -# an empty directory outside any worktree and the fallback made that the literal -# outcome -- rev-parse failed, REPO_ROOT became $PWD, no plugins/ and no -# marketplace.json were found, exit 0, silent. -if [[ -n "${1:-}" ]]; then - REPO_ROOT="$1" -elif ! REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null)" || [[ -z "$REPO_ROOT" ]]; then - echo "Error: not inside a git worktree -- cannot locate the repository root, and guessing \$PWD would let this check report \"clean\" over a tree it never inspected. Run it from within the repository, or pass the repo root as an argument." >&2 - exit 1 -fi -FAIL=0 - -err() { echo " FAIL: $1" >&2; FAIL=$((FAIL + 1)); } - -if ! command -v jq &>/dev/null; then - echo "Error: jq is required but not installed" >&2 - exit 1 -fi - -MARKETPLACE="$REPO_ROOT/.claude-plugin/marketplace.json" - -SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" -# Repo-root-relative, not script-dir-relative -- see tests/run-tests.sh for why. -# shellcheck source=scripts/lib/marketplace-plugins.sh -source "$SCRIPT_DIR/lib/marketplace-plugins.sh" - -# Candidate plugin directories on disk. The trigger is any of the three markers that -# make a directory a plugin rather than scratch -- apm.yml (the ADR-0015 authoring -# source), .apm/ (its content tree), or a compiled .claude-plugin/plugin.json. Matching -# all three keeps this set aligned with the plugins/*/ glob the validate-plugins -# pre-commit hook uses, which is the disagreement the disk -> marketplace pass below -# exists to close; a directory with none of them is scratch and stays out of scope. -# -# It is collected before the marketplace is read because a missing marketplace.json is -# only "nothing to check" when there is also nothing on disk to check against it. -PLUGIN_DIRS=() -for candidate in "$REPO_ROOT"/plugins/*/; do - candidate="${candidate%/}" - [[ -d "$candidate" ]] || continue - if [[ ! -f "$candidate/apm.yml" && ! -d "$candidate/.apm" && ! -f "$candidate/.claude-plugin/plugin.json" ]]; then - continue - fi - PLUGIN_DIRS+=("$candidate") -done - -# An absent marketplace.json used to exit 0 unconditionally -- the same empty-set-reads- -# as-pass shape this script's other passes were fixed for. Per ADR-0015 the manifest is -# compiled output of root apm.yml's marketplace.packages[], so its absence alongside -# on-disk packages is drift, not an opt-out: it leaves every marketplace-derived gate -# (this one and sync-plugin-content.sh --all) walking an empty plugin set in silence. -if [[ ! -f "$MARKETPLACE" ]]; then - if [[ ${#PLUGIN_DIRS[@]} -eq 0 ]]; then - exit 0 - fi - listing="" - # Guarded expansion even though the check above makes an empty array unreachable - # here: bash 3.2 under `set -u` aborts on a bare expansion of an empty array, and - # tests/test-vale-wrap.sh's bash32_glob scan is line-based, so a guard two lines up - # cannot clear it. Same form as the disk -> marketplace loop below. - for candidate in ${PLUGIN_DIRS[@]+"${PLUGIN_DIRS[@]}"}; do - listing+="${listing:+, }${candidate#"$REPO_ROOT"/}" - done - err ".claude-plugin/marketplace.json does not exist, but plugins/ holds ${#PLUGIN_DIRS[@]} plugin directory/ies ($listing) — every marketplace-derived check (this one, and sync-plugin-content.sh --all) silently walks an empty plugin set without it. Recompile the manifests from root apm.yml with \`apm pack\`." - echo "Manifest check failed: $FAIL error(s)" >&2 - exit 1 -fi - -# Preconditions the marketplace walk below cannot report on itself: it runs inside a -# process substitution, so an abort in there is swallowed (see the helper's comment). -assert_marketplace_manifest_usable "$MARKETPLACE" - -# Validates one plugin.json pointer field against disk, for the non-apm fallback below. -# -# check_pointer_field -# -# test_flag is `test`'s: -d where only a directory is meaningful, -e otherwise. -# -# Per the vendored host docs (plugins/kyberforge/docs/research/docs/ -# claude-code-plugins/configuration.md and .../github-copilot-plugins/configuration.md) -# these fields are legally `string | string[] | object`. Reading them with -# `jq -r ".$field // empty"` collapsed the array and object shapes to their -# pretty-printed JSON text, which then matched no path on disk -- a manifest that -# resolves fine reported as broken. Reading `.skills | length` was worse than wrong: on -# a (legal) string value it returned the character count, and the `.skills[$i]` that -# followed aborted the whole script mid-loop under `set -e` with no summary line, so -# every plugin later in the marketplace went unchecked. -# -# The bare `$(jq ...)` assignments below are safe only because the caller has already -# established that $manifest parses AND that its root is an object (see the -# precondition in the marketplace walk). Do not call this without that check: `set -e` -# turns any jq failure in here into the same silent mid-loop abort described above. -check_pointer_field() { - local name="$1" plugin_dir="$2" field="$3" test_flag="$4" - local manifest="$plugin_dir/.claude-plugin/plugin.json" - local field_type count i elem_type - - field_type="$(jq -r ".${field} | type" "$manifest")" - case "$field_type" in - null) ;; - # An inline definition (a hooks or mcpServers object written straight into the - # manifest) declares no path, so there is nothing on disk to resolve. - object) ;; - string) - check_pointer_path "$name" "$plugin_dir" "$field" "$(jq -r ".${field}" "$manifest")" "$test_flag" - ;; - array) - count="$(jq ".${field} | length" "$manifest")" - for ((i = 0; i < count; i++)); do - elem_type="$(jq -r ".${field}[$i] | type" "$manifest")" - if [[ "$elem_type" != "string" ]]; then - err "plugin '$name': ${field}[$i] must be a path string, got $elem_type" - continue - fi - check_pointer_path "$name" "$plugin_dir" "$field" "$(jq -r ".${field}[$i]" "$manifest")" "$test_flag" - done - ;; - *) - err "plugin '$name': $field must be a path string, an array of path strings, or an inline object, got $field_type" - ;; - esac -} - -check_pointer_path() { - local name="$1" plugin_dir="$2" field="$3" ref="$4" test_flag="$5" - local full_path="$plugin_dir/$ref" - full_path="${full_path%/}" - if ! test "$test_flag" "$full_path"; then - err "plugin '$name': $field path not found: $ref" - fi -} - -# Every local plugin directory marketplace.json claimed, canonicalized, so the -# disk -> marketplace pass below can tell "listed" from "unlisted" regardless of how -# the `source:` string was spelled (./plugins/x, plugins/x, plugins/x/). -SEEN_PLUGIN_DIRS=() - -while IFS=$'\t' read -r name plugin_dir; do - source_rel="${plugin_dir#"$REPO_ROOT"/}" - - if [[ ! -d "$plugin_dir" ]]; then - err "plugin '$name': source directory not found: $source_rel" - continue - fi - # -P so a plugin directory reached through a symlink compares equal to the same - # directory reached directly; the disk-side walk below resolves the same way. - SEEN_PLUGIN_DIRS+=("$(cd "$plugin_dir" && pwd -P)") - - manifest="$plugin_dir/.claude-plugin/plugin.json" - if [[ ! -f "$manifest" ]]; then - err "plugin '$name': .claude-plugin/plugin.json not found in $source_rel" - continue - fi - - # apm-native plugin: pointer-field validation is sync-plugin-content.sh --check's - # job (see header comment above). - [[ -d "$plugin_dir/.apm" ]] && continue - - # Precondition for check_pointer_field, which reads the manifest with bare - # `field_type="$(jq ... )"` assignments. Under `set -e` a jq failure in one of - # those aborts the whole script mid-loop: rc=5, a raw `jq: parse error` and no - # `Manifest check failed:` summary, with every later plugin left unchecked -- - # the same failure class the marketplace's own `jq empty` precondition closes, - # for a file that is equally generated output. Both shapes have to be caught - # here: `jq empty` passes on a valid non-object document like `[]` or `123`, and - # it is the `.skills` lookup on such a root ("Cannot index array with string") - # that aborts, not the parse. - if ! jq empty "$manifest" >/dev/null 2>&1; then - err "plugin '$name': .claude-plugin/plugin.json is not valid JSON — it is compiled output, so recompile it with \`apm pack\`." - continue - fi - manifest_type="$(jq -r 'type' "$manifest")" - if [[ "$manifest_type" != "object" ]]; then - err "plugin '$name': .claude-plugin/plugin.json is a JSON $manifest_type at its top level; expected an object." - continue - fi - - # Fallback for a non-apm plugin: validate that any skills/hooks/mcpServers/agents - # pointer fields in its hand-authored plugin.json still resolve to real paths. - # skills/agents point at directories; hooks/mcpServers may point at a file. - check_pointer_field "$name" "$plugin_dir" skills -d - check_pointer_field "$name" "$plugin_dir" agents -e - check_pointer_field "$name" "$plugin_dir" hooks -e - check_pointer_field "$name" "$plugin_dir" mcpServers -e -done < <(list_marketplace_local_plugins "$REPO_ROOT" "$MARKETPLACE") - -# Disk -> marketplace, over the PLUGIN_DIRS candidate set collected above. -# -# A candidate counts as listed if it is either a directory some local entry pointed at -# (path match, canonicalized above) or a directory whose name matches a REMOTE entry's -# name. The name axis exists only for a plugin vendored on disk but declared with the -# remote-object `source:` shape: list_marketplace_local_plugins deliberately skips those, -# so a path-only match would report a missing entry that is in fact already there. -# -# It is restricted to non-string sources on purpose. Applied to local entries too, the -# name axis silently rescues genuine orphans, because a local entry's name need not equal -# the basename of the directory it points at: an entry named "beta" pointing at -# ./plugins/alpha would mark an unrelated, entirely unlisted plugins/beta/ as listed. -# Local entries already have an exact path to match on, so they need no name fallback. -# -# The select is an allowlist of the object shape, not a denylist of the string one -- -# see list_marketplace_remote_plugin_names in scripts/lib/marketplace-plugins.sh, which -# owns it, and tests/test-check-manifests.sh, which exercises it directly against -# malformed entries rather than through this caller (where -# assert_marketplace_manifest_usable rejects them first, and so would mask a regression -# in the select itself). -MARKETPLACE_NAMES=() -while IFS= read -r entry_name; do - [[ -n "$entry_name" ]] && MARKETPLACE_NAMES+=("$entry_name") -done < <(list_marketplace_remote_plugin_names "$MARKETPLACE") - -for candidate in ${PLUGIN_DIRS[@]+"${PLUGIN_DIRS[@]}"}; do - candidate_abs="$(cd "$candidate" && pwd -P)" - candidate_name="$(basename "$candidate")" - listed=0 - for seen in ${SEEN_PLUGIN_DIRS[@]+"${SEEN_PLUGIN_DIRS[@]}"}; do - if [[ "$seen" == "$candidate_abs" ]]; then - listed=1 - break - fi - done - if [[ $listed -eq 0 ]]; then - for entry_name in ${MARKETPLACE_NAMES[@]+"${MARKETPLACE_NAMES[@]}"}; do - if [[ "$entry_name" == "$candidate_name" ]]; then - listed=1 - break - fi - done - fi - - if [[ $listed -eq 0 ]]; then - err "plugin directory '${candidate#"$REPO_ROOT"/}' has no entry in .claude-plugin/marketplace.json — it is skipped by every marketplace-derived check (this one, and sync-plugin-content.sh --all) while still being globbed by the validate-plugins hook. Add it to root apm.yml's marketplace.packages[] and recompile the manifests." - fi -done - -if [[ $FAIL -gt 0 ]]; then - echo "Manifest check failed: $FAIL error(s)" >&2 - exit 1 -fi diff --git a/tests/test-check-manifests.sh b/tests/test-check-manifests.sh deleted file mode 100644 index 2c76648..0000000 --- a/tests/test-check-manifests.sh +++ /dev/null @@ -1,771 +0,0 @@ -#!/usr/bin/env bash -set -euo pipefail - -REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" -SCRIPT="$REPO_ROOT/scripts/check-manifests.sh" -PASS=0 -FAIL=0 - -pass() { echo " PASS: $1"; PASS=$((PASS + 1)); } -fail() { echo " FAIL: $1"; FAIL=$((FAIL + 1)); } - -# Several distinct faults all end in exit 1, and the bugs fixed below were precisely -# about the WRONG one being reported (a corrupt manifest blamed on six unlisted plugin -# directories, a legal manifest blamed for unresolvable paths). Exit-code-only -# assertions cannot see that, so these cases assert on the message text. -RUN_OUT="" -RUN_RC=0 -run_script() { RUN_OUT="$(bash "$SCRIPT" "$1" 2>&1)" && RUN_RC=0 || RUN_RC=$?; } - -# assert_fails_with