unic / unic/unic-agents-plugins

wayfinder: unic-archon-dlc is prose, and proven at FZAG

Open
#373 5 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

app:unic-archon-dlc repo wayfinder:map
Dominant language
JavaScript
Stars
1
Forks
0
Avg merge
16h 43m
Merged PRs (30d)
19

Description

Destination

unic-archon-dlc is prose, releasable, and proven on real client work: the FZAG design-system
monorepo (DXP-DesignSystem, Azure DevOps, dev.azure.com/FZAG/dxp) runs the main line
/specs/tickets/build and has delivered its first real slices, including the Figma
conventions documented for agents.

Notes

Domain: an Archon-driven set of workflows for the AFK legs of development at Unic, plus thin
wrappers so Unic's context composes Matt Pocock's skills for the HITL legs. The plugin is a Harness;
the Methods it hosts own procedure.

Skills every session consults: /grilling, /domain-modeling. /research for the research
tickets, /prototype where a rough artefact beats a paragraph. /writing-for-agents is the skill
this map runs on
— five tickets are prose edits to an AGENTS.md or a command file, which is exactly
its subject.

Every ticket carries a session opener — a comment titled "How to start this session". When a
ticket carries more than one, the newest is authoritative and older ones are marked stale; never
follow the oldest by position. The opener says what to invoke, in what order, and the traps specific
to that ticket. Read it before starting; it is not a restatement of the body. Two
things it will tell you that are easy to get wrong: /implement sends you to /tdd, which is wrong on
this map because decisions 3 and 11 delete the tests; and #376 and #379 are claimed here but worked in
~/Sites/FZAG/DXP-DesignSystem.

Links, never bare ids (adopted 2026-08-21, from #378): in prose — tickets, comments, openers, docs — a Confluence page id, GitHub issue number or ADO work item always carries its URL. Bare ids stay only in structured output.

Start a session with /wayfinder 373 to take the next frontier ticket, or /wayfinder 373 #<n> to
take a named one. One ticket per session — except research, which runs in parallel.

Week of 2026-08-25, standing directive (maintainer, 2026-08-25): the target is one component
from design to code
— the #379 walk at
FZAG. No upgrade work this week unless the target lands before the deadline: that parks
#425 (the Archon 0.9.0 gate),
#423,
#424,
#422,
#418 and
#400. Archon stays at 0.7.0 all week —
#425 gates any upgrade regardless. In-flight work finishes
(#420); the critical path is
#406 → #405 → #416 → #379 plus the design-side fixes in
WI 42961 (focus states and the three
typos stop /specs).

THE PREFACTOR IS MERGED, 2026-08-26 17:32. P landed on DXP-DesignSystem's develop as dda788a
(PR 5798, 11 commits, two review
iterations plus an orchestrator set-read, target never retargeted).
WI 42974 is Ready for Test — a prefactor's real
test is S1. The walk's remaining steps run in a session rooted at the Consumer, per
issuecomment-5427549188:
the DLC commands are project-scoped to DXP-DesignSystem, and /wayfinder does not exist there either
— it is a repo-local skill of this repository, so the next session reads the ticket rather than claiming.
Two defects filed from P's own review, both with verbatim evidence:
#430 (the review Box cannot verify an author's
build, lint, type or test claims — no node_modules in the Archon worktree) and
#431 (reconcile counts withdrawn,
kept-by-design and moved findings as fixed, proven by the Box contradicting its own thread statuses inside
one run).

DISPATCHED 2026-08-26 13:05wayfinder-379 ran against
#379, labelled ready-for-agent. Its opener was
frozen at 13:00:51 and the session started four minutes later, so it holds the final version. From here a
correction goes as a superseding comment plus a message to the running session, never a silent edit to the
opener.

Where that path stands, 2026-08-26 12:25. #406, #405, #416 and #414 are all closed; the three typos
are fixed in Figma and the card carries focus, so #379 is the only thing left on the path, and it is
dispatchable.
Its opener is written, re-measured and amended
(issuecomment-5417415983);
the 2026-08-14 one is marked stale in place.

Three decisions taken by the maintainer on 2026-08-26, before dispatch, all on that opener:

  1. docs.publish flips to true for the walk. The Confluence parent
    (Design System Components,
    973276506, zero children as of 12:05) exists and its page creation is part of what this walk proves.
    The PRD publishes nothing — no parent is named for one and none should be invented; a PRD's home is
    workflows/<slug>/PRD.md in the repository, because it is the plan for a walk and not a specification.

  2. Scope A: the PRD covers P, S1, S2, S3 from
    #377's resolution;
    S4S6 named in Out of Scope with their blockers.

  3. The Tailwind prefix is kept and renamed uidxp, with tailwind.prefix set to match in
    components.json. packages/ui-react is a library other DXP apps consume, so unprefixed utilities
    would collide with a consumer's own Tailwind; and ui in particular is the name a second component
    layer picks — ProfileServices will compose code from two agencies, Unic and Omnevo. dxp names the
    platform, so it cannot collide, and it does not put an agency name in a class that outlives the
    engagement. Changing it is a two-line edit inside P and a per-file migration after S1. Verified:
    Tailwind v4 puts the prefix at the FRONT, before any variant (dxp:hover:bg-surface) — and the
    repository's only prefixed code, stock card.tsx, has it backwards, so three of its hover styles are
    dead today. Still unverified: what the shadcn CLI emits when given "dxp", probed inside P.

  4. P gains four token-layer constraints (2026-08-26 12:45), so brand and colour-theme support stays
    possible without this walk building it. The design system must eventually carry two independent axes
    — brand (two airports today) and light/dark — and the axes compose only when they touch different tiers:
    brand overrides primitives, theme overrides role tokens, and utilities reference roles only, which costs
    N + M override blocks instead of N × M. semantic.jsonbase.json is already tier 2 → tier 1. The
    four: the dark variant declared as a selector (@custom-variant dark (&:where([data-theme=dark], [data-theme=dark] *))) — the most expensive one to defer, since otherwise every dark: utility is
    wired to prefers-color-scheme and cannot be driven by a switcher; @theme inline on every role token,
    because bare @theme snapshots the value and a selector override then silently does nothing; components
    restricted to semantic tokens, never a primitive; and the duplicate unprefixed Tailwind import in
    packages/tailwind-config/shared-styles.css removed, which today defeats the namespace the prefix
    exists to create. Constraints only — no second brand, no dark values, no roster. The architecture is
    WI 42973, filed 2026-08-26, which also carries
    the brand roster (the website's zrh-default / zrh-magazine / dxn-default suggests brand plus
    sub-brand rather than a flat list), whether "system" is a third theme state, the Storybook and
    visual-diff cost of the matrix, and the Figma work — neither axis is drawn today, so a contract
    cannot record either and code would be inventing values.

  5. The reasoning is documented, and the routing is decided (2026-08-26 13:00). No new home was
    invented — the Consumer already had the shapes. P writes
    docs/adr/0003-utility-prefix-is-dxp.md and
    docs/adr/0004-brand-and-theme-on-separate-token-tiers.md, both of which pass the repository's own ADR
    test, and adds the semantic-tokens-only rule to CLAUDE.md § the bar a component meets. The close-out,
    not P
    , writes docs/agents/unic-archon-dlc.md § Where each artefact lands — the four systems with
    their page ids and area path, plus why a PRD is not published and which homes were rejected — because a
    layout written before the run is intended state stated as fact. The plugin's CONTEXT.md gains only
    the generic principle, naming no tool: a fact lives where its author lives, and a PRD is a plan for a walk
    rather than a specification. For FZAG-wide readership, Confluence 973276506 points at the ADR — one
    home, a pointer, no mirror.

