Skip to content

[v1.0.0] Extract reference data to reduce SKILL.md token usage - #31

Draft
Adi-ty wants to merge 13 commits into
v1.0.0/task/remote-scaffold-inventoryfrom
v1.0.0/task/skill-token-refactor
Draft

[v1.0.0] Extract reference data to reduce SKILL.md token usage#31
Adi-ty wants to merge 13 commits into
v1.0.0/task/remote-scaffold-inventoryfrom
v1.0.0/task/skill-token-refactor

Conversation

@Adi-ty

@Adi-ty Adi-ty commented Jun 11, 2026

Copy link
Copy Markdown
Collaborator

What this PR does

  • Extract bulky reference data (tables, shell commands, templates) from SKILL.md files into references/*.md files, loaded on demand
  • scaffold/SKILL.md: 230 → ~110 lines (canonical layout, engine errors, TDD loop, test checklist, adaptive wiring moved to references)
  • setup/SKILL.md: 382 → ~105 lines (detection commands, Phase A/B tables, PSR-4 wiring, report template, PHPCS/test ref tables moved to references)

Closes

Closes #

Changes

scaffold/SKILL.md

  • §0 (Plan): 8-item mandatory checklist → 2-sentence directive
  • §3: 11-row canonical layout table → Read references/canonical-layout.md
  • §4: 15-line integration test matrix → Read references/test-checklist.md
  • §5: 3-step multi-kind run order → single line
  • §6a (Adaptive Wiring): 4-step subsection → Read references/adaptive-wiring.md
  • §7: 7-step TDD table + per-kind framework matrix → Read references/tdd-loop.md
  • Engine errors: 7-row error table + CI/CD variant + reference links → Read references/engine-errors.md
  • Hard rules: tightened prose, preserved all prohibitions

setup/SKILL.md

  • §1 (Detect): 7 shell command blocks → Read references/detection-commands.md
  • §2 (Plan): Phase A (11-row table) + Phase B (6-row table) → Read references/phase-a-setup.md and phase-b-features.md
  • §4 (Execute): 5 inline command blocks → Read references/phase-a-setup.md
  • PSR-4 wiring: dedicated subsection → Read references/psr4-wiring.md
  • Report: full multi-block template → Read references/report-template.md
  • Error handling: 4 verbose paragraphs → compact error-code table

Adi-ty added 12 commits May 27, 2026 19:58
@Adi-ty
chore: add monorepo package layout
15cc791 
Move the existing wp-tooling package into an npm workspace and add placeholder package slots for future lint, Tailwind, skills, PHPCS, and PHPStan packages.
@Adi-ty
fix(monorepo): complete wp-tooling package layout
a512ca9 
Move scaffolds, docs, orphaned tests into node-packages/wp-tooling/. Fix evals SKILLS_DIR path. Fix .gitignore build/ pattern to exclude scaffold dirs.
@Adi-ty
feat: split ESLint, Stylelint, Tailwind configs into standalone packages
255958e 
Extract @rtcamp/eslint-config, @rtcamp/stylelint-config, and @rtcamp/tailwind-config from @rtcamp/wp-tooling into separate npm workspace packages. Clean break — remove config exports and peerDependencies from wp-tooling. Update wp-tooling's eslint.config.js to consume @rtcamp/eslint-config. Repoint lint scaffolds to reference the new packages (eslint.config.js dest, stylelint extends path, npm_dev_dependencies)
@Adi-ty
fix: update ESLint configuration references and package versions in d…
0a58e02 
…ocumentation
@Adi-ty
feat: move skills into wp-tooling package, drop empty tooling-skills
9a860ca
@Adi-ty
chore: sync scaffold SKILL.md into claude-skills template
5d27241
@Adi-ty
fix: update .gitignore to include nested workspace patterns for monorepo
71d8306
@Adi-ty
feat(scaffolds): serve scaffolds from another repo via a central inve…
c0d5848 
…ntory

Add a central inventory so a scaffold's whole scaffold.json plus templates can live in an owning repo (e.g. rtCamp/wp-shared-workflows), with wp-tooling holding only a one-line pointer per remote scaffold.
  - inventory.js: parse/validate inventory.json; entry -> thin remote record
  - fetch.js: zero-dep fetchRemoteFile() over raw.githubusercontent.com, with
    on-disk caching for immutable refs (tags / full SHAs)
  - cache.js + cli/commands/cache.js: `wp-tooling cache clear`
  - errors.js: extract ScaffoldError; add EFETCHFAIL (network/HTTP) distinct
    from EBADSCAFFOLD (bad/invalid manifest)
  - registry.js: scan() overlays inventory as origin:'remote' records; execute()
    lazily hydrates + validates the remote manifest, then prefetches templates
    (offline-safe re-runs; dry-run fetches the manifest only)
  - list.js: remote rows (kind:'template', origin:'remote', counts:null), offline
  - validate.js: recognise remote ids offline; opt-in --remote fetches +
    schema-validates each manifest at its pinned ref
  - docs + scaffold skill updated for the remote path
@Adi-ty
feat(scaffolds): serve scaffolds from another repo via per-repo sourc…
d1720cc 
…es + an index

- fetch.js: fetchRemoteFile() over raw.githubusercontent with ETag-validated caching (If-None-Match -> 304 serves cache; offline falls back to cache, HTTP errors surface); readCached() for offline id recognition
- registry.js: scan() discovers via sources -> index (offline-tolerant); execute() hydrates + validates the remote manifest, then fetches templates
- validate.js: sources-shape offline (+ remote ids from a cached index); --remote fetches each index + manifest and schema-validates
- list.js: remote rows (origin 'remote', counts null) + a warnings array
- cache.js / cli: `wp-tooling cache clear`; new error code EFETCHFAIL
- docs + scaffold skill updated; dormant by default (no sources.json ships)
@Adi-ty
feat(scaffolds): engine-side input discovery + feature toggle layer
9d3aba0 
Two additive engine capabilities plus supporting scaffolds, tests and docs.
All backward-compatible: execute() result shape is unchanged (only the new
engine.inputs / scaffold.kind fields), and the feature block never surfaces
in the add/execute path.

discover_from input resolution:
- Engine resolves scaffold inputs from composer.json / package.json /
  .wp-tooling.json with precedence supplied -> discovered -> default, and is
  fail-safe (missing or malformed files fall through to the default).
- New `transform: json-escape` for derived inputs (psr4 autoload key).
- Annotate bundled scaffolds (psr4, wp/*) with discover_from.

Feature toggle layer:
- Optional `feature` block (config_key, owned_files, confirm_remove,
  gitignore) with TTY-free enable/disable/status verbs, persisted in
  .wp-tooling.json. New `wp-tooling features` CLI command.
- setup/tailwind ships as a toggleable feature.

UI:
- New `style` helper (TTY-aware ANSI, no-ops in non-TTY output).
- terminal.js: stdin close now rejects in-flight readers with CancelledError
  instead of resolving '' (fixes infinite re-prompt under required validators).

Other:
- phpstan scaffold points at the dedicated rtcamp/wp-phpstan baseline and
  drops the hardcoded level.
- Extract shared add/features CLI helpers into cli-support.js.
@Adi-ty
docs: add CHANGELOG entries and #29 tracking issue
d01d2e9 
- CHANGELOG: discover_from input discovery + feature toggle layer under ## Unreleased
- .claude/issues/29-remote-scaffold-sources.md: decision log + verification for PR #30
@Adi-ty
refactor(skills): split scaffold and setup skills into progressive-di…
8b196f8 
…sclosure layout

Move heavy reference tables (canonical layout, per-kind test checklist, TDD
loop, engine errors, adaptive wiring, Phase A/B tables, detection commands,
PSR-4 wiring, report template) into references/ subdirectories so each is
loaded on demand rather than always in context. Main SKILL.md shrinks from
230→136 lines (scaffold) and 382→140 lines (setup) while the full instruction
set is preserved verbatim across SKILL.md + references.
@Adi-ty Adi-ty self-assigned this Jun 11, 2026
@Adi-ty
Refactor documentation and workflow for setup and scaffolding processes
35dc903 
- Updated adaptive wiring documentation for clarity and conciseness.
- Enhanced canonical layout reference with usage context.
- Revised engine error codes documentation for better understanding of error handling.
- Improved TDD loop instructions to emphasize step-by-step execution.
- Clarified integration test checklist with specific assertions for each kind.
- Expanded setup skill documentation to include detailed parsing and detection instructions.
- Streamlined phase A and phase B setup references for better usability.
- Updated PSR-4 wiring guide to ensure accurate application of autoloading.
- Enhanced final report template for clearer output and formatting rules.
@AnuragVasanwala
AnuragVasanwala self-requested a review June 15, 2026 04:32
@Adi-ty
Adi-ty force-pushed the v1.0.0/task/remote-scaffold-inventory branch from d01d2e9 to 5273ae7 Compare June 15, 2026 10:18
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@AnuragVasanwala AnuragVasanwala Awaiting requested review from AnuragVasanwala

Assignees

@Adi-ty Adi-ty

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@Adi-ty