YAAA

Imported from Yet-Another-AI-Agent/YAAA (AGENTS.md). Install upstream with npx skills add Yet-Another-AI-Agent/YAAA. Copyright stays with the author.

MCP Tools: code-review-graph

IMPORTANT: This project has a knowledge graph. ALWAYS use the code-review-graph MCP tools BEFORE using Grep/Glob/Read to explore the codebase. The graph is faster, cheaper (fewer tokens), and gives you structural context (callers, dependents, test coverage) that file scanning cannot.

When to use graph tools FIRST

• Exploring code: semantic_search_nodes or query_graph instead of Grep
• Understanding impact: get_impact_radius instead of manually tracing imports
• Code review: detect_changes + get_review_context instead of reading entire files
• Finding relationships: query_graph with callers_of/callees_of/imports_of/tests_for
• Architecture questions: get_architecture_overview + list_communities

Fall back to Grep/Glob/Read only when the graph doesn't cover what you need.

Key Tools

Workflow

1. The graph auto-updates on file changes (via hooks).
2. Use detect_changes for code review.
3. Use get_affected_flows to understand impact.
4. Use query_graph pattern="tests_for" to check coverage.

Imported Claude Cowork project instructions

YAAA agent workspace protocol

This section is the authoritative operating contract for every worker, verifier, researcher, and replacement agent. It is intentionally generic: the task prompt and live workspace determine the actual deliverables. Do not infer additional files, phases, permissions, or requirements from a familiar task shape.

1. Startup: establish the source of truth

At startup, use this order of authority:

1. The current agent prompt and execution contract.
2. An explicitly supplied live workspace inventory or artifact mapping.
3. An explicitly supplied predecessor handoff.
4. Files discovered with workspace tools.
5. General project conventions, only when the task explicitly invokes them.

The prompt is already the assignment context. Starting an agent does not imply that any support documents exist. Never search for or invent conventional files such as assignment.md, context.md, README.md, instructions.md, skills-description.md, or a root-level handOff.md.

Before the first mutation, confirm from the prompt:

• the mission objective and current subtask;
• required output files and their exact names and case;
• acceptance criteria and required evidence;
• allowed capabilities, tools, languages, and read/write scope;
• whether the role is a producer, verifier, researcher, or coordinator;
• whether a predecessor handoff is actually provided.

If any of these are absent, use the available discovery or reporting tool. Do not manufacture a missing requirement and do not restart merely to obtain a document that was never supplied.

2. Assignment and handoff filenames

When these files are actually present in a task workspace, their names are case-sensitive:

• handsOn.md is the orchestrator-authored assignment/instructions artifact.
• handOff.md is the agent-produced completion or blocker artifact.

The usual agent-scoped locations are:

• agent-workspaces/<agent-id>/handsOn.md
• agent-workspaces/<agent-id>/handOff.md

Use an exact path supplied by YAAA or returned by a tool. A new agent reads its own handsOn.md only if that path exists or is explicitly supplied. A new agent does not read a predecessor handoff unless the orchestrator supplies the predecessor's exact path or the live inventory shows it. A worker creates or updates only its own agent-workspaces/<agent-id>/handOff.md when stopping.

Never substitute one of these files with README.md, instructions.md, assignment.md, or a same-named file in another agent directory.

3. Skills and technical documentation

Skill documentation is not part of the workspace. When a selected skill is provided, read it through the native read_skill tool using the supplied skill id. Do not use read_file, search_files, shell commands, or guessed paths to look for skill documentation. Do not invent skills-description.md.

Complete required skill preflight before using a tool governed by that skill. Follow the selected skill's scope, safety rules, templates, and verification requirements. If the native skill reader is unavailable, report the capability gap; do not simulate it by searching the task workspace.

4. Path resolution and discovery

Treat every planner path, handoff path, filename mentioned by a model, and relative path from an earlier attempt as a claim until confirmed against the live workspace.

• Relative paths resolve from the task workspace, not the repository root, process working directory, or another agent's workspace.
• A path is valid only after it is supplied by the prompt, returned by a tool, present in the live inventory, or confirmed with path_metadata.
• Before reading an unconfirmed path, use list_files, search_files, or path_metadata. Prefer exact case-sensitive matches.
• Resolve basename and suffix matches carefully. If multiple files match, stop and report ambiguity rather than choosing arbitrarily.
• Do not create a missing parent directory or alternate path merely to make a guessed filename work.
• Do not silently change case, extension, directory, or language. If the requested path is unavailable, report the mismatch and use the canonical live path only when the mapping is unambiguous.
• Absolute paths may be used only when the task or tool explicitly permits them. Relative deliverable paths remain task-workspace scoped.

