Skip to content

refactor: dissolve composer extracts and consolidate plugin doctrine - #278

Draft
FrkAk wants to merge 1 commit into
refactor/plugin-skills-claude5-t1from
refactor/plugin-skills-claude5-t2
Draft

refactor: dissolve composer extracts and consolidate plugin doctrine#278
FrkAk wants to merge 1 commit into
refactor/plugin-skills-claude5-t1from
refactor/plugin-skills-claude5-t2

Conversation

@FrkAk

@FrkAk FrkAk commented Aug 2, 2026

Copy link
Copy Markdown
Owner

Summary

Task Reference: [PYZ-379]

Second tranche of the Claude 5 plugin modernization, stacked on #277. Establishes a single source of truth for every kind of doctrine in the claude-code plugin:

  • Dissolve skills/composer/references/ (4 phase-rule extracts + sources.json hash-pin machinery). Phase-unique rules moved into the owning agent body; content mirroring the canonical skills/piyaz/references/ files replaced with pointers. The stale mirror blockquotes in the canonical files are removed.
  • Fold composer-planner into composer-researcher: the researcher owns the plan rubric and the draft -> planned transition under its merged mandate, and serves direct "plan " dispatch. agents/composer-planner.md deleted.
  • agents/manage.md drops workflows C-F (plan, record completion, resume, propagate); they are owned by the piyaz skill's workflow index and lifecycle.md.
  • Convert all 7 DOT digraphs to numbered lists.
  • Collapse per-agent status-transition blocks to 1-2 lines; lifecycle.md is the sole state machine. The never-self-promote-to-done rule stays explicit in each dispatched agent body.
  • Refine the piyaz skill description (completion and shipping triggers, completion-protocol read-first) and the Hard rules done clause: done is reachable only from in_review, user-reported completion records and sets in_review, unverified or failing criteria hold the task.
  • scripts/check-plugins.ts: remove the extract hash-pin machinery and the extract sync entry.

Net for the claude-code plugin: -10,301 words (-16.6%), 0 @-includes, 0 digraphs, 5 files deleted.

Behavioral A/B against the tranche 1 plugin (15 scenarios, 51 runs per arm, paired scoring): mean delta +0.079, 95% CI [0.004, 0.177]; completion-protocol and grounded-record scenarios improved, zero illegal status transitions across the arm.

Type of change

  • Bug fix
  • New feature
  • Refactor / cleanup
  • Documentation

Testing

  • Tested locally with bun run dev
  • Linting passes (bun run lint)
  • Typecheck passes (bun run typecheck)
  • Workers smoke passes (bun run build:cf && bun run smoke:cf) — required when this PR touches app/api/**, middleware.ts, worker-cf.ts, or a .node.ts / .workers.ts pair

Notes for reviewer

Brand plugin directories (plugins/codex, plugins/cursor, plugins/antigravity) are intentionally not synced; check:plugins reports drift until the pre-merge bun run sync:plugins on the final PR of this stack.

Docs impact

  • Skills/agents catalog regenerates via the Docs Sync workflow; no hand-edited pages affected.

Compliance impact

  • none

@FrkAk FrkAk changed the title refactor/plugin skills claude5 t2 refactor: dissolve composer extracts and consolidate plugin doctrine Aug 2, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant