# Claude Maintenance Guide

## Purpose

This file defines repository-specific operating rules for Claude Code sessions working in this analysis repository.

## Repository Role

This repository is used to analyze Claude Code framework internals. The main artifacts are:

- `reference/`: source snapshots and source materials
- `reports/`: rendered reports and visual explanations
- `knowledge-base/`: durable Markdown notes and indexes
- `advanced-site/`: generated or exploratory visual material, when present

## Default Behavior

When answering or extending the analysis:

- read the relevant source files before explaining behavior
- cite source paths and line numbers
- distinguish direct source facts from inference
- update `knowledge-base/index.md` when adding a new research topic
- keep topic files focused and top-level unless a subdirectory is clearly justified

## Knowledge Base Rules

Use `knowledge-base/readme.md` as the entry description and `knowledge-base/index.md` as the active topic index.

For each new topic:

1. Create one Markdown file at `knowledge-base/<topic>.md`.
2. Add metadata: category, status, date, source files.
3. Explain the mechanism in plain language.
4. Add a flow diagram when the logic crosses files.
5. Add an evidence map with source references.
6. Add open questions.
7. Link the file from `knowledge-base/index.md`.

## Source Reading Rules

Prefer these source-reading habits:

- use `rg` or `rg --files` first
- read the actual implementation before summarizing
- inspect call sites and data flow, not only type definitions
- verify whether a field is sent to the model or only used locally
- check both interactive REPL and non-interactive/SDK paths when discussing entrypoints

## Report Update Rules

When updating `advanced-site/Claude-Code-Analysis.html`:

- keep sections jumpable from the sticky directory
- add source snippets only when they support a specific claim
- keep new sections consistent with the existing visual style
- validate that script rendering still runs

## Safety Rules

- Do not revert unrelated user changes.
- Do not delete existing notes unless explicitly requested.
- Do not recreate uppercase `.markdown` duplicates for the top-level guides. Use `agents.md` and `claude.md`.
- Do not edit source snapshots under `reference/` unless the user explicitly asks.
- Do not claim browser or visual validation was run unless it actually was.

## Current High-Value Follow-Ups

- `entrypoints-and-normalization.md`: how CLI, REPL, SDK, Bridge, and MCP converge into `Message[]` and `QueryParams`.
- `system-prompt-construction.md`: exact prompt construction priority and dynamic sections.
- `context-injection-and-memory-files.md`: CLAUDE.md, `.claude/rules`, conditional rules, nested memory, and user/system context injection.
- `tool-runtime-and-permissions.md`: local tool execution, `canUseTool`, permission modes, hooks, and bridge/channel approval.
- `transcript-compact-recovery.md`: message growth, compact boundary, transcript persistence, and recovery paths.

## Agent-Team Workflow Notes

Source base: `/Users/stometa/dev/agent-team/README.md`, `/Users/stometa/dev/agent-team/workspace-context.md`, `/Users/stometa/dev/agent-team/templates/auto-harness.md`, and this repository's first report at `advanced-site/Claude-Code-Analysis.html`.

### Core Thesis

Claude-facing workflow in this repository should treat agent execution as a durable tree:

1. The root is the user's goal or issue.
2. First-level branches are the main control surfaces: context, tools, permissions, agents, PR review, and verification.
3. Second-level branches are concrete mechanisms: `QueryParams`, compact boundaries, tool schemas, role rules, review sentinels, and harness checkpoints.
4. Deep leaves are source-backed facts, command evidence, and open questions.

### Workspace Rules From Agent-Team

- Code claims require source paths and line numbers. If a claim cannot be directly cited, mark it as a hypothesis.
- Agents should not route work to each other with mentions. The human routes; agents execute.
- Structured artifacts use templates instead of ad-hoc prose.
- A PR is the delivery unit for code-shipping agents. A commit alone is not a shipped change.
- Every recommendation should include the accepted choice, rejected alternatives, and the constraint that made the accepted choice viable.

### Discovery To Execution

The agent-team flow moves from discussion to delivery through explicit layers:

1. User opens a `discussion` issue.
2. CEO, CTO, PM, and Designer comment from their own lens and recommend senior or junior implementation tier.
3. PM wraps the discussion into a change proposal and creates child issues.
4. Tech Lead writes specs for spec-labeled child issues.
5. Senior or Junior Engineer implements.
6. Review separates code quality, security/performance, product outcome, and behavioral QA.

### PR-Sweep Review Workflow

The PR-sweep automation is a workflow-side state machine:

- GitHub Actions runs a deterministic filter on open PRs.
- Each PR maps to one Multica review issue.
- Senior Engineer and Security & Performance Reviewer independently review the current head SHA.
- HTML sentinels record review state, consensus, or debate.
- Disagreement or blocking findings route to CTO follow-up in the same review issue.

Key insight: script runs are cheap; agent invocations are the cost driver. Deterministic filtering keeps agent work focused on PRs that actually need new review.

### Auto-Harness

Large implementation tasks use a two-stage shape:

1. Stage 1 runs locally in Claude Code and writes `.harness/<task-id>/spec.md`.
2. Stage 2 runs in Multica, parses checkpoints, and creates self-contained child issues.
3. When checkpoint issues close, a fresh E2E child issue verifies the full flow.
4. A retro records outcome, iteration count, wall-clock time, and lessons.

Budget gates should bounce a task back to Stage 1 when it crosses complexity thresholds such as 500+ net LOC, 8+ production files, 3+ modules, LLM call sites, new dependencies, migrations, schema, daemon, or supervisor changes.