Sample-project tutorial

Build Agent Boundaries Around ReleaseDesk

Work on a tiny release-readiness dashboard, then add PersonaKit contracts when the product work needs safer agent boundaries.

ReleaseDesk is a small dashboard for a team preparing a public software release. It tracks required tasks, blockers, owners, and whether the release is ready to ship. The starter app looks plausible, but it has a serious bug: it can say the release is ready even when a required security review is blocked.

You will fix that product bug, review the change, add a filtered-list empty state, and prepare docs/release-readiness guidance. PersonaKit enters only when the work starts needing durable boundaries for agents.

Open starter app Materials: readiness skill completed app completed root

What You'll Build

The Product

A dependency-free ReleaseDesk dashboard with release metadata, readiness summary, task filters, blocker display, and a useful empty state.

The Host Skill

A local ReleaseDesk readiness skill that gives an agent a reusable procedure for investigating the failing rule and guiding an approved fix.

The Operating Contracts

Four work modes that make the approved job, skill access, validation, and stop points visible.

1. Get The Starter App Running

Work from a copy so the tutorial can create a local .personakit root without changing the published starter materials.

Terminal setup 
rm -rf /tmp/releasedesk-lab
cp -R Site/public/tutorials/releasedesk/starter /tmp/releasedesk-lab
cd /tmp/releasedesk-lab
open index.html
node test/run-tests.mjs

The app opens, but the test should fail. That failure is the first real reason to ask an agent for help.

Expected output 
not ok - blocked security review keeps release from ready
AssertionError [ERR_ASSERTION]: true !== false

2. Try A Skill First

A skill is the right first instinct. ReleaseDesk has a repeated procedure: inspect the release data, inspect the readiness rules, run the test, identify the smallest safe fix, and report validation. That procedure is useful; it just is not authority by itself.

Open the host-local skill in the starter project and read it like a procedure card. In a real agent tool, you would paste the skill text, attach the skill file, or invoke the host's skill mechanism before giving the task.

Skill file 
host-skills/releasedesk-readiness/SKILL.md

For this first pass, use the skill as shared instructions and keep the job diagnostic. The point is to learn what the skill can clarify before any edits are authorized.

Agent prompt 
Use the ReleaseDesk readiness skill to diagnose the failing readiness test.
Run node test/run-tests.mjs.
Do not edit files yet.
Return the suspected rule, evidence from the release data, and the smallest safe fix.

The useful result is not a code change yet. It is a grounded diagnosis:

Likely diagnosis 
Diagnosis
- The release has a required security task: "Complete security review".
- That task is blocked and its status is not "done".
- The readiness summary still reports ready, so the bug is in readiness logic, not release data.

Smallest safe fix
- In src/releaseRules.js, count every required task whose status is not "done".

The skill gives the agent a repeatable product procedure and keeps the task focused on ReleaseDesk instead of generic debugging. It answers "how should I investigate this?" but not "am I allowed to fix it right now?"

3. Where The Skill Gets Awkward

After diagnosis, the team needs more than a procedure. The same ReleaseDesk skill is helpful for implementation, but it should not quietly become authority to edit, review, release, or carry the task into another work mode. This is the gap PersonaKit fills: not more context, but visible permission boundaries.

Question Skill Alone PersonaKit Contract
Is this implementation or review? The skill can describe a procedure, but the active role is still implied by the prompt. The session resolves one persona and directive before work starts.
May the agent edit files? The answer depends on the current prompt and surrounding conversation. The contract can allow the skill in implementation and forbid it in review.
May the host use every available skill? The skill exists, so the agent may treat it as fair game. The contract distinguishes available capabilities from authorized capabilities.

The same pattern can be used for PersonaKit itself: a host skill can make grounding easy to invoke, while PersonaKit still defines the actual operating boundary. Open the PersonaKit grounding skill example.

4. Add A Bounded Implementation Lane

Now the operator approves the fix. The agent needs to edit code and use the readiness skill, but it must not release software, touch credentials, or expand the task. Start by declaring the shared capability and guardrail pieces.

Terminal setup 
personakit init .personakit

