The constitution — routing, ownership, non-negotiables

Adapted from the repo's CLAUDE.md — the operating constitution every agent session loads. Part of Internals: the platform's design set, published as content on the platform it describes.

Contract-first monorepo for a personal publishing platform — a file-based blog, branded bflo.sh: articles are Markdown files on disk (no admin panel), indexed and served on schedule by a read-only Laravel API and rendered by a Next.js reader front-end. Built by a Claude Code agent team. This file defines how work is routed, who owns what, and which rules are non-negotiable. The detailed design set lives in docs/ — read it before large tasks (reading order: docs/README.md).

Status (2026-07-07): the delivery roadmap (docs/master-blueprint.md §11) is complete — Phases 0–4 shipped and verified. Contract v0.8.1 (contract/CHANGELOG.md), ADRs 0001–0017 Accepted. Design of record: docs/master-blueprint.md; end-to-end technical tour: docs/how-it-works.md; day-to-day operation: docs/runbook.md. The repo was spun from a reusable contract-first template; the stack and tier model it fixed (ADR-0003/0004) are unchanged.

Stack (fixed — ADR-0003, ADR-0004)

Repository layout

Team roster

Roster is a starting point — adjust members, ownership, and responsibilities as the team and codebase evolve (update .claude/agents/, docs/team.md, and this file together; process in docs/team.md).

Full responsibility descriptions: docs/team.md.

Rules of engagement (non-negotiable)

1. Contract-first across members. contract/ is the source of truth for every cross-team interface. No member implements against an endpoint, payload, or event that is not published in contract/ and passing ddev contract-lint. Interface change flow: propose → contract-owner reviews/versions/publishes → consumers implement.
2. Tier direction holds between members. Dependencies point one way only: frontend → contract ← backend; within backend Http → Domain → Data (ports). Reverse or sideways edges are forbidden. Details: docs/rules-of-engagement.md.
3. Cross-tier work is coordinated via tasks/messages through contract-owner — never via direct cross-file edits. A member needing a change outside its ownership area files a task or message to contract-owner, who routes it to the owning member.
4. Ownership is exclusive. Each path has exactly one owning role; only the owner edits it.

Working agreement (autonomy & version control)

• Members are fully autonomous within their task: decide, implement, verify, and report outcomes faithfully — no permission-seeking mid-task. Escalate only genuine blockers.
• Never push to git. No member, workflow, or the lead may run git push under any circumstances.
• Commit only on explicit request from the user. Otherwise leave changes in the working tree and report them.
• UI feel needs the user's eyes. For interactive/visual frontend work (gestures, zoom, motion, modals, visual states), structural verification is necessary but not sufficient — hand off for the user's browser pass and hold the commit until they confirm, even under a standing commit-when-verified instruction.
• Destructive operations require an explicit user-approved task.
• Full agreement (incl. escalation and reporting rules): docs/working-agreement.md.

Orchestration model

The interactive session (you, the lead) is the orchestrator, not the primary implementer. Full playbook: docs/orchestration.md. Summary:

1. Route most build work through the roster (.claude/agents/). Decompose the request, then spawn the owning member with the Agent tool (subagent_type: <member>). Give spawned members stable names and continue them via SendMessage instead of respawning.
2. Use the Workflow tool for deterministic multi-member orchestration — fan-out, pipelines, contract-gate → parallel implementation → verify. Patterns and a reference script: docs/orchestration.md.
3. Track cross-member work as tasks/messages (TaskCreate / SendMessage), never as one member editing another member's files. Cross-tier coordination goes through contract-owner.
4. Use worktree isolation when members mutate files in parallel within the same tier.
5. Model & effort are assigned at dispatch time, not in agent definitions. Members inherit the session model/effort by default; the lead overrides per dispatch (lower tiers for mechanical work, higher effort for verification/arbitration). Policy: docs/orchestration.md.
6. The lead integrates results, verifies against the contract, and reports to the user.

Phase-start confirmation gate: at each delivery-roadmap phase boundary (docs/master-blueprint.md §11), the owning member(s) draft that phase's task list and the lead presents it for explicit user confirmation before any execution (from Phase 2 onward); on confirmation the lead runs the phase as a Workflow honoring each task's assigned model/effort (items 2 & 5). See docs/orchestration.md.

Do the work directly (no roster routing) only for trivial single-file edits, answering questions, or reading/reporting.

Definition of done & verify commands

Work is not "done" until its tier's verify passes and the outcome is reported — failures reported as failures, with actual output.

Plus, for any task: implementation conforms to the published contract version it claims to implement; no forbidden dependency edges introduced; relevant ADRs written or updated.

Frontend design quality (part of the frontend Definition of Done). Any frontend UI work — building new screens or reshaping existing ones — applies the frontend-design skill (.claude/skills/frontend-design/): a distinctive, subject-grounded visual point of view (deliberate palette, typography, and one signature element) rather than templated defaults, with copy treated as design material, all executed to the skill's quality floor (responsive to mobile, visible keyboard focus, reduced motion respected). docs/ui-ux.md is the normative design doc and encodes how the skill applies to this product; frontend UI work follows it and updates it in the same task when it deviates. "Renders correctly and passes verify" is necessary but not sufficient — it must also look intentional, not templated. For interactive/visual changes the user's browser pass is part of verification (see the working agreement above).

Environment & commands

Local runtime is DDEV-managed — a host-split topology (ADR-0010): the reader app at https://publishing-platform.ddev.site, the API at https://api.publishing-platform.ddev.site/v1 (production naming: bflo.sh / api.bflo.sh). Operational runbook — start, publish, troubleshoot: docs/runbook.md; topology source of truth: infra/README.md. Typical entry points:

Canonical docs

Index and reading order: docs/README.md.

• docs/architecture.md — tier model, backend layering, data flow, environments
• docs/master-blueprint.md — the product design of record: the publishing platform applied to the tier model, incl. the delivery roadmap (§11)
• docs/team.md — roster, responsibilities, ownership map, roster-evolution process
• docs/orchestration.md — agent-team orchestration, Workflow patterns, task/message protocol
• docs/rules-of-engagement.md — contract-first mechanics, tier direction, arbitration
• docs/working-agreement.md — autonomy boundaries, version-control rules, verification hand-offs
• docs/ui-ux.md — UI/UX definition + design system for the reader front-end (normative for all frontend work; applies the .claude/skills/frontend-design/ skill)
• docs/runbook.md — how to start, run, and publish on the stack day to day
• docs/how-it-works.md — end-to-end technical walkthrough (architecture + sequence diagrams)
• docs/adr/ — architecture decision records (start from adr/0000-template.md)