claude-code-basecamp

Overview

This is a meta-repository for Claude Code. It serves as a unified workspace with shared skills, commands, and hooks — so every team member gets consistent, high-quality AI assistance from day one.

Note: The "Agent Docs" listing below is auto-generated from frontmatter in markdown files in agent-docs/.

Critical Requirements

1. Read relevant documentation first - Before taking action on any task:
   • Review the Agent Docs list below
   • Read ALL documents relevant to your task before proceeding
   • Re-evaluate after encountering failures or gaining new insights—additional documents may become relevant
2. Use uv for Python execution - Execute all scripts and tools with uv run <script/tool>. This workspace exclusively uses uv for package and environment management. For scripts with inline dependencies (PEP 723), run them directly (uv run script.py) to ensure dependencies resolve correctly.
3. Use available skills - Check if relevant skills are available in your environment for your tasks, and if there are - utilize them.
4. Verify before diagnosing - When analyzing failures or investigating issues, use documentation and available tools to verify facts. Provide diagnoses ONLY after verification.

5. Write minimal, correct code (Ponytail ladder) - Before writing any code, stop at the first rung that holds:

   1. Does this need to be built at all? (YAGNI)
   2. Does it already exist in this codebase? Reuse the helper, util, or pattern that's already here, don't re-write it.
   3. Does the standard library already do this? Use it.
   4. Does a native platform feature cover it? Use it.
   5. Does an already-installed dependency solve it? Use it.
   6. Can this be one line? Make it one line.
   7. Only then: write the minimum code that works.

   The ladder runs after understanding the problem, not instead of it: read the task and code it touches, trace the real flow end-to-end, then climb. Mark deliberate simplifications with a ponytail: comment naming the ceiling and upgrade path. Never skip validation, error handling, security, or accessibility — these are never on the chopping block.

Violating these requirements results in incomplete solutions, wasted effort, and task failures. </critical-requirements>

Modular Documentation System

The agent-docs/ directory contains modular, task-focused documentation that provides crucial information, context, and instructions for various tasks relevant to this workspace.

Documentation review workflow:

1. ALWAYS review the "Agent Docs" list below when starting any task
2. Identify documents relevant to your task based on their descriptions and "When to read" sections
3. Read ALL identified relevant documents before proceeding
4. Re-evaluate relevance whenever you gain new insights during the task - when discoveries change your understanding, immediately check if additional documents are now relevant

For more information, see agent-docs/README.md.

Agent Docs

Agent Resources Overview

In addition to environment-provided capabilities (e.g., tools, MCPs, Skills), this workspace defines project-specific resources:

• Documentation (agent-docs/) — AI reads when relevant to tasks
• Skills (skills/) — Reusable agent capabilities with scripts and instructions
• Commands (commands/) — Human invokes via /command; AI receives prompt

The commands/ directory contains AI commands invoked by humans via /command syntax.

For more information, see commands/README.md. </commands-section>

The skills/ directory contains reusable agent skills following the Agent Skills specification.

For more information, see skills/README.md. </skills-section>

Configuration

This workspace is configured via ai-workspace.toml at the repository root. After changing configuration or agent docs, regenerate workspace files:

uv run .ai-workspace/scripts/align-workspace.py

For configuration reference, see .ai-workspace/README.md.

Pre-commit Hooks

Pre-commit hooks are configured to maintain code quality and documentation consistency.

Setup (if not already installed):

uv run pre-commit install

Recommended workflow: After completing tasks, run pre-commit to validate the workspace:

uv run pre-commit run --all-files

Temporary Files

The .tmp/ directory is git-ignored and available for transient artifacts, design documents, logs, or intermediate files.

When writing files to .tmp/: First create a task-specific subdirectory:

uv run .ai-workspace/scripts/mktmpdir.py [name]

The script outputs the created path. If the directory exists, returns the existing path.

When delegating subtasks: Pass the directory path so related work stays together.

Working with Repositories

The repositories/ directory is where users clone the repos they work on. These repos are not tracked by the workspace — each user clones what they need.

Before making changes to any repo in repositories/, read its documentation:

1. CLAUDE.md — Follow repo-specific conventions, commands, and workflows
2. README.md — Understand project context, structure, and development practices
3. Other relevant docs — Review additional documentation as needed

Repository Focus

The user can type /focus to select which repo(s) to work on. After selection, constrain all file operations to the selected repo(s) — do not read or modify files in unselected repos under repositories/ unless the user explicitly asks.

Repository Status

At session start, each repository's git state is reported via <repository-status> in the session context. This includes:

• Current branch and configured default branch
• Whether there are uncommitted changes
• How many commits behind the remote tracking branch

Use this information to decide whether to switch branches, pull latest changes, or proceed as-is. Verify current repo state with git commands before branch switches or destructive operations — this status is a snapshot from session start and may be outdated.

Commit/Push Workflow

When working in a repo under repositories/, commit and push directly from within that repo. Changes push to that repo's own remote — the workspace is never involved.

cd repositories/<repo>
git add <files> && git commit -m "Your changes"
git push origin <branch>