Cabloy Spec Generation

Cabloy Repository Specs

Create or maintain repository-native planning authority. Planning is not source implementation, acceptance evidence, ADR acceptance, or execution authorization.

Read before substantial generation or revision:

• references/repo-aware-discovery.md: edition, source discovery, and observed versus new target semantics;
• references/repo-specs-document-set.md: authority and proportionate document architecture;
• references/canonical-spec-input.md: canonical declarations, parser compatibility, and the three quality gates;
• references/traceability-and-status-rules.md: stable IDs, evidence, and authority-first updates.

1. Discover the active repository

Inspect the root, working tree, edition markers, root package.json, existing repo-specs/ indexes, relevant suite/module topology, and authored governance. Discover npm run vona / npm run zova command families when planning cites implementation commands.

• Exactly __CABLOY_BASIC__: use observed Basic scripts, UI, sites, flavors, and output paths.
• Exactly __CABLOY_START__: resolve those details from the active Start source; do not copy Basic examples.
• Both markers: stop; the checkout is invalid or ambiguous.
• Neither: inspect the owning package and nearby structure, then ask before edition-sensitive planning.

Cite inspected paths. Keep repository facts separate from user inputs, target design, and evidence. Never read or expose .env* contents to recommend worktree identity or ports.

2. Choose one planning mode

An existing directory is the normal incremental destination, not an automatic conflict. Ask about a conflict only for a genuine identity collision, parallel authority, or requested destructive replacement. Do not reset the directory or regenerate the whole baseline by default.

A growing business domain defaults to the complete baseline. Ask before choosing lightweight scope. Do not invent requirements to fill omitted documents.

3. Resolve identity without changing the workflow

For unresolved provider/suite/module naming, route to cabloy-domain-planning with a naming-only return to generation. Validate the returned names and resume this mode and its confirmation gate. Naming confirmation does not authorize source scaffolding.

For suite-first ownership, the short name is {providerId}-{suiteName}; suiteName uses lowercase English letters only, without another hyphen. Use capability names for modules. Reuse the stable existing suite/capability planning slug rather than creating a competing hierarchy.

4. Resolve only missing site strategy

First inspect active shared-site composition owners, extension points, independent-site conventions, and framework constraints. A capability module or an Admin audience alone does not require an independent site.

• If both Web and Admin strategies are unresolved, evaluate them separately, recommend contextually, and present one single-select decision: shared/shared, independent/shared, shared/independent, independent/independent. Keep Other for custom/no-site/deferred choices.
• If only one audience is in scope or unresolved, ask only about that audience.
• If an established strategy already governs the requested change, preserve it; do not repeat the four-way question absent a material change.

Choosing strategy confirms only that input. It does not accept an ADR or approve implementation.

Classify every target as observed existing, proposed new, or explicitly approved new under the discovery reference. Shared integration requires an observed owner. A proposed independent tuple may be designed before its source exists: validate framework constraints and collisions, obtain explicit design approval, and retain its governing ADR as Proposed until separately accepted. An explicitly approved new tuple with an Accepted ADR can be created by a bounded execution task; source pre-existence is not a prerequisite.

Unknown or unchecked values stay TODO(confirm) with the exact missing design/source/conflict check. Block only dependent site/frontend implementation; keep backend, unrelated audiences, and runnable discovery tasks actionable.

5. Collect the remaining inputs

Ask only for missing inputs in a compact clarification pass:

• identity/output path, outcomes, personas, journeys, scope, exclusions, and acceptance;
• modules and reused persistence/identity owners; audience strategy and target classification;
• tenant, server-authoritative identity/authorization, privacy, lifecycle, transactions, concurrency, idempotency, audit, integrations, and migration/version decisions where material;
• dependencies, release constraints, contract-loop checkpoints, test levels, fixture cleanup, proof/redaction, and optional records;
• durable decisions, ADR candidates, and unresolved gates.

Label recommendations as proposals. A request for comprehensiveness is not permission to invent security or business decisions.

6. Confirm generation scope

Before writing, present the edition/root, mode, identity/path, intended ownership, outcomes/scope, site strategy/target tuple classification, affected records, justified omissions/extensions, unresolved gates, and initial status/evidence policy. Include planned chart eligibility and README language.

Keep three approvals separate:

1. Generation approval authorizes the named planning edits only.
2. Design/ADR approval explicitly approves a durable decision; record Accepted only for the decision actually accepted. A tuple design approval is not source-existence proof.
3. Execution approval belongs to a bounded WBS dossier in cabloy-spec-execution.

Do not treat silence, strategy selection, naming confirmation, or generation approval as another approval. Drafts retain Proposed ADRs and controlling TODO(confirm) gates.