autoplan SKILL.md (1839 lines) is too large — split into router + references/ to save tokens
- Dominant language
- TypeScript
- Stars
- 133k
- Forks
- 19.9k
- Avg merge
- 18h 46m
- Merged PRs (30d)
- 26
Description
## Problem
The `autoplan` SKILL.md is **1839 lines** (~24,500 tokens at load time). This is **3.7x the recommended max of 500 lines** and triggers the `skill-cert` progressive disclosure check as a hard failure:
```
⚠️ Load tier too large: 24520t (limit: 5000t). Consider moving detailed instructions to references/.
⚠️ No references/ directory found. Skills over 2500t should use references/ for on-demand loading.
```
## Why this matters
Every time the model loads this skill, it pays ~24K tokens before executing a single instruction — that's 3-5x more than typical skills. Most of those tokens are consumed by the gstack shared preamble (lines 1-135), AskUserQuestion format reference (lines 325-447), and detailed phase-by-phase instruction blocks that the model only needs to reference on-demand during specific phases.
## Proposed pattern: Router + references/
The same pattern gstack already recommends for code organization (split large modules) should apply to skills. The router stays lean (~200-300 lines) — triggers, core decision principles, phase orchestration overview. Detailed instructions move to:
```
gstack-autoplan/
├── SKILL.md # ~300 lines: router only
├── references/
│ ├── preamble.md # Shared gstack preamble (already reused across all skills!)
│ ├── askuserquestion-format.md # AskUserQuestion spec (already reused across all skills!)
│ ├── ceo-review.md # Phase 1: full CEO review instructions
│ ├── design-review.md # Phase 2: design review instructions
│ ├── eng-review.md # Phase 3: eng review instructions
│ ├── dx-review.md # Phase 3.5: DX review instructions
│ ├── final-gate.md # Phase 4: approval gate
│ └── decision-audit-trail.md # Audit trail format
```
The router reads references/ on demand as each phase starts. Skill-level context is preserved exactly — nothing is removed, just lazy-loaded.
## Token savings estimate
- **Current**: ~24,500 tokens at load
- **After refactor**: ~6,000 tokens at load (router only), ~18,500 tokens loaded on-demand
- **Net savings**: ~18,500 tokens per load when not using autoplan, equivalent savings for other preamble-sharing skills
## Note on shared preamble
The preamble (lines 1-135) is currently duplicated across ALL gstack skills. This is another source of waste. If the preamble were extracted to a shared `references/preamble.md` loaded once per session, every skill invocation saves those ~2,000 tokens. This is a larger refactor but worth considering.
Contributor guide
Research direction
Start with gstack-autoplan/SKILL.md and run the skill-cert progressive disclosure check to confirm the current size and failure. Review the listed preamble, AskUserQuestion, phase, and audit-trail sections, then separate them into references/ while keeping the router and skill-level context intact. Done means the router is about 200–300 lines, detailed sections load on demand, and the size check passes.
Written by the indexing model from the issue text.
Assessment
- Domain
- developer-experience, tooling
- Issue type
- Refactor
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 68/100