|
2 | 2 |
|
3 | 3 | Guidance for Claude Code when working with this repository. |
4 | 4 |
|
| 5 | +## Repository Structure |
| 6 | + |
| 7 | +This repository uses a worktree-based development workflow. |
| 8 | + |
| 9 | +**Documentation Setup:** |
| 10 | +- This file is `AGENTS.md` (the canonical source) |
| 11 | +- `CLAUDE.md` is a symlink pointing to `AGENTS.md` |
| 12 | +- Read either file - they're the same content |
| 13 | +- Commit changes to `AGENTS.md`, the symlink will automatically reflect them |
| 14 | + |
| 15 | +**Directory Structure:** |
| 16 | +``` |
| 17 | +/home/julien/github/ha-mcp/ # Main repository (checkout master here) |
| 18 | +├── AGENTS.md # This file (canonical source) |
| 19 | +├── CLAUDE.md -> AGENTS.md # Symlink for convenience |
| 20 | +├── worktree/ # Git worktrees (gitignored) |
| 21 | +│ ├── issue-42/ # Feature branch worktree |
| 22 | +│ └── fix-something/ # Fix branch worktree |
| 23 | +├── local/ # Scratch work (gitignored) |
| 24 | +└── .claude/agents/ # Custom agent workflows |
| 25 | +``` |
| 26 | + |
| 27 | +**Why use `worktree/` subdirectory:** |
| 28 | +- Keeps worktrees organized in one place |
| 29 | +- Gitignored (won't pollute `git status`) |
| 30 | +- All worktrees automatically inherit `.claude/agents/` workflows |
| 31 | +- Easy cleanup: `git worktree prune` removes stale references |
| 32 | + |
| 33 | +## Worktree Workflow |
| 34 | + |
| 35 | +### Creating Worktrees |
| 36 | + |
| 37 | +**ALWAYS create worktrees in the `worktree/` subdirectory**, not at the repository root. |
| 38 | + |
| 39 | +```bash |
| 40 | +# Correct - worktrees go in worktree/ subdirectory |
| 41 | +cd /home/julien/github/ha-mcp |
| 42 | +git worktree add worktree/issue-42 -b issue-42 |
| 43 | +git worktree add worktree/feat-new-feature -b feat/new-feature |
| 44 | + |
| 45 | +# Wrong - don't create worktrees at repo root |
| 46 | +git worktree add issue-42 -b issue-42 # ❌ Creates orphaned worktree |
| 47 | +git worktree add ../issue-42 -b issue-42 # ❌ Outside repo, no .claude/agents/ |
| 48 | +``` |
| 49 | + |
| 50 | +**Working in a worktree:** |
| 51 | +```bash |
| 52 | +# Navigate to your worktree |
| 53 | +cd worktree/issue-42 |
| 54 | + |
| 55 | +# Work normally - you have full access to .claude/agents/ |
| 56 | +git status |
| 57 | +git commit -m "feat: implement feature" |
| 58 | +git push |
| 59 | + |
| 60 | +# When done, return to main repo and clean up |
| 61 | +cd /home/julien/github/ha-mcp |
| 62 | +git worktree remove worktree/issue-42 |
| 63 | +``` |
| 64 | + |
| 65 | +**Cleaning up stale worktrees:** |
| 66 | +```bash |
| 67 | +# If worktree directories were deleted but git still tracks them |
| 68 | +git worktree prune |
| 69 | +``` |
| 70 | + |
| 71 | +### Agent Workflows |
| 72 | + |
| 73 | +Custom agent workflows are located in `.claude/agents/`: |
| 74 | + |
| 75 | +| Agent | File | Model | Purpose | |
| 76 | +|-------|------|-------|---------| |
| 77 | +| **issue-analysis** | `issue-analysis.md` | Opus | Deep issue analysis - comprehensive codebase exploration, implementation planning, architectural assessment, complexity evaluation. Complements automated Gemini triage with human-directed deep analysis. | |
| 78 | +| **issue-to-pr-resolver** | `issue-to-pr-resolver.md` | Sonnet | End-to-end issue implementation: pre-flight checks → worktree creation → implementation with tests → pre-PR checkpoint → PR creation → iterative CI/review resolution until merge-ready. | |
| 79 | +| **pr-checker** | `pr-checker.md` | Sonnet | Review and manage existing PRs - check comments, CI status, resolve review threads, monitor until all checks pass. | |
| 80 | + |
5 | 81 | ## Project Overview |
6 | 82 |
|
7 | 83 | **Home Assistant MCP Server** - A production MCP server enabling AI assistants to control Home Assistant smart homes. Provides 80+ tools for entity control, automations, device management, and more. |
@@ -513,6 +589,9 @@ return create_error_response( |
513 | 589 | {"success": False, "error": {...}} # Failure |
514 | 590 | ``` |
515 | 591 |
|
| 592 | +### Tool Consolidation |
| 593 | +When a tool's functionality is fully covered by another tool, **remove** the redundant tool rather than deprecating it. Fewer tools reduces cognitive load for AI agents and improves decision-making. Do not add deprecation notices or shims — just delete the tool and update any docstring references to point to the replacement. |
| 594 | + |
516 | 595 | ## Tool Waiting Behavior |
517 | 596 |
|
518 | 597 | **Principle**: MCP tools should wait for operations to complete before returning, not just acknowledge API success. |
|
0 commit comments