Part V · The configurable PDLC
Prompts & schemas¶
Two kinds of content define what an agent actually does: its prompt (how it behaves) and its artifact schema (what it must produce). Both are data, both are editable in the Lifecycle Studio, and both are versioned on every save. This page covers the Agent Editor, the prompt-block model, the artifact schemas and their section instructions, and the version history that backs it all.
About the visuals on this page
The illustrations come from the binding design mocks for the Agent Editor and Artifact Designer. The shipped build follows them; details may differ.
The Agent Editor¶
The Agent Editor (/pdlc/:id/agent/:name/edit) is the full configuration surface for one agent, organized in five tabs: Identity · System Prompt · Tools & Subagents · Model & Provider · Context.
For built-in agents the editor opens read-only except for the model allocation (see Agent rosters for the immutable-base rule); a duplicated custom agent is editable throughout.
Prompt blocks¶
An agent's system prompt is not one opaque wall of text. It is assembled from blocks — named, labeled sections you edit individually — plus shared partials: prompt fragments common to many agents (house rules, output conventions) that you toggle on or off per agent, each showing its token cost so you can see what a toggle spends on every single turn.
Why blocks instead of one text area? Three reasons:
- Reviewability. A change to "escalation rules" is a diff in one named block, not a needle in a 4,000-token haystack.
- Sharing without copy-paste. A partial edited once updates every agent that enables it; the copy-paste alternative drifts within a week.
- Honest preview. The editor renders the assembled system prompt as color-coded layers — exactly what the model will receive, with each block and partial attributable. What you review is what runs.
The editor can also run an automated prompt review before you save. It is advisory only — you can override it, and overrides are recorded in the version history rather than blocked.
The Tools tab¶
The Tools & Subagents tab grants capabilities. It is a registry-driven tree: every tool the instance's MCP registry knows about (built-in loopback tools, Prism, Context7, custom servers), searchable, with per-agent checkboxes layered over the agent's defaults. The same tab governs which subagents an agent may dispatch.
The reason grants are per-agent and explicit: an agent's tool set is part of its behavioural contract. A Librarian with repository-write tools is not a Librarian anymore.
Artifact schemas¶
Every phase produces an artifact, and the artifact's shape is declared as a schema — JSON Schema (draft 2020-12), validated server-side with ajv on every write. The schema is not documentation of the artifact; it is the contract: an agent's output that does not conform does not land.
This buys three things:
- Predictable structure. Every Vision artifact in every product following this lifecycle has the same sections and fields — reviewable, comparable, and consumable by downstream phases without guesswork.
- Server-side progress. Artifact completeness is derived from the schema — the fraction of sections actually filled — not from an agent's self-assessment.
- Editability. Changing what a Business Spec must contain is a schema edit in the Artifact Designer, not a code change.
The Artifact Designer¶
The Artifact Designer (/pdlc/:id/artifact/:phaseType) edits one phase's artifact definition: an outline rail of sections, a section editor for fields, and a live preview of the rendered artifact.
Fields are typed (string, array, enum, number, and structured sub-elements), and sections can be optional — opted into per artifact instance rather than cluttering every document.
Section instructions¶
Alongside the fields, each section carries its working instructions — metadata that guides the producing agent while it fills the section in:
- Intent — what this section is for, in one line.
- Completion rules — which fields (any or all) make the section count as done, feeding the server-side completeness measure the design workbench renders as the progress donut.
- What good looks like — concrete quality bars for the section's content.
- Decisions to surface — the judgment calls the agent must raise with you instead of silently making.
- Research hints — where the agent should look before writing.
This is why editing a schema changes agent behaviour without touching a prompt: the instructions travel with the section definition, so every agent producing this artifact — in every product on this lifecycle — picks up the new guidance on its next turn.
Definition versioning¶
Every save of a definition — in the Agent Editor and in the Artifact Designer — writes a full snapshot into an append-only version history: a numbered version carrying the complete document, a change summary, and the author. Saving is versioning; there is no separate "publish" step to forget.
Two properties follow from the append-only, full-snapshot design:
- Nothing is ever lost. Any prior version can be inspected — or restored verbatim, because each version is the complete document, not a diff that depends on its neighbours.
- Overrides are on the record. When a save proceeds against an advisory review, the version row says so.
And the fork-not-edit rule from the PDLC designer applies here too: saving a definition that belongs to the protected built-in lifecycle transparently forks the lifecycle first and applies your save — with its version history — to the fork. The shared baseline stays pristine; your changes are versioned in a lifecycle you own.