personakit create skill --root .personakit \
  --id code-editing \
  --name "Code Editing" \
  --description "Make focused source changes inside the approved scope." \
  --provided-by "host coding agent" \
  --risk-level medium \
  --requires-human-review \
  --risk-note "Can change project behavior."

personakit create skill --root .personakit \
  --id releasedesk-readiness \
  --name "ReleaseDesk Readiness Skill" \
  --description "Use the local ReleaseDesk readiness skill to diagnose readiness behavior and, when implementation is authorized, guide the fix." \
  --provided-by "host-local skill" \
  --risk-level medium \
  --requires-human-review \
  --risk-note "Can guide product behavior changes, but does not authorize edits by itself."

personakit create skill --root .personakit \
  --id deployment-runner \
  --name "Deployment Runner" \
  --description "Publish, deploy, tag, notarize, or release software." \
  --provided-by "release tooling" \
  --risk-level high \
  --requires-human-review \
  --risk-note "Can create public or irreversible release effects."

personakit create essential --root .personakit --force \
  --id contract-boundaries \
  --title "Contract Boundaries" \
  --body "Stay inside the approved task. Keep changes small. Validate before closeout. Stop before deployment, credential changes, or new execution behavior."

personakit create kit --root .personakit --force \
  --id product-guardrails \
  --name "Product Guardrails" \
  --summary "Shared ReleaseDesk boundaries for focused product work." \
  --essential contract-boundaries

Now create the persona, directive, and session for this specific kind of work.

Terminal check 
personakit create persona --root .personakit --force \
  --id product-implementer \
  --name "Product Implementer" \
  --summary "Implements small approved product changes with explicit validation." \
  --responsibility "Resolve the active contract before editing." \
  --responsibility "Keep implementation scoped to the requested behavior." \
  --value "small diffs" \
  --value "operator approval before release actions" \
  --non-goal "deployment" \
  --default-kit product-guardrails \
  --allow-skill code-editing \
  --allow-skill releasedesk-readiness \
  --forbid-skill deployment-runner

personakit create directive --root .personakit \
  --id small-product-change \
  --title "Small Product Change" \
  --goal "Complete one bounded implementation change without expanding the work mode." \
  --step "Read the active contract and identify the requested behavior." \
  --step "Make the smallest change that satisfies the task." \
  --review-step "Stop if the task requires release behavior, credentials, or new execution surfaces." \
  --acceptance "The change stays inside the requested scope." \
  --acceptance "Validation commands are reported." \
  --verify-command "node test/run-tests.mjs" \
  --skill code-editing \
  --skill releasedesk-readiness

personakit create session --root .personakit \
  --id implementation-lane \
  --persona product-implementer \
  --directive small-product-change

personakit contract --root .personakit --session implementation-lane
Boundary preview

Work mode: approved implementation for a bounded ReleaseDesk behavior change.

  • Allowed: code editing and the ReleaseDesk readiness skill.
  • Forbidden: deployment, release actions, tags, and credentials.
  • Validation: node test/run-tests.mjs.

The task prompt can stay focused on the diagnosed product bug because the contract carries the repeated boundary.

Agent prompt 
Operate under implementation-lane. Use the ReleaseDesk readiness skill to fix the readiness bug so blocked required security work prevents a ready-to-ship state. Run node test/run-tests.mjs and stop before any release action.

The fix belongs in src/releaseRules.js. The readiness summary should treat every incomplete required task as release-blocking, including security work.

Code change 
export function readinessSummary(tasks) {
  const required = requiredTasks(tasks);
  const incompleteRequired = required.filter((task) => task.status !== "done");

  return {
    blockedCount: blockedTasks(tasks).length,
    incompleteRequiredCount: incompleteRequired.length,
    isReady: incompleteRequired.length === 0,
    requiredCount: required.length,
  };
}

Run the test again after the fix:

Terminal check 
node test/run-tests.mjs

5. Add Review Only When Review Is A Different Job

After implementation, you need skepticism. Reusing the implementation skill and asking it to be careful blurs authority: the skill is optimized for readiness repair, not independent review. Create a read-only lane instead so the same product area can be inspected under a different contract.

