CLAUDE.md · diff
git:20260224.203719e to git:20260503.9963ce2
167 added, 1 removed. Audit B to B.
- AGENTS.md
+ ## Overview
+
+ This is a **meta-repository** for Claude Code. It serves as a unified workspace with shared skills, commands, and an automated setup evaluator — 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**.
+
+ 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>
+ ```
+