factory-init

What this skill does

factory-init orchestrates the unified brownfield bootstrap: one command that reverse-engineers an existing codebase onto all three project-memory layers and measures how well they align with the code.

It coordinates the leaf lifecycle skills directly — product-init, product-clarify, product-implement, product-analyze, architect-init, architect-clarify, architect-implement, architect-analyze, change-init, change-clarify, change-publish — never the peer orchestrators factory-intent / factory-learn.

Its own final step, the sweep, is the only cross-layer analysis in the factory: it builds the coverage matrix (.adlc/coverage/coverage.md) — a feature-area pivot plus the four traceability relations PDR↔ADR, PDR↔code, ADR↔code, ChDR↔code — and diffs it against the previous sweep to detect drift.

It operates as a Kind-A DAG orchestrator in alignment with the shared executor engine contract in factory-runbook/references/executor.md.

Requires: the factory-runbook skill (provides the shared executor contract): adlc-cli skills add tikalk/adlc-team-skills --skill factory-runbook

Scope boundary: project-local memory only (PDR, ADR, ChDR + code). Team context directives (CDR / team-init) are NOT bootstrapped here — they publish to the external team-ai-directives repo and are owned by factory-learn. The sweep's final output includes a prose recommendation to run factory-learn / /team-init for reusable patterns spotted during bootstrap.

When to use

• You adopt ADLC on an existing repo (code exists, no/partial PDRs, ADRs, ChDRs) and want the full bootstrap in one run.
• You want a recurring cross-layer alignment audit (--refresh): which decisions are undocumented, which code is undecreed, where product and architecture disagree.

When NOT to use:

• Greenfield / empty project → run factory-intent (specify routes) instead.
• Single-layer work → factory-intent / factory-learn directly.
• CDR / team-directives contribution → factory-learn.
• Feature implementation → factory-mission.

Route Classification

Per-layer skip — each track classifies independently; a layer whose memory AND compiled artifact both exist skips its init/implement and runs only its analyze:

Lifecycle DAG & Step Resolution

factory-init implements a fixed named-skill DAG (fixed step resolution). Tracks run sequentially — each track completes before the next starts. Rationale: the human gets one coherent review session per domain; architect-clarify reads the accepted PDR decisions as context (architecture serves product); the sweep receives the most mature inputs.

Bootstrap Route (12 steps, 3 clarify gates + final matrix review)

Refresh Route (1 step + loop)

Correction Loops

• product-analyze / architect-analyze CRITICAL/HIGH → route back to their own track's clarify⭐ (executor default, bounded by max_corrections, default 2).
• sweep CRITICAL/HIGH findings route by layer tag : every finding carries [layer: product|architecture|change|cross] and routes to the matching track's clarify (product-clarify / architect-clarify / change-clarify). cross findings route to the track owning the cited record; ambiguous → halt for the human (hybrid gate). Bounded by max_corrections.

The Sweep Step (inline composite step)

The sweep is executed by this orchestrator (step skill: factory-init, prompt = this section), not by a leaf skill.

Inputs (all read-only)

| Source | Yields | |--| | product-init + architect-init setup scripts (re-run; idempotent JSON scanners) | sub-systems, feature-areas, tech stack | | docs/adlc/memory/{pdr,adr,chdr}/ (legacy .adlc/memory/ fallback, + indexes) | accepted decisions per layer | | docs/adlc/product/PRD.md, docs/adlc/architect/AD.md | compiled artifacts | | .adlc/coverage/coverage.md (if exists) | previous matrix → drift diff |

Output: .adlc/coverage/coverage.md (+ history/<date>-<run_id>.md)

1. Pivot: Area Coverage — row axis is the union of sub-systems ∪ feature-areas, reconciled by name/directory overlap with a mapping column; unreconciled rows stay separate and are flagged. Every cell cites evidence (record IDs, file paths) — no fabricated cells.

## Pivot: Area Coverage

| Area | Feature-Area | Sub-System | PDRs | ADRs | ChDRs | Code Evidence | Coverage |
|------|--------------|------------|------|------|-------|---------------|----------|
| payments | billing | payments | 3 | 1 | 4 | present (src/payments/) | 62% |

2. Relations — four pairwise, bidirectional; each section has a Coverage: N% line and gap lines citing record IDs or paths, each tagged [layer: ...]:

PDR↔ADR mapping requires textual overlap between records — proposed, never asserted.

Every gap line uses the form:

- Gap: <description citing PDR-NNN / ADR-NNN / ChDR-NNN or a file path> [layer: product|architecture|change|cross]

3. Severity model (family standard): constitution violation = CRITICAL; accepted decision contradicted by code = HIGH; undocumented/undecided mismatches = MEDIUM; unreconciled areas, style = LOW.

4. Drift section — ## Drift vs <previous date> sweep (or ## Baseline on first sweep): new gaps, closed gaps, regressed areas. On refresh, this diff IS the report.

