Templates — Choose What You Want to Reuse

aachat uses “template” for three different operations. Choose according to whether you want to structure documents in an existing Project, start a new Project together with its assigned Agents, or welcome a client through a public form.

These are starting materials. They do not continuously synchronize existing Projects with later template edits.

Reuse document kinds in an existing Project

Use this when several Projects should write similar briefs, specs, or reports. A kind defines the structure and display rules for documents; its _template.md gives authors a starting body. Installing kinds does not create a Project, assign Agents, copy conversations, or migrate existing document bodies.

1. In the target Project, open Discover templates in Docs, or Install from Discover in Kind Definition under Project Settings. You need write access (Admin or Collaborator). You can also use Install on a Discover → Document templates detail page and enter the Team slug and Project name.
2. Search the catalog and select a template. Read its kinds and description first.
3. Install it. If kind names conflict, “Conflicting kinds detected” appears; read the existing and incoming names before choosing Overwrite conflicting kinds. Cancel if the existing definition must be preserved.
4. Inspect the resulting kinds and their document templates. Create a document of a selected kind using its template and fill in the real task's content. Check its rendered fields and any validation diagnostics.

For example, after installing a brief kind, use its template for a new docs/brief/website-refresh.md in that Project. Replace example text with the actual goal and constraints. The local path is:

aachat/teams/<team>/projects/<project>/docs/brief/website-refresh.md

Save it through the Shared Documents workflow.

Installation merges nonconflicting kinds and requires explicit overwrite for same-named kinds. With an invalid existing definition, forcing installation can replace that definition, so inspect or preserve it first. Existing document text is not rewritten, but replacing its kind schema can change validation and rendering. A later catalog update does not update installed definitions automatically.

There are two ways to publish a kind template; neither is an Agent publication.

• Prepare it in publication management: in Publication management, choose Publish something new, then Document template and the source Project. The Runtime on your computer exports the Project's kind definition as kinds.yaml and prepares it for publication; a human reviews and publishes it. Publishing again from the same Project updates the same template. See Discover for the steps
• Publish directly from Kind Definition: Publish as Template under Kind Definition in Project Settings shares the selected definition as is. Enter a Name, a Slug (2–64 lowercase letters, numbers, and single hyphens), and Tags. Unsaved changes or validation errors block publishing

Either way, review included schema and template/example text for private content. If installation fails, check Project access and validation errors. For a conflict, choose deliberately between retaining the local definition and overwriting it; repeating an unchanged request does not resolve the conflict.

Start a Project from a Discover Project Template

Use this when a catalog example describes the work you want to start, together with its team of Agents. Starting prepares the template's Agents as your own Agents, joins all of them, sets the Lead, installs PROJECT.md, document kinds, and Workflows, and then sends the Lead your first request. You do not pick the Lead manually.

The Discover home shelf and the Project templates navigation entry are shown only while at least one template is published; the page itself stays reachable at /en/discover/project-templates.

Preconditions:

• You are signed in and are an active member of the team that will own the Project.
• If new Agents must be prepared, you can grant GitHub access once (each new Agent is created as a private repository in your GitHub account).
• For the Lead to start right away, your runtime is connected with aachat up. Without it, the Project is still created and the Lead's Session waits for the connection.

Steps:

1. Read the template's details and Agents in Project templates, then choose Start project. A template cannot start when its definition is incomplete (missing roles, Lead, or pinned sources), when it has no Agents, or when some of its Agents are not in the catalog.
2. Choose the team under Which team owns the project, enter a new Project name (2–30 lowercase letters, numbers, or hyphens; not stream, dm, or repo), and in What should this project do? describe the outcome, completion evidence, decision boundaries, and important references.
3. Choose Review project setup and check each role's assignment under The agents for your project.
   • If you previously prepared an Agent for the same team, source, and commit, it is reused (your changes and runtime settings are kept). Otherwise a new Agent is prepared.
   • Change assignments lets you assign one of your active Agents made from the same source (not dormant, with a repository). An Agent used in another team also joins this team.
   • If a previously prepared Agent was deleted or made dormant, explicitly choose Prepare a new agent for this role.
   • When new Agents are needed, choose a runtime under Runtime for new agents. If exactly one runtime is connected, it is used.
   • The document templates (kinds) and Workflows to install are listed. Workflows are installed without starting Runs or creating Triggers.
   • Connect GitHub once appears when GitHub access is needed.
4. Choose Start this project once. Preparing your project shows progress while it runs.
5. When Your project is ready appears, choose Open project. Check that every Agent joined, the Lead, PROJECT.md, the kinds in Docs, and Workflows, and follow the Lead's Session for connection status and replies.

The Lead's first Session handles setup: it prepares PROJECT.md and an initial REPORT.md, asks for missing information through Asks, and ends once both documents are complete. You then request the next work (Projects). A completed preparation means the first request was accepted, not that deliverables are finished.

What is and is not installed

The Project, PROJECT.md (with {project_name} and {agent.<key>} replaced by the real names), your Admin membership, every template Agent's membership, the Lead, document kinds' _template.md files, published Workflows, and the Lead's first request are committed together in one transaction. A partially created Project is never left behind.

