diff --git a/.claude/agents/qatux.md b/.claude/agents/qatux.md index abc3adf15..fcf268ed2 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 "$REPO_ROOT/db/connectors/qdrant_connector.py" index-file `. +- **Re-index documents:** After archiving or updating documents, re-index them in Qdrant via `db/connectors/qdrant-index `. ## Team workflow (mandatory) diff --git a/.claude/skills/plan-sprint/SKILL.md b/.claude/skills/plan-sprint/SKILL.md index 58a80cc93..7d9cbe43e 100644 --- a/.claude/skills/plan-sprint/SKILL.md +++ b/.claude/skills/plan-sprint/SKILL.md @@ -56,7 +56,7 @@ file so the team knows who to spawn. ### 1. Determine sprint number ```bash -"$REPO_ROOT/db/connectors/ticket" sprint --active +db/connectors/ticket sprint --active ``` Next sprint = active sprint ID + 1. If no active sprint, ask the user. @@ -66,8 +66,8 @@ Next sprint = active sprint ID + 1. If no active sprint, ask the user. Review the active sprint for carry-overs: ```bash -"$REPO_ROOT/db/connectors/ticket" list --sprint --status in_progress -"$REPO_ROOT/db/connectors/ticket" list --sprint --status ready +db/connectors/ticket list --sprint --status in_progress +db/connectors/ticket list --sprint --status ready ``` Any ticket not `done` is a potential carry-over. Note these for the briefing. @@ -77,16 +77,16 @@ Any ticket not `done` is a potential carry-over. Note these for the briefing. Pull candidate tickets by priority: ```bash -"$REPO_ROOT/db/connectors/ticket" epics --status backlog +db/connectors/ticket epics --status backlog ``` For critical epics, check their children: ```bash -"$REPO_ROOT/db/connectors/ticket" children +db/connectors/ticket children ``` -Use `"$REPO_ROOT/db/connectors/ticket" show --brief [...]` to quickly scan multiple tickets. +Use `db/connectors/ticket show --brief [...]` to quickly scan multiple tickets. ### 4. Read existing code state @@ -154,10 +154,10 @@ After the user approves, assign all selected tickets to the new sprint: ```bash # Create the sprint -"$REPO_ROOT/db/connectors/sqlite-exec" "INSERT INTO sprints (name, goal, status) VALUES ('Sprint N: Theme', 'goal', 'planned')" +db/connectors/sqlite-exec "INSERT INTO sprints (name, goal, status) VALUES ('Sprint N: Theme', 'goal', 'planned')" # Assign tickets -"$REPO_ROOT/db/connectors/ticket" sprint assign +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 216a39cd6..5a81729cf 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 `"$REPO_ROOT/db/connectors/ticket" show ` for full details. +Use `db/connectors/ticket show ` for full details. ## Key Decisions diff --git a/.claude/skills/review-pr/SKILL.md b/.claude/skills/review-pr/SKILL.md index 51c92ed2e..40d58ebbc 100644 --- a/.claude/skills/review-pr/SKILL.md +++ b/.claude/skills/review-pr/SKILL.md @@ -45,7 +45,7 @@ If the diff is empty, report "No changes to review" and stop. - `Cargo.lock` (auto-generated) - `client/addons/gdUnit4/` (vendor test framework) - `*.uid` (Godot-generated) -- `db/commonwealth.db` (binary) +- `docs/backups/settledreach.db.backup` (binary) Three-dot diff with pathspec exclusions is unreliable. Instead, either: 1. Use `git diff main...` (full diff) and filter in the prompt, or diff --git a/.claude/skills/search-docs/SKILL.md b/.claude/skills/search-docs/SKILL.md index b41b4e9d0..4da561f5e 100644 --- a/.claude/skills/search-docs/SKILL.md +++ b/.claude/skills/search-docs/SKILL.md @@ -14,10 +14,17 @@ Semantic search across Commonwealth project documents using Qdrant vector databa ## Access Method -**Use the connector script.** The `$REPO_ROOT` environment variable is pre-set -per worktree — always use it as a prefix: +**Use the connector wrapper scripts:** ```bash -python3 "$REPO_ROOT/db/connectors/qdrant_connector.py" [args] +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 @@ -25,9 +32,9 @@ python3 "$REPO_ROOT/db/connectors/qdrant_connector.py" [args] ### Search Find documents semantically related to a query: ```bash -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" +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. @@ -35,10 +42,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 "$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 +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). @@ -46,25 +53,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 "$REPO_ROOT/db/connectors/qdrant_connector.py" index "unique-id" "Text content to index" --metadata source=manual heading="Custom heading" +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 -python3 "$REPO_ROOT/db/connectors/qdrant_connector.py" health +db/connectors/qdrant-health ``` ### Collection info Check how many documents are indexed: ```bash -python3 "$REPO_ROOT/db/connectors/qdrant_connector.py" count +db/connectors/qdrant-count ``` ### Create collection Initialize the Qdrant collection (run once during setup): ```bash -python3 "$REPO_ROOT/db/connectors/qdrant_connector.py" create-collection +python3 db/connectors/qdrant_connector.py create-collection ``` ## Endpoints @@ -93,7 +100,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 "$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" +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/start-sprint/SKILL.md b/.claude/skills/start-sprint/SKILL.md index 196410995..812b6785b 100644 --- a/.claude/skills/start-sprint/SKILL.md +++ b/.claude/skills/start-sprint/SKILL.md @@ -14,19 +14,6 @@ allowed-tools: Bash, Read, Grep, Glob Prepare a team branch for sprint work: sync with main, load the sprint 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 use `$REPO_ROOT` as a prefix — this environment variable -is pre-set in each worktree's `.claude/settings.local.json`. - -- Ticket CLI: `"$REPO_ROOT/db/connectors/ticket"` -- Sprint briefings: `"$REPO_ROOT/docs/sprints/sprint-N/.md"` -- Decision files: `"$REPO_ROOT/decisions/*.md"` - -**Never use bare relative paths** like `db/connectors/ticket` — they break -when the shell's CWD doesn't match the worktree root. - ## Workflow ### 1. Determine the team @@ -51,7 +38,7 @@ If the merge has conflicts, report them and stop — do not force-resolve. ### 3. Find the active sprint ```bash -"$REPO_ROOT/db/connectors/ticket" sprint --active +db/connectors/ticket sprint --active ``` Extract the sprint ID and name from the JSON output. If no active sprint, @@ -59,7 +46,7 @@ report that and stop. ### 4. Read the sprint briefing -Read `$REPO_ROOT/docs/sprints/sprint-N/.md` where N is the sprint ID +Read `docs/sprints/sprint-N/.md` where N is the sprint ID and team matches the branch name (e.g. `server.md`, `client.md`, `copy.md`). If no matching briefing exists for the team, report that and suggest running `/plan-sprint` to generate one. @@ -71,7 +58,7 @@ should be mentioned. For each ticket listed in the briefing, run: ```bash -"$REPO_ROOT/db/connectors/ticket" show +db/connectors/ticket show ``` Identify which tickets are actionable now (no open blockers) vs blocked. diff --git a/.claude/skills/ticket/SKILL.md b/.claude/skills/ticket/SKILL.md index c3998c808..a5df765cb 100644 --- a/.claude/skills/ticket/SKILL.md +++ b/.claude/skills/ticket/SKILL.md @@ -10,15 +10,14 @@ allowed-tools: Bash, Read, Grep, Glob # Ticket Skill -Manage the Commonwealth project ticketing database at `db/commonwealth.db`. +Manage the project ticketing database (shared `settledreach.db` in the worktree parent directory). ## Access Method -**Use the `ticket` CLI for all ticket operations.** The `$REPO_ROOT` environment -variable is pre-set per worktree — always use it as a prefix: +**Use the `ticket` CLI for all ticket operations:** ```bash -"$REPO_ROOT/db/connectors/ticket" [args...] -"$REPO_ROOT/db/connectors/ticket" --help +db/connectors/ticket [args...] +db/connectors/ticket --help ``` All output is JSON on stdout. @@ -26,67 +25,67 @@ All output is JSON on stdout. For raw SQL access (rare), use the wrapper scripts: | Script | Purpose | |--------|---------| -| `"$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 | +| `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 | ## Commands ### List tickets ```bash -"$REPO_ROOT/db/connectors/ticket" list [--status S] [--priority P] [--epic N] [--sprint N] [--assigned A] [--team T] +db/connectors/ticket list [--status S] [--priority P] [--epic N] [--sprint N] [--assigned A] [--team T] ``` ### Show ticket detail ```bash -"$REPO_ROOT/db/connectors/ticket" show +db/connectors/ticket show ``` Returns full ticket with children, blockers, and dependents. ### Create ticket ```bash -"$REPO_ROOT/db/connectors/ticket" create [--parent N] [--priority P] [--decision D] [--team T] +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 -"$REPO_ROOT/db/connectors/ticket" status <id> <new_status> -"$REPO_ROOT/db/connectors/ticket" done <id> [<id> ...] +db/connectors/ticket status <id> <new_status> +db/connectors/ticket done <id> [<id> ...] ``` Statuses: `backlog`, `ready`, `in_progress`, `review`, `done`, `cancelled` ### Assignment ```bash -"$REPO_ROOT/db/connectors/ticket" assign <id> <agent> -"$REPO_ROOT/db/connectors/ticket" unassign <id> +db/connectors/ticket assign <id> <agent> +db/connectors/ticket unassign <id> ``` ### Team assignment ```bash -"$REPO_ROOT/db/connectors/ticket" team <id> <teams> +db/connectors/ticket team <id> <teams> ``` Teams are comma-separated, e.g. `server`, `client`, `server,client`. ### Sprint management ```bash -"$REPO_ROOT/db/connectors/ticket" sprint [--active] -"$REPO_ROOT/db/connectors/ticket" sprint assign <id> <sprint_id> +db/connectors/ticket sprint [--active] +db/connectors/ticket sprint assign <id> <sprint_id> ``` ### Dependencies ```bash -"$REPO_ROOT/db/connectors/ticket" deps <id> +db/connectors/ticket deps <id> ``` ### Search and browse ```bash -"$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] +db/connectors/ticket search <keyword> +db/connectors/ticket epics [--status S] +db/connectors/ticket children <id> +db/connectors/ticket count [--status S] ``` ## Workflow diff --git a/CLAUDE.md b/CLAUDE.md index fa5396163..a8ee610a2 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -22,7 +22,6 @@ docs/ sprints/ # Sprint briefings per team (server.md, client.md, copy.md, joint.md, etc.) workshops/ # Workshop briefs and outputs (per-workshop subdirectories) db/ - commonwealth.db # SQLite ticketing database schema.sql # Database schema connectors/ # Connector scripts for SQLite and Qdrant config.json # Endpoint configuration @@ -51,39 +50,36 @@ See [docs/DEVOPS.md](docs/DEVOPS.md) for build, test, lint, and CI procedures. A ## Agent Instructions -### Path resolution +### Database -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). +The ticketing database (`settledreach.db`) lives in the **parent directory** shared across all worktrees — it is not tracked in git. A backup is committed to `docs/backups/settledreach.db.backup` via main only. ### Before starting work -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/` +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/` ### Ticket and database access **Prefer the ticket CLI over raw SQL.** The CLI handles column names, joins, and output formatting correctly: ```bash -"$REPO_ROOT/db/connectors/ticket" list --sprint 2 --team server -"$REPO_ROOT/db/connectors/ticket" show 78 -"$REPO_ROOT/db/connectors/ticket" sprint --active +db/connectors/ticket list --sprint 2 --team server +db/connectors/ticket show 78 +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 -"$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" +db/connectors/sqlite-query "SELECT * FROM tickets WHERE status='in_progress'" +db/connectors/sqlite-exec "UPDATE tickets SET status='done' WHERE id=1" ``` ### Qdrant / document search ```bash -"$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" +db/connectors/qdrant-search "asymmetric information design" +db/connectors/qdrant-index docs/briefings/tyre.md +db/connectors/qdrant-health +db/connectors/qdrant-count ``` ### Gitea access (tea CLI) @@ -119,7 +115,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 `"$REPO_ROOT/db/connectors/ticket"` CLI or `/ticket` skill +- Tickets: managed via `db/connectors/ticket` CLI or `/ticket` skill ### Commit conventions Use conventional commits with project-specific scopes: