Use AI as a Cratis maintainer

You maintain a Cratis repository (Arc, Chronicle, a client SDK, Components, the CLI, this documentation) and want an agent to do real work in it. The agent should not guess how the framework works; the repository already carries the instructions it needs. Your part is to start it in the right place, state the outcome, and insist on fresh verification before anything ships.

Work from the repository root

Start the assistant in the repository you intend to change

The root AGENTS.md (or CLAUDE.md) links to the repository’s own instructions and the installed Cratis rules. Profile selection matters: application vertical-slice rules do not apply to Chronicle, Arc, Components, or client-library source. A framework repository installs a cratis/engineering/<language> profile, for example:
Terminal window
```
cratis ai install \
  --harnesses claude,codex,copilot,cursor,opencode,pi \
  --profiles cratis/engineering/csharp,cratis/engineering/typescript,cratis/documentation \
  --languages csharp,typescript
```
Add a product profile such as cratis/arc or cratis/chronicle when you want that product’s skills as well. Choose Cratis AI profiles explains the split.
Read project-owned context

Project-specific instructions live in .cratis/ai/rules/project.md and the concern files it lists. Some repositories still carry a legacy .cratis/PROJECT.md; the installer can split it into the new layout. Keep that context in the repository you are working in. Never replace, concatenate, or copy another repository’s managed AI corpus.
Ask for the outcome, not an implementation pattern

Good requests name the behavior and the 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.”
A matching skill guides the workflow. If you know the skill or prompt, name it through your harness’s skill picker or slash command.
Let the repository answer routine questions

The assistant should inspect local rules, source, generated patterns, and specs before interrupting you. It should stop for product choices, missing authority, credentials, risky production actions, or evidence that genuinely conflicts.
Require fresh gates

Compilation is not evidence of behavior. Run the repository’s current build, specs, lint, generated-file, and documentation checks, and run the failing check again after a fix.
Ship through a reviewed pull request

Use logical commits, green CI, and the repository’s merge policy. When the work creates a new repository in the Cratis organization, prepare a Strategy intake proposal with the facts Strategy needs (purpose, owner, lifecycle, dependencies, release and security expectations). The proposal is a draft for a maintainer to route; an agent does not open, comment on, or link Cratis/Strategy issues on its own.

Common maintainer workflows

Skills are installed when a selected profile includes them; the marketplace plugins carry all of them. Prompts are installed with every managed profile.

Intent	Skill or prompt
Design commands, events, streams, views, or reactions before building	`cratis-chronicle-event-modeling`, or `cratis-screenplay-event-modeling` for a `.play` model
Build a complete application behavior	`new-vertical-slice` prompt
Add a command, read model, projection, reactor, reducer, or concept	`cratis-arc-command`, `cratis-chronicle-read-model`, `cratis-chronicle-projection`, `cratis-chronicle-reactor`, `cratis-chronicle-reducer`, `cratis-fundamentals-concept`; or the `add-projection`, `add-reactor`, `add-reducer`, `add-concept` prompts
Diagnose a stale read model or a stopped reactor	`cratis-chronicle-projection`, `cratis-chronicle-reactor`
Inspect a running Chronicle store	`cratis-chronicle-cli-operations`, `cratis-chronicle-mcp-inspection`, `cratis-cli-terminal-workbench`
Review correctness, architecture, security, or performance	`cratis-code-review`, `cratis-security-review`, `cratis-performance-review`; or the `code-review` and `review-pr` prompts
Write product or site documentation	`cratis-documentation-writing`, `cratis-engineering-docs-authoring`, `cratis-technical-examples`
Record an architectural decision	`cratis-engineering-decision-record`
Commit, push, open, monitor, and merge a pull request	`ship-changes` prompt

Do not propagate the corpus

Do not copy shared .cratis/ai, .claude, .github, .agents, or .pi trees from one repository to another. Copying created mixed versions, unclear ownership, and changes that fanned out by accident, so it is no longer done.

Shared guidance reaches a repository through one of three channels instead:

cratis ai install and cratis ai update, which copy the current main of Cratis/AI (or a --source checkout) and record the source commit and file hashes;
the @cratis/pi npm package, versioned per release; or
the native marketplace plugins, which carry skills only.

Change shared guidance in Cratis/AI through a reviewed pull request, then update consuming repositories through their channel. Roll back by reinstalling from a known-good commit with --source, or by pinning an earlier @cratis/pi version. Cratis AI distribution describes the channels in full.

Some repositories still carry repository-local AI files from before the managed install. Leave them in place unless a reviewed change retires them, and do not restart copying between repositories.

Keep shared and project knowledge separate

Shared skills own Cratis conventions and reusable workflows. The consuming repository owns architecture decisions, commands, environments, how credentials are obtained, fixtures, and verification details. Keeping them apart lets the shared corpus update without overwriting the facts that make one project different from another. Remove private or project-specific facts before you propose a reusable improvement to Cratis/AI.

Read Cratis AI distribution for the ownership rules and Start using Cratis AI for the setup steps.