Terminal check 
personakit create skill --root .personakit \
  --id code-review \
  --name "Code Review" \
  --description "Inspect code and report findings without editing files." \
  --provided-by "host coding agent" \
  --risk-level low \
  --note "Review findings do not authorize implementation."

personakit create persona --root .personakit \
  --id behavior-reviewer \
  --name "Behavior Reviewer" \
  --summary "Reviews behavior, scope, and validation without becoming the implementer." \
  --responsibility "Report confirmed issues before suggestions." \
  --value "findings first" \
  --value "read-only review" \
  --non-goal "code editing" \
  --default-kit product-guardrails \
  --allow-skill code-review \
  --forbid-skill code-editing \
  --forbid-skill releasedesk-readiness \
  --forbid-skill deployment-runner

personakit create directive --root .personakit \
  --id read-only-review \
  --title "Read-Only Review" \
  --goal "Review the current change without editing code." \
  --step "Inspect the diff and surrounding behavior." \
  --step "Report confirmed issues before suggestions." \
  --review-step "Stop before making fixes or staging files." \
  --acceptance "Findings are ordered by severity." \
  --verify-manual "Explain what was inspected and what remains unverified." \
  --skill code-review

personakit create session --root .personakit \
  --id review-lane \
  --persona behavior-reviewer \
  --directive read-only-review
Boundary preview

Work mode: read-only review of the current ReleaseDesk change.

  • Allowed: code review and findings-first reporting.
  • Forbidden: code editing and readiness repair.
  • Closeout: report findings, suggestions, and validation gaps.
Agent prompt 
Operate under review-lane. Review the readiness fix for behavior regressions and missing validation. Do not edit files.

If the reviewer finds a readiness issue, the contract still holds. A finding is evidence, not permission to switch modes.

Stop case 
A readiness issue is found under review-lane.
- Report it as a finding.
- Do not invoke the ReleaseDesk readiness repair skill.
- Do not edit files.
- Ask for approval before switching back to implementation-lane.

6. Use Approval To Add The Empty State

The dashboard has another product gap: choosing an area with no tasks leaves the list blank. That is a small approved fix, so reuse the implementation lane with a narrower prompt rather than creating a new durable contract.

Agent prompt 
Operate under implementation-lane. Add a useful empty state when a filter has no matching ReleaseDesk tasks. Do not change readiness rules.

In the completed app, choosing Design shows a clear empty state instead of a silent blank list.

7. Add A Docs And Release-Readiness Lane

ReleaseDesk also needs public-facing explanation and release-readiness notes. That work can change docs, but it still must not publish, tag, deploy, notarize, or modify credentials.

Terminal check 
personakit create skill --root .personakit \
  --id docs-editing \
  --name "Docs Editing" \
  --description "Update documentation and static learning content." \
  --provided-by "host coding agent" \
  --risk-level medium \
  --note "Can change public explanation but not product behavior."

personakit create skill --root .personakit \
  --id release-runner \
  --name "Release Runner" \
  --description "Create tags, publish artifacts, deploy, notarize, or modify release credentials." \
  --provided-by "release tooling" \
  --risk-level high \
  --requires-human-review \
  --risk-note "Can create public release effects."

personakit create persona --root .personakit \
  --id docs-maintainer \
  --name "Docs Maintainer" \
  --summary "Improves public learning content while avoiding release actions." \
  --responsibility "Make public copy clearer and more actionable." \
  --value "practical examples" \
  --non-goal "publishing releases" \
  --default-kit product-guardrails \
  --allow-skill docs-editing \
  --forbid-skill release-runner

personakit create directive --root .personakit \
  --id docs-readiness \
  --title "Docs Readiness" \
  --goal "Improve ReleaseDesk docs or inspect release readiness without publishing anything." \
  --step "Identify the user-facing confusion to resolve." \
  --step "Make the narrow docs change or report readiness gaps." \
  --review-step "Stop before tags, deployments, notarization, credentials, or public release steps." \
  --acceptance "Public claims remain inside the product boundary." \
  --verify-command "node test/run-tests.mjs" \
  --skill docs-editing

