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

### Team boundaries

{If using sprint branches with ephemeral worktrees:}

Teams work on sprint branches (`sprint-{N}/{team}`). Ephemeral worktrees may be created per sprint via `start-sprint`. All file paths are relative to the repo root.

Each team has a scope — directories they may modify. Shared directories (`docs/`, `decisions/`) are readable by all teams.

{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}`) is accessed via `SR_DB_PATH` env var or parent directory fallback. 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})