docs(arch): skill-stack harmonization design contour — specs, SSOT rows, routing bindings - #1462
Merged
Conversation
added 22 commits
August 17, 2026 22:13
…(SSOT #253) Two deltas over the wrapped brainstorming loop: batch prerequisite-settled questions per round (dependent ones stay serial), and enumerate-before-done — the dialogue closes only when every design decision is answered or an explicit operator fork. Superpowers 6.2.0 verified to lack the mechanism (grep over the whole installed plugin: 0 hits; brainstorming pins one-question-per-message). Prior-art: prior-art-evaluations.md#253 (grill-me/grilling, ADAPT — only the tree/frontier mechanic transfers; recommendation-per-question and probe-don't-ask already exist as H1 + T8/T20).
…d ADAPT→ADOPT Operator-ratified design session (D1-D4): the compressed frontier-pacing paraphrase measurably lost upstream's non-blocking probe rule (same-day cold review vs the raw upstream text), so /arch §1 now consumes the grilling skill AS IS via the mattpocock-skills companion plugin (MIT, versioned, precedent #64 brainstorming) and keeps only a thin binding: brainstorming collision resolution, probe routing (T20/§1.5), AskUserQuestion as the round carrier (added to allowed-tools), and the spec's live decision register as the tree surface. Register format lands in the spec-template obligation; SSOT #253 revisit triggers gain a named recording surface + a vendor-copy fallback arm. Prior-art: prior-art-evaluations.md#253 (grill-me/grilling, ADOPT — companion plugin consumed AS IS; paraphrase channel measured lossy, hence the lift from ADAPT).
…to one list Adopted from mattpocock code-review's two-axis separation (one axis must not mask the other) during the 2026-08-17 plugin sweep; the §2 seats already report independently, this pins that their findings are presented side by side and never reranked across altitudes. Prior-art: prior-art-evaluations.md#253 (mattpocock-skills plugin sweep; doc-only edit, no new capability).
…w ownership idea Prep-doc for a future /arch design session: enumerates all three skill populations (ours 16, superpowers 6.2.0 14, mattpocock-skills 1.2.3 35 — all 35 read in full), maps collisions per capability area (sharpest: Matt tdd vs SP TDD contradict on refactor placement and seam scoping; diagnosing-bugs vs systematic-debugging claim the same trigger space), lists the six available resolution mechanisms with two unknowns (per-skill disable, routing precedence) as probes, and drafts a one-owner-per-area map plus a live decision register the design session starts from. Prior-art: prior-art-evaluations.md#253 (grilling ADOPT — this prep extends the same three-stack comparison to the full plugin; doc-only, no capability).
…ur hard references Measured map of what our machinery hard-references upstream (grep over skills/rules/agents/CLAUDE.md/templates): SDD is the most-referenced upstream and crosses the shipped axis (tier-home.md); requesting-code-review is the highest-risk collision zone because dispatcher/harvest contracts name it while Matt's code-review claims the same trigger space; TDD/debugging collisions carry routing risk only (zero hard edges from us). Also: D-H4 recorded as answered (parallel commit 09569a3 landed mid-session), §7 gains the re-probe-before-edit note. Prior-art: prior-art-evaluations.md#253 (same three-stack comparison; doc-only edit).
… audit Per-repo DeepWiki interrogation folded in: (a) the measured routable surface is exactly 11 mattpocock skills (user-invoked ones never enter the router — his collision policy is the user/model-invoked split, confirmed live in this session's skill listing); (b) Matt's refactor-out-of-loop is a June-2026 behavioral measurement («agents essentially never performed it»), not doctrine — D-H2 needs our own corpus check; (c) TDD edge CORRECTED: SDD's implementer-prompt.md:36 says bare «TDD», so the collision is transitive-contract grade, not routing-only; (d) superpowers documents Project > Personal > Plugin per-skill shadowing — new mechanism 7, P1 narrowed. New §4.5: our 16 skills audited — nothing deletable, orchestrator is the one THIN candidate (D-H9); D-H10 TDD shadow, D-H11 domain-modeling pairing added to the register. Prior-art: prior-art-evaluations.md#253 (same three-stack comparison; doc-only edit).
…didates + 4 raw ideas Operator correction folded in: «no collision» ≠ «no value» — the user-invoked planning skills get per-skill adopt/adapt verdicts (wayfinder ADAPT strongest; to-tickets ADAPT mechanizable; to-spec one section; implement REJECT; triage two residues). New §4.6 carries four raw ideas for the design session: (1) the decision map as the multi-session layer over /arch — D4's register lifted to wayfinder shape, map-location sub-fork included; (2) kickoff Blocked-by edges with a pipeline-computed frontier; (3) seams-first Testing-seams slot in the spec template, unlocking the seams half of D-H2; (4) glossary SSOT as a term-ownership generated index — the CONTEXT.md-free adaptation that makes the grilling+domain-modeling pairing adoptable (D-H11 re-opened from defer). Register grows D-H12-D-H14. Prior-art: prior-art-evaluations.md#253 (same three-stack comparison; doc-only edit).
…ion handoff Interview phase complete (frontier empty): P-1..P-6 operator premises, 15-area ownership map ratified (D-H1), decision register D-H0..D-H16 with falsifiers, mechanism set (prune script, CONTEXT.md rule+test, claim reorder, Blocked-by frontier, seams slot, aif plugin), probe register P1/P2a-c/P5-pending/P6, routed-work inventory for §3 exit routing. Awaiting §2 cold two-altitude review (this session's next step).
…landed Both §2 seats returned REVISE (9 + 8 findings). All round-triggering findings repaired in place: §1 restated as two declared lanes (TD-F1); prune radius narrowed to 2 machine-globally-justified items per the operator's F7 answer + --check pre-push drift detector (TD-F2/F7); D-H17 completes the ownership map to all 11 model-invocable skills (TD-F3); setup run re-bucketed attended (TD-F4); D-H5 claim mechanics specified with real machinery + P4 restored (TD-F5, B-M1/M2); §5.6 non-target named (B-M3); /vitest transfer dissolved (B-M4); D-H7/D-H8 counter statuses corrected (B-M5); D-H13 adopts incumbent 'Depends on' spelling (B-M6). New: P-7 premise + D-H18 consumer-axis contour routed out via chip. Full dispositions: §9 v2 entry.
#254-257 Round-2 delta review (both seats REVISE; all round-1 closures confirmed): - --check channel corrected: owner:'maintainer' section in the pre-push.ts section registry (the file ships to consumers but maintainer sections never compose on a consumer layout, fail-closed) — .husky/pre-push is an exec dispatcher with no sections (convergent TD/B finding). - D-H16 build item DISSOLVED: aif container mounts the host ~/.claude/plugins read-only (docker-compose.override.yml), so the plugin is already visible in-container and the prune/--check cover it by construction (measured round-2). - 'counter armed' made true instead of re-worded: D-H7/D-H8 arm + observation No.0 appended to SSOT #253; REJECT rows #254-257 added (Matt implement, ADR dir, severity-less review model, total-sweep pruning). Spec SS8 item 5 DONE in-session. Dispositions: spec SS9 v3 entry.
…sion edits Round 3 (targeted delta): both cold seats GO. Spec header → REVIEWED-GO; §9 round-3 entry (one TD MINOR accepted as recorded limit: container premise rests on untracked local docker-compose.override.yml — covered by D-H16 falsifier). Routed §8 item 2 small edits, per spec: - arch/SKILL.md §1: Testing seams slot added to the spec-template obligation (D-H14; seams-first adopted WITHOUT Matt's refactor placement) - ai-doc/SKILL.md: skill-authoring ownership note (standard=ours, process=SP writing-skills, writing-for-agents=REFERENCE) - rule-tests/SKILL.md: tautological-test anti-pattern REFERENCE note (D-H2 transfer (b))
Review GO (3 rounds), exit routing done (3 chips + in-session edits), SSOT appends landed. Handoff retained as closure record; residue = operator actions (spec SS8 item 1) + chip-routed umbrellas.
…-3 handoff Round-2 /arch contour (D-H18): interview closed, D-C1..D-C8 ratified with falsifiers; three-class collision model (factory CI / install-time census / informed consent); detect+declare+prescribe mechanism recorded. Cold review and exit routing DEFERRED behind the operator-mandated round-3 top-down creative re-examination (P-C3) — handoff written for the fresh session.
…xt bindings land Round 3 (D-C8, operator-mandated P-C3) executed per the handoff's membrane phase order. Operator-axis spec v4: D-H15 SUPERSEDED — the prune apparatus (script / wizard / --check pre-push section / gate P5) dissolved, replaced by CLAUDE.md routing bindings (repo section + ~/.claude/CLAUDE.md machine-global half, written in-session with live operator approval) + meta-kickoff.template.md binding line (D-H10 fallback promoted to primary); D-H8 gains a frontmatter-neutering ladder step. Round-2 spec v2: D-C1 re-cut to the thin form (static census prose + known-pair presence check; inventory-join engine not built), D-C9 fourth-stack admission boundary added (knowledge-work trio stays on SSOT #235). Round-3 handoff closed with the continuation-state staleness correction; keen-shannon merged in (3ae6981) so both specs live on one branch.
…line Both P2-class triggers flip with the CLAUDE.md bindings in context (headless claude -p, fresh sessions reading the worktree CLAUDE.md from disk). Method finding recorded: in-session subagent probes are invalid for mid-session binding edits — subagents inherit the parent's session-start CLAUDE.md snapshot (measured via a failed in-session probe plus its diagnostic follow-up).
Convergent BLOCKER fixed: the meta-kickoff.template.md binding line REMOVED — .claude/skills/pipeline/ ships to consumers via GETFF_SKILLS_ENV (setup.d/lib.sh:59) at the default env profile, so carrier #3 breached the operator-axis membrane while buying no coverage; its removal restores all 8 install fingerprints to the baseline blob. §5.1's «no mechanical channel at all» premise corrected (config layer only; frontmatter + a possible Skill-matched PreToolUse hook priced — P8 records the hook UNVERIFIED: guide claims no Skill matcher, live harness observation contradicts). P7 restated honestly (1 measured flip + 1 post-only confirmation). SSOT #253/ #257 got dated supersession notes (no prune ever executed). Five residual prune assertions re-cut. Consumer spec: population corrected — TWO shipped cc-plugin rows (superpowers + ast-grep, the latter disabled on the operator's own machine); presence check re-keyed on installed_plugins.json + enabledPlugins; D-C5/D-C6 aligned; class-2 own-skills half recorded as prose-only limit. ESCALATED to operator: ast-grep shipping fate (ESC-1) + the detection-wire fork (TD-M2/P8). ~/.claude/CLAUDE.md section relocated to file end (orphaned AIF bullet restored to its heading).
…nded Both R2 seats REVISE with a convergent root cause: R1 edited the surfaces findings argued FROM, not every surface repeating the claim. Closed: §1 premise re-cut to config-layer wording; §1 scope guard now names the pre-round-3 routed edits as verified degrade-safe REFERENCEs; sixth prune assertion re-cut (D-H16); handoff header unmerged label; D-H15 exclusivity hedge; consumer D-C1/§7 re-keyed on installed_plugins.json + enabledPlugins; both §8 inventories carry the escalations. Operator answers recorded live: ESC-1 → retro-census BOTH shipped rows, keep ast-grep on a clean census; P8 → VERIFY via the settings.json hand-off (§8 item 7). Review round cap (2 REVISE) reached — residual state surfaced in §9 instead of a third cold round.
consumer-satellite-contract (thin form: retro-census of BOTH manifest rows per the answered ESC-1, D-C2 principle test, AGENTS.md.template section + parity line, install-registry-keyed presence check) and skill-harmonization-mechanisms (CONTEXT.md pointer-rule test, four-part claim machinery closing probe P4, Depends-on frontier). Both carry host-verify contracts and the PR-pause note: they become dispatchable only when the spec branch merges to staging.
Merge-forward per .claude/rules/git-conflict-merge-forward.md (never rebase a published/parallel branch). Conflict resolution — .claude/orchestrator-prompts/skill-harmonization-mechanisms/kickoff.md (add/add): kept the ROUND-3 version from this branch (9f4e4b4, 80 lines), dropped the pre-round-3 version that landed on staging via #1458 (c6bc0ef, 259 lines). Rationale: round 3 (operator-ratified live, 2026-08-18) SUPERSEDED D-H15 — the prune script, its `--check` pre-push section, the wizard walkthrough and the P5 operator probe are all DISSOLVED, replaced by injected-context CLAUDE.md bindings that already landed in-session. #1458's kickoff was authored against the round-2 GO (spec commit f2d3fe2) and still carries S1 as a build stage, so dispatching from it would build a mechanism the design has killed. The round-3 kickoff carries the surviving three stages (anchors / claim / frontier) plus its own traps, gates and host-verify block. Prior-art: skipped — merge-forward conflict resolution, no new capability introduced
…round-3 kickoffs Principle 40 (`packages/core/principles/40-kickoff-rigor-label.test.ts`) requires every post-cutoff kickoff to carry a `Rigor label … L0 …` line with a legal value. Both round-3 kickoffs were authored without it and failed the gate at push time. - skill-harmonization-mechanisms → `build-and-verify`: all three surviving stages are factory-internal and reversible, each with a live RED/GREEN seam proof. - consumer-satellite-contract → `research-grade`: S3/S4 touch consumer-shipped surfaces (AGENTS.md.template, ./setup), which effort-worthiness §1 reserves for the research-grade contour. Prior-art: skipped — mechanical gate compliance on two doc files, no new capability
…0 labels The operator-registered log-only PreToolUse Skill hook fired on a forced model-invoked skill in a fresh headless session (JSON with tool_name=Skill + the skill name in tool_input). The guide-agent's 'skill loading bypasses the tool pipeline' claim is falsified — the P6 failure class again. Measured boundary: user-typed slash commands bypass the Skill tool (invisible to the wire, irrelevant: misroutes are model-invocations). TD-M2 closes — the log IS the v0 misroute detection wire feeding the D-H7 counter; spec §6 P8 + D-H8 + §8 item 7 updated. Both kickoffs gained effort-worthiness L0 rigor labels (parallel session's edit kept as-is).
…kills
The branch edits `.claude/skills/{ai-doc,arch,rule-tests}/SKILL.md` — all three are
shipped artefacts, so their fingerprints move in every stack baseline that carries
them. Captured with `SNAPSHOT_MODE=capture bash tests/install-sh/snapshot.sh`.
Diff reviewed before committing (round-3 R1 precedent: an unreviewed template edit
turned 8 fingerprints stale): exactly three payload paths changed hash — rule-tests
(22 occurrences), arch (16), ai-doc (16) — and every fingerprint file is 1:1 on line
count, so no payload entered or left any stack.
Prior-art: skipped — snapshot regeneration after a shipped-file edit, no new capability
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Lands the three-stack skill-harmonization design contour (rounds 1-3) so that the four
build umbrellas routed out of it become dispatchable. Until this merges, dispatch
precondition D-P1 blocks every stage: executors start from
staging, where the specsthat are their verbatim source of truth do not exist.
What lands
2026-08-18-skill-stack-harmonization-design.md,REVIEWED-GO after 3 cold two-altitude rounds), the consumer-axis design, the arch-prep
collision map, and the two continuation handoffs.
docs/meta-factory/prior-art-evaluations.md— fix(docs): session followup — SSOT #81 broken citation + README:74 drop Cline/Aider #253 counter arm + REJECT rowsresearch(M-A Stage 1): orchestrator skill per-H2-section audit vs 7 companions #254-257 (fuzzy collision detectors rejected at measured 13%/38% precision).
CLAUDE.md«Skill routingbindings» — injected-context routing instead of a plugin-cache prune.
skill-harmonization-mechanisms(round-3 form, 3 stages) andconsumer-satellite-contract.Conflict resolution (merge-forward, not rebase)
.claude/orchestrator-prompts/skill-harmonization-mechanisms/kickoff.mdconflictedadd/add against the copy that landed on staging via #1458. Kept the round-3 version
from this branch; dropped the pre-round-3 one. #1458's kickoff was authored against the
round-2 GO and still lists the prune script /
--checkpre-push section / wizard / P5operator probe as stage S1 — all four DISSOLVED by round 3 (operator-ratified live,
2026-08-18). Dispatching from the staging copy would have built a mechanism the design
had already killed. Recipe followed:
.claude/rules/git-conflict-merge-forward.md.Parked questions
None. The one judgment made in-flight — the L0 rigor labels required by principle 40,
absent on both round-3 kickoffs — is recorded in its own commit with the reasoning per
kickoff (
build-and-verifyfor the factory-internal umbrella,research-gradefor theconsumer-shipped one). Either is a one-line edit to revise.
Fidelity verdict
FIDELITY: skipped — this is a design-record landing PR (specs, SSOT rows, kickoffs, a
CLAUDE.md bindings section); it declares no substrate and ships no executable mechanism,
so there is no implementation-vs-spec surface for agents/fidelity-auditor.md to audit.
The mechanisms themselves land per-stage under the umbrellas this PR unblocks, each with
its own fidelity round.
§1.7 Forward-check applied
Checked this PR against the disciplines that own its surfaces before pushing.
doc-authority-hierarchy.md— each new spec declares its own authority scope; thekickoffs point at the spec as SSOT rather than restating decisions. file:line evidence:
.claude/orchestrator-prompts/skill-harmonization-mechanisms/kickoff.md:5effort-worthiness.md§2 L0 — both kickoffs now declare a rigor label; principle 40green locally. file:line evidence:
packages/core/principles/40-kickoff-rigor-label.test.ts:73git-conflict-merge-forward.md— the add/add conflict was resolved by merging stagingINTO this branch; no rebase, no force-push. file:line evidence:
.claude/rules/git-conflict-merge-forward.md:1no-paid-llm-in-ci.md— no CI-side model calls introduced; all review work wassession-bound. file:line evidence:
.claude/rules/no-paid-llm-in-ci.md:1build-first-reuse-default.md— no capability commit here; the prior-art consult wasspent at design time and is recorded per stage in the kickoffs.
§1.7 Backward-check applied
Swept the existing artefacts this PR's scope overlaps, for supersession and stale refs.
#1458's kickoff copy — SUPERSEDED, not merged: its S1 (prune +--check+ wizard)and the P5 gate are dissolved by round 3. file:line evidence:
.claude/orchestrator-prompts/skill-harmonization-mechanisms/kickoff.md:16append-only register rule. file:line evidence:
docs/meta-factory/prior-art-evaluations.md:1~/.claude/CLAUDE.mdmachine-global bindings — the repo-side section is the committedhalf of a pair whose other half is operator-local and deliberately uncommittable.
file:line evidence:
CLAUDE.md:1./setupedits live in the consumer-satellite-contract umbrella, not here. file:line evidence:
.claude/orchestrator-prompts/consumer-satellite-contract/kickoff.md:20Prior-art: skipped — design-record landing PR, no new capability introduced by the merge