First contract

Start Here

Run a tiny example end to end and watch a session resolve into an inspectable contract before any agent work begins.

This walkthrough does not ask PersonaKit to make a code change. It asks PersonaKit to prove the operating contract that an agent would receive before making a change.

Before you begin

This walkthrough runs against a bundled example root, so you need two things:

The personakit CLI on your PATH — see Install PersonaKit.
The example root. If you cloned the repo, it already lives at Site/public/examples/swift-cli-maintenance (the path used below). If you installed only the CLI, run personakit init <dir> to scaffold your own validating root, then point --root at it instead — the commands are the same, though your contract's specifics will differ from the example shown here.

The 30-second version

Run it now, read the why after

You told the agent to stay read-only and it edited anyway. Here is that boundary made into a contract you can run:

cd Site/public/examples/swift-cli-maintenance
personakit validate --root personakit-root
personakit contract --root personakit-root --session cli-maintenance
personakit export --root personakit-root --session cli-maintenance

That resolves one contract: code editing authorized, deployment and autonomous loops forbidden, all visible before any work. The rest of this page explains what each command proves, then the schema behind it.

New to the CLI? Run personakit with no arguments to orient: it points you to personakit guidance for the current scope and personakit --help for the full command list.

1. Validate The Example Root

cd Site/public/examples/swift-cli-maintenance
personakit validate --root personakit-root

Expected shape:

Validation summary: personas=1 kits=1 directives=1 skills=4 errors=0

Validate and contract also print a leading line naming the resolved scopes. Here it reports project-only, because --root pins a single root and skips global library discovery.

What this proves: the authored PersonaKit root is structurally valid. The persona, directive, kit, skill declarations, and session can be loaded before any agent work starts.

2. Inspect The Resolved Contract

personakit contract --root personakit-root --session cli-maintenance

The output is longer than this, but these are the first fields to care about:

{
  "sessionId" : "cli-maintenance",
  "personaId" : "cli-maintainer",
  "directiveId" : "bounded-cli-fix",
  "authorizedSkillIds" : [
    "code-editing"
  ],
  "forbiddenSkillIds" : [
    "autonomous-agent-loop",
    "deployment-runner"
  ],
  "injectedContractIds" : [
    "persona-activation-contract",
    "skill-authorization-contract"
  ],
  "isAuthorized" : true
}

What this proves: the named session resolves to one role, one directive, injected built-in contracts, and an explicit capability boundary. PersonaKit is no longer relying on prompt memory or implied intent.

3. Export The Handoff Context

personakit export --root personakit-root --session cli-maintenance

What this proves: the resolved operating contract can be exported as inspectable handoff context before any coding tool starts work.

Add --stats to print a size summary of the resolved export (lines, bytes, sections) to stderr, which helps spot context bloat before handoff.

How To Read The Payload

Section	What To Check
Resolution	The session, persona, directive, and kits match the work mode you intended.
Persona	The role has the right responsibilities, values, and non-goals.
Skill Contract	The needed capability is authorized and dangerous capabilities are forbidden.
Applied Kits	The durable rules that shape this work mode are included.
Grounding Skills	Always-on and triggered grounding is present, including built-in PersonaKit contracts.
Directive	The steps, stop points, acceptance criteria, and verification fit the task.
Handoff Context	The exported Markdown is ready to copy into the coding tool you use for the actual work.

What You Proved

PersonaKit can load authored project context.
PersonaKit can validate its shape.
A named session resolves to concrete boundaries.
Built-in persona activation and skill authorization contracts are injected.
Authorized and forbidden capabilities are visible before work starts.
The exported handoff context can be inspected before work starts.

PersonaKit Studio uses this same resolved-contract model for visual inspection and pack maintenance, but this guide keeps the CLI and static example root as the primary practical path.

Next Step

Now that you have seen a resolved contract, learn how the pieces compose before choosing a root to adapt.

Continue to Learn PersonaKit