Each newly prepared Agent is a copy of its source repository at the pinned commit, placed in your private repository, and gets a DM in your personal team like any other Agent. Copies are limited to 20 MiB per repository, and sources containing submodules, symbolic links, or Git LFS content cannot be prepared.

Existing document instances, Triggers, and reapplying a template to an existing Project are not included. The created Project does not stay synchronized with the template.

Interruption, resuming, and failures

• Preparation is saved. Even if you close the browser, unfinished preparations appear under Your project preparations on the team's Projects page, and Resume setup continues them. If a response is lost, the same preparation is looked up, so the same Project is not created twice.
• If the Project name was taken during preparation, choose Choose another project name, then Save name and continue to continue the same preparation.
• If GitHub authorization is needed again, use Connect GitHub and continue; for a temporary failure, use Retry preparation.
• Cancel preparation stops it. Agents and repositories already prepared are not deleted automatically and remain yours.
• If you are unsure whether a submission went through, check Your project preparations and the Projects list before starting a new preparation.

Prepare a Project Template in publication management for a human to publish

A Project Template is prepared from one of your Projects in Discover publication management; a human then reviews the content and publishes it. Agents cannot publish.

Preconditions:

• You are signed in.
• You are an Admin or Collaborator of the source Project. Archived Projects cannot be selected.
• aachat is running on your computer and shows as connected on the publication management screen. Preparation runs with that computer's Runtime.
• Every Agent the template assigns is already published on Discover. Preparation does not publish Agents automatically, so publish any unpublished Agent first (Discover).

Steps:

1. In Publication management, choose Publish something new, then choose Project template as the type.
2. Under What to share, select the source Project, check the Runtime and connection, and choose Prepare for publication.
3. The preparation Agent reads the Project's documents, document kinds, Workflows, and Agent assignments, and prepares project-template.json and its referenced files for publication. When preparation finishes, you can review the documents, assignments, and Workflows to be published, along with what changed from the source.
4. Write any changes you want in the conversation box on the same screen. The draft is saved, so you can continue from its row in the publication management list or from the same URL. The source Project's files are not changed.
5. Review the content and choose Publish this content. If publication fails, retry from the same screen.
6. Check the public page under Discover's Project templates.

See Discover for the shared screen flow and limits.

Review a saved draft

Opening a Project template row in the publication management list opens the review screen for its saved draft (/discover/admin?template=<id>).

• Switch between Overview, Agents, Documents, and Workflows. Select a document kind or a workflow and bundle file to read it; the full manifest is also available under Overview. Resolve listed issues, check “I reviewed this saved revision and its bundled files.”, and choose Publish reviewed revision.

Saving a draft alone does not change the published version. The list distinguishes Private draft, Published, and Published with unpublished edits. If the draft changes while you review it, publishing or unpublishing is rejected; review the refreshed content again. Unpublish stops publication and keeps the draft. If the slug is already used by another template, publishing fails with “Project template slug already exists”.

Definition limits

• project-template.json and its referenced files total at most 2 MiB. References must be relative to the same directory; absolute paths, .., and symbolic links are not allowed.
• 1–10 Agents, with exactly one Lead. Each Agent references a public catalog repository pinned to a 40-character lowercase commit SHA, and each repository appears only once. Each key is a unique lowercase identifier (letters, digits, -, _; at most 40 characters).
• At most 32 document kinds and 16 Workflows. Each Workflow follows normal bundle limits (1 MiB per file, 4 MiB per bundle, 128 files).
• Use {project_name} and {agent.KEY} in PROJECT.md and document templates, and never the author's own Agent name. In Workflows, steps.<key>.session.agent must be the quoted token "{agent.KEY}".

Welcome a client with an entry template

Use this for a dedicated client conversation without requiring a GitHub account. This is configured by a team owner/Admin in Team Settings → Client Entry, separately from Discover.

1. Create an enabled template with a project name pattern, such as consultation-{date}-{short_id}.
2. Select default human members (Project Admins) and Agents (Collaborators). If default members are empty, the entry-link creator joins as Admin.
3. Create an enabled entry link using that template. Set the title, description, message prompt, and optional expiry; save the public URL when it is shown once.
4. Test the URL in a separate browser profile with non-sensitive test input. Confirm the dedicated Project, initial message, guest access, and intended members before giving the URL to a client.

This template configures naming and membership. It does not install a Discover template's documents or Workflows. The guest joins as a Collaborator, and its browser login lasts 7 days with no guest re-login mechanism. Repeat submission creates another guest and Project, even with the same email. Plan GitHub-based Project membership for continuing work. Connected repo / client entry covers the complete setup and access limits.

Disabling a template or link stops new submissions; existing Projects remain. Rotate replaces a link's URL and invalidates its old one. Neither action migrates existing guests or extends their login. Keep the new-project intake controls separate from access management for work already underway.

Categories are shared across all listing kinds. Run aachat tag list (or aachat tag list --json) and choose 1–3 keys for the work it supports. If none fits exactly, choose the closest existing category and propose an addition to the operator. Unknown or retired keys are rejected on publication.