Skip to main content
Specifications for everyone authoring against Ralphy. If you ship a new template, write a skill, draft a playbook, add a model entry, or read project memory from another tool, this section is your contract. Each page documents one format: the field-by-field schema, the lint that enforces it, and a full working example you can copy. The rest of the docs cover how to use Ralphy. This section covers how to extend it.

​
Pages

Models registry

The MODELS.md format. Per-section conventions, the per-model matrix tables, lifecycle, and how to add a new entry.

Skill format

SKILL.md frontmatter contract, body sections, the 1536-char description cap, and the ralphy vs ralphy-dev namespace split.

Template format

template.yaml Zod schema, the five segment-persona categories, vibe-reference vs vibe-style, slug rules, and version gating.

Playbook format

docs/playbooks/<role>.md structure, sub-doc convention, routing into AGENTS.md, and the agents-md lint.

Memory schemas

The three JSONL logs under workspace/projects/<id>/logs/. Append-only contract, field-by-field schema, and read patterns.

Asset manifest

asset-manifest.json slot pointer table, slot-id convention, and how the auto-versioning archive interacts with manifest pointers.

​
How the specs interact

The Ralphy stack has one routing surface (AGENTS.md) and four format contracts that hang off it. Read them as a chain:
  1. A request comes in. AGENTS.md routes it to a playbook (docs/playbooks/<role>.md). See Playbook format.
  2. The playbook may invoke a skill. Skills live under .agents/skills/<name>/SKILL.md and are slash-invocable. See Skill format.
  3. The skill or playbook picks a template. Templates live in the hosted content library (and your workspace/templates/) and declare a template.yaml. See Template format.
  4. The template names model IDs. All available models are in MODELS.md. See Models registry.
  5. Every generation writes to project memory. Append-only logs land in workspace/projects/<id>/logs/; per-slot pointers land in asset-manifest.json. See Memory schemas and Asset manifest.
If you change any one format, the others depend on it. The CI lints in scripts/lint-*.ts are the contract between layers — they’re the first thing to read when adding a field.

​
Working on the specs themselves

The source of truth for each spec lives in the repo:
SpecSource files
Models registryMODELS.md
Skill formatdocs/skills-format.md, scripts/lint-skills.ts
Template formatcli/lib/schemas/template.ts, scripts/lint-templates.ts
Playbook formatdocs/playbooks/README.md, scripts/lint-agents-md.ts
Memory schemascli/lib/gen-log.ts
Asset manifestcli/commands/generate.ts (see Manifest type + readManifest / writeManifest)
When a doc page and the source disagree, the source wins. Open an issue or PR.