Implementation guide
Start with the architecture diagram. Use the folder tree to lay out the persona, then follow the same definitions through installation, a team goal, and review.
Map the architecture to an implementation
Section titled “Map the architecture to an implementation”| Architecture | Definition or runtime responsibility | Reference |
|---|---|---|
| Persona and domain | Git holds the root skill, published configuration, ontology, and release evals. | Definition files |
| Team and playbooks | Studio stores team definitions, pinned agent placements, saved playbooks, and team resources in assets/studio-teams.json. |
Studio definitions |
| Linked definitions | The portable registry identifies workflow, pipeline, and list revisions. The generated workspace graph describes the wider authoring repository. | Registry and authoring graph |
| Goal, runtime, and harness | A team-scoped run captures its definition revisions and inputs. The runtime checks access and capabilities and uses the harness for supported steps. | Runtime rules |
| Connector and vault | The playbook declares operations and account context. The workspace grants a connection, holds its credentials, and maps logical operations to permitted tools. | Requirements and steps |
| Records and apps | A publish step sends allowed fields to a bound destination. A team view reads a list. A custom interface is a separate package with workspace installation settings. | Records, pipelines, and apps |
| Governed execution | The workspace records human decisions, rehearsal evidence, exact effect approvals, and live receipts. Reviewed changes to definitions or evals become new Git revisions. | Rehearsal and governed execution |
| Marketplace | Install an individual playbook, a team that pins playbooks, or a persona that pins teams. | Publish and reuse |
Example files
Section titled “Example files”The Meeting desk example uses a team goal to read an authorized calendar and draft a summary. A separate playbook lets a member review a summary before publishing it to a team board. The JSON uses the Gabriel Studio and ontology schemas.
| Path | What to inspect |
|---|---|
SKILL.md |
Domain instructions and review expectations. |
assets/chat-config.json |
The portable root envelope with a stable persona key. |
assets/ontology.json |
The meeting entity and fields that a source mapping can use. |
assets/studio-teams.json |
The team, agent pins, goal and structured playbooks, connector requirement, and list, pipeline, and board definitions. |
references/registry.json |
The portable lock. It is empty because all the example’s resources are local Studio definitions. |
These files illustrate the definition profile. Gabriel’s authoring tools generate the pins and validate changes against the destination workspace. The example has zero execution credits, and a workspace supplies the actual model, account, publisher, and grants. An appliance import uses a separately compiled, signed release candidate. See the Portable Persona Runtime installer.
Bind and run a team goal
Section titled “Bind and run a team goal”- Load the persona and verify pins. Read the root revision and each linked definition from its published revision. Compare fingerprints and reject unresolved or mismatched references. Preview and validate definition changes against the expected source and workspace revisions before adopting them.
- Resolve the execution environment. Select a harness with the capabilities the work needs and report unsupported steps. Gabriel’s native goal and connector playbooks use its native runtime. Other runtimes report their supported actions and account availability.
- Bind the example’s calendar. Use a member-authorized calendar connection and bind the logical
calendar:upcomingoperation. Map its result to the example’smeetingsfield. Configure a team budget and give the runfromanduntilinputs. The goal playbook declares the same connector authority as the child it can invoke. - Start the goal. A run captures the selected playbook and its permitted child definitions, with limits on delegation, time, model calls, and credits. Recheck membership and grants before dispatch. A missing account holds the step. A repeated start with the same request identifier must refer to the same inputs.
- Review and publish. Configure the workspace publisher
meeting-summariesforlist.meeting-desk.summariesand allow onlysummary. Rehearse Publish summary with synthetic text, consent to sharing the field, and review the exact input before continuing. The board reads the resulting list record. For a real handoff of private data, use the runtime’s accepted-output reference in the same parent goal so it can recheck the source grants.
Gabriel resolves private handoffs of the form studio-output:<runId>#/summary only when the source run is complete and its assignment was accepted in the same parent goal, team, workspace, and member scope. The workspace still checks whether the source allows shared publication.
See the Lane walkthrough for a larger example with connector reads, exact effect approval, shared publication, and handoffs.
Implement the review and rehearsal boundary
Section titled “Implement the review and rehearsal boundary”- Declare where a person is needed. Separate input confirmation or specialist judgment from approval to dispatch a protected effect. Route each decision to the person who has the relevant authority. An optional AI reviewer can provide evidence for either decision.
- Exercise the proposed effect safely. For Meeting desk, use a disposable workspace, synthetic meeting text, and a test publisher. Verify the summary field mapping and denied fields, then capture the proposed destination, allowed fields, and result. In a form playbook, use a copied form or a test endpoint with live submission disabled.
- Build the live proposal. Resolve the authorized production binding separately. Show the person the operation, exact proposed input, target, and acting account along with the rehearsal results and any gaps. Keep the decision attached to the proposal and its definition and policy revisions.
- Revalidate and dispatch once. Check current grants and material live facts. If the summary, destination, account, or policy changed, regenerate the affected evidence and obtain fresh approval. Reuse the durable result on a confirmed retry. When dispatch may already have happened, reconcile before trying again.
The Meeting desk files show the existing Studio review and publish steps. The test publisher and durable evidence records are runtime setup. The draft does not define an additional portable JSON field for sandbox configuration.
Review a revision
Section titled “Review a revision”For a connector write or process, hold dispatch until the authorized person approves the exact effect. An approval in Gabriel is scoped to the run, definition, step, operation, mapped input, and current connector assignment. Recheck it when the relevant details change. For shared publishing, check the destination grant, the member’s field consent, and source grants independently.
Record what the specialist reviewed and what was approved, corrected, or rejected. Turn a recurring issue into an eval case, then review and publish the updated definition. Future runs take the adopted revision and obtain their own permissions and approvals. See evals and specialist review.
Publish and reuse
Section titled “Publish and reuse”Commit linked resources first, then publish the persona root with their Git links and generated fingerprints. The portable registry pins linked definitions. The root commit versions local assets such as studio-teams.json. A workspace can adopt a new revision while keeping its own credentials, records, and run history.
For Studio packages, publish each playbook before the team that uses it and publish the team before the persona. Review each exact version and map the required operations and outputs in the destination workspace. Package and manifest reference
Compose and install a package
Section titled “Compose and install a package”- Define a capability. For an Accountants team, define a playbook that verifies public signals. Give it an input and output contract and a skill with the evidence rules. Add another playbook if the outcome requires a separate review or handoff.
- Compose a team. Reference the playbooks by exact revision and declare the handoffs and resource requirements. Bind the connectors and test a goal scoped to the team. Exercise any required review before dispatching a protected action.
- Publish the dependency graph. Publish playbooks before the team that pins them, and teams before the persona that pins them. Include the executable and skill files in each playbook release. The published name, version, and digest identify that release.
- Review installation and bind local resources. Resolve the selected release and its dependencies for the intended destination. Review its placements, operations, output bindings, and scripts before adoption. Supply the destination’s accounts, grants, budget, and compute before running a goal in the installed team. Portable playbook lifecycle
Gabriel reference implementation
Section titled “Gabriel reference implementation”Gabriel uses the versioned package profile and retains provider session or interaction IDs when it runs a bounded decision through a hosted adapter. It validates that decision and applies workspace tool grants and approval checks before any protected effect. The OpenAI SDK sandbox profile uses isolated compute. The OpenAI Realtime and Gemini Live profiles use native speech.
In Lane Pilot Research, the Google ADK and Gemini Agents API runs each recorded one live research read and cited the retrieved evidence. Separate checks exercised live Gemini speech and the isolated workspace for the OpenAI SDK. Live OpenAI and Claude model execution still require provider verification.