personakit create session --root .personakit \
  --id docs-readiness \
  --persona docs-maintainer \
  --directive docs-readiness
Boundary preview

Work mode: docs and release-readiness explanation without publishing anything.

  • Allowed: docs editing and public learning-content cleanup.
  • Forbidden: tags, publishing, deployment, notarization, and credentials.
  • Validation: report site/readiness validation status.

This lane exists because docs and release-readiness work has a different risk profile from implementation. It is not just "code editing, but wordier."

8. Add A Grounded Handoff Lane

Some host systems can choose tools or pass tasks into places the operator does not directly watch. PersonaKit should not become that system. It can define the boundary the host must resolve before tool choice and carry with the task.

Terminal check 
personakit create skill --root .personakit \
  --id mcp-grounding \
  --name "MCP Grounding" \
  --description "Resolve read-only PersonaKit context before selecting host-local tools." \
  --provided-by "PersonaKit MCP client" \
  --risk-level low \
  --note "Grounding provides context and provenance, not execution authority."

personakit create skill --root .personakit \
  --id worker-delegation \
  --name "Worker Delegation" \
  --description "Assign work to hidden helper workers." \
  --provided-by "agent harness" \
  --risk-level high \
  --requires-human-review \
  --risk-note "Can make work happen outside the operator's direct view."

personakit create persona --root .personakit \
  --id contract-grounded-agent \
  --name "Contract-Grounded Agent" \
  --summary "Resolves PersonaKit context before choosing tools or passing work onward." \
  --responsibility "Resolve the active contract before selecting tools." \
  --responsibility "Pass the relevant boundary with any assigned task." \
  --responsibility "Stop when a needed capability is missing or forbidden." \
  --value "ground first" \
  --non-goal "subagent orchestration" \
  --default-kit product-guardrails \
  --allow-skill mcp-grounding \
  --forbid-skill worker-delegation

personakit create directive --root .personakit \
  --id resolve-before-tools \
  --title "Resolve Before Tools" \
  --goal "Resolve PersonaKit context before any tool choice or worker handoff." \
  --step "Resolve the requested session and inspect authorization." \
  --step "Use only capabilities authorized by the resolved contract." \
  --review-step "Stop before assigning worker tasks or acting outside the exported boundary." \
  --acceptance "The resolved boundary is visible before work starts." \
  --verify-manual "Report the resolved session and authorization boundary." \
  --skill mcp-grounding

personakit create session --root .personakit \
  --id grounded-handoff \
  --persona contract-grounded-agent \
  --directive resolve-before-tools
Boundary preview

Work mode: resolve and export a boundary before a host receives scoped work.

  • Allowed: MCP grounding and boundary export.
  • Forbidden: worker delegation and release actions.
  • Closeout: report the resolved session and authorization boundary.

The rule is simple: resolve before tool choice, use only authorized capabilities, pass the relevant boundary with assigned work, and stop when a needed capability is missing or forbidden.

9. Compare The Finished Materials

The completed project includes the fixed app, the host-local skill, and a public personakit-root that mirrors what you built locally.

Terminal check 
personakit validate --root .personakit
personakit list --root .personakit sessions
personakit recommend --root .personakit --goal "Review this diff without editing files"
Piece Job
host-skills/releasedesk-readiness/SKILL.md Reusable procedure for a host agent working on ReleaseDesk readiness.
releasedesk-readiness PersonaKit declaration that makes the host-local skill visible in the contract.
implementation-lane Session that allows implementation and the readiness skill for approved fixes.
review-lane Session that forbids implementation and the readiness skill so review stays read-only.
Session Product Situation
implementation-lane Fix readiness logic or an approved dashboard behavior.
review-lane Inspect the change without editing files.
docs-readiness Improve explanation or readiness notes without release actions.
grounded-handoff Resolve boundaries before tool choice or host handoff.

Next step

Run the ReleaseDesk workday

Now that the foundation is in place, follow the same product through a normal engineering day: review pressure, approved fixes, docs cleanup, and handoff boundaries.

Continue to the workday