chore: de-dogfood unic-archon-dlc and upgrade Matt's skills to upstream main

[orioltf]

Closes #297

Why

.agents/skills/ held a pre-v1.1 generation of mattpocock/skills. Upstream renamed and
deleted skills at v1.1.0 and again across the 101 commits since, so six installed skills no longer
existed upstream and fifteen were missing — including /wayfinder, /to-spec, /to-tickets and
/code-review. npx skills add never prunes, so a plain reinstall would have left the dead six
behind.

The upgrade could not land honestly on its own. /wayfinder reads a Wayfinding operations
section from docs/agents/issue-tracker.md, and that file was generated by unic-archon-dlc — a
plugin whose own doctrine forbids /triage from reading Matt's tracker docs and declares
setup-matt-pocock-skills a non-dependency. This repo was running both systems at once, with two
generators writing one set of files.

What changed

Three commits, in dependency order.

A — chore: upgrade Matt Pocock's skills to upstream main

26 skills: all of skills/engineering/ (18) and skills/productivity/ (7), plus
misc/git-guardrails-claude-code. Never skills/in-progress/ — the two in-progress skills the
previous install picked up (decision-mapping, review) had already been renamed or deleted
upstream, which is the argument for the rule. migrate-to-shoehorn is dropped deliberately: no
shoehorn dependency and no .test.ts file exists here, so it could never fire.

Removed	Successor
to-prd	to-spec
to-issues	to-tickets
write-a-skill	writing-for-agents
diagnose	diagnosing-bugs
caveman, zoom-out	none

B — chore: de-dogfood unic-archon-dlc

unic-archon-dlc is a product built in this repo, not a driver run against it. Deleted fourteen
.archon/unic-dlc-* artefacts, both unic-dlc.config.* files, .archon/ralph/,
docs/agents/workflow.md (documented the retired seven-workflow generation) and
docs/agents/branching.md (Gitflow table duplicated verbatim in AGENTS.md), plus the plugin's
"Dogfooding note" doctrine. docs/agents/{labels,domain}.md survive as hand-owned files.

Recorded as ADR-0033, with ADR-0032 amended rather than superseded: its four-tier taxonomy
stands, but tiers 1-3 move to repo ownership, wayfinder:* is admitted as a fifth tool-scoped
namespace, and 0032's own "do not re-run /setup-matt-pocock-skills" warning is resolved by never
re-running it. 0032's Context and Decision are untouched, so the label-migration record it explains
stays intact.

C — docs: enable /wayfinder and rename to-prd/to-issues

docs/agents/issue-tracker.md hand-authored from upstream's v1.1 GitHub template, with the full
Wayfinding operations section, PRs-as-a-request-surface set to yes, and the dissolved
lib/tracker-adapter.mjs reference dropped. Renames across CONTRIBUTING.md, ONBOARDING.md and
both docs/process/ guides.

Notes for review

• skills remove is 2-for-3. It cleans the .claude/skills/<name> symlink and the
  skills-lock.json entry, but leaves the .agents/skills/<name> source directory orphaned. Each
  removal needs a git rm -r alongside it. Its -s flag also rejects a comma list and -a '*',
  both of which add accepts. That procedure is now written into AGENTS.md.
• Three untracked .archon/ workflow copies were deleted and do not appear in this diff:
  copy-fix-github-issue.yaml, unic-pr-review.yaml, unic-archon-pr-review.yaml. Nothing
  referenced them by filename; /archon-rollout dispatches the native archon-fix-github-issue.
• Corrected in passing: CONTRIBUTING.md and both process guides promised unic-dlc-build as
  this repo's future AFK runner. ADR-0033 makes that false; the AFK path here is /archon-rollout,
  which is what has actually been in use.
