CLAUDE.md git:20260818.c105324B

Immutable. This exact content is served forever at /api/v1/blob/e4f3f845fab0783b.

## 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/`](agent-docs/).

## **Critical Requirements**

<critical-requirements>
These requirements ALWAYS apply. Follow them throughout every task - some apply at task start, others when specific situations arise:

1. **Read relevant documentation first** - Before taking action on any task:
   - Review the [Agent Docs](#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/`](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/README.md).

### Agent Docs

<agent-docs-items>
<doc path="agent-docs/codebase-onboarding.md">
<name>Codebase Onboarding</name>
<description>Systematic onboarding to unfamiliar codebases. Analyzes project structure, tech stack, conventions, entry points, and data flow to produce an onboarding guide. Use when joining a new project or helping a team member get started.</description>
<when-to-read>When exploring an unfamiliar repository for the first time. When generating onboarding docs for a new team member. When analyzing project structure, conventions, dependencies, or entry points of a codebase you haven't worked in before.</when-to-read>
</doc>
<doc path="agent-docs/deep-research.md">
<name>Deep Research</name>
<description>Multi-source deep research with citations. Use when the user wants thorough research on any topic — technology evaluation, library comparison, algorithm analysis, literature review, or competitive analysis. Searches the web, synthesizes findings, and delivers cited reports.</description>
<when-to-read>When the user asks for research, comparison, or evaluation of technologies, libraries, algorithms, or approaches. When producing a literature review, competitive analysis, or trade-off assessment that requires multiple web sources.</when-to-read>
</doc>
<doc path="agent-docs/mcp-patterns.md">
<name>Mcp Patterns</name>
<description>Patterns for building, securing, and consuming MCP (Model Context Protocol) servers. Covers schema-first design, authentication, input validation, audit logging, and security best practices.</description>
<when-to-read>When building, modifying, or debugging an MCP server. When defining MCP tool schemas, configuring MCP authentication, or reviewing MCP security. When a .mcp.json file is present and the user is working on MCP integration.</when-to-read>
</doc>
<doc path="agent-docs/subagent-driven-development.md">
<name>Subagent-Driven Development Guide</name>
<description>Execute implementation plans by dispatching a fresh subagent per task with two-stage review (spec compliance, then code quality). Power-user workflow for complex multi-task implementations.</description>
<when-to-read>When executing implementation plans with many independent tasks in the current session. When you need isolated context per task to avoid pollution.</when-to-read>
</doc>
<doc path="agent-docs/workspace-development.md">
<name>Workspace Development Guide</name>
<description>How to modify, configure, and extend this workspace. Covers configuration, package management, creating agent-docs/skills/commands, tool discovery, and session hooks.</description>
<when-to-read>When modifying workspace infrastructure or configuration. When creating or editing agent-docs, skills, or commands. When adding dependencies or changing ai-workspace.toml. When adding session hook support for a new AI tool.</when-to-read>
</doc>
<doc path="agent-docs/writing-skills.md">
<name>Writing Skills Guide</name>
<description>TDD methodology for creating new AI skills. Covers skill types, SKILL.md structure, Claude Search Optimization, testing with subagents, and the RED-GREEN-REFACTOR cycle applied to documentation.</description>
<when-to-read>When creating new skills, editing existing skills, or verifying skills work before deployment. When extending the workspace with new team-specific patterns.</when-to-read>
</doc>
</agent-docs-items>

## Agent Resources Overview

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

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

<commands-section>
## Commands

The [`commands/`](commands/) directory contains AI commands invoked by humans via `/command` syntax.

For more information, see [`commands/README.md`](commands/README.md).
</commands-section>

<skills-section>
## Skills

The [`skills/`](skills/) directory contains reusable agent skills following the [Agent Skills specification](https://agentskills.io/specification).

For more information, see [`skills/README.md`](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:
```bash
uv run .ai-workspace/scripts/align-workspace.py
```

For configuration reference, see [`.ai-workspace/README.md`](.ai-workspace/README.md).

## Pre-commit Hooks

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

**Setup (if not already installed):**
```bash
uv run pre-commit install
```

**Recommended workflow:** After completing tasks, run pre-commit to validate the workspace:
```bash
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:

```bash
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/`](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.

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