From c20c1810b105a755d55929072c94235a0cfa0f81 Mon Sep 17 00:00:00 2001 From: Jeroen Schweitzer Date: Thu, 12 Feb 2026 15:37:38 +0100 Subject: [PATCH 1/2] chore(config): use $REPO_ROOT env var in all instruction files Each worktree now has REPO_ROOT pre-set in .claude/settings.local.json, removing the need for git rev-parse --show-toplevel at runtime. Updated CLAUDE.md, skills (start-sprint, plan-sprint, ticket, search-docs), briefing template, and qatux agent to use the env var prefix. Co-Authored-By: Claude Opus 4.6 --- .claude/agents/qatux.md | 2 +- .claude/skills/plan-sprint/SKILL.md | 16 +++---- .../references/briefing-template.md | 2 +- .claude/skills/search-docs/SKILL.md | 31 ++++++------- .claude/skills/start-sprint/SKILL.md | 9 +--- .claude/skills/ticket/SKILL.md | 45 ++++++++++--------- CLAUDE.md | 35 +++++++++------ 7 files changed, 72 insertions(+), 68 deletions(-) diff --git a/.claude/agents/qatux.md b/.claude/agents/qatux.md index 12230a27f..abc3adf15 100644 --- a/.claude/agents/qatux.md +++ b/.claude/agents/qatux.md @@ -44,7 +44,7 @@ Named after Qatux, the Raiel with perfect memory who helped Paula Myo by recalli - **Work in dedicated round files:** All new rounds happen in `docs/discussions/round-NN-topic.md` from the start. DISCUSSION.md is retired for new content. - **Update the discussion index ONLY when closing:** After a round is formally closed, update `docs/discussions/README.md` with the round entry (number, topic, decisions produced, file link). - **Update briefings:** After a round produces new decisions, update the relevant agent briefing files in `docs/briefings/`. -- **Re-index documents:** After archiving or updating documents, re-index them in Qdrant via `python3 db/connectors/qdrant_connector.py index-file `. +- **Re-index documents:** After archiving or updating documents, re-index them in Qdrant via `python3 "$REPO_ROOT/db/connectors/qdrant_connector.py" index-file `. ## Team workflow (mandatory) diff --git a/.claude/skills/plan-sprint/SKILL.md b/.claude/skills/plan-sprint/SKILL.md index 3764dfeef..4e3157de5 100644 --- a/.claude/skills/plan-sprint/SKILL.md +++ b/.claude/skills/plan-sprint/SKILL.md @@ -20,7 +20,7 @@ next sprint based on current project state. ### 1. Determine sprint number ```bash -db/connectors/ticket sprint --active +"$REPO_ROOT/db/connectors/ticket" sprint --active ``` Next sprint = active sprint ID + 1. If no active sprint, ask the user. @@ -30,8 +30,8 @@ Next sprint = active sprint ID + 1. If no active sprint, ask the user. Review the active sprint for carry-overs: ```bash -db/connectors/ticket list --sprint --status in_progress -db/connectors/ticket list --sprint --status ready +"$REPO_ROOT/db/connectors/ticket" list --sprint --status in_progress +"$REPO_ROOT/db/connectors/ticket" list --sprint --status ready ``` Any ticket not `done` is a potential carry-over. Note these for the briefing. @@ -41,16 +41,16 @@ Any ticket not `done` is a potential carry-over. Note these for the briefing. Pull candidate tickets by priority: ```bash -db/connectors/ticket epics --status backlog +"$REPO_ROOT/db/connectors/ticket" epics --status backlog ``` For critical epics, check their children: ```bash -db/connectors/ticket children +"$REPO_ROOT/db/connectors/ticket" children ``` -Use `ticket show --brief [...]` to quickly scan multiple tickets. +Use `"$REPO_ROOT/db/connectors/ticket" show --brief [...]` to quickly scan multiple tickets. ### 4. Read existing code state @@ -111,10 +111,10 @@ After the user approves, assign all selected tickets to the new sprint: ```bash # Create the sprint -db/connectors/sqlite-exec "INSERT INTO sprints (name, goal, status) VALUES ('Sprint N: Theme', 'goal', 'planned')" +"$REPO_ROOT/db/connectors/sqlite-exec" "INSERT INTO sprints (name, goal, status) VALUES ('Sprint N: Theme', 'goal', 'planned')" # Assign tickets -db/connectors/ticket sprint assign +"$REPO_ROOT/db/connectors/ticket" sprint assign ``` ### 9. Present summary diff --git a/.claude/skills/plan-sprint/references/briefing-template.md b/.claude/skills/plan-sprint/references/briefing-template.md index 5a81729cf..216a39cd6 100644 --- a/.claude/skills/plan-sprint/references/briefing-template.md +++ b/.claude/skills/plan-sprint/references/briefing-template.md @@ -26,7 +26,7 @@ Each team gets one briefing file at `docs/sprints/sprint-N/.md`. |---|-------|------------| | #ID | Title | #dependency or — | -Use `db/connectors/ticket show ` for full details. +Use `"$REPO_ROOT/db/connectors/ticket" show ` for full details. ## Key Decisions diff --git a/.claude/skills/search-docs/SKILL.md b/.claude/skills/search-docs/SKILL.md index 74b96a727..b41b4e9d0 100644 --- a/.claude/skills/search-docs/SKILL.md +++ b/.claude/skills/search-docs/SKILL.md @@ -14,9 +14,10 @@ Semantic search across Commonwealth project documents using Qdrant vector databa ## Access Method -**Use the connector script:** +**Use the connector script.** The `$REPO_ROOT` environment variable is pre-set +per worktree — always use it as a prefix: ```bash -python3 db/connectors/qdrant_connector.py [args] +python3 "$REPO_ROOT/db/connectors/qdrant_connector.py" [args] ``` ## Commands @@ -24,9 +25,9 @@ python3 db/connectors/qdrant_connector.py [args] ### Search Find documents semantically related to a query: ```bash -python3 db/connectors/qdrant_connector.py search "asymmetric information design" -python3 db/connectors/qdrant_connector.py search "what did we decide about fog of war" -python3 db/connectors/qdrant_connector.py search "engine requirements" +python3 "$REPO_ROOT/db/connectors/qdrant_connector.py" search "asymmetric information design" +python3 "$REPO_ROOT/db/connectors/qdrant_connector.py" search "what did we decide about fog of war" +python3 "$REPO_ROOT/db/connectors/qdrant_connector.py" search "engine requirements" ``` Returns top 5 matching document chunks with source file, heading, and relevance score. @@ -34,10 +35,10 @@ Returns top 5 matching document chunks with source file, heading, and relevance ### Index a file Add or update a document in the search index: ```bash -python3 db/connectors/qdrant_connector.py index-file decisions/architecture.md -python3 db/connectors/qdrant_connector.py index-file decisions/perception.md -python3 db/connectors/qdrant_connector.py index-file docs/discussions/round-10-map-fog-borderless.md -python3 db/connectors/qdrant_connector.py index-file docs/briefings/tyre.md +python3 "$REPO_ROOT/db/connectors/qdrant_connector.py" index-file decisions/architecture.md +python3 "$REPO_ROOT/db/connectors/qdrant_connector.py" index-file decisions/perception.md +python3 "$REPO_ROOT/db/connectors/qdrant_connector.py" index-file docs/discussions/round-10-map-fog-borderless.md +python3 "$REPO_ROOT/db/connectors/qdrant_connector.py" index-file 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). @@ -45,25 +46,25 @@ Files are chunked by markdown headings (# and ##). Each chunk is embedded via ol ### 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" +python3 "$REPO_ROOT/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 -python3 db/connectors/qdrant_connector.py health +python3 "$REPO_ROOT/db/connectors/qdrant_connector.py" health ``` ### Collection info Check how many documents are indexed: ```bash -python3 db/connectors/qdrant_connector.py count +python3 "$REPO_ROOT/db/connectors/qdrant_connector.py" count ``` ### Create collection Initialize the Qdrant collection (run once during setup): ```bash -python3 db/connectors/qdrant_connector.py create-collection +python3 "$REPO_ROOT/db/connectors/qdrant_connector.py" create-collection ``` ## Endpoints @@ -92,7 +93,7 @@ grep -r -i "search term" decisions/ DISCUSSION.md docs/ --include="*.md" ## 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 - python3 db/connectors/qdrant_connector.py index-file "$f" +for f in "$REPO_ROOT"/decisions/*.md "$REPO_ROOT"/DISCUSSION.md "$REPO_ROOT"/TEAM.md "$REPO_ROOT"/docs/discussions/*.md "$REPO_ROOT"/docs/briefings/*.md; do + python3 "$REPO_ROOT/db/connectors/qdrant_connector.py" index-file "$f" done ``` diff --git a/.claude/skills/start-sprint/SKILL.md b/.claude/skills/start-sprint/SKILL.md index 2aaf2df40..92ffa0a83 100644 --- a/.claude/skills/start-sprint/SKILL.md +++ b/.claude/skills/start-sprint/SKILL.md @@ -17,14 +17,9 @@ briefing, and present actionable next steps. ## Path resolution (CRITICAL) This project uses **git worktrees**. Each team branch is a separate directory. -All file paths MUST be resolved from the worktree root, never guessed. +All file paths MUST use `$REPO_ROOT` as a prefix — this environment variable +is pre-set in each worktree's `.claude/settings.local.json`. -**First**, resolve the repo root and store it for all subsequent commands: -```bash -REPO_ROOT="$(git rev-parse --show-toplevel)" -``` - -Then use `$REPO_ROOT` as a prefix for every path in this skill: - Ticket CLI: `"$REPO_ROOT/db/connectors/ticket"` - Sprint briefings: `"$REPO_ROOT/docs/sprints/sprint-N/.md"` - Decision files: `"$REPO_ROOT/decisions/*.md"` diff --git a/.claude/skills/ticket/SKILL.md b/.claude/skills/ticket/SKILL.md index 00feba4d3..c3998c808 100644 --- a/.claude/skills/ticket/SKILL.md +++ b/.claude/skills/ticket/SKILL.md @@ -14,10 +14,11 @@ Manage the Commonwealth project ticketing database at `db/commonwealth.db`. ## Access Method -**Use the `ticket` CLI for all ticket operations:** +**Use the `ticket` CLI for all ticket operations.** The `$REPO_ROOT` environment +variable is pre-set per worktree — always use it as a prefix: ```bash -db/connectors/ticket [args...] -db/connectors/ticket --help +"$REPO_ROOT/db/connectors/ticket" [args...] +"$REPO_ROOT/db/connectors/ticket" --help ``` All output is JSON on stdout. @@ -25,67 +26,67 @@ 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 | +| `"$REPO_ROOT/db/connectors/sqlite-query" ""` | Run SELECT queries | +| `"$REPO_ROOT/db/connectors/sqlite-exec" ""` | Run INSERT/UPDATE/DELETE | +| `"$REPO_ROOT/db/connectors/sqlite-init"` | Create/update database from schema | +| `"$REPO_ROOT/db/connectors/sqlite-seed"` | Seed initiatives from DECISIONS.md | ## Commands ### List tickets ```bash -db/connectors/ticket list [--status S] [--priority P] [--epic N] [--sprint N] [--assigned A] [--team T] +"$REPO_ROOT/db/connectors/ticket" list [--status S] [--priority P] [--epic N] [--sprint N] [--assigned A] [--team T] ``` ### Show ticket detail ```bash -db/connectors/ticket show +"$REPO_ROOT/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] +"$REPO_ROOT/db/connectors/ticket" create <type> <title> [--parent N] [--priority P] [--decision D] [--team T] ``` Types: `initiative`, `epic`, `story`, `task`, `bug` Priorities: `critical`, `high`, `medium`, `low` ### Update status ```bash -db/connectors/ticket status <id> <new_status> -db/connectors/ticket done <id> [<id> ...] +"$REPO_ROOT/db/connectors/ticket" status <id> <new_status> +"$REPO_ROOT/db/connectors/ticket" done <id> [<id> ...] ``` Statuses: `backlog`, `ready`, `in_progress`, `review`, `done`, `cancelled` ### Assignment ```bash -db/connectors/ticket assign <id> <agent> -db/connectors/ticket unassign <id> +"$REPO_ROOT/db/connectors/ticket" assign <id> <agent> +"$REPO_ROOT/db/connectors/ticket" unassign <id> ``` ### Team assignment ```bash -db/connectors/ticket team <id> <teams> +"$REPO_ROOT/db/connectors/ticket" team <id> <teams> ``` Teams are comma-separated, e.g. `server`, `client`, `server,client`. ### Sprint management ```bash -db/connectors/ticket sprint [--active] -db/connectors/ticket sprint assign <id> <sprint_id> +"$REPO_ROOT/db/connectors/ticket" sprint [--active] +"$REPO_ROOT/db/connectors/ticket" sprint assign <id> <sprint_id> ``` ### Dependencies ```bash -db/connectors/ticket deps <id> +"$REPO_ROOT/db/connectors/ticket" deps <id> ``` ### Search and browse ```bash -db/connectors/ticket search <keyword> -db/connectors/ticket epics [--status S] -db/connectors/ticket children <id> -db/connectors/ticket count [--status S] +"$REPO_ROOT/db/connectors/ticket" search <keyword> +"$REPO_ROOT/db/connectors/ticket" epics [--status S] +"$REPO_ROOT/db/connectors/ticket" children <id> +"$REPO_ROOT/db/connectors/ticket" count [--status S] ``` ## Workflow diff --git a/CLAUDE.md b/CLAUDE.md index acd32bb7d..71e989703 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -51,32 +51,39 @@ See [docs/DEVOPS.md](docs/DEVOPS.md) for build, test, lint, and CI procedures. A ## Agent Instructions +### Path resolution + +This project uses **git worktrees** — each team branch is a separate directory. +The `$REPO_ROOT` environment variable is pre-set per worktree via +`.claude/settings.local.json`. Use it as a prefix for all path-sensitive +commands (especially Bash calls to scripts and CLIs). + ### Before starting work -1. Read your sprint briefing at `docs/sprints/sprint-N/{team}.md` for current tasks -2. Use `db/connectors/ticket show <id>` for full ticket details -3. Read the relevant `decisions/*.md` domain file(s) referenced in the briefing -4. Background context: `docs/briefings/{your-name}.md`, `docs/discussions/` +1. Read your sprint briefing at `$REPO_ROOT/docs/sprints/sprint-N/{team}.md` for current tasks +2. Use `"$REPO_ROOT/db/connectors/ticket" show <id>` for full ticket details +3. Read the relevant `$REPO_ROOT/decisions/*.md` domain file(s) referenced in the briefing +4. Background context: `$REPO_ROOT/docs/briefings/{your-name}.md`, `$REPO_ROOT/docs/discussions/` ### Ticket and database access **Prefer the ticket CLI over raw SQL.** The CLI handles column names, joins, and output formatting correctly: ```bash -db/connectors/ticket list --sprint 2 --team server -db/connectors/ticket show 78 -db/connectors/ticket sprint --active +"$REPO_ROOT/db/connectors/ticket" list --sprint 2 --team server +"$REPO_ROOT/db/connectors/ticket" show 78 +"$REPO_ROOT/db/connectors/ticket" sprint --active ``` Only fall back to raw SQL for queries the CLI doesn't support. **Never use the `sqlite3` CLI** — it crashes in Claude Code due to a known std::bad_alloc bug. Use the wrapper scripts instead: ```bash -db/connectors/sqlite-query "SELECT * FROM tickets WHERE status='in_progress'" -db/connectors/sqlite-exec "UPDATE tickets SET status='done' WHERE id=1" +"$REPO_ROOT/db/connectors/sqlite-query" "SELECT * FROM tickets WHERE status='in_progress'" +"$REPO_ROOT/db/connectors/sqlite-exec" "UPDATE tickets SET status='done' WHERE id=1" ``` ### Qdrant / document search ```bash -db/connectors/qdrant-search "asymmetric information design" -db/connectors/qdrant-index docs/briefings/tyre.md -db/connectors/qdrant-health -db/connectors/qdrant-count +"$REPO_ROOT/db/connectors/qdrant-search" "asymmetric information design" +"$REPO_ROOT/db/connectors/qdrant-index" docs/briefings/tyre.md +"$REPO_ROOT/db/connectors/qdrant-health" +"$REPO_ROOT/db/connectors/qdrant-count" ``` ### Gitea access (tea CLI) @@ -112,7 +119,7 @@ Key rules: - Decision IDs: `D-NNN` (confirmed), `Q-NNN` (open questions), `R-NNN` (rejected) - Discussion rounds: numbered sequentially, archived to `docs/discussions/` when complete - Briefings: one per agent, updated after decision-producing rounds -- Tickets: managed via `db/connectors/ticket` CLI or `/ticket` skill +- Tickets: managed via `"$REPO_ROOT/db/connectors/ticket"` CLI or `/ticket` skill ### Commit conventions Use conventional commits with project-specific scopes: From 5af42708e9a4f0da9ad3a67e8c63839cdc9e2021 Mon Sep 17 00:00:00 2001 From: Jeroen Schweitzer <jpmschweitzer@gmail.com> Date: Thu, 12 Feb 2026 15:37:51 +0100 Subject: [PATCH 2/2] chore(meta): update changelog Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> --- CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 1400aa457..29f0059b7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,6 +10,7 @@ Format based on [Keep a Changelog](https://keepachangelog.com/). - `ticket team` command and `--team` filter — comma-separated team assignment for tickets (server, client, joint, content) ### Changed +- All instruction files (CLAUDE.md, skills, agent files) now use `$REPO_ROOT` env var instead of `git rev-parse --show-toplevel` — pre-set per worktree via `.claude/settings.local.json` - `start-sprint` skill now requires plan mode — agent must create and get approval for a concrete sprint plan before starting implementation ### Fixed