Install unic-archon-dlc into DXP-DesignSystem by hand, on day 1 #376

Activity

1. orioltf

   added

   app:unic-archon-dlc

   p0Critical priorityCritical priority

   wayfinder:taskWayfinder ticket: do the thingWayfinder ticket: do the thing

   on Aug 14, 2026
2. orioltf

   added a parent issue on Aug 14, 2026

   • wayfinder: unic-archon-dlc is prose, and proven at a Consumer #373
3. orioltf

   marked this as blocking on Aug 14, 2026

   • Land a rendering component on develop, so the client sees the walk's output #379
4. orioltf commented on Aug 14, 2026

   

   orioltf

   on Aug 14, 2026

   Last edited by orioltf

   MemberAuthor

   More actions

   How to start this session

   Produces: the DLC installed in DXP-DesignSystem, and a written list of what Azure DevOps does not
   give the DLC. Day 1 of the Consumer sprint.

   1. Run /wayfinder 373 #376 here to claim the ticket. The work then happens in
      the Consumer's clone.
   2. Confirm the ground: git remote get-url origin names the Consumer's Azure DevOps project, and
      archon --version reports 0.7.0 or higher.
   3. Copy the four .archon/workflows/unic-dlc-*.yaml Boxes from this plugin.
   4. Copy the Methods from the plugin's vendor/mattpocock-skills/ into .archon/methods/.
   5. Write .archon/unic-dlc.config.yaml by hand. Read lib/config-schema.mjs as the field reference
      while it still exists — read it, never run it.
   6. Run archon workflow list. Expect the four Boxes.
   7. Write up every GitHub assumption Azure DevOps does not satisfy, naming the file and the node.

   Traps

   • Do not run /unic-archon-dlc:setup. Decision 14 retires it, and artefact-install.mjs is the
     plugin's largest defect source.
   • The tracker is Azure DevOps and the DLC has only ever run against GitHub. The azure-devops-cli
     skill is installed and unic-pr-review already works this tenant — read how it does it rather than
     inventing a call.
   • Keep the exact command sequence. It becomes the source for Rewrite commands/setup.md from scratch as prose #383 and for the README's install section.
5. orioltf

   self-assigned this

   on Aug 17, 2026
