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
  connectors/         # 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

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

db/connectors/ticket list --sprint N --team {team}
db/connectors/ticket show N
db/connectors/sprint status

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/

Ticket and database access

Prefer the ticket CLI over raw SQL. The CLI handles column names, joins, and output formatting correctly:

db/connectors/ticket list [--status S] [--sprint N] [--team T]
db/connectors/ticket show <id>
db/connectors/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:

db/connectors/sqlite-query "SELECT * FROM tickets WHERE status='in_progress'"
db/connectors/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:

db/connectors/sprint status                    # Current sprint progress
db/connectors/sprint status --team {team}      # Team-scoped view
db/connectors/sprint start-work [--team T]     # Full context dump for starting work
db/connectors/sprint prepare                   # Prepare next sprint (candidates + gaps)
db/connectors/sprint start                     # Activate a planned sprint
db/connectors/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:

db/connectors/qdrant-search "query text"
db/connectors/qdrant-index docs/briefings/agent.md
db/connectors/qdrant-health
db/connectors/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 db/connectors/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})