zachbutton

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

• What is PYRS?
• Installation
  • Claude Code
  • OpenCode
• The Problem
• The Philosophy
• How It Works
  • The Pyramid Directory
  • Pyramid File Structure
  • Pyramid Identifiers
  • Commands
  • Placeholders
  • The Audit Loop
• Example Walkthrough
• Bootstrapping an Existing Project
• Adoption Strategies
  • Full Coverage (new projects)
  • Sparse Coverage (existing projects)
  • Meta Pyramid Repos (codebases you don't control)
• Source Control

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