Work with templates

Both Platform and Organization Templates use a draft-and-publish workflow. A lineage has at most one mutable draft in its owning scope. Saving a draft preserves work without creating a published Template Version. Publishing creates the next immutable version and clears the draft. Agents continue to use their exact pinned published version until explicitly repinned.

New Organization Templates begin as draft-only lineages. They become selectable as published Templates after their first publication. Organization Members can read and use published Templates but cannot author shared definitions. Organization Owner/Admin manage Organization Templates; Platform authoring requires Platform Administrator authority.

1. Open Settings → Templates in the selected Organization.
2. Create a new Template or open an existing lineage's detail page.
3. For an existing Template, select Start draft or Continue editing draft.
4. Edit the metadata, Markdown artifacts, and required Skills. Required Skill selections retain exact version pins and standalone/group requirements.
5. Save the draft to retain unpublished work.
6. Publish when the draft is ready to become the next immutable Organization Template Version.
7. Explicitly select the published version on each Agent that should use it.

The lineage list shows published-version and draft state. A lineage can have a published version and an in-progress draft at the same time. Editing a shared Template does not edit an Agent-private Override Draft. Draft-only content cannot be pinned or executed by an Agent.

Recommended authoring sequence

1. Define the behavioral boundary in SOUL.md and the role in IDENTITY.md.
2. Add repeatable workflows to AGENTS.md.
3. Add tool-selection conventions to TOOLS.md.
4. Provide a context schema in USER.md.
5. Keep startup setup repeatable in BOOT.md.
6. Add idempotent preparation to BOOTSTRAP.md.
7. Add bounded proactive checks to HEARTBEAT.md.

Before writing workflows, establish what the Agent is, what it is allowed to do, what it must never do, what authority it lacks, when it must ask for confirmation, and when it must escalate.

Add repeatable workflows

A useful workflow includes a trigger, required inputs, validation, ordered actions, an approval boundary, expected output, failure or escalation behavior, and the durable state that should be recorded.

Avoid relying on vague instructions:

Handle support tickets appropriately.

Prefer an explicit contract:

For a support request:

1. Classify it as informational, access-related, billing-related, or technical.
2. Answer informational requests from approved documentation.
3. Never perform an account or billing change without the required authority.
4. Escalate security incidents immediately.
5. End with the action taken or the next owner.

Keep content in the correct artifact

Write for reuse

A shared Template should avoid hardcoding a specific Agent name, a platform bot username, one Slack channel, one Telegram chat ID, one Discord server, one person’s credentials, one customer’s private information, or environment URLs that are supplied by an integration.

Use supported placeholders for the Agent name. Tool credentials belong to Agent Secrets or eligible Shared Credentials; messaging credentials and Connection-owned access or admission policies are managed separately.

A Template can require explicit Skill assignments at exact published versions.

Required:
- Jira
- Confluence

Agent must have:
Jira AND Confluence

Code host:
- GitHub
- Bitbucket

Agent must have:
GitHub OR Bitbucket

required_skill_versions maps every selected Skill ID to its exact published version. A Skill cannot be both standalone and a group member, or belong to multiple groups, in the same Template Version. Every required Skill must already have a published version.

Add required Skills

In the Template editor:

1. Find Required skills.
2. Search for an accessible Skill.
3. Select Add for a standalone requirement.
4. To create an alternative group, select Group skills.
5. Select the alternatives.
6. Choose Group as “at least one of”.
7. Review the version shown for every selected Skill; choose an older published version only for deliberate compatibility or rollback behavior.
8. Review the required providers shown under each Skill.
9. Publish only after every requirement points to an available immutable Skill Version.

Provider requirements

A required Skill may need a provider credential.

Template requires:
At least one of GitHub or Bitbucket

Agent selects:
GitHub

Agent must also have:
A valid GitHub Agent Secret or Shared Credential

Agent Barn validates required Skills and provider credentials when an Agent is hired, updated, or repinned.

