create-canopy-project

Scaffolds the Canopy Method into a project root.

create-canopy-project (binary: canopy-init) drops a working Canopy Method scaffold into any directory in seconds. It writes the .canopy/ skeleton, the complete docs/methodology/ directory (10 docs covering the 9 primitives), and a method-aware CLAUDE.md agent guide. Then it offers a 5-minute interactive tutorial walking through the five base primitives (Outcome / Decision / Context / Issue / Signal).

Quickstart

npx create-canopy-project my-app
cd my-app

Or, install globally:

npm i -g create-canopy-project
canopy-init my-app

What gets scaffolded

| Path | Purpose | |---|---| | .canopy/PROJECT.md | Project intent + requirements (Validated / In Flight / Pending / Deferred) | | .canopy/ROADMAP.md | Milestones + Phases | | .canopy/STATE.md | Current Outcome + Stage + session continuity | | .canopy/MILESTONES.md | Shipped milestone log | | .canopy/REQUIREMENTS.md | Testable requirements | | docs/methodology/ | The 10 canonical Canopy Method docs (METHOD, OUTCOMES, DECISIONS, CONTEXT, BUGS, FLOW-AND-SIGNAL, INVARIANTS, INITIATIVES, CROSS-CLAN, LIVING-PROCESS, plus VOCABULARY / PORTFOLIO / TEMPLATE-primitive / MIGRATION-clan-alpha-to-canopy / CLAUDE.md) | | CLAUDE.md | Thin agent-guide pointer with the <!-- canopy-init:start --> marker block |

The CLI deliberately does NOT scaffold .jungle/, .brain/, or .clan-alpha/ — those belong to the Jungle ecosystem and are a separate concern.

Sibling product: canopy-cc

create-canopy-project and canopy-cc are sibling npm packages with distinct jobs:

• create-canopy-project (this) — scaffolds the methodology + project skeleton into a directory. For human teams adopting the method.
• canopy-cc — installs slash-commands into AI coding agents (Claude Code, OpenCode, Gemini, Codex). For AI agents operating in a Canopy project.

They're designed to be used together: one developer runs npx create-canopy-project my-app to scaffold; everyone (humans + AI agents) then operates against the same docs/methodology/ source of truth.

Idempotency

Re-running the CLI on an existing Canopy project is safe:

canopy-init --update     # diff bundled docs vs local, prompt to update
canopy-init --update --yes   # auto-accept all updates

Behavior:

• docs/methodology/*.md — diffed against bundled version; user chooses per-file whether to update.
• .canopy/*.md — never overwritten. Missing template files are created.
• CLAUDE.md — only the content between <!-- canopy-init:start --> and <!-- canopy-init:end --> markers is updated. Project-specific content before/after the markers is preserved.

Flags

| Flag | Effect | |---|---| | --yes, -y | Accept defaults; skip prompts. | | --no-tutorial | Skip the 5-minute interactive tutorial. | | --tutorial | Run only the tutorial (against an existing Canopy project). | | --update | Update an existing Canopy project to the latest method docs. | | --dry-run | Show what would be written without modifying files. | | --version, -v | Print version and exit. | | --help, -h | Print usage and exit. |

The 5-Minute Tutorial

After scaffolding, the CLI offers a 5-minute interactive walkthrough of the 5 base primitives:

1. Outcome — a result that delivers value
2. Decision — a choice that needs to be made
3. Context — captured knowledge
4. Issue — a defect or gap
5. Signal — progress visibility

Each primitive includes a definition, two examples, a vocabulary callout ("if you know Scrum: X is closer to Y; we don't say Z"), and one multiple-choice quiz. The 4 v2.0 primitives (Invariant, Initiative, CrossClanDependency, LivingProcess) are introduced in the wrap-up screen with pointers to the full docs.

Updating Bundled Docs (Monorepo Maintainers)

The CLI bundles docs/methodology/*.md and scripts/check-vocabulary.cjs from the root of this monorepo. When you change those source-of-truth files, re-run the sync:

pnpm sync:cli-templates

The CI gate scripts/check-cli-bundle.cjs fails the build if you forget. It runs as part of npm run check:all.

Local Development

pnpm install
pnpm --filter @canopy/cli build
node packages/cli/dist/index.js --help

The internal workspace name is @canopy/cli; the published name is create-canopy-project (via publishConfig.name).

License

MIT. See LICENSE.