The live workspace inventory is authoritative over stale planner claims. A file's existence does not prove that it is the required artifact; compare its path, case, type, content, and acceptance criteria.

5. ENOENT and other read failures

An ENOENT/"no such file" response means the requested path was not found at that resolved location. It is evidence about the path, not evidence that the file should be created.

After the first missing-path response:

1. Stop repeating the same read.
2. Record the exact requested path and the resolved workspace root.
3. Discover the directory or search for the basename using the file tools.
4. Check case, extension, parent directory, and agent-workspace scope.
5. If one canonical match exists, use that exact path and record the mapping.
6. If no match exists, report the missing artifact and continue with available work or ask the orchestrator for clarification.
7. If multiple matches exist, report ambiguity and do not guess.

Never respond to ENOENT by repeatedly retrying, spawning a replacement agent with the same unverified path, creating a placeholder support document, or claiming that the task context is missing when the prompt contains it.

For EPERM, permission, or access-denied errors, preserve the path and report the required capability or permission. Do not work around the error by using sudo, changing ownership, weakening security, or writing outside scope.

6. Reading and inspecting files

Read only the files required by the assignment, the selected skill, the live artifact mapping, or discovered evidence. Prefer targeted reads for large or structured files. Before editing an existing file, inspect the relevant current contents and preserve unrelated user changes.

Do not scan the entire machine, repository, or task history without a stated reason. Do not treat a file's name, extension, planner description, or handoff claim as proof of its contents. Verify the actual file type and content when that distinction matters.

7. Creating and editing artifacts

Use the exact required artifact path. Keep one canonical artifact per required deliverable unless the prompt explicitly requires variants.

• Inspect the live inventory before creating a deliverable.
• A successful full write is completion of creation, not an invitation to regenerate the same path.
• After created or unchanged, continue to the next artifact or verification.
• If a full write returns DUPLICATE_WRITE, do not retry it or repeat the containing batch. Read the current file/range and use a targeted line edit only when a correction is necessary.
• Do not create case-variant duplicates such as foo.js and Foo.js, root and src/ copies, or Python and JavaScript alternatives unless explicitly asked.
• Do not create empty placeholders, speculative helper files, generated binaries, or unrelated documentation to satisfy a guessed requirement.
• Keep implementation language consistent with the assignment. A Node.js task does not receive a parallel Python implementation unless requested.
• Preserve existing files and user changes outside the declared scope.

For binary or structured artifacts, use the task's required skill/tooling and verify that the resulting file is readable, non-empty, and at the required path. For code, run the requested tests or the narrowest meaningful validation and record the command and result.

8. Producers, verifiers, and handoffs

Producer agents create or modify only their assigned deliverables. Verifier agents are read-only unless the prompt explicitly grants a repair role; they must not recreate producer artifacts or “fix” a missing file by writing an alternate copy.

Before handing work to a verifier, ensure the handoff names actual canonical paths and distinguishes:

• completed artifacts;
• missing or ambiguous artifacts;
• commands run and their results;
• limitations, assumptions, and unresolved risks.

The handoff must be concise, factual, and durable. Do not claim completion based only on a write call; include path and validation evidence. If blocked, write the blocker, exact failing operation, attempted discovery, and the next required decision.

9. Subtasks, delegation, and retries

Every delegated subtask must carry its own concrete objective, required artifacts, acceptance criteria, exact known paths, role, and available tools. Do not delegate “continue,” “investigate,” or “read the context” without a deliverable and evidence requirement.

Before starting a replacement agent, incorporate the prior attempt's actual handoff, tool results, and path mapping. A replacement must not repeat an identical failed operation with the same unverified path. Deterministic ENOENT, permission, duplicate-write, protocol, or capability failures require diagnosis or escalation—not blind retries.

When an agent reports no progress, inspect the evidence and failure fingerprint before deciding whether to continue, correct the scope, or stop. Do not spin up multiple agents to compete over the same artifact or repeat the same mutation.

10. Completion and stop conditions

An agent may declare completion only when the required artifacts exist at their canonical paths, acceptance criteria are addressed, and required verification evidence is available. “The model said done” is not sufficient.

An agent must stop and hand off when:

• a required path is missing and discovery finds no canonical match;
• paths are ambiguous or the task contract conflicts;
• required tools, permissions, skills, or inputs are unavailable;
• the same deterministic failure persists after one diagnostic recovery;
• the next action would exceed scope or overwrite user work.

Do not conceal gaps by creating guessed files, changing the requested deliverable name, weakening verification, or handing off an unverified claim.