From fa4c1ea68470ceaafb048057e67bec6046c12b4a Mon Sep 17 00:00:00 2001 From: Eduardo Marquez <55303379+DocksDocks@users.noreply.github.com> Date: Fri, 23 Oct 2026 18:40:15 -0300 Subject: [PATCH 1/2] docs: remove the pre-GitHub plan archive and old point-in-time records Plans have been GitHub issues since b976562e, and nothing reads the frozen archive or the dated records, so they only add noise. This removes docs/plans/ (121 files), docs/release-evidence/, the two dated audits, docs/PLAN-QUEUE.md, and the launch entry that served the archive. docs/AGENTS.md now says that docs/ holds only AGENTS.md and PLAN.md and that plans, audits, and release evidence go in issues and pull requests. Git history keeps every removed file. Refs #106 --- .claude/launch.json | 11 - AGENTS.md | 4 +- docs/AGENTS.md | 21 +- docs/PLAN-QUEUE.md | 23 - docs/PLAN.md | 3 - docs/authoring-audits.md | 78 - docs/optimization-audit-may-2026.md | 338 -- docs/plans/finished/.gitkeep | 0 .../finished/2026-05-12-plan-review-smoke.md | 123 - ...2026-05-12-skills-references-extraction.md | 199 -- ...05-24-foundation-categorization-scoring.md | 152 - .../2026-05-24-html-sidecar-generator.md | 103 - .../2026-05-24-pipelines-to-skills.md | 167 - docs/plans/finished/2026-05-24-scaffold.md | 122 - .../2026-05-24-skill-maintainer-fixes.md | 131 - docs/plans/finished/2026-05-24-tree-skill.md | 161 - .../2026-05-25-agents-validate-warnings.md | 185 - .../2026-05-27-multi-tool-bridge-rename.md | 132 - .../2026-05-27-skill-agent-pipeline-rename.md | 183 - .../2026-05-28-context-tree-loss-guard.md | 144 - ...26-05-28-data-preservation-shared-infra.md | 123 - .../2026-05-28-kit-wording-rollout.md | 125 - ...-03-context-tree-content-accuracy-audit.md | 98 - .../2026-06-03-no-author-scripts-guard.md | 105 - ...6-10-capability-tuning-research-rollout.md | 103 - ...06-10-codex-mirror-native-manifest-note.md | 69 - ...2026-06-10-full-kit-prompt-optimization.md | 92 - .../2026-06-23-improve-audit-grafts.md | 116 - .../2026-06-23-model-tiered-executor-mode.md | 113 - ...06-23-plan-optimizer-integration-claude.md | 196 -- ...-06-23-plan-optimizer-integration-codex.md | 94 - .../2026-06-23-plan-optimizer-integration.md | 273 -- .../2026-06-23-plans-lifecycle-auto-review.md | 152 - .../2026-06-26-cold-handoff-contract.md | 248 -- ...2026-06-27-cold-handoff-contract-stage4.md | 362 -- ...-01-knowledge-format-lint-and-citations.md | 142 - ...026-07-02-session-relay-app-server-push.md | 649 ---- ...026-07-02-session-relay-auto-inbox-push.md | 535 --- .../2026-07-02-session-relay-rust-port.md | 253 -- .../2026-07-02-session-relay-spawn.md | 761 ---- .../2026-07-03-ci-validators-to-mjs.md | 115 - .../2026-07-03-codex-plan-agent-bootstrap.md | 111 - .../finished/2026-07-03-codex-plan-agents.md | 94 - .../2026-07-03-durable-anchors-followups.md | 95 - .../finished/2026-07-03-durable-anchors.md | 168 - .../2026-07-03-effect-kit-migration.md | 155 - .../finished/2026-07-03-executable-claims.md | 99 - .../2026-07-03-okf-knowledge-bundle.md | 127 - .../finished/2026-07-03-plans-v2-md-only.md | 120 - ...2026-07-03-session-relay-auto-discovery.md | 150 - ...2026-07-03-session-relay-cross-tool-bus.md | 246 -- ...7-03-session-relay-per-session-identity.md | 239 -- .../finished/2026-07-05-docks-kit-refresh.md | 239 -- .../finished/2026-07-05-docks-skill-gaps.md | 101 - .../2026-07-05-effect-kit-upgrade-review.md | 214 -- ...2026-07-06-relay-spawn-model-discipline.md | 129 - .../2026-07-07-plan-review-crosscheck.md | 146 - .../2026-07-07-relay-token-efficiency.md | 166 - .../2026-07-10-relay-attach-command.md | 104 - .../2026-07-10-relay-notify-reliability.md | 177 - .../2026-07-10-relay-store-hygiene.md | 152 - .../finished/2026-07-11-relay-live-view.md | 211 -- .../2026-07-12-cross-company-review-policy.md | 274 -- ...-compatibility-final-review-repair-rung.md | 3088 ----------------- ...4-legacy-start-transition-compatibility.md | 636 ---- ...orker-lifecycle-primitives-continuation.md | 257 -- ...elay-worker-lifecycle-primitives-legacy.md | 2995 ---------------- .../2026-07-15-refactor-session-relay-rust.md | 981 ------ .../2026-07-15-relay-worker-fanout.md | 297 -- ...orkflow-model-roles-and-bounded-reviews.md | 604 ---- ...16-plan-review-convergence-and-improver.md | 519 --- ...2026-07-17-completion-reuse-terminal-lf.md | 161 - ...26-07-17-single-gpt-plan-review-default.md | 401 --- ...session-relay-prebuilt-cli-distribution.md | 500 --- ...7-18-target-plugin-ci-and-release-gates.md | 247 -- ...7-19-session-relay-prebuilt-cli-release.md | 644 ---- ...07-22-session-relay-workspace-isolation.md | 646 ---- ...n-relay-linux-workspace-recertification.md | 241 -- ...y-correlated-results-release-completion.md | 132 - ...correlated-results-release-continuation.md | 164 - ...rrelated-results-release-exact-scope-v2.md | 123 - ...-correlated-results-release-exact-scope.md | 135 - ...rrelated-results-release-remediation-v2.md | 106 - ...rrelated-results-release-remediation-v3.md | 107 - ...rrelated-results-release-remediation-v4.md | 126 - ...rrelated-results-release-remediation-v5.md | 87 - ...rrelated-results-release-remediation-v6.md | 105 - ...rrelated-results-release-remediation-v7.md | 91 - ...rrelated-results-release-remediation-v8.md | 84 - ...rrelated-results-release-remediation-v9.md | 130 - ...-correlated-results-release-remediation.md | 111 - ...ession-relay-correlated-results-release.md | 198 -- ...elay-release-binder-repository-proof-v2.md | 69 - ...n-relay-release-binder-repository-proof.md | 64 - ...6-07-28-accepted-planrun-proof-contract.md | 193 -- ...07-28-agent-worktree-lifecycle-strategy.md | 228 -- .../2026-07-28-legacy-retirement-path.md | 207 -- ...28-legacy-schema6-policy-classification.md | 308 -- ...plan-review-controller-failure-recovery.md | 675 ---- ...28-plan-workflow-phases-and-loop-escape.md | 711 ---- ...26-07-28-relay-worktree-portable-layout.md | 421 --- ...correlated-messaging-and-worker-results.md | 335 -- ...ssion-relay-linux-workspace-publication.md | 584 ---- ...8-session-relay-linux-workspace-release.md | 329 -- .../2026-07-30-plan-dispatch-driver.md | 721 ---- .../2026-07-31-plan-evidence-row-scales.md | 283 -- ...07-31-relay-release-instance-separation.md | 567 --- ...2026-07-31-relay-supervisor-socket-stat.md | 236 -- ...2026-08-02-lifecycle-dispatch-integrity.md | 327 -- ...026-08-02-relay-fanout-reaper-reporting.md | 245 -- ...2026-08-02-session-relay-0.15.0-release.md | 770 ---- ...-08-03-plan-lifecycle-plugin-extraction.md | 372 -- .../2026-08-03-step-ids-and-class-budget.md | 523 --- ...ompletion-rehearsal-and-contract-guards.md | 167 - ...2026-08-04-session-relay-0.16.0-release.md | 784 ----- ...lay-0.16.0-terminal-evidence-correction.md | 127 - ...-04-shared-plugin-release-orchestration.md | 183 - ...-05-ci-observability-and-test-contracts.md | 130 - ...026-08-05-plan-execution-queue-contract.md | 174 - ....16.0-correction-plan-terminal-evidence.md | 104 - ...6-08-07-session-relay-custody-deadlines.md | 426 --- ...26-08-07-session-relay-payload-boundary.md | 391 --- ...8-07-session-relay-post-cutover-modules.md | 106 - ...26-08-07-session-relay-quiesce-deadline.md | 155 - ...26-08-07-session-relay-typed-irc-sqlite.md | 128 - ...an-lifecycle-derived-history-navigation.md | 109 - ...-lifecycle-review-and-authority-modules.md | 264 -- ...n-lifecycle-review-dispatch-performance.md | 110 - ...ay-0.16.0-terminal-correction-successor.md | 5 - ...ession-relay-0.16.0-terminal-correction.md | 9 - 130 files changed, 9 insertions(+), 35968 deletions(-) delete mode 100644 .claude/launch.json delete mode 100644 docs/PLAN-QUEUE.md delete mode 100644 docs/authoring-audits.md delete mode 100644 docs/optimization-audit-may-2026.md delete mode 100644 docs/plans/finished/.gitkeep delete mode 100644 docs/plans/finished/2026-05-12-plan-review-smoke.md delete mode 100644 docs/plans/finished/2026-05-12-skills-references-extraction.md delete mode 100644 docs/plans/finished/2026-05-24-foundation-categorization-scoring.md delete mode 100644 docs/plans/finished/2026-05-24-html-sidecar-generator.md delete mode 100644 docs/plans/finished/2026-05-24-pipelines-to-skills.md delete mode 100644 docs/plans/finished/2026-05-24-scaffold.md delete mode 100644 docs/plans/finished/2026-05-24-skill-maintainer-fixes.md delete mode 100644 docs/plans/finished/2026-05-24-tree-skill.md delete mode 100644 docs/plans/finished/2026-05-25-agents-validate-warnings.md delete mode 100644 docs/plans/finished/2026-05-27-multi-tool-bridge-rename.md delete mode 100644 docs/plans/finished/2026-05-27-skill-agent-pipeline-rename.md delete mode 100644 docs/plans/finished/2026-05-28-context-tree-loss-guard.md delete mode 100644 docs/plans/finished/2026-05-28-data-preservation-shared-infra.md delete mode 100644 docs/plans/finished/2026-05-28-kit-wording-rollout.md delete mode 100644 docs/plans/finished/2026-06-03-context-tree-content-accuracy-audit.md delete mode 100644 docs/plans/finished/2026-06-03-no-author-scripts-guard.md delete mode 100644 docs/plans/finished/2026-06-10-capability-tuning-research-rollout.md delete mode 100644 docs/plans/finished/2026-06-10-codex-mirror-native-manifest-note.md delete mode 100644 docs/plans/finished/2026-06-10-full-kit-prompt-optimization.md delete mode 100644 docs/plans/finished/2026-06-23-improve-audit-grafts.md delete mode 100644 docs/plans/finished/2026-06-23-model-tiered-executor-mode.md delete mode 100644 docs/plans/finished/2026-06-23-plan-optimizer-integration-claude.md delete mode 100644 docs/plans/finished/2026-06-23-plan-optimizer-integration-codex.md delete mode 100644 docs/plans/finished/2026-06-23-plan-optimizer-integration.md delete mode 100644 docs/plans/finished/2026-06-23-plans-lifecycle-auto-review.md delete mode 100644 docs/plans/finished/2026-06-26-cold-handoff-contract.md delete mode 100644 docs/plans/finished/2026-06-27-cold-handoff-contract-stage4.md delete mode 100644 docs/plans/finished/2026-07-01-knowledge-format-lint-and-citations.md delete mode 100644 docs/plans/finished/2026-07-02-session-relay-app-server-push.md delete mode 100644 docs/plans/finished/2026-07-02-session-relay-auto-inbox-push.md delete mode 100644 docs/plans/finished/2026-07-02-session-relay-rust-port.md delete mode 100644 docs/plans/finished/2026-07-02-session-relay-spawn.md delete mode 100644 docs/plans/finished/2026-07-03-ci-validators-to-mjs.md delete mode 100644 docs/plans/finished/2026-07-03-codex-plan-agent-bootstrap.md delete mode 100644 docs/plans/finished/2026-07-03-codex-plan-agents.md delete mode 100644 docs/plans/finished/2026-07-03-durable-anchors-followups.md delete mode 100644 docs/plans/finished/2026-07-03-durable-anchors.md delete mode 100644 docs/plans/finished/2026-07-03-effect-kit-migration.md delete mode 100644 docs/plans/finished/2026-07-03-executable-claims.md delete mode 100644 docs/plans/finished/2026-07-03-okf-knowledge-bundle.md delete mode 100644 docs/plans/finished/2026-07-03-plans-v2-md-only.md delete mode 100644 docs/plans/finished/2026-07-03-session-relay-auto-discovery.md delete mode 100644 docs/plans/finished/2026-07-03-session-relay-cross-tool-bus.md delete mode 100644 docs/plans/finished/2026-07-03-session-relay-per-session-identity.md delete mode 100644 docs/plans/finished/2026-07-05-docks-kit-refresh.md delete mode 100644 docs/plans/finished/2026-07-05-docks-skill-gaps.md delete mode 100644 docs/plans/finished/2026-07-05-effect-kit-upgrade-review.md delete mode 100644 docs/plans/finished/2026-07-06-relay-spawn-model-discipline.md delete mode 100644 docs/plans/finished/2026-07-07-plan-review-crosscheck.md delete mode 100644 docs/plans/finished/2026-07-07-relay-token-efficiency.md delete mode 100644 docs/plans/finished/2026-07-10-relay-attach-command.md delete mode 100644 docs/plans/finished/2026-07-10-relay-notify-reliability.md delete mode 100644 docs/plans/finished/2026-07-10-relay-store-hygiene.md delete mode 100644 docs/plans/finished/2026-07-11-relay-live-view.md delete mode 100644 docs/plans/finished/2026-07-12-cross-company-review-policy.md delete mode 100644 docs/plans/finished/2026-07-14-compatibility-final-review-repair-rung.md delete mode 100644 docs/plans/finished/2026-07-14-legacy-start-transition-compatibility.md delete mode 100644 docs/plans/finished/2026-07-14-relay-worker-lifecycle-primitives-continuation.md delete mode 100644 docs/plans/finished/2026-07-14-relay-worker-lifecycle-primitives-legacy.md delete mode 100644 docs/plans/finished/2026-07-15-refactor-session-relay-rust.md delete mode 100644 docs/plans/finished/2026-07-15-relay-worker-fanout.md delete mode 100644 docs/plans/finished/2026-07-15-workflow-model-roles-and-bounded-reviews.md delete mode 100644 docs/plans/finished/2026-07-16-plan-review-convergence-and-improver.md delete mode 100644 docs/plans/finished/2026-07-17-completion-reuse-terminal-lf.md delete mode 100644 docs/plans/finished/2026-07-17-single-gpt-plan-review-default.md delete mode 100644 docs/plans/finished/2026-07-18-session-relay-prebuilt-cli-distribution.md delete mode 100644 docs/plans/finished/2026-07-18-target-plugin-ci-and-release-gates.md delete mode 100644 docs/plans/finished/2026-07-19-session-relay-prebuilt-cli-release.md delete mode 100644 docs/plans/finished/2026-07-22-session-relay-workspace-isolation.md delete mode 100644 docs/plans/finished/2026-07-23-session-relay-linux-workspace-recertification.md delete mode 100644 docs/plans/finished/2026-07-26-session-relay-correlated-results-release-completion.md delete mode 100644 docs/plans/finished/2026-07-26-session-relay-correlated-results-release-continuation.md delete mode 100644 docs/plans/finished/2026-07-26-session-relay-correlated-results-release-exact-scope-v2.md delete mode 100644 docs/plans/finished/2026-07-26-session-relay-correlated-results-release-exact-scope.md delete mode 100644 docs/plans/finished/2026-07-26-session-relay-correlated-results-release-remediation-v2.md delete mode 100644 docs/plans/finished/2026-07-26-session-relay-correlated-results-release-remediation-v3.md delete mode 100644 docs/plans/finished/2026-07-26-session-relay-correlated-results-release-remediation-v4.md delete mode 100644 docs/plans/finished/2026-07-26-session-relay-correlated-results-release-remediation-v5.md delete mode 100644 docs/plans/finished/2026-07-26-session-relay-correlated-results-release-remediation-v6.md delete mode 100644 docs/plans/finished/2026-07-26-session-relay-correlated-results-release-remediation-v7.md delete mode 100644 docs/plans/finished/2026-07-26-session-relay-correlated-results-release-remediation-v8.md delete mode 100644 docs/plans/finished/2026-07-26-session-relay-correlated-results-release-remediation-v9.md delete mode 100644 docs/plans/finished/2026-07-26-session-relay-correlated-results-release-remediation.md delete mode 100644 docs/plans/finished/2026-07-26-session-relay-correlated-results-release.md delete mode 100644 docs/plans/finished/2026-07-26-session-relay-release-binder-repository-proof-v2.md delete mode 100644 docs/plans/finished/2026-07-26-session-relay-release-binder-repository-proof.md delete mode 100644 docs/plans/finished/2026-07-28-accepted-planrun-proof-contract.md delete mode 100644 docs/plans/finished/2026-07-28-agent-worktree-lifecycle-strategy.md delete mode 100644 docs/plans/finished/2026-07-28-legacy-retirement-path.md delete mode 100644 docs/plans/finished/2026-07-28-legacy-schema6-policy-classification.md delete mode 100644 docs/plans/finished/2026-07-28-plan-review-controller-failure-recovery.md delete mode 100644 docs/plans/finished/2026-07-28-plan-workflow-phases-and-loop-escape.md delete mode 100644 docs/plans/finished/2026-07-28-relay-worktree-portable-layout.md delete mode 100644 docs/plans/finished/2026-07-28-session-relay-correlated-messaging-and-worker-results.md delete mode 100644 docs/plans/finished/2026-07-28-session-relay-linux-workspace-publication.md delete mode 100644 docs/plans/finished/2026-07-28-session-relay-linux-workspace-release.md delete mode 100644 docs/plans/finished/2026-07-30-plan-dispatch-driver.md delete mode 100644 docs/plans/finished/2026-07-31-plan-evidence-row-scales.md delete mode 100644 docs/plans/finished/2026-07-31-relay-release-instance-separation.md delete mode 100644 docs/plans/finished/2026-07-31-relay-supervisor-socket-stat.md delete mode 100644 docs/plans/finished/2026-08-02-lifecycle-dispatch-integrity.md delete mode 100644 docs/plans/finished/2026-08-02-relay-fanout-reaper-reporting.md delete mode 100644 docs/plans/finished/2026-08-02-session-relay-0.15.0-release.md delete mode 100644 docs/plans/finished/2026-08-03-plan-lifecycle-plugin-extraction.md delete mode 100644 docs/plans/finished/2026-08-03-step-ids-and-class-budget.md delete mode 100644 docs/plans/finished/2026-08-04-release-precompletion-rehearsal-and-contract-guards.md delete mode 100644 docs/plans/finished/2026-08-04-session-relay-0.16.0-release.md delete mode 100644 docs/plans/finished/2026-08-04-session-relay-0.16.0-terminal-evidence-correction.md delete mode 100644 docs/plans/finished/2026-08-04-shared-plugin-release-orchestration.md delete mode 100644 docs/plans/finished/2026-08-05-ci-observability-and-test-contracts.md delete mode 100644 docs/plans/finished/2026-08-05-plan-execution-queue-contract.md delete mode 100644 docs/plans/finished/2026-08-05-session-relay-0.16.0-correction-plan-terminal-evidence.md delete mode 100644 docs/plans/finished/2026-08-07-session-relay-custody-deadlines.md delete mode 100644 docs/plans/finished/2026-08-07-session-relay-payload-boundary.md delete mode 100644 docs/plans/finished/2026-08-07-session-relay-post-cutover-modules.md delete mode 100644 docs/plans/finished/2026-08-07-session-relay-quiesce-deadline.md delete mode 100644 docs/plans/finished/2026-08-07-session-relay-typed-irc-sqlite.md delete mode 100644 docs/plans/finished/2026-08-08-plan-lifecycle-derived-history-navigation.md delete mode 100644 docs/plans/finished/2026-08-08-plan-lifecycle-review-and-authority-modules.md delete mode 100644 docs/plans/finished/2026-08-08-plan-lifecycle-review-dispatch-performance.md delete mode 100644 docs/release-evidence/session-relay-0.16.0-terminal-correction-successor.md delete mode 100644 docs/release-evidence/session-relay-0.16.0-terminal-correction.md diff --git a/.claude/launch.json b/.claude/launch.json deleted file mode 100644 index d09423b4..00000000 --- a/.claude/launch.json +++ /dev/null @@ -1,11 +0,0 @@ -{ - "version": "0.0.1", - "configurations": [ - { - "name": "plans-dashboard", - "runtimeExecutable": "python3", - "runtimeArgs": ["-m", "http.server", "8137", "--directory", "docs/plans"], - "port": 8137 - } - ] -} diff --git a/AGENTS.md b/AGENTS.md index ae58b8f5..9d565e25 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -29,7 +29,7 @@ Bun runs this repository's tooling and is the package manager; its version is th ├── .agents/skills/ project-local skills (canonical, multi-tool) ├── .codex/agents/ repo-local Codex reviewer wrappers (not plugin payload) ├── .claude/skills/ Claude Code-visible symlinks → ../../.agents/skills/ -├── docs/ plan routing and point-in-time records (rules: docs/AGENTS.md) +├── docs/ plan routing (rules: docs/AGENTS.md) ├── scripts/ plugin-author tooling (NOT shipped to consumers) └── .github/workflows/ gh-side CI on PR + tag push ``` @@ -40,7 +40,7 @@ Per-area conventions load lazily from nested `AGENTS.md` nodes. A node is a sing | Node | Covers | |---|---| -| `docs/AGENTS.md` | plan-record routing, GitHub issue backend, frozen pre-GitHub archive | +| `docs/AGENTS.md` | plan-record routing, GitHub issue backend | | `plugins/docks/skills/AGENTS.md` | skill authoring - description CSO, frontmatter, body rules, scoring | | `plugins/plan-lifecycle/skills/AGENTS.md` | plan-lifecycle skill authoring - the lifecycle skills and yolo, contract sync, fail-loud routing | | `scripts/AGENTS.md` | validators, edit→release workflow, double-layer gating, versioning | diff --git a/docs/AGENTS.md b/docs/AGENTS.md index 0b5fed77..ed39875a 100644 --- a/docs/AGENTS.md +++ b/docs/AGENTS.md @@ -9,21 +9,14 @@ Read `skills/productivity/plan-manager/references/plan-contract.md` inside the installed `plan-lifecycle` plugin for the record and lifecycle contract. `docs/PLAN.md` provides local routing. Do not duplicate the contract here. -`docs/PLAN-QUEUE.md` may remain as a human discovery and priority note. -No lifecycle helper reads it. +## Records -`docs/plans/finished/` is frozen pre-GitHub history. Never parse, migrate, or use -it as the current source of truth. +`docs/` holds only `AGENTS.md` and `PLAN.md` (verify: `ls docs`). Record plans, +audits, and release evidence in GitHub issues and pull requests. Do not add +them as files under `docs/`. -## Point-in-time records - -Every file under `docs/` except `AGENTS.md`, `PLAN.md`, and `PLAN-QUEUE.md` is a -point-in-time record: release evidence, dated audits, and the frozen archive -(verify: `ls docs`). Preserve their historical claims and context when editing -them. - -`file:line` anchors are allowed only in those point-in-time records. Long-lived -documentation and context-tree nodes must use the durable grammar: -`` `path` - `symbol/config key` - purpose (verify: `command`) ``. +Long-lived documentation and context-tree nodes must use the durable grammar: +`` `path` - `symbol/config key` - purpose (verify: `command`) ``. Do not use +`file:line` anchors in them. Pointers here name concepts, not coordinates — if a path or symbol moved, trust the stated purpose and re-locate it (grep the symbol) before acting. diff --git a/docs/PLAN-QUEUE.md b/docs/PLAN-QUEUE.md deleted file mode 100644 index 2a382825..00000000 --- a/docs/PLAN-QUEUE.md +++ /dev/null @@ -1,23 +0,0 @@ -# Plan execution queue - -Status: project-owned discovery and prioritization view. - -This file records selection order only. It grants no review, lifecycle, mutation, -or external-effect authority. Canonical plan records, current user intent, and -observed acceptance remain authoritative. -The `Plan` cell now holds a plan issue number; any existing non-numeric cell names a frozen pre-GitHub record. - -| Stage | Plan | Depends on | Why | -|---:|---|---|---| -| 1 | ci-observability-and-test-contracts | - | This plan is finished. | -| 2 | plan-execution-queue-contract | ci-observability-and-test-contracts | CI observability is finished and its full gate is green; this plan is finished, so the queue now orders the remaining work. | - -## OptMem design input - -[OptMem](https://github.com/VictorTaelin/OptMem) supports one useful boundary: -lossless append-only records remain authoritative while summaries and indexes are -rebuildable. Apply that idea to CI evidence, Relay event indexes, and Plan -Lifecycle history navigation. Never use lossy summaries as authority or evidence. - -No license file or GitHub license metadata was present when checked. Study its -concepts only; do not copy its code or add it as a dependency without permission. diff --git a/docs/PLAN.md b/docs/PLAN.md index e69e6fdc..ae910385 100644 --- a/docs/PLAN.md +++ b/docs/PLAN.md @@ -13,6 +13,3 @@ Use `plan-workspace` to maintain workspace routing, main-context `plan-manager` to run the lifecycle, and internal `plan-reviewer` for plan review. The two read-only wrappers are `plan-reviewer` and `code-reviewer`. If the plugin is missing, report that prerequisite. Do not invent a local copy. - -`docs/plans/finished/` is frozen pre-GitHub history, not lifecycle input. -An optional `docs/PLAN-QUEUE.md` is a human note only. No helper reads it. diff --git a/docs/authoring-audits.md b/docs/authoring-audits.md deleted file mode 100644 index 3a1c8443..00000000 --- a/docs/authoring-audits.md +++ /dev/null @@ -1,78 +0,0 @@ -# Authoring audits — backlog - -This file tracks **deferred audits** of the plugin's skills and agents against authoritative authoring best-practices. The first audit (skills, May 2026) lives in this repo's git history; what's recorded below is what hasn't been done yet so a future session can pick it up cold. - -> **Historical record — inventory below predates v0.2.** The May 2026 audits ran against an older command / agent / skill inventory. The v0.2 rebalance (`a8a3ecc`) demoted `/fix`, `/review`, `/test`, `/human-docs`, `/roadmap-init` from commands to skills, changing the command / agent / skill mix. Hardcoded floors (for example, old fixed totals) also predate `93db77e`, which switched CI to count-derived floors (`N × per-file_floor`). For current inventory and floors, see `node plugins/docks/skills/productivity/write-skill/scripts/skill-guard.mjs score --per-file`, `node scripts/agents/score.mjs --per-file plugins/plan-lifecycle/agents`, and `scripts/AGENTS.md` → "Validators". The **pipelines-to-skills** re-architecture later removed commands entirely — `/docs`, `/refactor`, `/security` became cross-tool skills and command guard/score scripts were deleted, so the "commands body audit" section below is fully historical. - -The starting point for any audit is `plugins/docks/skills/AGENTS.md` and `AGENTS.md` (frontmatter + description rules), plus the validators under `scripts/skills/` and `scripts/agents/`. Those cover the description layer; what's parked here is the **body / system-prompt layer**. - -## Sources to re-check before starting any audit - -- -- -- (especially "Write an effective CLAUDE.md") -- -- - -## Resolved: agents body audit (May 2026) - -The agent body audit ran in May 2026. Total scorer output improved; per-file minimums and floors were raised in `scripts/ci.sh`, and the GH workflow was synced. These classes of fix landed: - -1. **Body-counting bug** in `scripts/skills/score.sh` / `scripts/agents/score.sh` / `scripts/skills/guard.sh` / `scripts/agents/guard.sh` — `---` lines inside YAML code fences were miscounted as a third frontmatter marker, truncating body length. Fixed with `&& c<2` cap on the awk counter. `docs-agents-builder` and `docs-skills-builder` jumped 14→15 from this fix alone. -2. **Slop trigger words in example lists** — `human-docs-writer` line 40 and `human-docs-pre-verifier` line 51 enumerated `"robust"` and `"seamless"` as inflated adjectives to flag, which the scorer (correctly) couldn't distinguish from authoring slop. Replaced with `"best-in-class"` and `"industry-leading"` — same teaching value, no scorer trigger. -3. **2nd `` block** added to agents that had only the universal shell-avoidance constraint (verifier-scope for post-verifiers; evidence/specificity/boundary rules for scanner and categorizer roles). - -The remaining sub-max agents are missing the research-gate point by design — they don't touch external library docs (explorers, post-verifiers, categorizers, scanners). The per-file floor captures the structural minimum without forcing unjustified context7 references. - -**Audit followup #4 — research-gate spot-check (May 2026)**: sampled representative sub-max agents (`fix-explorer`, `refactor-explorer`, `security-explorer`, `docs-pattern-extractor`, `docs-verifier`). All sampled agents are correctly research-gate-N/A: -- *Explorers* enforce a 2nd constraint "enumerate; do not diagnose" — research-gate would conflict with this. They map facts; downstream phases use them. -- *Pattern-extractors* extract from existing code; no framework recommendation. -- *Verifiers* validate structural integrity (frontmatter, paths, sizes) — they don't write framework claims. - -Conclusion: the research-gate scorer correctly gates this point on agents that produce or recommend framework code (writers, builders, fixers). For enumerate/extract/verify roles, the 14/15 ceiling is the right shape. - -**No CLAUDE.md prose change needed** — the per-file ≥14 floor mechanically requires 2 constraint blocks (mandatory-only ceiling is exactly 14), so "every agent gets a 2nd role-specific constraint" is now enforced by the scorer rather than documentation. - -**Re-running this audit**: invariants from above carry forward; run `node scripts/agents/score.mjs --per-file plugins/plan-lifecycle/agents | sort -k2 -n | head -20` to find the next sub-max cluster, then identify whether the gap is mechanical (research-gate, slop, missing constraint) or by-design. - -## Resolved: commands body audit (May 2026) - -The command audit ran in May 2026. Total scorer output improved, with `roadmap-init` left as a by-design lower scorer at the time. One mechanical fix landed: - -1. **`docs.md` argument wiring** — the Usage section documented `/docs ` (scoped audit) but the frontmatter lacked `argument-hint` and the body never referenced `$ARGUMENTS`. Added `argument-hint: "[path-or-scope]"` and threaded `$ARGUMENTS` into the Phase 1 explorer prompt as a scope hint (empty = full project). Score 20 → 21. - -Commands now score at the per-file maximum. Two follow-up audits closed remaining gaps: - -1. **`docs.md` `$ARGUMENTS` propagation (Audit followup #1)**: the initial argument-wiring fix only threaded `$ARGUMENTS` into the Phase 1 explorer prompt; phases 2–6 operated on the full project regardless. Updated the pre-flight Environment block to render `Scope: $ARGUMENTS` (so it lands in the plan file once), and added explicit scope handling to each subagent prompt (Phase 2a/2b/3/4a/4b/5/6). When a user runs `/docs src/api`, the scope flows through every phase: pattern-scanner restricts source-line searches; categorizer prioritizes new-skill proposals tied to the directory; verifier samples within scope when spot-checking file:line refs. - -2. **`argument-hint` scoring quirk (Audit followup #2)**: the original check rewarded `argument-hint` presence unconditionally, costing 1pt for genuinely no-arg commands. Mirrored the orchestrator-aware Plan Mode rule — the check now passes automatically when the command's body never references `$ARGUMENTS` (no-args by design). Brings `roadmap-init` to 21/21. - -Two scoring quirks resolved during the broader command audit: - -- **Plan Mode quirk**: original check unconditionally required `Plan Mode`/`EnterPlanMode` text — mis-fired against mechanical scaffolders. Now skipped when zero `subagent_type:` refs (single-session work doesn't need a planning gate). -- **`argument-hint` quirk** (above). - -Both quirk fixes share the same shape: detect "feature-applicable by orchestration shape" and skip the check when not applicable. The result is a scoring rubric that doesn't penalize genuinely simple commands, while still catching real authoring failures in orchestrators. - -**Allowed-tools surface audit (Audit followup #3)**: trimmed `Bash(ls:*) Bash(find:*) Bash(wc:*)` from `docs.md`, `human-docs.md`, and `refactor.md` — these were declared but never used in the orchestrator body, and conflict with the kit's shell-avoidance philosophy (orchestrator + agents both use `Glob`/`Read`/`Grep` instead of shell utilities). The remaining commands had clean allowed-tools lists. - -**`` block retirement (Audit followup #6)**: roadmap-init was the last command using `...` blocks; the rest had already moved to thin orchestrator (`subagent_type` refs) or plain markdown. `` was a kit-internal visual-grouping convention with no Claude Code semantics — Anthropic's docs (skills, commands, subagents, plugins) do not document or parse it. Plain markdown sections (`## Phase`, `### Success Criteria`) achieve the same grouping with less ceremony, so the kit retired the convention. The guard now rejects `` blocks anywhere to keep commands consistent. - -**Other audit checklist points evaluated:** -- **Structural alignment**: multi-agent commands follow Plan Mode → multi-phase → ExitPlanMode → Implementation; `roadmap-init` deliberately diverged when it existed as a mechanical, idempotent command. Aligned. -- **Phase Transition Protocol**: was enforced by the deleted commands guard for 3+ phase commands; passed at the time. -- **subagent_type references**: were enforced by the deleted commands guard to resolve to existing agent files; passed at the time. -- **allowed-tools surface**: not audited line-by-line; left for future iteration if drift surfaces. -- **Description tightness**: done in earlier audit; all commands ≤500 chars (one-pt tier). - -**Re-running this historical commands audit**: command scripts no longer exist. Translate any still-relevant checklist item into the current skill/agent validators before acting on it. - -## When picking up either audit - -1. Re-fetch the source URLs above — Anthropic's docs evolve. -2. Run `node scripts/ci.mjs` first to confirm green baseline. -3. Run `node plugins/docks/skills/productivity/write-skill/scripts/skill-guard.mjs score --per-file` and `node scripts/agents/score.mjs --per-file plugins/plan-lifecycle/agents` to get current per-file scores. -4. Work through the audit checklist file-by-file. -5. Apply low-risk fixes; list higher-risk recommendations for user review. -6. Update the matching `AGENTS.md` node with any new universally-applicable rules. -7. Update `plugins/docks/skills/productivity/write-skill/scripts/skill-guard.mjs` or `scripts/agents/score.mjs` if the audit reveals a new mechanical check worth enforcing. diff --git a/docs/optimization-audit-may-2026.md b/docs/optimization-audit-may-2026.md deleted file mode 100644 index 6bae6743..00000000 --- a/docs/optimization-audit-may-2026.md +++ /dev/null @@ -1,338 +0,0 @@ -# `docks` Plugin Optimization Audit on Opus 4.7 — May 2026 - -> **Historical record (May 2026).** The command orchestrators, the named subagents (for example `refactor-pre-verifier` and `security-synthesizer`), and the `scripts/*.sh` validators in this file no longer exist. Open tasks here are not live work. The current validators are `.mjs` scripts under `scripts/`; see `scripts/AGENTS.md` → "Validators". - -**Scope:** the `docks` plugin (repo: `~/projects/docks`, published as [DocksDocks/docks](https://github.com/DocksDocks/docks)) ships the multi-agent pipeline kit — command orchestrators, portable skills, specialized subagents, and the author-side validators under `scripts/skills/`, `scripts/agents/`, `scripts/tree/`, and `scripts/scaffold/`. Inventory shifts as the plugin evolves; use the filesystem and validators for the current roster. Consumer-facing pieces — settings.json, hooks, status line, sync — live in `public` and are tracked at `docs/roadmap/planned/optimization-audit-may-2026.md` in the [DocksDocks/public](https://github.com/DocksDocks/public) repo. - -## TL;DR - -- **High-confidence wins for `docks`:** (1) selectively add `effort: xhigh` to the Sonnet agents whose current `max` inheritance from the parent is wasteful (the §A.1 table is the source of truth; several agents were miscategorized in the v0 draft); (2) extend the Builder-Verifier pattern by requiring verifier agents to **reproduce** their findings (re-grep the cited line, re-run the failing test) rather than only check syntactic citations — `/ultrareview`'s reported sub-1% false-positive rate comes from this step; (3) opt parallel scanners into `context: fork` via a skill-wrapper refactor (see next bullet) for the ~10× input-token cut on children 2-N. -- **The fork-wrapper win was APPLIED on 2026-05-06:** parallel-scanner agents are now opted into `context: fork` for the ~10× input-token cut on children 2-N. Issue [#16803](https://github.com/anthropics/claude-code/issues/16803) was closed in **v2.1.101** — plugin-loaded skills now honor `context: fork` and `agent` frontmatter, and the `agent:` field accepts custom plugin-defined agent names per [Anthropic's skills docs](https://code.claude.com/docs/en/skills). The kit shipped wrapper skills under `plugins/docks/skills/forked-*/SKILL.md`, each carrying `context: fork` + `agent: `; the command orchestrators now invoke `Skill(skill: "docks:forked-", args: "{plan-path} $ARGUMENTS")` for parallel scanner phases. No validator carve-out was needed — wrappers score above the floor. Sequential phases keep their `Agent(subagent_type: ...)` path. (§A.2) -- **The plugin's architectural choices are mostly defensible and sometimes ahead of the curve.** Plan-file-as-IPC matches OpenHands' event-stream substrate and Cursor's January 2026 dynamic-context-discovery (46.9% token reduction). Builder→Verifier matches Aider's architect/editor split, Anthropic's lead/subagent research pattern, and Anysphere's Bugbot. CSO-style "Use when… Not for…" descriptions are the documented agentskills.io standard. Per-phase model tiering (Opus synthesis / Sonnet exploration) is exactly what Anthropic's research multi-agent system used to beat single-Opus by 90.2%. The subagent roster is deliberately specialized rather than sprawling. -- **The most impactful new patterns the plugin is *not* using:** the **advisor tool** (`advisor_20260301`, **public beta** since April 9, 2026 — beta header `advisor-tool-2026-03-01`) which lets a Sonnet executor consult Opus mid-loop without orchestration code (good fit for the Phase-4-planner cost concentration); **per-finding reproduction** in verifier agents (the strongest signal-to-noise pattern documented anywhere as of May 2026); and **dynamic skill discovery** (Cursor's "files-not-tools" — expose only names + 1-line desc, defer full body to grep on demand). - ---- - -## Tasks - -Top-10 actionable items derived from §1 below. - -- [ ] **(HIGH)** Add `effort: xhigh` overrides to Sonnet agents per the corrected table in §A.1; keep `max` on Opus synthesis tier and on `security-vulnerability-scanner` (cybersecurity refusal sensitivity). -- [x] **(MED) APPLIED 2026-05-06** Opt parallel scanners into `context: fork` via skill-wrapper refactor. No validator carve-out needed; wrapper skills clear the existing floor. Unblocked by v2.1.101 fix to issue [#16803](https://github.com/anthropics/claude-code/issues/16803). (§A.2). Expected: ~10× input-token cut on parallel-scanner children 2-N — to be confirmed via `cache_read_input_tokens` measurement on the next live runs. -- [ ] **(HIGH)** Add reproduce-step to verifier agents (`refactor-pre-verifier`, `refactor-post-verifier`, `security-synthesizer`, `docs-verifier`) — re-grep cited line / re-run failing test before report (§D.1). -- [ ] **(MED)** Pilot advisor tool (`advisor_20260301`) on `refactor-pre-verifier` (Sonnet) via Messages API outside the kit — beta header `advisor-tool-2026-03-01` (§A.3). Demoted from HIGH because per-agent integration is not yet exposed through Claude Code agent frontmatter. -- [ ] **(MED)** Move long enumerations from skill `description` fields to body sections (§C.1). Run `bash scripts/skills/score.sh --per-file` to verify no regressions. -- [ ] **(MED)** Restructure skill listings to Cursor's "names + 1-line desc" pattern (§C.2). Pilot with one skill before full rollout. -- [ ] **(MED)** Add OODA framing to orchestrator command bodies (`/docks:security`, `/docks:docs`, `/docks:refactor`) (§B.1). -- [ ] **(MED)** Audit plan-file IPC for chain-of-thought leakage — verifier should see decisions only, not planner's reasoning trace (§B.2). -- [ ] **(MED)** Add plan-brittleness mitigation — re-plan triggers on hard execution failures (§D.2). -- [ ] **(LOW)** Pre-emptive: `disable-model-invocation: true` on any future skill that performs destructive operations (§C.4). - ---- - -## Section 1 — Top recommendations (docks-scoped) - -Confidence: **HIGH** = multiple independent sources + empirical data; **MED** = one strong source or strong logical argument; **LOW** = speculative, pilot only. - -| # | Recommendation | Confidence | Effort | Expected Impact | -|---|---|---|---|---| -| 1 | Add `effort: xhigh` to the Sonnet agents where parent inheritance of `max` is wasteful — `*-pre-verifier.md`, `docs-verifier.md`, `docs-skills-builder.md`, `docs-agents-builder.md`, plus `*-pattern-scanner.md` / `*-pattern-extractor.md` / `*-dead-code-scanner.md` / `*-duplication-scanner.md` / `*-explorer.md` already on Sonnet. | HIGH | trivial | 20–40% token reduction on those phases without quality loss; preserves `max` on Opus tier and on cybersecurity-sensitive `security-vulnerability-scanner`. | -| 2 | **APPLIED 2026-05-06** — opted parallel scanners into `context: fork` via skill wrappers (`plugins/docks/skills/forked-*/SKILL.md`), each carrying `context: fork` + `agent: `; orchestrators now dispatch via `Skill(skill: "docks:forked-")`. Unblocked by v2.1.101 fix to issue [#16803](https://github.com/anthropics/claude-code/issues/16803). | HIGH | applied | ~10× input-token cut on parallel-scanner children 2-N expected (Anthropic v2.1.117 patch notes); to be confirmed via `cache_read_input_tokens` on next live runs. | -| 3 | Add a **reproduce step** to verifier agents (`*-pre-verifier`, `*-post-verifier`, `*-verifier`, `security-synthesizer`). Each finding must be reproduced (file:line re-grepped, failing test re-run) before landing in the report. | HIGH | moderate | Drives false-positive rate toward `/ultrareview`'s sub-1% bar. Highest signal-to-noise pattern documented as of May 2026. | -| 4 | Pilot the **advisor tool** (`advisor_20260301`, public beta) on `refactor-pre-verifier`. Configure as Sonnet-executor + Opus-advisor; consult Opus only on findings flagged low-confidence. Run via Messages API — Claude Code can't pass arbitrary beta headers yet. | MED | moderate | Anthropic benchmark: Sonnet+Opus-advisor > Sonnet-solo on SWE-bench Multilingual (+2.7 pp) at 11.9% lower cost than Opus-solo. | -| 5 | Move long enumeration content from skill `description` fields into bodies. The `description` loads every session and is capped at 1,536 chars (and silently truncated past that); the body loads only on activation. | MED | moderate | Cleans system-prompt prefix; per-skill scorer rewards ≤500 char descriptions. | -| 6 | Restructure skill listings to **Cursor's "names + 1-line desc" pattern** (Jan 2026 blog, 46.9% MCP token reduction). Defer full body to grep-on-demand. | MED | high | Major prefix-size reduction; re-architects the way skills load. Highest-effort item in this list. | -| 7 | Add **OODA framing** to orchestrator command bodies (`/docks:security`, `/docks:docs`, `/docks:refactor`). Anthropic's research multi-agent paper uses OODA for the lead-research-agent. | MED | trivial | Tighter loop discipline on the orchestrator; not relevant to Sonnet sub-scanners. | -| 8 | Audit plan-file IPC for **chain-of-thought leakage**. The plan file should carry decisions/conclusions only; reasoning trace stays in the planner's working context. | MED | low | Reduces verifier's input-token cost (planner reasoning is unrelated to verification). Was the original justification for splitting Builder-Verifier (per Aider). | -| 9 | Add **plan-brittleness mitigation** — re-plan triggers on execution failures. Currently plan-and-execute is "brittle when plans need mid-run adaptation" per Digital Applied Team's 2026 Agent Architecture Patterns taxonomy. | MED | moderate | Recovers gracefully when a scanner hits unexpected input or a fixture moves. | -| 10 | Verify `disable-model-invocation: true` on any skill that performs destructive operations (e.g. ones that author writes to repo state). | LOW | trivial | Defense-in-depth; agentskills.io spec calls it out. Not yet known if any current docks skill warrants it. | - ---- - -## Section A — Per-Agent Frontmatter - -### A.1 Effort tiering — push wasteful `max` inheritance down to `xhigh` (HIGH / trivial / low risk) - -Public repo policy is `CLAUDE_CODE_EFFORT_LEVEL=max` (kept intentional — see `agent_optimization.md` §2.1). Subagents inherit that effort unless their frontmatter declares otherwise. **Inheritance is wasteful** on Sonnet-tier explorers, scanners, builders, and verifiers that do bounded I/O work (file lists, grep, structured authoring) where `max` thinking budget is overkill. Anthropic's [Effort docs](https://platform.claude.com/docs/en/build-with-claude/effort) recommend `xhigh` as the starting point for coding and agentic work on Opus 4.7; for Sonnet that translates to "the highest tier short of `max`" — same principle. - -**Recommended overrides** (set `effort: xhigh` in frontmatter, leaving model decisions untouched): - -"Current model" column verified by `grep -m1 '^model:' plugins/docks/agents/*.md` on 2026-05-06. - -| Agent | Current model | Recommended effort | Why | -|---|---|---|---| -| `refactor-explorer.md` | sonnet | `xhigh` | Maps stack/tools — bounded discovery work, but xhigh keeps headroom for monorepo/DI inference | -| `refactor-dead-code-scanner.md` | sonnet | `xhigh` | Deeper than explorer; needs reasoning on classification | -| `refactor-duplication-scanner.md` | sonnet | `xhigh` | Same | -| `refactor-solid-analyzer.md` | **opus** | **`max`** | Keep — Opus synthesis-tier work (per-principle deep analysis with cross-package coupling) | -| `security-explorer.md` | sonnet | `xhigh` | Attack-surface mapping — xhigh keeps headroom for endpoint/auth-flow inference | -| `security-vulnerability-scanner.md` | sonnet | **`max`** | Keep — Anthropic's 4.7 cybersecurity refusals are sensitive to effort drop | -| `security-adversarial-hunter.md` | **opus** | **`max`** | Keep — Opus + cybersecurity-sensitive (chained-finding reasoning) | -| `security-logic-analyzer.md` | **opus** | **`max`** | Keep — Opus synthesis-tier (trust-boundary / race-condition reasoning) | -| `docs-explorer.md` | sonnet | `xhigh` | Repo-mapping work — xhigh keeps headroom for skill/agent enumeration with frontmatter parsing | -| `docs-categorizer.md` | **opus** | **`max`** | Keep — Opus synthesis-tier (full skill-set proposal with CSO descriptions) | -| `docs-pattern-scanner.md` | sonnet | `xhigh` | Same | -| `docs-pattern-extractor.md` | sonnet | `xhigh` | Same | -| `docs-role-mapper.md` | **opus** | **`max`** | Keep — Opus synthesis-tier (agent-role mapping with skill-reference audit) | -| `refactor-planner.md` | opus | **`max`** | Keep — synthesis tier | -| `refactor-pre-verifier.md` | **sonnet** | `xhigh` | Verifier on Sonnet — `xhigh` override balances reproduction effort against cost (top advisor-tool pilot candidate per §A.3) | -| `refactor-post-verifier.md` | opus | **`max`** | Keep | -| `security-synthesizer.md` | opus | **`max`** | Keep — synthesis tier | -| `docs-skills-builder.md` | **sonnet** | `xhigh` | Builder on Sonnet — `xhigh` override; structured-output authoring benefits from extended exploration | -| `docs-agents-builder.md` | **sonnet** | `xhigh` | Builder on Sonnet — `xhigh` override; same rationale | -| `docs-verifier.md` | **sonnet** | `xhigh` | Verifier on Sonnet — `xhigh` override pairs with §D.1 reproduce-step | - -**Rationale:** Anthropic's [Effort docs](https://platform.claude.com/docs/en/build-with-claude/effort) explicitly state `max` "can lead to overthinking" on structured-output / less intelligence-sensitive tasks. Hex's CTO measured "low-effort Opus 4.7 ≈ medium-effort Opus 4.6"; DataCamp's benchmark found `xhigh` produced over-verbose output on routine tasks. The `public` repo accepts that on the orchestrator turn but the per-subagent overrides above are where the savings actually compound. - -**Where the savings really live now:** with the corrected baseline, Sonnet-tier agents become candidates for an `effort: xhigh` override — the inherited `max` is wasteful across explorers, scanners, builders, and verifiers alike. The Opus tier is largely correct as-is and keeps `max` for synthesis-tier reasoning. - -**Risk:** the `security-vulnerability-scanner` keeps `max` because 4.7-specific cybersecurity refusals are sensitive to effort drop (Anthropic-flagged in 4.7 release notes; refusal rate on safety-research tasks is 33% even at high effort). - -**Validation:** the existing `scripts/agents/score.sh` does NOT yet score the `effort` field. Consider adding a per-agent floor for the synthesis tier (must declare `max`) so a contributor can't accidentally drop it. - -### A.2 Fork subagents — APPLIED via skill-wrapper refactor (2026-05-06) - -**Status update 2026-05-06:** Issue [#16803](https://github.com/anthropics/claude-code/issues/16803) was closed in **v2.1.101** ([Anthropic collaborator confirmation](https://github.com/anthropics/claude-code/issues/16803#issuecomment-4272680635)) — plugin-loaded skills now honor `context: fork` and `agent` frontmatter fields, matching the behavior of user/project skills. Anthropic's [skills docs](https://code.claude.com/docs/en/skills) explicitly confirm that the `agent:` field accepts *"any custom subagent from `.claude/agents/`"* — not just built-ins like `Explore` / `Plan` / `general-purpose`. **Fork is now reachable from the docks plugin** via a skill-wrapper layer, and this audit's recommendation has been applied. - -**The mismatch and the fix:** `context: fork` is a **skill-level** frontmatter field, not an agent-level one. The orchestrators (`commands/{refactor,security,docs}.md`) previously dispatched via `Agent(subagent_type: )`, which routes through the named-agent code path and bypasses fork (per [Build This Now](https://www.buildthisnow.com/blog/guide/mechanics/claude-code-fork-subagent) reverse-engineering of the Agent tool). The fix: each parallel-scanner phase now invokes `Skill(skill: "docks:forked-", args: " $ARGUMENTS")`, where each wrapper skill carries `context: fork` + `agent: ` and the agent's full system prompt drives execution. - -**What landed:** - -1. **Wrapper skills** at `plugins/docks/skills/forked-/SKILL.md` — matching each parallel-scanner role (see roster below). Each wrapper is a thin task envelope (~50 lines body) with `context: fork`, `agent: `, `` blocks (IPC contract, thin-envelope rule, missing-arg abort), and a Wrapper-args table. Bodies use `$0` for the plan-file path and `$1` for the scope (per Anthropic's [`$ARGUMENTS[N]` substitution](https://code.claude.com/docs/en/skills#available-string-substitutions)). -2. **Orchestrator edits** — `refactor.md`, `security.md`, and `docs.md` use wrappers for their parallel scanner phases. Each parallel-scanner block now reads `Skill(skill: "docks:forked-", args: "{plan-path} $ARGUMENTS")`. Sequential phases (Explorer, Synthesizer, Builders, Verifiers, Planner) keep the existing `Agent(subagent_type: ...)` path — fork has no sibling to share a prefix with on a one-shot call. `Skill` was added to each command's `allowed-tools`. -3. **No validator carve-out needed** — the audit predicted one, but the wrappers score above the per-file floor, driven by `` blocks, BAD/GOOD output-discipline tables, fresh `metadata.updated`, and CSO-tight descriptions. Body-size sweet-spot (80–310 lines) was deliberately skipped — the whole point of these wrappers is to be thin task envelopes; bloating them to 80+ lines would defeat the cache-reuse goal by enlarging each fork's prompt. - -**Wrapper roster:** - -| Wrapper | Wraps | Phase | IPC heading | -|---|---|---|---| -| `forked-refactor-dead-code-scanner` | `refactor-dead-code-scanner` | `/refactor` 2a | `## Phase 2a: Dead Code Findings` | -| `forked-refactor-duplication-scanner` | `refactor-duplication-scanner` | `/refactor` 2b | `## Phase 2b: Duplication Findings` | -| `forked-security-vulnerability-scanner` | `security-vulnerability-scanner` | `/security` 2a | `## Phase 2a: Vulnerability Findings` | -| `forked-security-logic-analyzer` | `security-logic-analyzer` | `/security` 2b | `## Phase 2b: Logic Findings` | -| `forked-security-adversarial-hunter` | `security-adversarial-hunter` | `/security` 2c | `## Phase 2c: Adversarial Findings` | -| `forked-docs-categorizer` | `docs-categorizer` | `/docs` 2a | `## Phase 2a: Categorizer Proposals` | -| `forked-docs-pattern-scanner` | `docs-pattern-scanner` | `/docs` 2b | `## Phase 2b: Pattern Scanner Findings` | -| `forked-docs-role-mapper` | `docs-role-mapper` | `/docs` 4a | `## Phase 4a: Role Mapper Proposals` | -| `forked-docs-pattern-extractor` | `docs-pattern-extractor` | `/docs` 4b | `## Phase 4b: Pattern Extractor Content` | - -The audit's original "wrapper candidates" list missed some docs fan-outs. On reading `docs.md`, more parallel fan-outs surfaced — `docs-categorizer` runs alongside `docs-pattern-scanner` in Phase 2, and `docs-role-mapper` runs alongside `docs-pattern-extractor` in Phase 4. Those docs fan-outs are now wrapped too. - -**Expected benefit:** ~10× input-token cut on parallel-scanner children 2-N (per Anthropic v2.1.117 patch notes for the cache-prefix sharing the env var enables). The exact savings depend on the number of siblings in a given phase; `/docs` benefits in multiple phases. - -**Validation plan:** capture `cache_read_input_tokens` on parallel-scanner children 2-N during the next live `/refactor`, `/security`, and `/docs` runs (see §G's validation section). The kit can ship the wrappers, but only a real run on `claude-opus-4-7[1m]` confirms the cache prefix is actually being reused. - -**Risk surfaced:** the wrapper layer increases the skill-listing budget marginally (per Anthropic's docs the listing aggregates at 1% of context, default 8,000 chars; descriptions are silently dropped past the cap). Wrappers carry `user-invocable: false`, so they don't appear in the `/` menu — but their descriptions still load into Claude's listing. The wrapper descriptions are concise enough for the fallback budget today. If this becomes a pressure point in future, set `SLASH_COMMAND_TOOL_CHAR_BUDGET` higher or move the wrappers to `name-only` via `skillOverrides`. - -(Sequential-only agents — `refactor-solid-analyzer`, `refactor-planner`, all `*-verifier`, `security-synthesizer`, `docs-skills-builder`, `docs-agents-builder`, `docs-explorer`, `refactor-explorer`, `security-explorer` — don't benefit from fork because there's no parallel sibling to share the prefix with. Skipped intentionally.) - -### A.3 Advisor tool retrofit (HIGH if scoped / moderate / low risk) - -Wrap the `refactor-pre-verifier` API call with `advisor_20260301` configured to consult Opus 4.7 from its existing Sonnet executor. Anthropic's BrowseComp data: Haiku-with-Opus-advisor went from 19.7% → 41.2%. SWE-bench Multilingual: Sonnet 4.6 + Opus 4.6 advisor scored 74.8% (+2.7 pp over Sonnet-solo's 72.1%) at **−11.9% cost** vs Opus-solo. - -**Best fit:** Sonnet verifier/builder agents (now correctly identified — see §A.1): `refactor-pre-verifier`, `docs-verifier`, `docs-skills-builder`, `docs-agents-builder`. These are Sonnet doing structured-output authoring or verification — exactly the workload Anthropic's prompting guide for the advisor optimizes (early-call before substantive work, late-call before declaring done). - -**Pilot:** run `refactor-pre-verifier` (Sonnet+Opus-advisor) on the same fixture as a current run. Hypothesis: equal or better quality at the per-task cost of Sonnet-only plus a fixed Opus surcharge per advisor call (typically 2–3 calls per task, 1,400–1,800 tokens each per [Anthropic docs](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool)). - -**Status:** the advisor tool is in **public beta** (since April 9, 2026); requires the `advisor-tool-2026-03-01` beta header. The `/advisor` slash command (Claude Code v2.1.101+, shipped April 11, 2026) is the user-facing wrapper around the same `advisor_20260301` server tool. **Per-agent integration requires API-level access** — Claude Code subscription clients cannot pass arbitrary beta headers, so this can only be piloted via the Messages API outside the kit until Anthropic surfaces it through agent frontmatter. - ---- - -## Section B — Command-Body and Orchestration Patterns - -### B.1 OODA framing for orchestrator commands (MED / trivial) - -Anthropic's research multi-agent paper explicitly instructs the lead-research-agent on OODA loops with parallel-tool-call instructions: "leave any extensive tool calls to subagents; focus on running subagents in parallel efficiently." - -The plugin's command orchestrators are exactly this role. Add a one-paragraph OODA framing near the top of each command body: - -> **Orchestrator OODA:** observe (read fixture / repo state), orient (decide which subagents to spawn for this phase), decide (set scopes), act (spawn in parallel via single tool-call turn). Subagents do the actual work; orchestrator coordinates. - -Sub-scanner agents do not need OODA framing — they're inside one OODA cycle of the orchestrator's act step. - -### B.2 Plan-file-as-IPC — chain-of-thought leakage audit (MED / low) - -The plan-file-as-IPC pattern is best-in-class (matches OpenHands event-stream, Cursor dynamic-context-discovery, claudefa.st `claude-progress.txt`, Anthropic's research multi-agent system). - -**Audit:** verify the plan files emitted by Phase-3/Phase-4 of each command don't carry the planner's reasoning trace. Aider's architect/editor design — and the original Builder-Verifier split rationale — is that the verifier should see decisions/conclusions only, not the planner's working memory. Reasoning leakage costs the verifier input tokens for content it doesn't need. - -How to check: read a few real `/docks:refactor` plan files, look for sections like "I considered X but decided against it because Y" — those belong in the planner's working context, not the plan file. - -### B.3 Parallel scanner fan-out — verify intra-agent parallelism (MED / trivial) - -When the orchestrator decides to fan out, *also* tell each subagent to use parallel tools internally. Anthropic documents "two kinds of parallelization": -1. Fan-out across subagents (which the kit does correctly). -2. Per-subagent intra-tool parallelism (each subagent uses 3+ tools in parallel within its own turn). - -Verify the scanner agents' system prompts explicitly instruct intra-agent parallelism. If they default to sequential tool use, the fan-out gain is partially squandered. - -### B.4 PostToolBatch hook for cross-scanner consistency (LOW / moderate) - -New hook event runs *after every tool call in a batch resolves* (per Claude API hooks reference 2026). For the "parallel scanners launched in single tool-call turns" pattern, this is the natural place to: -- Validate cross-scanner consistency (do scanners agree on file ownership?) -- Trigger an early Builder phase if all scanners agree (skip the synthesis-merge step) - -Hook itself is configured in `public/ssot/.claude/settings.json` (see `agent_optimization.md` §3.3) but the consumer pattern lives here. Pilot on `/docks:security` Phase 2. - -### B.5 Phase-4/5 cost concentration — additional levers beyond the existing audit - -The original audit's conclusion (don't merge Builder/Verifier; sample the verifier's research-gate ~30–50K tokens) holds. Two **additional** levers: - -1. **Forked subagents on parallel scanners** (cache-prefix sharing, see §A.2 — applied 2026-05-06 via skill wrappers since v2.1.101). -2. **Advisor tool on the pre-verifier** (Sonnet-executor + Opus-advisor on Phase 5, see §A.3). -3. **Partial result streaming via PostToolBatch:** if the planner emits a checklist, fire the verifier on each item as it's completed, in parallel with the planner finishing. Hard to implement, high payoff. -4. **Re-run the merge audit** after §A.2 fork wrappers and §A.3 advisor land — the 44% concentration may shift enough that the merge-vs-sample tradeoff changes. - ---- - -## Section C — agentskills.io Structural Compliance - -### C.1 Description bloat — push enumerations into body (HIGH / moderate) - -Per `docks/CLAUDE.md`: -> "the combined `description` and `when_to_use` text is truncated at 1,536 characters in the skill listing"; first 100 chars matter most for matching. - -Every session loads the description. Audit existing skills for `Covers X, Y, Z…` enumerations in the description that should live in the body. - -The `scripts/skills/score.sh` validator already rewards ≤500 char descriptions (2 pts ≤500, 1 pt ≤1000, 0 else) and deducts for slop words (`comprehensive`, `robust`, `elegant`, `seamless`). **Verify scores haven't regressed** since the most recent additions. - -Worth running `bash scripts/skills/score.sh --per-file` and looking for any skill scoring below the 8/16 floor. - -### C.2 Cursor's "names + 1-line desc" listing pattern (MED / high effort) - -Right now `skillListingBudgetFraction: 0.025` injects full skill descriptions into the system-prompt prefix. Cursor's January 2026 dynamic-context-discovery blog measured **46.9% MCP token reduction** by: -- Loading only `name + 1-line description` statically -- Letting the agent grep `.claude/skills/*/SKILL.md` for full content on demand - -This is now the documented agentskills.io progressive-disclosure pattern. Implementation: shrink the description field to a single sentence and put trigger details in a `when_to_use` body section. - -**Why MED, not HIGH:** the rewrite is high-effort (touches every skill) and breaks existing semantic match on descriptions that have grown rich for matching. Pilot with one skill first; measure prefix size and false-trigger rate before/after. - -### C.3 Vendored skills — `upstream:` block discipline (kept; verify) - -Third-party / vendored skills already get the `upstream:` frontmatter block (`source`, `license`, `vendored_at: "YYYY-MM-DD"`) per the kit standard. This signals validators to relax kit-specific checks while preserving universal structural ones. Working as designed; verify any new vendored skill follows it. - -### C.4 `disable-model-invocation: true` for destructive operations (LOW / trivial) - -agentskills.io spec calls out this field for skills that perform destructive operations. The plugin's current skill set appears read-mostly, so this is preemptive: if a future skill writes to repo state in non-trivial ways (file deletes, schema migrations), set the flag. - -### C.5 `paths:` glob to gate auto-loading by file context (MED / trivial) - -For skills tied to specific file types (e.g., `nextjs-conventions`, `react-effect-policy`, `react-reuse-components`, `typescript-typing`), set `paths: "src/**/*.{ts,tsx}"` (or similar). This gates auto-loading by current file context — the skill only triggers when the working set matches. Reduces false-trigger on non-Next.js / non-React projects. - ---- - -## Section D — Builder-Verifier and the Reproduce Step - -### D.1 Reproduce, don't just check (HIGH / moderate / high payoff) - -The plugin's verifier agents currently **check** outputs (file:line citations match a regex, or the SubagentStop hook in `public` regex-matches a citation pattern). They do not **reproduce** the underlying claim. - -`/ultrareview`'s reported sub-1% false-positive rate comes from per-finding reproduction: -- Each finding has a sandbox where the bug must reproduce (run the failing test, grep the cited line, verify the assertion holds). -- Findings that fail to reproduce are dropped before report. - -Apply to: -- `refactor-pre-verifier` — for each "this change will break X" claim, re-grep for X and confirm the impact. -- `refactor-post-verifier` — for each "the change introduced Y violation" claim, re-run the affected linter rule. -- `security-synthesizer` — for each finding from the parallel scanners, re-grep the cited file:line and verify the pattern matches. -- `docs-verifier` — for each "skill X cites missing path Y" claim, verify path Y is missing. - -This is the strongest signal-to-noise pattern documented anywhere as of May 2026 (Aider, Anthropic research multi-agent, Bugbot, /ultrareview all converge on it). It's also the largest Phase-5 payoff lever. - -**Cost:** verifier agents take longer because they re-execute. Pair with §A.3 advisor tool to keep cost bounded. - -### D.2 Plan brittleness — re-plan triggers on execution failures (MED / moderate) - -Per Digital Applied Team's 2026 Agent Architecture Patterns taxonomy: plan-and-execute (the kit's pattern) is "brittle when plans need mid-run adaptation." - -**Mitigation:** add re-plan triggers on execution failures. When a phase agent reports a hard failure (file gone, scanner crashed, dependency missing), the orchestrator should not blindly continue — it should re-invoke the planner with the failure context. - -Currently the kit's commands appear to push through; verify by reading the command bodies. If absent, add a one-paragraph "on hard failure, reset to Phase N-1 with the failure context appended" rule. - -**Test:** inject a deliberate mid-run failure (delete a file the planner expects after Phase 3 emits the plan) and observe whether `/docks:refactor` recovers gracefully. - -### D.3 Failure compounding — verify file:line citations resolve (MED / moderate) - -An incorrect upstream inference treated as ground truth is the #2 multi-agent failure mode. The plugin's `SubagentStop` hook (in `public`) regex-matches citations but does not verify them. Catching *fabricated* citations requires actually opening the cited file and confirming the line exists. - -**Recommendation:** the SubagentStop hook migration to an `agent`-type hook (see `agent_optimization.md` §3.1) gives the agent `Read`/`Grep`/`Glob` access — use it to verify each `file:line` claim resolves. Plugin-side, ensure verifier agents emit citations in a format the hook can parse (`path/to/file.ts:42` is unambiguous; `near the auth handler` is not). - ---- - -## Section E — Measurements `docks` Should Run - -Each is a real decision the public web can inform but not settle. Targets live here; runs are ad-hoc for now. - -1. **Per-agent effort tiering impact (§A.1).** Measure tokens-per-phase before and after applying the recommended `effort:` overrides on a fixed `/docks:refactor` fixture. Hypothesis: 20–40% reduction on Sonnet phases without quality drop on the verifier's "bugs found / regressions caught" metric. - -2. **Fork + intra-agent parallelism (§A.2 + §B.3).** Skill-wrapper refactor landed 2026-05-06 — capture `cache_read_input_tokens` on parallel-scanner children 2-N during the next live `/refactor`, `/security`, and `/docs` runs. Hypothesis: 5–10× reduction (Anthropic v2.1.117 patch notes). - -3. **Advisor tool on `refactor-pre-verifier` (§A.3).** Sonnet+Opus-advisor vs current Opus-solo on Phase 5, run via Messages API. Hypothesis: equal quality at 30–50% lower cost. - -4. **Reproduce-step on verifiers (§D.1).** Inject 10 known-false findings into the input to `refactor-post-verifier`. Hypothesis: reproduce-step drops 9–10 of them; check-only drops 0–3. - -5. **/ultrareview comparison.** Run Anthropic's multi-agent reviewer fleet against `/docks:security` on the same diffs. Sub-1% false-positive rate is the bar. If `/docks:security` matches or beats it, publish; if not, study the per-finding-reproduction step and adopt it (this is §D.1 already, with measurement). - -6. **Skill-listing budget (§C.2).** Measure system-prompt prefix size and cache-hit rate before/after switching one skill to "names + 1-line desc, body fetched on demand." Decide whether to roll out broadly. - -7. **Phase-4/5 merge audit, redux.** §A.2 (fork wrappers) landed 2026-05-06; §A.3 (advisor) is still gated on Messages-API access. Re-run the original audit's merge-vs-sample analysis once both are validated against live `cache_read_input_tokens` data — the 44% concentration may shift enough that the tradeoff changes. - -8. **Plan-brittleness (§D.2).** Inject a deliberate mid-run failure (delete a file the planner expects) and measure whether the orchestrator re-plans gracefully. Anthropic 2026 Architecture Patterns lists this as the #1 plan-and-execute failure mode. - -9. **Description-bloat sweep (§C.1).** Run `bash scripts/skills/score.sh --per-file` and `bash scripts/agents/score.sh --per-file`. Any score below the floor → trim to ≤500 chars and re-run. - ---- - -## Section F — Things `docks` Does Exceptionally Well - -Reinforcement — don't break these: - -1. **CSO-compliant agent descriptions** ("Use when… Not for…") are the documented agentskills.io standard and the recommended Anthropic skill-authoring practice. Validators (`scripts/agents/guard.sh`) enforce this. Keep rigorously. - -2. **Per-phase model tiering — empirically validated.** Not a folk theory: - - Anthropic's research system: Lead Opus + Sonnet subagents outperformed single-Opus by 90.2%. - - Aider's architect+editor benchmark: SOTA at 85% with split-model. - - Steve Kinney's published Architect/Builder/Validator/Scribe template uses exactly this pattern. - -3. **64% Opus / 78% wall-clock concentration in 3 phases** is a feature, not a bug — it's the price of the Builder-Verifier quality pattern. - -4. **`` blocks, `## Workflow` with context-acknowledgment, `## Anti-Hallucination Checks`, `## Success Criteria`** all match published frameworks (Steve Kinney's template, PubNub best-practices, Anthropic skill best practices). Rigorous structure ahead of most community kits. - -5. **Author-side validators** (`guard/score` scripts in `scripts/`) — CI-quality gate on the kit itself, mirroring Anthropic's [`skill-creator` Eval/Benchmark pipeline](https://tessl.io/blog/anthropic-brings-evals-to-skill-creator-heres-why-thats-a-big-deal/) (executor → grader → comparator → analyzer subagents with blind A/B and LLM-as-judge; Elo-style preference scoring from Anthropic's [crowdworker eval research](https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents)). Not common in community kits. The count-derived total floors (`artifact_count × per-file_floor`) automatically scale with growth — a clean design. - -6. **Plan-file-as-IPC** — matches OpenHands' state/event-stream architecture (arXiv:2407.16741), Cursor's January 2026 "files as the primary interface" (46.9% token reduction), claudefa.st Code Kit's `claude-progress.txt` substrate, and Anthropic's research multi-agent memory pattern. - -7. **The subagent roster is conservative** vs broad community kits. The original audit's agent inventory appears to have conflated the plugin with the broader installed-skill landscape; use `ls plugins/docks/agents/*.md | wc -l` when the current count is actually needed. - -8. **Marketplace + plugin in one repo, double-layered release gating.** Local `ci.sh` catches stage issues fast; GitHub-side `tag-CI` is the authoritative gate before `gh release create`. Two layers because each catches different failure modes. - -9. **Plugin namespace** (`docks:fix`, `docks:security-vulnerability-scanner`) — clean and avoids collision with user agents. - -10. **Body sweet-spot rule (80–310 lines)** in `docks/CLAUDE.md` matches Anthropic's auto-compaction reattachment behavior (first 5,000 tokens of each invoked skill, 25K shared budget). Engineering-grade authoring guidance. - ---- - -## Section G — Caveats - -- **Source weighting:** where Anthropic's official docs and a community blogger disagree, both views are reported. The plugin's per-phase model tiering and Builder-Verifier patterns are *empirically* validated (Anthropic research blog, Aider benchmarks); the advisor tool and reproduce-step are newer and have less independent corroboration. - -- **Inventory caveat:** the original audit's agent inventory appears stale or counts something other than `plugins/docks/agents/*.md`. The Augment Code coordination-overhead concern still applies to any specialization/orchestration tradeoff, but current inventory should be computed from the filesystem instead of copied into prose. - -- **`context: fork` is reachable via skill wrappers** since v2.1.101 closed issue [#16803](https://github.com/anthropics/claude-code/issues/16803). Direct path on agent frontmatter remains unsupported (agent-tool named-`subagent_type` calls bypass fork); the kit's skill-wrapper layer (described in §A.2 and applied 2026-05-06) bridges this. This audit is authored for a Linux/macOS-only target stack — Windows-specific caveats are not tracked. - -- **Cursor "files-not-tools" 46.9% reduction** is measured on Cursor's MCP-heavy workload, not Claude Code's plugin/skill workload. Magnitude on the docks plugin is workload-dependent — pilot before rolling out (§E.6). - -- **Advisor tool is in public beta** (requires `advisor-tool-2026-03-01` beta header), not GA. Per-agent integration requires Messages-API access; Claude Code subscription clients cannot pass arbitrary beta headers. - -- **Advisor tool benchmarks** (BrowseComp 19.7→41.2, SWE-bench Multilingual 72.1→74.8 / −11.9% cost) come from Anthropic's own publication. Independent corroboration is limited as of May 2026. - -- **`/ultrareview` sub-1% false-positive rate** comes from Anthropic internal data; no external reproduction yet. Treat as the bar to aim for, not a proven benchmark. - -- **Empirical numbers** (10×, 30%, 90.2%, etc.) are derived from cited sources; on the plugin's specific workload, expect variance. §E is the way to confirm. - ---- - -## Cross-references - -- Consumer-side optimizations (`ssot/.claude/settings.json` env vars, hooks, status line, sync, global `~/.claude/CLAUDE.md` heuristics, RTK, plugin selection): see `docs/roadmap/planned/optimization-audit-may-2026.md` in the [DocksDocks/public](https://github.com/DocksDocks/public) repo. diff --git a/docs/plans/finished/.gitkeep b/docs/plans/finished/.gitkeep deleted file mode 100644 index e69de29b..00000000 diff --git a/docs/plans/finished/2026-05-12-plan-review-smoke.md b/docs/plans/finished/2026-05-12-plan-review-smoke.md deleted file mode 100644 index e980c9c2..00000000 --- a/docs/plans/finished/2026-05-12-plan-review-smoke.md +++ /dev/null @@ -1,123 +0,0 @@ ---- -title: Smoke-test the docks:plans handoff-grade redesign -goal: Verify the new docs:plans schema, 3-tier pretty-print, and skill workflow end-to-end via this very plan -status: finished -created: "2026-05-12T00:00:00-03:00" -updated: "2026-05-25T00:00:00-03:00" -started_at: "2026-05-12T00:00:00-03:00" -assignee: null -blockers: [] -blocked_reason: null -blocked_since: null -ship_commit: 7bd0f257457a5ef4a18220b8307224857ac268a2 -tags: [meta, dogfood] -affected_paths: - - docs/plans/AGENTS.md - - plugins/docks/skills/plan-init/references/plans-agents-md-template.md - - plugins/docks/skills/plan-init/SKILL.md - - plugins/docks/skills/plan-manager/SKILL.md - - plugins/docks/skills/plan-review/SKILL.md - - plugins/docks/agents/plan-manager.md - - plugins/docks/agents/plan-review.md - - plugins/docks/commands/plan.md - - AGENTS.md -related_plans: [] -review_status: passed ---- - -# Smoke-test the docks:plans handoff-grade redesign - -## Goal - -Validate that the rebuilt `docs:plans` convention works end-to-end. Concretely: a plan file using the new schema (with `goal`, `started_at`, `tags`, `affected_paths`, `related_plans`, `review_status` frontmatter plus the new `## Goal` / `## Steps` / `## Mistakes & Dead Ends` / `## Sources` / `## Evidence log` / `## Review` body sections) can be created, listed in three pretty-print tiers (goal-listing, bulk digest with category-specific age tokens, single-plan preview), moved through `planned/ → ongoing/ → finished/` with `started_at` set on first ongoing entry and `ship_commit` set on ship, and reviewed by the new `plan-review` skill which writes a structured `## Review` block. - -## Context - -The previous plans system worked but plan files were shallow (no `goal`, no structured `Steps` with parallelism, no `Mistakes & Dead Ends` journal, no `Sources` log, no `Review` section). Pretty-print used ambiguous `X days` tokens. The `/docks:plan` slash command had been over-built into a multi-arg dispatcher when the original intent was a one-shot bootstrap. This redesign moved every runtime operation into cross-tool skills triggered by natural language, deleted the slash command, and extended plan files into complete handoff documents. This smoke-test plan exists to dogfood the result. - -## Steps - -| # | Task | Depends | Parallel | Status | Owner | -|---|---|---|---|---|---| -| 1 | Update `docs/plans/AGENTS.md` with new schema + sections + age tokens | — | with #2 | done | self | -| 2 | Update `plan-init/references/plans-agents-md-template.md` in lockstep | — | with #1 | done | self | -| 3 | Create `plan-manager` skill | 1, 2 | with #4 | done | self | -| 4 | Create `plan-review` skill | 1, 2 | with #3 | done | self | -| 5 | Update `plan-init/SKILL.md` to mention new sibling skills | 1 | with #6, #7 | done | self | -| 6 | Refactor `plan-manager` agent to thin opus wrapper | 3 | with #7 | done | self | -| 7 | Create `plan-review` agent (thin opus wrapper) | 4 | with #6 | done | self | -| 8 | Delete `plugins/docks/commands/plan.md` | — | — | done | self | -| 9 | Update root `AGENTS.md` with `` block | 3, 4 | — | done | self | -| 10 | Run `bash scripts/ci.sh` — verify guards + scorers green | 1–9 | — | done | self | -| 11 | Smoke-test: this plan file + lifecycle demonstration | 10 | — | done | self | - -### Step details - -- **#1 + #2** — Lockstep edit. Both files received identical body content; only differences are the `{{ISO_DATE}}` placeholder (template) vs literal timestamp (canonical) and the wrapping 4-backtick code fence (template only). -- **#3 + #4** — New skills target 16/16 on `score-skills.sh` via 4 constraints each (capped at 3 for scoring), Wrong/Right traps table for BAD/GOOD credit, multiple code fences with language tags, body in 80–310 line sweet spot. -- **#6 + #7** — Agent bodies shrank to ~85 lines each but stayed substantive via the 4 (plan-manager) / 2 (plan-review) unique constraints + Workflow + Anti-Hallucination + Success Criteria + context7 mention. plan-manager scores 15/15; plan-review 14/15. -- **#10** — Full CI pass: 27 skills (score 406, floor 216), 3 commands (63/63 — perfect since plan.md deleted), 22 agents (320, floor 308). -- **#11** — This plan file IS the smoke test artifact; demonstrates schema, sections, and 3-tier pretty-print render. - -## Acceptance criteria - -- [x] All frontmatter fields documented in `docs/plans/AGENTS.md` are present and valid in this file (`title`, `goal`, `status`, `created`, `updated`, `started_at`, `assignee`, `blockers`, `blocked_reason`, `blocked_since`, `ship_commit`, `tags`, `affected_paths`, `related_plans`, `review_status`). -- [x] All 12 canonical body sections present with non-trivial content (or heading-only for optional sections 6–11). -- [x] `## Steps` table includes the `Depends` and `Parallel` columns with at least one row demonstrating each. -- [x] `## Mistakes & Dead Ends` entries follow the structured shape `****: → → `. -- [x] `## Sources` entries pair each URL with the concept it clarified. -- [x] Plan moves through `planned/ → finished/` with `started_at` set — completed by this ship (`started_at: 2026-05-12`, `ship_commit: 7bd0f25`). Routed planned→finished directly (the work was already complete at creation), not via `ongoing/`. -- [x] `plan-review` auto-fires on the `→ finished/` move and writes a structured `## Review` block. - -## Out of scope - -- Migration of existing plan files (none exist — all category dirs hold only `.gitkeep`). -- A plan-health scorer (`scripts/score-plans.sh`) — follow-up. -- `affected_paths`-based conflict detection between ongoing plans — follow-up. -- Codex-equivalent `.toml` subagent files — Codex consumes the skills directly; no subagent needed for plans. - -## Mistakes & Dead Ends - -- **2026-05-12**: First draft of the redesign added `/docks:plan` subcommands (`review`, `new`) on top of the existing `show/list/check-scheduled/migrate-from-roadmap` dispatcher → user clarified the original `/docks:plan` was only meant to bootstrap with no arguments, and runtime operations belong in skills → avoid by asking about a command's original scope BEFORE adding subcommands; check whether a skill could replace the command before extending it. -- **2026-05-12**: First draft of Tier-2 pretty-print used bare `6 days` with no contextual word → user pointed out "days" is ambiguous (since creation? in category? since last edit?) → avoid by always pairing age numbers with a category-specific contextual word (`6d queued`, `2d in flight`, `blocked 47d`, `fires in 5d`, `shipped 4d ago`); added `started_at` frontmatter so the `ongoing/` token is exact, not approximated. -- **2026-05-12**: First Tier-2 example showed a row in `ongoing/` tagged "blocked → see plan", which contradicts the convention (blocked plans live in `blocked/`, not `ongoing/`) → avoid by sanity-checking example rows against lifecycle rules before publishing them. - -## Sources - -- https://github.com/mattpocock/skills/blob/main/skills/productivity/handoff/SKILL.md — reference-driven handoff structure; inspires the "every plan is a complete handoff document" framing and the `## Sources` section pairing URLs with what each clarified -- https://github.com/vercel-labs/agent-browser — session-isolation pattern and deterministic refs (`@e1`); inspires the deterministic `#N` step IDs in the `## Steps` table -- https://learn.microsoft.com/en-us/agent-framework/workflows/orchestrations/handoff — decentralized routing; inspires the `Depends` + `Owner` columns as a routing graph declaration -- https://fast.io/resources/ai-agent-state-checkpointing/ — 4-layer checkpoint state (mission / tool-env / model-config / artifact-refs); maps to `goal/status`, `affected_paths`, `assignee`, `sources`/`related_plans` -- https://github.com/TauricResearch/TradingAgents — per-step decision log capturing what + WHY; inspires `## Mistakes & Dead Ends` -- `plugins/docks/agents/plan-manager.md` (pre-refactor) — the 7-step workflow whose substance migrated into the new `plan-manager` skill (now an 8-step workflow with new-plan scaffolding added) -- `plugins/docks/agents/refactor-post-verifier.md` — template for `plan-review` (validator-runner + delta-reporter pattern) - -## Blockers - -(none — actionable now; this plan tracks the redesign work that's already largely complete) - -## Notes - -- Eating own dog food: this plan uses every new frontmatter field and every new body section, including the 3-entry `## Mistakes & Dead Ends` populated with the actual planning-session mistakes from this redesign. -- `started_at: 2026-05-12` — the redesign work (`7bd0f25`) was already complete when this plan was created, so it documents same-day work; it sat in `planned/` only because the final lifecycle move was overlooked. -- `affected_paths` lists every file touched by the redesign so the eventual `plan-review` can run the scope-drift check. -- **Closed 2026-05-25**: the two previously-deferred criteria (lifecycle move + plan-review) are now satisfied by this very ship — the smoke test completed by shipping itself through the system it validates. The `docs:plans` redesign (`7bd0f25`) has been in continuous use since 2026-05-12 (8+ plans shipped through it). - -## Evidence log - -- 2026-05-12T12:55 -03:00 — Plan research phase (three Explore agents: current-plans inventory, handoff/agent-browser research, sibling-agent reference patterns) -- 2026-05-12T13:10 -03:00 — User confirmed scope decisions: bundle bonus frontmatter, both auto+manual plan-review trigger, structured Mistakes entries -- 2026-05-12T13:30 -03:00 — User requested Codex equivalent via skills; plan extended to cross-tool skill-first architecture -- 2026-05-12T13:50 -03:00 — User clarified ambiguous "X days" tokens; pretty-print rewritten with category-specific age tokens + `started_at` field added -- 2026-05-12T14:10 -03:00 — User clarified `/docks:plan` was bootstrap-only (no arguments); plan rewritten skill-first, slash command deleted, root AGENTS.md `` block added -- 2026-05-12T15:30 -03:00 — Implementation complete: `docs/plans/AGENTS.md` + plan-init template rewritten; `plan-manager` + `plan-review` skills created (both 16/16); plan-manager agent refactored to thin opus wrapper (15/15); plan-review agent created (14/15); `/docks:plan` command deleted; root AGENTS.md updated; `bash scripts/ci.sh` green -- 2026-05-12T15:45 -03:00 — This smoke-test plan file written as dogfood of the new schema - -## Review - -- **Goal met:** yes — All 7 `[x]` criteria are evidence-backed in `7bd0f25`: the diff documents the full 15-field frontmatter schema + 12 canonical body sections in `docs/plans/AGENTS.md`, the `Steps` Depends/Parallel columns, category-specific age tokens (replacing bare `X days`), and wires `plan-review` auto-fire on `→ finished/` (plan-manager skill Step 8). The lifecycle move + plan-review criteria are satisfied by this very ship — the smoke test completes itself. Live corroboration: the redesigned system has shipped 8+ plans through plan-manager + plan-review since 2026-05-12. -- **Regressions:** none — CI green; no offending pattern found on reproduction reads of the changed skills/agents/AGENTS files. -- **CI:** pass (`bash scripts/ci.sh` exit 0; workflow-YAML step is a local `⚠ skipped` for missing pyyaml, not a failure — GitHub tag-CI validates it regardless). -- **Scope:** no drift — all 9 `affected_paths` appear in the `7bd0f25` diff (incl. the planned deletion of `plugins/docks/commands/plan.md`); the only unannounced change is the plan file creating itself, which is expected. The skills have since relocated to `plugins/docks/skills/productivity/` (foundation-categorization) — a later, separately-reviewed plan, not drift in this one. -- **Follow-ups:** none — the two `## Out of scope` deferrals (`scripts/score-plans.sh`, `affected_paths` conflict detection) remain valid future work but are not regressions; file them via "new plan " only if/when desired. -- Filed by: plan-review on 2026-05-25T00:14:50-03:00 diff --git a/docs/plans/finished/2026-05-12-skills-references-extraction.md b/docs/plans/finished/2026-05-12-skills-references-extraction.md deleted file mode 100644 index 680d5e6c..00000000 --- a/docs/plans/finished/2026-05-12-skills-references-extraction.md +++ /dev/null @@ -1,199 +0,0 @@ ---- -title: Introduce on-demand references/ files in 6 skills -goal: Lift deep per-language/per-framework/per-tool content into references/ for solid, test-coverage, dep-vuln-workflow, lint-no-suppressions, code-review, fix-workflow — main SKILL.md becomes decision-tree + top-rules -status: finished -created: "2026-05-12T00:00:00-03:00" -updated: "2026-05-12T00:00:00-03:00" -started_at: "2026-05-12T00:00:00-03:00" -assignee: null -blockers: [] -blocked_reason: null -blocked_since: null -ship_commit: 584a53dc62655de331cfd748a2d7dd016b779c0b -tags: [skills, refactor, references] -affected_paths: - - plugins/docks/skills/solid/ - - plugins/docks/skills/test-coverage/ - - plugins/docks/skills/dep-vuln-workflow/ - - plugins/docks/skills/lint-no-suppressions/ - - plugins/docks/skills/code-review/ - - plugins/docks/skills/fix-workflow/ -related_plans: [] -review_status: passed ---- - -# Introduce on-demand references/ files in 6 skills - -## Goal - -Restructure 6 skills so each one's main SKILL.md becomes a thin **decision tree + top-rules + 1–2 BAD/GOOD pairs + 2–3 `` blocks** that routes the agent to per-language, per-framework, or per-tool `references/.md` files for deep content. Mirrors the pattern proven in the prior audit: - -- `react-component-patterns` — 94-LOC SKILL.md decision tree + 174-LOC `references/effects.md` + 298-LOC `references/composition.md` -- `type-safety-discipline` — TS-primary SKILL.md body + `references/{rust-newtype,kotlin-value-class,python-typing}.md` - -Each restructured skill must: - -- Keep its per-file scorer score ≥ 8 (current floor); preferably retain or improve its current 14–16 score -- Keep its CSO description tight (lead with concept triggers; first 100 chars matter most for matching) -- Retain at least one BAD/GOOD code pair and 2–3 `` blocks in the main SKILL.md body (the scorer rewards both) -- Carry an unambiguous decision tree at the top of SKILL.md so the agent loads the right references file on first read - -## Context - -The prior skills-audit commit introduced the references/ pattern with concrete proof: an inactive skill costs nothing from references (they live on disk; only SKILL.md description loads into the session listing), and an active skill loads only the specific references file relevant to the task. This frees the SKILL.md body for tight rules + decision tree without bloating per-skill cost. The 6 candidate skills currently have monolithic bodies covering multiple stacks/tools/axes — they're exactly the cases where references would help. - -Current state of the 6 affected skills (LOC = body line count from `wc -l`): - -- `solid` — 228 LOC, TS-primary code examples, mentions Python/Go in passing but no deep examples -- `test-coverage` — ~161 LOC, generic 6-step framework but no per-framework templates -- `dep-vuln-workflow` — ~170 LOC, multi-ecosystem (pnpm/npm/yarn/pip/cargo/go) in main body -- `lint-no-suppressions` — ~117 LOC, ESLint-leaning examples -- `code-review` — ~145 LOC, covers bug/security/perf/maintainability/AI-slop axes -- `fix-workflow` — ~168 LOC, tier-1/2/3 plans but no per-finding-type templates - -## Steps - -| # | Task | Depends | Parallel | Status | Owner | -|---|---|---|---|---|---| -| 1 | Restructure `solid` → universal-language SKILL.md + `references/{typescript,rust,python,go}-solid.md` (per-principle deep examples per language) | — | with #2-#6 | **done** | self | -| 2 | Restructure `test-coverage` → generic 6-step body + `references/{jest-vitest,pytest,junit,cargo-test,go-test}.md` (per-framework templates: file layout, assertion idioms, mocking conventions, fixture patterns) | — | with #1,#3-#6 | **done** | self | -| 3 | Restructure `dep-vuln-workflow` → triage process body + `references/{npm-pnpm,pip,cargo,go-mod}-playbook.md` (per-ecosystem audit commands, severity-triage flags, major-version upgrade order) | — | with #1,#2,#4-#6 | **done** | self | -| 4 | Extend `lint-no-suppressions` → keep body lean + extract bash hook to `references/pre-commit-hook.md` + add `references/per-tool-catalog.md` (suppression syntax for ESLint, TS / `@ts-ignore` / `@ts-expect-error`, mypy, ruff, clippy, golangci-lint, shellcheck, pylint, Java) | — | with #1-#3,#5,#6 | **done** | self | -| 5 | Restructure `code-review` → SKILL.md as per-axis triage decision tree + `references/{security,perf,maintainability}.md` (per-axis finding catalogue, severity calibration, common false-positive guards; ai-slop merged into maintainability) | — | with #1-#4,#6 | **done** | self | -| 6 | Restructure `fix-workflow` → main body as tier-1/2/3 framework + `references/{security-fix,perf-fix,bug-fix}-templates.md` (per-finding-type plan templates with revert triggers and test strategy) | — | with #1-#5 | **done** | self | -| 7 | Run `bash scripts/ci.sh` and `bash scripts/score-skills.sh --per-file` after EACH skill restructure; verify guard pass and per-file score ≥ 8 | 1-6 (incrementally) | — | **done** | self | -| 8 | Update `metadata.updated` frontmatter on each restructured skill | 1-6 | — | **done** | self | -| 9 | Commit: one commit per skill OR one batched commit (decide based on diff size; rule of thumb: batch if total <500 LOC changed, split if >500). Push to main. | 7, 8 | — | **done** (6 per-skill commits chosen) | self | - -Status enum: `planned` / `in-flight` / `done` / `blocked` / `skipped`. - -## Acceptance criteria - -- [x] All 6 skills restructured with at least one `references/` file each — confirmed: 20 references files total across the 6 skills (4 + 5 + 4 + 2 + 3 + 3 - 1 dual-use? actually: solid 4 + test-coverage 5 + dep-vuln 4 + lint-no-supp 2 + code-review 3 + fix-workflow 3 = 21) -- [x] Each restructured skill's per-file score ≥ 8 (current floor); preferably ≥ 14 — actual: solid 16, test-coverage 16, dep-vuln 15, lint-no-supp 13 (below ≥14 stretch target by 1 — body 72 LOC sits below sweet spot 80–310; acceptable given floor 8), code-review 16, fix-workflow 16 -- [x] `bash scripts/ci.sh` green end-to-end after each commit — verified across all 6 commits -- [x] `grep -rn 'references/' plugins/docks/skills/{solid,test-coverage,dep-vuln-workflow,lint-no-suppressions,code-review,fix-workflow}/` confirms every named references file exists (no dangling pointers) — verified at 2026-05-12T17:38 -- [x] Each SKILL.md body retains ≥1 BAD/GOOD code pair and ≥2 `` blocks (scorer signal preservation) — all 6 retain ≥2 constraints + canonical BAD/GOOD or per-axis routing -- [x] Description listing budget stays under 50% of `SLASH_COMMAND_TOOL_CHAR_BUDGET` (currently ~37% — net effect should be roughly flat since descriptions don't grow) — descriptions remained roughly flat; solid's description added "Rust / Python / Go" but stayed under 500 -- [x] Manual sanity check: read each restructured SKILL.md in isolation and confirm the decision tree unambiguously routes to the correct references file — all 6 SKILL.md files now lead with When-to-Load-References table that unambiguously routes based on language / framework / finding type - -## Out of scope - -- Skills NOT in the 6-skill list (tdd-workflow, agents, plan-init/manager/review are already tight or orchestration-only; design-tokenization and make-interfaces-feel-better already have references; type-safety-discipline and react-component-patterns are the predecessors) -- The `forked-*` orchestration wrappers (intentionally tiny; references would be over-engineering) -- New skill additions -- Description rewrites (only update a description if extraction reveals it's now misleading) -- Cross-tool guard for SKILL.md ↔ references/ pointer validation — useful but separate plan -- Plugin manifest/marketplace.json edits (descriptions enumerate themes, not individual files; no change needed) -- Codex manifest regeneration (no Claude-side description changes here, so Codex side stays in sync via `release.sh` version lockstep alone) - -## Mistakes & Dead Ends - -(empty — append entries as the work proceeds) - -## Sources - -- `/home/docks/.claude/plans/analyze-the-whole-plugin-snappy-neumann.md` — the prior audit plan that established the references/ pattern, including the primary-language-first structure decision -- Latest commit on main: `refactor(skills): audit out stack-specific drift; merge + generalize + prune` — the predecessor that introduced `react-component-patterns` and `type-safety-discipline` as references-using exemplars -- `plugins/docks/skills/type-safety-discipline/SKILL.md` + `references/` — concrete example of TS-primary + per-language references (Rust/Kotlin/Python) -- `plugins/docks/skills/react-component-patterns/SKILL.md` + `references/` — concrete example of merged-skill-with-decision-tree (effects + composition) -- `scripts/score-skills.sh` — scorer mechanics; per-file floor 8/16; rewards `` blocks (up to 3), BAD/GOOD code pairs, freshness, table density -- `scripts/guard-skills.sh` — structural validator (frontmatter, ≤500 lines, name-matches-dir) -- `CLAUDE.md` § "Authoring skills, commands & agents" — description budget, listing truncation rules (1,536 chars per description, 8K total at default budget) -- agentskills.io specification — references/ files load on-demand only when SKILL.md body instructs Read - -## Blockers - -(none — actionable immediately) - -## Notes - -- **Scorer signal preservation:** the scorer rewards `` blocks (≤3 max credit) and BAD/GOOD code pairs in the SKILL.md body. When extracting content to references/, ensure each main SKILL.md retains the most-illustrative BAD/GOOD pair AND 2–3 strongest `` blocks. If a skill currently has 3 constraints, redistribute carefully — don't drop below 2. -- **Cross-reference discipline:** every references/.md mentioned in SKILL.md must exist. There is no validator for this yet — manual grep check after each restructure (acceptance criterion #4 above covers this). -- **Per-language scope decisions:** - - `solid`: TS-primary (current state) + Rust + Python + Go = 4 references files. Skip Kotlin/Swift unless trivial; kit users skew JS/Python/Rust/Go. - - `test-coverage`: Jest+Vitest combined (npm ecosystem) + pytest + JUnit + cargo test + go test = 5 references files - - `dep-vuln-workflow`: npm+pnpm combined + pip + cargo + go mod = 4 playbook references files -- **Single vs multiple references for `lint-no-suppressions`:** one consolidated `per-tool-catalog.md` is fine here because the suppression-syntax topic is narrow (just the syntax forms per tool, plus one universal rule: "include a reason on the same line"). Don't fragment. -- **Description budget impact:** descriptions don't grow in this plan (only bodies and references move). Listing budget impact ≈ 0. -- **Body line-count target:** after restructure, aim for 80–200 LOC in each SKILL.md (well within scorer sweet spot 80–310). Current bodies are 117–228 LOC, so most have headroom even before extraction. -- **Commit strategy decision:** prefer per-skill commits unless a single skill's diff is trivial (<50 LOC), in which case batch with the next one. Avoid one mega-commit covering all 6 — review burden too high. - -### Research findings (2026-05-12) - -Two parallel Explore agents mapped each affected skill's current body, extraction targets (file:line), and scorer-signal preservation. **All 6 skills currently score 16/16; all retain ≥2 `` blocks and ≥1 BAD/GOOD pair post-extraction → no risk of dropping below per-file floor 8.** - -**1. `solid` (228 LOC → ~100–120 LOC main)** -- 4 references: `typescript-solid.md`, `rust-solid.md`, `python-solid.md`, `go-solid.md` -- Verbatim TS extraction: lines 56–79 (S strategy map), 93–121 (L discriminated union), 135–152 (I split), 167–200 (D injection) ≈ 110 LOC -- Fresh authoring: ~150 LOC each for Rust/Python/Go idiomatic per-principle examples (Rust newtype + trait-object + enum-match; Python dataclass + Protocol + ABC; Go interface + composition + replace-directives) -- Stay in main: 3 constraints (lines 14–24), O-section BAD/GOOD (Strategy Map — most universal), Common Traps table (lines 218–227) -- Estimated post-restructure score: 14–15/16 - -**2. `test-coverage` (161 LOC → ~80–100 LOC main)** -- 5 references: `jest-vitest.md`, `pytest.md`, `cargo-test.md`, `go-test.md`, `junit.md` -- Verbatim extraction: Step 3 example only (lines 64–81) ≈ 8 LOC; rest needs fresh per-framework templates -- Fresh authoring: ~120 LOC each for jest-vitest + pytest (file layout, describe/it or fixtures, mocking, assertions, coverage config); ~100 LOC each for cargo-test, go-test, junit -- Stay in main: 3 constraints (lines 12–22), Step 3 import-path BAD/GOOD (lines 64–81 — universal across frameworks) -- Estimated post-restructure score: 14–15/16 - -**3. `dep-vuln-workflow` (168 LOC → ~90–110 LOC main)** -- 4 references: `npm-pnpm-playbook.md`, `pip-playbook.md`, `cargo-playbook.md`, `go-mod-playbook.md` -- Verbatim extraction: lines 44–54 (pnpm upgrade), 128–134 (Next/React upgrade surprises), 157–161 (npm-specific gotchas) ≈ 22 LOC → `npm-pnpm-playbook.md` -- Fresh authoring: ~30 LOC fresh in npm-pnpm-playbook (yarn/npm equivalents); ~100 LOC each for pip / cargo / go-mod playbooks -- Stay in main: 3 constraints (lines 12–13, 104–106, 151–153), Split Strategy BAD/GOOD (lines 78–100 — language-neutral commit discipline) -- Move to `npm-pnpm-playbook.md`: Lint/Typecheck BAD/GOOD (lines 117–126 — React/Next-specific) -- Estimated post-restructure score: 15–16/16 - -**4. `lint-no-suppressions` (105 LOC → ~50–60 LOC main)** -- 2 references: `pre-commit-hook.md`, `per-tool-catalog.md` -- Verbatim extraction: bash pre-commit hook (lines 47–93) ≈ 47 LOC → `pre-commit-hook.md` -- Fresh authoring: ~100–120 LOC per-tool catalog (ESLint, TS `@ts-ignore` / `@ts-expect-error` / `@ts-nocheck`, mypy `# type: ignore`, ruff `# noqa`, clippy `#[allow]`, golangci-lint `//nolint`, shellcheck, pylint, Java `@SuppressWarnings`) -- Stay in main: 2 constraints (lines 12–14, 99–101), decision table (lines 33–42) -- Estimated post-restructure score: 16/16 maintained - -**5. `code-review` (136 LOC → ~100–110 LOC main)** -- 4 references (or 3 — see open decision below): `security.md`, `perf.md`, `maintainability.md`, `ai-slop.md` -- Verbatim extraction: ~10 LOC of categorization prose (Step 3, lines 59–68) -- Fresh authoring: ~60–80 LOC security (OWASP Top 10 finding templates + severity calibration), ~50–70 LOC perf (N+1, loops, sync I/O, render cascades), ~40–60 LOC each for maintainability + ai-slop -- Stay in main: all 3 constraints (lines 12–22), Common Traps table (lines 101–111), Output Example (lines 113–131) -- Estimated post-restructure score: 16/16 maintained - -**6. `fix-workflow` (168 LOC → ~127 LOC main)** -- 3 references: `security-fix-templates.md`, `perf-fix-templates.md`, `bug-fix-templates.md` -- Verbatim extraction: Step 4 template table (lines 85–100) ≈ 16 LOC stays in main as the framework; per-finding-type expansions are new -- Fresh authoring: ~50–70 LOC each (security-fix: CVE/GHSA triage + dependency bump test strategy + security-specific revert triggers; perf-fix: profiling commands + perf revert triggers + common perf anti-patterns; bug-fix: reproduction test template + integration-vs-unit decision + regression-prevention) -- Stay in main: all 3 constraints (lines 12–22), Steps 1–6 framework, Common Traps table (lines 133–145), Pairing With Other Skills (lines 146–154) -- Estimated post-restructure score: 16/16 maintained - -**Total scope summary:** -- 22 references files (21 if `ai-slop` merges into `maintainability` for code-review) -- ~250 LOC verbatim extraction across all 6 skills -- ~1,600 LOC fresh authoring (Rust/Python/Go SOLID; pytest / cargo-test / go-test / junit templates; pip / cargo / go-mod playbooks; per-tool suppression catalog; per-axis review references; per-finding-type fix templates) -- Per-skill post-restructure scores estimated at 14–16/16; per-file floor 8 not at risk - -**Open decisions for implementer:** -1. **`test-coverage`:** keep `junit.md` (Java/JVM) in scope, or defer? Kit users skew JS/Python/Rust/Go. -2. **`code-review`:** 4 references files (keep `ai-slop` separate) or 3 (merge into `maintainability` since they overlap substantially)? -3. **Implementation order (suggested):** `lint-no-suppressions` (smallest, mostly extract — validates the pattern) → `dep-vuln-workflow` (~22 LOC extract + 4 playbooks) → `fix-workflow` (3 templates, tight scope) → `code-review` (4 per-axis references) → `test-coverage` (5 per-framework references) → `solid` (4 languages, largest fresh authoring). -4. **Commit strategy:** per-skill (6 commits) recommended. Per-reference-file (22 commits) too granular; batched mega-commit too large for review. - -## Evidence log - -- **2026-05-12T16:07:30-03:00** — Plan created — assistant (Claude Opus 4.7) -- **2026-05-12T16:23:14-03:00** — Research completed via 2 parallel Explore forks (skills 1–3 + 4–6); per-skill extraction plans recorded in Notes; 4 open decisions surfaced — assistant (Claude Opus 4.7) -- **2026-05-12T16:57:24-03:00** — Plan started (planned/ → ongoing/, set started_at); Step #4 done: restructured `lint-no-suppressions` — SKILL.md 117→72 LOC, new `references/pre-commit-hook.md` (100 LOC, lifts the bash hook + CI mirror), new `references/per-tool-catalog.md` (166 LOC, covers ESLint/TS/mypy/ruff/pylint/clippy/golangci-lint/shellcheck/Java with same-line-reason rule); per-file score 16→13 (above floor 8, above plan AC ≥14 floor: short by 1 point — body LOC 72 sits below scorer sweet spot 80–310) — assistant (Claude Opus 4.7) -- **2026-05-12T17:02:00-03:00** — Step #3 done: restructured `dep-vuln-workflow` — SKILL.md 168→133 LOC (within sweet spot 80–310), 4 new references files (`npm-pnpm-playbook.md` 97 LOC, `pip-playbook.md` 91 LOC, `cargo-playbook.md` 87 LOC, `go-mod-playbook.md` 87 LOC; total 362 LOC of per-ecosystem content); main body retains 3 `` blocks + Split Strategy BAD/GOOD pair; per-file score 15/16 (above AC ≥14 floor); guard PASS — assistant (Claude Opus 4.7) -- **2026-05-12T17:10:00-03:00** — Step #6 done: restructured `fix-workflow` — SKILL.md 168→179 LOC (added When-to-Load-References routing table; still within sweet spot 80–310), 3 new references files (`security-fix-templates.md` 58 LOC with attacker-targeted test strategy + OWASP mapping, `perf-fix-templates.md` 70 LOC with profiling matrix + regression thresholds, `bug-fix-templates.md` 82 LOC with reproduction template + bisect playbook); main body retains all 3 `` blocks and Common Traps table; per-file score 16/16 maintained; guard PASS — assistant (Claude Opus 4.7) -- **2026-05-12T17:17:00-03:00** — Step #5 done: restructured `code-review` (ai-slop merged into maintainability, 3 references not 4) — SKILL.md 145→156 LOC (added When-to-Load routing table after Step 3; still within sweet spot 80–310), 3 new references files (`security.md` 63 LOC with OWASP Top 10 → finding-template mapping + 3-question severity calibration + common false-positives, `perf.md` 87 LOC with per-domain pattern catalog DB/loop/async/render + calibration matrix, `maintainability.md` 104 LOC with dead-code + duplication + smart-abstraction + 11-row AI-slop tells catalog); main body retains all 3 `` blocks, Common Traps table, Output Example; per-file score 16/16 maintained; guard PASS — assistant (Claude Opus 4.7) -- **2026-05-12T17:25:00-03:00** — Step #2 done: restructured `test-coverage` — SKILL.md 161→167 LOC (added When-to-Load routing table after Step 1; still within sweet spot 80–310), 5 new references files (`jest-vitest.md` 119 LOC with detection signals + co-located/__tests__ naming + Vitest/Jest mock differences + RTL idioms, `pytest.md` 149 LOC with fixtures + scopes + monkeypatch + pytest-asyncio + conftest precedence, `cargo-test.md` 178 LOC with unit-vs-integration layout + trait-object DI + mockall + tokio::test + cargo-llvm-cov, `go-test.md` 204 LOC with white-vs-black-box packages + table-driven subtests + t.Cleanup + httptest + Go 1.22 loop-var fix, `junit.md` 210 LOC with mirroring layout + @Nested + Mockito strict stubbing + Spring slice tests + JaCoCo); main body retains all 3 `` blocks AND the universal import-path BAD/GOOD pair in Step 3; per-file score 16/16 maintained; guard PASS; some references > 150 LOC soft guideline (cargo/go/junit) — accepted because per-framework topic depth is real and on-demand load means zero cost when inactive — assistant (Claude Opus 4.7) -- **2026-05-12T17:35:00-03:00** — Step #1 done: restructured `solid` — SKILL.md 235→144 LOC (clean trim; deep per-principle code examples lifted out; main body now smell→fix tables + indicators + canonical O-section Strategy Map BAD/GOOD pair + Decision Tree + Common Traps; well within sweet spot 80–310). 4 new references files (`typescript-solid.md` 188 LOC with all 5 principles + ExtractMappedType pattern + exhaustiveness sentinel + function-argument DI, `rust-solid.md` 218 LOC with HashMap-of-fn + non_exhaustive enum + sealed-trait pattern + generics-vs-dyn DI matrix, `python-solid.md` 228 LOC with dict-of-callable + match + assert_never exhaustiveness + Protocol structural typing + constructor-or-argument injection, `go-solid.md` 254 LOC with map-of-func + sealed-interface sum type via isType() seal + caller-side small interfaces + accept-interfaces-return-structs idiom + ChargeFn fn-arg form). Main body retains all 3 `` blocks + the canonical Strategy Map BAD/GOOD + Common Traps table; per-file score 16/16 maintained; guard PASS; references 188-254 LOC over 150-LOC soft guideline but justified by 5-principle depth × language idioms — assistant (Claude Opus 4.7) -- **2026-05-12T17:38:00-03:00** — Plan shipped: all 6 SKILL.md files now route to references/ on activation; final acceptance check confirmed every pointer resolves; ship_commit 584a53dc; moving from ongoing/ to finished/2026-05-12-skills-references-extraction.md — assistant (Claude Opus 4.7) - -## Review - -- **Goal met:** yes — all 6 SKILL.md files route to 21 new `references/` files via explicit "When to Load References" tables; per-file scores held at solid 16, test-coverage 16, dep-vuln 15, code-review 16, fix-workflow 16, lint-no-suppressions 13 (1 below the ≥14 plan stretch but above floor 8 — body 64 LOC sits below scorer sweet spot 80–310 because content moved to references; acknowledged in plan AC #2). -- **Regressions:** none — `affected_paths` covers all 27 changed files (no scope drift, no unannounced changes); each restructured SKILL.md retains ≥3 `` blocks plus Wrong/Right table-form fix patterns (lint-no-suppressions, code-review, fix-workflow use Wrong-fix → Right-fix tables in lieu of literal BAD/GOOD blocks — AC #5 explicitly permits the per-axis-routing alternative). -- **CI:** pass — `bash scripts/ci.sh` exits 0 (369/200 skills, 63/63 commands, 320/308 agents; per-file floors all clear). -- **Follow-ups:** none — the 1-point lint-no-suppressions stretch miss is acknowledged in-plan, not a regression worth a new plan. -- Filed by: plan-review on 2026-05-12T17:26:48-03:00 diff --git a/docs/plans/finished/2026-05-24-foundation-categorization-scoring.md b/docs/plans/finished/2026-05-24-foundation-categorization-scoring.md deleted file mode 100644 index 48c0fc12..00000000 --- a/docs/plans/finished/2026-05-24-foundation-categorization-scoring.md +++ /dev/null @@ -1,152 +0,0 @@ ---- -title: Categorize skills/agents into folders with per-category scoring -goal: Split skills + agents into engineering/productivity/internal folders, declare in plugin.json, rebalance score floors per category -status: finished -created: "2026-05-24T00:00:00-03:00" -updated: "2026-05-24T00:00:00-03:00" -started_at: "2026-05-24T00:00:00-03:00" -assignee: null -blockers: [] -blocked_reason: null -blocked_since: null -ship_commit: 6c818d524457d1981b86a3784d892e9ed28bf29a -tags: [foundation, refactor, scoring] -affected_paths: - - plugins/docks/.claude-plugin/plugin.json - - plugins/docks/.codex-plugin/plugin.json - - plugins/docks/skills/engineering/ - - plugins/docks/skills/productivity/ - - plugins/docks/skills/internal/ - - scripts/scoring.config.json - - scripts/read-floor.sh - - scripts/guard-skills.sh - - scripts/score-skills.sh - - scripts/guard-commands.sh - - scripts/score-commands.sh - - scripts/ci.sh -related_plans: [skill-maintainer-fixes, tree-skill, codex-agents-dual-emit, scaffold] -review_status: passed ---- - -# Categorize skills/agents into folders with per-category scoring - -## Goal - -Replace the flat `plugins/docks/{skills,agents}//` layout with a three-folder categorization (`engineering/`, `productivity/`, `internal/`); declare each category as an explicit path in `plugin.json` (depth-1 auto-discovery requirement); update guards and scorers to walk depth-2; rebalance score floors so each category gets a calibrated bar (engineering raised, internal lowered, productivity unchanged). The forked-* wrappers stop needing filler to clear an inappropriate floor; user-facing engineering skills get a higher bar. - -## Context - -Two coupled problems: - -1. At ~30 skills the flat directory clutters — forked-* wrappers mixed with user-facing skills mixed with workflow tools. Naming prefixes (`docs-`, `forked-`, `plan-`) implicitly categorize today; folders make it explicit. -2. The uniform ≥8/16 score floor forces forked-* wrappers (thin `context: fork` helpers, ~30 lines) to inflate with filler to pass. Per-category floors fix the calibration. - -They ship together: per-category scoring needs categories to scope to. - -Structural plan — no behavior changes, no new skills, no new agents. Every later plan touches paths or validators that change here, so this lands first. - -## Steps - -| # | Task | Depends | Parallel | Status | Owner | -|---|---|---|---|---|---| -| 1 | Confirm category assignments with user | — | — | done | self | -| 2 | Add `scripts/scoring.config.json` (skills per-category; agents+commands flat) | 1 | with #3 | done | self | -| 3 | Write `scripts/read-floor.sh` helper (1-arg flat, 2-arg per-category) | 1 | with #2 | done | self | -| 4 | Update `.claude-plugin/plugin.json` with `"skills": [...]` array | 1 | with #5 | done | self | -| 5 | Mirror in `.codex-plugin/plugin.json` | 1 | with #4 | done | self | -| 6 | Move every skill into its category folder | 4, 5 | — | done | self | -| 7 | ~~Move every agent into its category folder~~ — see Mistakes & Dead Ends | — | — | skipped | self | -| 8 | Update `guard-skills.sh` + `score-skills.sh` to walk depth-2 with category prefix | 6 | with #9 | done | self | -| 9 | Update `guard-commands.sh` + `score-commands.sh` agent-resolution paths (no change needed — agents flat) | 6 | with #8 | done | self | -| 10 | Update root `CLAUDE.md` path references | 6 | — | done | self | -| 11 | Add `scripts/ci.sh` skill-category sanity + per-category floor logic | 8, 9 | — | done | self | -| 12 | `bash scripts/ci.sh` green | 2–11 | — | done | self | -| 13 | ~~`./scripts/release.sh patch`~~ — deferred per user instruction (commit only, push later) | — | — | skipped | self | - -### Step details - -- **#1** — Final assignments (skills only — agents stay flat per the constraint discovered in Mistakes & Dead Ends): - - `skills/engineering/` (12): code-review, dep-vuln-workflow, design-tokenization, fix-workflow, human-docs-workflow, lint-no-suppressions, make-interfaces-feel-better, react-component-patterns, solid, tdd-workflow, test-coverage, type-safety-discipline - - `skills/productivity/` (7): agents, caveman, plan-init, plan-manager, plan-review, write-skill, zoom-out - - `skills/internal/` (9): all `forked-*` wrappers -- **#2** — Final `scripts/scoring.config.json` shape (skills per-category, agents+commands flat — calibrated against observed scores): - ```json - { - "skills": { - "engineering": { "per_file_floor": 10 }, - "productivity": { "per_file_floor": 8 }, - "internal": { "per_file_floor": 8 } - }, - "agents": { "per_file_floor": 14 }, - "commands": { "per_file_floor": 21 } - } - ``` -- **#4** — `.claude-plugin/plugin.json` change: `"skills": ["./skills/engineering", "./skills/productivity", "./skills/internal"]`. No `agents` field — `claude plugin validate` rejects it. -- **#5** — `.codex-plugin/plugin.json`: same `"skills": [...]` array. Validated by `jq empty`. -- **#8** — Iteration changes for skills: `for skill_dir in "$DIR"/*/` → `for skill_dir in "$DIR"/*/*/`. `score-skills.sh --per-file` output goes from `name score` to `category/name score`. -- **#9** — Agent + command scripts kept their existing depth-1 paths; only their use of `scoring.config.json` (via `read-floor.sh agents` / `read-floor.sh commands`) changed. -- **#10** — Root CLAUDE.md has one reference to `plugins/docks/agents/*.md` (line 52). Still accurate — agents are flat. -- **#11** — `ci.sh` adds a "category layout" section that checks every category dir listed in `plugin.json` exists on disk and no skill lives outside a category subdir. - -## Acceptance criteria - -- [x] Every existing **skill** lives under a category folder; no skills at `skills//` directly -- [x] **Agents stay flat** at `agents/.md` (constraint — see Mistakes & Dead Ends) -- [x] `.claude-plugin/plugin.json` declares `skills` array of category paths; CI fails if any category dir is missing -- [x] `.codex-plugin/plugin.json` mirrors the skills array -- [x] `score-skills.sh` applies per-category floors via `read-floor.sh`; agents + commands use flat floors from the same config -- [x] Every skill clears its category's floor; agents clear 14; commands clear 21 -- [x] `bash scripts/ci.sh` green -- [x] Root `CLAUDE.md` path references audited — only the agent reference remains, still accurate (flat) - -## Out of scope - -- No new skills, agents, or commands -- No behavior changes to existing skills -- No `misc/` category -- Categorization of commands (only 3 today, no benefit) -- Renaming the `forked-` prefix once they live in `internal/` - -## Mistakes & Dead Ends - -- **2026-05-24**: Tried to categorize agents into `agents//.md` (depth-2) the same way as skills → `claude plugin validate` rejected `"agents":` in plugin.json as either string or array; the Claude Code plugin loader auto-discovers agents at depth-1 only and the manifest doesn't accept an `agents` field at all → reverted: agents stay flat at `agents/.md`; only skills get categorized (plugin.json `skills` array IS supported). `scoring.config.json` simplified: skills per-category, agents+commands flat. Avoid this by checking `claude plugin validate` schema support BEFORE designing a categorization layout — the plugins-reference docs list what fields the manifest accepts. -- **2026-05-24**: Initial floor for `internal/` skills set to ≥4 in the plan body, assuming forked-* wrappers were thin. After `score-skills.sh --per-file` against actual files, all forked-* wrappers score 14 → calibrated floor to 8 (same as productivity) so the bar isn't tautologically met but also doesn't penalize the consistent structural shape they have. Avoid this by running `score-*.sh --per-file` BEFORE setting per-category floors when designing similar plans. -- **2026-05-24**: Sandbox can't remove `.git/index.lock` left by failed git operations OR temp object files left by successful commits → user has to clear the lock manually between commits (`rm /Users/docks/projects/docks/.git/index.lock`). Avoid this by batching all file work into one commit per plan and minimizing git invocations from inside the sandbox; surface the lock-clear command to the user up front when it happens. -- **2026-05-24**: Raising `engineering/` floor to 10 and keeping `productivity/` at 8 newly flagged the two **upstream-vendored** skills — `make-interfaces-feel-better` (score 9, engineering) and `caveman` (score 7, productivity; this one was already below the pre-existing flat-8 floor on `main`). Vendored skills are preserved verbatim per the kit's upstream policy, so editing their bodies to inflate density-based scores is forbidden, and the per-category floors are calibrated against kit-authored skills only → exempted `upstream:` skills from the per-file floor in `ci.sh` (structural guards still gate them; mirrors the CSO/freshness relaxation `score-skills.sh` already applies to upstream skills). Avoid this by deciding upstream-skill floor treatment at the same time as setting per-category floors — a vendored skill can fall below a kit bar without being "broken." - -## Sources - -- https://code.claude.com/docs/en/skills — Claude Code plugin skills are depth-1 auto-discovered; custom paths declared in plugin.json supplement defaults -- https://developers.openai.com/codex/plugins/build — Codex plugin manifest fields, `skills` path declaration -- `scripts/guard-skills.sh` (repo) — current depth-1 iteration pattern this plan changes -- `scripts/score-skills.sh` (repo) — current uniform-floor scoring that per-category replaces - -## Blockers - -(none — actionable immediately) - -## Notes - -- Open questions resolved during execution: - - Agent categorization: not supported by plugin manifest (see Mistakes & Dead Ends). Agents stay flat. - - Forked-* rename: kept the prefix this round (renaming would break every `Skill(skill: "docks:forked-…")` reference). Defer to a separate plan with a sed pass. - - Floor calibration: ran `score-*.sh --per-file` before locking floors. -- Plan tree-skill will later relocate authoring guidance out of root CLAUDE.md into `plugins/docks/skills/AGENTS.md`. This plan only audited path strings. -- Empty `agents/engineering/` and `agents/internal/` directories were left behind on disk after the revert (sandbox can't `rmdir` them); harmless — git doesn't track empty dirs, validators don't see them. - -## Evidence log - -- 2026-05-24T22:00 -03:00 — Plans 01-05 written and committed (`f476df5`); plan 01 moved to ongoing/ -- 2026-05-24T22:15 -03:00 — Plan 01 execution started: scoring.config.json, read-floor.sh, plugin.json manifest updates -- 2026-05-24T22:25 -03:00 — All 28 skills + 22 agents moved into category folders via plain `mv` -- 2026-05-24T22:30 -03:00 — `claude plugin validate` rejected `agents` field → reverted agent moves, kept skills categorized -- 2026-05-24T22:35 -03:00 — `bash scripts/ci.sh` reported green during execution (claim later found inaccurate — see next entry) -- 2026-05-24T19:51 -03:00 — Resume: re-ran `bash scripts/ci.sh` from a clean session; 2 per-file failures (`make-interfaces-feel-better` 9<10, `caveman` 7<8), both upstream-vendored. Added `upstream:` exemption to ci.sh per-file floor → re-ran: all checks pass (`2 upstream exempt`). Committing now. - -## Review - -- **Goal met:** yes — 28 skills categorized 12/7/9 under engineering/productivity/internal (depth-2 verified, zero stray depth-1 skills); both manifests declare the `skills[]` array; `scoring.config.json` + `read-floor.sh` drive per-category floors (eng 10, prod/internal 8) with agents flat 14, commands flat 21; CI green with 2 upstream skills exempt. -- **Regressions:** none — `bash scripts/ci.sh` exit 0; all structural guards + per-file/per-category floors pass. -- **CI:** pass — "All ci.sh checks passed"; per-file section: "skills per-file all clear per-category floors (2 upstream exempt)". -- **Follow-ups:** none — empty `agents/engineering/` + `agents/internal/` dirs persist on disk (sandbox can't rmdir) but are untracked and invisible to validators; tracked as a known harmless artifact in Notes, not a regression. Scope notes: `guard-agents.sh`/`score-agents.sh` were edited to read floors via `read-floor.sh` (beyond the step-9 wording, which named only command scripts) and 4 sibling plan files got bookkeeping edits — both benign, no follow-up needed. -- Filed by: plan-review on 2026-05-24T20:02:33-03:00 diff --git a/docs/plans/finished/2026-05-24-html-sidecar-generator.md b/docs/plans/finished/2026-05-24-html-sidecar-generator.md deleted file mode 100644 index 3f9c5a5e..00000000 --- a/docs/plans/finished/2026-05-24-html-sidecar-generator.md +++ /dev/null @@ -1,103 +0,0 @@ ---- -title: Add plan-sidecar skill + simplified HTML standard -goal: Ship a plan-sidecar skill that authors plan HTML sidecars + the index.html dashboard from shared assets (per-plan latitude), simplify the AGENTS.md standard, and wire plan-manager to invoke it -status: finished -created: "2026-05-24T00:00:00-03:00" -updated: "2026-05-25T00:00:00-03:00" -started_at: "2026-05-24T00:00:00-03:00" -assignee: null -blockers: [] -blocked_reason: null -blocked_since: null -ship_commit: 56869c392d17c8df2df087b8fd5fe188edfecffb -tags: [plans, html, skill, dashboard] -affected_paths: - - plugins/docks/skills/productivity/plan-sidecar/SKILL.md - - plugins/docks/skills/productivity/plan-sidecar/references/templates.md - - plugins/docks/skills/productivity/plan-manager/SKILL.md - - docs/plans/AGENTS.md - - docs/plans/index.html - - docs/plans/finished/2026-05-24-scaffold.html - - docs/plans/planned/20260512-plan-review-smoke.html -related_plans: [pipelines-to-skills, tree-skill] -review_status: passed ---- - -# Add plan-sidecar skill + simplified HTML standard - -## Goal - -Make the HTML sidecar contract real — as a **skill**, not a generator script. The standard exists (`docs/plans/AGENTS.md` § "HTML sidecar") and the shared assets exist (`docs/plans/_assets/dashboard.{css,js}`, commit `6c73fe3`), but **no `.html` has ever been authored** — plan-manager claims it "regenerates" sidecars, yet nothing does. Build a cross-tool `plan-sidecar` skill that turns a plan `.md` into its `.html` sidecar and (re)builds `docs/plans/index.html`, using the shared assets and the documented `data-*` contract, with **per-plan latitude** (a plan may add visualization beyond the floor as long as every css/js hook still resolves). Simplify the AGENTS.md standard from a deterministic-generation spec into a skill-authoring contract, and replace plan-manager's hand-generation language with an invocation of the skill. Ship the skill + the dashboard + 2 exemplar sidecars (one finished, one planned) — not a full backfill; the skill authors the rest on each plan's next touch. - -## Context - -Re-spec of the original "deterministic plan HTML sidecar generator" plan. The user's call (2026-05-24): **a separate skill, not a `scripts/gen-plan-html.sh` generator** — "instead of just creating a generator that doesn't fit for us, I wanted just a standard for the html as we would have a .js and .css file for all of them, but some cases may differ according to each plan, since it's for a better visualization of a plan." So: one shared standard (css + js + `data-*` contract) that every sidecar conforms to, authored by a skill that has latitude to tailor each plan's view. This mirrors the kit's own direction — cross-tool skills over Claude-only scripts (see `pipelines-to-skills`) — and the saved preference "skill + documented standard over a deterministic generator script." - -The `.md` stays canonical and is the only thing agents read; the `.html` is a derived, browser-only artifact (collapsible sections, click-to-copy, status color). Because authoring it well needs judgment (per-plan emphasis, "better visualization"), it belongs in a skill an agent runs — not a rigid transform. - -## Steps - -| # | Task | Depends | Parallel | Status | Owner | -|---|---|---|---|---|---| -| 1 | Lock decisions: skill (not script); simplified standard; per-plan latitude; check in `.html`; 2 exemplars (not full backfill) | — | — | done | self | -| 2 | Create `plugins/docks/skills/productivity/plan-sidecar/SKILL.md` + `references/templates.md` (sidecar + dashboard modes, shared-asset contract, latitude) | 1 | — | done | self | -| 3 | Simplify `docs/plans/AGENTS.md` § HTML sidecar for skill-authoring — keep the load-bearing `data-*` contract, drop the generator-script language, point to `plan-sidecar` | 1 | with #4 | done | self | -| 4 | Wire `plan-manager` SKILL.md — constraint + Step 7.5 invoke `plan-sidecar` instead of describing hand-generation | 1 | with #3 | done | self | -| 5 | Author `docs/plans/index.html` dashboard — every plan across categories, filter/sort, shared assets | 2 | with #6 | done | self | -| 6 | Author 2 exemplar sidecars: `finished/2026-05-24-scaffold.html` + `planned/20260512-plan-review-smoke.html` | 2 | with #5 | done | self | -| 7 | `content_hash` backfill (plan-sidecar, plan-manager) + `bash scripts/ci.sh` green | 2, 4 | — | done | self | -| 8 | Ship — feat commit, plan-manager ship (→ finished, regen this plan's own sidecar), plan-review | 3–7 | — | done | self | - -### Step details - -- **#2** — One skill, two modes by argument: `plan-sidecar ` authors one sidecar; `plan-sidecar dashboard` (re)builds `index.html`. Body holds the workflow + contract essentials + BAD/GOOD + gotchas + latitude; the full HTML skeletons live in `references/templates.md` (loaded on demand). `user-invocable: true` (plan-* family) so it runs standalone AND is invoked by plan-manager. -- **#3** — AGENTS.md keeps the policy (md-canonical, assets path, the `data-*` attribute table, checked-in default) and points to the skill for the authoring template. Removes the verbose full-template block and the script-oriented "Generation contract" (byte-identical no-op / hash skip-write → one-line "skip if unchanged"). -- **#4** — plan-manager Step 7.5 becomes "activate the `plan-sidecar` skill for the touched plan, then `dashboard` mode" — keeping the .md-canonical / never-read-the-.html rules. Step 8 still re-runs it after plan-review writes `## Review`. -- **#6** — Exemplars chosen for variety: scaffold (finished — green badge, full Steps/Mistakes/Review) and plan-review-smoke (planned — gray badge, queued token, empty Review auto-collapses). Dashboard links these two to `.html`; the other rows link to `.md` until their sidecars are authored on next touch. - -## Acceptance criteria - -- [x] `plan-sidecar` skill exists (scores 15/15, well above the productivity floor 8) and documents sidecar + dashboard modes + the shared-asset `data-*` contract + per-plan latitude -- [x] `docs/plans/AGENTS.md` § HTML sidecar is simplified for skill-authoring (keeps the `data-*` contract; points to `plan-sidecar`; no generator-script language) -- [x] `plan-manager` SKILL.md invokes `plan-sidecar` instead of describing hand-generation (constraint + Step 7.5) -- [x] `docs/plans/index.html` lists every plan with working filter/sort, using `_assets/dashboard.{css,js}` -- [x] 2 exemplar sidecars render correctly (status badge, sections, steps `data-status`, embedded `plan-data` JSON, `_assets` refs, zero inline styles) -- [x] `bash scripts/ci.sh` green; `content_hash` re-synced for changed skills - -## Out of scope - -- A `scripts/gen-plan-html.sh` generator or any deterministic transform — superseded by the skill (the whole point of this re-spec) -- Full backfill of all plans' sidecars — only 2 exemplars now; the skill authors the rest on each plan's next plan-manager touch -- Restyling `dashboard.css` / `dashboard.js` — consumed as-is -- A CI freshness guard (`guard-plan-html.sh`) — sidecars are skill-authored, not lockstep-generated, so a byte-freshness guard doesn't apply; revisit if drift becomes a problem -- Rendering non-plan markdown - -## Mistakes & Dead Ends - -- **2026-05-24** (re-spec: script → skill): the plan originally specced `scripts/gen-plan-html.sh`, a deterministic bash+python generator, plus a CI freshness guard. → The user rejected a generator that "doesn't fit for us" and asked for a standard + a skill with per-plan latitude ("some cases may differ according to each plan… for a better visualization"). A rigid transform can't exercise that judgment, and a freshness guard only makes sense for lockstep-generated output. → Rewrote as the cross-tool `plan-sidecar` skill consuming the existing shared assets; AGENTS.md simplified from a generation spec to an authoring contract; plan-manager invokes the skill. Slug kept (`html-sidecar-generator`) as the stable ID; title updated. - -## Sources - -- `docs/plans/AGENTS.md` § "HTML sidecar (browser view)" (repo) — the standard being simplified: sidecar structure, dashboard structure, the `data-*` attribute table the css/js depend on -- `docs/plans/_assets/dashboard.css` + `dashboard.js` (repo, commit `6c73fe3`) — shared assets the skill references (status colors, collapsible sections, click-to-copy, dashboard filter/sort) -- `plugins/docks/skills/productivity/plan-manager/SKILL.md` (repo) — the HTML-sidecar constraint + Step 7.5 / Step 8 this plan rewires to invoke the skill -- `plugins/docks/skills/productivity/scaffold/SKILL.md` (repo) — sibling generative-skill pattern (modes by argument, references/ for verbose templates) - -## Blockers - -(none — actionable immediately; shared assets already landed in `6c73fe3`) - -## Notes - -- **Origin**: deferred out of the pipelines-to-skills ship review (2026-05-24). Earlier ships (foundation, skill-maintainer, scaffold, tree) all skipped sidecar generation, confirming the gap was the missing author — now filled by the skill, not a script. -- **Checked-in `.html`**: per the user ("Check in all .html") and the AGENTS.md default. No `.gitignore` stanza. -- **Dogfood at ship**: when this plan moves ongoing → finished, plan-manager runs `plan-sidecar` on it, so the finished plan gets its own sidecar — the skill validated end-to-end on its own plan. - -## Review - -- **Goal met:** yes — `plan-sidecar` skill ships (scores 15/16, above the productivity floor of 8) documenting sidecar + dashboard modes, the shared-asset `data-*` contract, and per-plan latitude; `docs/plans/AGENTS.md` simplified to a skill-authoring contract (6 `data-*` refs retained, zero generator-script language, points to the skill); `plan-manager` constraint + Step 7.5 rewired to invoke the skill; `index.html` lists all 8 plans with live filter/sort; 2 exemplar sidecars conform. All 6 `[x]` acceptance criteria verified against the `56869c3` diff and current tree. -- **Regressions:** none — no inline `