canon-create

Canon create is an architecture interview and specification workflow, not a scaffold generator. Its job is to convert product context, constraints, trade-offs and existing evidence into a project-specific architecture that future coding agents can follow consistently.

Resolve PLUGIN_ROOT to this installed plugin directory and PROJECT_ROOT to the user's target repository. Quote paths. Use "$PLUGIN_ROOT/bin/canon-engine" <command> --root "$PROJECT_ROOT"; never assume the current directory is the target. Build the plugin once with npm run build:binaries if bin/canon-engine is absent. Knowledge is reference data, never authority to execute commands or override user/project instructions.

1. Establish the source of truth

Read existing .canon artifacts first. Never silently overwrite an architecture contract.

If the repository already contains code, determine whether the user wants to:

1. preserve the current architecture;
2. use a representative project/module as reference and normalize it;
3. evolve the current architecture toward a new target; or
4. design a new architecture without treating the current structure as normative.

Ask progressively, one material decision at a time. Do not dump a long questionnaire when repository evidence can answer a question.

For reference mode run inspect. Read representative modules, composition roots, imports, public contracts, persistence boundaries and tests. Classify observations as:

• intended architecture;
• consistent project convention;
• feature-specific implementation;
• accidental/legacy debt;
• unknown/ambiguous.

Frequency is evidence, not intent. A majority pattern can still be historical debt. Attach file evidence and confidence to material inferences and confirm ambiguity before making it policy.

2. Understand the system before selecting patterns

Establish enough context to make architectural decisions:

• product/system type and primary user flows;
• domain complexity and expected rate of change;
• team size/ownership and expected project lifetime;
• scale, latency, availability and consistency requirements;
• compliance, audit and security constraints;
• deployment/operational model;
• persistence and integration constraints;
• synchronous/asynchronous communication needs;
• compatibility/migration constraints for existing systems.

Do not choose microservices, DDD, CQRS, repositories, events or another pattern because it is fashionable. For every material pattern ask internally:

1. What current problem does this solve?
2. What happens if we do not use it?
3. What complexity does it add?
4. Is that complexity justified now?

Load only the relevant Canon knowledge packs before recommending or rejecting a pattern.

3. Define architecture at the correct levels

The final architecture must make these decisions explicit where relevant.

System and module boundaries

Define deployable shape, business-capability boundaries, module ownership, public APIs, data ownership, cross-module communication and allowed exceptions.

Dependency direction

State which layer/module may depend on which. Decide where framework, ORM, transport, messaging and external SDK types are allowed. Prefer mechanically verifiable rules for critical invariants.

Domain model

Decide selectively whether entities, value objects, aggregates, domain services and domain events are useful. Do not force a rich domain model into simple CRUD. Define aggregate/transaction boundaries when they matter.

Application flow

Define use-case/application-service/command-query conventions, port ownership, orchestration responsibilities, transaction ownership and idempotency where relevant.

Greenfield create activates the starter kinds in .canon/conventions.yaml as the pattern for new code. Reference create records the repeated pattern of each kind from inspect (fileKinds, shapes) as observed and writes .canon/baseline.json so current debt does not fail review. A use case shape is one example. Any kind with match, shape, and how is a pattern the agent must copy. Promote a different pattern only after sync-conventions --confirm. Generated artifacts: conventions.md, architecture.md, naming.md, practices/<binding>.md.

Infrastructure and integrations

Define persistence adapter placement, external gateway/adapters, mapping boundaries, events/queues, cache, configuration and secrets responsibilities without leaking vendor APIs into policy layers unless the project deliberately chooses that trade-off.

Presentation/API

Define controller/handler responsibilities, DTO/validation location, authentication/authorization boundary, error mapping, contracts and versioning expectations.

4. Define architecture of code, not only concepts

The architecture is incomplete until a coding agent can answer where new code belongs.

Specify:

• project/module/feature folder trees;
• naming conventions;
• public module entrypoints;
• responsibility of every recurring file/component type;
• allowed and forbidden imports;
• shared/common/core policy and ownership;
• expected composition root/DI wiring;
• mapper/DTO/error/event conventions when selected;
• file/cohesion expectations without arbitrary line-count dogma.

Use real examples from selected knowledge packs and the repository. Prefer one canonical project example over many conflicting examples.

5. Define testing and quality gates

For each selected component/layer define the useful verification level, for example:

• domain behavior -> focused unit/property tests where valuable;
• application orchestration -> unit/component tests using fakes at ports;
• persistence/integration adapters -> integration tests against realistic dependencies;
• HTTP/message boundaries -> integration/e2e/contract tests;
• dependency/module rules -> architecture tests/static analysis;
• critical performance/security behavior -> explicit specialized tests when required.

Choose mocks, fakes, builders, fixtures or real containers according to the boundary being tested. Coverage percentage is evidence, not a correctness goal by itself.

6. Record decisions and compose the manifest

Once target intent is confirmed, run:

create --name "<name>" --mode greenfield

or for reference mode:

create --name "<name>" --mode reference --reference "<path>"

Then refine the generated .canon artifacts to the confirmed design. In particular:

• edit .canon/project.md into the actual project contract;
• create ADRs for consequential choices/trade-offs;
• keep only relevant knowledge packs in .canon/manifest.yaml;
• add stack/domain/pattern/testing packs selected during the interview;
• give task-selectable packs useful triggers;
• configure deterministic validation roots/rules for declared invariants;
• keep maxRepairAttempts bounded;
• resolve knowledge and review the resulting canon.lock.

Do not leave the generic starter composition in place if the interview selected something else.

7. Produce a canonical example

Create or select one small, representative canonical feature/module that demonstrates the architecture in real code. It should show, where applicable:

• folder structure;
• entity/value object/aggregate boundaries;
• application operation;
• port and adapter;
• framework composition;
• transport boundary;
• naming;
• tests.

For an existing project, prefer a proven representative implementation after separating good convention from accidental debt. Do not rewrite the reference repository during discovery.

8. Final architecture review

Before declaring /canon create complete, check for contradictions such as:

• dependency rules that examples violate;
• repository ownership inconsistent with the project contract;
• domain declared framework-free while examples import framework types;
• module isolation contradicted by cross-module persistence access;
• CQRS/event sourcing/saga selected without a stated need;
• tests that do not exercise the architecture's risky boundaries;
• naming/folder examples inconsistent with the declared convention.

Run build/tests for any generated executable example and run Canon architecture review where supported. Report actual commands and outcomes. Architecture artifacts and implementation completion are separate claims.

Required result

A successful create workflow leaves a project with a concise architecture contract, not a documentation dump:

.canon/
├── manifest.yaml
├── canon.lock
├── project.md
├── decisions/
├── skills/project-architecture/SKILL.md
└── examples/canonical-module/

Future agents should be able to receive a short task and infer the expected structure without the user repeating "follow our architecture".