The Canopy Method
← The Method

CLAUDE.md — Canopy Method for AI Coding Agents

This file is the entry point for AI coding agents operating in a Canopy Method project. Read this file first. Then read the linked docs in the order presented. Vocabulary discipline: see VOCABULARY.md. Drift is a method failure.

How This Works

This project uses the Canopy Method — a development methodology that replaces Scrum with Outcomes, Decisions, Context, Issues, Signal, and the four v2.0 primitives (Invariant, Initiative, CrossClanDependency, LivingProcess). You are not just a code generator — you are an agent operating within a methodology.

Before writing any code, creating any file, or making any change:

  1. Read the relevant Context
  2. Check for blocking Decisions
  3. Understand which Outcome you're working toward
  4. Honor any linked Invariants
  5. Know which Flow stage the work is in (Define / Build / Review / awaiting_approval / Ship / Done)

Canonical Docs (read in this order)

File What It Contains When to Read
METHOD.md The complete Canopy Method — 9 primitives in 15 minutes Once, to understand the methodology
VOCABULARY.md Preferred terms + banned terms + enforcement Once, then refer continuously
OUTCOMES.md Writing Outcomes (incl. v2.0 kind / is_retroactive / blocked_on) When creating or refining Outcomes
DECISIONS.md Identifying and resolving Decisions (incl. multi-Alpha coalition variant) When a choice needs to be made or a block is identified
CONTEXT.md Capturing and using project knowledge When writing Context or before building
BUGS.md The Issue primitive with v2.0 diagnostic_state vocabulary When filing or working on bugs
INVARIANTS.md Enforced standing constraints When discovering a constraint that applies to all work
INITIATIVES.md Cross-cutting groupings between Outcome and Phase When work spans multiple Outcomes as a coherent subsystem
CROSS-CLAN.md Paired-lifecycle entities for cross-clan work When work depends on or affects another clan
LIVING-PROCESS.md Always-on agents / services where the running process IS the product Council-tier only
FLOW-AND-SIGNAL.md Flow stages (incl. awaiting_approval) + reporting surfaces When transitioning stages or generating reports
PORTFOLIO.md One-line context per real-portfolio clan referenced in examples When examples reference clan names

Cross-Cutting Agent Rules

These rules apply across all modes. The detailed semantics live in the docs above; this is the agent contract.

  1. Vocabulary is non-negotiable. Use the preferred terms from VOCABULARY.md. If you catch yourself typing "task" or "ticket" or "story", stop and use the preferred term. npm run check:vocab enforces this.

  2. Context before code. Never write code without reading the linked Context first. If Context is missing, write it before building.

  3. Surface Decisions, don't pick alone. When you encounter a choice, frame it as a Decision per DECISIONS.md, present alternatives with reversibility, and ask the human to decide. Do not pick silently.

  4. Outcomes are results, never tasks. Write Outcomes as "X can do Y" or "System does Z" per OUTCOMES.md. If you find yourself writing "Build X," stop and ask what's true when it's done.

  5. One owner per Outcome. Never assign to "the team" or multiple people.

  6. Three priorities only: Now / Next / Later. If asked for P0/P1/P2 or Critical/High/Medium/Low, map them.

  7. Honor Invariants. Before shipping any Outcome, check whether any linked Invariants would be violated. If yes, fail and surface the violation rather than shipping.

  8. Respect approval gates. If Outcome.gate.required = true, do not move to Ship. The Outcome goes to awaiting_approval. Per-Outcome override (Outcome.gate.override = true) is allowed during Claude Code sessions but must be recorded with reason.

  9. File CrossClanDependencies, not informal asks. If your work depends on another clan, file a CrossClanDependency entity (see CROSS-CLAN.md) — do not send a Jungle message and hope. Jungle MCP syncs the entity so both clans see the same state.

  10. Use the full diagnostic vocabulary for Issues. triage / investigating / likely_resolved / awaiting_evidence / misdiagnosed / not_our_bug. OPEN/IN_PROGRESS/DONE is too coarse. See BUGS.md.

  11. Don't replicate observability for LivingProcess. Link out to Grafana / Datadog. See LIVING-PROCESS.md.

When You Disagree With This File

If a doc in this directory contradicts this file, the doc wins. This file is the index; the docs are the spec.

If a project-specific CLAUDE.md or .canopy/ instruction contradicts this file, follow the project-specific guidance — but flag the conflict so the methodology can be updated if needed.

Source

This file is part of the Canopy Method methodology docs. Origin: v2.0 (2026-05-24) per docs/methodology/validation/DECISIONS-RESOLVED.md.