Clayers Onboard

Systematically create a complete clayers specification for main.

The goal: every meaningful code construct is described in the spec, mapped via artifact traceability, and verified clean by the tooling.

Prerequisites

1. clayers is installed: run clayers --version
2. Project is adopted: .clayers/schemas/ exists and clayers/main/index.xml exists. If not, run clayers adopt .

Mode Selection

• Fresh onboarding (default): start from the discovery phase
• Resume (--resume): check which acceptance criteria already pass and continue from the first incomplete mode
• Catch-up (--catch-up): query lyr:mode[@name="catch-up"] instead of onboard modes to fill gaps in an existing spec

Phase 1: Codebase Discovery

Before executing layer modes, build a mental model:

1. Scan the project tree: identify source directories, languages, build system
2. Catalog modules: for each directory/package, note its purpose
3. Extract domain concepts: identify domain terms from type names, function names, constants, comments (feeds into terminology layer)
4. Map dependencies: what depends on what (feeds into relation layer)

This mental model guides the layer mode execution that follows.

Phase 2: Layer Mode Discovery

Query the project spec for layers with onboard modes:

clayers query '//lyr:layer' clayers/main/
clayers query '//lyr:mode[@name="onboard"]' clayers/main/

Each lyr:layer describes a layer. Each lyr:mode[@name="onboard"] inside declares how to onboard that layer, including:

• lyr:requires: prerequisite layers
• lyr:condition: when this mode applies
• lyr:acceptance: success criteria
• pr:section body: step-by-step guidance

Phase 3: Topological Execution

Build a dependency graph from lyr:requires elements and execute modes in topological order:

1. For each mode in order:
   • Check lyr:condition against the project state. Skip if it doesn't apply.
   • Read the mode body (the pr:section inside contains the guidance).
   • Follow any pr:xref ref="tpl-*" links to templates in templates.xml for XML boilerplate.
   • Execute the guidance: create spec elements as instructed.
   • Validate: clayers validate clayers/main/
   • Check lyr:acceptance criteria.
2. If acceptance criteria fail: re-read the mode guidance and fix gaps before moving on.

Phase 4: Quality Iteration

After all modes execute, run the full quality suite:

clayers artifact --coverage clayers/main/
clayers connectivity clayers/main/
clayers artifact --drift clayers/main/
clayers validate clayers/main/

Targets:

• Coverage: zero unmapped nodes
• Connectivity: zero isolated nodes
• Drift: zero drifted mappings
• Validation: no structural errors

For any metric that fails, re-execute the relevant layer's catch-up or review mode. Iterate until all metrics are clean.

Reading Mode Guidance

To read a specific mode's guidance:

clayers query '//lyr:mode[@id="mode-trm-onboard"]' clayers/main/

The mode body contains a pr:section with detailed step-by-step guidance, template references, and anti-patterns. Follow it precisely.

Catch-Up Mode

When invoked with --catch-up, query for catch-up modes instead:

clayers query '//lyr:mode[@name="catch-up"]' clayers/main/

Execute the same phases 2-4, using catch-up modes instead of onboard modes. Catch-up modes typically focus on gap analysis and targeted fixes rather than full layer construction.