Clairvoyance is a set of agent skills and commands inspired by John Ousterhout's A Philosophy of Software Design. Each skill focuses on one design dimension (module depth, information hiding, error handling, etc.) and suggests concrete tests and decision criteria to apply during code review and implementation.
The goal is to get your agent to write software the way Ousterhout argues it should be written: strategically, with deep modules, clean abstractions, and relentless simplicity. Instead of applying these principles yourself after the fact, Clairvoyance nudges agents to bake them into the code as it's being written.
Each skill teaches your agent to ask specific questions.
- Does this interface hide real complexity, or just pass things through?
- Can this method be understood without reading another one in a different file?
- Is error handling pushing work onto callers that the module could handle itself?
Skills activate automatically when relevant, or you can invoke them directly as slash commands: /red-flags for a design smell scan, /deep-modules to check interface depth, /design-it-twice to compare alternatives before committing.
Installation differs by platform. Claude Code has a built-in plugin marketplace. Codex and OpenCode require manual setup.
/plugin marketplace add codybrom/clairvoyance
/plugin install clairvoyance@clairvoyance-pluginsnpx skills add codybrom/clairvoyanceTell Codex:
Fetch and follow instructions from https://raw.githubusercontent.com/codybrom/clairvoyance/refs/heads/main/.codex/INSTALL.mdSee .codex/INSTALL.md for detailed steps.
Tell OpenCode:
Fetch and follow instructions from https://raw.githubusercontent.com/codybrom/clairvoyance/refs/heads/main/.opencode/INSTALL.mdSee .opencode/INSTALL.md for detailed steps.
| Skill | Covers |
|---|---|
deep-modules |
Module depth, shallow modules, classitis, pass-through methods, interface vs implementation |
module-boundaries |
Merge vs split, conjoined methods, method splitting, dependency minimization |
information-hiding |
Information leakage, temporal decomposition, partial hiding, false encapsulation |
pull-complexity-down |
Caller burden, configuration parameters, the core asymmetry |
| Skill | Covers |
|---|---|
abstraction-quality |
Genuine vs false abstractions, layer boundaries, decorators |
general-vs-special |
Interface generality, special-general mixture, edge-case elimination |
error-design |
Define errors out of existence, exception masking, aggregation, just crash |
| Skill | Covers |
|---|---|
naming-obviousness |
Isolation test, scope-length principle, consistency, avoid extra words |
comments-docs |
Comment types, comments-first workflow, cross-module documentation |
| Skill | Covers |
|---|---|
strategic-mindset |
Strategic vs tactical, investment rule, tactical tornado |
design-it-twice |
Generate alternatives, compare on criteria, synthesize |
code-evolution |
"Designed this way" standard, repetition, technical debt |
complexity-recognition |
Change amplification, cognitive load, unknown unknowns |
| Skill | Covers |
|---|---|
red-flags |
Design smell scan covering structure, boundaries, documentation, naming, and process |
These skills are adapted in part from the teachings of John Ousterhout, professor of computer science at Stanford University, and his book A Philosophy of Software Design. This project is not affiliated with, endorsed by, or sponsored by John Ousterhout, Stanford University, or the publishers of A Philosophy of Software Design.
If you find these skills useful, you should really buy and read the book. The skills in this repo are by no means a substitute for reading it. It is the definitive treatment of these ideas and an enjoyable read for any dev. Available from Amazon (no affiliate link). Also available in German (O'Reilly, 2021) and Chinese (Posts and Telecommunications Press, 2024).
The skills and code in this project are independently authored original works by the project's contributors. Brief quotations from the book are sometimes used with full attribution for purposes of commentary, criticism, and education. All trademarks and copyrights are the property of their respective owners.
Skills live directly in this repository. To contribute:
- Fork the repository
- Create a branch for your skill
- Follow the
writing-skillsskill from Superpowers for creating and testing new skills - Each skill lives in
skills/<skill-name>/SKILL.mdwith optionalreferences/files - Submit a PR
Skills update automatically when you update the plugin:
/plugin update clairvoyanceMIT License © 2026 Cody Bromley