• Historical records are left as written — docs/issues/**, docs/research/,
  docs/conversations/, .out-of-scope/. They describe what was true when written.
• Losing dogfooding costs coverage. No Consumer-shaped repo exercises the plugin's /setup on
  every change any more. ADR-0033 names this as the price and points at a scratch clone instead.

Verification

Check	Result
pnpm ci:check	exit 0, Prettier clean
pnpm test	exit 0
pnpm typecheck	exit 0
pnpm --filter unic-archon-dlc test	209 pass, 0 fail
jq '.skills|keys|length' skills-lock.json	26, all paths under engineering/productivity/misc
Dangling .claude/skills symlinks	none
grep -rln "AUTO-GENERATED by unic-archon-dlc" docs/	only a historical PRD that quotes the banner

Still to do, after merge

Create the five wayfinder:* labels with gh label create — wayfinder:map,
wayfinder:research, wayfinder:prototype, wayfinder:grilling, wayfinder:task. Held back
deliberately: label creation mutates the live repo and reverting this PR would not undo it.

Then the real end-to-end test: run /wayfinder on a throwaway idea and confirm the map issue, a
child sub-issue, and a native blocked_by edge all land.

🤖 Generated with Claude Code

---

D — docs: correct output claims the rename glossed over (added after review)

A wide re-read found the rename was lexical where it needed to be behavioural. Six defects, none
catchable by CI:

1. to-spec/to-tickets no longer write files. They publish GitHub issues with native
   sub-issue and blocking links; local-file mode writes .scratch/, not docs/issues/<slug>/. Four
   docs claimed the old contract.
2. Both apply ready-for-agent themselves, which under our 8-state vocabulary is a triage
   decision. Docs now say treat it as a proposal — worth a policy call separately.
3. triage-labels.md didn't map the roles the v1.1 skill names. Keyed on prose, so wontfix
   had no row; and category role enhancement had no mapping, risking recreation of the label
   ADR-0032 deleted.
4. docs/agents/feature-runner.md was missed by the earlier sweep — same false unic-dlc-build
   promise.
5. CONTEXT-MAP.md still called the label tiers "archon-owned".
6. A ../../../../ link in unic-confluence/CONTRIBUTING.md pointing above the repo root — a
   pre-existing bug preserved when repointing.

Plus: removed a top-level agent/skills/ tree of frontmatter-rewritten duplicates that
skills add -a '*' created in commit A. AGENTS.md now documents -a claude-code as the correct
target and the two other CLI traps.

[orioltf]

🔍 Comprehensive PR Review

PR: #298 · Reviewed by: 5 specialised agents · Date: 2026-08-05
Base/head: 39080fb → 17489d9 · CI: 15/15 green

---

Summary

No repo-authored executable code changes here: 20 dead .archon/ artefacts deleted, docs/agents/*.md
re-homed from generator-owned to repo-owned, the vendored mattpocock/skills tree upgraded to upstream
main (17 → 26 skills), and fifteen repo docs rewritten to name the renamed skills. The structural work is
verified, not asserted: 26 lockfile keys == 26 .agents/skills/ directories == 26 .claude/skills/
symlinks, one-to-one, no orphans, no dangling links, and the installed set matches upstream's engineering/

• productivity/ trees plus one misc/ entry exactly. ADR-0032 is amended rather than rewritten, and every
  deletion is accounted for in ADR-0033.

Two defects block, both cheap and both inside the diff:

1. The new Wayfinding operations section prescribes gh issue create --label wayfinder:map against five
   wayfinder:* labels that do not exist on this tracker — confirmed live by two agents independently.
   The first documented /wayfinder step fails, so ADR-0033's headline consequence is unearned.
2. README.md is the only file still advertising the two docs/agents/ files this PR deletes.

Everything else is an upstream-owned defect that must not be patched here, an acceptance criterion whose
literal wording the shipped state deliberately improves on, or a missing regression guard.

Verdict: REQUEST_CHANGES

Severity	Count
🔴 CRITICAL	0
🟠 HIGH	3
🟡 MEDIUM	12
🟢 LOW	15

30 distinct findings (32 raw; two pairs deduplicated). Per-agent verdicts: code-review APPROVE,
error-handling APPROVE, test-coverage APPROVE, comment-quality REQUEST_CHANGES, docs-impact
UPDATES_REQUIRED.

---

🟠 High Issues

H1 · Wayfinding operations prescribes five wayfinder:* labels that do not exist

📍 docs/agents/issue-tracker.md:44, docs/agents/labels.md:7, ADR-0032 §Amendment, ADR-0033 §Consequences
🔬 comment-quality (HIGH) + docs-impact (MEDIUM), deduplicated

gh label list --limit 100 returns 31 labels — 8 state, 6 type, 4 priority, 10 area, repo, plus
Dependabot's two. Zero wayfinder:*. gh issue create --label wayfinder:map exits non-zero with
could not add label: 'wayfinder:map' not found and creates nothing.

ADR-0033 records that the live verification covered "GitHub sub-issues and native issue-dependency
endpoints" — both real — and concludes "/wayfinder becomes usable". The labels were not part of that
verification, and they are the first write the skill makes. /wayfinder is now the recommended entry point
in AGENTS.md, CONTRIBUTING.md and ONBOARDING.md.

View fix

The two agents split on whether to create the labels in this PR. Recommendation: document the
prerequisite in-diff, decide on creating the labels separately — that keeps the PR revertible, which is
why the creation was held back in the first place.

In docs/agents/issue-tracker.md, § Wayfinding operations:

Prerequisite: the five labels do not exist yet. Create them once, before the first /wayfinder run —
label creation mutates the live repo, so it is held out of the PR that documented this flow:

gh label create wayfinder:map       --description "Wayfinder map issue"
gh label create wayfinder:research  --description "Wayfinder child ticket: research"
gh label create wayfinder:prototype --description "Wayfinder child ticket: prototype"
gh label create wayfinder:grilling  --description "Wayfinder child ticket: grilling"
gh label create wayfinder:task      --description "Wayfinder child ticket: task"

In docs/agents/labels.md:7, extend the existing sentence: "… /wayfinder owns their lifecycle, and they
are created by hand once (see Wayfinding operations)."

In ADR-0033 Consequences: "/wayfinder becomes usable once the five wayfinder:* labels exist."

If you create the labels at merge time instead, soften the doc to "are a one-off setup, already applied to
this repo".

---

H2 · block-dangerous-git.sh fails open — a missing jq allows git push --force

📍 .agents/skills/git-guardrails-claude-code/scripts/block-dangerous-git.sh:3-4,25
🔬 error-handling · upstream-owned — do not patch here

The hook derives the command with jq and never checks that the extraction worked. No set -euo pipefail.
With jq absent, COMMAND is empty, no pattern matches, and the script reaches exit 0 — which a
PreToolUse hook means as allow.

View reproduction and fix

Reproduced three ways:

$ echo '{"tool_input":{"command":"git push --force origin main"}}' | env PATH=/tmp/nojq /bin/bash bdg.sh
bdg.sh: line 4: jq: command not found
status=0        # 0 = allow. The force-push proceeds.

$ echo 'not json' | bash bdg.sh
jq: parse error: Invalid numeric literal at line 1, column 4
status=0        # allow

$ echo '{"tool_input":{"command":"git -C . push origin main"}}' | bash bdg.sh
status=0        # allow — the patterns are unanchored substrings

Hook stderr on a pass is not surfaced, so the guardrail's absence looks exactly like its presence. The
bundled verification (SKILL.md step 5) tests only the happy path. The same substring matching also blocks
echo "remember to git push later" (reproduced, exit 2), which trains users to disable the hook.

Fix path: report upstream to mattpocock/skills — set -euo pipefail, a command -v jq precondition,
and a fail-closed default. Interim: a one-line jq-prerequisite caveat in the AGENTS.md upgrading
section. AGENTS.md:172 says edits under .agents/skills/** die silently on the next npx skills add, so
a local patch is the one fix guaranteed to disappear.

Not a blocker on this PR — the defect ships with the upstream tree, and exposure is opt-in today: the
PR does not wire the hook into .claude/settings.json.

---

H3 · README.md advertises two docs/agents/ files this PR deletes

📍 README.md:59 · 🔬 docs-impact

README.md is the only doc still naming docs/agents/branching.md and docs/agents/workflow.md. Every
other reference was repointed. A reader following the inventory looks for two files that are gone and never
learns about triage-labels.md and feature-runner.md. AGENTS.md:161-165 lists the correct five, so an
agent reading both gets two answers.

View fix

├── agents/               # Agent skill documentation (indexed in AGENTS.md § Agent skills)

One owner for the index, one link — rather than a second enumeration that can drift again.

---

🟡 Medium Issues (12)

M1 · setup-matt-pocock-skills stays installed while four vendored prompts tell agents to run it

📍 AGENTS.md:175 and :179, .claude/skills/setup-matt-pocock-skills, skills-lock.json
🔬 code-review + docs-impact, deduplicated

AGENTS.md and ADR-0033 forbid running it — a run reverts docs/agents/triage-labels.md to the five-role
wontfix vocabulary. The skill remains installed and invocable, and four upstream skills instruct an agent
to invoke it on a missing tracker or label mapping (triage/SKILL.md:43, wayfinder/SKILL.md:25,
to-tickets/SKILL.md:11, to-spec/SKILL.md:9). The guard is one table row against four contrary prompts.
The failure has a precedent: ADR-0032's amendment records that the 8-state reconciliation was silently lost
in 2026-08 for exactly this reason.

Option	Approach	Effort	Risk if skipped
A	Uninstall (skills remove + git rm -r)	LOW	—
B	Name the exception in the selection policy, keep it installed	LOW	Prose guard only, against four contrary prompts
C	PreToolUse hook blocking the invocation	MED	—

The two agents split: code-review preferred A (make it a property of the tree, not a rule about it);
docs-impact preferred B (it is the reference docs/agents/*.md was hand-authored from). Both agree the
selection policy must name the exception either way — that is the one-clause change this PR is missing.
Recommendation: B now, A as a separate decision.

Adjacent: git-guardrails-claude-code is a skills/misc/ entry, and AGENTS.md:179 admits misc/ only
"by explicit justification". None is recorded. Worth one clause in the same edit.

M2–M5 · four error-handling defects in the vendored wizard and HITL scripts (upstream-owned)

All four were reproduced locally. None should be patched here — AGENTS.md:172.

• M2 · wizard/template.sh:78-88 — open_url prints "↗ opening <url>", then runs its opener chain
  inside a brace group redirected to >/dev/null 2>&1. The else branch calls warn, which writes to
  stdout, so the fallback warning goes to /dev/null too; the brace group exits 0 and the trailing
  || warn never fires. Nothing opens, nothing is said. Root cause is warn on stdout, not the brace group.
• M3 · wizard/template.sh:105-147 — ask/ask_secret end with read -r input || true. Nothing
  distinguishes "the human pressed Enter" from "there is no human". On EOF, write_env writes KEY=, prints
  a green ✓ wrote, and exits 0. For ask_secret there is no echo, so nothing on screen ever hinted the
  value was empty. Fix: [[ -t 0 ]] guard plus write_env refusing empty values into SKIPPED.
• M4 · wizard/template.sh:151-176 — set_secret/set_var run the write with >/dev/null 2>&1 and
  funnel every non-zero exit into "gh not ready; set it later". The write can fail with gh perfectly ready
  — no origin remote, insufficient scope, wrong repo resolved, rate limit, SSO-gated org. The human
  re-authenticates, succeeds, re-runs, gets the same line. Fix: split the two cases, surface gh's stderr
  (safe — the value goes in on stdin, not argv).
• M5 · diagnosing-bugs/scripts/hitl-loop.template.sh:17-27,40-42 — bare read -r -p under
  set -euo pipefail. On EOF the script dies before the --- Captured --- block that is its entire output
  contract. The documented usage is "the agent runs the script", so without a tty every run dies at the first
  prompt and the calling agent sees exit 1 with no parseable output. Fix: tty guard plus an EXIT trap.

Note the inconsistency: wizard/template.sh writes read -r input || true everywhere,
hitl-loop.template.sh writes bare read. Same upstream release, opposite handling, no diagnostic in
either. One upstream report covers M2–M5 plus L5.

M6 · the three-way skills invariant is hand-verified and CI cannot see it

📍 skills-lock.json, .claude/skills/*, .agents/skills/** — no test file · 🔬 test-coverage

Three sets must agree: lockfile keys, source directories, symlinks. The PR body verifies all three by hand
and they pass — but the same PR documents two tool behaviours that break the invariant silently:
npx skills remove orphans .agents/skills/<name>, and npx skills add -a '*' wrote a second
frontmatter-rewritten tree at the repo root (deleted by hand in commit D). Both are one forgotten flag away
from recurring, and both are pure filesystem facts.

Two prerequisites a naive implementation misses: CI's changes filter has no entry for
.agents/skills/**, skills-lock.json or .claude/**, so a test in an existing package would never fire
on the change it guards; and Windows checkouts with core.symlinks=false materialise symlinks as text
files, so assert "entry exists, and if it is a symlink its target resolves", not isSymbolicLink().
Recommend a node:test file — full body in the artifact. Follow-up, not this PR.

M7 · no markdown link check, on a PR whose main risk is broken links

📍 .github/workflows/ci.yml:20 · 🔬 test-coverage

pnpm ci:check runs Biome plus prettier --check on Markdown. Prettier validates formatting, not link
targets. This PR deletes two documents, renames five skills, and repoints references across fifteen docs.
Commit D found a ../../../../ root-escaping link by re-reading, not by tooling.

A scan over 315 Markdown files at the head tree found 49 broken relative links, 0 introduced by this PR
— 48 pre-exist on develop (apps/claude-code/unic-archon-dlc/commands/*.md write repo-root-relative
docs/adr/00NN-*.md links from a commands/ file, so an agent cannot open the ADR it is told to consult),
plus one root escape in .claude/skills/archon/guides/slack.md. The check cannot switch on red, so pair it
with fixing the 48 — all one prefix wrong. Follow-up.

M8 · de-dogfooding removes the plugin's only live /setup exercise

📍 docs/adr/0033-de-dogfood-unic-archon-dlc.md, apps/claude-code/unic-archon-dlc/ · 🔬 test-coverage

The generated .archon/ artefacts and docs/agents/* files were the only observable output of
unic-archon-dlc's /setup. ADR-0033 names the price and points at a scratch clone — but no doc says how to
make that clone or what to run in it, and a note in an ADR is not a step anyone performs. The plugin's 209
tests cover lib/ completely and cannot reach /setup, which is a Markdown prompt.

The failure mode is on record here: /setup never installed the Archon artefacts despite the README
promising it, and a hand-seeded .archon/ hid the gap for two and a half months — found by inspecting this
repo's own generated files, the exact signal this PR removes. Recommend promoting the scratch-clone run into
the plugin's release checklist. Accepting the trade-off is your call; the finding asks only that the
mitigation become a step.

M9 · ai-development.md still defines a Feature Runner as "the skill"

📍 docs/process/ai-development.md:9 · 🔬 comment-quality

This PR rewrote root CONTEXT.md from "The skill that implements…" to "Whatever implements…", precisely so
a human driver counts as a runner. The definition sentence here kept the old wording while citing that same
file, and the paragraph six lines below names a developer as one of the two runners. A developer is not a
skill.

Fix — mirror the glossary verbatim, since paraphrase is what let it drift:

A Feature Runner is whatever implements a Feature's Issues end-to-end in one worktree, branch, and
pull request (see root CONTEXT.md).

M10 · two Wayfinding operations bullets hand-wave the command their siblings spell out

📍 docs/agents/issue-tracker.md:45, :47 · 🔬 comment-quality

This file is a runtime reference — an agent reads it mid-session. The Blocking bullet is exemplary: full
gh api invocation, the blocked_by endpoint, and the database-id-not-#number trap called out. The two
bullets that need the sub-issues endpoint just name it. gh issue list has no sub-issue filter, so "scoped
to the map's sub-issues" is not executable as written; the link step needs POST …/sub_issues with a numeric
database id — the same trap the neighbouring bullet documents and this one omits.

The asymmetry actively misleads: the exactness of the sibling reads as a promise that anything left vague
did not need spelling out. Spell out both gh api calls and state the database-id rule once for all three.

M11 · the workflow docs call /to-tickets the only gate, but /to-spec also publishes ready-for-agent

📍 docs/process/development-workflow.md:47, docs/process/ai-development.md:81, ONBOARDING.md:66,
docs/agents/triage-labels.md:39 · 🔬 comment-quality

.agents/skills/to-spec/SKILL.md step 3 applies ready-for-agent too, and its only in-session check is
about test seams — not the spec body. So a spec issue lands carrying the label, in the same query
/archon-rollout sweeps, with no ## What to build / ## Acceptance criteria shape and no ## Blocked by
edges. Dispatching one sends an agent at a whole feature described as user stories.

Recommend documenting it in this PR (say what the label actually means there, and that a rollout skips
the spec issue) and filing the /archon-rollout selection change as a follow-up — that is command work
with its own acceptance criteria. The docs currently assert a guarantee that does not hold, which is worse
than silence.

M12 · README.md still lists Ralph as a prerequisite

📍 README.md:35, docs/process/spec-template.md:15 · 🔬 docs-impact

ralph-orchestrator was retired in ADR-0009 and this PR deletes its final artefacts (.archon/ralph/, four
files), so nothing in the tree needs the Claude Code CLI "for Ralph". spec-template.md carries the same
residue — "Ralph uses this to verify the starting state". The template is orphaned (no live doc links it),
which is why earlier sweeps missed it. Whether it survives at all is a separate call.

---

🟢 Low Issues

View 15 low-priority findings

#	Issue	Location	Agent	Suggestion
L1	branching.md's merge-strategy fact did not survive the deletion	AGENTS.md:90	code-review	Add: "PRs merge with a merge commit, never a squash — the release flow reads develop → main merges." Criterion 3 is the only justification offered for deleting the file
L2	triage-labels.md was rewritten, though criterion 8 says "unchanged"	docs/agents/triage-labels.md	code-review	Amend criterion 8 on #297, not the file — the rewrite realigns role names to .agents/skills/triage/SKILL.md (2 category + 5 state roles, exact match) and preserves the 8-state/rejected outcome the criterion protects
L3	criterion 2's grep still matches a historical PRD	docs/issues/unic-archon-dlc-dogfood-banner/PRD.md	code-review	Scope criterion 2's grep to docs/agents/ — the hit is a quoted string in a retired spec the scope places out of bounds
L4	ONBOARDING.md still names /to-prd and /to-issues	ONBOARDING.md:27, :52-53	code-review	Amend criterion 9 to "never as an instruction; historical rename notes are fine" — all three are rename notes a new joiner reading old issues needs
L5	_existing's guard is load-bearing on pipefail	.agents/skills/wizard/template.sh:98-102	error-handling	Upstream-owned. Fold into the M2–M5 report as a one-line note; not worth its own issue
L6	a hand-edit to a vendored skill dies silently and CI stays green	AGENTS.md:172, .agents/skills/**	test-coverage	PR-scoped rule: a diff touching .agents/skills/** must also touch skills-lock.json. Precise, no false positives — skills add always rewrites the hashes. A deny-list grep was tested and rejected: every surviving mention of the old names is a deliberate negation
L7	Phase 3 sends /research output to a plugin directory	docs/process/development-workflow.md:32	comment-quality	Point at docs/research/, which AGENTS.md:32 declares and the skill's "match the existing convention" rule already finds. The "delete when shipped" rule must not read as applying there
L8	the Feature Runner table keeps a stale completion marker	docs/process/ai-development.md:20	comment-quality	`resolved` label on the issue, or `Status: resolved` in the ticket file — the Input row already carries both modes
L9	Phase 5 omits Testing Decisions and Further Notes	docs/process/development-workflow.md:47	comment-quality	List all seven template sections. Testing Decisions carries the seams into /tdd — the omission understates the seams check in the next clause
L10	labels.md scopes app:<plugin> to apps/claude-code/, but a live label has no app there	docs/agents/labels.md:31	comment-quality	Note app:unic-ticket-specification as the exception. Deleting the label drops it off every issue carrying it — history loss for a docs-only PR
L11	the ownership table's .claude/skills/* row covers three repo-local dirs it does not own	AGENTS.md:172	comment-quality	Split into two rows: npx skills-managed symlinks, and repo-authored directories (archon, new-plugin, verify-spec). The (symlinks) qualifier is doing all the work the glob does not
L12	docs/adr/README.md does not describe the amend-in-place pattern ADR-0032 now uses	docs/adr/README.md:10,30-33	docs-impact	Add the pattern to "Amending records" and the two-clause status-line variant to the Format block. Otherwise amend and supersede diverge without a rule
L13	repo-owned verify-spec still assumes specs land as docs/issues/<slug>/PRD.md	.claude/skills/verify-spec/SKILL.md:3,22,26-31	docs-impact	State the scope limit now (two lines); file a follow-up for the gh issue view fallback. Today it reports "no file matches" on a /to-spec Feature, which reads as a missing spec rather than an unsupported location
L14	AGENTS.md workspace tree lists a docs/plans/ that does not exist	AGENTS.md:30	docs-impact	Delete the row. README.md:56-64 has the same tree without it, so the two disagree
L15	README.md plugin table omits unic-spec-review	README.md:9-13, :26-30	docs-impact	Add the row and install line while you are in the file for H3 and M12; otherwise defer to a docs issue

L2, L3 and L4 recommend amending issue #297's acceptance criteria, not changing the branch — in each
case the shipped state deliberately improves on the criterion's literal wording.

---

✅ What's Good

• The upstream sync is verifiable, not asserted. The installed set is exactly upstream's engineering +
  productivity trees plus the one misc skill; each of the four removed skills (caveman, to-issues,
  write-a-skill, zoom-out) is genuinely absent upstream. Symlinks, source dirs and lockfile entries agree
  one-to-one — 26 / 26 / 26. Two agents re-ran this independently.
• issue-tracker.md tracks the template it claims to. Section for section against upstream's GitHub
  template, both fallbacks dropped with a stated reason, the PRs as a request surface flag set to yes,
  and the Destination heading wayfinder/SKILL.md expects but the template omits.
• ADR-0032 is amended, not rewritten. Status line plus an appended dated amendment; Context and Decision
  byte-identical. It also corrects its own superseded "three-tier" wording and explains why the earlier
  reconciliation vanished — turning a bug report into a durable rule.
• ADR-0033 records the cost, not just the win. "Losing dogfooding costs coverage … that is a real
  regression in confidence" is the line most ADRs omit, and it is what makes the decision auditable later.
• AGENTS.md § "Three traps the CLI sets" is high-value operational documentation. Each trap states the
  failing invocation, the symptom, and the fix. -s a,b,c "reports 'no matching skills found' and exits 0"
  is precisely the silent-failure detail that costs an hour to rediscover.
• Every AUTO-GENERATED header is removed, and each surviving file gains the same Repo-owned. Hand-maintained line. Five files, five identical lines — the discipline that makes a doc set greppable.
• The reference graph is clean. No live doc still points at docs/agents/workflow.md,
  docs/agents/branching.md, .archon/unic-dlc.config.*, /to-prd, or /to-issues. Both new cross-doc
  anchors resolve, and a pre-existing broken link was fixed in passing.
• ONBOARDING.md annotates its own stale data rather than swapping names and leaving the numbers looking
  freshly measured.
• No test regression is possible — no executable file changed, and no test reads a path the PR deletes;
  both verified, not inferred. unic-archon-dlc keeps its 1:1 module-to-test mapping (9 lib/, 9 test/).
• Removing 20 unexercised .archon/ workflow files is a net reduction in silent-failure surface.

---

📋 Suggested Follow-up Issues

Issue title	Type	Priority	Finding
Report five error-handling defects to mattpocock/skills, add a jq prerequisite caveat	bug	P1	H2, M2–M5, L5
Guard the three-way skills invariant with a node:test and a CI changes filter entry	tech-debt	P2	M6
Add a relative-link check over repo-owned Markdown, fix the 48 pre-existing breaks	tech-debt	P2	M7
Write the scratch-Consumer-clone procedure into unic-archon-dlc's release checklist	docs	P2	M8
Skip spec parents and wayfinder:map in /archon-rollout issue selection	feature	P2	M11
Teach /verify-spec to read acceptance criteria off a GitHub issue	feature	P3	L13

Decide separately, not as issues: whether to uninstall setup-matt-pocock-skills (M1 Option A), and whether
to create the five wayfinder:* labels at merge time (H1).

---

Next Steps

1. Fix in this PR — H1 and H3. The REQUEST_CHANGES verdict rests on these two.
2. Fix in this PR if you agree — M1's selection-policy clause, M9, M10, M11 (document-only half), M12,
   and the ten LOW prose edits. All are self-contained edits to files the PR already touches.
3. Amend issue tech-debt(repo): de-dogfood unic-archon-dlc — one agent-skill driver, not two #297 — criteria 2, 8 and 9 (L2, L3, L4). The shipped state is better than the wording.
4. Do not patch here — H2, M2–M5, L5. .agents/skills/** is upstream-owned; AGENTS.md:172 states
   edits die silently on the next npx skills add. One upstream report covers all six.
5. File the six follow-up issues above.

CI is 15/15 green and nothing here contradicts that. No finding in this review is reachable by pnpm check:
it runs Biome plus Prettier-on-Markdown only, with no shell linting and no link checking — which is exactly
what M6 and M7 propose to close.

---

Reviewed by the Archon comprehensive-pr-review workflow
Artifacts: artifacts/runs/5ae414bc6ba4da448c05f12fd50d0c02/review/

[orioltf]

⚡ Auto-Fix Report

Status: COMPLETE for CRITICAL + HIGH
Pushed: ✅ 17489d9..fb2e0d2 on feature/de-dogfood-dlc-and-upgrade-methods — base develop, MERGEABLE

---

Fixes Applied

Severity	Fixed	Documented instead	Skipped
🔴 CRITICAL	0	0	0 — none found
🟠 HIGH	2	1	0

Five docs changed, +24 −6. No executable code in this PR, so no unit is under test and no test was added —
reasoning below.

What was fixed

• ✅ H1 · Wayfinding operations prescribed five wayfinder:* labels that do not exist
  (docs/agents/issue-tracker.md, docs/agents/labels.md, docs/adr/0033-de-dogfood-unic-archon-dlc.md)
  Re-verified live before editing: gh label list --limit 100 returns 31 labels, zero wayfinder:*. Added
  a Prerequisite block carrying the five gh label create commands and the reason the creation is held
  back; matched the note in labels.md; softened ADR-0033's Consequences from "/wayfinder becomes
  usable" to "… once the five wayfinder:* labels exist", naming the one remaining prerequisite.
  The labels themselves are not created — that mutates the live tracker and a revert would not undo it.
  Run the five commands at merge time, then change "do not exist yet" to "already applied to this repo".

• ✅ H3 · README.md advertised the two docs/agents/ files this PR deletes (README.md:59)
  Replaced the drifted enumeration with a pointer at the AGENTS.md § Agent skills index — one owner for
  the list, rather than a second copy that can drift again.

• ⚠️ H2 · block-dangerous-git.sh fails open — a missing jq allows git push --force
  (AGENTS.md § Upgrading, new ### Vendored hook caveat section)
  The script is upstream-owned and AGENTS.md:172 states edits under .agents/skills/** die silently on
  the next npx skills add, so the code fix cannot land here — it goes upstream. What landed is the
  prerequisite and the test that catches it: confirm jq resolves for the hook runner, then pipe a payload
  in with jq off the PATH and expect a non-zero exit. The skill's own verification step only tests
  the matching-command path, so installing it appears to confirm protection that is conditional on jq.

Tests added

None. The PR changes no executable code, and all three HIGH fixes are prose in Markdown.

The two structural guards the review asked for are follow-ups, each because of a prerequisite that makes it
a separate change: M6 (three-way skills invariant) needs a new CI changes filter entry for
.agents/skills/**, skills-lock.json and .claude/** — without it a test placed in an existing package
never fires on the change it guards; M7 (Markdown link check) cannot switch on green until the 48
pre-existing broken links on develop are fixed.

---

❌ Not Fixed (Manual Action Required)

• H2 code fix — upstream. Open an issue on mattpocock/skills with the recorded reproduction (three
  cases: jq absent, malformed payload, git -C . push slipping the unanchored substring patterns) asking
  for set -euo pipefail, a command -v jq precondition, and a fail-closed default. Fold in M2–M5 and
  L5 — one report covers all six defects in that tree. Exposure here is opt-in: the hook is not wired into
  .claude/settings.json.
• H1 label creation — your call, one command block, best run at merge time.

---

🟡 MEDIUM Issues (Your Decision — 12)

Six are self-contained prose edits you may want in this PR; six are upstream-owned or follow-up work.

Issue	Options
M1 · setup-matt-pocock-skills installed while four vendored prompts recommend running it	Name the exception in the selection policy (both agents agree this is needed either way) / uninstall / block with a hook
M2–M5 · four error-handling defects in the vendored wizard and HITL scripts	Upstream only — do not patch here
M6 · three-way skills invariant hand-verified, CI blind to it	Follow-up: node:test plus the CI changes filter entry
M7 · no Markdown link check on a rename-heavy PR	Follow-up: link check + fix the 48 pre-existing breaks
M8 · de-dogfooding removes the only live /setup exercise	Follow-up: promote the scratch-clone run into the release checklist
M9 · ai-development.md:9 defines a Feature Runner as "the skill"	Fix now — one sentence, mirrors CONTEXT.md
M10 · two Wayfinding operations bullets hand-wave their gh api calls	Fix now — three lines
M11 · docs call /to-tickets the only gate, but /to-spec also labels ready-for-agent	Document now + file the /archon-rollout selection change
M12 · README.md:35 still lists Ralph as a prerequisite	Fix now — two lines

LOW (15): unchanged. L2, L3 and L4 recommend amending issue #297's acceptance criteria (8, 2 and 9)
rather than the branch — the shipped state deliberately improves on each criterion's literal wording.

---

📋 Suggested Follow-up Issues

1. Report five error-handling defects to mattpocock/skills, fix block-dangerous-git.sh fail-open (bug, P1) — H2, M2–M5, L5
2. Guard the three-way skills invariant with a node:test and a CI changes filter entry (tech-debt, P2) — M6
3. Add a relative-link check over repo-owned Markdown, fix the 48 pre-existing breaks (tech-debt, P2) — M7
4. Write the scratch-Consumer-clone procedure into unic-archon-dlc's release checklist (docs, P2) — M8
5. Skip spec parents and wayfinder:map in /archon-rollout issue selection (feature, P2) — M11
6. Teach /verify-spec to read acceptance criteria off a GitHub issue (feature, P3) — L13

---

Validation

Check	Command	Result
Format + lint	pnpm ci:check	✅ exit 0 — Biome 255 files, 5 infos, 0 errors; Prettier clean
Type check	pnpm typecheck	✅ exit 0 — all five plugin projects
Tests	pnpm test	✅ exit 0 — 1792 pass, 0 fail
Build	—	N/A — no build step in this repo (format check ci:check test typecheck are the only root scripts)

pnpm format ran before checking, because Prettier repads Markdown tables and a one-cell edit can
otherwise fail the root check. It reported every file unchanged.

---

Auto-fixed by the Archon comprehensive-pr-review workflow
Fixes pushed to feature/de-dogfood-dlc-and-upgrade-methods as fb2e0d2

[Copilot]

Pull request overview

This PR removes unic-archon-dlc dogfooding artifacts from the monorepo and upgrades the vendored mattpocock/skills set to upstream, then updates repo-owned docs/ADRs to reflect the new single-driver setup and the /to-spec + /to-tickets + /wayfinder workflow.

Changes:

• De-dogfood unic-archon-dlc by deleting generated .archon/unic-dlc.* config/workflows/commands and removing auto-generated docs/agents/{workflow,branching}.md.
• Add ADR-0033 and amend ADR-0032 to record the new ownership split (repo-owned docs/agents/*.md, upstream-owned .agents/skills/**) and wayfinder:* labeling.
• Upgrade/rename skills (to-prd→to-spec, to-issues→to-tickets, etc.) and update onboarding/contributing/process docs to match.

Reviewed changes

Copilot reviewed 149 out of 150 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
README.md	Updates prerequisites and clarifies docs/agents role.
ONBOARDING.md	Renames skills and updates the delivery flow description.
docs/research/running-your-afk-agent.md	Adds an AFK-agent research note.
docs/agents/workflow.md	Deletes DLC-generated workflow doc.
docs/agents/triage-labels.md	Rewrites mapping to align with 8-state + rejected label vocabulary.
docs/agents/labels.md	Converts from generated 3-tier to repo-owned 4-tier (+ wayfinder namespace).
docs/agents/issue-tracker.md	Replaces DLC-generated tracker doc with repo-owned GitHub + wayfinder operations.
docs/agents/feature-runner.md	Updates runner guidance to /archon-rollout and manual /tdd//implement.
docs/agents/domain.md	Strips generator header; asserts repo ownership.
docs/agents/branching.md	Deletes DLC-generated branching doc.
docs/adr/README.md	Adds “amend in place” policy for ADR maintenance.
docs/adr/0033-de-dogfood-unic-archon-dlc.md	New ADR recording de-dogfooding decision.
docs/adr/0032-label-taxonomy.md	Adds amendment section describing ownership shift and wayfinder:* namespace.
CONTRIBUTING.md	Updates workflow docs to /wayfinder → /to-spec → /to-tickets → /archon-rollout.
CONTEXT.md	Updates “Feature” and “Feature Runner” definitions to GitHub-issue-first model.
CONTEXT-MAP.md	Updates label-tier ownership wording post de-dogfooding.
apps/claude-code/unic-confluence/CONTRIBUTING.md	Fixes planning link to point at current process doc.
apps/claude-code/unic-archon-dlc/AGENTS.md	Removes dogfooding claim; documents monorepo is not a Consumer.
AGENTS.md	Removes DLC markers; documents ownership split and upgrade procedures for skills.
.claude/skills/verify-spec/SKILL.md	Clarifies that verify-spec reads spec files only (not GitHub issues).
.claude/commands/archon-rollout.md	Points branching topology ownership at root AGENTS.md instead of deleted doc.
.archon/workflows/unic-dlc-triage.yaml	Deletes DLC workflow.
.archon/workflows/unic-dlc-cleanup.yaml	Deletes DLC workflow.
.archon/unic-dlc.config.yaml	Deletes DLC config.
.archon/unic-dlc.config.json	Deletes DLC config.
.archon/ralph/setup-slash-command/prd.md	Deletes archived Ralph PRD artifact.
.archon/commands/unic-dlc-triage.md	Deletes DLC command doc.
.archon/commands/unic-dlc-review.md	Deletes DLC command doc.
.archon/commands/unic-dlc-qa.md	Deletes DLC command doc.
.archon/commands/unic-dlc-plan.md	Deletes DLC command doc.
.archon/commands/unic-dlc-explore.md	Deletes DLC command doc.
.archon/commands/unic-dlc-cleanup.md	Deletes DLC command doc.
.archon/commands/unic-dlc-build.md	Deletes DLC command doc.
.agents/skills/zoom-out/SKILL.md	Removes deprecated/renamed skill.
.agents/skills/writing-for-agents/SKILL-MECHANICS.md	Adds skill-specific mechanics reference.
.agents/skills/writing-for-agents/agents/openai.yaml	Adds OpenAI agent metadata for the skill.
.agents/skills/write-a-skill/SKILL.md	Removes renamed skill.
.agents/skills/wizard/SKILL.md	Adds new “wizard” skill.
.agents/skills/wizard/agents/openai.yaml	Adds OpenAI agent metadata for “wizard”.
.agents/skills/wayfinder/agents/openai.yaml	Adds OpenAI agent metadata for “wayfinder”.
.agents/skills/wait-what/SKILL.md	Adds new “wait-what” skill.
.agents/skills/wait-what/agents/openai.yaml	Adds OpenAI agent metadata for “wait-what”.
.agents/skills/triage/SKILL.md	Updates triage behavior (incl. PR triage) and invocation policy.
.agents/skills/triage/OUT-OF-SCOPE.md	Clarifies when to write out-of-scope records (rejected vs already-implemented).
.agents/skills/triage/agents/openai.yaml	Adds OpenAI agent metadata for “triage”.
.agents/skills/triage/AGENT-BRIEF.md	Extends brief guidance to PRs and adds PR example.
.agents/skills/to-tickets/SKILL.md	Adds new “to-tickets” skill (successor to to-issues).
.agents/skills/to-tickets/agents/openai.yaml	Adds OpenAI agent metadata for “to-tickets”.
.agents/skills/to-spec/SKILL.md	Renames to “to-spec” and updates framing from PRD→spec.
.agents/skills/to-spec/agents/openai.yaml	Adds OpenAI agent metadata for “to-spec”.
.agents/skills/to-questionnaire/SKILL.md	Adds new “to-questionnaire” skill.
.agents/skills/to-questionnaire/agents/openai.yaml	Adds OpenAI agent metadata for “to-questionnaire”.
.agents/skills/to-issues/SKILL.md	Removes deprecated/renamed skill.
.agents/skills/teach/SKILL.md	Adds new “teach” skill.
.agents/skills/teach/RESOURCES-FORMAT.md	Adds “teach” workspace resource format template.
.agents/skills/teach/MISSION-FORMAT.md	Adds “teach” mission format template.
.agents/skills/teach/LEARNING-RECORD-FORMAT.md	Adds “teach” learning record format template.
.agents/skills/teach/GLOSSARY-FORMAT.md	Adds “teach” glossary format template.
.agents/skills/teach/agents/openai.yaml	Adds OpenAI agent metadata for “teach”.
.agents/skills/tdd/tests.md	Adds guidance on avoiding tautological tests.
.agents/skills/tdd/SKILL.md	Refactors TDD guidance around seams and loop rules.
.agents/skills/tdd/refactoring.md	Removes split-out refactoring guidance file.
.agents/skills/tdd/interface-design.md	Removes split-out interface design guidance file.
.agents/skills/tdd/deep-modules.md	Removes split-out deep modules guidance file.
.agents/skills/tdd/agents/openai.yaml	Adds OpenAI agent metadata for “tdd”.
.agents/skills/setup-matt-pocock-skills/triage-labels.md	Updates seed mapping doc to the current 5-role upstream vocabulary.
.agents/skills/setup-matt-pocock-skills/SKILL.md	Updates setup flow and clarifies when sections should run.
.agents/skills/setup-matt-pocock-skills/issue-tracker-local.md	Updates local tracker seed template to spec+tickets language + wayfinder ops.
.agents/skills/setup-matt-pocock-skills/issue-tracker-gitlab.md	Updates GitLab template to spec language + MR triage + wayfinder ops.
.agents/skills/setup-matt-pocock-skills/issue-tracker-github.md	Updates GitHub template to spec language + PR triage + wayfinder ops.
.agents/skills/setup-matt-pocock-skills/domain.md	Updates domain-doc producer references from grill-with-docs to domain-modeling.
.agents/skills/setup-matt-pocock-skills/agents/openai.yaml	Adds OpenAI agent metadata for setup skill.
.agents/skills/resolving-merge-conflicts/SKILL.md	Adds new merge-conflict resolution skill.
.agents/skills/resolving-merge-conflicts/agents/openai.yaml	Adds OpenAI agent metadata for merge-conflict skill.
.agents/skills/research/SKILL.md	Adds new research skill wrapper guidance.
.agents/skills/research/agents/openai.yaml	Adds OpenAI agent metadata for research skill.
.agents/skills/prototype/UI.md	Updates prototype cleanup guidance to preserve variants on throwaway branch.
.agents/skills/prototype/SKILL.md	Updates logic prototype approach (HTML file) and capture policy.
.agents/skills/prototype/agents/openai.yaml	Adds OpenAI agent metadata for prototype skill.
.agents/skills/improve-codebase-architecture/SKILL.md	Refactors skill to HTML-report-first approach and updates vocabulary sourcing.
.agents/skills/improve-codebase-architecture/LANGUAGE.md	Removes old internal vocabulary reference (replaced by codebase-design).
.agents/skills/improve-codebase-architecture/INTERFACE-DESIGN.md	Removes old interface-design doc (replaced by codebase-design invocation).
.agents/skills/improve-codebase-architecture/HTML-REPORT.md	Adds detailed HTML report scaffold and styling guidance.
.agents/skills/improve-codebase-architecture/DEEPENING.md	Removes old dependency/deepening guide doc.
.agents/skills/improve-codebase-architecture/agents/openai.yaml	Adds OpenAI agent metadata for architecture skill.
.agents/skills/implement/SKILL.md	Adds new “implement” skill.
.agents/skills/implement/agents/openai.yaml	Adds OpenAI agent metadata for implement skill.
.agents/skills/handoff/SKILL.md	Updates handoff to avoid workspace writes and to redact sensitive info.
.agents/skills/handoff/agents/openai.yaml	Adds OpenAI agent metadata for handoff skill.
.agents/skills/grilling/SKILL.md	Updates grilling to round-based frontier questions format.
.agents/skills/grilling/agents/openai.yaml	Adds OpenAI agent metadata for grilling skill.
.agents/skills/grill-with-docs/SKILL.md	Converts grill-with-docs into a router to grilling + domain-modeling.
.agents/skills/grill-with-docs/CONTEXT-FORMAT.md	Removes embedded context format doc.
.agents/skills/grill-with-docs/agents/openai.yaml	Adds OpenAI agent metadata for grill-with-docs.
.agents/skills/grill-with-docs/ADR-FORMAT.md	Removes embedded ADR format doc.
.agents/skills/grill-me/SKILL.md	Converts grill-me into a router to grilling.
.agents/skills/grill-me/agents/openai.yaml	Adds OpenAI agent metadata for grill-me.
.agents/skills/git-guardrails-claude-code/SKILL.md	Adds skill for installing git guardrail hooks.
.agents/skills/git-guardrails-claude-code/scripts/block-dangerous-git.sh	Adds hook script to block dangerous git commands.
.agents/skills/git-guardrails-claude-code/agents/openai.yaml	Adds OpenAI agent metadata for git guardrails skill.
.agents/skills/domain-modeling/agents/openai.yaml	Adds OpenAI agent metadata for domain-modeling.
.agents/skills/diagnosing-bugs/SKILL.md	Renames/updates diagnosing skill content and tight-loop criterion.
.agents/skills/diagnosing-bugs/scripts/hitl-loop.template.sh	Adds HITL loop helper script.
.agents/skills/diagnosing-bugs/agents/openai.yaml	Adds OpenAI agent metadata for diagnosing-bugs.
.agents/skills/codebase-design/agents/openai.yaml	Adds OpenAI agent metadata for codebase-design.
.agents/skills/code-review/SKILL.md	Adds new code-review skill (two-axis review).
.agents/skills/code-review/agents/openai.yaml	Adds OpenAI agent metadata for code-review.
.agents/skills/caveman/SKILL.md	Removes deleted skill.
.agents/skills/ask-matt/PHASE-BOUNDARIES.md	Adds “phase boundaries” guidance doc.
.agents/skills/ask-matt/agents/openai.yaml	Adds OpenAI agent metadata for ask-matt.

Suppressed comments (2)

.agents/skills/triage/SKILL.md:45

• This skill instructs agents to run /setup-matt-pocock-skills if the label mapping isn’t provided, but this repo’s AGENTS.md explicitly says not to run it (it would revert docs/agents/triage-labels.md). The skill should instead direct the agent to read docs/agents/triage-labels.md / docs/agents/labels.md or ask the maintainer.
  .agents/skills/to-spec/SKILL.md:10
• This skill tells the agent to run /setup-matt-pocock-skills if tracker/label vocab isn’t provided, but AGENTS.md says that skill must not be run in this repo. Prefer pointing at the repo-owned docs (docs/agents/issue-tracker.md, docs/agents/triage-labels.md, docs/agents/domain.md).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.