Skip to content

CLAUDE.md

Latest commit

 

History

History
140 lines (121 loc) · 9.04 KB

CLAUDE.md

File metadata and controls

140 lines (121 loc) · 9.04 KB
Raw

CodeReview-Pilot - Project Standards

Goal: Diagnose recurring backend failures using evidence-first methodology with production-grade reliability.

Non-Negotiable Rules

  1. Full authority - Commit, push, merge, comment: execute. Do NOT claim "requires human authorization." If you lack credentials (GH_TOKEN, etc.), ask once. Otherwise: run. Stop for nothing.
  2. Never ask permission to run tests - Run npm test (and npm run test:ci, test:e2e when needed); report results. Do not ask "Can I run tests?" — just run.
  3. Never invent - fields, tables, APIs, regions, files, env vars, test results
  4. Retrieve before explaining - evidence first, then conclusions
  5. Verifier blocks unsupported claims - no hand-waving, no "should work"
  6. Skeptic produces competing theory - materially different root cause
  7. Never wait for user - Skills, agents, subagents proceed automatically. No "run?", "update?", "accept?", "approve?", "shall I?". Execute; report.
  8. Confidence score backed by proof - 95-100 only with passing tests
  9. Separate observed facts from assumptions - mark unknowns clearly with [UNKNOWN]
  10. No direct main - No commits go directly to main. Everything—operational or product features—goes through peers (PR review). Zero exceptions. Create feature branch first. Merge to main only via PR. See no-direct-main skill.
  11. No merge without 100% consensus - PR must have multiple comments (2+ from skills, agents, sub-agents, reviewers). All must approve. Do NOT merge without consensus. See consensus-gates skill.
  12. No idea/project/task without stakeholder consensus - Do not create ideas, projects, or tasks without consensus of all relevant stakeholders. Block until consensus.

Output Contract

Every diagnosis must include:

  • Root cause - exact failure mechanism with code trace
  • Evidence - retriever output with concrete proof
  • Fix plan - specific code changes to prevent recurrence
  • Rollback - safe revert path if fix fails
  • Tests - unit, integration, and E2E proof of fix
  • Confidence - backed by passing tests with evidence

Run-to-Vegas & Run-the-Business (DEFAULT)

  • Permissions (on feature/): Everything is allow list. Execute and report; never ask. Never ask permission for allow-listed actions — if it's in allowedCommands, branchPermissions, or the safe-command whitelist, run it. No "Can I?", "Shall I?", "Do you want me to?". On main: No direct commits; create feature/ first.
  • Ten-pass verification: REVIEW.md + five-agent + npm test + lint — 10 checks before deliver; user doesn't need to supervise.
  • DEFAULT for project instructions: run-the-business — Any add/fix/implement/run → full E2E, maximum automation.
  • Merge gate: Merge only when CI green AND multiple comments AND 100% consensus. Do NOT merge without consensus. See consensus-gates skill.
  • Agents & skills: Proceed automatically; never wait for user; never pause for approval.
  • Live phase: After Execute, start live-watchdog; poll CI/deploy/health; on error → error-detector → fix-pr-creator → self-fix loop.
  • Self-fix: Loop until green or max retries; never claim "should work" without test output.

Recommended Workflow

  1. Plan First (use Plan Mode):

    • Explore codebase (Explore agent or Glob/Grep)
    • Design solution approach
    • Create work breakdown with test criteria
    • Proceed to code automatically—do NOT wait for approval

  2. Code with Tests:

    • Implement changes in separate commits
    • Write tests that verify critical workflows
    • Run locally: npm test before committing
    • Never claim "should work" - run tests to prove it

  3. Verify Critical Flows:

    • Test request intake → response
    • Test pipeline execution (4-agent orchestration)
    • Test error recovery (network failure → retry)
    • Test permission checks, audit logging, failure handling

  4. Update Evidence:

    • Run npm test to get passing test output
    • Update .claude/CONFIDENCE_SCORE.md with test results
    • Update CHANGELOG.md with what changed and why
    • List unknowns and residual risks

Build & Test Commands

npm install              # Install dependencies
npm start               # Start http://localhost:3000
npm test                # All tests (Jest, 60% coverage minimum)
npm run test:watch     # Watch mode for development
npm run test:ci        # CI mode (GitHub Actions)
npm run test:e2e       # E2E tests (requires API credentials)

