CLAUDE.md — {{PROJECT_NAME}}

Project Identity

{{PROJECT_DESCRIPTION}}

Conventions & Rules

Rules are split into files for sync between template and global config:

• Global rules (~/.claude/rules/): roles, quality, workflow, git, security, conventions, python-uv
• Project rules (.claude/rules/): stack-specific (python, node, nextjs, go, rust)
• Precedence: .claude/rules/ (project) > CLAUDE.md > ~/.claude/rules/ (global)

Run /sync-global to synchronize rules between this template and global config.

Structure

{{PROJECT_NAME}}/
├── {{SRC_DIR}}        → source code
├── {{TEST_DIR}}       → test files (mirror of src/)
├── docs/              → documentation
│   └── specs/         → functional specifications per domain (auto-generated by /spec-update)
├── .claude/           → Claude Code config (hooks, skills, commands)
│   ├── hooks/         → automatic hooks (security, TDD, memory, skill eval)
│   ├── commands/      → slash commands (/commit, /tdd, /review, /test-runner)
│   ├── agents/        → custom agent definitions (test-runner, security-auditor, tech-debt-auditor)
│   ├── rules/         → project + generic rules (synced with ~/.claude/rules/)
│   ├── stacks/        → language-specific guides (read on demand)
│   └── audit-config.json → audit skip decisions & last results (created by /audit-conformity)
└── memory/            → persistent cross-session memory
    ├── MEMORY.md          → project identity, session notes (auto-injected)
    ├── polaris.md         → north star: top of mind, goals, values (auto-injected)
    ├── patterns.md        → technical patterns, debugging lessons (on-demand)
    ├── decisions.md       → architectural decision records (on-demand)
    ├── active-context.md  → current work context (focus + next steps auto-injected)
    ├── scratchpad.md      → running work log (last 30 lines auto-injected)
    └── session-cache.json → session handoff (auto-generated)

Skills Conventions

Taxonomy (3 tiers)

Frontmatter (required)

Every .claude/skills/<name>/SKILL.md must start with:

---
name: kebab-case-name        # must match folder name, max 64 chars
description: >               # max 200 chars, include trigger phrases
  What this skill does and when to invoke it.
  Triggers: "keyword1", "keyword2".
type: component|interactive|workflow
---

Anatomy (6 sections, in order)

1. Purpose — What this skill does and when to use it
2. Key Concepts — Frameworks, definitions, anti-patterns
3. Application — Step-by-step instructions (templates for component, question flows for interactive)
4. Examples — Concrete cases showing good and bad usage
5. Common Pitfalls — Named failure modes with Symptom/Consequence/Fix format
6. References — Related skills, external sources, credit

Interactive Skills Protocol

All interactive skills delegate facilitation behavior to workshop-facilitation skill:

• 3 entry modes: Guided (question by question) / Context dump (paste everything) / Best guess (infer + label assumptions)
• Progress labels: Show Context Qx/N during collection, Scoring Qx/N during assessment
• One question per turn: Wait for answer before continuing
• Decision points only: Offer numbered recommendations only when a choice is needed

Available PM Skills

• /user-story — Write user stories with Cohn format + Gherkin acceptance criteria
• /prd-development — Structured PRD in 8 phases (2-4 days)
• /prioritization-advisor — Choose the right prioritization framework (RICE, ICE, Kano...)
• /discovery-interview-prep — Prepare customer interviews (Mom Test style)
• /opportunity-solution-tree — OST: outcomes → opportunities → solutions → POC

Task Coordination

• TodoWrite: track progress on single-thread tasks (subtask decomposition, status updates)
• Task tool: coordinate multi-agent workflows (spawn subagents, parallel execution, cross-agent context)
• Both tools are valid — use Task tool when delegating to agents (test-runner, security-auditor, etc.)

Workflow

1. Edit code in this repo
2. Run tests: {{TEST_COMMAND}}
3. /commit → conventional commit with quality gate
4. Push: git push origin {{DEFAULT_BRANCH}}

Project-Specific Config

• TDD: use /tdd skill — hook tdd-guard.js reminds automatically
• Quality gate: /commit runs secret scan, slop scan, format ({{FORMAT_COMMAND}}), tests ({{TEST_COMMAND}}), coverage report ({{TEST_COMMAND_COVERAGE}}), doc completeness check
• Commit rhythm: commit-reminder.js (auto-detect), post-commit-lessons.js (post-commit eval)
• Environment awareness: session-context.js injects cwd, branch, git status, stack at session start

Scratchpad Protocol (compact-resilient)

Maintain memory/scratchpad.md as a running work log during active sessions:

• When to write: After completing each subtask, before switching context

• Format: Append-only, latest entry at the bottom, structured entries:

  ### HH:MM — Task title
  - Done: what was completed
  - Next: immediate next step
  - Decision: key decision made (if any)
  ---

• Content: Current task, what was done, what's next, key decisions
• Why: Survives /compact — last 30 lines re-injected by session-context.js
• Cleanup: Clear at the start of each new feature/story

Polaris Protocol (north star)

memory/polaris.md contains the user's strategic context: top of mind, goals, and values.

• Auto-injected at session start (~100 tokens) by session-context.js
• Setup: run /polaris to fill or update interactively with guided questions
• Auto-proposed when polaris.md is empty at session start
• Update frequency: every 1-2 weeks, or when priorities shift
• Modification: Level 3 (propose & wait for PO approval)
• Usage: reference Polaris when evaluating alignment of decisions, priorities, or new opportunities

Project Tracking

• Source of truth: GitHub Projects V2 — view project
• Project number: {{PROJECT_NUMBER}} (set per repo after template copy)
• Read backlog: gh project item-list {{PROJECT_NUMBER}} --owner wilsto --format json
• Read issues: gh issue list --repo wilsto/{{REPO_NAME}} --state open
• Create issue: 3-step process (see workflow.md → Issue Creation Procedure):
  1. gh issue create --repo wilsto/{{REPO_NAME}} — creates the issue
  2. gh project item-add {{PROJECT_NUMBER}} --owner wilsto --url <URL> — adds to project board
  3. Set all fields via GraphQL (Status, Phase, Priority, Size, Type, Start date)
• Sub-issues: mcp__github__sub_issue_write for epic decomposition
• Phase transitions: Level 3 (propose & wait for PO approval)
• At session start: Claude reads the project backlog to understand current context
• Discuss/migrate: use /roadmap skill
• Field IDs: cached in CLAUDE.local.md → "GitHub Project Field IDs" section

Compact Instructions

When /compact is triggered, always preserve in the summary:

• Full list of modified files and their purpose
• Current task status (what's done, what's in progress)
• Key decisions made and their rationale
• Active test commands and environment-specific details
• Any blocking issues or open questions for PO

Model Selection