Two corrections that came out of answering them, both recorded as an erratum on #377
(issuecomment-5423930842):
P item 5 (widen the Storybook glob) is struck — the Consumer's CLAUDE.md puts stories where the
existing glob already looks, so the item was satisfied by changing nothing; and the Consumer does have
docs/adr/, holding ADR 0001 and 0002, which answers #377's own item-6 open question.

Two further defects found while routing that documentation, both now in P: CLAUDE.md § Tailwind
states the dead Tailwind v3 class order as fact ("hover:ui:bg-blue-700 — variant first, prefix second")
in an always-loaded file, so an agent writes dead classes on purpose; and sd.config.js's
tailwind/theme-css format emits a bare @theme block, which carries the silent-override problem into a
generated file if role tokens ever flow through it.

Button, button-round and sidenavigation-link still lack focus, so the feature must not name them —
#429 makes one blocked component stop the whole
run.

The nineteen decisions taken while charting this map (2026-08-14). These are standing for the
whole effort. A session that contradicts one is wrong, not creative.

# Decision
1 Released means: one other Unic repo installs the plugin and runs it end to end.
2 repo-scoped process work is frozen. Fix a process defect only when it blocks product work.
3 The plugin is prose. Code exists only where prose physically cannot act.
4 A ticket's acceptance criteria are decided before dispatch, never repaired at dispatch.
5 The 48 open issues get one triage pass against this destination; the maintainer approves a close-list.
6 The 1.0 box set is /build plus setup, triage, specs, tickets.
7 A ticket carries few criteria, about the prose that ticket delivers.
8 A PRD exists only when the work needs more than one ticket.
9 FZAG is the Consumer.
10 docs/process/ai-development.md §4 is deleted; its lesson moves to the root AGENTS.md.
11 lib/ and test/ are deleted, all of it, unless a module proves it earns its place.
12 commands/tickets.md is rewritten from scratch, after the doctrine is written down.
13 FZAG gets as much as possible; /build is first priority.
14 /setup becomes prose with no module, rewritten from scratch.
15 The ADRs are pruned aggressively. A superseded ADR is context that invites hallucination.
16 Order: the doctrine now; the deletions after the ten days.
17 Ten-day goal: the design-system repo, deep — /specs, /tickets and /build all running there.
18 The Azure DevOps tracker risk is not spiked. It is fixed when it appears, on day 1.
19 Surgery scope is the bleeding-stopper now; the rest later, if the ten days leave room.
20 The pre-dispatch audit is dropped. ready-for-agent means what Matt's canonical role means — specified and approved in-session at publish. Gate 3 and the PR review are the checks that remain, and a short ready queue replaces the gate.

Two consequences that contradict each other unless stated. /specs and /tickets must run in
FZAG during the ten days (17), but their rewrites are deferred (16). So the ten days run the bloated
versions as they stand today. Nobody rewrites a command mid-sprint. And the ADO risk (18) lands
on day 1, not day 8, because creating DXP-DesignSystem on Azure DevOps and installing the DLC is
the first thing done.

What derailed this effort, so no session repeats it. docs/process/ai-development.md §4 defined
a good acceptance criterion as a runnable command carrying its pasted output and a citation that must
still resolve. This plugin's product is prose. Prose cannot satisfy that bar, but a .mjs module
can — so lib/ grew to 2 056 lines with 4 431 lines of tests, 1.6× the size of the product, and
lib/slopcheck.mjs exists only to be tested (unic-dlc-build.yaml:120 inlines its own copy and
imports nothing). Meanwhile every merge invalidated every pending citation, so the pre-dispatch audit
had to re-verify 15–21 criteria per round: 2.5 hours before one night shift could start. The
to-tickets Method says the opposite in one line — "avoid specific file paths or code snippets —
they go stale fast"
— and ships a two-criteria template.

Where the FZAG work lives. This map and its tickets are about the plugin. The design system's
own slices are Azure DevOps work items in dev.azure.com/FZAG/dxp, never GitHub issues here.

The two repositories move together, and a session that touches one owes the other. Neither direction
is optional, and both were needed on 2026-08-19 within a single ticket (#389):

  • Plugin → Consumer. A change to a Box, a command or the config shape is not delivered until
    DXP-DesignSystem carries it. Nobody has rewritten setup.md yet (#383), so the Boxes are a hand
    copy with no version marker — nothing detects a stale one, and #389 re-copied the four twice and
    still shipped a wrong claim about their parity, because the only available check is one a human runs
    and reports. /setup was never retired: #402 restores it as the installer, and its --check mode is
    what will detect a stale copy.
    #390 closed the other half: the commands install from the marketplace, so nothing is copied, the
    version and the commit are recorded, and the Consumer doc names both. The Boxes remain the manual half.
  • Consumer → plugin. Running a Box against a live tenant is the only thing that finds certain defects,
    and it finds them at a rate worth planning for. #389's two unic-dlc-pr-review iterations against one
    small pull request produced four real plugin defects, including a pre-push guard that failed open
    under zsh and the hash instability now filed as #394. None was reachable from this repository's tests.

So: after a plugin change, port it and say so on the ticket. After a Consumer run, read the findings for
what they say about the plugin rather than only the Consumer, and file what you find. A ticket that
closes with one direction done is half closed.

This holds until the streams finish. When it stops holding, say so here — do not let it lapse silently.

unic-pr-review is a separate live product, not frozen. #275 (p0, every --post write fails)
and #274 (p1, intent verdicts silently discarded) stay open and untouched, with stream #316.
Both FZAG DXP repos use that plugin today. The DLC's own review Box will supersede it eventually;
until then it is outside this map and inside nobody's freezer.

Reference for a later session: github.com/seanrobertwright/archon-pocock-workflow — a generic
port of Matt's skills to Archon workflows. Ticket exists below.

Decisions so far

  • Delete ai-development.md §4 and put the prose doctrine in the root AGENTS.md
    — §4 is gone and the doctrine is four reads in the always-loaded root AGENTS.md. Decision 20 was
    taken here: deleting §4's citation requirement removed the rot the pre-dispatch audit existed to
    catch, so the audit went with it. PR #386, merged as 5366a4a.

  • Triage every open issue against the map's destination and produce a close-list
    — 33 closed, 7 kept; the non-wayfinder backlog goes 40 → 7. What stays: #332, and the six
    unic-pr-review issues that are a separate live product. The Out-of-scope section below holds the
    21 genuinely ruled past the destination; the other 12 were absorbed, settled or shipped.

  • Install unic-archon-dlc into DXP-DesignSystem by hand, on day 1
    — installed on feature/42928_initial-DLC-installation (83e8b67): four Boxes discovered and
    validated, eleven Methods at .archon/methods/, a hand-written config, and bootstrap reading it.
    Nine gaps written up; the four that block a FZAG run are one decision, now
    #387, which blocks #379. The install
    sequence on the ticket is the source for #383 and the README.

  • Decide the DLC's tracker contract on Azure DevOps
    — the contract is two repo-local prose files, not a config schema. docs/agents/issue-tracker.md
    carries access, addressing and the work-item scope; docs/agents/triage-labels.md carries the
    seventeen roles, each row naming its own axis. DLC /setup owns both, which is an input to #383.
    A section earns its place only when it states a fact about the tenant — an MCP server discovers an
    API, so writing operations down freezes a flag table in Markdown. The whole tracker block,
    classification.labels, project.pr_strategy, repo_ref and the ambiguous-repo guard leave the
    config; MANDATORY_PATHS becomes project.branching alone. ADR-0024 is amended, not superseded:
    its rule that Matt's setup artefacts are never consulted is reversed, and "the tier carries the
    axis" is disproved. Work split into
    #388, which unblocks #379 on its own, and
    #389.

  • Write the tracker contract files in DXP-DesignSystem
    — merged. docs/agents/issue-tracker.md and docs/agents/triage-labels.md exist in the Consumer,
    PR !5769 completed as 4a9e227, work item 42928 is Resolved. Matt's two-file split was kept for
    compatibility. Writing it corrected #387's own tenant facts: mapping needs-triage, needs-info
    and ready-for-human onto State New moves an already-Active work item backwards, so all three
    write nothing. It also found pnpm format forking the Method Bundle — filed on #383, because every
    Consumer with a Markdown glob has it.

    The Box reviewed its own installation, three times. Every Azure DevOps path in
    unic-dlc-pr-review has now run: read work items, find the PR from the branch, scan threads, post
    a summary, update it in place, open inline threads. Iteration 2 classified 5 fixed · 5 still
    present · 0 regressed · 4 new. Two of its findings were #376 acceptance criteria that were written
    on the GitHub ticket and never read back against WI 42928. Decision 1 is met.

  • Install the DLC's command Boxes in DXP-DesignSystem
    — the route is the marketplace entry, not a copy: claude plugin install unic-archon-dlc@unic-agent-plugins --scope project, with extraKnownMarketplaces and enabledPlugins
    committed to the Consumer's .claude/settings.json. Copying commands/*.md cannot work, because Step 1
    imports plugin lib/ through $CLAUDE_PLUGIN_ROOT. DXP-DesignSystem !5778, work item 42948;
    docs/agents/unic-archon-dlc.md now records both install halves and the version each carries.

    All seven commands load and every one stops at Step 1. Two plugin defects, both deleted by #381:
    $CLAUDE_PLUGIN_ROOT is unset inside the Bash tool, and lib/ imports the bare yaml package while an
    installed plugin ships no node_modules. So #381 now blocks /specs/tickets/build at FZAG
    rather than tidying this repository, and #379 waits behind it. AC-3 was resolved by hand instead —
    ready-for-human → Tag needs-human on work item 42948, the tag created on first use with no
    permission change — and completes properly when /triage runs.

  • Delete lib/ and test/ — take the plugin to zero code
    — the plugin is zero code and zero runtime dependencies: twelve modules and nineteen test files
    (6 413 lines) deleted, all seven command Step 1 blocks rewritten as prose, the manifest's data moved
    to prose (README § Dependencies is the list itself; provenance in vendor/mattpocock-skills/README.md).
    PR #398, released as unic-archon-dlc@0.23.0 (1968067). The Consumer criterion is met:
    DXP-DesignSystem refreshed via !5782 (2002246, WI 42952), and two read-only probes ran past
    Step 1 where 0.22.0 halted — two of seven probed, and the Consumer doc says so. Fallout tickets:
    #400, #401, #402.

  • What replaces a test as the quality bar for a prose Box?
    — the bar is a run and a read, never a test: it runs where it ships (marketplace install into a
    Consumer), its rules are stated where they are needed, and what it depends on is written once. Both
    hard cases got losing verdicts stated plainly — nothing replaces the staging/pinning grep, and the
    upstream-rename tripwire becomes a by-hand Bundle diff in the commit that moves the pin. Landed as
    #### The quality bar for a prose Box in the root AGENTS.md, inside PR #398.

  • Figma conventions for agents, from Confluence PRISM 840073301
    — the ticket named the wrong subtree: all nineteen pages under 840073301 are a literature review
    that mentions Figma once, in a bibliography line. The conventions are in
    PRISM 852591905 — one current
    page plus two their author filed under old the day before, which are the only home for PascalCase
    and exact Figma-to-code name matching. Scope was widened to read the live Figma file, because the
    docs are dated 3 June and the file was edited 21 August: seven documented-versus-actual
    disagreements, eight defects in the file. get_variable_defs returns resolved token values across
    the library boundary
    , so the Token Studio detour routes around a limitation that no longer holds —
    the design files are the source of truth for tokens, decided 2026-08-21, with three conditions.
    docs/research/figma-conventions-for-agents.md in the Consumer, merged as d177e6f (!5783, WI
    42953). Output 2 (docs/agents/figma.md) is blocked on decisions, not access, and only it can carry
    the Figma file keysget_libraries returns library keys and nothing resolves one to a file.
    Spawned #403, #404, #405, #406 and plugin defect #407.

  • What are the FZAG design system's first slices?
    one prefactor and six slices, with S1 and S2 running in parallel off the prefactor. The
    card is cut by variant, not shipped whole: S1 the card and its three states, S2 badge-main,
    S3 the card carrying a badge, then Code Connect, Chromatic, and responsive. The grilling surfaced
    the stack — shadcn + Base UI + Tailwind, named by the maintainer and written down nowhere in the
    Consumer — which added three items to the prefactor and collapsed four card slices to two: the Figma
    variant axis maps onto composition of shadcn parts, not onto a prop, and only state is a real
    style variant. Two of this ticket's own opener claims are corrected on the ticket: badge-main is
    not blocked by #406 — instance-level SVG
    export works from the design system file — and
    #405 binds at S2, not on the first build.
    The card ships as a plain container with no focus style, by the maintainer's decision, pending a UX
    answer. #379 is now unblocked.

  • Reopen decision 14: is /setup retired, or is it the Consumer's installer?
    Decision 14 stands as written, and it was never a retirement. Row 14 says /setup becomes
    prose with no module, rewritten from scratch. Decision 6 keeps setup inside the 1.0 box set. The
    word "retired" entered at one line of this map, citing decision 14 for something it does not say,
    and spread from there to #389's grounds
    for deleting config keys and to the Consumer doc. That line is rewritten above; row 14 is unchanged,
    because it was right all along.

    /setup is the Consumer's installer, and it owns four artefact classes under one rule. The
    Boxes (.archon/workflows/unic-dlc-*.yaml) and the Methods (.archon/methods/) are verbatim plugin
    output: /setup owns them and replaces them silently, exactly as
    ADR-0036
    D3 already says. The config (.archon/unic-dlc.config.yaml) and the tracker docs
    (docs/agents/issue-tracker.md, docs/agents/triage-labels.md) are tenant-authored: /setup
    writes each one only when it is absent, and on a re-run it reads, reports what differs, and changes
    nothing. That is one rule stated twice — idempotent by replacement for what the plugin owns,
    idempotent by refusal for what the tenant owns. It replaces the phrase "the non-plugin half", which
    named two classes that need opposite treatment.

    autoUpdate goes off in a Consumer, and the fear it answers is narrower than it looked.
    Measured 2026-08-23: the marketplace entry in DXP-DesignSystem names the git URL with no ref, so
    the marketplace follows develop — but plugin.json declares a version, and a declared version
    pins the plugin, so Claude Code skips the update while that string is unchanged. autoUpdate: true
    therefore carries a version bump, not every commit. Under this repo's release flow the bump
    merges to develop before the release PR to main, so a Consumer receives it at merge rather than
    at tag. Off is still the right default: a tenant that cannot test the new version before it lands
    should not receive it unattended, and claude plugin update costs one command. Pinning the
    marketplace to a ref was rejected — a marketplace ref naming a per-plugin tag couples six
    plugins to one plugin's release.

    The Generated header is restored to a writer, not deleted from CONTEXT.md. It grows one line:
    the Archon version /setup observed at install time. That is the whole answer to the three-way
    plugin × Archon × Consumer coupling — one observed number, stamped where provenance already lives,
    no compatibility matrix and no new mechanism. A Consumer can then read the set it was installed
    against and compare it to what it runs. The Methods get a directory-level record
    (.archon/methods/INSTALLED.md) instead of a per-file stamp, because stamping eleven upstream
    SKILL.md files forks the text that pnpm format already forked once. The upstream Method pin
    needs no field of its own: the plugin version is the pin (root AGENTS.md). This reverses
    ADR-0036's 2026-08-14 amendment, which recorded that no separate record file exists, so a fourth
    amendment note is owed — and it belongs to the new ticket below, not to #402.

    A /setup --check mode is what makes the header worth stamping. With autoUpdate off, drift
    stops being an unattended overwrite and becomes staleness by inaction. --check is the same prose
    as a normal run with the write step skipped: it compares each installed artefact against the plugin
    on disk and prints what differs. PULL over PUSH stands, re-examined rather than inherited — nobody
    is present when an update fires. Both real failures to date, #389's wrong parity claim and the two
    rotted files the 0.23.0 port found, were detection failures, which is the gap this closes.

    /setup also owns a marker-delimited block in the Consumer's formatter ignore file. This is a
    second instance of a rule the plugin already has for CLAUDE.md: the block is replaced in place,
    markers included, and everything outside it is preserved verbatim. Report-and-refuse was considered
    and rejected here, because the step gets skipped and the evidence is that pnpm format rewrote
    thirteen Methods before anyone noticed. The asymmetry the Consumer doc records is load-bearing and
    the block must reproduce it: .archon/methods/ needs the exclusion because the Bundle is full of
    .md; the Boxes are .yaml, the glob cannot reach them, and an entry for them would read as a
    claim that it can.

    Bundling the Methods stays right, settled here rather than left to #383. The rule above depends
    on it: /setup copies out of the plugin, so it can only copy what the plugin ships. The reason
    bundling was chosen — an upstream rename and an Archon release both broke migration — was never
    about resolution tiers, so retiring the tiers did not touch it.

    Work split: #383 grows to six write
    actions plus the first-write rules; a new ticket takes provenance and --check, and carries
    ADR-0036's fourth amendment. What this grilling did not decide is listed on #402.

  • /archon-upgrade verifies the Archon config keys we depend on
    — the check is a behavioural probe (five runs, one a true empty-config control) stated in the
    command's own prose; worktree.remote measured as read on 0.7.0, governing base-branch
    resolution only. Found and fixed on the way: Step 1 stopped on installed == floor, so Step 5's
    ADR-0011 trap re-assertion was unreachable on the floor version since it shipped. PR #410,
    merged as 427ccbd, ships in unic-archon-dlc@0.24.0.

  • A finding with no file gets an invented one, so its hash is unstable across iterations
    — the thread's marker IS a finding's identity: only a first appearance computes a hash, reconcile
    carries it forward, scoped findings (pull request / work item / repository) stay summary-only with
    a fixed vocabulary, and the anchor admission rule checks the diff because Azure DevOps accepts
    out-of-diff anchors. Proven across THREE Consumer iterations on !5788 (20 priors = 20 verdicts,
    all four classifications measured, regressed fired unstaged); the Box found eleven real defects
    in its own fix, each round catching the previous round's fixes wanting. PR #409, merged as
    147465e, ships in unic-archon-dlc@0.24.1.

  • How does a Figma component represent three or more variant dimensions?
    the axis name carries the mechanism, and five names are enough: state → a selector,
    variant and size → props, layout → composition, responsive → a media query. SLOT,
    INSTANCE_SWAP, BOOLEAN and TEXT complete a nine-row table an agent applies without judgement.
    The ticket's own name-keyed proposal lost on one measured fact: variant is an appearance axis on
    button-round and an arrangement axis on card-profile-main, in one file. SLOT is the row that
    settled it — card-profile-main.variant splits into layout: default | progress plus an
    action slot, because icon versus badge was never the card's axis but badge-main.variant on
    the nested instance. "Never both" becomes structural rather than documented, and ADR-0001's worked
    table is amended while CLAUDE.md § Composition stands unchanged.

    Two of this ticket's premises were false, and the file answered both. Verified against Figma's
    own documentation: a component set need not carry every combination, so an agent enumerates the
    set's children and never the product of the axes. And Button already draws a complete 3 × 6 flat
    matrix — state on the horizontal, variants × size nested on the vertical — so the layout
    convention did not need inventing, only naming. The boolean-versus-variant tension resolves against
    the Confluence rule on a primary citation (booleans are Figma's documented way to toggle icons on
    buttons), the numeric cap is dropped because Figma's own remedy is nesting instances, and "base
    component" gets no rule at all because Figma uses the phrase once and defines it nowhere.

    Figma bends to shadcn, names and values — variantsvariant, primarydefault,
    secundarysecondary, m/sdefault/sm — and button-round merges in as
    shape: default | round, which costs the Figma-name-to-code-component match. Cheap today, because
    no component exists in the Consumer yet. focus now blocks /specs, so it blocks /tickets
    and /build; no component in the file has it, which blocks #379 alongside three outstanding typos
    that stop a run rather than being silently corrected. The condition is declared by the Consumer's
    docs/agents/figma.md, never by the plugin — the same split #387 settled for the tracker.
    Undesigned shadcn values stay available with a JSDoc marker and no gate: a design system gives
    guides, not guard rails. Spawned
    #414; removes #404's need for a value map.

  • What does a component design contract contain, and what does /specs write?
    — the contract is derived; the authored half of the component's Confluence page is not. That line
    is what the ticket was missing, and drawing it dissolved its hardest open question: there is one page
    per component
    , an authored half plus a generated block /specs writes through injection markers, so
    /specs creates the page and "no component spec page exists" stops blocking. Four sections —
    visible Provenance, Design as read, Code shape, Non-designable facts — keyed on nodeId, never on the
    name, because card-profile-main appears three times and profile/card four times in one file. Lists
    and no tables anywhere: the Consumer formats every .md at any depth, so no location escapes the
    formatter
    and the problem was orthogonal to the location question all along. contract.generated.md
    beside the component lands inside DXP-DesignSystem's existing *.generated.* ignore rule, so that
    Consumer needs no edit. Nothing detects staleness; the checkers are named — the human at the PRD gate,
    and the next /specs run. DOCS.publish governs contracts as well as the PRD. An unpublished component
    stops /specs, because the read returns published components only and the failure is a silently
    empty contract. The organising rule, stated once: the what is the plugin's, the how is the
    Consumer's figma.md
    — location, blocking conditions, the image route and formatter protection all
    split that way. Spawned #416, which now
    blocks #379: nothing carried the design branch into commands/specs.md, and a hand-written first
    contract proves nothing about the plugin. Also #417
    (README's design.type enum names Figma — AC 5 would otherwise have passed on a technicality).

  • Rewrite commands/setup.md from scratch as prose
    /setup is the installer, and ownership decides what a re-run does: a tree the plugin owns is
    replaced, a tenant-owned file is written once and thereafter reported on, a marked block inside a
    tenant file is patched in place. Three treatments, not the two the ticket claimed — a marker block is a
    plugin-owned region inside a tenant-owned file, and that miscount was one of two criteria the grilling had
    to amend. The other: the ignore block excludes both installed trees, because the one real Consumer had
    already written the entry the criterion forbade, for a reason the criterion did not answer. Thirteen
    decisions in all. The load-bearing ones: the plugin's own directory comes from Claude Code's
    installed_plugins.json (installPath, matched on projectPath) and never from the version cache, which
    held nine versions of this plugin on the machine measured; the formatter exclusions detect the
    project's toolchain and name no tool; the tracker contract is written from a measured board vocabulary
    with no defaults offered; and the legacy flat .json migration is deleted as a path nothing ever walked.
    The run is what found the defect no read could: the Method Bundle groups by category, so the install
    would have reported success and left every Box unable to find every Method. Shipped as 0.25.0 in
    #420; unblocked
    #408 and spawned
    #422 (/archon-upgrade has the same locate
    defect). The Consumer's docs/agents/unic-archon-dlc.md "/setup must not run here yet" passage is now
    false — for the next DXP-DesignSystem PR, not a PR of its own.

    This was archon-comprehensive-pr-review's cleanest recorded run: no base retarget, both marked
    comments selected by marker, a full roll call, one fix commit, CI held green. It caught four HIGH the
    two-axis /code-review had missed, two of which were defects in my verification rather than only in the
    file, and its MEDIUM pile held four genuine correctness findings.

  • Get edit access to the Global Tokens and Assets Figma files
    — granted on the call, and the measurement corrected the ticket's own premise: access was never the
    whole blocker.
    Both libraries subscribe to nothing external, so the graph terminates. A primitive
    token value stays unreachable even on edit access — search_design_system returns names with no
    values and get_variable_defs needs a node — so a value arrives only resolved, on a node that binds
    it, in a file already readable. The contract records the semantic name and never needed the primitive
    file. Four file keys captured for #414. Edit-for-read accepted, with the price written down: the same
    credentials reach use_figma and create_new_file.

  • What does an agent read as design intent, when a Figma file carries data nobody chose?
    — the rule is property versus layer: an override through a declared property is intent, an
    override typed onto a layer is not, and a colour bound to a token is the one exception. The body's
    blanket proposal lost, because three property rows are overrides. Both of the body's reads were
    wrong about the same thing — an icon override is invisible in the component read and in
    get_design_context, existing only inside exported SVG bytes — which is what makes the detection
    test work: compare the SVG literal against get_variable_defs, verified three for three. layout
    leaves #403's table, which goes nine rows to eight: deleting has icon/has badge as designer
    convenience removes the collision layout was invented for. A subscription mismatch warns. And
    the consumption surface moved to the new platform file, which supersedes the old planned page and
    showed the predicted leak in the wild — 7 of 21 cards carry the library's placeholder badge, and two
    of four breakpoints are scaled artboards rather than layouts.

  • Write the design branch into commands/specs.md
    — shipped as 0.26.0 (PR #426): /specs now
    branches on design.type set-versus-none, reads the Consumer's hand-written design-conventions
    doc, and writes one design contract per component a feature names. Transcribing eleven decided rules
    needed three answers #404 had not given, so each got the cheapest defensible answer and a ticket:
    the doc's location is derived as docs/agents/<design.type>.md (verified against the Consumer, where
    design.type: figma and #414 writes docs/agents/figma.md) and nobody installs it —
    #428; a blocking condition stops the whole
    run rather than the one component —
    #429. Both review axes converged on the same
    page, the list of what that doc owns, from opposite sides: duplication that had already drifted, and a
    gap where Step 7 asked the doc for three facts its own list never claimed — relayed to #414 mid-flight
    as items 17–18. The mechanical grep bar earned its place twice over: it caught two design-tool names
    specs.md had carried since before this ticket.

  • Write docs/agents/figma.md in DXP-DesignSystem
    — on the Consumer's develop (!5794,
    662ed2d). The design contract now sits beside the tracker one: the four file keys nothing else
    resolves, which read carries which fact, nodeId as the identity key, the override rule with a
    detection test, three conditions that stop /specs, the contract path, the appearance gate, and eight
    open questions each naming its owner and whether it blocks. #379's card path is clear — Jessi drew
    focus on card-profile-main and fixed all three misspellings, so what blocks now is Button,
    button-round and sidenavigation-link. The lesson is the cadence: the design file moved four times
    while the ticket was open
    (15:55, 17:19, 17:25, 17:31), and three facts transcribed from #405's
    resolution comment that morning were false by lunchtime — so every claim carries a time, not a date,
    and an opener must say re-measure and stamp it rather than transcribe the decision. The fourth move
    widened a rule rather than a measurement: badge-main binding its icon sizes to tokens proved #405's
    carve-out was written colour-only where the plugin's prose is value-generic
    (#405 correction).
    Filed rather than settled: #427 and work item
    42970.

Not yet specified

  • Whether a config enum should enumerate tools at all (added 2026-08-25, from
    #417): an open list would let a Consumer
    on Penpot or on Claude's design tool declare itself with no plugin change. #404's
    grilling never asked it; PR #419 only removed
    the two closed lists (design.type, docs.type) that made it look answered. The command's own enums
    are gone
    #383's rewrite asks both fields
    open and writes the answer through, so #404's AC 5 is met and this patch is now the design question
    alone: whether the config schema should carry a tool list at all.

  • Installing the DLC into DXP-ProfileServices and DXP-Website — both already run Archon 0.7.0,
    both on the same ADO project, so the install is cheap once DXP-DesignSystem proves the path.

  • Seven Archon defects that land on the Consumer, none ours to fix. /archon-upgrade is the box that
    would classify them; 0.8.0 is already out and every one was measured on 0.7.0.

    • archon complete shells out to gh pr list unconditionally, so on an ADO remote its open-PR
      refusal degrades to a warning and /cleanup --apply runs unguarded (#376).
    • Archon reads the second-to-last URL segment as the organisation, so every ADO repo lands under a
      shared _git/ workspace directory (#376).
    • The two approval surfaces do not behave the same way. Found 2026-08-18 across runs
      510ebb0d129f009dc8ae2426d56a12cc and ace753970841246ec09fd092757275c1. archon workflow approve from the terminal approves and resumes, in one command. Approving the same gate in
      the Archon UI records approved and leaves the run paused indefinitely; archon workflow approve then refuses with "already approved and is awaiting resume", which reads as an error
      but is the only hint that archon workflow resume <id> exists. An operator who approves in the
      UI is told nothing, and the run waits forever.
    • A run executes the Box from the invocation directory's working tree, not from the branch.
      Measured 2026-08-24 (#394, run 73462921): --from <branch> checks the branch out, then
      silently overwrites the worktree's tracked .archon/ from the invocation directory —
      git log reads correct while the wrong Box runs. Consequence: a Consumer verification of a
      Box change dispatched this way tests the old Box and passes green. Workaround: copy the
      changed Box into the registered clone's working tree (uncommitted), dispatch from there, and
      shasum-compare the archon worktree's Box against the branch before the gate. Only
      Box-changing PRs run the wrong prose — but the blast radius is wider (measured iteration 3,
      2026-08-24): the clobber covers the WHOLE tracked .archon/, so the review reads a working
      tree the author never created and can raise legitimate-looking findings about it (a critical
      "uncommitted config edit reverts a fix" that was Archon's own revert). Any .archon/-touching
      PR is exposed. Root cause read from the binary (2026-08-24, #411 — commands on its closing
      comment, https://github.com/unic/unic-agents-plugins/issues/411#issuecomment-5393118347):

      Archon 0.7.0's worktree-sync prepends .archon to its copy list unconditionally —
      worktree.copyFiles cannot remove it and no opt-out exists — and copies with
      fs.promises.cp(…, {recursive: true}), whose default force: true overwrites and never
      deletes: the canonical clone's files replace the branch's, extra branch files survive, the
      commit is untouched. Two sharpenings. The copy source is the canonical clone's working
      tree, not a ref
      — which is why staging an uncommitted file there is the workaround, and why
      any unstaged local edit in that clone leaks into every run. And the sync is mtime-gated
      on the two .archon directory mtimes — guaranteed at worktree creation, intermittent on
      resume — so an absence-of-clobber reproduction proves nothing; do not plan one. #411
      investigated the observed config modification and closed into this defect: the Box writes
      nothing (every config reference in unic-dlc-pr-review.yaml is a read, every write targets
      SESSION). A useful instrument fell out: the Archon CLI is a Bun bundle whose JavaScript is
      readable with strings — a "does Archon do X?" question can be answered at source, which
      beats the behavioural probe and answers why as well as whether.
    • archon workflow resume walks through an unresolved HITL approval gate. Measured 2026-08-26,
      run e56747e9cb561fb70a4a32dc2694daeb, the first real unic-dlc-pr-review run against
      PR 5798. The run paused at
      review-gate, then died with Process terminated (SIGTERM) while paused. archon workflow resume
      on it posted the whole review — one summary thread and nine inline threads — and reported
      Workflow completed successfully. No approval was ever accepted: both approve attempts
      errored. Verified independently from the tracker rather than from the run's own claim: threads
      65278–65287 on that pull request, all written 11:59:03–11:59:30, run completed at 11:59:51.
      This is an approval bypass on the one gate that makes a Box safe to run unattended, and every
      gate in DXP-DesignSystem's config is hitl. Mechanism, read from the binary: resume replays the
      DAG from getDagResumeSnapshot's completed-node outputs, and only an approval of type
      interactive_loop or child_workflow takes a special path — a plain approval gate is not
      re-asserted as a precondition, and the module's own resolveApprovalGate is not consulted on that
      path. The exact node-state precondition was not traced end to end; the conclusion rests on the
      measured outcome plus the shape of the resume path. Archon's side, not the Box's. Operationally:
      a crashed-at-gate run must be abandoned, never resumed.
    • A run dispatched as a shell background child dies with the shell. Same run, same day: the
      dispatch was a & child of an agent's tool shell, and an interactive interrupt killed its process
      group, so a paused run that should have waited at its gate indefinitely went to
      Process terminated (SIGTERM). Not Archon's defect so much as a dispatch rule nobody had written
      down: dispatch an Archon run as a detached or task-managed process, never as a shell & child.
      Every opener that dispatches a Box now says so.
    • A run keeps reporting running after its worktree is destroyed — the DB row is not
      liveness; check the working path exists and is a git repository. archon workflow abandon
      is the clean kill (2026-08-24, run a3a93876, evidence on #394).
    • archon workflow run exits 0 when it refuses to start — e.g. the source-symlink refusal
      from a sibling worktree. A dispatcher judging by exit code reads a refusal as a launch
      (2026-08-24, evidence on #394).
    • archon isolation cleanup can never clean a worktree a DLC Box produced. Measured
      2026-08-23: 0 cleaned, 7 failed, every one refused with "contains modified or untracked files,
      use --force to delete it"
      . Every unic-dlc-* run writes its session artefacts to
      <artifacts_dir>/<slug>/, which is relative and untracked, so the worktree is dirty by
      construction and cleanup calls git worktree remove without --force. The worktrees
      accumulate silently — seven on one repository inside six days. The sanctioned
      cleanup (settled 2026-08-24 on #394, replacing this passage's earlier by-hand advice): verify
      the run is terminal, then archon complete <branch> --force--force waives exactly the
      never-pushed check that rejects every read-only review run. Harvest first (2026-09-02, run e95e79db): terminal is not consumed. Every Box writes outward in its
      last node, so a killed run usually holds its complete, unposted product in <artifacts_dir>/<slug>/ — repo-relative,
      so only in the worktree — and complete deletes worktree and branch together. Copy that directory out before
      completing, or do not complete a run whose output was never consumed. If it is already gone,
      remote_agent_workflow_events in ~/.archon/archon.db holds every tool input and the summary can be rebuilt. isolation cleanup --merged
      compares against main, so a Gitflow repo never matches; [days] needs 7 days; bare
      complete refuses never-pushed branches. Never git worktree remove --force — that
      gesture, invited by this very accumulation, destroyed a live run's artefacts on 2026-08-24. WARNING (added
      2026-08-24, after it happened): check archon workflow status for running runs FIRST.
      A
      live run's worktree is dirty by construction and indistinguishable from abandoned scratch in
      git worktree list; this exact --force sequence destroyed a running review's session
      artefacts on !5788 (run a3a93876, commit survived, run did not). Not verified: whether the
      failed run still deregisters them, which would leave orphaned directories that
      archon isolation list cannot see.
    • approve, reject, resume and abandon are undocumented. archon --help lists none of
      them; the sole trace is a passing mention inside the --json flag description. Combined with
      the defect above, an operator who approves in the UI has no visible way to learn what to do next.
      Measured cost, 2026-08-26: wayfinder-379 needed to stop a review run that had bootstrapped
      from a stale commit, checked the help, found nothing between run and complete, and reported
      that 0.7.0 has no stop verb. The verbs are readable in the binary —
      case"abandon":{let L=Q[2];if(!L)return console.error("Usage: archon workflow abandon <run-id>"),
      "Usage: archon workflow resume <run-id>", and a CLI verb set
      new Set(["cancel","abandon","approve","reject"]) in which cancel and abandon are aliases.
      Abandon sets status:"cancelled" and reports cascadeFailures and blockedParentRunId, so it
      cascades to a blocked parent run. abandon is now confirmed on a LIVE run, not only on the
      zombie of 2026-08-24: run 9e2ff3e6 went cancelled at 11:37:06, archon complete <branch> --force removed its worktree, and a re-dispatch was running 22 seconds later against the true
      branch tip. The standing rule this makes explicit: absence from --help is not absence from the
      tool
      — grep the bundle for '"<verb>"'.

    One Archon behaviour worth recording as a design constraint rather than a defect: a resumed run
    prints "AI session context from prior nodes is not restored. Nodes that depend on prior context may
    need to re-read artifacts." post survived the resume only because it reads SESSION/comment.md
    from disk. A Box that leaned on conversation memory would resume blind, so the fresh-context and
    durable-artefact discipline (ADR-0012, ADR-0013) is load-bearing for resume, not only for
    determinism.

  • The Figma MCP needs edit access, not view accessanswered 2026-08-25 on
    #406
    : access granted, edit-for-read
    accepted with its price recorded, and a third access fact found — a primitive token value is
    unreachable even with edit access. All three facts, and the four file keys, are now content items on
    #414.

  • DXP-DesignSystem has no CI. Measured 2026-08-23 while working #377: no azure-pipelines.yml
    on develop, and none of the 49 pipelines in dev.azure.com/FZAG/dxp targets the repository. There
    is no test task in turbo.json and no root test script either. So every quality bar the first
    slices agree to — story, vitest browser test, DOM snapshot, a11y — runs only on a developer's
    machine, and Chromatic cannot be wired at all until a pipeline exists. Not this map's work, and the
    first thing that makes the Consumer's green look like a green.

  • The design file needs a change set before any slice runs, and nothing tracks it.
    #403 decided what changes: rename
    variantsvariant and its values to shadcn's, rename m/sdefault/sm, delete
    card-profile-main's has icon and has badge values
    — reverted on 2026-08-25 from #403's
    layout plus action slot, because the file has one slot already and the two values are designer
    convenience (#405) — merge button-round into Button
    as shape, add a focus value to every interactive component, and fix three typos
    (secundary, larg-ultra, a capitalised Default). That is Figma-side design work, so it belongs
    in dev.azure.com/FZAG/dxp as work items rather than here — and no work item exists for any of
    it
    . Until it does, the focus blocker stops /specs on every interactive component, which
    includes the card #379 is about to slice.
    Two smaller pieces sit in the same cluster, both narrowed by #404 on 2026-08-25.
    card-profile-main still has no Confluence spec page, which is where a component's applicable
    states and non-designable facts live — but the absence no longer blocks, because /specs now
    creates the page with an empty authored half. What is missing is the authored content, and one fact
    nobody has decided: which Confluence parent a component page is created under, now an acceptance
    criterion on #414, because /specs cannot
    create a page without it. The component-spec template that would carry the applicable-states
    checklist still does not exist. Also owed: the card
    shipped with no focus style by a decision that has since changed
    (#377), and #403 ruled it a defect to
    file rather than grandfathered.

  • Nothing detects a stale design contractanswered 2026-08-25 on
    #404
    : nothing detects it, and the answer
    is the named checkers rather than a mechanism — the human at the PRD gate, and the next /specs run
    for that component, which re-reads the design anyway. The stale Box copy still has no answer, same
    shape: a hand-carried artefact with no version marker.
    #408 is the ticket. One caveat carried
    forward: whether Figma's assetKey changes when a component is edited is unverified — it can be
    read, not watched change — so no design-side detection should be planned on it without a test.

  • What 1.0 means once FZAG has run. Decision 1 names the finish line; the version number, the
    changelog shape and the marketplace listing are not decided.

  • What re-verifies the four ADR-0011 schema traps now lib/schema-traps.mjs and its test are gone
    (#381, 2026-08-20). /archon-upgrade Step 5 is the only place they are re-asserted — by reading,
    in a command a human runs. Thinner than the deleted test, said so in the file, chosen by nobody.

  • The fate of /qa, /pr-review, /explore, /archon-upgrade Decided 2026-08-20 (grilled
    with the maintainer, alongside the post-implementation pipeline): /pr-review survives — it is
    the standard self-review flow for DXP-DesignSystem PRs, so #394 is promoted to p1 and its two
    review-gate defects below become debt on the daily path (mitigated by a standing never-reject
    rule: a reject destroys every finding). /archon-upgrade is kept — its proof is a first real
    run against Archon 0.8.0. /qa and /explore wait until after the ten-day goal. None of the
    four enters the 1.0 box set. The defect detail below stands as filed context. They are outside the 1.0 box set (decision 6) but
    nothing says whether they ship unproven, get cut, or wait. Two /pr-review gate defects wait on
    this decision
    , both found on 2026-08-18 by the first full run against Azure DevOps
    (DXP-DesignSystem !5769, run 510ebb0d129f009dc8ae2426d56a12cc). review-gate has neither an
    on_reject nor an on_approve: a reject discards a full review — fourteen minutes and every
    finding — with no record, where /qa's uat-gate keeps its $REJECTION_REASON; and the approval
    comment the Archon UI offers is never read, because post reads SESSION/comment.md and nothing
    else. The second is the shape of a silent failure — the operator believes they annotated the
    review. And the Box never emits a suggestion. Every finding carries "Suggested fix: …" as prose
    inside the comment body, so no reviewer gets an apply-this-change control; inline.json has no
    suggestion field at all. Whether each host renders one, and in what syntax, is the kind of fact the
    tracker contract now holds — so this is a Box capability to add, not a provider branch to write.
    Whoever decides this Box's fate decides all three with it.

  • Whether #362 still describes anything real. It reported that the pre-audit reads a stale tree and
    trusts its own auditor; decision 20 removes the pre-audit, so the stale-tree half is gone and only
    "trusts its own auditor" could still apply, to Gate 3. #372 is settled: it described the
    audited-commit marker, which decision 20 deletes. Both stay open for the close-list ticket.

  • What the Harness still owns once lib/ is gone and /setup is prose Decided 2026-08-20
    (grilled with the maintainer while working #381). #387 had answered the first third: the tracker
    half of the config schema is replaced by two repo docs the Methods already read. The other two are
    now answered, and neither is replaced by code.

    • Method resolution is one literal path, .archon/methods/<name>/SKILL.md, read the same way by
      every Box and every command. The config tier (methods.<name>.source) and the local tier
      (.archon/methods.local/) are retired, and with them the resolution order and the tier line
      (ADR-0031,
      amended). The tiers only ever reached the command half — an Archon node could not import
      resolveMethod — so retiring them made the two halves agree, which is what ADR-0023 §5's own
      constraint had been asking for.
    • The issues schema is the seven mandatory fields, stated as a table in /tickets Step 8 and
      checked by reading. Ordering is prose: a slice follows every slice its blocked_by names, a
      blocked_by naming an id absent from the file is an error rather than a slice that ships first,
      and a cycle stops the step by name instead of getting an invented order written into the baton.
    • What it cost is on the ticket, not hidden here. The upstream-rename tripwire is gone: the
      deleted tests compared two hand-written surfaces inside this repository and never watched
      upstream, so they could not have caught the v1.1.0 wave they were written for. The root
      AGENTS.md now names the moment the check happens — diff the vendored Bundle against the new
      upstream tag by hand, in the commit that moves the pin — and between two upgrades a rename
      surfaces on the next Consumer run.

Out of scope

The triage pass landed on 2026-08-15 — [Triage every

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with /wayfinder 373 to identify the next frontier ticket, then read that ticket's newest “How to start this session” comment before inspecting its named files and documents. Done means the selected ticket's prose deliverable and acceptance criteria are complete, with decisions recorded in the specified ADR or documentation homes and no code added unless prose cannot act.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript, tailwindcss
Domain
developer-experience, documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Needs clarification
Newbie friendliness
20/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.