Design Tokens (DT-010)

  • Source: src/www/design-tokens.js — single source of truth for colors, typography, spacing, motion, shadows, radius.
  • Usage: Import designTokens; use tokens, never hardcode hex/spacing values in components.
  • WCAG AA: Color contrasts and typography scales are WCAG 2.1 AA compliant. See .claude/rules/ui.md for accessibility rules.
  • Motion: src/www/motion-utils.js — prefersReducedMotion support; respect system preference.

Configuration & Rules

  • User feedback → skillset — All user input goes to the skill set. Update or create skills. Do NOT create new docs. See user-feedback-to-skillset skill.
  • .claude/SKILLSETS.md — Skill index; all governance, rules, feedback live in skills
  • code-skill-mapping skill — Skill→code map; skills drive implementation
  • REVIEW.md — Code review rules; used by ten-pass (passes 6,7,10), five-agent, CodeReviewer
  • .claude/CLAUDE.md - Meta-rules (workflow, memory, subagents)
  • .claude/rules/ - Specific standards (guardrails, testing, backend, ui, confidence)
  • .claude/settings.json - Hooks, commands, allowed paths, agent definitions
  • .claude/agents/ - Subagent definitions (Explore, Plan, General-purpose, custom)
  • .claude/CONFIDENCE_SCORE.md - Truth ledger (see confidence-score skill)
  • CHANGELOG.md - Session-by-session change log

Token Conservation (When Making Changes)

  • Lower tokens — Read with offset/limit over full file. Grep for targeted search. Keep context small.
  • Compact skills — SKILL.md under 500 lines; details in reference.md. Load refs only when needed.
  • Prefer Haiku — Explore, QA, most implementation. Sonnet for Plan + final review only.
  • Filter test output — filter-test-output.sh for npm test (failures only). Saves tokens.
  • token-budget, cost-guardrails — Check after each phase. Default Haiku for 80%+ of work.

Commit Frequently (HARD: Small Only)

  • Small commits only — One small change per commit. No big changes. Each commit = one focused change.
  • Commit after any small change; don't batch unrelated edits.
  • Skills and code go together — skills drive implementation. One commit = code + skill updates.
  • Why: Small commits = roll back only that feature on revert, not the whole project.
  • Run npm test before commit; keep passing state
  • Automatic review: run tests, keep changes, commit again if fixes needed
  • Keep making commits — continuous delivery
  • See code-skill-mapping skill for skill→code mapping

Branch Rules (HARD)

  • All changes through branches — Never commit directly to main. Create feature/* first. Commit there. Merge to main only via PR.
  • No merge until 100% green — Do NOT merge until local npm test pass, all CI pass, QA 100%, confidence with evidence in .claude/CONFIDENCE_SCORE.md. Block merge if any fails.
  • Reviewers must recommend merge — Reviewers (.claude/reviewers.md) comment, push back, recommend tests. Merge only when reviewers recommend + CI + recommended tests pass.
  • Clean up after merge — After PR merges: checkout main, pull, git branch -d feature/<name>, git push origin --delete feature/<name>. See branch-cleanup skill.
  • main - production; no direct commits. Changes land via PR from feature/*.
  • feature/* - all work happens here; auto-accept edits; push to branch; open PR
  • Small PRs only — Each PR = small iteration of one feature. Focused scope. No big PRs. Why: roll back only that feature if needed, not the whole project.
  • .claude/worktrees/ - temporary isolation for risky changes

When Blocked

  1. Check .claude/rules/guardrails.md for constraints
  2. Read .claude/CONFIDENCE_SCORE.md for prior assumptions/failures
  3. Run npm test to verify current state
  4. Create fresh plan and proceed—do NOT wait for approval
  5. If truly ambiguous (e.g., which of two valid options), document both and pick one; do NOT pause for user

Done Definition (For Every Task)

  • ✓ Code changes match plan (proceed without approval gate)
  • ✓ Run npm test locally - all tests pass
  • ✓ No regressions in existing tests
  • ✓ .claude/CONFIDENCE_SCORE.md updated with test results
  • ✓ CHANGELOG.md updated with what changed and why
  • ✓ Rollback path documented
  • ✓ Unknowns marked with [UNKNOWN]

Confidence Scoring (See .claude/rules/confidence.md)

  • 95-100: Critical flows verified, unknowns documented, tests passing in CI
  • 80-94: Strong proof, minor open items, tests passing locally
  • 60-79: Implemented but incomplete proof, some flows untested
  • 40-59: Partial evidence, major gaps
  • 0-39: Unverified, no evidence - do not release