5. Findings output — severity-ranked summary published as output_type: findings (comment bus if tracker-integrated, else runs/<run_id>/findings/sweep.md); every finding tagged [layer: ...] for correction routing . The matrix file itself is the artifact; the matrix never edits records — it reports, clarify fixes.

Shared Executor Overrides

factory-init overrides the shared executor engine primitives as follows:

1. Publish Target: Fixed to local. Outputs are written to .adlc/ (drafts, coverage) and docs/adlc/ (memory records, docs/adlc/product/PRD.md, docs/adlc/architect/AD.md). If tracker-integrated, a tracker completion summary comment is also posted.
2. Output Types (per the output-type classification): init steps → draft; clarify⭐ → decision; implement/publish → artifact-ref; analyze + sweep → findings.
3. Supervision Default: hybrid. Human gates hard-enforced at the three clarify⭐ steps (PDR, ADR, ChDR approvals) and at final coverage-matrix review.
4. Pre-flight Check: Verifies that the product-*, architect-*, and change-* lifecycle skills are installed. Team AI directives configuration is NOT required (CDR excluded); architect-init's team-directives dedup degrades gracefully if unconfigured.
5. Worktree / lease / heartbeat: follow the shared executor contract, as sibling orchestrators do.
6. Route for CDR hand-off: after the sweep, present (prose only, no step): "Reusable patterns spotted during bootstrap → run factory-learn or /team-init."

Deconfliction

• factory-intent lanes' brownfield routes remain the single-layer entry points; factory-init is the unified one. Per-layer skip keeps a re-run cheap on repos that already have one layer documented.
• factory-learn Historical Mining route = ongoing/incremental ChDR mining (post-incident, pre-refactor); factory-init = one-time deep bootstrap (full window). Both reuse the same change-* leaf skills.
• team-init (brownfield CDR) has no factory route today — a known gap in factory-learn, out of scope here.

Red Flags

• Fabricating matrix cells — every coverage cell and gap must cite a record ID or file path. An uncited gap is context poisoning.
• Asserted PDR↔ADR mappings — mapping is proposed on textual evidence; "we think these relate" without overlap text is a fabrication.
• Silent reconciliation — merging a feature-area with a sub-system without flagging the mapping (or flagging unreconciled rows as gaps) hides product/architecture disagreement.
• Skipping clarify gates — the sweep is last because it audits ACCEPTED decisions; sweeping drafts or auto-accepted records defeats the pipeline.
• Blind correction routing — sweep findings must carry [layer: ...] tags; routing everything to "the preceding clarify" sends product gaps to architecture review.
• The matrix editing records — the sweep reports; only clarify⭐ steps modify decisions with human approval.

Verification

• All 12 bootstrap steps completed (or per-layer skip applied with reason recorded in state)
• docs/adlc/product/PRD.md, docs/adlc/architect/AD.md, docs/adlc/memory/{pdr,adr,chdr}/ populated per track
• .adlc/coverage/coverage.md written with Pivot (all layer columns), four relations each with Coverage: N%, layer-tagged + cited gap lines, and Drift/Baseline section
• Prior matrix archived to .adlc/coverage/history/<date>-<run_id>.md
• Every sweep finding tagged [layer: ...]; CRITICAL/HIGH routed to the matching track's clarify (bounded max_corrections)
• Three clarify gates (product, architecture, change) plus the final matrix review fired in hybrid mode
• CDR hand-off recommendation presented in the final output
• Zero records modified by the sweep itself

Configuration

• PDR_DRAFTS_DIR — {REPO_ROOT}/.adlc/drafts/pdr
• ADR_DRAFTS_DIR — {REPO_ROOT}/.adlc/drafts/adr
• CHDR_DRAFTS_DIR — {REPO_ROOT}/.adlc/drafts/chdr
• COVERAGE_DIR — {REPO_ROOT}/.adlc/coverage (coverage.md + history/)
• PRD_FILE — {REPO_ROOT}/docs/adlc/product/PRD.md | AD_FILE — {REPO_ROOT}/docs/adlc/architect/AD.md
• Shared run state — {REPO_ROOT}/.adlc/workflows/runs/<run_id>/state.json via adlc-cli workflow state helpers (shared run state; lease/resume)

References

• factory-runbook/references/executor.md — shared executor contract (step schema, phases, correction loop, output types)
• factory-runbook/references/tracker-integration.md — comment bus, marker comments, distributed lease
• the factory-init matrix (factory-init skill — unified brownfield bootstrap + coverage matrix)
• layer-tagged correction routing
• Workflows as graphs — the fixed DAG is chosen; declarative graphs remain an option
• the output-type classification (output type classification — draft/decision/findings/artifact-ref)
• factory-intent/SKILL.md, factory-learn/SKILL.md — sibling orchestrators; single-layer entry points