settled-reach/whatsinagame/templates/CLAUDE.md

# {Project Name}

{Project description — one paragraph summarizing what the project is, its core mechanics or purpose, and the technology stack.}

## Project Structure

```
{tech-stack-specific directories — e.g.:}
{  src/                # Application source}
{  lib/                # Shared libraries}
{  assets/             # Static assets}
docs/
  discussions/        # Discussion rounds (archived per round)
  briefings/          # Per-agent context briefings
  architecture/       # Technical architecture documents
  design/             # Design documents
  sprints/            # Sprint briefings per team
  workshops/          # Workshop briefs and outputs
db/
  schema.sql          # Database schema
tooling/
  db/                 # Connector scripts for SQLite and Qdrant
    config.json       # Endpoint configuration
    ticket            # Ticket CLI (list, show, create, assign, sprint, etc.)
    sqlite_connector.py   # SQLite mini MCP
    qdrant_connector.py   # Qdrant + ollama mini MCP
.claude/
  agents/             # Agent personality files
  skills/             # Skill definitions
decisions/            # Decision domain files (source of truth)
  README.md           # Domain index and query examples
  architecture.md     # Architecture decisions
  scope.md            # Scope decisions
  process.md          # Process decisions
  questions.md        # Open questions
  rejected.md         # Rejected alternatives
```

## DevOps

See [docs/DEVOPS.md](docs/DEVOPS.md) for build, test, lint, and CI procedures. All development operations go through the top-level `Makefile` — run `make` for a summary of targets.

## Agent Instructions

### Worktree boundaries

{If using git worktrees:}

This project uses **git worktrees** in a shared parent directory. Each team branch is checked out in its own worktree under that parent. The parent directory also contains shared resources like the ticketing database.

Each worktree contains the full repository. The worktree root IS the git root — use `git rev-parse --show-toplevel` if in doubt.

Unless there is a direct instruction or a functional need (e.g. accessing the shared database in the parent directory), **all work must remain within the scope of the git root Claude is running in.**

- All file paths are relative to the worktree/git root.
- Do not navigate to or access sibling worktrees unless explicitly instructed.
- Do not navigate above the git root unless explicitly instructed.

{If single-branch workflow:}

All work happens on feature branches from `main`. All file paths are relative to the repository root.

### Database

The ticketing database (`{db_name}`) lives {in the parent directory shared across worktrees | in the repository root}. Access via CLI wrappers — never use the `sqlite3` CLI directly (it crashes in Claude Code due to std::bad_alloc):

```bash
tooling/db/ticket list --sprint N --team {team}
tooling/db/ticket show N
tooling/db/sprint status
```

### Before starting work

1. Read your sprint briefing at `docs/sprints/sprint-N/{team}.md` for current tasks
2. Use `tooling/db/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
tooling/db/ticket list [--status S] [--sprint N] [--team T]
tooling/db/ticket show <id>
tooling/db/ticket sprint --active
```

Only fall back to raw SQL for queries the CLI doesn't support. **Never use the `sqlite3` CLI** — use the wrapper scripts instead:

```bash
tooling/db/sqlite-query "SELECT * FROM tickets WHERE status='in_progress'"
tooling/db/sqlite-exec "UPDATE tickets SET status='done' WHERE id=1"
```

### Sprint CLI

**Use the sprint CLI for sprint-scoped operations.** It batches ticket queries and formats output for agent consumption:

```bash
tooling/db/sprint status                    # Current sprint progress
tooling/db/sprint status --team {team}      # Team-scoped view
tooling/db/sprint start-work [--team T]     # Full context dump for starting work
tooling/db/sprint prepare                   # Prepare next sprint (candidates + gaps)
tooling/db/sprint start                     # Activate a planned sprint
tooling/db/sprint stop                      # Complete an active sprint
```

Team is auto-detected from the current git branch (if not `main`). Sprint is auto-detected from DB state.

### Document search

If Qdrant + Ollama are configured for semantic search:

```bash
tooling/db/qdrant-search "query text"
tooling/db/qdrant-index docs/briefings/agent.md
tooling/db/qdrant-health
tooling/db/qdrant-count
```

### Git host access

{For GitHub — use `gh` CLI:}

```bash
gh pr list --state open
gh pr view <number>
gh pr create --title "feat(scope): description" --body "PR body"
gh pr comment <number> --body "comment"
```

{For Gitea — use `tea` CLI with all required flags to avoid interactive prompts:}

```bash
tea pr list --login {login} --repo {owner/repo} --state open --output simple
tea pr create --login {login} --repo {owner/repo} --title "title" --description "body" --base main --head branch
tea comment --login {login} --repo {owner/repo} <number> "comment body"
```

{For GitLab — use `glab` CLI:}

```bash
glab mr list --state opened
glab mr create --title "title" --description "body"
glab mr comment <number> --message "comment"
```

Key rules:
- **All flags must be explicit** — omitting required flags triggers interactive prompts that crash in Claude Code (no TTY)
- **Use machine-readable output** where available
- **Never delete protected branches** — `main` and team branches are protected

### File conventions

- Decisions: domain files in `decisions/` (see `decisions/README.md` for index)
- 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 `tooling/db/ticket` CLI

### Commit conventions

Use conventional commits with project-specific scopes:

```
<type>(<scope>): <description>
```

Types: `feat`, `fix`, `chore`, `docs`, `refactor`, `test`, `ci`, `style`
Scopes: {project-specific scopes — e.g. `agents`, `skills`, `docs`, `briefings`, `discussions`, `schema`, `db`, `config`, `meta`}

### Pull requests

{Git host CLI commands — see "Git host access" above for the appropriate CLI.}

Always provide all required flags to ensure non-interactive execution. Include a clear title following commit conventions and a description body.

### Large content pushes (team pattern)

When producing many files (wiki pages, content batches, bulk docs):

1. **Librarian agent** (read-only): ingests all source material, answers focused context queries from writers, tracks cross-file consistency
2. **Multiple writer agents** (parallel, by domain): each gets a task slice, writes directly to disk using the Write tool — one file at a time, write often, no text accumulation
3. **Reviewer agents** (blocked until writing done): check voice consistency, attribute uniformity, style

Key: writers use Write tool directly (no transcription bottleneck), librarian catches contradictions early, split work by domain not volume.

### Local services

{Configure as needed:}

- Git host: `{url}` (login: `{user}`)
- Qdrant: `{url}`
- Ollama: `{url}` ({embedding model})
- Collection: `{name}` ({dimensions}, {distance metric})