Keystone: A Structured Architecture Execution Layer for Claude Code

The core problem with using LLMs for architecture work isn't capability. The models are extraordinary. The problem is that expert reasoning requires consistency — and prompts don't enforce consistency. A persona declared in a system prompt drifts. Output structure varies per session. Assumptions go unnamed. Risk gets buried in prose or skipped entirely.

Keystone is our answer to that problem.

The Design Principle

Architecture work produces artifacts, not conversations. A requirements document. An estimation table. A system diagram. An ADR. These are the deliverables that get reviewed in PRs, presented to boards, and read by engineers who join the team six months later.

Keystone treats each of these artifacts as a first-class output contract. Every skill enforces a strict template — not as a style preference, but because structured output is the only output that is composable, auditable, and trustworthy across a team and over time.

The persona layer is secondary to the output contract. The skill doesn't just behave like a principal architect — it produces what a principal architect produces. That distinction matters in production.

The Four Open-Source Skills

/keystone-req — Requirements Clarification

Persona: Principal Product Architect. Output: MoSCoW-ranked functional requirements, non-functional requirements with specific measurable targets (latency SLAs in milliseconds, availability in nines with justification, consistency model declared explicitly), out-of-scope boundaries, and every assumption tagged [ASSUMPTION]. The skill refuses to produce a narrative product overview. It forces decisions.

/keystone-est — Back-of-Envelope Estimation

Persona: Staff Engineer (Scale Specialist). Output: traffic estimation table with arithmetic shown step-by-step, storage projection by entity at 1-year and 3-year horizons, bandwidth breakdown, infra sizing with instance types and monthly cost, and a scale triggers table — the exact metric at which each component reaches its design limit and the specific action required. "Scales well" is prohibited output.

/keystone-hld — High-Level Design

Persona: Principal Architect. Output: explicit monolith vs microservices decision with technical justification, component table with a mandatory "why not the alternative" column for every choice, a Mermaid system topology diagram, critical data flows for every MUST-have requirement with sync/async split declared, failure modes tagged [RISK: HIGH/MED/LOW] inline, and a deployment model table. Every architectural opinion is traceable to a reason.

/keystone-adr — Architecture Decision Record

Persona: Decision Documentarian. Output: structured YAML — context, decision, rationale (three specific measurable reasons minimum), consequences (positive, negative with [RISK] tags and mitigations, neutral), and alternatives considered with rejected_because stated as a specific technical argument. Exports to /decisions/ADR-NNN-[slug].md. The decision lives in the repository, not the conversation.

Caveman Protocol

Keystone ships with architecture-grade token compression active by default. Prose output drops approximately 65% with no loss on structured tasks. Tables, schemas, Mermaid diagrams, and code blocks are always preserved verbatim. The toggle is per-command, per-session, or global — with a three-level override system. Filler output ("Certainly!", "Great question!", "Let me know if you need anything!") is prohibited in both compressed and verbose modes. The distinction between modes is depth of reasoning, not politeness theater.

Validation

We ran all four skills against a single problem statement: a real-time payments platform at 5M DAU, 10K TPS peak, strong consistency on balances, eventual on notifications, 7-year regulatory retention.

Outputs:

• 13 functional requirements, MoSCoW-ranked, with 7 open assumptions explicitly named

• Traffic: 350 peak write QPS at launch → 764 by Year 3 (30% YoY growth compounded), arithmetic shown

• Storage: 154TB replicated at Year 3, with [RISK: HIGH] flagging the 100TB threshold at Year 2 and a specific tiering action

• Infra: $4,520/mo itemized across 13 components; Reserved Instance reduction to $3,200/mo noted

• Scale triggers: 7 explicit thresholds with named components, breach metrics, and required actions

• HLD: microservices decision justified on domain orthogonality grounds; 14-component table with rejection reasoning for each alternative; full system Mermaid diagram; 4 critical data flows with failure modes

• ADR: event sourcing selected over CRUD and blockchain; blockchain rejected as "100–1,000× latency overhead violates 500ms p99 SLA; no regulatory mandate in target jurisdiction"; CRUD rejected for audit trail reliability under hotfix conditions

All outputs exported as .md files. Every assumption named. Every risk tagged. Every decision traceable.

Architecture

skills/          — Skill definitions (persona, template, output schema)
adapters/        — Claude Code, Kilo Code, Gemini CLI connectors
tools/           — keystone-compress (CLAUDE.md token reduction)
CLAUDE.md        — Skill index, loaded every session
ETHOS.md         — Design philosophy and output invariants

Four skills are MIT-licensed. The full 12-skill CTO suite — LLD generation, scalability stress-testing, adversarial bottleneck review, cost modeling, PRD-to-architecture conversion, and full pipeline chain — is private, used internally across SingularRarity Labs projects.

Installation

git clone --depth 1 https://github.com/singularrarity/keystone.git \
  ~/.claude/skills/keystone \
  && cd ~/.claude/skills/keystone && ./setup

The AI is the instrument. The architect is still you.

github.com/SingularRarity/Keystone