Use AI as a Cratis maintainer

Cratis maintainers do not ask a general assistant to guess the framework. Each Cratis repository already carries the instructions and host adapters needed for its current development workflow. Your job is to start in the right repository, state the outcome, and require fresh verification before shipping.

Work from the repository root

1. Start the assistant in the repository you intend to change

   The root AGENTS.md identifies whether the repository is a Cratis application, framework, client, documentation site, or another supported profile. Profile selection matters: application vertical-slice rules do not apply to Chronicle, Arc, Components, or client-library source repositories.

2. Read project-owned context

   If the repository has project-specific context, preserve it. Current repositories may still use .agents/PROJECT.md; the controlled migration design uses .cratis/PROJECT.md with small host bootstraps. Never replace, concatenate, or copy another repository’s project context.

3. Ask for the outcome, not an implementation pattern

   Good requests name the behavior and constraints:

   • “Model the registration flow before implementation.”
   • “Add a strongly typed invoice number.”
   • “Diagnose why this projection stopped updating.”
   • “Review this change for Cratis architecture and security.”

   The matching skill chooses the Cratis workflow. If you know the skill, you can invoke it explicitly using your host’s skill picker or mention syntax.

4. Let the repository answer routine questions

   The assistant should inspect local rules, source, generated patterns, and specs before interrupting you. Stop only for product choices, unavailable authority, credentials, risky production actions, or genuinely conflicting evidence.

5. Require fresh gates

   Compilation is not behavior evidence. Run the repository’s current build, specs, lint, generated-file, and documentation gates. Re-run the failing gate after a correction.

6. Ship through a reviewed pull request

   Use logical commits, green CI, and the repository’s merge policy. When a task creates a new Cratis repository, register it through a linked Cratis/Strategy issue so Strategy can establish ownership, metadata, and AI setup with its own rules.

Common maintainer workflows

Intent	Skill or capability
Design unsettled commands, facts, streams, views, or reactions	event-modeling
Build a complete application behavior	new-vertical-slice
Add a command, read model, projection, reactor, reducer, or concept	The matching focused Cratis skill
Diagnose source behavior	diagnose-slice
Inspect a running Chronicle store	inspect-running-chronicle and the CLI
Review correctness, architecture, security, or performance	The matching review skill
Write product or site documentation	The Cratis documentation skills
Commit, push, open, monitor, and merge a PR	ship-changes

Skills guide the work; analyzers still enforce contracts

The AI workflow does not replace Arc or Chronicle analyzers, compiler errors, specifications, CI, or human review. It helps an agent reach the same gates a maintainer would use.

Do not propagate the corpus

Do not copy shared .ai, .claude, .github, .agents, or .pi trees from one repository to another. The old all-to-all propagation model is frozen because it created mixed versions, ownership ambiguity, and accidental fan-out.

The replacement model is:

1. author and approve canonical capabilities in Cratis/AI;
2. generate immutable, host-native artifacts into Cratis/AI.Distribution;
3. install or pin one reviewed version through the host or organization scope;
4. keep only project facts and minimal host bootstraps in the consuming repository;
5. canary updates, observe failures, and roll back by version.

Existing repository-local AI files remain in place until the replacement has real canary and rollback evidence. Do not delete them early, and do not restart legacy propagation.

Keep shared and project knowledge separate

Shared skills own Cratis conventions and reusable workflows. The consuming repository owns architecture decisions, commands, environments, credentials, fixtures, and verification details. That separation lets a shared package update without overwriting the facts that make one project different from another.

Read Trust and distribution for the complete boundary and Start using AI with Cratis for the public setup status.