# Agents Maintenance Guide ## Purpose This file defines how agents should maintain this repository when adding code-reading notes, reports, or supporting artifacts. The repository is not an implementation project. It is an analysis workspace. The primary output is durable understanding backed by source evidence. ## Responsibilities Agents working in this repository should: - preserve verified findings in `knowledge-base/` - update [index.md](index.md) whenever a new topic file is added - keep `reports/` for rendered or user-facing reports - keep source references under `reference/` unchanged unless the user explicitly asks to update the source snapshot - avoid overwriting existing user-created notes, especially the top-level `agents.md` and `claude.md` guides ## Research Note Standard Every new knowledge-base topic should include: - title - category - status - summary - source evidence - flow or graph when the logic spans multiple files - examples when the concept is easy to confuse - open questions for follow-up Use `verified from source reading` only when the note cites concrete files and line numbers. Use `draft` or `hypothesis` when the reasoning is not fully verified. ## Evidence Rules Use precise source references: ```text reference/sourcecode/src/query.ts:181 reference/sourcecode/src/context.ts:116 ``` When a claim depends on multiple files, list all of them in an evidence map. Do not describe behavior as fact if it was inferred without source confirmation. ## File Organization Recommended layout: ```text knowledge-base/ readme.md index.md agents.md claude.md query-parameters-explanation.md ``` For new research topics, add a focused file at the top level, for example: ```text knowledge-base/entrypoints-and-normalization.md knowledge-base/system-prompt-construction.md knowledge-base/tool-runtime-and-permissions.md ``` Only introduce a subdirectory when a topic has multiple independent files and the top-level index would become hard to scan. ## Update Workflow 1. Read source files first. 2. Write or update the focused topic file. 3. Add or update the topic entry in [index.md](index.md). 4. If the topic changes repository operating rules, update this file or [claude.md](claude.md). 5. If the user-facing HTML report should reflect the finding, update `advanced-site/Claude-Code-Analysis.html`. 6. Run lightweight validation: check links, file existence, and source references. ## Do Not - Do not bury primary notes inside a namespace directory unless explicitly needed. - Do not add unverified claims to the index as final findings. - Do not mix temporary scratch notes with durable knowledge-base entries. - Do not rewrite unrelated files to improve style. - Do not remove user-created files unless the user explicitly asks. ## Agent-Team Role Notes Source base: `/Users/stometa/dev/agent-team/README.md`, `/Users/stometa/dev/agent-team/workspace-context.md`, and every `agents//personality.md` file in `/Users/stometa/dev/agent-team`. ### Core Thesis Agents are role-bound work units, not free-form chat participants. Each role has: - a persona file for identity, goal, touchstone, and identity-level constraints - a skill file for operational rules, triggers, output formats, and platform-level do-not rules - a handoff boundary that keeps work scoped and auditable The README roster lists 10 agents. `workspace-context.md` still says 9-agent team at the top, so treat that as a sync issue to resolve later. ### Role Map | Layer | Agents | Primary Job | |---|---|---| | Direction | CEO, CTO | Set direction, constraints, and technical surface area | | Shaping | PM, Designer, Tech Lead | Convert fuzzy input into PRD, interaction shape, and Tech Spec | | Implementation | Senior Engineer, Junior Engineer, CTO, Tech Lead | Ship verified code through ready PRs | | Review | Senior Engineer, Security & Performance Reviewer, Tech Lead, PM, CEO, Designer, QA | Review correctness, risk, product fit, and behavior | | Research | Researcher | Produce source-grounded memos with explicit confidence | ### Direction Layer - CEO decides what is worth building, when to start, and when to stop. Every decision must state the underlying constraint. - CTO controls technical surface area, build-vs-buy choices, stack conventions, dependencies, and abstractions. ### Shaping Layer - PM turns fuzzy problems into scoped PRDs, decision summaries, and child issues. PM recommends implementation tier but does not assign agents directly. - Designer defines interaction, layout, and review verdicts. Every UI element must have a job. - Tech Lead turns strategy into specs with alternatives, constraints, data model, runtime flow, verification commands, and checkpoints. ### Implementation Layer - Senior Engineer handles complex implementation, cross-module changes, migrations, auth flows, and runtime-critical paths. Senior also reviews every production-code PR. - Junior Engineer handles small, well-scoped changes. Junior reads first, asks second, writes third, and marks uncertainty with `TODO_DECISION:`. - CTO and Tech Lead can act as player-coaches when foundational or blocking work is better demonstrated in code than delegated. ### Review Layer - Senior Engineer reviewer covers general code correctness and production-impacting bugs. - Security & Performance Reviewer covers auth boundaries, input validation, secrets, dependency footprint, concurrency, side channels, query plans, hot-path allocations, blocking calls, complexity, and indexes. - QA tests happy path, expected failure path, and weird path, including Unicode, long input, concurrency, refresh/back, offline, permissions, time edges, prompt injection, token overflow, and provider failure. ### Research Lane Researcher produces primary-source-grounded memos. Every claim needs source identity, section or page, date read, and a confidence label. Thin evidence should produce `inconclusive`, not a forced answer. ### Naming Convention The canonical top-level maintenance files are `agents.md` and `claude.md`. Do not recreate uppercase `.markdown` duplicates as entry points.