diff --git a/apps/claude-code/unic-archon-dlc/AGENTS.md b/apps/claude-code/unic-archon-dlc/AGENTS.md index 0ce5c359..c49cef1c 100644 --- a/apps/claude-code/unic-archon-dlc/AGENTS.md +++ b/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-.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 `` and `` 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-.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 diff --git a/apps/claude-code/unic-archon-dlc/CONTEXT.md b/apps/claude-code/unic-archon-dlc/CONTEXT.md index d37ae280..4337b29f 100644 --- a/apps/claude-code/unic-archon-dlc/CONTEXT.md +++ b/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//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//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-.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-.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//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 diff --git a/apps/claude-code/unic-archon-dlc/docs/adr/0001-setup-as-slash-command.md b/apps/claude-code/unic-archon-dlc/docs/adr/0001-setup-as-slash-command.md index 7b2130d5..854aa7cf 100644 --- a/apps/claude-code/unic-archon-dlc/docs/adr/0001-setup-as-slash-command.md +++ b/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 diff --git a/apps/claude-code/unic-archon-dlc/docs/adr/0014-workflow-per-box-decomposition.md b/apps/claude-code/unic-archon-dlc/docs/adr/0014-workflow-per-box-decomposition.md index 7a2b0039..574df76b 100644 --- a/apps/claude-code/unic-archon-dlc/docs/adr/0014-workflow-per-box-decomposition.md +++ b/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 diff --git a/apps/claude-code/unic-archon-dlc/docs/adr/0015-workflows-slug-artifact-home.md b/apps/claude-code/unic-archon-dlc/docs/adr/0015-workflows-slug-artifact-home.md index 9afefe9f..f7c35c65 100644 --- a/apps/claude-code/unic-archon-dlc/docs/adr/0015-workflows-slug-artifact-home.md +++ b/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 `//` (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//`**. 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. diff --git a/apps/claude-code/unic-archon-dlc/docs/adr/0016-dlc-thin-process-layer.md b/apps/claude-code/unic-archon-dlc/docs/adr/0016-dlc-thin-process-layer.md new file mode 100644 index 00000000..84ac0652 --- /dev/null +++ b/apps/claude-code/unic-archon-dlc/docs/adr/0016-dlc-thin-process-layer.md @@ -0,0 +1,23 @@ +# 0016. DLC is a thin process layer; compose team system-skills for the _how_ + +**Status:** Accepted (2026-07-02) + +## Context + +The redesign toward config-driven genericity (grilled 2026-07-02) surfaced a sharper framing than "config + compose CLIs." Unic's clients run heterogeneous stacks — their own Confluence, Jira, Azure DevOps, GitHub, GitLab, Figma, or docs "elsewhere." Hardcoding any of these is expensive and non-portable: `unic-pr-review` is the cautionary tale (~830 lines of ADO-specific fetch/write code, per-tracker provider bundles, three separate setup commands, retrofitting a provider pattern after the fact). Pesche's `unic-ticket-specification` (PR #257) demonstrated the alternative — generic workflow/command templates that read **all** specifics from per-project config and compose the right tool for each job (MCP-first, CLI fallback). + +## Decision + +The DLC owns the **what** — the process/lifecycle (grill → PRD → slice → build → review → qa; the on-ramps; the off-line utilities) and the **shape** of its artefacts (what a PRD or an agent-ready issue must contain). It owns **none of the _how_** — talking to a tracker, a docs system, or a design tool. + +Every system interaction is delegated to a **team-provided system-skill** (e.g. a Confluence skill, the `azure-devops-cli` skill, the Figma MCP, `gh`/`az`/`jira` CLIs), composed at run time and selected from per-project config. The plugin is a **thin process layer over composable system-skills**. + +"Unic writes specs in Confluence" and similar are **not** universal assumptions — they are per-project config values pointing at whatever system-skill the team already has. + +## Consequences + +- The plugin's value is the **process** plus the novel deterministic IP (the anti-cheat build DAG, slopcheck, schema validation) — not integrations. See [ADR-0018](0018-generic-core-config-compose.md) for the code/compose line and [ADR-0017](0017-container-follows-structural-need.md) for containers. +- No box may hardcode a tracker/docs/design system; each reads config and composes the corresponding skill/CLI/MCP. +- `unic-pr-review` is reframed as a **donor of learnings**, not a template or dependency; whether it later converges or retires is a separate, deferred decision. +- Onboarding a new client stack = the team installs/points at the relevant system-skill and fills config; **no plugin code changes**. +- Interactive boxes compose **Matt Pocock's skills** for the process (`grill-with-docs`, `to-prd`, `to-issues`, `triage`, `improve-codebase-architecture`, `handoff`) rather than reimplementing them. diff --git a/apps/claude-code/unic-archon-dlc/docs/adr/0017-container-follows-structural-need.md b/apps/claude-code/unic-archon-dlc/docs/adr/0017-container-follows-structural-need.md new file mode 100644 index 00000000..c5dece3a --- /dev/null +++ b/apps/claude-code/unic-archon-dlc/docs/adr/0017-container-follows-structural-need.md @@ -0,0 +1,36 @@ +# 0017. Container follows structural need (Archon for AFK, commands/skills for interactive) + +**Status:** Accepted (2026-07-02) + +> **Amended (2026-07-02):** per the earns-its-place test ([ADR-0021](0021-earns-its-place-compose-verbatim.md)), `/handoff` and `/prototype` are **referenced Matt skills, not shipped** (verbatim wrappers add nothing). Matt's skill suite is a declared dependency that `/setup` verifies. + +## Context + +[ADR-0014](0014-workflow-per-box-decomposition.md) fixed the **box set** but framed every box as an _Archon workflow_ ("one Archon workflow per box"). Building `/handoff` exposed the flaw: an Archon workflow runs in an **isolated git worktree with fresh context** and has **no access to the live conversation** — yet `/handoff`'s entire job is compacting the current conversation. It is _structurally impossible_ as an Archon workflow. That is not a `/handoff` quirk; it is a test that classifies every box. Matt Pocock's skills — the process we're honouring — use **zero Archon**; they are all in-session skills because they are conversation-driven. + +## Decision + +The **container follows the box's structural need**, not a blanket rule: + +> **Archon workflow** ⟺ work that runs **unattended, in an isolated worktree, needing no live conversation.** > **Claude Code command/skill** ⟺ work that needs the **live conversation** (grilling, approving, compacting) or operates on **repo-global** state. + +Applying the test: + +``` +ARCHON (AFK, isolated, fresh-context): /build · /qa (with an approval gate) · /pr-review · /explore +COMMANDS / SKILLS (live conversation): /specs · /tickets · /triage · /improve-architecture · /handoff · /cleanup · /setup + └─ compose Matt's originals (see ADR-0016), don't reimplement +``` + +Notes: + +- `/build` is where Archon genuinely earns its keep — the anti-cheat red/green loop ([ADR-0012](0012-fresh-context-red-green-separation.md)) _needs_ isolation, parallelism, and fresh context. +- `/qa` is an AFK pipeline with a single interactive **approval** gate (schema per [ADR-0011](0011-archon-schema-target.md)). +- `/pr-review` is a **new** generic Archon workflow built the [ADR-0016](0016-dlc-thin-process-layer.md) way, harvesting the _review-aspect learnings_ of `unic-pr-review` (code quality, tests, silent-failure, type-design, comment-rot, intent-check, re-review) — **not** its ADO-specific code, and **not** as a dependency. +- `/cleanup` operates on repo-global git state (sibling worktrees/branches/PRs) so it cannot live _inside_ an isolated worktree → command. + +## Consequences + +- **Revises [ADR-0014](0014-workflow-per-box-decomposition.md):** its box set, names, revised `triage`/`cleanup`/`improve-architecture` meanings, and the _agent-ready issue_ term all stand; only its "every box is an Archon workflow" assumption is replaced by this ADR. +- The gate mode config (`gates.: hitl|afk`) still applies to Archon boxes; interactive boxes are inherently HITL by being in-session. +- Redesign step docs are re-scoped: `/handoff`, `/setup`, `/specs`, `/tickets`, `/triage`, `/improve-architecture`, `/cleanup` become command/skill steps; only `/build`, `/qa`, `/pr-review`, `/explore` remain Archon-workflow steps. The `AGENTS.md`/`CONTEXT.md` sweep and step-doc rewrite follow in a subsequent PR. diff --git a/apps/claude-code/unic-archon-dlc/docs/adr/0018-generic-core-config-compose.md b/apps/claude-code/unic-archon-dlc/docs/adr/0018-generic-core-config-compose.md new file mode 100644 index 00000000..57a85d69 --- /dev/null +++ b/apps/claude-code/unic-archon-dlc/docs/adr/0018-generic-core-config-compose.md @@ -0,0 +1,32 @@ +# 0018. Generic core + per-project config; tested lib only for tracker-agnostic deterministic IP + +**Status:** Accepted (2026-07-02) + +## Context + +[ADR-0016](0016-dlc-thin-process-layer.md) establishes that the DLC composes team system-skills for the _how_. This ADR draws the concrete line **inside the plugin**: where does bespoke tested code stop and config + composition start? The two reference points pull opposite ways — Pesche's `unic-ticket-specification` (PR #257) has **no lib at all** (pure markdown + bash + config), while the DLC's anti-cheat `/build` DAG is exactly the deterministic logic that _must_ be tested code. `unic-archon-dlc` already proves the config-driven half: `lib/tracker-adapter.mjs` keeps canonical names in code and generates tracker CLI strings from config, tested across four trackers. + +## Decision + +**Tested lib survives only for novel, deterministic, tracker-agnostic IP** that has no existing tool to compose: + +``` +KEEP as tested lib: dag-builder · slopcheck · stub-detector · issues+PRD schema-validation + · thin config validate/merge · tiny archon version-guard +DISSOLVE into config + prose composition: + tracker-adapter · labels-config · prd-writer(templates) · install-runner + · setup-explorer · agent-docs-writer · handoff-generator · findings-writer + · spike-verdicts · config-loader (absorbed into the thin config lib) +``` + +**The config substrate** becomes a rich per-project **`.archon/unic-dlc.config.yaml`** (replacing the thin `.archon/unic-dlc.config.json`), deliberately **converged with `unic-ticket-specification`'s schema** so the two plugins share a config philosophy. It carries: `project`, `tracker` (`type`, `access:{mcp,cli}`, per-tracker coords), `docs` (`type`), `repos`, **`templates`** (PRD/issue/bug — dissolving `prd-writer`'s hardcoded sections into a generic, config-driven validator), `classification`, plus the DLC's own `gates` and `build` keys. + +**Access convention: MCP-first, CLI-fallback.** Boxes prefer a configured MCP server for a system; fall back to its CLI (`gh`/`az`/`jira`, or the `azure-devops-cli` skill). Even `tracker-adapter`'s CLI-string generation is dissolved: command templates read config and compose the tool in prose (#257-style), rather than a lib building CLI strings. + +## Consequences + +- **The Axis-2 line is crisp:** tested lib ⟺ _tracker-agnostic_ deterministic IP. Tracker-_specific_ translation is prose composition driven by config, not lib. +- `prd-writer`'s template _content_ moves to config; only a generic structure _validator_ remains in lib (shared with issue-schema validation). +- Config migrates JSON → YAML; the conversational `/setup` ([ADR-0019](0019-conversational-setup.md)) reads any existing `.json` and writes the rich `.yaml` (keeping a backup) on next run. +- The `lib/` test surface shrinks to the deterministic core; every dissolved module's behaviour re-homes to config + a composed skill/CLI, validated behaviourally per box. +- This ADR states the target; the actual module removals and path/prose migration are owned by the per-box redesign steps, not this foundations PR. diff --git a/apps/claude-code/unic-archon-dlc/docs/adr/0019-conversational-setup.md b/apps/claude-code/unic-archon-dlc/docs/adr/0019-conversational-setup.md new file mode 100644 index 00000000..9cdbaeee --- /dev/null +++ b/apps/claude-code/unic-archon-dlc/docs/adr/0019-conversational-setup.md @@ -0,0 +1,27 @@ +# 0019. Conversational `/setup` + one thin tested schema lib + +**Status:** Accepted (2026-07-02) + +**Supersedes** [ADR-0001](0001-setup-as-slash-command.md). + +> **Amended (2026-07-02):** `/setup` also **discovers and registers the team's system-skills** into config — a capability→tool mapping (tracker/docs/design → `mcp | cli | skill`, MCP-first), not a presence snapshot. Discovery is **verify-only** (introspect installed skills/MCP + bash CLI probes; never installs). A missing **required** capability (incl. Matt's suite, [ADR-0021](0021-earns-its-place-compose-verbatim.md)) → **warn + degrade, non-blocking**: setup completes, records it unavailable, and lists the blocked boxes; boxes **re-probe at runtime** (MCP-first, CLI-fallback) and fail with a clear "install X". + +## Context + +[ADR-0001](0001-setup-as-slash-command.md) had `/setup` delegate all filesystem writes to a tested `lib/install-runner.mjs` (merge `defaults < existing < answers`, marker-delimited `CLAUDE.md` update, `docs/agents/*.md` generation). Under [ADR-0016](0016-dlc-thin-process-layer.md)/[ADR-0018](0018-generic-core-config-compose.md), setup is **tracker/tenant/OS wiring** — the archetypal _how_ — so it belongs in config + composition, not a bespoke lib. Pesche's `unic-ticket-specification` (PR #257) makes setup fully conversational (markdown + bash, no lib). But one genuinely deterministic, error-prone concern hides in setup: **idempotent config read-merge-write + schema validation** (a re-run must not clobber a partial config). + +## Decision + +`/setup` becomes a **conversational command**: detect tracker/OS/repo, prompt for gaps, **compose** the relevant system-skill/CLI (`az` / the `azure-devops-cli` skill, `gh`, `jira`, MCP-first) to discover and register what the team has, and write the rich **`.archon/unic-dlc.config.yaml`** ([ADR-0018](0018-generic-core-config-compose.md)). + +**Exactly one thin tested lib survives** for the deterministic part: **config schema-validate + idempotent merge** (read existing `.json`/`.yaml` → merge → validate → write `.yaml`, keeping a backup). The heavy setup libs — `install-runner`, `setup-explorer`, `agent-docs-writer` — are **dissolved**. + +The runtime Archon version check moves to a **behavioural min-floor check (`≥ 0.5.0`)**, replacing the fictional exact-`0.10` assertion ([ADR-0011](0011-archon-schema-target.md)). + +## Consequences + +- ADR-0001's "delegate all writes to `install-runner`" is reversed; setup conducts the conversation and composes tools, keeping only schema-validate/merge as tested code. +- `/setup` gains the job of **discovering/registering the team's system-skills** into config, so every downstream box knows what it can compose ([ADR-0016](0016-dlc-thin-process-layer.md)). +- New config keys (`gates.: hitl|afk`, `build.fresh_context_red_green`, `templates`, `tracker.access`, `docs.type`) are written by the conversational flow, validated by the thin lib. +- Idempotency and mandatory-field invariants are preserved by the thin lib, not lost to prose. +- Implementation (dissolving the libs, JSON→YAML migration, the version-check fix) is owned by the `/setup` redesign step, not this foundations PR. diff --git a/apps/claude-code/unic-archon-dlc/docs/adr/0020-specs-branch-on-input.md b/apps/claude-code/unic-archon-dlc/docs/adr/0020-specs-branch-on-input.md new file mode 100644 index 00000000..3dfb671b --- /dev/null +++ b/apps/claude-code/unic-archon-dlc/docs/adr/0020-specs-branch-on-input.md @@ -0,0 +1,44 @@ +# 0020. `/specs` reaches an aligned PRD by branch-on-input + +**Status:** Accepted (2026-07-02) + +> **Amended (2026-07-02):** +> +> - **PRD destination:** repo floor always (`//PRD.md`); **docs-publish is opt-in** (`docs.publish`, default off) and **composes the configured docs system-skill** (e.g. `unic-confluence` for Confluence), whose injection markers guarantee the human-authored source is never overwritten. +> - **Estimations:** the DLC **composes** an estimator (e.g. #257, or a team estimation skill) — it never builds one ([ADR-0021](0021-earns-its-place-compose-verbatim.md)). Two optional config-gated waves: **provisional @ `/specs`** (coarse, client sign-off) and **definitive @ `/tickets`** (per-slice). `estimations = off | provisional | definitive | both`. +> - **`/prototype`** (interactive design-question tool) is **Matt's referenced skill**, not a `/specs` sub-step; the AFK spike lives in `/explore`. + +## Context + +Two spec-building philosophies were in tension for `/specs`: + +- **Matt Pocock** (`grill-with-docs` + `to-prd`) — a _shared conversation_ co-builds understanding; alignment happens _during_ creation; needs the human present; doesn't run AFK. +- **Pesche `unic-ticket-specification`** (PR #257) — _autonomous_ draft (+ estimations); the human then _reads every ticket and decides_ if it is what they want; alignment happens _at review_; scales/AFK; risk of rubber-stamping a plausible-but-wrong spec. + +They looked opposed, but they are the **same job on different inputs**. Unic features arrive with heterogeneous starting material: sometimes just a raw idea; sometimes an existing spec in the team's docs system; sometimes UX specs and Figma links (design isn't always involved). + +## Decision + +`/specs` is an in-session **command/skill** ([ADR-0017](0017-container-follows-structural-need.md)) whose job is to **reach one human-approved PRD by the cheapest path given what already exists**: + +``` +raw idea, no source → converse (Matt: grill-with-docs → to-prd) — build understanding +existing spec / Figma / UX → ingest + synthesise (+ estimate) → human REVIEWS (#257 model) +partial (some docs, gaps) → ingest what exists, then grill only the GAPS +``` + +Invariants regardless of path: + +- Ends at **one PRD approval gate** before `/tickets` (HITL by default). +- **Composes team system-skills** to read whatever source exists (Confluence/Jira/ADO/GitHub/Figma via MCP-first/CLI-fallback) — `/specs` owns the _what_, not the _how_ ([ADR-0016](0016-dlc-thin-process-layer.md)). +- The conversational path composes Matt's `grill-with-docs` + `to-prd`; the ingest path composes a source-reading system-skill + synthesis, reusing `to-prd`'s PRD _shaping_ but not `grill-with-docs`. +- Keeps Matt's **seam-design approval** ("fewest seams, ideally one") before the PRD is written. +- **Estimations** are config-optional (from the #257 ingest path). +- The PRD is written to `workflows//PRD.md` ([ADR-0015](0015-workflows-slug-artifact-home.md)) and, when `docs.type` is set, published to the team's docs system via the composed skill. + +## Consequences + +- `/specs` has two code paths (converse / ingest) plus a hybrid; the old `plan.discuss_mode` flag is subsumed by input detection. +- Input detection depends on the team's system-skills being registered at `/setup` time ([ADR-0019](0019-conversational-setup.md)). +- PRD template content comes from config ([ADR-0018](0018-generic-core-config-compose.md)); a generic validator enforces structure. +- Detailed mechanics (Figma ingestion, estimation model, gap-detection, docs-system publishing) are owned by the `/specs` redesign step. diff --git a/apps/claude-code/unic-archon-dlc/docs/adr/0021-earns-its-place-compose-verbatim.md b/apps/claude-code/unic-archon-dlc/docs/adr/0021-earns-its-place-compose-verbatim.md new file mode 100644 index 00000000..88560364 --- /dev/null +++ b/apps/claude-code/unic-archon-dlc/docs/adr/0021-earns-its-place-compose-verbatim.md @@ -0,0 +1,35 @@ +# 0021. A box earns a shipped implementation only if it adds value; reference verbatim skills + +**Status:** Accepted (2026-07-02) + +## Context + +[ADR-0016](0016-dlc-thin-process-layer.md) says compose team system-skills for the _how_; [ADR-0017](0017-container-follows-structural-need.md) says interactive boxes are commands/skills composing Matt Pocock's originals. Building `/handoff` exposed the next question: if a "box" would be a **verbatim wrapper** around a skill the team already has (Matt's `handoff` compacts the live conversation — exactly what our `/handoff` would do, nothing added), why ship it at all? Shipping a duplicate violates the compose-don't-reimplement principle on our _own_ surface. + +## Decision + +**A box earns a shipped implementation in this plugin only if it adds Unic value over the raw composed skill** — config-driven genericity, the novel deterministic IP (the build DAG, slopcheck, schema validation), tracker/docs composition, or process orchestration. If a box would be a verbatim wrapper, it is **referenced, not shipped**. + +Applying the test: + +| Box | Adds value over the raw skill? | Verdict | +| ----------------------- | ------------------------------------------------- | --------------------------------- | +| `/specs` | branch-on-input + config templates + docs publish | ship | +| `/tickets` | build-DAG gen + Nyquist + tracker composition | ship | +| `/build` | the anti-cheat Archon IP | ship | +| `/pr-review` | generic Archon harvest | ship | +| `/qa` | Archon pipeline + gate | ship | +| `/triage` | config-driven tracker + intake | ship (thin) | +| `/improve-architecture` | ADR superseding + config | ship (thin) | +| `/cleanup`, `/setup` | no Matt analog | ship (new) | +| `/explore` | AFK research/spike orchestration | ship | +| **`/handoff`** | **nothing** (verbatim Matt) | **reference Matt's, not shipped** | +| **`/prototype`** | **nothing** (verbatim Matt; interactive) | **reference Matt's, not shipped** | + +## Consequences + +- **Matt Pocock's skill suite is a declared dependency of the DLC** (every skill box composes it; `/handoff` and `/prototype` are used verbatim). `/setup` verifies its presence and warns if absent ([ADR-0019](0019-conversational-setup.md)). +- The box-set diagram keeps `/handoff` and `/prototype` as lifecycle steps, tagged _(Matt's skill, referenced)_ — not shipped artefacts. +- Redesign step 02 shrinks from "build `/handoff`" to "document that the lifecycle references Matt's `handoff`; ensure it's a declared dependency." +- This refines [ADR-0016](0016-dlc-thin-process-layer.md)/[ADR-0017](0017-container-follows-structural-need.md): "compose, don't reimplement" now explicitly covers our own would-be boxes, not just system access. +- Same reasoning applies to estimation: the DLC composes an estimator, it does not build one ([ADR-0020](0020-specs-branch-on-input.md)). diff --git a/apps/claude-code/unic-archon-dlc/docs/adr/README.md b/apps/claude-code/unic-archon-dlc/docs/adr/README.md index ba05b319..613115c4 100644 --- a/apps/claude-code/unic-archon-dlc/docs/adr/README.md +++ b/apps/claude-code/unic-archon-dlc/docs/adr/README.md @@ -4,20 +4,26 @@ Plugin-scoped architectural decisions. Repo-wide decisions live in `docs/adr/` a ## Index -| ID | Title | Status | -| ---- | ---------------------------------------------------------------------------------------- | ---------------------- | -| 0001 | Setup is a slash command delegating to `lib/install-runner.mjs` | Accepted | -| 0002 | Each plugin has its own Ralph loop with its own ralph.yml and PROMPT.md | Superseded by ADR-0009 | -| 0003 | Spec template format for Ralph-executable specs | Superseded by ADR-0009 | -| 0004 | Ralph implements one spec per iteration, then commits and stops | Superseded by ADR-0009 | -| 0005 | `/tdd` for behavioral specs, direct for structural ones, dispatched by `Version impact:` | Accepted | -| 0006 | Feature Runner injects a scoped context bundle into every `/tdd` sub-agent invocation | Superseded by ADR-0010 | -| 0007 | `## Blocked by` is the canonical sequencing signal for Feature Runner issue execution | Accepted | -| 0008 | Feature Runner invokes `/tdd` non-interactively; acceptance criteria replace planning | Superseded by ADR-0010 | -| 0009 | Retire ralph-orchestrator; adopt unic-archon-dlc as the Feature Runner | Accepted | -| 0010 | Retire the `/implement-feature` skill; Feature Runner backed solely by `unic-dlc-build` | Accepted | -| 0011 | Archon version target (≥ 0.5.0) and key-discriminated node-schema conventions | Accepted | -| 0012 | Fresh-context red/green separation for anti-cheating | Accepted | -| 0013 | Issue tracker is the single source of truth; HANDOFF.md/ROADMAP.md dropped | Accepted | -| 0014 | Workflow-per-box decomposition | Accepted | -| 0015 | `workflows//` is the artifact home | Accepted | +| ID | Title | Status | +| ---- | ---------------------------------------------------------------------------------------- | ----------------------------- | +| 0001 | Setup is a slash command delegating to `lib/install-runner.mjs` | Superseded by ADR-0019 | +| 0002 | Each plugin has its own Ralph loop with its own ralph.yml and PROMPT.md | Superseded by ADR-0009 | +| 0003 | Spec template format for Ralph-executable specs | Superseded by ADR-0009 | +| 0004 | Ralph implements one spec per iteration, then commits and stops | Superseded by ADR-0009 | +| 0005 | `/tdd` for behavioral specs, direct for structural ones, dispatched by `Version impact:` | Accepted | +| 0006 | Feature Runner injects a scoped context bundle into every `/tdd` sub-agent invocation | Superseded by ADR-0010 | +| 0007 | `## Blocked by` is the canonical sequencing signal for Feature Runner issue execution | Accepted | +| 0008 | Feature Runner invokes `/tdd` non-interactively; acceptance criteria replace planning | Superseded by ADR-0010 | +| 0009 | Retire ralph-orchestrator; adopt unic-archon-dlc as the Feature Runner | Accepted | +| 0010 | Retire the `/implement-feature` skill; Feature Runner backed solely by `unic-dlc-build` | Accepted | +| 0011 | Archon version target (≥ 0.5.0) and key-discriminated node-schema conventions | Accepted | +| 0012 | Fresh-context red/green separation for anti-cheating | Accepted | +| 0013 | Issue tracker is the single source of truth; HANDOFF.md/ROADMAP.md dropped | Accepted | +| 0014 | Workflow-per-box decomposition | Accepted; revised by ADR-0017 | +| 0015 | `workflows//` is the artifact home | Accepted | +| 0016 | DLC is a thin process layer; compose team system-skills for the _how_ | Accepted | +| 0017 | Container follows structural need (Archon for AFK, commands/skills for interactive) | Accepted | +| 0018 | Generic core + per-project config; tested lib only for tracker-agnostic deterministic IP | Accepted | +| 0019 | Conversational `/setup` + one thin tested schema lib | Accepted | +| 0020 | `/specs` reaches an aligned PRD by branch-on-input | Accepted (amended) | +| 0021 | A box ships only if it adds value; reference verbatim skills | Accepted | diff --git a/apps/claude-code/unic-archon-dlc/docs/redesign/00-prework-archon-schema.md b/apps/claude-code/unic-archon-dlc/docs/redesign/00-prework-archon-schema.md index 1fb5c66d..4018b7c5 100644 --- a/apps/claude-code/unic-archon-dlc/docs/redesign/00-prework-archon-schema.md +++ b/apps/claude-code/unic-archon-dlc/docs/redesign/00-prework-archon-schema.md @@ -1,5 +1,7 @@ # Step 00 — Pre-work: Archon schema & version reconciliation +> **✓ Done (schema recorded in ADR-0011).** Still valid and it gates the Archon boxes. See [PLAN.md](./PLAN.md). + > **Read [PLAN.md](./PLAN.md) and [README.md](./README.md) first.** This step GATES every other step. Mostly research; the only edits are to PLAN.md and one ADR. ## Why diff --git a/apps/claude-code/unic-archon-dlc/docs/redesign/01-foundations.md b/apps/claude-code/unic-archon-dlc/docs/redesign/01-foundations.md index 7b4d6f7f..2f14714a 100644 --- a/apps/claude-code/unic-archon-dlc/docs/redesign/01-foundations.md +++ b/apps/claude-code/unic-archon-dlc/docs/redesign/01-foundations.md @@ -1,5 +1,7 @@ # Step 01 — Foundations: cross-cutting ADRs + doc edits +> **✓ Largely done.** Decisions recorded as ADRs 0012–0021; `AGENTS.md`/`CONTEXT.md`/PLAN.md swept to the two-axis model. This doc's original list is superseded by those ADRs — see [PLAN.md](./PLAN.md). + > **Read [PLAN.md](./PLAN.md), [README.md](./README.md), and step 00's ADR first.** This step records the locked cross-cutting decisions durably in the repo so every later step builds on them. No workflow YAML changes here. ## Task diff --git a/apps/claude-code/unic-archon-dlc/docs/redesign/02-handoff.md b/apps/claude-code/unic-archon-dlc/docs/redesign/02-handoff.md index 66f04588..0b1f0e6d 100644 --- a/apps/claude-code/unic-archon-dlc/docs/redesign/02-handoff.md +++ b/apps/claude-code/unic-archon-dlc/docs/redesign/02-handoff.md @@ -1,4 +1,6 @@ -# Step 02 — `/handoff` workflow (NEW) +# Step 02 — `/handoff` (NEW skill) + +> **⚠ Two-axis update (2026-07-02):** `/handoff` is a **Claude Code command/skill**, NOT an Archon workflow — it compacts the live conversation, which an isolated Archon worktree structurally cannot do (that realisation triggered the whole two-axis pivot; ADR-0017). **Not shipped** — reference Matt's `handoff` verbatim (earns-its-place test, [ADR-0021](../adr/0021-earns-its-place-compose-verbatim.md)); it's a declared dependency `/setup` verifies. The body below (which says "build a workflow/skill") is superseded; **[PLAN.md](./PLAN.md) + ADRs 0016–0021 win**. This step shrinks to: document the reference + ensure the dependency. > **Read [PLAN.md](./PLAN.md) + [README.md](./README.md).** Smallest unit — a good warm-up that exercises the new conventions end-to-end. diff --git a/apps/claude-code/unic-archon-dlc/docs/redesign/03-setup.md b/apps/claude-code/unic-archon-dlc/docs/redesign/03-setup.md index 6b87bc5f..4476450f 100644 --- a/apps/claude-code/unic-archon-dlc/docs/redesign/03-setup.md +++ b/apps/claude-code/unic-archon-dlc/docs/redesign/03-setup.md @@ -1,5 +1,7 @@ # Step 03 — `/setup` (config foundation) +> **⚠ Two-axis update (2026-07-02):** `/setup` is a **conversational command/skill** (ADR-0019, supersedes 0001) — it composes team system-skills to detect/register the stack and writes rich `.archon/unic-dlc.config.yaml`; only a thin tested lib does schema-validate + idempotent merge (install-runner/setup-explorer/agent-docs-writer dissolved). **[PLAN.md](./PLAN.md) + ADRs 0016–0020 win** where the body below differs. + > **Read [PLAN.md](./PLAN.md) + [README.md](./README.md).** Do this before the main-line workflows — they read this config. ## Goal diff --git a/apps/claude-code/unic-archon-dlc/docs/redesign/04-specs.md b/apps/claude-code/unic-archon-dlc/docs/redesign/04-specs.md index d5e62b2f..4ca3a1cf 100644 --- a/apps/claude-code/unic-archon-dlc/docs/redesign/04-specs.md +++ b/apps/claude-code/unic-archon-dlc/docs/redesign/04-specs.md @@ -1,5 +1,7 @@ # Step 04 — `/specs` (grill → PRD) +> **⚠ Two-axis update (2026-07-02):** `/specs` is a **command/skill** that **branches on input** (ADR-0020): raw idea → converse (Matt grill-with-docs + to-prd); existing spec/Figma/UX → ingest + synthesise (+ estimate) → review (#257); partial → ingest + grill gaps. One PRD approval gate. Composes team system-skills to read the source. **[PLAN.md](./PLAN.md) + ADRs 0016–0020 win** where the body below differs. + > **Read [PLAN.md](./PLAN.md) + [README.md](./README.md).** First main-line box. Carved out of the existing `plan` workflow (first half). ## Goal diff --git a/apps/claude-code/unic-archon-dlc/docs/redesign/05-tickets.md b/apps/claude-code/unic-archon-dlc/docs/redesign/05-tickets.md index 65af1bb1..afcc750e 100644 --- a/apps/claude-code/unic-archon-dlc/docs/redesign/05-tickets.md +++ b/apps/claude-code/unic-archon-dlc/docs/redesign/05-tickets.md @@ -1,5 +1,7 @@ # Step 05 — `/tickets` (slice PRD → issues) +> **⚠ Two-axis update (2026-07-02):** `/tickets` is a **command/skill** (interactive slicing) that composes the team's tracker system-skill to publish issues, and runs the tested `dag-builder`/nyquist/schema lib to emit `build-.yaml`. No `tracker-adapter` lib (ADR-0018). **[PLAN.md](./PLAN.md) + ADRs 0016–0020 win** where the body below differs. + > **Read [PLAN.md](./PLAN.md) + [README.md](./README.md).** Second half carved out of `plan`. Feeds `/build`. **Upstream guarantor of contract B.** ## Goal diff --git a/apps/claude-code/unic-archon-dlc/docs/redesign/06-build.md b/apps/claude-code/unic-archon-dlc/docs/redesign/06-build.md index b38db2c3..bafea4dd 100644 --- a/apps/claude-code/unic-archon-dlc/docs/redesign/06-build.md +++ b/apps/claude-code/unic-archon-dlc/docs/redesign/06-build.md @@ -1,5 +1,7 @@ # Step 06 — `/build` (KEYSTONE: anti-cheating red/green) +> **⚠ Two-axis update (2026-07-02):** `/build` **stays an Archon workflow** (AFK-isolated — where Archon earns its keep). Port it to the key-discriminated schema (ADR-0011) and keep it generic + config-driven (ADR-0016/0018). The red/green contract is unchanged (ADR-0012). **[PLAN.md](./PLAN.md) is canonical.** + > **Read [PLAN.md](./PLAN.md) + [README.md](./README.md), especially contract B.** The most important step. Depends on step 05 (generated `build-.yaml`). ## Goal diff --git a/apps/claude-code/unic-archon-dlc/docs/redesign/07-triage.md b/apps/claude-code/unic-archon-dlc/docs/redesign/07-triage.md index 4735cf61..e96ee4c0 100644 --- a/apps/claude-code/unic-archon-dlc/docs/redesign/07-triage.md +++ b/apps/claude-code/unic-archon-dlc/docs/redesign/07-triage.md @@ -1,5 +1,7 @@ # Step 07 — `/triage` (intake on-ramp, NEW meaning) +> **⚠ Two-axis update (2026-07-02):** `/triage` is a **command/skill** (interactive classification) composing Matt's `triage` + the team's tracker system-skill. Not an Archon workflow (ADR-0017). **[PLAN.md](./PLAN.md) + ADRs 0016–0020 win** where the body below differs. + > **Read [PLAN.md](./PLAN.md) + [README.md](./README.md).** The old `triage` workflow (state snapshot) was dropped in step 01. This is the brand-new Matt-style intake. ## Goal diff --git a/apps/claude-code/unic-archon-dlc/docs/redesign/08-qa.md b/apps/claude-code/unic-archon-dlc/docs/redesign/08-qa.md index 1140908d..9a8fbc09 100644 --- a/apps/claude-code/unic-archon-dlc/docs/redesign/08-qa.md +++ b/apps/claude-code/unic-archon-dlc/docs/redesign/08-qa.md @@ -1,5 +1,7 @@ # Step 08 — `/qa` +> **⚠ Two-axis update (2026-07-02):** `/qa` **stays an Archon workflow** (AFK pipeline) with a single interactive **approval** gate for UAT (ADR-0011/0017). Keep it generic + config-driven. **[PLAN.md](./PLAN.md) is canonical.** + > **Read [PLAN.md](./PLAN.md) + [README.md](./README.md).** Largely reusable; add the on-ramp role. ## Goal diff --git a/apps/claude-code/unic-archon-dlc/docs/redesign/09-pr-review.md b/apps/claude-code/unic-archon-dlc/docs/redesign/09-pr-review.md index 8f169db6..245580ed 100644 --- a/apps/claude-code/unic-archon-dlc/docs/redesign/09-pr-review.md +++ b/apps/claude-code/unic-archon-dlc/docs/redesign/09-pr-review.md @@ -1,4 +1,6 @@ -# Step 09 — `/pr-review` (rename of `review`) +# Step 09 — `/pr-review` (NEW generic Archon workflow) + +> **⚠ Two-axis update (2026-07-02):** `/pr-review` is a **new generic Archon workflow** built the #257 way, **harvesting `unic-pr-review`'s review-aspect learnings** (code quality, tests, silent-failure, type-design, comment-rot, intent-check, re-review) — NOT its ADO code, NOT a dependency (ADR-0016/0017). `unic-pr-review` is a donor; its fate is deferred. **[PLAN.md](./PLAN.md) + ADRs 0016–0020 win** where the body below differs. > **Read [PLAN.md](./PLAN.md) + [README.md](./README.md).** diff --git a/apps/claude-code/unic-archon-dlc/docs/redesign/10-improve-architecture.md b/apps/claude-code/unic-archon-dlc/docs/redesign/10-improve-architecture.md index 754d06b9..7460d6ed 100644 --- a/apps/claude-code/unic-archon-dlc/docs/redesign/10-improve-architecture.md +++ b/apps/claude-code/unic-archon-dlc/docs/redesign/10-improve-architecture.md @@ -1,5 +1,7 @@ # Step 10 — `/improve-architecture` (off-line, from `cleanup` part A) +> **⚠ Two-axis update (2026-07-02):** `/improve-architecture` is a **command/skill** composing Matt's `improve-codebase-architecture` (design grilling needs the live conversation; ADR-0017). It also supersedes stale ADRs. **[PLAN.md](./PLAN.md) + ADRs 0016–0020 win** where the body below differs. + > **Read [PLAN.md](./PLAN.md) + [README.md](./README.md).** Off the main line — periodic / on demand, not per-feature. ## Goal diff --git a/apps/claude-code/unic-archon-dlc/docs/redesign/11-cleanup.md b/apps/claude-code/unic-archon-dlc/docs/redesign/11-cleanup.md index 04e1c38c..4a392a13 100644 --- a/apps/claude-code/unic-archon-dlc/docs/redesign/11-cleanup.md +++ b/apps/claude-code/unic-archon-dlc/docs/redesign/11-cleanup.md @@ -1,5 +1,7 @@ # Step 11 — `/cleanup` (NEW: operational janitor) +> **⚠ Two-axis update (2026-07-02):** `/cleanup` is a **command** (it prunes repo-global git state — sibling worktrees/branches/PRs — so it cannot run inside an isolated worktree; ADR-0017). Composes `archon isolation`/`gh`/`az`. **[PLAN.md](./PLAN.md) is canonical.** + > **Read [PLAN.md](./PLAN.md) + [README.md](./README.md).** The name `cleanup` is REPOINTED — the old `cleanup` content moved to `/improve-architecture` (step 10). This is the maintainer's original intent: git/Archon hygiene. No Matt analog. ## Goal diff --git a/apps/claude-code/unic-archon-dlc/docs/redesign/12-explore.md b/apps/claude-code/unic-archon-dlc/docs/redesign/12-explore.md index de6c1fec..ef0baf48 100644 --- a/apps/claude-code/unic-archon-dlc/docs/redesign/12-explore.md +++ b/apps/claude-code/unic-archon-dlc/docs/redesign/12-explore.md @@ -1,5 +1,7 @@ # Step 12 — `/explore` (off-line, optional) +> **⚠ Two-axis update (2026-07-02):** `/explore` **stays an Archon workflow** (AFK research/spike → `findings.md`); interactive prototyping stays Matt's `/prototype` skill (ADR-0017). Keep it generic + config-driven. **[PLAN.md](./PLAN.md) is canonical.** + > **Read [PLAN.md](./PLAN.md) + [README.md](./README.md).** Off the main line; optional precursor to `/specs`. ## Goal diff --git a/apps/claude-code/unic-archon-dlc/docs/redesign/13-finalize.md b/apps/claude-code/unic-archon-dlc/docs/redesign/13-finalize.md index 88fa0a93..350237a1 100644 --- a/apps/claude-code/unic-archon-dlc/docs/redesign/13-finalize.md +++ b/apps/claude-code/unic-archon-dlc/docs/redesign/13-finalize.md @@ -1,5 +1,7 @@ # Step 13 — Finalize: vision diagram + docs sweep +> **⚠ Two-axis update (2026-07-02):** the diagram + docs must reflect the **two-axis architecture** (ADRs 0016–0020: container per box, thin process layer, compose team system-skills, `config.yaml`), not just the box set. **[PLAN.md](./PLAN.md) is canonical.** + > **Read [PLAN.md](./PLAN.md) + [README.md](./README.md).** Last step — reconcile the docs with what was actually built. ## Goal diff --git a/apps/claude-code/unic-archon-dlc/docs/redesign/PLAN.md b/apps/claude-code/unic-archon-dlc/docs/redesign/PLAN.md index d266b09a..109ecdd2 100644 --- a/apps/claude-code/unic-archon-dlc/docs/redesign/PLAN.md +++ b/apps/claude-code/unic-archon-dlc/docs/redesign/PLAN.md @@ -1,37 +1,71 @@ -# Refining `unic-archon-dlc` into a Matt-Pocock-aligned workflow set +# Refining `unic-archon-dlc` into a thin, Matt-aligned, config-driven lifecycle -> Durable in-repo copy of the approved umbrella plan (grilled + approved 2026-06-23). -> Original drafted at `~/.claude/plans/functional-wishing-shannon.md`. This copy is the canonical reference for the redesign handoff sessions in this directory. +> Durable in-repo copy of the redesign plan. Grilled + approved 2026-06-23; **two-axis architecture added 2026-07-02** (grill-with-docs). Canonical reference for the redesign handoff sessions in this directory. Decisions are recorded as ADRs 0011–0021 in [`../adr/`](../adr/). ## Context -`unic-archon-dlc` already ships 7 Archon workflows (`explore, plan, build, qa, cleanup, triage, review`). They were scaffolded but the design has drifted from two reference points the maintainer wants to honour: +`unic-archon-dlc` shipped 7 bundled Archon workflows. Two reference points drive the redesign: -1. **Matt Pocock's skills** (installed in this repo under `.agents/skills/`) — the "idea → ship" methodology: grill → PRD → vertical-slice issues → test-first build → review, with durable artifacts as the contract between phases. -2. **The Unic-DLC vision diagram** (`../Unic-dlc.mmd`) — a per-command pipeline with HITL/AFK gates, written using Prism (a Figma→React design-system pipeline) as the worked example. +1. **Matt Pocock's skills** (`.agents/skills/`) — the "idea → ship" methodology: grill → PRD → vertical-slice issues → test-first build → review, with durable artifacts as the baton between phases. +2. **Pesche's `unic-ticket-specification`** (PR #257) — the config-driven genericity model: generic workflow/command templates, all tracker/tenant/OS specifics in per-project config, MCP-first/CLI-fallback, compose don't reimplement. `unic-pr-review` is the **cautionary tale** (hardcoded ADO, ~830 lines, expensive). -The driver is **both**: workflows are too _coarse_ (the `plan` workflow alone bundles grill + PRD + gate + issue-decomposition + test-mapping + validation + a second gate) **and** their internals don't faithfully implement Matt's discipline. The fix for coarseness — splitting into separate, independently-runnable, gated commands — is _also_ what makes Matt-fidelity natural, because each fresh command IS the fresh context Matt's discipline relies on. +The original driver was coarseness + Matt-fidelity; a second grilling pass (2026-07-02) added the deeper architectural axis: **genericity + composition**. -**North-star constraint:** the workflows must stay **generic, installable, and tweakable per project** (web-first is an acceptable initial constraint). Prism is a _consumer_, not the spec — no Prism/Figma/Storybook/design-system specifics may leak into the generic workflows. +**North-star:** generic, installable, tweakable per project. Prism/Confluence/ADO are _consumers_, never the spec. + +--- + +## The two axes (the heart of the design) + +``` +AXIS 1 — CONTAINER follows structural need [ADR-0017, revises 0014] + ARCHON (AFK, isolated, fresh-context): /build · /qa(+approval gate) · /pr-review · /explore + COMMANDS / SKILLS (live conversation): /specs · /tickets · /triage · /improve-architecture · /handoff · /cleanup · /setup + └─ compose Matt's originals, don't reimplement + Litmus: needs the live conversation or repo-global state → command/skill; else AFK-isolated → Archon. + +AXIS 2 — GENERICITY & COMPOSITION (applies to BOTH containers) [ADR-0016, 0018] + The DLC owns the WHAT (process + artifact shapes). It composes team system-skills for the HOW + (Confluence / ADO / Jira / GitHub / GitLab / Figma / …). Thin process layer over composable system-skills. + TESTED LIB (tracker-agnostic, deterministic, no tool to compose): + dag-builder · slopcheck · stub-detector · issues+PRD schema-validation · thin config validate/merge · archon guard + COMPOSE + CONFIG (everything else): + tracker → az/gh/jira + azure-devops-cli skill (prose, no adapter lib) · docs → MCP-first/CLI-fallback · interactive → Matt's skills + SUBSTRATE: rich .archon/unic-dlc.config.yaml (converged with #257) — ALL tracker/tenant/OS/template specifics live here. +``` --- ## Locked decisions -| # | Decision | -| --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| 1 | **One Archon workflow per box.** Each is independently runnable + resumable; the written artifact is the baton handed to the next box. | -| 2 | **Box set** (below) reconciles the diagram, Matt, and the existing 7 workflows. | -| 3 | **`/explore` and `/setup` are OFF the main line.** Setup is one-time (+ re-run after plugin updates). Explore is optional research/prototype; its findings _may_ feed `/specs` but it is never required. (Corrects the diagram, which marked research/prototype "out of scope.") | -| 4 | **`/triage` = Matt's on-ramp** (raw incoming work → agent-ready issues). It is _not_ a stage between specs and tickets (diagram was wrong there). | -| 5 | **Tickets are a convergence point**: agent-ready issues are produced by PRD-slicing (`/tickets`), the `/triage` on-ramp, `/qa` findings, AND humans. `/build` consumes them regardless of producer. | -| 6 | **The old `triage` workflow is dropped entirely.** Its only job was generating `HANDOFF.md`/`ROADMAP.md`; those are **dropped** — the **issue tracker is the single source of truth** for "where are we." The doctrine "HANDOFF.md/ROADMAP.md written exclusively by triage" is retired. | -| 7 | **`/handoff` is ADDED** as a new standalone — Matt's per-thread conversation→throwaway-file session bridge. | -| 8 | **`cleanup` splits into two**: **`/improve-architecture`** (Matt's arch-health: drift review + deepening + ADR consolidation incl. _superseding_ old ADRs) and a new **`/cleanup`** (operational janitor: prune merged/stale worktrees, branches, PRs — `archon isolation cleanup --merged`, `archon complete`, gh/az). | -| 9 | **The "Component Assets → deterministic output" loop needs NO new workflow.** Emergent: each fresh slice/session reads the _committed repo state_ (the baton on disk), so prior slices' output is automatically context for later ones. Documented as the stakeholder explanation; not built. | -| 10 | **Gates: HITL by default, AFK opt-in** via `/setup` config, per workflow. | -| 11 | **Build red/green = anti-cheating fresh-context separation** (contract B). Faithful to Matt on _slicing_ and the _red→green→refactor rhythm_; deliberately stricter on _context isolation_ because the loop can run unattended (AFK). | -| 12 | **Integration contract** (C): intent in the tracker, artifacts in slug-scoped `workflows//` (NOT under `docs/`), code in the worktree; nothing relies on conversation memory. | +| # | Decision | ADR | +| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | +| 1 | **Container follows structural need** — Archon for AFK-isolated legs (`/build`, `/qa`, `/pr-review`, `/explore`); commands/skills for interactive/repo-global (`/specs`, `/tickets`, `/triage`, `/improve-architecture`, `/handoff`, `/cleanup`, `/setup`). Replaces "one Archon workflow per box." | 0017 | +| 2 | **DLC = thin process layer; compose team system-skills for the _how_.** No box hardcodes a tracker/docs/design system. | 0016 | +| 3 | **Generic core + per-project config; tested lib only for tracker-agnostic deterministic IP.** Dissolve tracker-adapter, labels-config, prd-writer(templates), install-runner, setup-explorer, agent-docs-writer, handoff-generator, findings-writer, spike-verdicts, config-loader. | 0018 | +| 4 | **Config substrate = rich `.archon/unic-dlc.config.yaml`** converged with #257; MCP-first/CLI-fallback; templates in config. | 0018 | +| 5 | **`/setup` = conversational + one thin schema lib** (validate/merge); discovers & registers the team's system-skills; supersedes ADR-0001. | 0019 | +| 6 | **`/specs` = branch-on-input**: raw idea → converse (Matt); existing spec/Figma/UX → ingest+synthesise(+estimate)→review (#257); partial → ingest + grill gaps. One PRD approval gate. | 0020 | +| 7 | **`/pr-review` = new generic Archon workflow**, #257-style, harvesting `unic-pr-review`'s review-aspect _learnings_ (not its ADO code, not a dependency); its fate deferred. | 0017 | +| 8 | **Box set + revised meanings stand** (from 0014): `/triage` = intake on-ramp; `/cleanup` = operational janitor; `/improve-architecture` = arch-health + ADR superseding; `/handoff` added; `/explore` off-line/optional; tickets = convergence point (slicing + triage + qa findings + humans). | 0014 | +| 9 | **Build red/green = anti-cheating fresh-context separation**; slice intent fed to both fresh nodes. | 0012 | +| 10 | **Integration contract**: intent → tracker; artifacts → `workflows//`; code → worktree; no conversation-memory reliance. | 0013, 0015 | +| 11 | **Gates: HITL by default, AFK opt-in** per box via config (Archon boxes); interactive boxes are inherently HITL. | 0017 | +| 12 | **"Component Assets → deterministic output" needs NO new workflow** — emergent from fresh-slice-reads-committed-repo. Stakeholder explanation, not built. | — | +| 13 | **Archon schema** = key-discriminated, ≥ 0.5.0; the shipped `type:`-style workflows are a **blocking migration**. | 0011 | + +--- + +## Round-2 refinements (2026-07-02) + +Grill-with-docs pass 2 refined the two axes (ADRs 0016–0021): + +- **Earns-its-place (ADR-0021):** ship a box only if it adds value over the raw composed skill. `/handoff` and `/prototype` are **referenced Matt skills, not shipped**; Matt's skill suite is a declared dependency `/setup` verifies. +- **`/explore` vs `/prototype`:** `/explore` is one Archon box (research + AFK spike → findings); interactive `/prototype` is Matt's referenced skill. ("prototype" was overloaded: AFK spike ≠ interactive prototype.) +- **`/setup` skill-discovery (ADR-0019 amend):** verify-only discovery (introspect skills/MCP + CLI probes); registers a capability→tool mapping (not a presence snapshot); missing required → warn + degrade, non-blocking; boxes re-probe at runtime (MCP-first/CLI-fallback). +- **PRD destination (ADR-0020 amend):** repo floor always (`//PRD.md`; `artifacts_dir` config-driven per ADR-0015 amend); docs-publish opt-in, composed via the configured docs system-skill (`unic-confluence` for Confluence — a composition layer whose injection markers guarantee non-overwrite). +- **Estimations (ADR-0020 amend):** composed, never built; two optional waves — provisional @ `/specs`, definitive @ `/tickets` (`estimations = off | provisional | definitive | both`). +- **#257 feedback:** it bundles two separable concerns (spec + estimate; one-way dependency). Recommend splitting, keeping the spec artifact rich enough to be the estimator's baton (avoid re-analysis). --- @@ -39,27 +73,28 @@ The driver is **both**: workflows are too _coarse_ (the `plan` workflow alone bu ``` MAIN LINE /specs ──► /tickets ──► /build ──► /pr-review ──► /qa + (skill) (skill) (Archon) (Archon) (Archon) ▲ -ON-RAMPS /triage ──────┤ (raw bugs/requests → agent-ready issues) +ON-RAMPS /triage ──────┤ (raw bugs/requests → agent-ready issues) [skill] /qa findings ─┤ humans ───────┘ -OFF-LINE /setup · /explore · /improve-architecture · /cleanup · /handoff +OFF-LINE /setup(skill) · /explore(Archon) · /improve-architecture(skill) · /cleanup(skill) · /handoff(Matt's, ref) · /prototype(Matt's, ref) ``` -### Mapping from the existing 7 - -| Existing | → Target | Disposition | -| ----------------- | ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `setup` (command) | `/setup` | keep; add config flags (gates, red/green, model profile); re-runnable after plugin updates | -| `explore` | `/explore` | keep, **moved off-line**; optional; emits `findings.md` that may feed `/specs` | -| `plan` | **split** → `/specs` + `/tickets` | `/specs` = grill→PRD (load-context, specs-loop, to-prd, prd-gate). `/tickets` = decompose→issues (to-issues, nyquist-map, plan-checker, yaml-gen, plan-pr-gate) | -| `triage` | **dropped** | state-snapshot concept retired (decision #6) | -| (new) | `/triage` | Matt's intake on-ramp → agent-ready issues | -| `build` | `/build` | keep; rework to enforce anti-cheating red/green + intent injection (contract B) | -| `review` | `/pr-review` | rename; keep 4-aspect review | -| `qa` | `/qa` | keep; also recognised as an issue-producing on-ramp | -| `cleanup` | **split** → `/improve-architecture` + `/cleanup` | arch-health (incl. ADR consolidation/superseding) vs operational janitor (decision #8) | -| (new) | `/handoff` | Matt's per-thread session bridge | +### Mapping from the shipped 7 + +| Shipped | → Target | Container | Disposition | +| -------------- | ------------------------------------ | ------------- | ----------------------------------------------------------------------------------------------------------------------------- | +| `setup` | `/setup` | skill | Conversational + thin schema lib; discovers team system-skills; writes rich YAML config. [0019] | +| `explore` | `/explore` | Archon | Off-line, optional; research/spike AFK → `findings.md`; interactive prototyping stays Matt's `/prototype`. | +| `plan` | `/specs` + `/tickets` | skill + skill | `/specs` branch-on-input → PRD [0020]; `/tickets` slice → agent-ready issues (dag-builder/slopcheck/nyquist stay tested lib). | +| `triage` (old) | retired | — | State-snapshot dropped. [0013] | +| — | `/triage` | skill | Intake on-ramp; composes Matt's `triage`. | +| `build` | `/build` | Archon | Anti-cheat red/green; the keystone AFK box. [0012] | +| `review` | `/pr-review` | Archon | **New** generic workflow; harvest `unic-pr-review` learnings. [0017] | +| `qa` | `/qa` | Archon | AFK pipeline + one approval gate; also an issue-producing on-ramp. | +| `cleanup` | `/improve-architecture` + `/cleanup` | skill + skill | Arch-health (composes Matt's `improve-codebase-architecture`) vs. repo-global operational janitor. | +| — | `/handoff` | skill | Matt's per-thread session bridge (impossible as Archon — no live conversation). | --- @@ -67,88 +102,54 @@ OFF-LINE /setup · /explore · /improve-architecture · /cleanup · /handoff ### A. Gates (HITL/AFK) -Every baton handoff is a **HITL approval gate by default**; flippable to AFK per-workflow in `/setup` config (`gates.: hitl|afk`). Default HITL points: `/specs`→PRD, `/tickets`→issues, `/build`→(tests-OK, then code AFK), `/build`→build-PR, `/qa`→UAT+merge, `/triage`→classification. `/pr-review` posts findings (AFK post is fine; the merge gate is the human point). +Archon boxes gate via config (`gates.: hitl|afk`, HITL default), expressed as `approval:` nodes ([ADR-0011](../adr/0011-archon-schema-target.md)). Interactive skill boxes are inherently HITL. -### B. Build — anti-cheating red/green (the core fidelity decision) +### B. Build — anti-cheating red/green ([ADR-0012](../adr/0012-fresh-context-red-green-separation.md)) ``` -SLICE = vertical tracer bullet (Matt-faithful; may carry several assertions for ONE demoable behavior) - │ - ▼ RED node (fresh ctx) input: slice INTENT (acceptance criteria, from tracker/issues.json) - write failing test(s) → RUN → assert RED → commit - │ baton = (1) slice intent + (2) committed failing test (NOT red's reasoning/session) - ▼ GREEN node (fresh ctx) input: slice INTENT + committed test - minimum impl → RUN → assert GREEN - ▼ refactor (placement = open item for /build session: tail of green vs separate fresh node) +SLICE = vertical tracer bullet (one demoable behaviour) + ▼ RED node (fresh) ← slice INTENT (acceptance criteria) → failing test → assert RED → commit + ▼ GREEN node (fresh) ← slice INTENT + committed test (NOT red's reasoning) → min impl → assert GREEN + ▼ refactor (placement = /build step open item) ``` -- **Why fresh, against Matt's single-session TDD:** a shared test+impl context lets an unattended agent _cheat_ (tests written to pass its planned impl, or impl special-cased to its own tests). Matt avoids this with a human watching every cycle; an AFK pipeline must prevent it _structurally_. This is the failure mode `ralph-orchestrator` addressed and Anthropic's ralph-loop ignores. -- **Fresh ≠ blind:** every node, even fresh ones, is fed the slice's _original intent_. The generated `code-red-`/`code-green-` nodes must (a) carry `fresh_context: true` and (b) inject the issue's `acceptance_criteria` into each node's prompt. +Fresh ≠ blind: every node is fed the slice's intent; generated `code-red-`/`code-green-` nodes carry `context: fresh` and inject `acceptance_criteria`. -### C. Integration contract (baton / resumability) +### C. Integration contract ([ADR-0013](../adr/0013-tracker-single-source-of-truth.md), [ADR-0015](../adr/0015-workflows-slug-artifact-home.md)) -``` -INTENT → issue tracker (acceptance criteria on each issue) — durable, external, read by every fresh node -ARTIFACTS → workflows// (PRD.md, issues.json, plan-checker-report.md, report.md, findings.md) - ── MOVED here from today's docs/workflow//; keep docs/ for human-facing docs only -CODE → the worktree on disk (committed tests + impl = the running baton) -SCOPE → slug keys the worktree/branch AND workflows// -RESUME → re-run the box; all state external (tracker + disk), never conversation memory -PRUNE → /cleanup removes stale workflows// dirs (alongside worktrees/branches/PRs) -``` +Intent → issue tracker · artifacts → `workflows//` · code → worktree · resume = re-run the box · `/cleanup` prunes stale slug dirs. Nothing relies on conversation memory. (`workflows//` ≠ `.archon/workflows/` DAG YAMLs.) -Caveat to document: `workflows//` (artifacts) must not be confused with `.archon/workflows/` (generated DAG YAMLs). +### D. `/setup` ([ADR-0019](../adr/0019-conversational-setup.md)) -### D. `/setup` additions +Conversational; composes system-skills to detect/register the team's stack; writes rich `.archon/unic-dlc.config.yaml` (`project`, `tracker{type,access:{mcp,cli},coords}`, `docs`, `repos`, `templates`, `classification`, `gates`, `build`). One thin tested lib: schema-validate + idempotent merge. Version check → behavioural `≥ 0.5.0`. -New config keys: `gates.: hitl|afk`; `build.fresh_context_red_green: true` (default on); slice-granularity guidance; `model_profile: fast|balanced|max` (exists). Setup remains idempotent and the sole config entry point (ADR-0001); add "re-run after plugin update." +### E. Templates & validation ([ADR-0018](../adr/0018-generic-core-config-compose.md)) -### E. Template enforcement (the diagram's "validation over MD template") +PRD/issue/bug **template content lives in config**; a generic structure **validator** stays in tested lib (shared with issue-schema validation + Nyquist `test_command` gate). -Keep + strengthen existing validators: PRD 7-section (`lib/prd-writer.mjs` `validatePrdSections`), issue schema (`lib/issues-schema.mjs` `validateIssue`/`sortByDependency`), Nyquist `test_command`/`test_command_planned` gate. +### F. Tracker/docs access — compose, don't reimplement ([ADR-0016](../adr/0016-dlc-thin-process-layer.md)) -### F. Tracker sync (the diagram's "Sync to ADO/GitHub") - -Handled by the existing `lib/tracker-adapter.mjs` (github/ado/jira/local-markdown). `/tickets`, `/triage`, `/qa` publish via it. No dedicated sync workflow; ADO is just a `/setup`-selected target. +No `tracker-adapter` lib. Command/prompt templates read config and compose the tool: MCP-first, else `az`/`gh`/`jira` CLI or the `azure-devops-cli` skill. ADO/Jira/GitHub/GitLab/Confluence/Figma are per-project config + composed system-skills. --- -## Open risks / pre-work (do before refactoring workflows) - -1. **★ Archon version + YAML-schema reconciliation — RESOLVED (2026-06-23; version refreshed 2026-06-30). See [ADR-0011](../adr/0011-archon-schema-target.md).** - - **Version (confirmed):** the 0.x line churns fast — installed CLI moved **v0.3.12 → v0.5.0 within a week** (both brew-shipped; `brew list --versions archon` → `0.5.0`). The plugin's `AGENTS.md` "≥ 0.10" claim was **fictional** (no such version line) — corrected to **≥ 0.5.0**. Don't hard-pin: the **node schema is the stable contract, not the release number** (it held across 0.3.12 → 0.5.0); re-validate behaviourally on each bump. Target floor: **≥ 0.5.0**. - - **Schema (confirmed):** Archon is **key-discriminated**, not `type:`-discriminated. Each node carries exactly one of `command | prompt | bash | script | loop | approval | cancel`; unknown fields (incl. `type:`) are silently ignored. Variables are `$`-style (`$ARGUMENTS`, `$nodeId.output`, `$ARTIFACTS_DIR`) — there is **no `inputs:` block and no `{{ }}` Jinja**. - - **Silent-failure finding (the trap):** `archon validate workflows ` reports **"ok" on all 7 shipped workflows** (re-confirmed on v0.5.0) — because each node carries a recognised content key and the stray `type:` is ignored. But validation success masks inert semantics. Translation table (today → target, and what actually happens on the installed CLI now): - - | Shipped (`type:`-style) | Target (key-discriminated) | Runs today as | - | ------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------- | - | `type: prompt` + `prompt:` | drop `type:`; `prompt:` alone | prompt node — works by accident | - | `type: bash` + `runtime: bun` + `script:` | `script:` + `runtime:` (a real bash node uses `bash:`) | script node — works (mislabeled) | - | `type: interactive` + `fresh_context: true` + `prompt:` | **`approval:` node** (`message:`, opt `on_reject`) **+ workflow-level `interactive: true`** | 🔴 plain prompt — gate never pauses | - | `type: loop` + `prompt:` (no `loop:`/`until:`) | **`loop:`** { `prompt`, `until`, `max_iterations`, opt `fresh_context`/`until_bash` } | 🔴 single-shot prompt — never iterates | - | node-level `fresh_context: true` | `context: fresh` (cmd/prompt) or `loop.fresh_context` | 🔴 ignored — isolation never applied | - | `inputs:` block + `{{ inputs.slug }}` | slug via `$ARGUMENTS`, parsed in an early node | 🔴 literal passthrough — slug never substituted | - - **⚠ BLOCKING MIGRATION:** all 7 workflows must be ported off the `type:`-style schema before the redesign builds on them. Validation alone will not catch the regressions — gates, loops, fresh-context, and slug substitution must be confirmed **behaviourally**. Owned by the per-workflow steps (02+), not this pre-work step. The `$ARGUMENTS`-based slug change touches every workflow's prompts and the `lib/` path constants that assume `inputs.slug` — sequence it with pre-work #3 below. The `/setup` runtime version-check that asserts `0.10` must be corrected to `≥ 0.5.0` in step 03 (prefer a min-floor/behavioural check over an exact-version assertion, given the churn). +## Open risks / pre-work -2. **Nested `archon workflow run` is fragile.** `/build`'s `run-build` node shells out to `archon workflow run` from _inside_ a workflow; the skill warns about `CLAUDECODE=1` nested-Claude hangs. -3. **`docs/workflow//` → `workflows//` move** touches every workflow's prompts and `lib/` path constants. +1. **Archon schema migration — RESOLVED as a decision ([ADR-0011](../adr/0011-archon-schema-target.md)), but a BLOCKING implementation for Archon boxes.** Shipped `type:`-style workflows validate "ok" yet run inert (gates don't pause, loops run once, `fresh_context` ignored, `{{ }}`/`inputs:` never substitute). Port `/build`, `/qa`, `/pr-review`, `/explore` to the key-discriminated schema; confirm gates/loops/fresh-context **behaviourally**, not via `archon validate`. +2. **Nested `archon workflow run`** from inside `/build` is fragile under `CLAUDECODE=1`; decide nested vs inlined vs sibling. +3. **JSON → YAML config migration** handled by the conversational `/setup` (read old → write rich `.yaml` → backup). +4. **Docs sweep — DONE in this PR.** `AGENTS.md`, `CONTEXT.md`, this `README`/step-doc set, and the ADR index are aligned to the two axes. What remains is the per-box **implementation** (workflow YAML / command builds) in each box's own session, plus updating the vision diagram (`../Unic-dlc.mmd`) in step 13. --- -## ADR candidates (plugin `docs/adr/`) +## Recorded decisions (ADRs) -- **Fresh-context red/green separation for anti-cheating** (keystone for `/build`). -- **Tracker as single source of truth; HANDOFF.md/ROADMAP.md dropped.** -- **`workflows//` artifact home** (separate from `docs/`). -- **Workflow-per-box decomposition** (supersedes the bundled `plan` design). +- **0011** Archon schema target · **0012** red/green anti-cheat · **0013** tracker source of truth · **0014** box set (container revised by 0017) · **0015** `workflows//` artifact home +- **0016** thin process layer / compose team-skills · **0017** container follows structural need · **0018** generic core + config + lib line · **0019** conversational setup · **0020** `/specs` branch-on-input --- ## Per-workflow handoff stubs -See the numbered docs in this directory. Recommended order: +The numbered docs `00`–`13` carry a two-axis banner and a container tag (done in this PR); their full per-box bodies are finalised in each box's own session. Recommended order unchanged: `00 pre-work` → `01 foundations` → `02 /handoff` → `03 /setup` → `04 /specs` → `05 /tickets` → `06 /build` → `07 /triage` → `08 /qa` → `09 /pr-review` → `10 /improve-architecture` → `11 /cleanup` → `12 /explore` → `13 finalize diagram + docs`. diff --git a/apps/claude-code/unic-archon-dlc/docs/redesign/README.md b/apps/claude-code/unic-archon-dlc/docs/redesign/README.md index e4de48d4..ad34dc20 100644 --- a/apps/claude-code/unic-archon-dlc/docs/redesign/README.md +++ b/apps/claude-code/unic-archon-dlc/docs/redesign/README.md @@ -1,6 +1,31 @@ # unic-archon-dlc redesign — handoff sessions -This directory drives the refactor of `unic-archon-dlc` into a Matt-Pocock-aligned, one-workflow-per-box set. Read **[PLAN.md](./PLAN.md)** first — it is the canonical spec. Each numbered file below is a **self-contained prompt** for one fresh Claude Code session. Do them **in order**; each commits durable artifacts (workflow YAML, ADRs, lib changes) that later steps read from the repo, so a cold session always picks up cleanly. +This directory drives the refactor of `unic-archon-dlc` into a **thin, Matt-aligned, config-driven lifecycle** (two-axis architecture). Read **[PLAN.md](./PLAN.md)** first — it is the canonical spec, alongside ADRs **0011–0021**. Each numbered file below is a **self-contained prompt** for one fresh Claude Code session. Do them **in order**; each commits durable artifacts (workflow YAML or command/skill, ADRs, lib changes) that later steps read from the repo, so a cold session always picks up cleanly. + +> **Two-axis update (2026-07-02):** the step-doc bodies below were written before the two-axis pivot. Where a body still says "one Archon workflow per box", **PLAN.md + ADRs 0016–0021 win.** Each step's **container** (Archon workflow vs Claude Code command/skill) is shown in the table. + +## Progress — update after each step + +> **Every step's Definition of Done includes updating this table** (Status + PR) **with the maintainer**, before the step's PR is opened. This table is the single source of truth for progress; the invocation table below is only _how to launch_. +> +> Legend: ✅ done · ⏭️ skip (not a build) · ▶️ next · ⬜ todo + +| # | Step | Container | Status | PR / notes | +| --- | ----------------------- | ----------- | ------- | -------------------------------------------------------------------- | +| 00 | Archon schema pre-work | — | ✅ done | ADR-0011 (#262) | +| 01 | Foundations | — | ✅ done | ADRs 0012–0021 + AGENTS/CONTEXT sweep (#262) | +| 02 | `/handoff` | Matt's, ref | ⏭️ skip | referenced verbatim, not shipped; dependency declared in `/setup` | +| 03 | `/setup` | skill | ▶️ next | linchpin — skill-discovery + registry every other box reads | +| 04 | `/specs` | skill | ⬜ todo | branch-on-input | +| 05 | `/tickets` | skill | ⬜ todo | + dag-builder / nyquist lib | +| 06 | `/build` | Archon | ⬜ todo | keystone — anti-cheat red/green | +| 07 | `/triage` | skill | ⬜ todo | intake on-ramp | +| 08 | `/qa` | Archon | ⬜ todo | pipeline + approval gate | +| 09 | `/pr-review` | Archon | ⬜ todo | new — harvest unic-pr-review learnings | +| 10 | `/improve-architecture` | skill | ⬜ todo | + ADR superseding | +| 11 | `/cleanup` | command | ⬜ todo | new — repo-global janitor | +| 12 | `/explore` | Archon | ⬜ todo | `/prototype` NOT built (Matt's referenced skill) | +| 13 | Finalize | — | ⬜ todo | reduced — `Unic-dlc.mmd` diagram + dogfood dry-run only (sweep done) | ## How to run a step @@ -13,44 +38,45 @@ This directory drives the refactor of `unic-archon-dlc` into a Matt-Pocock-align ## Invocation prompts (one per step, in order) -| # | Step | Paste this into a fresh session | -| --- | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------- | -| 00 | Archon schema pre-work | `Follow apps/claude-code/unic-archon-dlc/docs/redesign/00-prework-archon-schema.md to the letter. Start in plan mode.` | -| 01 | Foundations (PRD + ADRs + doc edits) | `Follow apps/claude-code/unic-archon-dlc/docs/redesign/01-foundations.md to the letter. Start in plan mode.` | -| 02 | `/handoff` workflow | `Follow apps/claude-code/unic-archon-dlc/docs/redesign/02-handoff.md to the letter. Start in plan mode.` | -| 03 | `/setup` | `Follow apps/claude-code/unic-archon-dlc/docs/redesign/03-setup.md to the letter. Start in plan mode.` | -| 04 | `/specs` | `Follow apps/claude-code/unic-archon-dlc/docs/redesign/04-specs.md to the letter. Start in plan mode.` | -| 05 | `/tickets` | `Follow apps/claude-code/unic-archon-dlc/docs/redesign/05-tickets.md to the letter. Start in plan mode.` | -| 06 | `/build` (keystone) | `Follow apps/claude-code/unic-archon-dlc/docs/redesign/06-build.md to the letter. Start in plan mode.` | -| 07 | `/triage` | `Follow apps/claude-code/unic-archon-dlc/docs/redesign/07-triage.md to the letter. Start in plan mode.` | -| 08 | `/qa` | `Follow apps/claude-code/unic-archon-dlc/docs/redesign/08-qa.md to the letter. Start in plan mode.` | -| 09 | `/pr-review` | `Follow apps/claude-code/unic-archon-dlc/docs/redesign/09-pr-review.md to the letter. Start in plan mode.` | -| 10 | `/improve-architecture` | `Follow apps/claude-code/unic-archon-dlc/docs/redesign/10-improve-architecture.md to the letter. Start in plan mode.` | -| 11 | `/cleanup` | `Follow apps/claude-code/unic-archon-dlc/docs/redesign/11-cleanup.md to the letter. Start in plan mode.` | -| 12 | `/explore` | `Follow apps/claude-code/unic-archon-dlc/docs/redesign/12-explore.md to the letter. Start in plan mode.` | -| 13 | Finalize diagram + docs | `Follow apps/claude-code/unic-archon-dlc/docs/redesign/13-finalize.md to the letter. Start in plan mode.` | - -## Shared context (every step assumes this) - -These are LOCKED (PLAN.md has detail). Each step honours them; do not re-litigate without flagging. - -- **One workflow per box**, independently runnable + resumable. Artifact = baton. +| # | Step (container) | Paste this into a fresh session | +| --- | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | +| 00 | Archon schema pre-work | `Follow apps/claude-code/unic-archon-dlc/docs/redesign/00-prework-archon-schema.md to the letter. Start in plan mode.` | +| 01 | Foundations | `Follow apps/claude-code/unic-archon-dlc/docs/redesign/01-foundations.md to the letter. Start in plan mode.` | +| 02 | `/handoff` **(Matt's, ref)** | `Follow apps/claude-code/unic-archon-dlc/docs/redesign/02-handoff.md to the letter. Start in plan mode.` | +| 03 | `/setup` **(skill)** | `Follow apps/claude-code/unic-archon-dlc/docs/redesign/03-setup.md to the letter. Start in plan mode.` | +| 04 | `/specs` **(skill)** | `Follow apps/claude-code/unic-archon-dlc/docs/redesign/04-specs.md to the letter. Start in plan mode.` | +| 05 | `/tickets` **(skill)** | `Follow apps/claude-code/unic-archon-dlc/docs/redesign/05-tickets.md to the letter. Start in plan mode.` | +| 06 | `/build` **(Archon)** — keystone | `Follow apps/claude-code/unic-archon-dlc/docs/redesign/06-build.md to the letter. Start in plan mode.` | +| 07 | `/triage` **(skill)** | `Follow apps/claude-code/unic-archon-dlc/docs/redesign/07-triage.md to the letter. Start in plan mode.` | +| 08 | `/qa` **(Archon)** | `Follow apps/claude-code/unic-archon-dlc/docs/redesign/08-qa.md to the letter. Start in plan mode.` | +| 09 | `/pr-review` **(Archon)** | `Follow apps/claude-code/unic-archon-dlc/docs/redesign/09-pr-review.md to the letter. Start in plan mode.` | +| 10 | `/improve-architecture` **(skill)** | `Follow apps/claude-code/unic-archon-dlc/docs/redesign/10-improve-architecture.md to the letter. Start in plan mode.` | +| 11 | `/cleanup` **(command)** | `Follow apps/claude-code/unic-archon-dlc/docs/redesign/11-cleanup.md to the letter. Start in plan mode.` | +| 12 | `/explore` **(Archon)** | `Follow apps/claude-code/unic-archon-dlc/docs/redesign/12-explore.md to the letter. Start in plan mode.` | +| 13 | Finalize diagram + docs | `Follow apps/claude-code/unic-archon-dlc/docs/redesign/13-finalize.md to the letter. Start in plan mode.` | + +## Shared context (every step assumes this — LOCKED; PLAN.md + ADRs have detail) + +- **Two axes.** **Axis 1 (container, ADR-0017):** Archon workflows for AFK-isolated legs (`/build`, `/qa`, `/pr-review`, `/explore`); Claude Code commands/skills for interactive/repo-global boxes (`/specs`, `/tickets`, `/triage`, `/improve-architecture`, `/handoff`, `/cleanup`, `/setup`) — **composing Matt's originals, not reimplementing**. **Axis 2 (ADR-0016/0018):** the DLC owns the _what_ and composes team system-skills for the _how_. - **Box set** — MAIN: `/specs → /tickets → /build → /pr-review → /qa`. ON-RAMPS: `/triage`, `/qa` findings, humans → agent-ready issues. OFF-LINE: `/setup`, `/explore`, `/improve-architecture`, `/cleanup`, `/handoff`. -- **Gates: HITL by default, AFK opt-in** per workflow via `/setup` (`gates.: hitl|afk`). -- **Integration contract:** intent → tracker (acceptance criteria on the issue); artifacts → `workflows//` (NOT `docs/`); code → worktree. No conversation-memory reliance. `slug` keys worktree/branch + artifact dir. -- **Red/green = fresh-context anti-cheat**: RED node (fresh) writes+commits failing test from slice intent; GREEN node (fresh) gets intent + committed test, never red's reasoning. -- **Generic / installable / tweakable.** No Prism/Figma/Storybook specifics in generic workflows. -- **Archon schema:** use whatever step 00 confirmed and wrote back into PLAN.md. +- **Generic core + config (ADR-0018):** tested lib only for tracker-agnostic deterministic IP (dag-builder, slopcheck, stub-detector, issues/PRD schema-validate, thin config validate/merge). Everything tracker/tenant/OS-specific → `.archon/unic-dlc.config.yaml` + composed skill/CLI (MCP-first, CLI-fallback). No `tracker-adapter` lib. +- **Gates: HITL by default, AFK opt-in** for Archon boxes via config (`gates.: hitl|afk`); interactive skill boxes are inherently HITL. +- **Integration contract:** intent → tracker; artifacts → `workflows//` (NOT `docs/`); code → worktree; no conversation-memory reliance. `slug` keys worktree/branch + artifact dir. +- **Red/green = fresh-context anti-cheat (ADR-0012):** RED node (fresh) writes+commits failing test from slice intent; GREEN node (fresh) gets intent + committed test, never red's reasoning. +- **Generic / installable / tweakable.** No Prism/Confluence/ADO/Figma specifics baked in — they are per-project config + composed team system-skills. +- **Archon schema (ADR-0011):** key-discriminated, ≥ 0.5.0; the shipped `type:`-style workflows are a blocking behavioural migration for the Archon boxes. ## Per-step contract (what every step delivers) - Start in **plan mode**; grill the maintainer on the step's "Open questions" before editing. - Honour the locked decisions + the confirmed Archon schema. -- Update the relevant workflow YAML in `.archon/workflows/`, command stub in `.archon/commands/`, and any `lib/` modules. +- **Archon boxes** (`/build`, `/qa`, `/pr-review`, `/explore`): author/port the workflow YAML in `.archon/workflows/` + command stub in `.archon/commands/`. **Skill boxes** (the rest): author the command/skill under `commands/`, composing Matt's originals + team system-skills; touch `lib/` only for tracker-agnostic deterministic IP. +- Read specifics from `.archon/unic-dlc.config.yaml`; compose the configured skill/CLI/MCP for any system access. - Add/edit ADRs in `apps/claude-code/unic-archon-dlc/docs/adr/` as the step notes. - `pnpm --filter unic-archon-dlc typecheck` + `test` green; `pnpm bump` + CHANGELOG entry if shipping. - Open a PR to `develop` (per repo Gitflow). One PR per step. +- **Update the [Progress](#progress--update-after-each-step) table** with the maintainer — set the row's Status (→ ✅) and add the PR link — as part of the step's Definition of Done, before opening the PR. ## Suggested skills per step -`/grilling` + `/domain-modeling` (all design steps) · `/archon` (workflow authoring/schema) · `/tdd` (lib changes) · `/handoff` (to bridge into the next step's fresh session). +`/grilling` + `/domain-modeling` (all design steps) · `/archon` (Archon-box authoring/schema) · `/tdd` (lib changes) · `/handoff` (to bridge into the next step's fresh session). Plus the **team system-skill** for the box's target system (e.g. `azure-devops-cli`, a Confluence skill, the Figma MCP).