Skip to content

[VENTURE_NAME] — AI Operating Guide

This file explains how to behave in this repository. It is intentionally short and stable — it is not where project knowledge lives. It applies to any coding agent working in this repo (Claude Code, Codex, or otherwise) — this is the file coding agents read by convention, so project-wide behavior belongs here, not duplicated per tool.

All long-term project knowledge — product vision, architecture, design principles, coding standards, roadmap, feature backlog, decisions, glossary, open questions, and session history — lives in docs/ai/. Start there. docs/ai/README.md indexes every document and maps common task types to the file that's relevant, so you don't need to read the whole directory for every task.

Relationship to the governance repository

This is [VENTURE_NAME]'s implementation repository — it holds product code, not company or venture governance. Company-wide policy, standards, and [VENTURE_NAME]'s venture-level strategy/brand/domain standards live in the devonshire-digital governance repository, under ventures/[venture-slug]/. This repository's docs (docs/ai/) hold implementation-level facts: architecture, coding standards, shipped features, and implementation-level decisions. Material venture-level decisions made here (naming, monetization model, platform strategy, public product claims) must additionally be reflected back in the governance repository — do not let the two drift apart silently. See docs/decisions/ADR-0014-venture-implementation-repositories-are-the-default-pattern.md in the governance repository for why this split exists.

Brand assets (logos, marks, color systems) are designed and canonically owned in the governance repository, not here. This repository consumes finished exports (e.g. under public/brand/); it does not create or modify brand identity assets directly.

The governance repository's rule (per its ADR-0017) is: it governs the venture's existence — name, purpose, scope, target markets, legal structure. Everything about what the venture actually builds — product specifications, decisions, registry/lifecycle status, the product backlog, reusable-component content — belongs here, in this repository, not there.

Product registration

Every product built in this repository gets its own product.json under products/<slug>/product.json (or the equivalent top-level location for a non-Excel-workbook venture) — this is the authoritative registry record for that product: id, slug, display name, lifecycle_status, version, owner, and a status_note explaining current state. See the governance repository's schemas/product.schema.json for the expected shape.

The governance repository keeps a top-level portfolio/product-registry.json — a combined table of contents mirroring every venture's product.json files for company-wide visibility. Whenever a product is created here, or its lifecycle_status changes, update that governance-repo file in the same change (or immediately after) so it doesn't silently go stale. It carries no independent judgment of its own; this repository's product.json is always the source of truth if the two ever disagree.

Workflow Expectations

  • Before starting non-trivial work, check docs/ai/README.md for the doc(s) relevant to what you're touching.
  • When you learn or decide something durable — a new architectural decision, a shipped feature, a corrected assumption, a newly scoped feature — update the relevant file in docs/ai/ directly, not just local memory. Local memory is per-machine and invisible to other sessions; docs/ai/ is what keeps every session in sync.
  • Don't duplicate documentation. If something is already recorded in docs/ai/, update it in place there — don't restate it here or in a new file.
  • Before considering a change done, run this repository's lint/typecheck/build (or equivalent) commands — the same checks CI runs, since CI is the merge gate regardless of which agent produced the diff.
  • Do all work — solo or multi-agent — on a feature branch with a PR into the default branch; don't push directly to it. This gives every change a preview/CI run before it reaches production. The product owner reviews and merges each PR; an agent should not merge its own PR, even once CI is green.
  • Exception: a commit that touches only files under docs/ (or other non-code/non-config files with no runtime or build surface) — nothing else — may be pushed straight to the default branch. There's no preview deployment or CI check to gain from a PR when nothing built or deployable changed. If a commit mixes in even one code/config file, it doesn't qualify — split it instead.

Multi-Agent Workflow

More than one coding agent may work in this repo (e.g. Claude Code locally, a cloud agent elsewhere). To avoid clobbering each other's work:

  • One agent per branch. Don't run two agents against the same branch or working tree at the same time.
  • Each agent works on its own feature branch and opens its own PR. Don't have one agent broadly rewrite or "clean up" another agent's diff — ask for narrow, targeted review instead (bugs, regressions, missing tests, convention violations against docs/ai/coding-standards.md).

Report an issue about this page