docs(unic-archon-dlc): two-axis architecture — ADRs + full doc sweep#262
Merged
Conversation
Why: running redesign step 02 (/handoff) exposed that an Archon workflow — isolated worktree, fresh context, no live conversation — structurally cannot compact the current conversation. That wedge, plus Pesche's config-driven model (#257) and unic-pr-review's maintenance cost, reshaped the redesign into two orthogonal axes. This records the decisions before they drift (grill-with-docs discipline); the step-doc + AGENTS.md/CONTEXT.md sweep follows in a second PR. - ADR-0016 DLC is a thin process layer; compose team system-skills for the how - ADR-0017 Container follows structural need (Archon for AFK; commands/skills for interactive) — revises the container assumption of ADR-0014 (box set stands) - ADR-0018 Generic core + per-project config; tested lib only for tracker-agnostic deterministic IP (dissolves tracker-adapter et al.) - ADR-0019 Conversational /setup + one thin schema lib — supersedes ADR-0001 - ADR-0020 /specs reaches an aligned PRD by branch-on-input (converse | ingest) Also: mark ADR-0001 superseded, note ADR-0014 revised, update the ADR index, and rewrite docs/redesign/PLAN.md to the two-axis architecture. Docs only — no workflow/code behaviour change. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Way16CEwyskjYmnGEbK3V4
Fold the doc sweep into the same PR so develop is never internally inconsistent (ADRs 0016-0020 vs stale "workflow-per-box" guidance). - AGENTS.md: two-axis "what this Plugin is"; new doctrines (thin process layer, container follows structural need, tested-lib line); setup doctrine -> conversational; /handoff = command/skill; "Do not add" gains the no-hardcoded-specifics rule; layout notes updated. - CONTEXT.md: new Architecture terms (thin process layer, system-skill, container, config.yaml); PRD/Nyquist/yaml-gen/arch-review/ADR/Setup entries repointed from "workflow" to their real container; config.json -> config.yaml. - redesign/README.md: container per step, two-axis shared context, per-step contract split by container. - redesign/00-13: per-doc two-axis banner so a session pointed straight at a step doc isn't misled by its pre-pivot body. Docs only — no workflow/code behaviour change. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Way16CEwyskjYmnGEbK3V4
orioltf
changed the title
…radictory) The sweep-debt risk and the closing stubs note still said the AGENTS/CONTEXT/ step-doc sweep was deferred to a later PR, but it landed in this same PR. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Way16CEwyskjYmnGEbK3V4
…discovery, /specs destination + estimations Grill-with-docs pass 2, folded into the two-axis PR. - ADR-0021 (new): a box ships only if it adds value over the raw composed skill; verbatim wrappers referenced, not shipped. /handoff + /prototype become referenced Matt skills; Matt's suite is a declared dependency. - ADR-0015 amend: artifact base dir config-driven (artifacts_dir). - ADR-0017 amend: /handoff + /prototype referenced (not shipped). - ADR-0019 amend: /setup discovers + registers team system-skills (verify-only, capability->tool mapping, warn+degrade on missing required, runtime re-probe). - ADR-0020 amend: PRD destination (repo floor + opt-in composed docs publish, unic-confluence as docs system-skill, non-overwrite via markers); estimations composed not built, two waves (provisional @/specs, definitive @/tickets); /prototype referenced. - PLAN.md: round-2 refinements section; box diagram tags /handoff + /prototype as referenced. README index + step-02 banner updated. Also captures feedback for #257: split its bundled spec + estimate concerns. Docs only — no workflow/code behaviour change. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Way16CEwyskjYmnGEbK3V4
Member
Author
|
Round-2 refinements added (commit
Docs only. ADRs now 0011–0021. |
A multi-state status table (done/skip/next/todo) is now the single source of truth for redesign progress; updating your row (status + PR) with the maintainer is part of each step's Definition of Done. Status removed from the invocation table so it can't drift. Pre-filled: 00/01 done, 02 skip (/handoff referenced), 03 next, /prototype not built under 12, 13 reduced. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Way16CEwyskjYmnGEbK3V4
Contributor
There was a problem hiding this comment.
Pull request overview
Updates the unic-archon-dlc redesign documentation to reflect the “two-axis” architecture (Axis 1: container follows structural need; Axis 2: genericity via config + composition) and records the new/updated decisions in plugin-scoped ADRs, aiming to keep the redesign docs internally consistent while implementation work is deferred to later step PRs.
Changes:
- Document the two-axis model across redesign docs (README/PLAN + step prompts 00–13) including container assignments per step.
- Add new ADRs (0016–0021) and update ADR index/status annotations to reflect supersessions/revisions.
- Sweep plugin-level
AGENTS.mdandCONTEXT.mdvocabulary/claims to match the new architecture (thin process layer, system-skills, config.yaml, container terminology).
Reviewed changes
Copilot reviewed 28 out of 28 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| apps/claude-code/unic-archon-dlc/docs/redesign/README.md | Adds two-axis framing, progress table, and container-tagged invocation table. |
| apps/claude-code/unic-archon-dlc/docs/redesign/PLAN.md | Rewrites the redesign plan around the two axes and updates the “locked decisions” framing. |
| apps/claude-code/unic-archon-dlc/docs/redesign/00-prework-archon-schema.md | Adds “done” banner pointing to ADR-0011 as canonical. |
| apps/claude-code/unic-archon-dlc/docs/redesign/01-foundations.md | Adds “largely done” banner pointing readers to ADRs/PLAN as canonical. |
| apps/claude-code/unic-archon-dlc/docs/redesign/02-handoff.md | Adds banner clarifying /handoff is referenced (Matt skill), not shipped, per two-axis pivot. |
| apps/claude-code/unic-archon-dlc/docs/redesign/03-setup.md | Adds banner reframing /setup as conversational command/skill + thin config lib. |
| apps/claude-code/unic-archon-dlc/docs/redesign/04-specs.md | Adds banner for branch-on-input /specs and composition model. |
| apps/claude-code/unic-archon-dlc/docs/redesign/05-tickets.md | Adds banner for interactive /tickets + tested lib outputs + composition constraints. |
| apps/claude-code/unic-archon-dlc/docs/redesign/06-build.md | Adds banner emphasizing /build remains Archon and must migrate to key-discriminated schema. |
| apps/claude-code/unic-archon-dlc/docs/redesign/07-triage.md | Adds banner clarifying /triage is interactive and composes Matt + tracker tooling. |
| apps/claude-code/unic-archon-dlc/docs/redesign/08-qa.md | Adds banner clarifying /qa remains Archon with a single approval gate. |
| apps/claude-code/unic-archon-dlc/docs/redesign/09-pr-review.md | Adds banner reframing /pr-review as new generic Archon workflow, not unic-pr-review dependency. |
| apps/claude-code/unic-archon-dlc/docs/redesign/10-improve-architecture.md | Adds banner clarifying interactive command/skill container and ADR-superseding role. |
| apps/claude-code/unic-archon-dlc/docs/redesign/11-cleanup.md | Adds banner clarifying /cleanup is a repo-global command composing git/Archon/CLI tools. |
| apps/claude-code/unic-archon-dlc/docs/redesign/12-explore.md | Adds banner clarifying /explore remains Archon; /prototype remains Matt skill. |
| apps/claude-code/unic-archon-dlc/docs/redesign/13-finalize.md | Adds banner to ensure final step updates diagram/docs to two-axis model. |
| apps/claude-code/unic-archon-dlc/docs/adr/README.md | Updates ADR index with new ADRs and revised/superseded statuses. |
| apps/claude-code/unic-archon-dlc/docs/adr/0001-setup-as-slash-command.md | Marks ADR-0001 as superseded by ADR-0019. |
| apps/claude-code/unic-archon-dlc/docs/adr/0014-workflow-per-box-decomposition.md | Notes container assumption revised by ADR-0017 while box set stands. |
| apps/claude-code/unic-archon-dlc/docs/adr/0015-workflows-slug-artifact-home.md | Amends artifact base dir to be config-driven while keeping slug-scoping principles. |
| apps/claude-code/unic-archon-dlc/docs/adr/0016-dlc-thin-process-layer.md | New ADR defining DLC as thin process layer composing team system-skills. |
| apps/claude-code/unic-archon-dlc/docs/adr/0017-container-follows-structural-need.md | New ADR defining container selection rule (Archon vs command/skill). |
| apps/claude-code/unic-archon-dlc/docs/adr/0018-generic-core-config-compose.md | New ADR defining the lib-vs-config boundary and YAML config substrate. |
| apps/claude-code/unic-archon-dlc/docs/adr/0019-conversational-setup.md | New ADR redefining /setup as conversational + thin tested config merge/validate lib. |
| apps/claude-code/unic-archon-dlc/docs/adr/0020-specs-branch-on-input.md | New ADR specifying /specs branch-on-input behavior and composition approach. |
| apps/claude-code/unic-archon-dlc/docs/adr/0021-earns-its-place-compose-verbatim.md | New ADR defining when to ship a box vs reference an existing skill verbatim. |
| apps/claude-code/unic-archon-dlc/CONTEXT.md | Updates plugin domain vocabulary to include two-axis concepts and YAML config. |
| apps/claude-code/unic-archon-dlc/AGENTS.md | Updates plugin guidance to reflect two-axis model, container split, and composition constraints. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- 0001: fold the two Status lines into one (Superseded by 0019; originally Accepted). - PLAN.md + 01-foundations.md: ADR range 0011–0020 → 0011–0021 (ADR-0021 added). - redesign README: /cleanup invocation row said (skill) → (command), matching the Progress table + 11-cleanup.md. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Way16CEwyskjYmnGEbK3V4
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
Running redesign step 02 (
/handoff) exposed a structural flaw in the approved plan: an Archon workflow runs in an isolated worktree with fresh context and no access to the live conversation — yet/handoff's whole job is compacting the current conversation. It's impossible as an Archon workflow. That wedge, plus Pesche's config-driven model (#257) andunic-pr-review's maintenance cost, reshaped the redesign into two orthogonal axes.Records the decisions and sweeps every doc to match — in one PR, so
developis never internally inconsistent (ADRs vs. stale "workflow-per-box" guidance). Docs only; no workflow/code behaviour change.The two axes
/build,/qa+gate,/pr-review,/explore); commands/skills for interactive/repo-global (/specs,/tickets,/triage,/improve-architecture,/handoff,/cleanup,/setup) — composing Matt's originals..archon/unic-dlc.config.yaml(converged with feat(unic-ticket-specification): add portable ticket-specification workflow plugin #257) + MCP-first/CLI-fallback.Changes
docs/redesign/PLAN.mdto the two-axis architecture (canonical spec).AGENTS.md+CONTEXT.mdto the two axes (doctrines, vocabulary,config.json→config.yaml, container-correct entries).docs/redesign/README.mdcontainer-per-step + two-axis shared context; per-doc banners on step docs00–13so a session pointed straight at one isn't misled.Deferred
unic-pr-review's fate (converge/retire) remains a separate, deferred decision.🤖 Generated with Claude Code