A lightweight Codex skill that decides whether a coding task needs architecture guidance or should proceed with normal model judgment.
The router makes one of three decisions:
use— loadcodebase-designfor a real interface, module-depth, seam-placement, or testability decision.skip— keep the model unconstrained for localized implementation, mechanical work, or evidence gathering.defer— diagnose first when the root cause is still unknown, then route again only if the evidence reveals a design choice.
The repository includes both the router and its companion codebase-design skill, so a fresh installation is complete. The companion is adapted from Matt Pocock's codebase-design skill; see Origins and attribution.
Architecture guidance is valuable when the shape of the code is the problem. Applying it to every coding task adds ceremony and can encourage premature abstraction. This router keeps that guidance available without making it the default for routine work.
Clone the repository and copy both skills into your Codex skills directory:
git clone https://github.com/easyvibecoding/codebase-design-router.git
mkdir -p ~/.codex/skills
cp -R codebase-design-router/skills/route-codebase-design ~/.codex/skills/
cp -R codebase-design-router/skills/codebase-design ~/.codex/skills/Restart Codex so it discovers the new skills.
To update an existing installation:
git -C codebase-design-router pull --ff-only
rm -rf ~/.codex/skills/route-codebase-design ~/.codex/skills/codebase-design
cp -R codebase-design-router/skills/route-codebase-design ~/.codex/skills/
cp -R codebase-design-router/skills/codebase-design ~/.codex/skills/Review the rm -rf targets before running the update command if you have locally modified either installed skill.
Invoke the router explicitly:
Use $route-codebase-design to decide whether this task needs the codebase-design skill.
The skill also supports implicit discovery. Explicit user direction always wins: asking for codebase-design routes directly to it, while asking for unconstrained model judgment skips it.
Typical outcomes:
| Task | Route | Reason |
|---|---|---|
| Decide what a public interface must guarantee | use |
Callers and contract shape are changing |
| Move duplicated caller logic behind one module | use |
Behavior placement and module depth are design choices |
| Fix a bug inside a known interface | skip |
The interface shape is already established |
| Update copy, styles, configuration, or deployment | skip |
No code-design decision is introduced |
| Investigate an unexplained regression | defer |
Evidence is needed before deciding whether restructuring matters |
skills/
├── route-codebase-design/ # Thin use / skip / defer router
└── codebase-design/ # Deep-module vocabulary and design guidance
tests/
└── validate_skills.py # Dependency-free package validation
python3 tests/validate_skills.pyCI runs the same validation on every push and pull request.
See CONTRIBUTING.md. Please keep the router small and discriminating: it should decide whether design guidance applies, not perform the design itself.
route-codebase-design and the repository packaging are original EasyVibeCoding work.
The bundled skills/codebase-design directory is derived from Matt Pocock's mattpocock/skills project, specifically skills/engineering/codebase-design at source revision e38b908fb73e4982eee85b2c6f6928e3b46fa0a6.
This repository adds Codex metadata, Markdown code-fence annotations, terminology adjustments, and a delegation fallback for harnesses without parallel sub-agents. Matt Pocock and the upstream project do not endorse these modifications.
See THIRD_PARTY_NOTICES.md for the complete provenance record. The upstream MIT license and notice also travel inside the installed companion at skills/codebase-design/LICENSE and skills/codebase-design/NOTICE.md.
- Original Router and repository work: MIT, copyright EasyVibeCoding.
- Bundled
codebase-designderivative: MIT, copyright Matt Pocock; modifications are documented in NOTICE.md.
Traditional Chinese documentation: README.zh-TW.md