6. orioltf commented on Aug 17, 2026

   

   orioltf

   on Aug 17, 2026

   Last edited by orioltf

   MemberAuthor

   More actions

   Done

   unic-archon-dlc is installed in DXP-DesignSystem on branch feature/42928_initial-DLC-installation, commit 83e8b67, pushed to the Consumer's Azure DevOps project. No PR yet. /unic-archon-dlc:setup was not run.

   • .archon/workflows/ — the four unic-dlc-*.yaml Boxes.
   • .archon/methods/ — eleven Methods plus the upstream LICENSE, each directory named for its canonical Method name.
   • .archon/unic-dlc.config.yaml — hand-written, tracker ado.

   archon workflow list reports 25 workflows: 21 bundled plus the four Boxes. archon validate workflows says ok for each of the four.

   A Box reads the config. archon workflow run unic-dlc-build "dlc-install-smoke" --from feature/42928_initial-DLC-installation. The bootstrap node emitted status: no-issues, expected_base: main, gate: hitl, and the sentence "Config reads fine at .archon/unic-dlc.config.yaml"; guard-not-ready then cancelled the run, which is the designed outcome for a slug with no issues.json. The worktree was removed with archon complete … --force.

   The install sequence

   Run every command from the Consumer repo root. <PLUGIN> is apps/claude-code/unic-archon-dlc inside a unic-agents-plugins checkout.

   # 1. Confirm the ground.
   git remote get-url origin       # the repository the Boxes will act on
   archon --version                # 0.7.0 or higher
   
   # 2. Copy the four Boxes.
   mkdir -p .archon/workflows .archon/methods
   cp <PLUGIN>/.archon/workflows/unic-dlc-*.yaml .archon/workflows/
   
   # 3. Copy the Methods. The target directory is the Method's canonical name,
   #    which is not always its upstream directory name.
   for m in to-spec to-tickets triage code-review improve-codebase-architecture \
            implement tdd research domain-modeling codebase-design; do
     cp -R <PLUGIN>/vendor/mattpocock-skills/skills/engineering/$m .archon/methods/$m
   done
   cp -R <PLUGIN>/vendor/mattpocock-skills/skills/productivity/grilling .archon/methods/grilling
   cp <PLUGIN>/vendor/mattpocock-skills/LICENSE .archon/methods/LICENSE
   
   # 4. Write .archon/unic-dlc.config.yaml by hand.
   #    Field reference: <PLUGIN>/lib/config-schema.mjs. Read it; never run it.
   #    Mandatory: tracker.type, project.pr_strategy, project.branching,
   #    classification.labels (all 17 roles across the state/type/priority tiers).
   
   # 5. Verify.
   archon workflow list | grep unic-dlc
   for w in build qa pr-review explore; do archon validate workflows "unic-dlc-$w"; done

   Two things the sequence hides:

   • grilling is the only Method under skills/productivity/. The other ten sit under skills/engineering/.
   • Step 5 proves the Boxes load, not that the config parses. To prove that, commit and push the branch, then run any Box with a throwaway slug and read the bootstrap output. --from rejects a branch that exists only locally.

   What Azure DevOps does not give the DLC

   Nine findings. Each names the file and the node that assumes the missing thing.

   1. repo_ref is one string; Azure DevOps addresses a repository with three

   unic-dlc-build.yaml bootstrap step 4 derives repo_ref from git remote get-url origin. The run produced https://<org>@dev.azure.com/<org>/dxp/_git/DXP-DesignSystem. On GitHub that URL yields owner/repo, which is exactly what --repo takes. Azure DevOps needs organisation, project and repository as three separate arguments.

   Every node told to "name TARGET_REPO explicitly" passes one opaque string and no node is told to decompose it: unic-dlc-build.yaml open-pr and implement-review-precheck; unic-dlc-qa.yaml verify-pr-base, merge and uat-gate.on_reject; unic-dlc-pr-review.yaml prep and post; unic-dlc-explore.yaml spike-ticket.

   tracker.coords already holds {org, project, repo}, but only two nodes read it — unic-dlc-explore.yaml spike-ticket step 1 and unic-dlc-qa.yaml uat-gate.on_reject step 1 — and neither says to prefer it over repo_ref. The fix is a Harness rule, not a flag table: coords identifies the repository, repo_ref proves which one the checkout points at.

   2. The ambiguous-repo guard normalises GitHub spellings only

   Same step 4c in all four bootstrap nodes. It normalises a trailing .git, the user@host:path against https://host/path form, and case. Azure DevOps adds three spellings that survive all of it: the embedded user (https://<org>@dev.azure.com/…), the SSH form git@ssh.dev.azure.com:v3/<org>/dxp/DXP-DesignSystem which drops the _git segment, and the legacy https://<org>.visualstudio.com/dxp/_git/…. Two remotes naming one repository in two of those spellings read as two repositories, and the guard cancels a run that should proceed.

   DXP-DesignSystem has one remote, so the guard never fires today. It fires the first time anyone adds a second.

   3. Work items belong to the project, not to a repository

   unic-dlc-qa.yaml uat-gate.on_reject step 1 says "File every issue on $bootstrap.output.repo_ref". unic-dlc-explore.yaml spike-ticket step 2 says "Check whether a spike ticket for this SLUG already exists in TARGET_REPO". unic-dlc-build.yaml implement-review-precheck step 2 says "Read those issues from $bootstrap.output.repo_ref".

   An Azure DevOps work item has no repository field. Every work item in dxp is shared by DXP-DesignSystem, DXP-Website and DXP-ProfileServices. So "file it on TARGET_REPO" has no meaning to execute, and spike-ticket's idempotency search will match spike tickets filed from the other two repositories. The DLC needs a second scope — the area path, or a tag — to keep three repositories apart inside one project.

   4. Nothing links a branch, a commit or a PR back to the work item

   DXP-DesignSystem/CLAUDE.md sets branch naming as feature/<workitem-id>_<slug>. Archon names its worktree branch archon/task-<workflow>-<timestamp>, and unic-dlc-explore.yaml preserve-spike step 1 names its branch spike/<slug>. Neither carries a work-item id.

   On GitHub the PR body closes the issue by number. Azure DevOps links by AB#<id> in the commit message or PR text, or by an explicit work-item link on the PR. The PR body template in unic-dlc-build.yaml open-pr step 3 has no work-item reference at all, and the commit messages in run-build step 3 are test(<SLUG>) / feat(<SLUG>). Every artefact the DLC produces at the Consumer will therefore land unlinked, and unic-dlc-pr-review.yaml prep step 3a — which expects to find "linked work items … from the PR body, branch name, or tracker links" — will find none of the three.

   This is the finding with the largest day-to-day cost, and the cheapest fix: put AB#<id> in the PR body.

   5. The state tier has no Azure DevOps axis wide enough

   Decided in this ticket and written into the config as chosen: the state tier maps onto System.State, the type tier onto System.WorkItemType, the priority tier onto Microsoft.VSTS.Common.Priority.

   A User Story in dxp has the states New, Active, Resolved, Blocked, Ready for Test, Closed, Removed. Five of the eight state roles — needs-triage, needs-info, needs-specs, ready-for-agent, ready-for-human — all collapse onto New. Three of the five type roles — spike, tech-debt, docs — all collapse onto Task.

   So /triage cannot distinguish needs-triage from ready-for-agent, which is the one distinction /tickets and /build gate on. unic-dlc-qa.yaml uat-gate.on_reject step 3 writes state ready-for-agent and unic-dlc-explore.yaml spike-ticket step 3a writes type spike; both write a value that says nothing.

   Tags would carry all seventeen roles, but lib/config-schema.mjs LABEL_TIERS fixes one axis per tier, so a config cannot say "this role is a Tag and that one is a State". Widening that is a plugin decision, not a config edit.

   6. project.pr_strategy uses GitHub's merge vocabulary

   unic-dlc-qa.yaml merge reads project.pr_strategy and names its three values squash | merge | rebase. Azure DevOps completes a PR with noFastForward, squash, rebase or rebaseMerge. merge is not one of them. The Box forbids writing a flag, so the agent has to map the value at run time with nothing in the config telling it the vocabularies differ.

   DXP-DesignSystem has no branch policy on main, so nothing enforces a strategy either way. The config says squash, which is a value both hosts understand.

   7. A pull request has threads, not comments

   unic-dlc-pr-review.yaml post says "add SESSION/comment.md as a new PR-level comment" and, on a match, "update THAT comment's body in place". prep step 4 says "Scan the PR's existing comments/threads".

   Azure DevOps has no PR-level comment. It has threads, and a general comment is a thread with no threadContext. Each thread holds an array of comments, so the marker scan is two levels deep, and an update is a patch against a comment id inside a thread id. The Box's prose reads as one level.

   Everything the Box asks for is reachable — unic-pr-review's own ado-fetcher and ado-writer agents already walk exactly this shape. Nothing here blocks; the prose just does not describe what the agent will find.

   Thread resolution is the one place Azure DevOps is the richer host: post's hedge "resolve the thread where the tracker supports a resolved status" is satisfied, because a thread carries status: fixed | closed | active.

   8. Archon derives its workspace path from the second-to-last URL segment

   Not a DLC file, but it lands on the Consumer. The smoke run created its worktree at ~/.archon/workspaces/_git/DXP-DesignSystem/worktrees/…, against ~/.archon/workspaces/unic/unic-agents-plugins/… for this repo. Archon read _git as the organisation.

   dxp has three repositories under one _git segment, so they already share one workspace directory, and two same-named repositories in different Azure DevOps projects would collide outright. archon isolation list groups by remote URL, so /cleanup still reads correctly; the collision is in the filesystem layout.

   9. archon complete shells out to gh unconditionally

   Also Archon's, also landing on the Consumer, and the sharpest of the two. Removing the smoke worktree printed:

   Warning: gh error: Command failed: gh pr list --head archon/task-… --state open --json number,title
   none of the git remotes configured for this repository point to a known GitHub host.
    — skipping open PR check
   

   The open-PR check is how archon complete refuses to delete a branch with a live pull request. On an Azure DevOps remote it degrades to a warning and completes anyway. /cleanup composes archon complete for branch lifecycle, so at the Consumer that safety check is off, silently, and the transcript reads like a normal run. Treat /cleanup --apply as unguarded here until Archon fixes it.

   archon doctor reports gh CLI: GitHub not configured as ○, not a failure, and says "All checks passed" — so nothing at setup time warns that a lifecycle guard has been disabled.

   Not covered

   • No Box has been run end to end. bootstrap and one guard are all that executed.
   • /specs and /tickets are Claude Code commands, not Boxes; they are not installed by this sequence and were not exercised.
   • Archon 0.8.0 is out. Everything above was measured on 0.7.0.
7. orioltf commented on Aug 17, 2026

   

   orioltf

   on Aug 17, 2026

   MemberAuthor

   More actions

   Resolved. See the finding list above: the install stands, four Boxes discovered and validated, bootstrap reads the config. The tracker gaps are one decision, now #387, which blocks #379.
8. orioltf

   closed this as completedon Aug 17, 2026
9. orioltf commented on Aug 17, 2026

   

   orioltf

   on Aug 17, 2026

   MemberAuthor

   More actions

   Correction to finding 6. It closed with "The config says squash, which is a value both hosts understand." That is no longer true, and the finding is now live rather than latent.

   Unic merges with a merge commit and never squashes, so project.pr_strategy is merge (df68e2b). No Azure DevOps completion strategy carries that name — the one that produces a merge commit is noFastForward. So unic-dlc-qa.yaml merge now reads a value its host does not recognise, and the node is forbidden from writing the mapping as a flag.

   The config records the mapping in a comment next to the key. That is a note for a human, not something a node reads. Where the mapping belongs is part of #387.