chore: Improve Claude setup (#549)

Author: patricklafrance

.github/prompts/code-review.md

@@ -22,7 +22,7 @@ Before reviewing, consult the directory index in `CLAUDE.md` to identify relevan
 
 ## Agent skills
 
-When performing code reviews, load and use agent skills from `.agents/skills/`. Apply the skill mapping defined in [agent-skills.md](../../agent-docs/docs/references/agent-skills.md) (both "By file type" and "By import" tables) to the changed lines in the PR diff.
+When performing code reviews, load and use agent skills from `.agents/skills/`. Apply the skill mapping defined in [agent-skills.md](../../agent-docs/references/agent-skills.md) (both "By file type" and "By import" tables) to the changed lines in the PR diff.
 
 ## Issues reporting
 

.github/prompts/update-agent-docs.md

@@ -55,17 +55,17 @@ When documenting Squide:
 
 - `CLAUDE.md` is a **table of contents** — short, routing-focused, link-heavy.
 - `agent-docs/ARCHITECTURE.md` is a **high-level map** — key concepts and package domains.
-- `agent-docs/docs/` is the **structured knowledge base** — categorized, detailed, but concise.
+- `agent-docs/` is the **structured knowledge base** — categorized, detailed, but concise.
 
 ### File layout
 
 - `CLAUDE.md` — workspace root. Table of contents / navigation map.
 - `agent-docs/` — structured knowledge base:
   - `ARCHITECTURE.md` — high-level architecture overview
-  - `docs/design/` — design patterns: routing, data fetching, registrations, communication
-  - `docs/specs/` — package specifications and APIs
-  - `docs/references/` — build tooling, CI/CD, infrastructure
-  - `docs/quality/` — testing and quality standards
+  - `design/` — design patterns: routing, data fetching, registrations, communication
+  - `specs/` — package specifications and APIs
+  - `references/` — build tooling, CI/CD, infrastructure
+  - `quality/` — testing and quality standards
   - `adr/` — Architecture Decision Records
 
 ### Rules
@@ -79,33 +79,33 @@ When documenting Squide:
 - **Reference real paths.** Always cite actual file paths as evidence (e.g., `packages/core/src/`).
 - **No duplication.** If information exists in one document, link to it from others.
 - **No invention.** Only document what you can verify from actual files.
-- **Never use advisory language in agent instructions.** Use prohibition framing and state consequences. See [writing-agent-instructions.md](../../agent-docs/docs/references/writing-agent-instructions.md).
+- **Never use advisory language in agent instructions.** Use prohibition framing and state consequences. See [writing-agent-instructions.md](../../agent-docs/references/writing-agent-instructions.md).
 - ONLY modify files under `agent-docs/` and `CLAUDE.md` at the root. Modifying files outside this set will cause an infinite workflow loop.
 - Do NOT modify `CLAUDE.md`.
 
 ### ADR vs docs boundary
 
-ADRs record **why** a decision was made (the problem, the alternatives, the chosen option, and the trade-offs accepted). Operational details about **how** the decision is implemented belong in `agent-docs/docs/`.
+ADRs record **why** a decision was made (the problem, the alternatives, the chosen option, and the trade-offs accepted). Operational details about **how** the decision is implemented belong in `agent-docs/`.
 
 - **Belongs in an ADR:** the problem that motivated the decision, options evaluated, which option was chosen and why, architectural trade-offs accepted.
-- **Belongs in `agent-docs/docs/`:** file paths and storage locations, URL rewriting patterns, CLI commands and flags, permissions and access controls, step-by-step operational procedures, server start/build commands.
+- **Belongs in `agent-docs/`:** file paths and storage locations, URL rewriting patterns, CLI commands and flags, permissions and access controls, step-by-step operational procedures, server start/build commands.
 
 Examples:
 
-- **Good ADR sentence:** "Evidence is stored on an orphan branch so GitHub issue links remain stable across runs. See [ci-cd.md](../docs/references/ci-cd.md) for operational details."
+- **Good ADR sentence:** "Evidence is stored on an orphan branch so GitHub issue links remain stable across runs. See [ci-cd.md](../references/ci-cd.md) for operational details."
 - **Bad ADR sentence:** "Evidence files are pushed to the `dogfood-evidence` branch using `git push --force`, and URLs are rewritten from `./screenshots/` to `https://raw.githubusercontent.com/...`."
 
-**Never put operational details (commands, paths, configs, permissions, URL patterns) into an ADR.** State the decision and its rationale, then link to the relevant `agent-docs/docs/` file for implementation specifics. Operational content in ADRs drifts from the actual implementation and misleads agents into following stale procedures instead of reading the source of truth.
+**Never put operational details (commands, paths, configs, permissions, URL patterns) into an ADR.** State the decision and its rationale, then link to the relevant `agent-docs/` file for implementation specifics. Operational content in ADRs drifts from the actual implementation and misleads agents into following stale procedures instead of reading the source of truth.
 
 ### CLAUDE.md requirements
 
 CLAUDE.md must stay between 80–150 lines. It must contain:
 
 1. **Purpose** — 1–2 short paragraphs identifying the repository.
-2. **How to Navigate** — table linking to `agent-docs/ARCHITECTURE.md` and `agent-docs/docs/` categories.
+2. **How to Navigate** — table linking to `agent-docs/ARCHITECTURE.md` and `agent-docs/` categories.
 3. **"If You Are Working On…"** — routing table mapping tasks to documents.
 
-If any section grows too large, extract it into an `agent-docs/docs/` file and replace with a link.
+If any section grows too large, extract it into an `agent-docs/` file and replace with a link.
 
 ### agent-docs/ARCHITECTURE.md requirements
 

CLAUDE.md

@@ -16,26 +16,26 @@
 
 ### Design
 
-- [routing-and-navigation.md](./agent-docs/docs/design/routing-and-navigation.md) — Route types (public, protected, hoisted, nested), navigation items, AppRouter
-- [data-fetching.md](./agent-docs/docs/design/data-fetching.md) — TanStack Query, usePublicDataQueries, useProtectedDataQueries, orchestration flow, error handling, error boundaries
-- [deferred-registrations.md](./agent-docs/docs/design/deferred-registrations.md) — Two-phase registration, conditional routes/nav based on data, feature flags, or LaunchDarkly
-- [cross-module-communication.md](./agent-docs/docs/design/cross-module-communication.md) — Event bus (pub/sub), plugins, shared types
+- [routing-and-navigation.md](./agent-docs/design/routing-and-navigation.md) — Route types (public, protected, hoisted, nested), navigation items, AppRouter
+- [data-fetching.md](./agent-docs/design/data-fetching.md) — TanStack Query, usePublicDataQueries, useProtectedDataQueries, orchestration flow, error handling, error boundaries
+- [deferred-registrations.md](./agent-docs/design/deferred-registrations.md) — Two-phase registration, conditional routes/nav based on data, feature flags, or LaunchDarkly
+- [cross-module-communication.md](./agent-docs/design/cross-module-communication.md) — Event bus (pub/sub), plugins, shared types
 
 ### References
 
-- [development.md](./agent-docs/docs/references/development.md) — pnpm workspace rules, env vars, JIT packages, dependency versioning, Retype docs, pre-commit hook, full command reference, adding packages
-- [agent-skills.md](./agent-docs/docs/references/agent-skills.md) — Skill directories, editing skills
-- [build-tooling.md](./agent-docs/docs/references/build-tooling.md) — Rslib, Rsbuild, Turborepo task graph, shared configs
-- [ci-cd.md](./agent-docs/docs/references/ci-cd.md) — GitHub Actions workflows, concurrency, caching, dogfood workflow, smoke tests
-- [release-process.md](./agent-docs/docs/references/release-process.md) — Changesets workflow, changelogs, npm publishing, PR preview packages
-- [writing-agent-instructions.md](./agent-docs/docs/references/writing-agent-instructions.md) — Principles for writing instructions agents follow, CLAUDE.md design rules
+- [development.md](./agent-docs/references/development.md) — pnpm workspace rules, env vars, JIT packages, dependency versioning, Retype docs, pre-commit hook, full command reference, adding packages
+- [agent-skills.md](./agent-docs/references/agent-skills.md) — Skill directories, editing skills
+- [build-tooling.md](./agent-docs/references/build-tooling.md) — Rslib, Rsbuild, Turborepo task graph, shared configs
+- [ci-cd.md](./agent-docs/references/ci-cd.md) — GitHub Actions workflows, concurrency, caching, dogfood workflow, smoke tests
+- [release-process.md](./agent-docs/references/release-process.md) — Changesets workflow, changelogs, npm publishing, PR preview packages
+- [writing-agent-instructions.md](./agent-docs/references/writing-agent-instructions.md) — Principles for writing instructions agents follow, CLAUDE.md design rules
 
 ### Quality
 
-- [testing.md](./agent-docs/docs/quality/testing.md) — Vitest, smoke tests, browser validation, test infrastructure
+- [testing.md](./agent-docs/quality/testing.md) — Vitest, smoke tests, browser validation, test infrastructure
 
 ### Other
 
-- [specs/README.md](./agent-docs/docs/specs/README.md) — All `@squide/*` packages: key APIs, source locations (i18next, MSW, LaunchDarkly, module federation, Storybook)
+- [specs/README.md](./agent-docs/specs/README.md) — All `@squide/*` packages: key APIs, source locations (i18next, MSW, LaunchDarkly, module federation, Storybook)
 - [adr/README.md](./agent-docs/adr/README.md) — Creating ADRs: when to write, template, status lifecycle
 - [odr/README.md](./agent-docs/odr/README.md) — Creating ODRs: when to write, template, status lifecycle

agent-docs/ARCHITECTURE.md

@@ -31,12 +31,12 @@ For detailed patterns and APIs, read the design docs linked below. This section
 
 - **FireflyRuntime** — Central runtime object (`initializeFirefly()`). Manages module registration, routes, navigation, event bus, logging, env vars, feature flags, and plugins.
 - **Modules** — Domain-specific units exporting a register function (`ModuleRegisterFunction`). Autonomous — they never import from other modules.
-- **Two-Phase Registration** — (1) Initial registration at bootstrap, (2) deferred registration re-runs when global data or feature flags change. See [deferred-registrations.md](./docs/design/deferred-registrations.md).
-- **AppRouter** — Wraps React Router, assembles routes from all modules, orchestrates data fetching lifecycle. See [routing-and-navigation.md](./docs/design/routing-and-navigation.md).
-- **Global Data Fetching** — Built on TanStack Query (`usePublicDataQueries`, `useProtectedDataQueries`). See [data-fetching.md](./docs/design/data-fetching.md).
-- **Route Types** — Protected (default), Public, Hoisted, Nested. See [routing-and-navigation.md](./docs/design/routing-and-navigation.md).
+- **Two-Phase Registration** — (1) Initial registration at bootstrap, (2) deferred registration re-runs when global data or feature flags change. See [deferred-registrations.md](./design/deferred-registrations.md).
+- **AppRouter** — Wraps React Router, assembles routes from all modules, orchestrates data fetching lifecycle. See [routing-and-navigation.md](./design/routing-and-navigation.md).
+- **Global Data Fetching** — Built on TanStack Query (`usePublicDataQueries`, `useProtectedDataQueries`). See [data-fetching.md](./design/data-fetching.md).
+- **Route Types** — Protected (default), Public, Hoisted, Nested. See [routing-and-navigation.md](./design/routing-and-navigation.md).
 - **Environment Variables** — Runtime-attached (not `process.env`). Registered via `initializeFirefly()` or `runtime.registerVariable()`.
-- **Cross-Module Communication** — Event bus (pub/sub), plugins, shared types. See [cross-module-communication.md](./docs/design/cross-module-communication.md).
+- **Cross-Module Communication** — Event bus (pub/sub), plugins, shared types. See [cross-module-communication.md](./design/cross-module-communication.md).
 
 ## Sample Applications
 
@@ -51,5 +51,5 @@ Each sample follows: **host** → **shell** (layout, bootstrapping route) → **
 
 ## Further Reading
 
-- All `@squide/*` packages and APIs: [specs/](./docs/specs/)
+- All `@squide/*` packages and APIs: [specs/](./specs/)
 - See [CLAUDE.md](../CLAUDE.md) for the full documentation index.

…ocs/design/cross-module-communication.md …ocs/design/cross-module-communication.mdagent-docs/docs/design/cross-module-communication.md renamed to agent-docs/design/cross-module-communication.md agent-docs/docs/design/cross-module-communication.md renamed to agent-docs/design/cross-module-communication.md

@@ -34,5 +34,5 @@ Evidence: `.github/workflows/smoke-test.yml`, `.github/workflows/dogfood.yml`, `
 - The dogfood session can discover issues outside the fixed page list, providing broader coverage.
 - AI-driven tests are less deterministic than scripted tests. False positives (AI misreads the UI) are possible but expected to be rare for binary PASS/FAIL outcomes.
 - Both workflows use `agent-browser install --with-deps` and `pnpm serve-endpoints` (production-like build). The dogfood session takes longer (~5–10 min including build and QA time) due to its exploratory nature vs the smoke test's fixed page list.
-- Dogfood evidence is stored on the `dogfood-evidence` orphan branch so GitHub issue links remain stable across runs. See [ci-cd.md](../docs/references/ci-cd.md#dogfood-workflow) for operational details.
+- Dogfood evidence is stored on the `dogfood-evidence` orphan branch so GitHub issue links remain stable across runs. See [ci-cd.md](../references/ci-cd.md#dogfood-workflow) for operational details.
 - Dogfood findings are filed as GitHub issues for human triage — the workflow does not block PRs or deployments.

agent-docs/docs/design/data-fetching.md agent-docs/design/data-fetching.mdagent-docs/docs/design/data-fetching.md renamed to agent-docs/design/data-fetching.md

@@ -25,5 +25,5 @@
 | Decision | ODR |
 |---|---|
 | Skill SKILL.md body keeps only critical patterns; everything else lives in reference files. Body should not grow past ~250 lines. | [0008](./0008-skill-body-reference-split.md) |
-| CLAUDE.md uses a single Memory Index with keyword summaries — never a separate routing table. Section anchors are added only for files over ~80 lines with distinct, high-frequency sub-tasks. Never add foler links to category headings. Keep the file under ~55 lines. | [0010](./0010-claude-md-progressive-disclosure-design.md) |
+| CLAUDE.md uses a single Memory Index with keyword summaries — never a separate routing table. Section anchors are added only for files over ~80 lines with distinct, high-frequency sub-tasks. Never add folder links to category headings. Keep the file under ~55 lines. | [0010](./0010-claude-md-progressive-disclosure-design.md) |