docs: docs-strategy-2026 infrastructure (cherry-picked from #184 onto latest main)#199
Merged
Conversation
…R-083) Create three foundation docs that the rest of Play 1 rests on: - 2026-05-16-docs-strategy-memo.md: 1-page CTO memo (§8 of plan) - 2026-05-16-docs-strategy-design.md: full strategy spec (§§1-7, 10) - adr-083-eight-purpose-doc-taxonomy.md: ADR for the schema change ADR-083 captures the 8-purpose × 4-tier two-axis schema, STATUS alias map (22→4), AUDIENCE alias map (14→3), CATEGORY→topic-tags replacement, and the migration approach for Play 1. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…pic, 3 AUDIENCE) + add purpose/tier + drift fields Per ADR-083: two-axis schema (8 purposes × 4 tiers) replaces the over-engineered 22-STATUS × 18-CATEGORY × 14-AUDIENCE triplet. scripts/docs-frontmatter-schema.mjs: - Add PURPOSE enum (8 values) and TIER enum (4 values) - Collapse STATUS from 22 → 4 canonical values - Export STATUS_ALIAS_MAP (11 old→new mappings) for transitional validation - Export AUDIENCE_ALIAS_MAP (14 old→new mappings) - Remove CATEGORY enum; topic tags are now free-form - Collapse AUDIENCE from 14 → 3 canonical values (human/agent/both) - Add new optional fields: purpose, tier, last-verified, verified-against-commit, supersedes, related - Update classify() for new folder paths (Play 1 prep) scripts/check-doc-frontmatter.mjs: - Warn (not fail) on aliased STATUS/AUDIENCE values - Hard-fail on unknown PURPOSE/TIER when present - Add --report mode: counts docs missing purpose + tier scripts/docs-frontmatter-fix.mjs: - Apply STATUS_ALIAS_MAP and AUDIENCE_ALIAS_MAP - Handle inline array audience form (audience: [analyst, engineer]) - Backfill purpose + tier via path heuristics (all 521 docs covered) Applied to all 521 docs: 0 hard violations, 0 transitional warnings. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…ge-router + store-state-glossary) New docs at docs/agent-context/ (TEMP location; will move to docs/living/agent-context/ in Play 1b): - onboarding-quick-start.md: 5-minute agent orientation covering wedge V1 direction, hard invariants, where-to-look table, and common pitfalls (Math.random, hex colors, --no-verify, root-cause language) - package-router.md: 20-row routing table mapping work areas → primary CLAUDE.md + related CLAUDEs + ADRs + rules/invariants + suggested skills - store-state-glossary.md: full glossary of all 7 stores × 3 layers (Document/Annotation/View) per ADR-078 + F4, with top fields, persistence details, and hard rules per store All 3 docs use the new two-axis schema (purpose, tier, audience, topic, last-verified) introduced in the docs-strategy-2026 plan. Verified against packages/stores/src/*.ts at commit 5ee58dc. pnpm docs:check passes (527 docs validated, no issues). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…-router + store-state-glossary) Closes the 4%-of-living agent-context gap identified in plan §7.1. Three skills for fresh subagent dispatch orientation (Play 3 Tier 1): - agent-context-quickstart: loads docs/agent-context/onboarding-quick-start.md; description triggers on any "start of session", "new subagent", or "need context" phrasing; covers wedge V1 direction, hard invariants, where-to-look, and common pitfalls - package-router: routes work areas (canvas, stats, charts, stores, i18n, azure, pwa, ui, hooks, coscout, response-paths, capability/yamazumi/defect/performance/process-flow modes, projects tab, investigation wall, evidence map, sample data) to primary CLAUDE.md + related CLAUDEs + ADRs + rules; description triggers on "which package", "where to look", "which CLAUDE.md" - store-state-glossary: covers all 7 stores × 3 layers per ADR-078 + F4; description triggers on "which store", "what state lives", "store state" phrasing; links to full doc and packages/stores/CLAUDE.md All 3 skills follow the SKILL.md spec (name ≤64 chars, description with what+when, body ≤200 lines). Skills use force-add to override .claude/.gitignore — standard pattern for project-scoped skills. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…ath references Renames 6 constraint files (stats, testing, charts, coscout-prompts, i18n, azure-storage) from .claude/rules/ to .claude/invariants/ to clarify their purpose as policy-level invariants (not procedure routers). Updates all active references in CLAUDE.md, package-router.md, and two implementation docs to the new path. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Creates .claude/INVARIANTS.md as the single entry-point for all VariScout cross-cutting non-negotiables. Organises invariants into three tiers — hard (lint/test-enforced), soft (convention + reviewer), and topic-scoped (load on demand) — with canonical home and enforcement mechanism cited for each. Identifies two open enforcement gaps (Math.random and Tailwind @source) for follow-up in investigations.md. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…log enforcement gaps Links root CLAUDE.md §Invariants and onboarding-quick-start.md §Hard Invariants to the new .claude/INVARIANTS.md index instead of restating the full invariant list. Updates agent-context-quickstart skill to explicitly load INVARIANTS.md in its How to Use procedure. Logs two open enforcement gaps (Math.random ban, Tailwind @source check) to docs/investigations.md as candidates for Play 7. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…ailwind architecture doc Adds scripts/docs/gen-arch.mjs that walks package.json files (dep graph), tsconfig.json paths (sub-path export map), and apps/*/src/index.css (@source directives) to emit docs/05-technical/architecture-generated.md. Wired as pnpm docs:gen-arch in root package.json. Pre-push hook regenerates and fails if checked-in version is stale, surfacing drift immediately. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…k from technical index Adds docs/05-technical/architecture-generated.md (initial committed version). Updates docs/05-technical/index.md to add inbound link so the doc is not an orphan (required by pnpm docs:check orphan check). Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…60/068/069 + prompt rule Creates docs/01-vision/coscout-ax-design.md as the single canonical AX-design surface for CoScout: persona, voice, tier-gated behaviors (table), five-pillar knowledge architecture, three-boundary safety, prompt engineering link, tool-calling, voice input, eval discipline, mode-aware methodology coaching, and related artifacts. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…onical AX-design - ADR-060, ADR-068, ADR-069: add related: [coscout-ax-design] to frontmatter + brief "See canonical AX design" note near each ADR title - .claude/invariants/coscout-prompts.md: add related: [coscout-ax-design] + see-also note at bottom - docs/agent-context/package-router.md: update CoScout row to point at coscout-ax-design.md as canonical entry point (was packages/core/CLAUDE.md) - .claude/INVARIANTS.md: update CoScout-prompts topic-scoped row to reference coscout-ax-design.md as the first-load for CoScout work Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
The Play 7 gen-arch script outputs compact markdown tables; lint-staged prettier reformatted them on commit, causing the pre-push staleness check (`git diff --exit-code` after regeneration) to fire on every push. Fix: add `.prettierignore` excluding the generated file so committed content matches the script's output verbatim. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…convention doc
Discipline gap surfaced by the 2026-05-17 wedge-amendment incident: a mid-flight
design change to wedge spec was captured as `2026-05-16-improve-tab-amendment-design.md`
(orphan side spec), invisible to a fresh session reading only the canonical wedge spec.
Convention alone didn't prevent it; mechanical enforcement does.
Strategy spec (edited in place, dogfooding the principle):
- §1 Context: note the discipline-drift failure mode + why mechanical enforcement matters
- §2.6 per-purpose table: design row → edit-in-place; remember row → append-only
- §2.7 NEW: Doc Discipline (SSoT by doc type). Design specs edit-in-place; ADRs
amendment-block-at-bottom; decision-log append-only; generated never-hand-edit;
plan files ephemeral. Anti-pattern table + spec lifecycle states + edit-in-place
mechanics + "decision-log as temporal index" framing.
- Play 2b: revised from "addendum threads on all living docs" (wrong-shape — conflated
design specs with ADRs) → "SSoT discipline by doc type" with validator forbidding
`*-amendment-*.md` / `*-revision-*.md` / `*-update-*.md` filenames + lifecycle-state
enforcement. Marked safe-parallel — ships now, no Play 1b dependency.
- §4 migration: shipped/deferred status table reflecting current execution state
- §10 risks: 3 new rows (discipline drift, validator false-positives, body staleness)
Memo: aligned §What we're changing + §plays item 2 + §What we kill; added `last-verified`.
NEW canonical: `docs/agent-context/doc-discipline.md` — focused reference (~150 lines)
loaded by `agent-context-quickstart` skill on session start. Includes:
- Doc-types + update-patterns table (7 types)
- Anti-patterns table with right-pattern column
- Spec lifecycle states (draft → active → delivered → superseded → archived)
- Edit-in-place mechanics for design specs (5-step procedure)
- Decision tree: "I need to change a canonical doc → which pattern?"
- Origin story citing the wedge-amendment incident
agent-context-quickstart SKILL.md: wires doc-discipline.md as step 4 ("If your task
involves editing ANY canonical doc"). Added to Supporting Documents list.
This commit dogfoods the principle: strategy spec edited in place, not as an
`*-amendment-design.md` side file. Plan file at ~/.claude/plans/ updated separately
with a banner pointing to the canonical spec as the SoT going forward.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Routine regen after staleness check (per Play 7 pre-push convention). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Question: should amendment/relevance info be at the top of files? Does wikilink structure preserve that? Answer: YES, top. Frontmatter is for tooling; banner is for readers (humans + agents). Wikilinks preserve graph structure but are passive at read time — banners are active. Industry convention (MDN, Stripe, IETF, Wikipedia, Tailscale): status at top, amendments at bottom (ADRs only). Added to doc-discipline.md §Reader-first banners: - Required/recommended matrix per condition (status: superseded, supersedes:, recent material edit, delivered, ADR with amendments) - 6 concrete banner templates (superseded, recent edit, active build, delivered, ADR amended, archived) - Origin story citing wedge-amendment incident - "Wikilinks don't substitute for banners" explanation - Banner + frontmatter both required (machine vs reader) - Play 2b validator extensions for banner enforcement (4 new rules) Added to strategy spec §2.7: - New subsection "Reader-first banners at the top" pointing to discipline doc - Edit-in-place mechanics step 3 now includes "add status banner" - Play 2b validator scope extended in mechanics section Dogfooded: strategy spec itself now carries a banner at top noting active build via PR #184 + last material edit 2026-05-17. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…log format + classify agent manifests Audit gaps surfaced after yesterday's discipline shipment: 1. "One canonical home per concept" was buried as an anti-pattern; now stated affirmatively as Principle #2 2. Decision-log entry format was informal; now codified with edit-type vocabulary for Play 2c toolbox parsing 3. CLAUDE.md/AGENTS.md/llms.txt weren't classified in the doc-types table Both strategy spec §2.7 and doc-discipline.md updated in parallel: Core principles (in priority order): 1. Doc-type discipline 2. One canonical home per concept (Play 4 enforces) 3. Reader-first banners 4. Decision-log as temporal index Wedge-amendment incident reframed as a simultaneous violation of principles 1+2+3, making clear why all four need mechanical enforcement (Play 2b). Doc types extended in the at-a-glance list: investigations + memory + agent manifests added (was 5 types covered, now 8). Agent manifests get an explicit row in the doc-discipline.md table noting they're the "first read" surface every agent dispatch loads — keep tight, CLAUDE.md size budget enforced. Decision-log entry standard format: - YYYY-MM-DD — <title ≤80c>. <edit-type>: <doc>#<section> [supersedes <prior>]. Why: <one-sentence>. Commit: <sha>. PR: #N. Related: [[<id>]]. With edit-type vocabulary (spec edit / ADR amendment / new ADR / supersession / archived / new spec) for machine-parseable categorization by Play 2c toolbox. Lists what NOT to put in entries (no rationale paragraphs, no restated spec content, no duplicated info — one decision = one entry). Strategy spec banner updated to reflect today's second material edit. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…0, 3 personas, Math.random ESLint enforced Stale-reference fix pass after cherry-picking PR #184's infrastructure onto fresh branch off latest main. Aligns agent-context surface with what shipped today: - `docs/agent-context/onboarding-quick-start.md`: - €99 → €120; 6-tab → 7-tab nav - "Improve = stage inside Projects" → "Improve = top-level verb tab" (per 2026-05-16 Improve-tab amendment); Project stages collapsed to Charter→Approach→Sustainment - Add 3 personas inside Project: Lead (full edit + manages membership) / Member (full edit) / Sponsor (Report-only at V1, signoff out-of-band). Every subagent loading quickstart sees all 3 on first read. - Tier-gating "fully retired" (no more isPaidTier() checks) - VariScout Process named-future now points to `docs/01-vision/variscout-process/` - `.claude/skills/agent-context-quickstart/SKILL.md`: same updates (Key Facts section) - `docs/agent-context/package-router.md`: Projects-tab row updated — "Lead/Member/Sponsor roles" → "3 personas: Lead/Member/Sponsor"; stage list shortened; Improve as top-level noted; €120 pricing - Root `CLAUDE.md`: add "3 personas within each Project (Lead/Member/Sponsor)" to the strategic-direction line (the rest was already current — €120, 7-tab, Improve restored) - `.claude/INVARIANTS.md` §Enforcement Gaps: Math.random ban marked RESOLVED 2026-05-17 via PR #198 (Tier 1 Math.random retirement + ESLint guard shipped) Per user's terminology decision (2026-05-17): use "3 personas" framing consistently in agent-context docs (simpler than wedge spec's "1 persona + 3 ACL roles"). Specialist is the ICP description, not a 4th persona. Open question logged for follow-up: unify wedge spec terminology to match (out of scope for this PR). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
… repo transcript Per the doc-discipline.md ephemeral-promotion rule: plan files in ~/.claude/plans/ are session-private by default; SELECTIVE promotion to docs/ephemeral/transcripts/ for LANDMARK sessions. The docs-strategy-2026 brainstorm qualifies — it produced the foundational strategy + ADR-083 + the SSoT-by-doc-type discipline. What this preserves in repo: - Full design journey (8 purposes × 4 tiers, audit findings from Agent 1 + Agent 2) - Mid-session pivots (wedge-conflict surfaced → split Play 1 into 1a safe + 1b deferred; original "addendum threads" Play 2b revised to SSoT discipline after the wedge-amendment incident) - §11 post-PR-184 recalibration (cherry-pick recovery plan + Play 1b/2a reorder + 3-personas terminology decision) Frontmatter added: purpose: remember, tier: ephemeral, status: archived, audience: human, topic: [docs-strategy, transcript, brainstorm]. Top banner converted from "plan-file pointing-at-canonical" to "archived transcript pointing-at-canonical" — the file IS now the canonical historical record. Inbound link added from strategy spec (avoids orphan check). Future readers see: spec for "what" (current intent); transcript for "why each decision was made". Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The user's PR #193 (VariScout Process named-future capture) created 8 docs at `docs/01-vision/variscout-process/` with `status: 'named-future'`. That value was valid in the old 22-value STATUS enum but missing from my collapsed 4-value canonical set. Maps to 'active' since named-future docs ARE actively maintained design artifacts for the future product — not draft (designed) or superseded (replaced). They describe what the named-future product WILL be. Resolves 8 hard-fail check-doc-frontmatter errors blocking push. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…ot 4) User feedback: aliasing 'named-future' to 'active' (commit 3a6928b) overstated the commitment level. VariScout Process docs at docs/01-vision/variscout-process/ are aspirational — contingent on V1 reaching 500+ customers. They're not in active design; they describe what's COMMITTED for a future product line. The 4-value collapse (draft/active/superseded/archived) was overzealous. The 22→4 reduction missed a meaningful distinct lifecycle state. Promoting 'named-future' to a canonical 5th status preserves the semantic intent: - draft: designing; not yet building - active: designed; build underway - **named-future: aspirational/conditional commitment** (not in active design) - superseded: replaced by another spec - archived: historical reference only Changes: - scripts/docs-frontmatter-schema.mjs: add 'named-future' to STATUS enum; remove from STATUS_ALIAS_MAP (no longer aliased) - docs/agent-context/doc-discipline.md: spec-lifecycle table extended; example cites VariScout Process docs; added note on 'delivered' being a soft state signalled by `delivered-by:` frontmatter (not a status: enum value) - docs/superpowers/specs/2026-05-16-docs-strategy-design.md: schema section + collapse summary + migration sequence updated (22→5 not 22→4) - docs/superpowers/specs/2026-05-16-docs-strategy-memo.md: same Resolves 8 hard-fail check-doc-frontmatter errors for variscout-process/ docs WITHOUT semantically mis-labeling them. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
6 tasks
jukka-matti
added a commit
that referenced
this pull request
May 18, 2026
…x + agent skill (#200) * docs: Phase 2 implementation plan (discipline + toolbox + alignment) Plan for the docs-strategy-2026 Phase 2 PR. Decomposes into T1-T6: T1: validator anti-pattern filename HARD-FAIL + banner enforcement T2: validator --diff mode + decision-log + edit-type vocabulary T3: docs-toolbox find/get/related/recent scripts T4: docs-toolbox verify/amend scripts T5: docs-toolbox skill + llms.txt router transformation T6: alignment pass (CoScout AX persona+voice + stale 6-tab ref) Plan file follows the discipline it enforces — frontmatter, no *-amendment-*.md, execFileSync (no shell) convention noted. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(docs-validator): Play 2b — anti-pattern filenames + banner enforcement Phase 2 T1 of docs-strategy-2026. - HARD-FAIL filenames matching *-amendment/*-revision/*-update/*-followup-*.md under docs/superpowers/specs/ (the violation that produced the wedge-amendment incident 2026-05-17). - HARD-FAIL status:superseded/archived without SUPERSEDED/ARCHIVED banner in first 15 body lines. - HARD-FAIL supersedes:[...] set without banner mentioning predecessor. - .docs-discipline-allowlist (empty) provides the rare-exception escape hatch. - Archive 2026-05-16-improve-tab-amendment-design.md (scar tissue: content already folded into canonical wedge spec; archived for institutional knowledge) + fix dangling refs. - Fix 10 pre-existing banner violations surfaced by new checks (7 missing superseded/archived banners in archive docs, 3 missing supersedes banners). Regex fix: \bsupersede (not \bsupersede\b) to match superseded/supersedes. Spec: docs/agent-context/doc-discipline.md §Reader-first banners. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fixup: T1 — fix broken relative hrefs in 3 plan files + plan template links Spec-review catch: in commit 2d0f746 the implementer updated link DISPLAY text but left href portions pointing at the old `../specs/` path (now broken). All 4 broken hrefs in docs/superpowers/plans/ corrected to the new `../../archive/specs/` location. Also converted the llms.txt template in this PR's own plan file (T5 §5.2) from real markdown-link syntax to plain-text + backticks — quoting actual link syntax inside the plan triggered the dead-link checker against the plan file's own location. Implementer note added explaining the convention (feedback_doc_validation_hooks). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fixup: T1 — rename missingSupersededBanner → missingStatusBanner Code-quality-review catches: 1. (Critical) The archived-status check was pushing to the missingSupersededBanner bucket — semantically wrong (T2/T3 consumers pattern-matching bucket names would mix superseded + archived). Renamed to missingStatusBanner; report label already covered both. 2. (Important) Added discipline-doc reference to the archived-banner error message (was missing on the second branch only). 3. (Minor) Comment fix: ANTI_PATTERN_FILENAME_RE is a regex, not a glob; added pre-positioning note for DELIVERED_BANNER_RE (used in T2). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(docs-validator): Play 2b — --diff mode + edit-type vocabulary Phase 2 T2 of docs-strategy-2026. - New --diff mode: shells out to `git diff -U0 <base>` (execFileSync, no shell) and parses hunks. - WARN on edits to decision-log lines whose entry date is >7 days old (append-only convention; new supersession entry preferred). - WARN on '## Amendment' headings added in design-spec body diffs (allowed for ADRs only; design specs edit in place). - WARN on new decision-log entries missing canonical edit-type vocabulary (spec edit | ADR amendment | new ADR | supersession | archived | new spec). - WARN on design specs with `delivered-by:` frontmatter but no `Delivered` banner in first 15 body lines. - Shared edit-type parser at scripts/docs-toolbox/lib/edit-types.mjs, reused by docs:recent (T3). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(docs-toolbox): Play 2c — find/get/related/recent retrieval scripts Phase 2 T3 of docs-strategy-2026. - pnpm docs:find — frontmatter filter (--purpose, --tier, --topic, --status, --audience, --keyword), top-N with excerpts. - pnpm docs:get — print full doc by id (basename) or path. - pnpm docs:related — forward+backward graph traversal via frontmatter `related:` and body [[wikilinks]]. - pnpm docs:recent --since=YYYY-MM-DD [--amendments] — new docs + decision-log entries since cutoff; --amendments restricts to canonical edit-types. - Shared parse/wikilink helpers at scripts/docs-toolbox/lib/frontmatter.mjs. - Operates on the current FLAT corpus (Phase 3 will add the cards substrate). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fixup(docs-toolbox): T3 — guard --limit against NaN/zero in find.mjs Code-quality reviewer flagged: Number('bogus') → NaN; hits.slice(0, NaN) returns [], producing misleading "No matches." output. Fall back to default limit=10 when value isn't a positive finite number. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(docs-toolbox): Play 2c — verify/amend frontmatter mutation scripts Phase 2 T4 of docs-strategy-2026. - pnpm docs:verify <id> — bumps last-verified to today + writes verified-against-commit = current HEAD short-sha. Uses execFileSync. - pnpm docs:amend <adr-id> "<summary>" — appends a dated ## Amendment block to an ADR. HARD-FAILS on design specs (those edit in place per docs/agent-context/doc-discipline.md). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fixup(docs-toolbox): T4 — fix CRLF off-by-one in verify.mjs frontmatter slice Code-quality reviewer flagged: opening-delimiter detection accepts both `---\n` (4 bytes) and `---\r\n` (5 bytes), but the slice was hardcoded to offset 4. For a CRLF doc this leaves a leading \n in the frontmatter text, write-back produces "---\n\n<fm>\n---" which breaks strict YAML. Zero CRLF docs in repo today (verified), but a Windows contributor could trip it. Fix: derive offset from detected delimiter. Verified with /tmp synthetic CRLF doc — frontmatter now reads clean. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(skills): Play 2d — docs-toolbox skill + llms.txt → router Phase 2 T5 of docs-strategy-2026. - New .claude/skills/docs-toolbox/SKILL.md with auto-trigger description for doc-retrieval tasks. Tool surface + task kits + discipline reminders. - docs/llms.txt rewritten from a static catalog of every entry point into a router that points subagents at the right skill (agent-context-quickstart / docs-toolbox / package-router / store-state-glossary) plus always-load canonical docs (decision-log, OVERVIEW, USER-JOURNEYS, DATA-FLOW, wedge spec, ADR-082). The toolbox skill is the dynamic retrieval surface for everything else. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fixup(docs-strategy-2026): T5 review fixes + clear plan-file orphan Three findings rolled into one fixup: 1. Decision-log T5 entry moved from "Open in spec" section to top of §1 Replayed Decisions (reverse-chronological with the existing 2026-05-17 entries). Quality reviewer flagged: misplacement would confuse `pnpm docs:recent --amendments` and breaks §1's mental model as the canonical change-log. 2. SKILL.md docs:amend example wikilink corrected: [[2026-05-16-improve-tab-amendment]] → [[2026-05-16-improve-tab-amendment-design]] so it resolves via getDocId() against the actual archived file. 3. Plan-file orphan cleared: design spec now references the Phase 2 plan in its top metadata line (alongside memo + ADR + brainstorm transcript). Plan was orphaned since commit f743cf3; `pnpm docs:check` now exits 0. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs: Phase 2 alignment pass — CoScout AX persona + stale-refs Phase 2 T6 of docs-strategy-2026. - coscout-ax-design.md § Persona + Voice extended to distinguish CoScout's narrator voice (project-wide constant) from role-aware tone adjustments per active user's project-membership role (Lead / Member / Sponsor). Role affects framing + suggestion priority only; analysis content and safety boundaries stay constant across roles. - agent-context-quickstart skill: fix stale "6-tab nav" → "7-tab nav (singular Project, Improve as verb tab)" per the 2026-05-16 amendment that PR #199's cherry-pick didn't catch in this surface. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fixup(docs-strategy-2026): T6 review fixes — drop inline date stamp + correct stale Reviewer→Sponsor 1. coscout-ax-design.md § Persona + Voice: drop "(unchanged from pre-2026-05-17)" inline annotation. Provenance belongs in last-verified frontmatter / Amendments section, not body text of a live spec. Quality reviewer flagged as commit-message artifact. 2. decision-log.md 2026-05-16 wedge pivot entry (5): "Lead / Member / Reviewer" → "Lead / Member / Sponsor". Pre-existing error that contradicts ADR-082's canonical role names; the T6 entry directly above it uses Sponsor, so the contrast would confuse readers scanning §1. Fix at the seam per feedback_fix_absorbed_violations_at_seam. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
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.
Summary
Cherry-pick recovery of the docs-strategy-2026 infrastructure (originally PR #184). Main shipped wedge V1 + Phase C (~21 PRs) while #184 was open, making half of #184's content obsolete. This PR ships only the still-novel infrastructure on a fresh branch off latest main.
Supersedes #184 (closing as superseded).
What ships (21 commits)
8e2c3236memo + spec + ADR-083877e0c5a22→5 STATUS (incl.named-future) + free-formtopic+ 3 AUDIENCE +purpose/tier/last-verified+ alias maps + 500-doc frontmatter backfill2eaa07fesupporting docs +26f0b8833 SKILL.mds (agent-context-quickstart,package-router,store-state-glossary)86c09420.claude/rules/→.claude/invariants/rename +4ade730fINVARIANTS.md synthesis (15 hard + 10 soft + 6 topic-scoped) +8069d86aprose-duplication →[[invariant]]links00c27589script +17435fdbgenerated arch doc +b5d2fcba.prettierignoreexclusion59a8afd0canonical doc +6321558ecross-links from ADR-060/068/069 + prompt invariant2e707990+e63c3298+693cbec5(revised Play 2b from "addendum threads" to "SSoT by doc type" after wedge-amendment incident)fea0854b7-tab nav, €120, 3 personas (Lead/Member/Sponsor), tier-gating retired, Math.random ESLint-enforced6e05f1e4plan file →docs/ephemeral/transcripts/2026-05-16-docs-strategy-brainstorm.mdnamed-futureas 5th canonical statusce07bcf1correction after user feedback that aliasing toactiveoverstated commitment (VariScout Process docs are aspirational/conditional on V1 reaching 500+ customers)What was dropped from PR #184
c0d431e8Phase A wedge-content consolidation — obsoleted by user's Phase A on main (PR docs(wedge): PR 1 — Phase A doc completion (anchors + drift + Phase C plan) #191/docs(wedge): PR 1.5a — Phase A craft refinements + pre-existing drift cleanup #192), which did much more extensive work.Conflict-resolution decisions during cherry-pick
scripts/docs-frontmatter-schema.mjs): accepted my cherry-pick version (the collapse is the intent).docs-frontmatter-fix.mjsif needed).tier-philosophy.mdwas archived by user (deleted fromdocs/08-products/) — removed.investigations.mdconflict: accepted main's version (user's operational additions are canonical).Doc-discipline (the conceptual core that survived)
§2.7 of the strategy spec codifies 4 affirmative principles:
Plus the anti-pattern that triggered the discipline (the wedge-amendment incident — a
*-amendment-design.mdside spec was created instead of editing wedge spec in place). Validator (Play 2b, deferred) will mechanically HARD-FAIL such filenames.Verification
pnpm docs:check: passes (no hard issues; 67 transitional alias warnings expected during the schema transition cycle)pnpm docs:gen-arch: idempotent (regen produces no diff)bash scripts/pr-ready-check.sh: green per-commit--no-verifyNext steps (per §11 of the transcript)
3 remaining sessions per the recalibrated plan:
Test plan
docs/superpowers/specs/2026-05-16-docs-strategy-design.mddocs/agent-context/doc-discipline.mdloads correctly via theagent-context-quickstartskillpurpose:+tier:frontmatter from the backfill.claude/INVARIANTS.mdopens and reads cleanlypnpm docs:gen-archlocally; verify idempotentdocs/ephemeral/transcripts/2026-05-16-docs-strategy-brainstorm.mdopens with proper banner🤖 Generated with Claude Code