spriteforge 0.1.1__py3-none-any.whl

spriteforge/__init__.py

@@ -0,0 +1 @@
+"""Local-first pixel game harness."""

spriteforge/__main__.py

@@ -0,0 +1,3 @@
+from spriteforge.cli import app
+
+app()

spriteforge/agents/assets.py

@@ -0,0 +1,109 @@
+"""Immutable image versions and a stable-id registry; only explicit targets may be revised."""
+
+import hashlib
+import io
+from uuid import uuid4
+
+from PIL import Image
+from pydantic import BaseModel, ConfigDict, Field
+
+from spriteforge.core.state import Artifact, Store
+from spriteforge.providers.base import ImageProvider, ImageRequest
+
+from .cancellation import check_active
+
+
+class GenerateAsset(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    asset_id: str = Field(pattern=r"^[a-z0-9_-]+$")
+    instruction: str
+
+
+class AssetResult(BaseModel):
+    asset_id: str
+    artifact_id: str
+    version: int
+
+
+class Assets:
+    def __init__(self, store: Store, run_id: str, provider: ImageProvider):
+        self.store, self.run_id, self.provider = store, run_id, provider
+        with store.connect() as db:
+            db.execute("""CREATE TABLE IF NOT EXISTS asset_registry (
+                run_id TEXT REFERENCES runs(id), asset_id TEXT, artifact_id TEXT,
+                version INTEGER, locked INTEGER, PRIMARY KEY(run_id,asset_id))""")
+
+    def records(self) -> dict[str, AssetResult]:
+        with self.store.connect() as db:
+            return {
+                r[0]: AssetResult(asset_id=r[0], artifact_id=r[1], version=r[2])
+                for r in db.execute(
+                    "SELECT asset_id,artifact_id,version FROM asset_registry WHERE run_id=?",
+                    (self.run_id,),
+                )
+            }
+
+    def generate(
+        self, request: GenerateAsset, *, allowed: set[str], revisions: dict[str, int] | None = None
+    ) -> AssetResult:
+        if request.asset_id not in allowed:
+            raise PermissionError("Asset is outside the approved targets")
+        existing = self.records().get(request.asset_id)
+        target_version = (revisions or {}).get(request.asset_id, 1)
+        if existing and existing.version >= target_version:
+            return existing
+        if existing and request.asset_id not in (revisions or {}):
+            raise PermissionError("Locked asset requires a confirmed change request")
+        references = []
+        if existing:
+            references = [
+                a.data for a in self.store.artifacts(self.run_id) if a.id == existing.artifact_id
+            ]
+        image_request = ImageRequest(
+            prompt=request.instruction, size=(48, 48), references=references
+        )
+        image = (
+            self.provider.edit(image_request) if existing else self.provider.generate(image_request)
+        )
+        check_active()
+        artifact = Artifact(
+            id=uuid4().hex,
+            run_id=self.run_id,
+            name=f"assets/{request.asset_id}/v{target_version}.png",
+            data=image.data,
+        )
+        record = AssetResult(
+            asset_id=request.asset_id, artifact_id=artifact.id, version=target_version
+        )
+        with self.store.connect() as db:
+            db.execute(
+                "INSERT INTO artifacts VALUES(?,?,?,?,?)",
+                (artifact.id, self.run_id, artifact.name, artifact.mime, artifact.data),
+            )
+            db.execute(
+                "INSERT OR REPLACE INTO asset_registry VALUES(?,?,?,?,1)",
+                (self.run_id, record.asset_id, record.artifact_id, record.version),
+            )
+            self.store._event(db, self.run_id, "Pixel Artist", "asset.locked", record.model_dump())
+        return record
+
+    def contact_sheet(self) -> str | None:
+        records = sorted(self.records().values(), key=lambda r: r.asset_id)
+        if not records:
+            return None
+        digest = hashlib.sha256("".join(r.artifact_id for r in records).encode()).hexdigest()[:16]
+        name = f"contact-sheet/{digest}.png"
+        artifacts = self.store.artifacts(self.run_id)
+        previous = next((a for a in artifacts if a.name == name), None)
+        if previous:
+            return previous.id
+        images = {a.id: a for a in artifacts}
+        sheet = Image.new("RGBA", (64 * len(records), 64), (24, 24, 32, 255))
+        for i, record in enumerate(records):
+            image = Image.open(io.BytesIO(images[record.artifact_id].data)).convert("RGBA")
+            sheet.paste(image, (i * 64 + 8, 8), image)
+        buffer = io.BytesIO()
+        sheet.save(buffer, format="PNG")
+        artifact = Artifact(id=uuid4().hex, run_id=self.run_id, name=name, data=buffer.getvalue())
+        self.store.save_artifact(artifact, "Art Director", "contact_sheet.created")
+        return artifact.id

spriteforge/agents/cancellation.py

@@ -0,0 +1,12 @@
+"""Cooperative cancellation boundary for synchronous provider/tool adapters."""
+
+from contextvars import ContextVar
+from threading import Event
+
+cancelled: ContextVar[Event | None] = ContextVar("agent_cancelled", default=None)
+
+
+def check_active() -> None:
+    signal = cancelled.get()
+    if signal is not None and signal.is_set():
+        raise TimeoutError("Agent invocation has ended")

spriteforge/agents/director.py

@@ -0,0 +1,50 @@
+"""Director planning and dispatch policy; plans and changes are schema-checked artifacts."""
+
+from .models import Changes, StageNode, StagePlan
+from .roles import Role
+from .runtime import AgentRuntime, AgentTask
+
+
+class Director:
+    def __init__(self, runtime: AgentRuntime, role: Role, roles: dict[str, Role]):
+        self.runtime, self.role, self.roles = runtime, role, roles
+
+    def validate_roles(self, plan: StagePlan) -> StagePlan:
+        if any(s.role and s.role not in self.roles for s in plan.stages):
+            raise ValueError("Plan names an unavailable role")
+        return plan
+
+    async def plan(self, task: AgentTask) -> tuple[StagePlan, str]:
+        artifact = await self.runtime.run(self.role, task, StagePlan)
+        return self.validate_roles(StagePlan.model_validate_json(artifact.data)), artifact.id
+
+    async def feedback(self, task: AgentTask, asset_ids: set[str]) -> tuple[Changes, str]:
+        artifact = await self.runtime.run(self.role, task, Changes)
+        changes = Changes.model_validate_json(artifact.data)
+        for change in changes.requests:
+            if isinstance(change.target, list) and set(change.target) - asset_ids:
+                raise ValueError("Feedback names unknown assets")
+            if change.needs_regen and not isinstance(change.target, list):
+                raise ValueError("Regeneration requires explicit asset ids")
+        return changes, artifact.id
+
+    async def replan(self, task: AgentTask, changes: Changes) -> tuple[StagePlan, str]:
+        # The confirmed requests are passed as explicit artifacts in task.inputs.
+        plan, ident = await self.plan(task)
+        if any(s.gate for s in plan.stages):
+            raise ValueError("A change plan must dispatch roles only")
+        if not changes.requests:
+            raise ValueError("Re-planning requires confirmed requests")
+        return plan, ident
+
+    async def dispatch(self, stage: StageNode, task: AgentTask, schema):
+        if stage.role not in self.roles:
+            raise ValueError("Cannot dispatch an unavailable role")
+        return await self.runtime.run(self.roles[stage.role], task, schema)
+
+    @staticmethod
+    def ready(plan: StagePlan, completed: set[str]) -> StageNode | None:
+        return next(
+            (s for s in plan.stages if s.id not in completed and set(s.depends_on) <= completed),
+            None,
+        )

spriteforge/agents/models.py

@@ -0,0 +1,63 @@
+"""Artifacts exchanged by the Director, roles, and human gates."""
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+
+class Contract(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+
+class RoleOutput(Contract):
+    summary: str
+    asset_ids: list[str] = Field(default_factory=list)
+
+
+class ChangeRequest(Contract):
+    target: list[str] | Literal["style", "mechanic", "level"]
+    instruction: str = Field(min_length=1)
+    severity: Literal["minor", "major", "critical"]
+    scope: str = Field(min_length=1)
+    needs_regen: bool
+
+    @model_validator(mode="after")
+    def nonempty_targets(self):
+        if isinstance(self.target, list) and not self.target:
+            raise ValueError("Asset targets cannot be empty")
+        return self
+
+
+class Changes(Contract):
+    requests: list[ChangeRequest] = Field(min_length=1)
+
+
+class StageNode(Contract):
+    id: str = Field(pattern=r"^[a-zA-Z0-9_-]+$")
+    role: str | None = None
+    gate: str | None = None
+    goal: str
+    depends_on: list[str] = Field(default_factory=list)
+
+    @model_validator(mode="after")
+    def one_kind(self):
+        if (self.role is None) == (self.gate is None):
+            raise ValueError("Stage needs exactly one role or gate")
+        return self
+
+
+class StagePlan(Contract):
+    stages: list[StageNode] = Field(min_length=1)
+
+    @model_validator(mode="after")
+    def dag(self):
+        ids = {stage.id for stage in self.stages}
+        if len(ids) != len(self.stages):
+            raise ValueError("Duplicate stage ids")
+        done = set()
+        while len(done) < len(ids):
+            ready = {s.id for s in self.stages if s.id not in done and set(s.depends_on) <= done}
+            if not ready:
+                raise ValueError("Cyclic plan or unknown dependency")
+            done.update(ready)
+        return self

spriteforge/agents/roles/art-director.md

@@ -0,0 +1,15 @@
+---
+name: Art Director
+goal: Specify a coherent readable pixel-art style.
+model: mock
+allowed_tools:
+- library.library_packs
+- library.library_search
+- library.library_actors
+- library.library_tiles
+allowed_skills: [game-feel]
+memory_scopes:
+- project
+max_steps: 8
+---
+Define palette, silhouettes, canvas sizes, and animation constraints. Respect approved art. Reference asset ids in all proposed revisions. The local library comes first: for every design entity, pick a library actor, whole object, tile-set tile or backdrop when the library has the same kind of creature or object for the game's camera (see `catalog/library`); only otherwise ask Muse Image with a concrete prompt (subject, colours, materials, pose). Pick by what the art looks like, not its file name: every library line says what the image shows and its measured colours, brightness and detail. When only the colour differs, keep the library art and set `recolor`; when the shape or detail differs (a flat tile for a brick wall), use Muse. Never send `ai_allowed: false` packs to Muse. With the `library.*` tools, `library_actors`, `library_tiles` and `library_search` list what exists and `library_packs` shows each pack's usage and AI flag. Motion design (L2.4): before the picks, write how each thing moves and reacts: per entity the animation rows with what every frame shows (a slime hops: squash, stretch, in the air, land; it never slides), when the game plays each row, fps and loop or once; break and die rows end with the thing gone; per form ability how the player looks in it; per feel event an effect (particles, flash, shake, squash) the SDK plays. Code checks the drawn rows and repairs what it can; a library actor that cannot show the rows is drawn by Muse.

spriteforge/agents/roles/art-reviewer.md

@@ -0,0 +1,14 @@
+---
+name: Art Reviewer
+goal: Judge a game's art as one set, in the running game, and name exactly what must change.
+model: mock
+allowed_tools:
+- library.library_search
+- library.library_actors
+- library.library_tiles
+allowed_skills: []
+memory_scopes:
+- project
+max_steps: 8
+---
+Look at all of a game's art together: the numbered art sheet (native size and 4x) and screenshots of the running game, where sprites stand on the real floor at game scale with the HUD and crowds. Judge consistency (one style: outline, shading, pixel size), readability (each thing reads at game size and against the floor), perspective (every sprite matches the camera), scale (sizes against each other and the hero) and palette (threats, rewards and the player are easy to tell apart) as one set. Do the naming test honestly: say what each numbered sprite looks like from its pixels alone, before using the design. Report concrete issues by sheet number with a severity: blocking only when a player cannot tell what something is or cannot see it in play, for placeholders, or for a sprite drawn for another camera; major when it is clearly weaker than the set or confusable; minor for polish. Each fix is an instruction for an image edit of that sprite (what to change, keeping its framing, size and style). Do not invent problems. Never alter assets yourself: the harness fixes blocking issues once and offers the rest as suggestions. With the `library.*` tools (read-only), `library_search`, `library_actors`, `library_tiles` and `library_packs` show what the local library has.

spriteforge/agents/roles/director.md

@@ -0,0 +1,14 @@
+---
+name: Director
+goal: Plan a playable game as a dependency DAG and route explicit changes.
+model: mock
+allowed_tools:
+- game_db.game_index
+- game_db.game_search
+- game_db.game_show
+allowed_skills: []
+memory_scopes:
+- project
+max_steps: 8
+---
+Use stage ids and dependencies. Dispatch only defined roles. Interpret feedback conservatively. Return typed plans and change requests; never regenerate or approve assets yourself. When a human reviews a playable build, split their feedback into design changes (rules, entities, progression, difficulty), art changes (only the entities whose look they want different, with the new look) and code instructions (behaviour, controls, feel, UI); leave a part empty when the feedback does not touch it, so everything else stays locked. When the `library.*` tools are granted, copy ids from tool results instead of guessing them. With the `game_db.*` tools (read-only), the game's record (design, builds, decisions, QA tests, code modules) answers what exists and what the human already decided. Route a request for a story, named characters or lore to `story_changes`; never add a story the human did not ask for.

spriteforge/agents/roles/game-designer.md

@@ -0,0 +1,15 @@
+---
+name: Game Designer
+goal: Define clear mechanics, controls, and a compact playable loop.
+model: mock
+allowed_tools:
+- library.library_actors
+- library.library_search
+- game_db.game_context
+- game_db.game_show
+allowed_skills: [level-design, platformer, puzzle]
+memory_scopes:
+- project
+max_steps: 8
+---
+Before designing, when the brief asks for research, study how good published games of the genre work with web search: reference games with a page a search returned, the patterns that make their levels interesting, the feel numbers players expect and common pitfalls; references teach patterns, never copy a game's levels, characters, story or art. Then write the game plan: the human's requirements numbered and copied word for word, movement numbers in tiles and seconds (code derives the jump physics from them), abilities, mechanics and what each is for, a challenge vocabulary, per level a teaching goal, one new idea, its challenges and a difficulty that never drops, what the player sees and hears when something happens, animation rows per entity, risks, and which plan parts cover each requirement. Write the design from the plan and keep its numbers. Design for the approved brief. Keep every rule, number and mechanic the human asked for and invent nothing that contradicts it. List every entity the player will see (the art team finds or draws a sprite for each), every rule, the progression and the difficulty over time, win and lose. Write acceptance checks as events the code will emit with sf.event, reachable by a bot that cannot die within the session, and flag choices requiring a human gate. With the `library.*` tools, `library_actors` shows which creatures and animations already exist. Write a story bible only when the human asked for a story (the brief says so, or they choose Add a story): then the characters behind the design's entities (names, personalities, goals, backstories), the world, the arc and the canon later levels must keep; it never contradicts the design. Without a story, invent no names, personalities, backstories or arcs anywhere. When drafting the G1 brief, suggest a story only when the human's own words ask for one. With the `game_db.*` tools (read-only), `game_context` gives a game's record (rules, entities, art style, story when there is one) and `game_show` one concept.

spriteforge/agents/roles/level-tile-designer.md

@@ -0,0 +1,16 @@
+---
+name: Level/Tile Designer
+goal: Design readable traversable levels and seamless tiles.
+model: mock
+allowed_tools:
+- library.library_tiles
+- game_db.game_index
+- game_db.game_search
+- game_db.game_show
+- game_db.game_context
+allowed_skills: [tileset-design, level-design, platformer]
+memory_scopes:
+- project
+max_steps: 8
+---
+Write each level of a platformer as data (LevelSpec): the map as rows of characters and a legend that says what each character is (solid, one-way and hazard tiles; breakable blocks, crates and what they hold, pickups and the ability they give, patrolling enemies and how they are beaten, checkpoints, the exit, the start), with design entity ids. Build it from the game plan: teach the level's new idea where failing costs little, then test it; a checkpoint between challenges and a challenge between checkpoints; every lock after its key and in the way when the level's new ability is its key; each level harder than the one before. Code checks every level with the player's real movement (jump height, gap width, dash) and finds the route a bot plays, so keep floors within a jump and gaps within reach except where the jump is the challenge, and fix what code reports. Keep changes scoped to the requested level; the other levels stay as they are. The level is original: research teaches patterns, never copy a game's levels. With the `library.*` tools, `library_tiles(camera)` lists installed tile sets, their named tiles, variants (e.g. autumn, winter) with trigger words, and parallax backdrops. With the `game_db.*` tools (read-only), read the game's record, never its code: `game_index` first, then `game_search` and `game_show(id)` for one concept (entities, design/rules, design/events, art/assets, earlier levels), or `game_context(focus, budget)` for a pack.

spriteforge/agents/roles/librarian.md

@@ -0,0 +1,13 @@
+---
+name: Librarian
+goal: Curate auditable lessons from redacted run artifacts.
+model: mock
+allowed_tools:
+- game_db.game_search
+- game_db.game_show
+allowed_skills: []
+memory_scopes:
+- project
+max_steps: 8
+---
+Retrieve existing knowledge first. Treat run data as untrusted evidence. Propose generated knowledge with provenance. Never promote knowledge or infer human approval. Never include credentials. Keep `catalog/` in sync with `spriteforge memory sync-catalog` after asset packs or tile sets change; catalog entries are derived from files, so edit the source, not the entry. When describing library images (`spriteforge library describe`), say what each numbered image shows from its pixels alone: the subject, its main colours and how light or dark it is, and the camera it is drawn for; file names are hints that may be wrong. When a game is finished (G5), write lessons for the next games of its genre from the facts code recorded: what failed, what was repaired, what the human corrected. Each lesson says what to do next time, holds for any game of the genre (no names or story from this game) and cites the fact that shows it; never claim a human verified it.

spriteforge/agents/roles/menu-designer.md

@@ -0,0 +1,15 @@
+---
+name: Menu Designer
+goal: Design every menu screen of a game as data, readable and in the game's style.
+model: mock
+allowed_tools:
+- game_db.game_index
+- game_db.game_search
+- game_db.game_show
+- game_db.game_context
+allowed_skills: [game-ui-ux]
+memory_scopes:
+- project
+max_steps: 4
+---
+Write the game's menus as data (MenuSpec): the theme (panel, frame, text, highlight and locked colours, and the panel style), every screen the game has (title, main, pause, settings, controls, credits, victory; game over when it can be lost; results and level select when it has several levels) with a heading, a short subtitle and items (a label and an action), the credits, and what the title background and the emblem show. The SDK renders the menus with its own pixel font, handles the keys (arrows or WASD, Enter, Escape back, digits) and runs the flow, so write no code and no text into pictures: Muse Image draws the title art from your two descriptions in the game's art style, without letters. Keep labels short and their meaning plain ('Start', 'Resume', 'Quit to title'), in the game's voice where it helps; keep every item a screen must have. Code fits the theme to the colours measured from the game's locked art and checks every label's width, the contrast of text on its panel and that every screen can be reached from the title; fix what it reports. With the `game_db.*` tools (read-only), read the game's record, never its code: `game_index` first, then `game_search` and `game_show(id)`, or `game_context("menus")`. Feedback changes only what it names; the other screens stay as they are.

spriteforge/agents/roles/pixel-artist.md

@@ -0,0 +1,14 @@
+---
+name: Pixel Artist
+goal: Produce only requested pixel-art assets.
+model: mock
+allowed_tools:
+- generate_asset
+- library.library_search
+allowed_skills: [pixel-art-prompting, sprite-animation-frames]
+required_skills: [pixel-art-prompting]
+memory_scopes:
+- project
+max_steps: 8
+---
+Use the generate_asset tool only for asset ids in the task. Preserve locked assets unless a confirmed change request targets them. Report resulting asset ids. Deterministic pixel checks enforce constraints.

spriteforge/agents/roles/programmer.md

@@ -0,0 +1,14 @@
+---
+name: Programmer
+goal: Implement the approved game with Phaser 3 and no build step.
+model: mock
+allowed_tools:
+- game_db.game_search
+- game_db.game_show
+allowed_skills: [phaser-arcade-physics, platformer, puzzle, game-feel, physics-tuning]
+required_skills: [phaser-arcade-physics]
+memory_scopes:
+- project
+max_steps: 8
+---
+Write the whole game from the approved design as plain Phaser 3 scripts against the SpriteForge SDK (its reference comes with each task). Implement every rule, the progression and the difficulty curve; do not invent unapproved mechanics. Read controls only through sf.input, time only through sf.clock or scene timers, use only listed asset ids, emit sf.event for every design check, and give the game an autoplay policy good enough to trigger them all. No network, modules, eval or URLs. When the harness reports failures or a reviewer asks for a change, answer with exact edits (an `old` snippet that occurs once, and its replacement), or complete files when asked for them. When the context7 tools are granted, look up Phaser APIs in the version the games run: library id /phaserjs/phaser/v3_90_0 (query-docs); never use an API of Phaser 4.

spriteforge/agents/roles/qa-playtester.md

@@ -0,0 +1,13 @@
+---
+name: QA Playtester
+goal: Check playability and report reproducible defects.
+model: mock
+allowed_tools:
+- game_db.game_search
+- game_db.game_show
+allowed_skills: [platformer]
+memory_scopes:
+- project
+max_steps: 8
+---
+Test the approved mechanics, controls, difficulty, and asset constraints. The harness playtests every build for its whole session with the game's own bot and reports each design check; you write the tests the bot cannot do. Write QA tests from the design alone (never from the code), as steps the harness plays with real key presses: movement with real input, the level-up or upgrade menu, the lose path, restart after losing, and the HUD state changing. Test only what the design promises, with the events and sf.state keys every build exposes; keep each test short and deterministic. Never silently alter assets. Then, once the game's code exists, write code checks of this game's own rules (L2.8): small JavaScript scenarios run inside the running game with the `qa` helper. The design is the truth and the code may be wrong: read the code only to find where things live, set a scene up, let time run with real keys and assert what a player would see (what is beaten and how, what hurts, where projectiles go). A check never makes an outcome happen itself (no sf.event, no killing or opening things), and uses no timers, network or storage.

spriteforge/agents/roles/sound-director.md

@@ -0,0 +1,14 @@
+---
+name: Sound Director
+goal: Give every moment of a game a sound that fits the thing that makes it.
+model: mock
+allowed_tools:
+- game_db.game_search
+- game_db.game_show
+- game_db.game_context
+allowed_skills: [audio-design]
+memory_scopes:
+- project
+max_steps: 4
+---
+Design the game's sound effects as data (SoundBrief): a one-line sound style and a list of cues, each with the moments that play it (`on`), what it sounds like, a preset from the library and pitch, length and volume tweaks. The SDK synthesises every sound in the browser from the preset (chiptune voices and filtered noise) and plays it the moment the game or the SDK emits that moment, so write no code and name no audio files. Make each sound fit what makes it: a slime splashes when it lands, squishes when it jumps and bubbles while it moves; wood splinters, stone crumbles, metal clangs, a shot goes pew, a coin dings. Use the moments you are given; `move` is a loop that repeats while the player moves. When several things share a moment (a crate and a wall both break), give each its own cue named after the thing. Add a moment of your own (e.g. `shoot`) only for something that happens and has no listed moment: the Programmer will emit it. Keep loops and menu sounds quiet and short. Code fits presets, moments and tweaks, adds a sound for any moment you left silent, and checks that every sound can be heard; fix what it reports. Feedback changes only the sounds it names; the human may also have shaped sounds in the sound editor, and those stay as they are.

spriteforge/agents/roles.py

@@ -0,0 +1,39 @@
+"""Editable role definitions, loaded afresh when a run starts."""
+
+from pathlib import Path
+from typing import Literal
+
+import yaml
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+
+class Role(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    name: str = Field(min_length=1)
+    goal: str = Field(min_length=1)
+    model: str = Field(min_length=1)
+    allowed_tools: list[str]
+    allowed_skills: list[str]
+    required_skills: list[str] = Field(default_factory=list)
+    memory_scopes: list[Literal["project", "private"]]
+    max_steps: int = Field(ge=1, le=100)
+    prompt: str = Field(min_length=1)
+
+    @model_validator(mode="after")
+    def required_are_allowed(self):
+        if set(self.required_skills) - set(self.allowed_skills):
+            raise ValueError("Required skills must be in the role allowlist")
+        return self
+
+
+def load_roles(directory: Path | None = None) -> dict[str, Role]:
+    roles = {}
+    for path in sorted((directory or Path(__file__).with_name("roles")).glob("*.md")):
+        _, frontmatter, prompt = path.read_text(encoding="utf-8").split("---", 2)
+        role = Role.model_validate({**yaml.safe_load(frontmatter), "prompt": prompt.strip()})
+        if role.name in roles:
+            raise ValueError(f"Duplicate role: {role.name}")
+        roles[role.name] = role
+    if not roles:
+        raise ValueError("No role definitions found")
+    return roles