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

chore(config): use $REPO_ROOT env var in all instruction files

Browse Source 
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 <noreply@anthropic.com>
This commit is contained in:
jpmschweitzer
2026-02-12 15:37:38 +01:00
co-authored by Claude Opus 4.6
parent 2da6923189
commit c20c1810b1
7 changed files with 72 additions and 68 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.claude/agents/qatux.md
+1 -1
View File
@@ -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 <path>`.
- **Re-index documents:** After archiving or updating documents, re-index them in Qdrant via `python3 "$REPO_ROOT/db/connectors/qdrant_connector.py" index-file <path>`.
## Team workflow (mandatory)
.claude/skills/plan-sprint/SKILL.md
+8 -8
View File
@@ -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 <current_id> --status in_progress
db/connectors/ticket list --sprint <current_id> --status ready
"$REPO_ROOT/db/connectors/ticket" list --sprint <current_id> --status in_progress
"$REPO_ROOT/db/connectors/ticket" list --sprint <current_id> --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 <epic_id>
"$REPO_ROOT/db/connectors/ticket" children <epic_id>
```
Use `ticket show --brief <id> [<id>...]` to quickly scan multiple tickets.
Use `"$REPO_ROOT/db/connectors/ticket" show --brief <id> [<id>...]` 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 <ticket_id> <sprint_id>
"$REPO_ROOT/db/connectors/ticket" sprint assign <ticket_id> <sprint_id>
```
### 9. Present summary
.claude/skills/plan-sprint/references/briefing-template.md
+1 -1
View File
@@ -26,7 +26,7 @@ Each team gets one briefing file at `docs/sprints/sprint-N/<team>.md`.
|---|-------|------------|
| #ID | Title | #dependency or — |
Use `db/connectors/ticket show <id>` for full details.
Use `"$REPO_ROOT/db/connectors/ticket" show <id>` for full details.
## Key Decisions
.claude/skills/search-docs/SKILL.md
+16 -15
View File
@@ -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 <command> [args]
python3 "$REPO_ROOT/db/connectors/qdrant_connector.py" <command> [args]
```
## Commands
@@ -24,9 +25,9 @@ python3 db/connectors/qdrant_connector.py <command> [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
```
.claude/skills/start-sprint/SKILL.md
+2 -7
View File
@@ -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/<team>.md"`
- Decision files: `"$REPO_ROOT/decisions/*.md"`
.claude/skills/ticket/SKILL.md
+23 -22
View File
@@ -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 <command> [args...]
db/connectors/ticket --help
"$REPO_ROOT/db/connectors/ticket" <command> [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 "<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 |
| `"$REPO_ROOT/db/connectors/sqlite-query" "<SQL>"` | Run SELECT queries |
| `"$REPO_ROOT/db/connectors/sqlite-exec" "<SQL>"` | 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 <id>
"$REPO_ROOT/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]
"$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
CLAUDE.md
+21 -14
View File
@@ -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: