jpmschweitzer/settled-reach
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge remote-tracking branch 'origin/main' into visual

Browse Source
This commit is contained in:
jpmschweitzer
2026-02-12 23:28:25 +01:00
parent ebcaff1a05 fd775878e7
commit 30f6666d7d
69 changed files with 7773 additions and 722 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.claude/skills/create-skill/references/.gitkeep
View File
.claude/skills/create-skill/scripts/.gitkeep
View File
.claude/skills/review-pr/SKILL.md
+54 -49
View File
@@ -1,18 +1,18 @@
---
name: review-pr
description: >
Review a branch diff with dual agents before merge. Use when the user says
"review-pr", "review this PR", "review this branch", or invokes /review-pr.
Spawns Hoshe (code quality) and Tyre (architecture) in parallel to review
the diff against main. Reports approve/reject with inline comments.
Review a branch diff with team-appropriate agents before merge. Use when the
user says "review-pr", "review this PR", "review this branch", or invokes
/review-pr. Spawns reviewers matched to the branch type (code, copy, visual,
audio) in parallel. Reports approve/reject with inline comments.
user-invocable: true
allowed-tools: Bash, Read, Grep, Glob, Task
---
# PR Review Skill
Dual-agent review of a branch diff against main. Hoshe reviews code quality,
Tyre reviews architecture. Both must approve for a clean review.
Multi-agent review of a branch diff against main. Reviewer composition depends
on the branch type. All reviewers must approve for a clean review.
## Workflow
@@ -32,7 +32,21 @@ Fetch remote branches first:
git fetch --all
```
### 2. Generate the diff
### 2. Determine reviewer team
Map the branch name to a reviewer set. Use the branch prefix (before any `/`
or `-` suffix) to classify:
| Branch type | Branches | Reviewers |
|-------------|----------|-----------|
| **code** | `server`, `client`, `ci`, or unknown | Hoshe (code quality) + Tyre (architecture) |
| **copy** | `copy` | Hoshe (QA) + Paula (narrative depth) + Miri (world consistency) |
| **visual** | `visual` | Hoshe (QA) + Araminta (art direction) |
| **audio** | `audio` | Hoshe (QA) + Ozzie (player experience) |
If the branch name doesn't match any known type, default to **code** reviewers.
### 3. Generate the diff and read source files
```bash
git log --oneline main..<branch>
@@ -49,75 +63,66 @@ 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...<branch>` (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/<branch>:<path>`
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/<branch>:<path>` and include them in the prompt.
### 3. Spawn both reviewers in parallel
**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**.
Use the Task tool to spawn **two agents simultaneously** in a single message.
Use `model: sonnet` for both — sufficient for review, saves cost.
For agents without Bash, you MUST read the source files yourself (via
`git show origin/<branch>:<path>`) 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.
**Agent 1 — 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
- Request structured verdict: APPROVE or REQUEST_CHANGES with file-specific comments
### 4. Spawn reviewers in parallel
**Agent 2 — 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/<branch>:<path>`
- Request structured verdict: APPROVE or REQUEST_CHANGES with file-specific comments
Use the Task tool to spawn **all reviewers simultaneously** in a single message.
### 4. Present results
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.
Format the combined review as a table per reviewer:
All reviewers: request structured verdict: APPROVE or REQUEST_CHANGES with
file-specific comments.
### 5. Present results
Format the combined review as a table per reviewer. Include one section per
reviewer that was spawned (2 for code/visual/audio, 3 for copy):
```
## Review: <branch> -> main
## Review: <branch> -> main (type: code|copy|visual|audio)
### Hoshe (Code Quality): [APPROVE | REQUEST_CHANGES]
### <Reviewer Name> (<Focus>): [APPROVE | REQUEST_CHANGES]
[Summary]
| # | File | Severity | Issue |
|---|------|----------|-------|
| 1 | path:line | critical/warning/suggestion | description |
### Tyre (Architecture): [APPROVE | REQUEST_CHANGES]
[Summary]
| # | File | Severity | Issue |
|---|------|----------|-------|
| 1 | path:line | critical/warning/suggestion | description |
### <Reviewer Name> (<Focus>): [APPROVE | REQUEST_CHANGES]
...
### Verdict: [APPROVED | CHANGES REQUESTED]
```
The overall verdict is APPROVED only if **both** reviewers approve.
The overall verdict is APPROVED only if **all** reviewers approve.
## Prompt template for reviewers
Use this structure when constructing the agent prompts (adapt as needed):
```
Review the following branch diff for merge into main.
Review the following {branch_type} branch diff for merge into main.
Branch: {branch}
Branch type: {branch_type} (code|copy|visual|audio)
Commits:
{commit_log}
@@ -126,7 +131,7 @@ Diff stats:
[Source files or diff here — exclude vendor/generated code]
Review focus: {focus_area}
Your review focus: {focus_area}
Respond with:
1. Verdict: APPROVE or REQUEST_CHANGES
@@ -138,7 +143,7 @@ Respond with:
If no issues found, say APPROVE with a brief positive summary.
```
## Posting results to Gitea
## 6. Posting results to Gitea
After presenting results to the user, post the review as a PR comment:
@@ -149,7 +154,7 @@ tea comment --login schweitz --repo jpmschweitzer/settled-reach <PR_NUMBER> "<re
Use a heredoc for multi-line review bodies:
```bash
tea comment --login schweitz --repo jpmschweitzer/settled-reach <PR_NUMBER> "$(cat <<'REVIEW'
## Dual-Agent Review: <branch> -> main
## Review: <branch> -> main
...review content...
REVIEW
)"
@@ -163,7 +168,7 @@ Note: `tea pr reject` does not work on your own PRs. Use `tea comment` instead.
tea comment --login schweitz --repo jpmschweitzer/settled-reach <PR_NUMBER> "$(cat /tmp/review.md)"
```
## Merging approved PRs
## 7. Merging approved PRs
`tea pr merge` fails (405) when branches have conflicts with main. Merge
locally instead:
.claude/skills/review-pr/references/reviewer-profiles.md
+103
View File
@@ -0,0 +1,103 @@
# 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/<branch>:<path>`
## 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)** — NO BASH ACCESS
- `subagent_type`: `paula`, `model`: `sonnet`
- 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)** — NO BASH ACCESS
- `subagent_type`: `miri`, `model`: `sonnet`
- 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
- 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)** — 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:
- 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)** — NO BASH ACCESS
- `subagent_type`: `ozzie`, `model`: `sonnet`
- 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?
- Pacing — do sounds support or fight the gameplay rhythm?
- Memorable moments — will players remember these audio cues?
.claude/skills/search-docs/SKILL.md
+13 -64
View File
@@ -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 <file>
db/connectors/qdrant-health
db/connectors/qdrant-count
```
Or the Python script directly:
```bash
python3 db/connectors/qdrant_connector.py <command> [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
```
.claude/skills/start-sprint/SKILL.md
+80 -17
View File
@@ -6,7 +6,7 @@ description: >
/start-sprint. Merges main into the team branch, finds the active sprint,
reads the sprint briefing, and presents the work plan with ticket details.
user-invocable: true
allowed-tools: Bash, Read, Grep, Glob
allowed-tools: Bash, Read, Grep, Glob, TeamCreate, Task, TaskCreate, TaskUpdate, TaskList, SendMessage, AskUserQuestion
---
# Start Sprint Skill
@@ -80,25 +80,88 @@ Output a summary:
Do NOT mark any ticket as `in_progress` yet.
### 8. Enter plan mode
### 8. Confirm and spawn the team
After presenting the work plan summary, you MUST enter plan mode using the
`EnterPlanMode` tool. In plan mode:
Before spawning agents, use `AskUserQuestion` to confirm the work plan and
agent lineup with the user. If declined, stop.
1. **Create a concrete sprint plan** — for each actionable ticket, outline:
- What files need to be created or modified
- What the implementation approach is
- What order tickets should be tackled in (respecting dependencies)
- Any open questions or risks per ticket
Once confirmed:
2. **Include blocked tickets** — note what unblocks them and when they might
become actionable during the sprint.
#### 8a. Parse agents from the briefing
3. **Write the plan to the plan file** — the plan should be self-contained so
you can follow it step-by-step once approved.
Extract agent names from the `**Agents:**` line. Format:
```
**Agents:** Name (role), Name (role), ...
```
4. **Exit plan mode** — use `ExitPlanMode` to present the plan for user
approval before starting any implementation work.
Map each name to its `subagent_type` (lowercase):
- "Dudley (simulation)" → `dudley`
- "Stig (UI)" → `stig`
- "Tyre (architecture)" → `tyre`
- "Hoshe (QA)" → `hoshe`
- "Mellanie (author)" → `mellanie`
- etc. (see `.claude/agents/` for full roster)
Only after the user approves the plan should you mark the first ticket as
`in_progress` and begin implementation.
#### 8b. Create the team
```
TeamCreate(team_name: "sprint-{N}-{team}")
```
This makes you the team lead.
#### 8c. Create tasks from tickets
For each ticket in the briefing, create a task:
```
TaskCreate(
subject: "#{id}: {title}",
description: "Full ticket details from step 5, plus briefing notes
and integration points for this ticket.",
activeForm: "Working on #{id}: {short_title}"
)
```
After creating all tasks, mirror the dependency chain from the briefing
using `TaskUpdate` with `addBlockedBy`.
#### 8d. Spawn agents
For each agent from the `**Agents:**` line, spawn a teammate in the
background. Spawn all agents in parallel (one message, multiple Task calls):
```
Task(
subagent_type: "{name_lowercase}",
team_name: "sprint-{N}-{team}",
name: "{name_lowercase}",
prompt: "You are on the {team} team for Sprint {N}.
Branch: `{team}`
1. Read the sprint briefing: docs/sprints/sprint-{N}/{team}.md
2. Read the decision files referenced in the briefing.
3. Check TaskList for available work.
4. Claim an unblocked task (TaskUpdate with owner: your name),
mark it in_progress, and implement it.
5. When done, mark the task completed and check TaskList for
the next available task.
Use `db/connectors/ticket show <id>` for full ticket specs.",
description: "Sprint {N} {team}: {name}",
run_in_background: true
)
```
#### 8e. Report
Output to the user:
- Team name: `sprint-{N}-{team}`
- Agents spawned (names and roles)
- Tasks created (count actionable vs blocked)
- How to interact: `SendMessage` to talk to agents, `TaskList` to
check progress
You are now the team lead. Agents work autonomously — monitor via
`TaskList`, communicate via `SendMessage`, and handle blockers as
they arise.
.claude/skills/ticket/SKILL.md
+9 -26
View File
@@ -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 <command> [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 "<SQL>"` | Run SELECT queries |
| `db/connectors/sqlite-exec "<SQL>"` | 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 <id>
```
Returns full ticket with children, blockers, and dependents.
### Create ticket
```bash
db/connectors/ticket create <type> <title> [--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