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 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):

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:

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:

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:

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:

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:}

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:}

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:}

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})