Project Model
What you'll learn
- What a project profile is and why Craik builds one for every repository it touches.
- The boundary distinction between mutable docs and immutable evidence.
- What
craik onboardemits and how runners consume it. - How project state changes propagate to case files and handoffs.
Project profile
The runner-readable view Craik builds from a registered repository. It combines local configuration, repository state, documentation boundaries, memory backend posture, policy posture, and known continuity records into a single typed object every Craik component speaks.
The project profile is operational, not descriptive. It tells an agent — human or model — concrete things it can act on:
- Which repository is being entered.
- Which docs are mutable.
- Which paths are immutable evidence.
- Which memory backend is configured.
- Which tasks and handoffs already exist.
- Which contradictions still need review.
- Which validation commands are expected.
- Which next actions are currently allowed.
When Craik builds a case file or a runner prompt, the project profile is the substrate every other layer is drawn against.
Mutable docs vs immutable evidence
Project profiles draw a clear line between documentation an agent may edit and evidence that should never be overwritten.
Mutable docs
README.md, files underdocs/, and other configured doc roots.- Loaded into the case file as context.
- Edits are allowed when the policy envelope grants write authority.
- Touched by agents producing PRs, drafts, or reconciliations.
Immutable evidence
- ADR directories (
docs/adr/) and any path explicitly marked immutable in the project profile. - Loaded into the case file as evidence.
- Edits require a separate, explicit policy grant.
- Used by agents to justify decisions, not to mutate them.
This is the line that keeps a "doc reconciliation agent" from silently overwriting an ADR while updating the surrounding guides.
What craik onboard emits
craik onboard --project <project-id-or-name> prints a
craik.agent_onboarding payload — the canonical, machine-readable
introduction a runner sees on every task.
craik onboard does not probe external services by default. Stigmem
status reports whether the project is configured for Stigmem and whether
connection environment variables are present — it never prints credentials.
Inspecting a project
craik project listList all registered projects with their ids, names, and Git heads.
craik project show <name-or-id>Print the full project_profile JSON.
craik onboard --project <name-or-id>Print the craik.agent_onboarding payload — what a runner sees first.
How updates propagate
The project profile is the canonical source for case files, intent locks, and onboarding payloads. When you change a project — register a new immutable path, configure a memory backend, add validation commands — the next case file build reflects it. Existing handoffs aren't rewritten; they stay faithful to the project state at the time the run ended.