AGENTS.md · diff
git:20261030.cb02696 to git:20261103.51c5454
1 added, 2 removed. Audit A to A.
What this update changes in the checks
No check changed: every fixed check gives the same answer before and after this update.
A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.
## Project Architecture
**AI Pair Programming Workspace** — toolkit for enhancing AI-assisted development. Centralizes agent personas, skills, and structured workflows.
### Core Components
- **MCP Servers** (`src/mcps/`): FastMCP-based tools — `skill_loader_mcp.py`, `search_engine.py` (semantic search). Registered proxies (DB, GitHub, Figma, etc.) are routed through `mcp-manager` and configured in `.mcp.json`.
- **Agents** (`agents/`): Persona definitions (developer-specialist, cybersecurity-specialist, etc.) with behavioral instructions.
- **Skills** (`skills/`): Reusable capabilities (workflows, guides, analysis patterns).
- **Instructions** (`instructions/`): Domain-specific rules (code style, testing, React patterns, etc.).
### Directory Reference
```
src/ MCP servers, utilities, copilot proxy
agents/ Agent persona YAML/markdown definitions
skills/ Skill files (workflows, style guides)
instructions/ Domain-specific rules and conventions
scripts/ Installation and environment setup
commands/ CLI command definitions
hooks/ Event-driven automation (Claude Code hooks)
lefthook/ Git hooks (managed by lefthook)
docs/ Project documentation
```
## Key Technologies
- **Python 3.11+** with `uv` for dependency management (`uv.lock` at root; `src/` builds with setuptools)
- **FastMCP** (`fastmcp>=2.0`): Model Context Protocol server framework
- **pytest**: Test framework (`asyncio_mode = "auto"`)
- **Node.js/TypeScript**: Supported for various project types
- **Bash**: Installation and environment scripts
## Quick Start Commands
Install and setup:
```bash
uv sync # Install root Python deps (hook scripts)
cd src && uv sync # Install MCP server deps
./install.sh [--all|--claude] # Set up symlinks, lefthook, and configurations
```
Run tests:
```bash
uv run --with pytest pytest scripts/ # Run script tests
```
Run MCP servers:
```bash
cd src && uv run skill-loader-mcp # skill-loader MCP server
```
<!-- INIT:AUTO-GENERATED-CONTEXT:DO-NOT-MODIFY -->
+
## Mandatory rules — always follow
- User question → interactive tool, never plain text. Claude: `AskUserQuestion`. Many questions: `grilling` skill.
- `AskUserQuestion` must be fully contextualized, never terse. Question body: explain _why_ asked (what found in code, what trade-off) before choice. Option `description`: what picking it does/causes — not label restated. No truncated question/option text; full explanation every time.
- User asks question → answer only. No code change without explicit user authorization.
- Multi-step work → use `TaskCreate`, `TaskGet`, `TaskList`, `TaskUpdate` for feedback. Mark each task complete when done, no batching.
- Modify component/screen → run Playwright (or similar E2E) tests before finalizing.
- Lint/type/test errors in touched files → fix, even if not caused by you.
- Docs (`markdown files`, `memories`) not absolute truth. Only implemented code = truth.
- No code assumed correct without tests validating it.
- TDD mandatory when repo already has tests (suite/framework present): failing test first (Red), minimal code to pass (Green), then refactor. Small loops only, no big unverified blocks. No test setup in repo → don't impose one unprompted.
- Evidence over trust: before human review, give proof change works — passing test logs, screenshots/recordings of E2E or visual tests. No "should work" claims.
- Vertical slices only: thin end-to-end slices (tracer bullets) through all layers, not horizontal layers (all DB, then all API, then all UI). Each slice tested and validated before next.
- Task done (testing, execution, build) → kill all background processes/servers started, delete temp dirs generated.
- Anytime: evaluate what worth saving as permanent memory. Save only what next session needs and can't rediscover from code, Git, or CLAUDE.md — _reason_ behind decision, non-obvious invariant, user preference. Already in repo or only relevant to this conversation → don't save. Persist via `ai-memory-durable-pages` skill.
## Mandatory rules — hallucination protection
- "I don't know" allowed: uncertain or info missing → say so explicitly (e.g. "I don't have enough information to confidently assess this"). Never fill gaps with guesses.
- Quote before analyzing: long docs (>20k tokens) → first extract word-for-word quotes relevant to task, base analysis only on them, reference by number. None found → say "No relevant quotes found".
- Cite every factual claim: each claim about code, docs, external sources carries source (`path:line`, command output, URL, direct quote) for audit.
- Verify after generating: check each claim in response has supporting quote/source. None → retract claim (mark removal with `[]` when editing document).
## Context-Specific Rules
The following rules apply to specific file types:
-
- [code.instructions](.claude/instructions/code.instructions.md) — applies to: `**/*.ts, **/*.js, **/*.py, **/*.java, **/*.go, **/*.css, **/*.cpp, **/*.c, **/*.vue, **/*.jsx, **/*.tsx`
-
<!-- END:AUTO-GENERATED-CONTEXT:DO-NOT-MODIFY -->