From 903d0fb1201adec8f8eaf10a5b78212bdb65c99d Mon Sep 17 00:00:00 2001 From: slaguru666 <111923774+slaguru666@users.noreply.github.com> Date: Sat, 11 Apr 2026 14:50:25 +0100 Subject: [PATCH] Initial Claude config sync CLAUDE.md, settings.json, memory files (GSD + Superpowers patterns). install.sh resolves memory path automatically from whoami. Co-Authored-By: Claude Sonnet 4.6 --- CLAUDE.md | 25 +++++++ README.md | 46 +++++++++++++ install.sh | 35 ++++++++++ memory/MEMORY.md | 36 ++++++++++ memory/gsd-patterns.md | 90 +++++++++++++++++++++++++ memory/superpowers-patterns.md | 116 +++++++++++++++++++++++++++++++++ settings.json | 10 +++ 7 files changed, 358 insertions(+) create mode 100644 CLAUDE.md create mode 100644 README.md create mode 100755 install.sh create mode 100644 memory/MEMORY.md create mode 100644 memory/gsd-patterns.md create mode 100644 memory/superpowers-patterns.md create mode 100644 settings.json diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..8788256 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,25 @@ +# Global Claude Instructions + +## Communication +- Concise, direct — lead with answer, not reasoning +- No emojis unless explicitly asked +- Reference file:line when pointing to code + +## Context Compaction +When compacting, preserve: +- Current task and immediate next steps +- File paths and function names modified +- Test results (failures only) +- Decisions made and their rationale +- Any blockers or open questions + +Discard: +- Exploratory file reads that led nowhere +- Intermediate reasoning that reached a conclusion +- Full file contents already committed to code +- Verbose command output with no failures + +## Working Style +- Verify before asserting — run the command, read the file +- Atomic changes — one thing at a time, confirm it works +- No speculative features beyond what was asked diff --git a/README.md b/README.md new file mode 100644 index 0000000..48cadab --- /dev/null +++ b/README.md @@ -0,0 +1,46 @@ +# claude-config + +Private repo syncing Claude Code config across machines. + +## Files + +| File | Destination | +|------|------------| +| `CLAUDE.md` | `~/.claude/CLAUDE.md` | +| `settings.json` | `~/.claude/settings.json` | +| `memory/MEMORY.md` | `~/.claude/projects/-Users--Git/memory/MEMORY.md` | +| `memory/gsd-patterns.md` | `~/.claude/projects/-Users--Git/memory/gsd-patterns.md` | +| `memory/superpowers-patterns.md` | `~/.claude/projects/-Users--Git/memory/superpowers-patterns.md` | + +## Install on a new machine + +```bash +git clone https://github.com/slaguru666/claude-config.git +cd claude-config +chmod +x install.sh +./install.sh +``` + +The install script uses `whoami` to resolve the correct memory path automatically — no manual path editing needed. + +## Keeping in sync + +After editing any config file on one machine: + +```bash +cd ~/Git/claude-config +cp ~/.claude/CLAUDE.md . +cp ~/.claude/settings.json . +cp ~/.claude/projects/-Users-$(whoami)-Git/memory/*.md memory/ +git add -A +git commit -m "sync config" +git push +``` + +On the other machine: + +```bash +cd ~/Git/claude-config +git pull +./install.sh +``` diff --git a/install.sh b/install.sh new file mode 100755 index 0000000..8243a1b --- /dev/null +++ b/install.sh @@ -0,0 +1,35 @@ +#!/usr/bin/env bash +# Installs Claude config files to ~/.claude/ +# Usage: ./install.sh +# Run this on any machine after cloning the repo. + +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +CLAUDE_DIR="$HOME/.claude" +USERNAME=$(whoami) +MEMORY_DIR="$CLAUDE_DIR/projects/-Users-${USERNAME}-Git/memory" + +echo "Installing Claude config for user: $USERNAME" + +# CLAUDE.md +cp "$SCRIPT_DIR/CLAUDE.md" "$CLAUDE_DIR/CLAUDE.md" +echo " Installed: ~/.claude/CLAUDE.md" + +# settings.json — merge if file already exists, otherwise copy +if [ -f "$CLAUDE_DIR/settings.json" ]; then + echo " ~/.claude/settings.json already exists — backing up to settings.json.bak" + cp "$CLAUDE_DIR/settings.json" "$CLAUDE_DIR/settings.json.bak" +fi +cp "$SCRIPT_DIR/settings.json" "$CLAUDE_DIR/settings.json" +echo " Installed: ~/.claude/settings.json" + +# Memory files +mkdir -p "$MEMORY_DIR" +cp "$SCRIPT_DIR/memory/MEMORY.md" "$MEMORY_DIR/MEMORY.md" +cp "$SCRIPT_DIR/memory/gsd-patterns.md" "$MEMORY_DIR/gsd-patterns.md" +cp "$SCRIPT_DIR/memory/superpowers-patterns.md" "$MEMORY_DIR/superpowers-patterns.md" +echo " Installed: memory files -> $MEMORY_DIR" + +echo "" +echo "Done. Restart Claude Code for settings to take effect." diff --git a/memory/MEMORY.md b/memory/MEMORY.md new file mode 100644 index 0000000..818c439 --- /dev/null +++ b/memory/MEMORY.md @@ -0,0 +1,36 @@ +# Claude Memory — /Users/timevans/Git + +## Core Working Philosophy +- Fight "context rot": break large tasks into fresh-context atomic units +- Discussion-first: capture user preferences BEFORE planning or building +- Spec before code: design → research → requirements → plan → execute → verify +- Atomic commits per task — enables git bisect, clear history, easy revert +- File-based state: human-readable Markdown/JSON survives context resets +- Evidence over claims: never say "done" without running actual verification + +## Iron Laws (from Superpowers — non-negotiable) +1. No production code without a failing test first +2. No fix without root cause investigation first +3. No completion claim without fresh verification evidence + +## Workflow Model +1. **Brainstorm/Discuss** — Socratic dialogue; surface gray areas; get explicit approval before building +2. **Research** — gather context, stack options, pitfalls +3. **Plan** — bite-sized atomic tasks (2-5 min each), dependency-ordered, with verify steps +4. **Execute** — parallel waves; TDD (RED→GREEN→REFACTOR) per task +5. **Debug** — 4-phase root cause (read errors → reproduce → check changes → gather evidence) before ANY fix +6. **Verify** — run actual commands, confirm actual output; no assertions without evidence +7. **Review** — two-stage: spec compliance first, then code quality +8. **Ship** — user acceptance, clean up, then loop to next phase + +See: [gsd-patterns.md](./gsd-patterns.md) and [superpowers-patterns.md](./superpowers-patterns.md) + +## User Preferences +- Concise, direct communication — lead with answer, not reasoning +- No emojis unless explicitly requested +- Reference file:line when pointing to code + +## Project Notes +- Working dir: /Users/timevans/Git +- GSD repo available at: /Users/timevans/Git/GSD/get-shit-done-main +- Superpowers repo available at: /Users/timevans/Git/Superpowers diff --git a/memory/gsd-patterns.md b/memory/gsd-patterns.md new file mode 100644 index 0000000..d70e403 --- /dev/null +++ b/memory/gsd-patterns.md @@ -0,0 +1,90 @@ +# GSD Patterns & Mental Models + +Source: /Users/timevans/Git/GSD/get-shit-done-main (v1.29.0) + +## Core Problem GSD Solves +- **Vibecoding**: casual AI-assisted coding where context degrades and quality drops +- **Context rot**: quality degradation as context window fills up +- Solution: structured context engineering, fresh agent contexts per task, file-based state + +## Key Mental Models + +### 1. Wave-Based Execution +Group tasks by dependencies into waves. Run each wave in parallel: +- Wave 1: all independent tasks (parallel) +- Wave 2: tasks that depend on Wave 1 (parallel within wave) +- Never execute dependent tasks in parallel — causes conflicts +- Each task gets its own fresh context window (200K) + +### 2. Discussion-First +Before planning ANYTHING non-trivial, surface ambiguities: +- Layouts and visual preferences +- Error handling strategies +- Naming conventions +- Tone/UX approach +- Edge cases the user hasn't mentioned +Two modes: `discuss` (interview style) or `assumptions` (analyze codebase, propose assumptions) + +### 3. Atomic Plans with XML Structure +Each plan task should be: +- Independently executable +- Has specific files, action, verification step, and done criteria +- Atomic git commit per task +- Checker validates plans are complete before execution (read-only check) + +### 4. State as Files (not memory) +All project state lives in `.planning/` as Markdown/JSON: +- PROJECT.md — vision, constraints, decisions +- REQUIREMENTS.md — scoped requirements (v1/v2/out-of-scope) +- ROADMAP.md — phase breakdown with status +- STATE.md — current position, decisions, blockers (living document) +- phases/XX-phase-name/ — per-phase context, research, plans, summaries + +### 5. Researcher → Planner → Checker → Executor → Verifier +Each role is specialized, never combined: +- Researchers: gather info, never write code +- Checkers: evaluate plans, never modify them (read-only) +- Executors: implement, don't research +- Verifiers: confirm outcomes match goals post-execution + +### 6. Fresh Context Per Task +Avoid context rot by spawning subagents with focused roles and fresh context. +Orchestrators stay thin — they coordinate, don't implement. + +### 7. Model Profiles +Match model capability to task complexity: +- Planning (most complex): Opus +- Execution (implementation): Sonnet +- Verification (checking): Sonnet or Haiku +- Budget tasks: all Sonnet + +### 8. "Absent = Enabled" Config Philosophy +Default configs should default to safe/on. Users explicitly disable, not enable. +Missing keys mean feature is active. + +## Greenfield vs Brownfield +- **Greenfield**: new-project → research → requirements → roadmap +- **Brownfield** (existing code): map-codebase first (4 parallel researchers analyze stack, architecture, conventions, concerns, testing, integrations) + +## Verification Layers +1. **Plan check** — does the plan cover all requirements? (before execution) +2. **Integration check** — do plans work together? (cross-plan compatibility) +3. **Post-execution verify** — did execution achieve goals? +4. **UAT** — user acceptance testing (manual) +5. **Nyquist validation** — test coverage gaps identified and filled +6. **UI review** — 6-pillar visual audit (if UI work) + +## Security Patterns (GSD v1.27+) +- Validate user paths resolve within project directory +- Scan planning artifacts for prompt injection before use +- Sanitize user text before shell interpolation +- Safe JSON parsing — catch malformed args before state corruption + +## Anti-Patterns to Avoid (from GSD philosophy) +- Editing code without reading it first +- Planning without discussing ambiguities +- Large monolithic tasks (break into atomic units) +- Combining researcher/planner/executor roles +- Ignoring existing conventions in brownfield projects +- Skipping verification steps +- Batch commits (commit per task, not per phase) diff --git a/memory/superpowers-patterns.md b/memory/superpowers-patterns.md new file mode 100644 index 0000000..7979434 --- /dev/null +++ b/memory/superpowers-patterns.md @@ -0,0 +1,116 @@ +# Superpowers Patterns & Mental Models + +Source: /Users/timevans/Git/Superpowers (v5.0.6, Jesse Vincent / obra) + +## Core Problem Superpowers Solves +- AI agents write code confidently that is untested, unverified, and unreviewed +- "Quick fixes" mask root causes; claims of completion are unverified assertions +- No enforced discipline means each session rediscovers the same failure modes +- Solution: iron-law workflows that mandate process at each stage + +## Iron Laws (non-negotiable, never rationalize away) + +1. **No production code without a failing test first** (TDD) +2. **No fix without root cause investigation first** (debugging) +3. **No completion claim without fresh verification evidence** (verification) + +These are NOT guidelines. Rationalizations like "too simple to test", "quick fix", "I'm confident it works" are red flags — stop, don't proceed. + +## Key Mental Models + +### 1. RED-GREEN-REFACTOR (TDD Cycle) +Every feature, every time: +1. Write a failing test (RED) — verify it actually fails, don't skip this +2. Write minimal code to pass (GREEN) — minimal means minimal +3. Refactor with tests still passing (REFACTOR) +- "If you didn't watch the test fail, you don't know if it tests the right thing" +- Tests written after the fact prove nothing; tests written first prove the code works + +### 2. Design Before Code (Brainstorming) +Socratic dialogue to refine ideas before a line is written: +- Present designs in discrete sections, get user approval on each +- Explore alternatives — what if we didn't do it this way? +- Surface constraints and tradeoffs the user hasn't thought of +- Save design spec to `docs/superpowers/specs/YYYY-MM-DD--design.md` +- Do NOT start implementing until design is explicitly approved + +### 3. Bite-Sized Plans +Good plans have tasks that are: +- 2-5 minutes of work each +- Self-contained with exact file paths +- Include complete code (not "add error handling") +- Include the specific test verification step +- Include the atomic commit step +- Save plan to `docs/superpowers/plans/YYYY-MM-DD-.md` + +### 4. Systematic Debugging (4-Phase Root Cause) +Before touching any code: +1. **Read errors carefully** — exact message, file, line, stack trace +2. **Reproduce** — confirm you can trigger it reliably +3. **Check recent changes** — git log/diff, what changed? +4. **Gather evidence** — logs, state, reproduction case + +Only AFTER all four phases: hypothesize → test hypothesis → fix → verify fix. +No guesses. No "probably". No trying things to see if they work. + +### 5. Evidence Before Completion Claims +Never say "done", "working", "fixed" without: +- Running the actual verification command +- Seeing the actual output +- Confirming the output matches expected +"Should work", "I'm confident", "probably" = not done. Run the command. + +### 6. Two-Stage Code Review +When reviewing code (or requesting review): +- Stage 1: Spec compliance — does it do what was designed? +- Stage 2: Code quality — is it well-written, secure, maintainable? +Never collapse these into one pass. Spec compliance comes first. + +### 7. Subagent Context Isolation +When dispatching subagents: +- Each gets a fresh context with ONLY what it needs +- No session history leaks in +- Provide: task description, relevant files, acceptance criteria +- Do NOT provide: full conversation history, unrelated context +- Two-stage review built into subagent-driven-development + +### 8. Git Worktree Isolation +For non-trivial branches: +- Create isolated worktree (`.worktrees//`) +- Run baseline tests before starting — confirm clean state +- Work doesn't pollute main checkout +- Verify tests pass before finishing branch + +### 9. finishing-a-development-branch Checklist +Before merging anything: +1. All tests pass +2. New code has tests +3. Verification evidence collected (not assumed) +4. Present options: merge / open PR / discard +5. Clean up worktree after merge + +## Skill Design Principles (meta) +When writing process documentation / skills: +- Description field = WHEN to use (not what it does) — Claude searches by trigger condition +- Pressure test first: run agent WITHOUT skill, observe failure mode +- Then write skill to address exactly that failure mode +- Verify compliance by re-running the failing scenario +- "Writing skills IS test-driven development applied to documentation" + +## Anti-Patterns to Avoid (from Superpowers) +- Writing tests after code is written (they prove nothing) +- Fixing bugs without identifying root cause first +- Claiming completion before running verification +- Broad agent context (subagents get minimal, focused context only) +- Parallel tasks that share mutable state +- Skipping the RED step in TDD ("it obviously fails") +- Ad-hoc debugging ("let me just try changing this") +- "Just this once" exceptions to iron laws + +## How This Complements GSD +GSD handles: project structure, phase management, research, planning, state files, context rot +Superpowers handles: code discipline, TDD enforcement, debugging methodology, verification rigor, review quality + +Combined workflow: +1. GSD: Discuss → Research → Plan (file-based, wave-organized) +2. Superpowers: Brainstorm → Write plan (bite-sized) → TDD execute → Systematic debug → Verify → Review → Merge diff --git a/settings.json b/settings.json new file mode 100644 index 0000000..fb9c69b --- /dev/null +++ b/settings.json @@ -0,0 +1,10 @@ +{ + "env": { + "MAX_THINKING_TOKENS": "8000", + "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "50" + }, + "autoUpdaterStatus": "enabled", + "preferredNotifChannel": "terminal_bell", + "verbose": false, + "cleanupPeriodDays": 30 +}