From 905fc764f52ef92cf1490d795fbf4a8292c82d10 Mon Sep 17 00:00:00 2001 From: Jeroen Schweitzer Date: Thu, 12 Feb 2026 18:41:07 +0100 Subject: [PATCH 1/3] fix(skills): pass file contents to non-Bash reviewer agents in review-pr Paula, Miri, Ozzie lack Bash access and cannot git show from branches. Skill now documents which agents can self-serve and instructs the caller to read and paste file contents into prompts for agents that can't. Co-Authored-By: Claude Opus 4.6 --- .claude/skills/review-pr/SKILL.md | 45 ++++++++++++++++++++++--------- 1 file changed, 32 insertions(+), 13 deletions(-) diff --git a/.claude/skills/review-pr/SKILL.md b/.claude/skills/review-pr/SKILL.md index c9c23daf0..b4aaec879 100644 --- a/.claude/skills/review-pr/SKILL.md +++ b/.claude/skills/review-pr/SKILL.md @@ -46,7 +46,7 @@ or `-` suffix) to classify: If the branch name doesn't match any known type, default to **code** reviewers. -### 3. Generate the diff +### 3. Generate the diff and read source files ```bash git log --oneline main.. @@ -63,13 +63,24 @@ If the diff is empty, report "No changes to review" and stop. Three-dot diff with pathspec exclusions is unreliable. Instead, either: 1. Use `git diff main...` (full diff) and filter in the prompt, or -2. Have Tyre read source files directly from the branch: +2. Read source files directly from the branch: `git show origin/:` For large diffs (>1000 lines of source), provide **source files** rather than raw diff to reviewers — cleaner context, better reviews. Read files with `git show origin/:` and include them in the prompt. +**IMPORTANT — agent tool access:** Not all reviewer agents have Bash access. +Agents that CAN read from branches themselves: **Hoshe, Tyre, Araminta**. +Agents that CANNOT (no Bash tool): **Paula, Miri, Ozzie, Gestalt, Gore, Nigel**. + +For agents without Bash, you MUST read the source files yourself (via +`git show origin/:`) and **paste the file contents directly +into the agent prompt**. Do not tell these agents to read files — they can't. +For very large PRs, read the key files (new/heavily modified) and include +summaries or excerpts of minor changes. Also read and include the relevant +`decisions/*.md` files these agents need for context. + ### 4. Spawn reviewers in parallel Use the Task tool to spawn **all reviewers simultaneously** in a single message. @@ -113,20 +124,24 @@ Use `model: sonnet` for all — sufficient for review, saves cost. - File organization and structure - Missing or orphaned files -**Paula (Narrative Depth)** +**Paula (Narrative Depth)** — NO BASH ACCESS - `subagent_type`: `paula`, `model`: `sonnet` -- Prompt: Include the changed files and commit log. Tell Paula to read the - relevant `decisions/*.md` files first, then review for: +- Paula cannot read from branches. You must paste file contents and decision + files directly into the prompt. +- Prompt: Include full text of changed files, commit log, and relevant + `decisions/*.md` content. Ask Paula to review for: - Narrative quality and character voice consistency - Whether dialogue and monologue feel authentic to the characters - Consequences and stakes — do choices carry weight? - Political and interpersonal depth - Emotional resonance — does the text make you feel something? -**Miri (World Consistency)** +**Miri (World Consistency)** — NO BASH ACCESS - `subagent_type`: `miri`, `model`: `sonnet` -- Prompt: Include the changed files and commit log. Tell Miri to read the - relevant `decisions/*.md` files first, then review for: +- Miri cannot read from branches. You must paste file contents and decision + files directly into the prompt. +- Prompt: Include full text of changed files, commit log, and relevant + `decisions/*.md` content. Ask Miri to review for: - Lore accuracy — do facts match established setting? - Internal consistency across files - IP originality — nothing should read as a copy from another franchise @@ -145,10 +160,11 @@ Use `model: sonnet` for all — sufficient for review, saves cost. - Missing or broken references in scene/resource files - Import settings consistency -**Araminta (Art Direction)** +**Araminta (Art Direction)** — HAS BASH ACCESS - `subagent_type`: `araminta`, `model`: `sonnet` -- Prompt: Include the changed files and commit log. Tell Araminta to read - the style guide and relevant design docs first, then review for: +- Araminta can read files from branches via `git show`. Prompt: Include commit + log and diff stats. Tell Araminta to read the style guide and relevant + design docs first, then review for: - Visual consistency with the established style guide - Color palette adherence - UI pattern consistency (diegetic-first, clarity over beauty) @@ -167,9 +183,12 @@ Use `model: sonnet` for all — sufficient for review, saves cost. - Missing or broken references - Import/bus configuration consistency -**Ozzie (Player Experience)** +**Ozzie (Player Experience)** — NO BASH ACCESS - `subagent_type`: `ozzie`, `model`: `sonnet` -- Prompt: Include the changed files and commit log. Ask Ozzie to review for: +- Ozzie cannot read from branches. You must paste file contents directly + into the prompt. +- Prompt: Include full text of changed files and commit log. Ask Ozzie to + review for: - Emotional impact — does the audio enhance the moment? - Atmosphere and tone — does it feel like the Commonwealth? - Player feedback clarity — can the player tell what just happened? From f1bc79a0d2bc39ed08d1b36192dd1e2bbc14e065 Mon Sep 17 00:00:00 2001 From: Jeroen Schweitzer Date: Thu, 12 Feb 2026 18:41:53 +0100 Subject: [PATCH 2/3] refactor(skills): trim duplication and improve progressive disclosure - search-docs: remove content already in CLAUDE.md (basic commands, endpoints, examples), keep only unique operations and workflows - ticket: remove duplicated access method and SQL wrapper docs, add missing show --brief command reference - review-pr: extract branch-type reviewer profiles to references/reviewer-profiles.md, reducing SKILL.md from 287 to 187 lines while preserving all reviewer specifications - create-skill: remove empty .gitkeep placeholders from unused references/ and scripts/ directories Reviewed all skills against /create-skill conventions. Main findings were CLAUDE.md content duplication wasting context tokens and a progressive disclosure opportunity in the longest skill. Co-Authored-By: Claude Opus 4.6 --- .../skills/create-skill/references/.gitkeep | 0 .claude/skills/create-skill/scripts/.gitkeep | 0 .claude/skills/review-pr/SKILL.md | 106 +----------------- .../review-pr/references/reviewer-profiles.md | 96 ++++++++++++++++ .claude/skills/search-docs/SKILL.md | 77 +++---------- .claude/skills/ticket/SKILL.md | 35 ++---- 6 files changed, 121 insertions(+), 193 deletions(-) delete mode 100644 .claude/skills/create-skill/references/.gitkeep delete mode 100644 .claude/skills/create-skill/scripts/.gitkeep create mode 100644 .claude/skills/review-pr/references/reviewer-profiles.md diff --git a/.claude/skills/create-skill/references/.gitkeep b/.claude/skills/create-skill/references/.gitkeep deleted file mode 100644 index e69de29bb..000000000 diff --git a/.claude/skills/create-skill/scripts/.gitkeep b/.claude/skills/create-skill/scripts/.gitkeep deleted file mode 100644 index e69de29bb..000000000 diff --git a/.claude/skills/review-pr/SKILL.md b/.claude/skills/review-pr/SKILL.md index c9c23daf0..7ea3a0e3b 100644 --- a/.claude/skills/review-pr/SKILL.md +++ b/.claude/skills/review-pr/SKILL.md @@ -73,110 +73,10 @@ raw diff to reviewers — cleaner context, better reviews. Read files with ### 4. Spawn reviewers in parallel Use the Task tool to spawn **all reviewers simultaneously** in a single message. -Use `model: sonnet` for all — sufficient for review, saves cost. ---- - -#### Code reviews (`server`, `client`, `ci`) - -**Hoshe (Code Quality)** -- `subagent_type`: `hoshe`, `model`: `sonnet` -- Prompt: Include source code and commit log. Ask Hoshe to review for: - - Correctness and bug risks - - Error handling gaps - - Test coverage (are new features tested?) - - Code style and clarity - - Security concerns (OWASP top 10, injection risks) - - Performance issues - -**Tyre (Architecture)** -- `subagent_type`: `tyre`, `model`: `sonnet` -- Prompt: Include source code and commit log. Tell Tyre to read the relevant - `decisions/*.md` files first, then review for: - - Architectural consistency with project decisions - - API/interface design quality - - Dependency and coupling concerns - - Scalability implications - - Whether the change respects non-negotiable baselines (D-010, D-012) -- Tyre can read files directly from the branch using `git show origin/:` - ---- - -#### Copy reviews (`copy`) - -**Hoshe (QA)** -- `subagent_type`: `hoshe`, `model`: `sonnet` -- Prompt: Include the changed files and commit log. Ask Hoshe to review for: - - Formatting consistency (markdown, file naming, frontmatter) - - Broken references or links - - Spelling and grammar - - File organization and structure - - Missing or orphaned files - -**Paula (Narrative Depth)** -- `subagent_type`: `paula`, `model`: `sonnet` -- Prompt: Include the changed files and commit log. Tell Paula to read the - relevant `decisions/*.md` files first, then review for: - - Narrative quality and character voice consistency - - Whether dialogue and monologue feel authentic to the characters - - Consequences and stakes — do choices carry weight? - - Political and interpersonal depth - - Emotional resonance — does the text make you feel something? - -**Miri (World Consistency)** -- `subagent_type`: `miri`, `model`: `sonnet` -- Prompt: Include the changed files and commit log. Tell Miri to read the - relevant `decisions/*.md` files first, then review for: - - Lore accuracy — do facts match established setting? - - Internal consistency across files - - IP originality — nothing should read as a copy from another franchise - - Faction, technology, and location details match the worldbuilding docs - - Setting serves gameplay mechanics (asymmetric information, perception) - ---- - -#### Visual reviews (`visual`) - -**Hoshe (QA)** -- `subagent_type`: `hoshe`, `model`: `sonnet` -- Prompt: Include the changed files and commit log. Ask Hoshe to review for: - - File format and naming conventions - - Asset organization and directory structure - - Missing or broken references in scene/resource files - - Import settings consistency - -**Araminta (Art Direction)** -- `subagent_type`: `araminta`, `model`: `sonnet` -- Prompt: Include the changed files and commit log. Tell Araminta to read - the style guide and relevant design docs first, then review for: - - Visual consistency with the established style guide - - Color palette adherence - - UI pattern consistency (diegetic-first, clarity over beauty) - - Whether assets scale gracefully (boxes-with-labels to full-art) - - Mood and tone — sleek, advanced, subtle Commonwealth aesthetic - ---- - -#### Audio reviews (`audio`) - -**Hoshe (QA)** -- `subagent_type`: `hoshe`, `model`: `sonnet` -- Prompt: Include the changed files and commit log. Ask Hoshe to review for: - - File format and naming conventions - - Audio asset organization and directory structure - - Missing or broken references - - Import/bus configuration consistency - -**Ozzie (Player Experience)** -- `subagent_type`: `ozzie`, `model`: `sonnet` -- Prompt: Include the changed files and commit log. Ask Ozzie to review for: - - Emotional impact — does the audio enhance the moment? - - Atmosphere and tone — does it feel like the Commonwealth? - - Player feedback clarity — can the player tell what just happened? - - Pacing — do sounds support or fight the gameplay rhythm? - - Memorable moments — will players remember these audio cues? - ---- +Read `references/reviewer-profiles.md` for the full per-branch-type reviewer +specifications (agent types, models, prompt focus areas). Match the branch type +from step 2 to the corresponding section. All reviewers: request structured verdict: APPROVE or REQUEST_CHANGES with file-specific comments. diff --git a/.claude/skills/review-pr/references/reviewer-profiles.md b/.claude/skills/review-pr/references/reviewer-profiles.md new file mode 100644 index 000000000..a27e861ff --- /dev/null +++ b/.claude/skills/review-pr/references/reviewer-profiles.md @@ -0,0 +1,96 @@ +# Reviewer Profiles by Branch Type + +Use `model: sonnet` for all reviewers — sufficient for review, saves cost. + +## Code reviews (`server`, `client`, `ci`) + +**Hoshe (Code Quality)** +- `subagent_type`: `hoshe`, `model`: `sonnet` +- Prompt: Include source code and commit log. Ask Hoshe to review for: + - Correctness and bug risks + - Error handling gaps + - Test coverage (are new features tested?) + - Code style and clarity + - Security concerns (OWASP top 10, injection risks) + - Performance issues + +**Tyre (Architecture)** +- `subagent_type`: `tyre`, `model`: `sonnet` +- Prompt: Include source code and commit log. Tell Tyre to read the relevant + `decisions/*.md` files first, then review for: + - Architectural consistency with project decisions + - API/interface design quality + - Dependency and coupling concerns + - Scalability implications + - Whether the change respects non-negotiable baselines (D-010, D-012) +- Tyre can read files directly from the branch using `git show origin/:` + +## Copy reviews (`copy`) + +**Hoshe (QA)** +- `subagent_type`: `hoshe`, `model`: `sonnet` +- Prompt: Include the changed files and commit log. Ask Hoshe to review for: + - Formatting consistency (markdown, file naming, frontmatter) + - Broken references or links + - Spelling and grammar + - File organization and structure + - Missing or orphaned files + +**Paula (Narrative Depth)** +- `subagent_type`: `paula`, `model`: `sonnet` +- Prompt: Include the changed files and commit log. Tell Paula to read the + relevant `decisions/*.md` files first, then review for: + - Narrative quality and character voice consistency + - Whether dialogue and monologue feel authentic to the characters + - Consequences and stakes — do choices carry weight? + - Political and interpersonal depth + - Emotional resonance — does the text make you feel something? + +**Miri (World Consistency)** +- `subagent_type`: `miri`, `model`: `sonnet` +- Prompt: Include the changed files and commit log. Tell Miri to read the + relevant `decisions/*.md` files first, then review for: + - Lore accuracy — do facts match established setting? + - Internal consistency across files + - IP originality — nothing should read as a copy from another franchise + - Faction, technology, and location details match the worldbuilding docs + - Setting serves gameplay mechanics (asymmetric information, perception) + +## Visual reviews (`visual`) + +**Hoshe (QA)** +- `subagent_type`: `hoshe`, `model`: `sonnet` +- Prompt: Include the changed files and commit log. Ask Hoshe to review for: + - File format and naming conventions + - Asset organization and directory structure + - Missing or broken references in scene/resource files + - Import settings consistency + +**Araminta (Art Direction)** +- `subagent_type`: `araminta`, `model`: `sonnet` +- Prompt: Include the changed files and commit log. Tell Araminta to read + the style guide and relevant design docs first, then review for: + - Visual consistency with the established style guide + - Color palette adherence + - UI pattern consistency (diegetic-first, clarity over beauty) + - Whether assets scale gracefully (boxes-with-labels to full-art) + - Mood and tone — sleek, advanced, subtle Commonwealth aesthetic + +## Audio reviews (`audio`) + +**Hoshe (QA)** +- `subagent_type`: `hoshe`, `model`: `sonnet` +- Prompt: Include the changed files and commit log. Ask Hoshe to review for: + - File format and naming conventions + - Audio asset organization and directory structure + - Missing or broken references + - Import/bus configuration consistency + +**Ozzie (Player Experience)** +- `subagent_type`: `ozzie`, `model`: `sonnet` +- Prompt: Include the changed files and commit log. Ask Ozzie to review for: + - Emotional impact — does the audio enhance the moment? + - Atmosphere and tone — does it feel like the Commonwealth? + - Player feedback clarity — can the player tell what just happened? + - Pacing — do sounds support or fight the gameplay rhythm? + - Memorable moments — will players remember these audio cues? diff --git a/.claude/skills/search-docs/SKILL.md b/.claude/skills/search-docs/SKILL.md index 4da561f5e..04637933b 100644 --- a/.claude/skills/search-docs/SKILL.md +++ b/.claude/skills/search-docs/SKILL.md @@ -10,82 +10,39 @@ allowed-tools: Bash, Read, Grep, Glob # Search Docs Skill -Semantic search across Commonwealth project documents using Qdrant vector database and ollama embeddings. +Semantic search across project documents. Basic commands (`qdrant-search`, +`qdrant-index`, `qdrant-health`, `qdrant-count`) and endpoints are documented +in CLAUDE.md. This skill covers advanced operations and workflows. -## Access Method - -**Use the connector wrapper scripts:** -```bash -db/connectors/qdrant-search "query text" -db/connectors/qdrant-index -db/connectors/qdrant-health -db/connectors/qdrant-count -``` - -Or the Python script directly: -```bash -python3 db/connectors/qdrant_connector.py [args] -``` - -## Commands - -### Search -Find documents semantically related to a query: -```bash -db/connectors/qdrant-search "asymmetric information design" -db/connectors/qdrant-search "what did we decide about fog of war" -db/connectors/qdrant-search "engine requirements" -``` - -Returns top 5 matching document chunks with source file, heading, and relevance score. - -### Index a file -Add or update a document in the search index: -```bash -db/connectors/qdrant-index decisions/architecture.md -db/connectors/qdrant-index decisions/perception.md -db/connectors/qdrant-index docs/discussions/round-10-map-fog-borderless.md -db/connectors/qdrant-index docs/briefings/tyre.md -``` - -Files are chunked by markdown headings (# and ##). Each chunk is embedded via ollama and stored in Qdrant with metadata (source_file, heading, chunk_index). +## Advanced Commands ### Index a single chunk + For precise indexing of specific content: ```bash python3 db/connectors/qdrant_connector.py index "unique-id" "Text content to index" --metadata source=manual heading="Custom heading" ``` -### Health check -Verify connectivity to Qdrant and ollama: -```bash -db/connectors/qdrant-health -``` - -### Collection info -Check how many documents are indexed: -```bash -db/connectors/qdrant-count -``` - ### Create collection + Initialize the Qdrant collection (run once during setup): ```bash python3 db/connectors/qdrant_connector.py create-collection ``` -## Endpoints +## Bulk Indexing -Configured in `db/connectors/config.json`: -- **Qdrant:** `http://tower-of-joy:6333` -- **Ollama:** `http://tower-of-joy:11434` (model: nomic-embed-text) -- **Collection:** `commonwealth` (768 dimensions, cosine distance) +Index all project documents at once: +```bash +for f in decisions/*.md DISCUSSION.md TEAM.md docs/discussions/*.md docs/briefings/*.md; do + db/connectors/qdrant-index "$f" +done +``` ## Fallback If Qdrant or ollama is unreachable, fall back to grep-based search: ```bash -# Search across all project docs grep -r -i "search term" decisions/ DISCUSSION.md docs/ --include="*.md" ``` @@ -96,11 +53,3 @@ grep -r -i "search term" decisions/ DISCUSSION.md docs/ --include="*.md" 3. After briefing updates, re-index affected briefings 4. After decision changes, re-index the relevant decisions/*.md domain files 5. Use search to answer "did we discuss this?" questions with citations - -## Bulk indexing -To index all project documents at once: -```bash -for f in decisions/*.md DISCUSSION.md TEAM.md docs/discussions/*.md docs/briefings/*.md; do - db/connectors/qdrant-index "$f" -done -``` diff --git a/.claude/skills/ticket/SKILL.md b/.claude/skills/ticket/SKILL.md index a5df765cb..e5ef809a3 100644 --- a/.claude/skills/ticket/SKILL.md +++ b/.claude/skills/ticket/SKILL.md @@ -10,39 +10,17 @@ allowed-tools: Bash, Read, Grep, Glob # Ticket Skill -Manage the project ticketing database (shared `settledreach.db` in the worktree parent directory). - -## Access Method - -**Use the `ticket` CLI for all ticket operations:** -```bash -db/connectors/ticket [args...] -db/connectors/ticket --help -``` - -All output is JSON on stdout. - -For raw SQL access (rare), use the wrapper scripts: -| Script | Purpose | -|--------|---------| -| `db/connectors/sqlite-query ""` | Run SELECT queries | -| `db/connectors/sqlite-exec ""` | Run INSERT/UPDATE/DELETE | -| `db/connectors/sqlite-init` | Create/update database from schema | -| `db/connectors/sqlite-seed` | Seed initiatives from DECISIONS.md | +Manage the project ticketing database. Basic usage (`ticket list`, `ticket show`, +`ticket sprint --active`) and raw SQL wrappers are documented in CLAUDE.md. +This skill covers the full command reference. ## Commands -### List tickets +### List tickets (full flags) ```bash db/connectors/ticket list [--status S] [--priority P] [--epic N] [--sprint N] [--assigned A] [--team T] ``` -### Show ticket detail -```bash -db/connectors/ticket show -``` -Returns full ticket with children, blockers, and dependents. - ### Create ticket ```bash db/connectors/ticket create [--parent N] [--priority P] [--decision D] [--team T] @@ -88,6 +66,11 @@ db/connectors/ticket children <id> db/connectors/ticket count [--status S] ``` +### Batch show +```bash +db/connectors/ticket show --brief <id> [<id>...] +``` + ## Workflow 1. **SI (Project Manager)** is the primary user of this skill From d153035621003a06c16e888ae32b1efd9b3e288d Mon Sep 17 00:00:00 2001 From: Jeroen Schweitzer <jpmschweitzer@gmail.com> Date: Thu, 12 Feb 2026 18:42:06 +0100 Subject: [PATCH 3/3] chore(meta): update changelog Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> --- CHANGELOG.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 9474edaf8..59dcb5bcf 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,10 @@ Format based on [Keep a Changelog](https://keepachangelog.com/). ## [Unreleased] +### Changed +- Skills trimmed for CLAUDE.md deduplication — search-docs (-48%), ticket (-17%), review-pr (-35%) now reference CLAUDE.md for basics instead of repeating them +- Review-pr reviewer profiles extracted to `references/reviewer-profiles.md` for progressive disclosure + ### Added - Review-pr skill routes reviewers by branch type — server/client get Hoshe+Tyre, copy gets Hoshe+Paula+Miri, visual gets Hoshe+Araminta, audio gets Hoshe+Ozzie - Start-sprint skill spawns team agents from sprint briefings — parses the Agents line, creates a team with tasks from tickets, and launches all listed agents as background teammates