Generate a Cabloy Suite Specification

In Claude Code, describe the business capability you want to plan:

/cabloy-spec-generation <business description>

For example:

/cabloy-spec-generation Plan a multi-tenant equipment-maintenance suite for technicians and operations managers, with work orders, asset history, role-based access, and an Admin dashboard.

You do not need to provide every product or technical decision in the first prompt. Cabloy AI inspects the active repository, asks focused questions, recommends boundaries where needed, and shows a confirmation summary. It generates or updates the suite specification set only after you explicitly approve that summary.

A specification set establishes product intent, technical contracts, delivery structure, acceptance procedures, and decision history. It does not prove that application code, generated artifacts, tests, or acceptance evidence already exist.

This guide is the planning half of AI Spec-Driven Development. It explains the visible workflow; the cabloy-spec-generation Skill retains the detailed procedural checks that operate it.

When to use it

Run /cabloy-spec-generation <business description> when you want to:

• establish a new long-lived business suite and its PRD, SRS, WBS, test plan, progress register, and initial ADR
• update an existing suite's requirements, contracts, scope, delivery plan, or acceptance planning
• turn confirmed product intent into traceable delivery and acceptance records before implementation

Use a different path when the task is already an approved bounded WBS increment, direct backend or frontend implementation, or Vona/Zova contract synchronization. If the provider, suite, or capability identity is still unresolved, AI guides that decision before it creates a competing suite hierarchy.

What happens after you invoke it

1. AI checks the current repository. It detects the active Cabloy edition, reads the relevant repository guidance and existing suite records, and distinguishes observed source facts from your confirmed decisions, proposals, and unresolved items.
2. AI identifies the planning scope. It chooses a complete new baseline, incremental maintenance of an existing set, or explicitly approved lightweight planning. An existing directory is normally the update destination, not a conflict or reset request. Basic and Start share the model, but runtime details come from the active edition. Both edition markers mean stop; if neither marker is present, inspect the owning package/structure and ask before edition-sensitive planning.
3. AI asks focused questions. You provide only the decisions that are needed to make the plan coherent. AI can recommend a boundary, but it identifies a recommendation as a proposal rather than treating it as confirmed input.
4. AI presents a confirmation summary. The summary states what will be created or changed, what remains unresolved, and which decisions or WBS branches remain gated.
5. You approve or revise the summary. No specification file is generated, replaced, or treated as approved merely because a question was asked or left unanswered. A confirmation to generate records also does not accept a durable ADR; a decision remains proposed until it is explicitly accepted.
6. AI generates or updates the set. It links the planning records, preserves traceability and stable identifiers, refreshes applicable derived planning views, and reports the resulting files, unresolved decisions, and next workflow.

What you may be asked to confirm

The initial business description can be short. During the conversation, AI may ask you to confirm:

• the business outcome, audiences, in-scope capabilities, exclusions, and deferred scope
• suite identity, capability ownership, and the target repo-specs/<suite>/ directory
• the Web, Admin, or other site strategy that current source and confirmed requirements support
• persistence, ownership, tenant, authorization, privacy, lifecycle, migration, and integration constraints
• delivery, release, and verification expectations
• unresolved durable decisions, the WBS branches they block, justified optional records, and the initial delivery status

AI asks only for missing decisions. If the existing strategy still governs, it does not repeat a Web/Admin four-way choice; a single unresolved audience gets a focused question. Unresolved naming takes a naming-only detour through cabloy-domain-planning, then returns here without scaffolding.

Existing facts and new designs

Targets have three distinct states:

• Observed existing: source/configuration was inspected and cited. Shared-site integration requires an observed owner.
• Proposed new: a deliberately new design, not a claim that source already exists.
• Explicitly approved new: the concrete tuple passed framework-constraint and collision checks, you explicitly approved the design, and its governing ADR is Accepted.

For a new independent SSR site, validate site ID, public path, flavor, configuration ownership, site module/registration, copied bundle, generated REST package, and paired SSR/REST commands together. The target need not exist before approval: a bounded execution task may create an explicitly approved new tuple after its own dossier approval. Unknown or unchecked values remain TODO(confirm); they block only dependent work. A new wrapper is a planned addition, not a current command to run. See Independent SSR Site and Flavor Setup.

Keep approval domains separate: approval to generate records does not accept a durable ADR or authorize source execution. Site-strategy selection approves only that input; design/ADR acceptance and bounded execution approval remain explicit.

What gets generated or updated

For a new long-lived suite, the normal core set is:

repo-specs/<suite>/
├── README.md
├── prd.md
├── srs.md
├── pdp-wbs.md
├── test-plan.md
├── progress.md
├── implementation-gantt.svg
├── implementation-burndown.svg
└── decisions/
    └── 0001-*.md

