factory-init

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-product / factory-architect / 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-mission/references/executor.md.

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-product and factory-architect (specify routes) instead.
• Single-layer work → factory-product / factory-architect / factory-learn directly.
• CDR / team-directives contribution → factory-learn.
• Feature implementation → factory-mission.

---

Route Classification

Condition	Route
Code exists, no memory records	Bootstrap (full pipeline)
.adlc/coverage/coverage.md exists, or --refresh	Refresh (sweep only)
Partial state	Bootstrap with per-layer skip (below)
No code	Halt: greenfield — use factory-product / factory-architect specify routes

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:

Layer	Skip init/implement when	Always runs
product	docs/adlc/memory/pdr/ (legacy .adlc/memory/pdr/ fallback — either non-empty) AND docs/adlc/product/PRD.md exists	product-analyze
architecture	docs/adlc/memory/adr/ (legacy .adlc/memory/adr/ fallback — either non-empty) AND docs/adlc/architect/AD.md exists	architect-analyze
change	docs/adlc/memory/chdr/ (legacy .adlc/memory/chdr/ fallback — either non-empty) AND docs/adlc/memory/chdr.md exists	(ChDRs feed the sweep directly)

---

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)

#	Step	Skill	Phase	output_type
1	product-init	product-init	generate	draft (.adlc/drafts/pdr/)
2	product-clarify⭐	product-clarify	clarify	decision
3	product-implement	product-implement	build	artifact-ref (docs/adlc/product/PRD.md)
4	architect-init	architect-init	generate	draft (.adlc/drafts/adr/)
5	architect-clarify⭐	architect-clarify (reads accepted PDR list)	clarify	decision
6	architect-implement	architect-implement	build	artifact-ref (docs/adlc/architect/AD.md)
7	change-init	change-init	generate	draft (.adlc/drafts/chdr/)
8	change-clarify⭐	change-clarify	clarify	decision
9	change-publish	change-publish	build	artifact-ref (docs/adlc/memory/chdr/)
10	product-analyze	product-analyze	analyze	findings
11	architect-analyze	architect-analyze	analyze	findings
12	sweep	inline (this skill, §The Sweep Step)	analyze	findings (.adlc/coverage/coverage.md + history)

Refresh Route (1 step + loop)

#	Step	Phase	output_type
1	sweep (rescan + rebuild + drift diff)	analyze	findings

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 (ADR-361): 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: ...]:

Relation	Gap directions
PDR↔ADR	product decision with no architectural support; orphan ADR (no product grounding — MEDIUM, not auto-defect)
PDR↔code	decided-but-unimplemented; implemented-but-undocumented
ADR↔code	decided-but-not-reflected-in-code; code pattern without ADR
ChDR↔code	ChDR-dense area with no ADR (active change, no architectural record); ChDR describing code that no longer matches (superseded decision)

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 (ADR-361). 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 PDR-050): 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-product / factory-architect 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 (ADR-395; lease/resume)

References

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