PYRS - Pyramidal Yield-Ready Specifications
Pronounced "pyres," short for pyramids.
An AI skill plugin for Claude Code and OpenCode that introduces a structured, hierarchical approach to building software with LLM agents.
You: "Add caching to this service"
Agent: rewrites half your architecture
(new session)
You: "Fix this bug"
Agent: ignores caching layer entirely
(that ^ doesn't have to be your life anymore!)
...because this is exactly what PYRS prevents.
What is PYRS?
Persistent context for AI coding agents. As you work with an agent, PYRS produces simple markdown files ("pyramids") that capture what your system does and why. These pyramids accumulate as a natural byproduct of the conversations you're already having. They're not documentation you maintain; they're artifacts that keep every future agent session aligned with your architecture.
Without PYRS — no matter how thorough your planning phase is, context doesn't survive the session.
You get:
- intent lost across sessions
- architecture slowly mutates
- changes are implicit and fragile
graph TD
A1["Agent · Session 1"] --> C["Code"]
A2["Agent · Session 2"] --> C
A3["Agent · Session N"] --> C
C --> X["scope creep · drift · decay"]
style X fill:#e74c3c,stroke:#c0392b,color:#fff
With PYRS — pyramids persist across sessions, drive tests, tests drive code.
You get:
- intent is stored as contracts
- drift is detectable and correctable
- code YOU write can be ingested into the contracts so future agents respect your work
graph TD
B1["Agent · Session 1"] --> P["Pyramids<br/><i>source of truth · persistent contracts</i>"]
B2["Agent · Session 2"] --> P
B3["Agent · Session N"] --> P
P --> T["Tests · derived from contracts"]
T --> C["Code · passes tests"]
C -.-> P
style P fill:#4a90d9,stroke:#2c5f8a,color:#fff
style T fill:#f5a623,stroke:#c4841c,color:#fff
style C fill:#7ed321,stroke:#5a9e18,color:#fff
Table of Contents
Installation
Claude Code
From within Claude Code:
/plugin marketplace add zachbutton/pyrs
/plugin install pyrs@zachbutton-pyrs
OpenCode
Clone the repo and run the install script. It adds the skills path to your OpenCode config at ~/.config/opencode/config.json, merging with any existing settings:
git clone https://github.com/zachbutton/pyrs.git ~/.local/share/pyrs
~/.local/share/pyrs/scripts/install-opencode
Or manually add the skills path to your OpenCode config (opencode.json in your project root or ~/.config/opencode/config.json):
{
"skills": {
"paths": ["~/.local/share/pyrs/skills"]
}
}
Skills are loaded on demand, not all at once. OpenCode scans the path for SKILL.md files and only reads a skill's full instructions when a task matches its description.
The Problem
LLM coding agents are powerful, but they have a fundamental limitation: they lack durable, structured understanding of the system they're building. Each conversation starts fresh. Context windows are finite. And the bigger a project gets, the harder it is for an agent to hold the full picture in its head.
This leads to predictable failure modes:
- Scope creep — an agent implementing one feature quietly introduces behavior that belongs somewhere else, or that was never asked for
- Conceptual drift — as features are added over time, the system's architecture silently diverges from what was intended, and nobody notices until it's a mess
- Fragile alignment — the only source of truth is the code itself, but code doesn't explain why it exists, what contracts it upholds, or how its pieces relate to each other
