diff --git a/CLAUDE.md b/CLAUDE.md index b7977f3..ea55f37 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,70 +1,4 @@ # Global Claude Code Instructions -## Session Behavior -- Treat each session as stateless — do not assume context from prior sessions -- The CLAUDE.md hierarchy is the only source of persistent context -- If something needs to carry forward across sessions, it belongs in a CLAUDE.md file, not in session memory - -## Project Memory -- Project-specific memory lives in `.claude/memory/` at the project root -- Use `MEMORY.md` in that directory as the index (one line per entry pointing to a file) -- Memory files use frontmatter: `name`, `description`, `type` (user/feedback/project/reference) -- Commit `.claude/memory/` with the repo so memory persists across machines and sessions - - -## Commits & Git Workflow -- Make many small, tightly scoped commits — one logical change per commit -- Follow conventional commit format per the conventions skill -- Ask before pushing to remote or force-pushing -- Ask before opening PRs unless explicitly told to - -## Responses & Explanations -- Be concise — lead with the action or answer, not the preamble -- Include just enough reasoning to explain *why* a decision was made, not a full walkthrough -- Skip trailing summaries ("Here's what I did...") — the diff speaks for itself -- No emojis unless explicitly asked - -## Tool & Approach Philosophy -- Prefer tools and solutions that are declarative and reproducible over imperative one-offs -- Portability across dev environments is a first-class concern — avoid hardcoding machine-specific paths or assumptions -- The right tool for the job is the right tool — no language/framework bias, but favor things that can be version-pinned and reproduced - -## Parallelism -- Always parallelize independent work — tool calls, subagents, file reads, searches -- When a task has components that don't depend on each other, run them concurrently by default -- Spin up subagents for distinct workstreams (audits, refactors, tests, docs) rather than working sequentially -- Subagents default to Sonnet for cost efficiency; agent frontmatter overrides where capability requires a different model -- Sequential execution should be the exception, not the default - -## Cost Awareness -- Subagent outputs should be concise — return the deliverable, not the reasoning -- When subagent results return to main context, prefer summaries over verbatim output -- Not every task needs the full planning pipeline — Tier 1 tasks with obvious approaches can go straight to worker dispatch - -## Verification -- After making changes, run relevant tests or build commands to verify correctness before reporting success -- If no tests exist for the changed code, say so rather than silently assuming it works -- Prefer running single targeted tests over the full suite unless asked otherwise - -## Context Management -- Use subagents for exploratory reads and investigations to keep the main context clean -- Prefer scoped file reads (offset/limit) over reading entire large files -- When a task is complete or the topic shifts significantly, suggest /clear - -## When Things Go Wrong -- If an approach fails twice, stop and reassess rather than continuing to iterate -- Present the failure clearly and propose an alternative before proceeding - -## Nix -- Nix is the preferred meta package manager on all systems — assume it is available even on non-NixOS Linux -- Always prefer a project-level `flake.nix` as the canonical way to define dev environments, build systems, and scripts -- Dev environments go in `devShells`, project scripts/tools go in `packages` or as `apps` within the flake -- Never suggest `apt`, `brew`, `pip install --user`, `npm install -g`, or other imperative global installs — reach for `nix shell`, `nix run`, or the project devshell instead -- Prefer `nix run` for one-off tool invocations and `nix develop` (or `direnv` + `use flake`) for persistent dev shells -- Binaries and tools introduced to a project should be pinned and run through Nix, not assumed to be on `$PATH` from the host -- Flakes are the preferred interface — avoid legacy `nix-env` or channel-based patterns - -## Research Before Acting -- Before implementing a solution, research it — read relevant documentation, search for existing patterns, check official sources -- Do not reason from first principles when documentation or prior art exists -- Prefer verified answers over confident guesses +Rules are modularized in `~/.claude/rules/` and loaded automatically. +Agent-team specific protocols live in skills (orchestrate, conventions, worker-protocol, qa-checklist). diff --git a/README.md b/README.md index 95e02b3..21bb649 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ cd ~/agent-team ./install.sh ``` -The script symlinks `agents/`, `skills/`, `CLAUDE.md`, and `settings.json` into `~/.claude/`. Works on Linux, macOS, and Windows (Git Bash). +The script symlinks `agents/`, `skills/`, `rules/`, `CLAUDE.md`, and `settings.json` into `~/.claude/`. Works on Linux, macOS, and Windows (Git Bash). ## Maintenance @@ -38,6 +38,10 @@ The script symlinks `agents/`, `skills/`, `CLAUDE.md`, and `settings.json` into | `qa-checklist` | Self-validation checklist workers run before returning results | | `project` | Instructs agents to check for and ingest a project-specific skill file before starting work | +## Rules + +Global instructions are modularized in `rules/` and auto-loaded by Claude Code from `~/.claude/rules/` on every session. Each file covers a focused topic (git workflow, Nix preferences, response style, etc.). Agent-team specific protocols live in skills, not rules. + ## How to use In an interactive Claude Code session, load the orchestrate skill when a task is complex enough to warrant delegation: diff --git a/install.sh b/install.sh index b68a323..50fbf87 100755 --- a/install.sh +++ b/install.sh @@ -8,8 +8,10 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" CLAUDE_DIR="$HOME/.claude" AGENTS_SRC="$SCRIPT_DIR/agents" SKILLS_SRC="$SCRIPT_DIR/skills" +RULES_SRC="$SCRIPT_DIR/rules" AGENTS_DST="$CLAUDE_DIR/agents" SKILLS_DST="$CLAUDE_DIR/skills" +RULES_DST="$CLAUDE_DIR/rules" CLAUDE_MD_SRC="$SCRIPT_DIR/CLAUDE.md" CLAUDE_MD_DST="$CLAUDE_DIR/CLAUDE.md" SETTINGS_SRC="$SCRIPT_DIR/settings.json" @@ -118,6 +120,7 @@ create_file_symlink() { create_symlink "$AGENTS_SRC" "$AGENTS_DST" "agents" create_symlink "$SKILLS_SRC" "$SKILLS_DST" "skills" +create_symlink "$RULES_SRC" "$RULES_DST" "rules" create_file_symlink "$CLAUDE_MD_SRC" "$CLAUDE_MD_DST" "CLAUDE.md" create_file_symlink "$SETTINGS_SRC" "$SETTINGS_DST" "settings.json" diff --git a/rules/01-session.md b/rules/01-session.md new file mode 100644 index 0000000..f3db2d6 --- /dev/null +++ b/rules/01-session.md @@ -0,0 +1,12 @@ +# Session Behavior + +- Treat each session as stateless — do not assume context from prior sessions +- The CLAUDE.md hierarchy is the only source of persistent context +- If something needs to carry forward across sessions, it belongs in a CLAUDE.md file, not in session memory + +# Project Memory + +- Project-specific memory lives in `.claude/memory/` at the project root +- Use `MEMORY.md` in that directory as the index (one line per entry pointing to a file) +- Memory files use frontmatter: `name`, `description`, `type` (user/feedback/project/reference) +- Commit `.claude/memory/` with the repo so memory persists across machines and sessions diff --git a/rules/02-responses.md b/rules/02-responses.md new file mode 100644 index 0000000..2dbbdf1 --- /dev/null +++ b/rules/02-responses.md @@ -0,0 +1,6 @@ +# Responses & Explanations + +- Be concise — lead with the action or answer, not the preamble +- Include just enough reasoning to explain *why* a decision was made, not a full walkthrough +- Skip trailing summaries ("Here's what I did...") — the diff speaks for itself +- No emojis unless explicitly asked diff --git a/rules/03-git.md b/rules/03-git.md new file mode 100644 index 0000000..d131578 --- /dev/null +++ b/rules/03-git.md @@ -0,0 +1,6 @@ +# Commits & Git Workflow + +- Make many small, tightly scoped commits — one logical change per commit +- Follow conventional commit format per the conventions skill +- Ask before pushing to remote or force-pushing +- Ask before opening PRs unless explicitly told to diff --git a/rules/04-tools.md b/rules/04-tools.md new file mode 100644 index 0000000..4bb7eef --- /dev/null +++ b/rules/04-tools.md @@ -0,0 +1,17 @@ +# Tool & Approach Philosophy + +- Prefer tools and solutions that are declarative and reproducible over imperative one-offs +- Portability across dev environments is a first-class concern — avoid hardcoding machine-specific paths or assumptions +- The right tool for the job is the right tool — no language/framework bias, but favor things that can be version-pinned and reproduced + +# Parallelism + +- Always parallelize independent work — tool calls, file reads, searches +- When a task has components that don't depend on each other, run them concurrently by default +- Sequential execution should be the exception, not the default + +# Context Management + +- Use subagents for exploratory reads and investigations to keep the main context clean +- Prefer scoped file reads (offset/limit) over reading entire large files +- When a task is complete or the topic shifts significantly, suggest /clear diff --git a/rules/05-verification.md b/rules/05-verification.md new file mode 100644 index 0000000..2d51096 --- /dev/null +++ b/rules/05-verification.md @@ -0,0 +1,10 @@ +# Verification + +- After making changes, run relevant tests or build commands to verify correctness before reporting success +- If no tests exist for the changed code, say so rather than silently assuming it works +- Prefer running single targeted tests over the full suite unless asked otherwise + +# When Things Go Wrong + +- If an approach fails twice, stop and reassess rather than continuing to iterate +- Present the failure clearly and propose an alternative before proceeding diff --git a/rules/06-nix.md b/rules/06-nix.md new file mode 100644 index 0000000..cd7a8f1 --- /dev/null +++ b/rules/06-nix.md @@ -0,0 +1,9 @@ +# Nix + +- Nix is the preferred meta package manager on all systems — assume it is available even on non-NixOS Linux +- Always prefer a project-level `flake.nix` as the canonical way to define dev environments, build systems, and scripts +- Dev environments go in `devShells`, project scripts/tools go in `packages` or as `apps` within the flake +- Never suggest `apt`, `brew`, `pip install --user`, `npm install -g`, or other imperative global installs — reach for `nix shell`, `nix run`, or the project devshell instead +- Prefer `nix run` for one-off tool invocations and `nix develop` (or `direnv` + `use flake`) for persistent dev shells +- Binaries and tools introduced to a project should be pinned and run through Nix, not assumed to be on `$PATH` from the host +- Flakes are the preferred interface — avoid legacy `nix-env` or channel-based patterns diff --git a/rules/07-research.md b/rules/07-research.md new file mode 100644 index 0000000..21f99ea --- /dev/null +++ b/rules/07-research.md @@ -0,0 +1,5 @@ +# Research Before Acting + +- Before implementing a solution, research it — read relevant documentation, search for existing patterns, check official sources +- Do not reason from first principles when documentation or prior art exists +- Prefer verified answers over confident guesses diff --git a/skills/orchestrate/SKILL.md b/skills/orchestrate/SKILL.md index b4b27ef..deaf870 100644 --- a/skills/orchestrate/SKILL.md +++ b/skills/orchestrate/SKILL.md @@ -132,7 +132,7 @@ Collect both verdicts before deciding whether to advance to the next wave or sen - **Docs:** if documentation was in scope, spawn `documenter` now with final implementation as context - **Package:** list what was done by logical area (not by worker). Include all file paths. Surface PASS WITH NOTES caveats as a brief "Heads up" section. -Lead with the result. Don't expose worker IDs, wave counts, or internal mechanics. +Lead with the result. Don't expose worker IDs, wave counts, or internal mechanics. When subagent results return to your context, prefer concise summaries over verbatim output — the full detail is in the code, not the report. ---