Applying a Template Version evaluates tool Integration provider credentials across every required Skill pin the request will assign. If a required Skill or prospective version move requires a provider credential that the Agent lacks, the application is blocked before changes are written.

Both Organization and Platform Template editors persist the selected version map. If required_skill_versions omits a newly selected Skill, the API resolves its latest published version at creation or publish time; that resolved pin is then immutable.

When publishing an Organization Template Version, omitted required-Skill fields preserve the previous requirement set and its exact pins. Supplying required_skill_versions repins only named selected requirements; newly selected Skills without an explicit pin resolve to their latest published version. Version entries outside the effective requirement set are rejected.

Select a Template while hiring

1. Select a Template.
2. Select the intended published version.
3. Review its description.
4. Preview the Markdown artifacts.
5. Review standalone and grouped Skill requirements and their exact versions.
6. Assign the required Skills at those versions.
7. Supply required provider credentials.
8. Finish creating the Agent.

The Agent pins the selected version. A later Template publish does not move that pin.

Apply a Template to an existing Agent

Agent → Configuration → Template

1. Select Edit.
2. Search by Template name, version, or key.
3. Select an exact published version.
4. Preview the selected snapshot.
5. Review required Skills and their exact versions.
6. Add or repin missing required Skills in the Agent’s Skills section if necessary.
7. Apply the selection.

Preview the selected version before applying it. Agent Barn revalidates every standalone Skill, at least one correctly versioned member from each group, exact Skill Version pins, and required tool Integration credentials. If the Agent has the right Skill lineage at the wrong version, application is rejected until it repins that Skill.

Both Platform and Organization Templates use a draft-and-publish workflow. A lineage has at most one mutable draft in its owning scope. Saving a draft preserves work without creating a published Template Version. Publishing creates the next immutable version and clears the draft. Agents continue to use their exact pinned published version until explicitly repinned.

New Organization Templates begin as draft-only lineages. They become selectable as published Templates after their first publication. Organization Members can read and use published Templates but cannot author shared definitions. Organization Owner/Admin manage Organization Templates; Platform authoring requires Platform Administrator authority.

1. Open Settings → Templates in the selected Organization.
2. Create a new Template or open an existing lineage's detail page.
3. For an existing Template, select Start draft or Continue editing draft.
4. Edit the metadata, Markdown artifacts, and required Skills. Required Skill selections retain exact version pins and standalone/group requirements.
5. Save the draft to retain unpublished work.
6. Publish when the draft is ready to become the next immutable Organization Template Version.
7. Explicitly select the published version on each Agent that should use it.

The lineage list shows published-version and draft state. A lineage can have a published version and an in-progress draft at the same time. Editing a shared Template does not edit an Agent-private Override Draft. Draft-only content cannot be pinned or executed by an Agent.

To customize a built-in Platform Template:

1. Open Organization → Settings → Templates.
2. Filter by Built-in if needed.
3. Open the Platform Template.
4. Select Start draft.
5. Change the Organization-specific behavior.
6. Save the draft, then publish it to create Organization version 1.

Publishing the draft creates an Organization fork:

1. Platform Template v4 The global built-in the Organization starts from
2. Organization fork v1 Publishing the Organization draft creates the first Organization-owned snapshot
3. Organization v2, v3 Further Organization versions, evolving independently

The first Organization snapshot is always Organization version 1, regardless of the Platform version it was forked from. The fork keeps the stable Template key, its Platform origin, the Platform baseline version, and a separate Organization version sequence.

Existing Agents stay on their exact prior pins. They do not automatically move to the new fork.

Apply a Platform Template update

When a newer Platform version is available, Agent Barn displays Platform update available. Selecting Apply platform update creates the next Organization version from the complete newer Platform snapshot.

Before applying:

1. Review the current Organization customization.
2. Review the newer Platform version.
3. Save any changes that must be reintroduced.
4. Apply the Platform update.
5. Create another Organization version if local behavior must be added again.
6. Test before repinning Agents.

Existing Agent pins remain unchanged after the Platform update.

Built-in Platform Templates and their Organization forks cannot be deleted through normal Organization Template deletion.