Record	What it provides
README.md	Index, reading order, topology summary, and authority map
prd.md	Product outcomes, audiences, scope, journeys, and business rules
srs.md and accepted ADRs	Technical contracts and durable decisions
pdp-wbs.md	Bounded delivery work, dependencies, completion checks, and applicable Contract Loop checkpoints
test-plan.md	Acceptance procedures, expected proof, and release gates
progress.md and charts	Derived delivery status and planning views, not upstream authority

Charts are generated only after complete supported README/WBS/ATP/progress inputs exist. A deliberately lightweight set agrees on selected records and omissions instead of forcing a complete baseline or charts. AI adds presentation contracts, rollout records, runbooks, extra ADRs, or evidence only when justified; it never creates empty evidence to imply execution.

For an existing suite, the workflow updates the owning upstream authority before dependent records. It preserves existing identifiers, accepted decisions, history, and evidence conventions rather than silently overwriting them or creating a parallel planning set.

Change or add requirements

Use the same Skill whenever an existing suite needs a changed requirement or a new capability. Describe the requested change in Claude Code:

/cabloy-spec-generation <changed or new business requirement>

AI reads the existing specification set, identifies the product, contract, decision, WBS, acceptance, and progress records affected by the change, then asks you to confirm the revised scope and any new boundaries. It updates the upstream PRD, SRS, or proposed/accepted ADR before it updates dependent WBS, ATP, progress, and derived-chart records.

If the change affects an approved or in-progress increment, return to planning first. Confirm the revised authority and delivery boundary before resuming execution; do not use an execution handoff or source workaround to redefine the requirement or contract.

How traceability and evidence work

Cabloy connects the specification set through Traceable Spec Delivery:

PRD → SRS → WBS → ATP → Evidence

A product or technical change belongs in its PRD, SRS, or accepted ADR before its WBS, acceptance, progress, evidence, and chart implications are updated. A progress entry or chart cannot introduce a requirement, resolve a contract conflict, or accept an ADR.

Planning records and derived charts do not establish implementation-complete or verified. verified requires the applicable acceptance procedure and retained, redacted observed evidence. A generated plan, planned command, scaffold, screenshot, or unrelated check is not automatically sufficient proof.

Check planning without claiming implementation

Use three independent gates:

1. Planning authority audit checks formal definitions, exact references, declared PRD → SRS → WBS → ATP associations, and local links:

   npm run spec:check -- <suite>
   # Only for explicitly limited planning scope:
   npm run spec:check -- <suite> --lightweight

   Lightweight mode reports omitted owners/chain coverage; it does not permit dangling references. If progress is present, its WBS owner is still needed.

2. Chart model/freshness checks supported WBS/dependency/ATP/progress consistency and generated-view freshness, only with complete supported inputs:

   npm run spec:charts -- <suite>
   npm run spec:charts:check -- <suite>

   Regenerate after WBS, test-plan, progress, or README title/language changes. With incomplete lightweight/legacy inputs, report the precise chart gap; do not invent business definitions or status to make a generator pass.

3. Human approval/evidence review retains ADR acceptance, controlling TODOs, bounded execution approval, and observed ATP proof as separate requirements. Neither static check approves a design or establishes verified.

New specs use atomic - **PRD-...**: <body> / - **SRS-...**: <body> declarations, phase/task WBS headings with explicit Dependencies, Traceability, Tasks, and Acceptance checks, and ### ATP-...: <title> scenarios under ## Acceptance Scenario Catalogue with Setup, Procedure, Expected result, Minimum proof, and Traceability. Resolve progress columns by WBS ID and Status headers rather than fixed positions. Compatible legacy catalogue tables remain supported; matrices and evidence are not definitions. Report legacy gaps without silently rewriting business meaning. See Repo Scripts for the active deterministic command contracts.

What happens next

After the specification set is coherent and one bounded WBS increment is approved, execute that increment in Claude Code:

/cabloy-spec-execution <WBS-ID>

Choose one named WBS item, or an explicitly approved finite phase with a closure boundary. Do not use execution to implement an entire suite automatically or to resolve an upstream product, contract, dependency, scope, or durable-decision conflict; return to planning when those records need to change.

Further reading

• AI Spec-Driven Development for the authority and evidence model
• Execute an Approved Cabloy Specification Increment for bounded implementation, verification, evidence, and progress handoff
• Docs, Skills, Rules, and CLI Mapping for the boundary between public guidance, skills, suite records, and internal rationale
• Repo Scripts for the derived-chart input contract and manual chart commands