docs(unic-archon-dlc): two-axis architecture — ADRs + full doc sweep

apps/claude-code/unic-archon-dlc/AGENTS.md

@@ -4,7 +4,7 @@ Guidance for any AI agent working inside this Plugin directory. `CLAUDE.md` in t
 
 ## What this Plugin is
 
-`unic-archon-dlc` is a Claude Code Plugin in the [`unic-agents-plugins`](../../../AGENTS.md) monorepo. It scaffolds an Archon-powered AI development lifecycle — a workflow-per-box set (main line `/specs` → `/tickets` → `/build` → `/pr-review` → `/qa`; on-ramps `/triage` + `/qa` findings; off-line `/setup`, `/explore`, `/improve-architecture`, `/cleanup`, `/handoff`) plus agent-skill docs — into any Consumer project. Configuration is performed once via the `/unic-archon-dlc:setup` slash command. See [ADR-0014](docs/adr/0014-workflow-per-box-decomposition.md) for the box set and [`CONTEXT.md`](CONTEXT.md) for the domain vocabulary (Session, Slug, PRD, Findings, Issues JSON, Nyquist map, yaml-gen, Setup).
+`unic-archon-dlc` is a Claude Code Plugin in the [`unic-agents-plugins`](../../../AGENTS.md) monorepo. It scaffolds a **thin process layer** for an AI development lifecycle: it owns the _what_ (the box set — main line `/specs` → `/tickets` → `/build` → `/pr-review` → `/qa`; on-ramps `/triage` + `/qa` findings; off-line `/setup`, `/explore`, `/improve-architecture`, `/cleanup`, `/handoff`) and **composes the team's system-skills for the _how_** (tracker/docs/design access). Each box's **container follows its structural need** — Archon workflows for the AFK-isolated legs (`/build`, `/qa`, `/pr-review`, `/explore`), Claude Code commands/skills for the interactive/repo-global ones (the rest, composing Matt Pocock's skills rather than reimplementing them). Configuration is via the `/unic-archon-dlc:setup` slash command. See [ADR-0016](docs/adr/0016-dlc-thin-process-layer.md)–[ADR-0018](docs/adr/0018-generic-core-config-compose.md) for the two-axis architecture, [ADR-0014](docs/adr/0014-workflow-per-box-decomposition.md) for the box set, and [`CONTEXT.md`](CONTEXT.md) for the vocabulary.
 
 ## Where to start
 
@@ -40,8 +40,8 @@ Monorepo-wide commands (`pnpm install`, `pnpm check`, `pnpm format`, `pnpm ci:ch
 ```tree
 .archon/                  # Archon assets installed into Consumer projects — workflow YAMLs and command stubs
 .claude-plugin/           # Plugin manifest (plugin.json) and marketplace listing
-commands/                 # Claude Code slash command definitions — only setup.md today
-lib/                      # Pure helper modules consumed by the setup command (ESM, // @ts-check)
+commands/                 # Claude Code slash command / skill definitions (setup + the interactive boxes)
+lib/                      # Tested helper modules — tracker-agnostic deterministic IP only (ESM, // @ts-check)
 test/                     # node:test suites covering lib/ and command behaviour
 CONTEXT.md                # Domain vocabulary for the Archon-powered AI development lifecycle
 docs/                     # Plugin-specific documentation
@@ -52,13 +52,16 @@ docs/                     # Plugin-specific documentation
 
 Load-bearing invariants. These either originate in a Plugin ADR or are policy decisions that are not obvious from the code.
 
-- **Setup is the sole entry point and is idempotent.** The `/unic-archon-dlc:setup` slash command is the one and only user-facing surface. Re-running it on a fully configured Consumer prints the current config; on a partial config it asks only for missing fields; on a fresh project it prompts for everything. See [ADR-0001](docs/adr/0001-setup-as-slash-command.md).
+- **Setup is the sole configuration entry point — conversational and idempotent.** The `/unic-archon-dlc:setup` slash command is the one user-facing config surface. It conducts the conversation, **composes the team's system-skills** to detect/register their stack, and writes `.archon/unic-dlc.config.yaml`; only a thin tested lib does schema-validate + idempotent merge (a re-run prints/patches, never clobbers). See [ADR-0019](docs/adr/0019-conversational-setup.md) (supersedes [ADR-0001](docs/adr/0001-setup-as-slash-command.md)).
+- **The DLC owns the _what_; it composes team system-skills for the _how_.** No box hardcodes a tracker/docs/design system; each reads `.archon/unic-dlc.config.yaml` and composes the configured skill/CLI/MCP (MCP-first, CLI-fallback). See [ADR-0016](docs/adr/0016-dlc-thin-process-layer.md).
+- **Container follows structural need.** Archon workflows only for AFK-isolated, no-live-conversation work (`/build`, `/qa`, `/pr-review`, `/explore`); Claude Code commands/skills for interactive or repo-global work, composing Matt's originals. See [ADR-0017](docs/adr/0017-container-follows-structural-need.md).
+- **Tested lib only for tracker-agnostic deterministic IP** (dag-builder, slopcheck, stub-detector, issues/PRD schema-validation, thin config validate/merge). Everything tracker/tenant/OS-specific lives in config + composition, never bespoke lib. See [ADR-0018](docs/adr/0018-generic-core-config-compose.md).
 - **Session is scoped by Slug.** Every Session artefact (Findings, PRD, Issues JSON, `build-<slug>.yaml`) is keyed by a single Slug. No cross-Session bleed. See [CONTEXT.md](CONTEXT.md).
-- **The issue tracker is the single source of truth for "where are we."** `HANDOFF.md` and `ROADMAP.md` are dropped, and the old state-snapshot `triage` workflow is retired — no workflow writes either file. Per-thread continuity is handled by the `/handoff` workflow, which writes a throwaway file, not a durable repo snapshot. See [ADR-0013](docs/adr/0013-tracker-single-source-of-truth.md).
+- **The issue tracker is the single source of truth for "where are we."** `HANDOFF.md` and `ROADMAP.md` are dropped, and the old state-snapshot `triage` workflow is retired — no workflow writes either file. Per-thread continuity is handled by the `/handoff` command/skill (it compacts the live conversation, so it cannot be an Archon workflow — see [ADR-0017](docs/adr/0017-container-follows-structural-need.md)), which writes a throwaway file, not a durable repo snapshot. See [ADR-0013](docs/adr/0013-tracker-single-source-of-truth.md).
 - **The `## Agent skills` block in a Consumer's `CLAUDE.md` is auto-managed.** Setup writes content between `<!-- unic-archon-dlc:begin -->` and `<!-- unic-archon-dlc:end -->` markers. Everything outside the markers is preserved verbatim across re-runs.
 - **Slopcheck before build.** Every new package referenced in `package.json` is verified against the npm registry before any `code-red`/`code-green` node runs. Packages that fail are flagged `[ASSUMED]` and require explicit human approval.
 - **Nyquist map gates yaml-gen.** Every issue in Issues JSON must carry a `test_command` before the `yaml-gen` node generates `.archon/workflows/build-<slug>.yaml`.
-- **Dogfooding note.** This monorepo has had Setup run against it; the generated artefacts live under [`docs/agents/`](../../../docs/agents/) at the repo root and are managed by the marker-delimited block in the root [`AGENTS.md`](../../../AGENTS.md). Those files describe the target workflow-per-box set (see [ADR-0014](docs/adr/0014-workflow-per-box-decomposition.md)) with the tracker as the single source of truth, and should be treated as the canonical agent guidance for this repo, not as a current-practice snapshot.
+- **Dogfooding note.** This monorepo has had Setup run against it; the generated artefacts live under [`docs/agents/`](../../../docs/agents/) at the repo root and are managed by the marker-delimited block in the root [`AGENTS.md`](../../../AGENTS.md). Those files describe the target two-axis architecture (see [ADR-0016](docs/adr/0016-dlc-thin-process-layer.md)–[ADR-0018](docs/adr/0018-generic-core-config-compose.md)) with the tracker as the single source of truth, and should be treated as the canonical agent guidance for this repo, not as a current-practice snapshot.
 
 ## External dependencies
 
@@ -68,7 +71,8 @@ Load-bearing invariants. These either originate in a Plugin ADR or are policy de
 
 - **Parallel-runner support before the linear path is operational.** The current happy path runs one Session at a time. Until that is rock-solid in real Consumers, do not add parallel-Session orchestration.
 - **Per-plugin variants of the Slug scheme.** Slug is monorepo-wide vocabulary; do not introduce a Plugin-specific Slug format.
-- **Consumer-side opt-out flags for individual workflow boxes.** Until a real Consumer asks for it with a concrete use case, the workflow-per-box set ships as one bundle. See [ADR-0014](docs/adr/0014-workflow-per-box-decomposition.md).
+- **Consumer-side opt-out flags for individual boxes.** Until a real Consumer asks with a concrete use case, the box set ships as one bundle. See [ADR-0014](docs/adr/0014-workflow-per-box-decomposition.md).
+- **Hardcoded tracker/tenant/OS specifics, or bespoke lib for what a team system-skill already does.** Read config and compose (MCP-first, CLI-fallback); keep tested lib to tracker-agnostic deterministic IP. See [ADR-0016](docs/adr/0016-dlc-thin-process-layer.md) / [ADR-0018](docs/adr/0018-generic-core-config-compose.md).
 - **`HANDOFF.md` / `ROADMAP.md` revival, or any workflow that writes durable repo-state snapshots.** The tracker is the single source of truth. See [ADR-0013](docs/adr/0013-tracker-single-source-of-truth.md).
 
 ## Plugin ADRs

apps/claude-code/unic-archon-dlc/CONTEXT.md

@@ -1,15 +1,42 @@
 # unic-archon-dlc
 
-An Archon-powered AI development lifecycle DLC that scaffolds a workflow-per-box set — main line
+A **thin process layer** for an AI development lifecycle. It owns the _what_ (the box set — main line
 `/specs` → `/tickets` → `/build` → `/pr-review` → `/qa`; on-ramps `/triage` and `/qa` findings;
-off-line `/setup`, `/explore`, `/improve-architecture`, `/cleanup`, `/handoff` — plus agent-skill
-docs into any target project. Configuration is performed once via the `/unic-archon-dlc:setup`
-slash command. See `docs/adr/0014-workflow-per-box-decomposition.md` for the box set.
+off-line `/setup`, `/explore`, `/improve-architecture`, `/cleanup`, `/handoff`) and **composes the
+team's system-skills for the _how_**. Each box's container follows its structural need: Archon
+workflows for the AFK-isolated legs, Claude Code commands/skills for the interactive ones.
+Configured via the `/unic-archon-dlc:setup` slash command. See `docs/adr/0016`–`0018` for the
+two-axis architecture and `docs/adr/0014` for the box set.
 
 Requires the Archon workflow engine (version ≥ 0.5.0) in the target project.
 
 ## Language
 
+### Architecture
+
+**Thin process layer**:
+The DLC owns the _what_ (the lifecycle and artefact shapes) and composes the team's system-skills
+for the _how_. See `docs/adr/0016-dlc-thin-process-layer.md`.
+_Avoid_: framework, integration layer
+
+**System-skill**:
+A team-provided capability that talks to one of their systems (a Confluence skill, the
+`azure-devops-cli` skill, the Figma MCP, `gh`/`az`/`jira`). Boxes compose these; the plugin never
+reimplements them.
+_Avoid_: integration, adapter, provider
+
+**Container**:
+How a box is packaged — an **Archon workflow** (AFK-isolated: `/build`, `/qa`, `/pr-review`,
+`/explore`) or a **Claude Code command/skill** (interactive/repo-global: the rest). Container
+follows structural need. See `docs/adr/0017-container-follows-structural-need.md`.
+_Avoid_: using "workflow" as a synonym for a box
+
+**config.yaml**:
+The rich per-project `.archon/unic-dlc.config.yaml` (converged with `unic-ticket-specification`)
+holding all tracker/tenant/OS/template specifics; boxes read it and compose accordingly (MCP-first,
+CLI-fallback). See `docs/adr/0018-generic-core-config-compose.md`.
+_Avoid_: config.json (the retired thin form)
+
 ### Session lifecycle
 
 **Slug**:
@@ -32,8 +59,9 @@ _Avoid_: ticket, ready ticket, groomed issue
 ### Planning artifacts
 
 **PRD**:
-Product Requirements Document produced by the `to-prd` node in the `/specs` workflow and stored at
-`workflows/<slug>/PRD.md`. Must contain exactly the seven mandatory sections.
+Product Requirements Document produced by the `/specs` command (branch-on-input; via Matt's
+`to-prd`) and stored at `workflows/<slug>/PRD.md`. Its section shape comes from the config template
+and is enforced by a generic validator. See `docs/adr/0020-specs-branch-on-input.md`.
 _Avoid_: spec, requirements doc
 
 **Findings**:
@@ -47,9 +75,9 @@ Each entry carries a `test_command` required for Nyquist validation.
 _Avoid_: tickets, tasks list
 
 **Nyquist map**:
-The node in the `/tickets` workflow that validates every issue in Issues JSON has a `test_command`
-before yaml-gen runs. Named after the Nyquist sampling theorem analogy: you must observe
-behaviour at twice the frequency to reconstruct it faithfully.
+The validation the `/tickets` command runs (via tested lib) to ensure every issue in Issues JSON
+has a `test_command` before `dag-builder` generates the build DAG. Named after the Nyquist sampling
+theorem analogy: you must observe behaviour at twice the frequency to reconstruct it faithfully.
 _Avoid_: validation node, test-command check
 
 ### Build discipline
@@ -77,17 +105,18 @@ Packages that fail the check are flagged `[ASSUMED]` and require explicit human
 _Avoid_: package check, dependency audit
 
 **yaml-gen**:
-The bash node in the `/tickets` workflow that generates `.archon/workflows/build-<slug>.yaml` — a DAG
-of `code-red` and `code-green` nodes for every issue, with correct `depends_on` edges derived
-from the `blocked_by` fields in Issues JSON.
+The tested `dag-builder` lib step the `/tickets` command runs to generate
+`.archon/workflows/build-<slug>.yaml` — a DAG of `code-red` and `code-green` nodes for every issue,
+with `depends_on` edges derived from the `blocked_by` fields in Issues JSON.
 _Avoid_: build generator, workflow generator
 
 ### Plugin entry points
 
 **Setup**:
 The one-time conversational configuration of unic-archon-dlc in a target project, invoked as
-`/unic-archon-dlc:setup`. Writes `.archon/unic-dlc.config.json`, generates `docs/agents/*.md`,
-and refreshes the marker-delimited `## Agent skills` block in `CLAUDE.md`. Idempotent: re-running
+`/unic-archon-dlc:setup`. Writes `.archon/unic-dlc.config.yaml`, discovers and registers the team's system-skills,
+and refreshes the marker-delimited `## Agent skills` block in `CLAUDE.md`. Idempotent (a thin tested
+lib does schema-validate + merge): re-running
 with no arguments prints the current config when fully populated, asks only for missing fields
 when partial, and prompts for everything on a fresh project. Pass `reconfigure` to force a full
 re-prompt; pass free-form intent (e.g. "change branching to github-flow") for targeted tweaks.
@@ -108,13 +137,13 @@ _Avoid_: slash command, workflow command (ambiguous)
 
 **arch-review**:
 The architecture review output at `workflows/<slug>/arch-review.md`, produced by the
-`arch-review` node in the `/improve-architecture` workflow. Identifies technical drift, intent
-drift, and deepening opportunities.
+`/improve-architecture` command/skill (which composes Matt's `improve-codebase-architecture`).
+Identifies technical drift, intent drift, and deepening opportunities.
 _Avoid_: architecture report, code review
 
 **ADR**:
 Architecture Decision Record. Written to `docs/adr/NNNN-*.md` only after explicit human
-approval in the `adr-consolidation` interactive node of the `/improve-architecture` workflow.
+approval in the `/improve-architecture` command/skill (which also supersedes stale ADRs).
 _Avoid_: decision doc, architecture note
 
 ## Relationships
@@ -125,4 +154,4 @@ _Avoid_: decision doc, architecture note
 - **code-green** depends on **code-red** within the same issue; independent issues run in parallel
 - **adr-consolidation** (in `/improve-architecture`) sources candidates from the "Decisions Made" section of `report.md` and "Accept as ADR" items from **arch-review**
 - The **issue tracker** is the single source of truth for project state; there is no `HANDOFF.md`/`ROADMAP.md`
-- The **Setup** slash command writes `.archon/unic-dlc.config.json`, `docs/agents/*.md`, and the `## Agent skills` block in `CLAUDE.md` into the target project
+- The **Setup** slash command writes `.archon/unic-dlc.config.yaml`, registers the team's system-skills, and refreshes the `## Agent skills` block in `CLAUDE.md` in the target project

apps/claude-code/unic-archon-dlc/docs/adr/0001-setup-as-slash-command.md

@@ -1,6 +1,6 @@
 # Setup is a slash command delegating to `lib/install-runner.mjs`
 
-**Status:** Accepted (2025-05)
+**Status:** Superseded by [ADR-0019](0019-conversational-setup.md) (2026-07-02); originally Accepted (2025-05). Setup stays a slash command, but the delegation to `lib/install-runner.mjs` is replaced by a conversational flow that composes system-skills and keeps only a thin config schema-validate/merge lib.
 
 The user-facing entry point for configuring unic-archon-dlc in a target project is the
 `/unic-archon-dlc:setup` slash command (`commands/setup.md`), not a Node CLI hook. The

apps/claude-code/unic-archon-dlc/docs/adr/0014-workflow-per-box-decomposition.md

@@ -1,6 +1,6 @@
 # 0014. Workflow-per-box decomposition
 
-**Status:** Accepted (2026-06-30)
+**Status:** Accepted (2026-06-30). Container assumption revised by [ADR-0017](0017-container-follows-structural-need.md) (2026-07-02) — the box set below stands, but boxes are no longer all Archon workflows (some are commands/skills).
 
 ## Context
 

apps/claude-code/unic-archon-dlc/docs/adr/0015-workflows-slug-artifact-home.md

@@ -2,6 +2,8 @@
 
 **Status:** Accepted (2026-06-30)
 
+> **Amended (2026-07-02):** the artifact base dir is **config-driven** (`artifacts_dir`, default `workflows`), so a team can relocate `<base>/<slug>/` (e.g. `docs/specs/`) — #257-aligned. Slug-scoping and the `docs/`-separation rule are unchanged.
+
 ## Context
 
 Session artefacts (the PRD, issues JSON, findings, plan-checker report, run report) were written under **`docs/workflow/<slug>/`**. That places generated, machine-owned, per-Session output inside `docs/` — the tree humans browse for hand-written documentation. The two concerns are different: `docs/` is curated and durable; Session artefacts are slug-scoped, regenerated on re-run, and pruned when the Session is done.