apt-mcp-agent-setup 2.0.1 → 3.0.0

package/src/templates/mcp-tools.md

@@ -1,175 +1,176 @@
-# MCP Tools — Decision Tree & Conventions
-
-## Developer pipeline 2.0
-
-- Start: `pipeline_start(pipeline, task, workspace)` with a canonical lowercase task ID.
-- Resume: `pipeline_use(task, runId)` binds the MCP session and project-scoped backends to the run workspace.
-- Progress: `pipeline_checkpoint(task, runId, step, status="completed", summary)` only accepts the next step.
-- Inspect: `pipeline_status()` lists current runs; task and runId inspect one run without rebinding.
-- Cancel: `pipeline_reset(task, runId, confirm=true)` preserves state and ledger history.
-- Finish: `pipeline_prepare_merge(task, runId)` never merges, pushes, publishes, or deletes a branch.
-
-Git projects share pipeline state through the Git common directory. Non-Git projects use `.agents/pipelines` and can run in place. Git bootstrap for a managed worktree always requires a read-only preview and direct user confirmation.
-
-Pipeline enforcement covers proxied MCP tools only. Native host shell and file tools must follow the returned `workspacePath` explicitly.
-
-## 🔍 Tool Selection — When to Use What
-
-### Code Search & Navigation
-
-| Situation | Use Tool | NOT | Why |
-|---|---|---|---|
-| Explore file structure & dependencies | `explore_code` | `list_dir` | **PRIMARY TOOL — call FIRST for any code question or before edit** |
-| Find symbol definition, function, class | `code_search` | `grep_search` | Semantic search, understands code structure |
-| Find all callers of a function | `find_callers` | `grep_search` | Follows call graph, not just text match |
-| Find all functions called by a function | `find_callees` | — | Call graph traversal |
-| List files matching a pattern | `list_code_files` | `list_dir` | Faster, code-aware filtering |
-| Search in config files (YAML, JSON, .env) | `grep_search` | `code_search` | Non-code files, literal string match |
-| Search in markdown, docs, comments | `grep_search` | `code_search` | Plain text, not code symbols |
-| Search for exact string literal in code | `grep_search` | `code_search` | Literal match (error messages, magic strings) |
-
-**Rule: explore_code FIRST. grep_search ONLY non-code. No grep loops.**
-
-### Impact Analysis
-
-| Situation | Use Tool | Why |
-|---|---|---|
-| "What breaks if I change this function?" | `impact_analysis` | Blast radius — shows all affected files/functions |
-| Before refactoring a shared module | `impact_analysis` | Prevent unintended side effects |
-| Code review — assessing risk of a PR | `impact_analysis` | Quantify change scope |
-| Simple "where is this used?" | `find_callers` | Lighter weight than full impact analysis |
-
-### Persistent Knowledge
-
-| Situation | Use Tool | Why |
-|---|---|---|
-| Save a decision made this session | `remember` | Cross-session persistence |
-| Save a bug fix (root cause + solution) | `remember` | Future reference when similar bug appears |
-| Recall what was decided about X | `recall` | Search by keyword |
-| Load full knowledge graph | `read_knowledge` | Session start, get full context |
-| Connect two related concepts | `link_knowledge` | Build relationship graph |
-| Remove outdated information | `forget` | Keep knowledge graph clean |
-
----
-
-## 🧠 Memory Auto-Save Protocol (MANDATORY)
-
-Agent MUST auto-call `remember` in these situations — do NOT wait for user to ask:
-
-| Trigger | What to Save |
-|---|---|
-| After completing pipeline step `grill-me` | Design decisions + constraints discussed |
-| After completing pipeline step `diagnose` | Root cause + reproduction steps |
-| After completing pipeline step `tdd` | Implementation decisions + test patterns |
-| After completing pipeline step `improve-architecture` | Architecture improvements + quality findings |
-| User states a preference or convention | What they prefer + context |
-| Non-trivial bug resolved | Root cause, solution, affected files |
-
-**Pipeline checkpoint responses include `memory_action` field — follow it immediately.**
-
-### Google Drive & Online Documents
-
-| Situation | Use Tool | Why |
-|---|---|---|
-| Search files on project Drive | `gdrive-search` | Find specs, testcases, sheets |
-| List files inside folder | `gdrive-list-folder` | Browse project folder structure |
-| Upload specs/testcase (xlsx/docx) | `gdrive-upload-file` | Set `convertToGoogleFormat: true` to auto-convert to Sheets/Docs |
-| Update specific row/cell in Sheets | `gdrive-update-sheet-cell` | Modify cells for real-time QC collaboration |
-| Share sheet/doc with bank stakeholder | `gdrive-share-file` | Invite collaborators (editor/viewer) |
-
----
-
-## 🔄 Index Management — When to Rebuild
-
-### code_search index (auto-managed)
-
-| Event | Action | Notes |
-|---|---|---|
-| Files changed on disk | **Auto-update** (file watcher) | No manual action needed |
-| Large refactor (50+ files) | Agent runs `code_search` after changes | Index catches up automatically |
-| New project setup | **Auto-index** on first query | May be slow first time |
-
-**Rule: NEVER ask the user to rebuild the code search index. It auto-manages.**
-
-### impact_analysis index (MANUAL update required)
-
-| Event | Action Required |
-|---|---|
-| Before ANY impact analysis query | Agent MUST run index update first |
-| After committing changes (git) | Agent MUST run index update before next query |
-| User manages git manually (SourceTree, etc.) | Agent auto-runs update, NEVER asks user |
-
-**Rule: ALWAYS update impact_analysis index before querying. Do it silently — never ask the user.**
-
-Before calling `impact_analysis`:
-1. Run index update (silent, no user prompt)
-2. Wait for completion
-3. Then execute the impact query
-
----
-
-## 🪜 Code Writing — Laziness Ladder
-
-Before writing ANY code, stop at the **first rung** that holds:
-
-| Rung | Check | Tool to Use | If Yes → |
-|---|---|---|---|
-| 1. YAGNI | Does this need to exist? | Think first | Skip it, explain why in one line |
-| 2. Reuse | Already in codebase? | `explore_code` | Reuse existing helper/util/pattern |
-| 3. Stdlib | Standard library does it? | Language docs | Use stdlib |
-| 4. Platform | Native platform feature? | — | Use it (CSS > JS, `<input type="date">` > picker lib, DB constraint > app code) |
-| 5. Installed dep | Already-installed dependency? | `explore_code` on package.json/pubspec | Use existing dep. No new deps for what a few lines do |
-| 6. One-liner | Can it be one line? | — | One line |
-| 7. Minimum | Only when above fail | — | Write minimum code that works |
-
-**Rule: The ladder runs AFTER understanding the problem. Read the code it touches (`explore_code`), trace the real flow, THEN climb.**
-
-**Bug fix rule: Root cause, not symptom.** Grep every caller (`find_callers`), fix the shared function once — not each caller path.
-
----
-
-## 🧠 Memory Conventions — When to Save & Read
-
-### When to SAVE (`remember`)
-
-| Trigger | Entity Type | What to Save |
-|---|---|---|
-| Resolved a non-trivial bug | `bug-fix` | Root cause, solution, affected files, how to detect similar |
-| Made an architecture/design decision | `decision` | What was decided, alternatives considered, rationale |
-| Completed a feature milestone | `feature` | What was built, key files, design choices |
-| Discovered a workflow/convention | `convention` | The pattern, why it exists, when to apply it |
-| User stated a preference | `preference` | What they prefer, context |
-| Completed project setup | `setup` | What was configured, tool versions, settings |
-
-**Save format:**
-```
-Entity: [descriptive-name]
-Type: [bug-fix | decision | feature | convention | preference | setup]
-Content: [structured description]
-Tags: [relevant, searchable, keywords]
-```
-
-### When to READ (`recall` / `read_knowledge`)
-
-| Trigger | Action | Tool |
-|---|---|---|
-| **Session start** | Load full knowledge graph | `read_knowledge` |
-| Before investigating known-problematic areas | Search for related bug-fixes | `recall` with keywords |
-| Before making design decisions | Search for prior decisions on same topic | `recall` with topic |
-| Before touching a module with history | Search for conventions/gotchas | `recall` with module name |
-| User asks "what did we decide about X?" | Search explicitly | `recall` with X |
-
-### Memory Architecture (2-tier)
-
-| Source | Purpose | Mutability | Location |
-|---|---|---|---|
-| `.agents/memory/MEMORY.md` | Static conventions, user preferences, coding standards | Manual edit only | Project repo |
-| `.memory/memory.jsonl` | Dynamic project knowledge graph | Agent read/write via MCP tools | Project root (gitignored) |
-
-**Rule: NEVER save to `.agents/memory/MEMORY.md` via MCP tools. That file is manually curated. MCP `remember`/`recall` always targets `.memory/memory.jsonl`.**
-
-### Memory Isolation
-
-- Each project has its own `.memory/memory.jsonl` (configured via `.mcp.json`)
-- Global fallback: `~/.anhdh/memory/global.json` (neutral, for cross-project knowledge)
-- `.mcp.json` per project overrides global config → no data leakage between projects
+# MCP Tools — Decision Tree & Conventions
+
+## Runtime and pipelines
+
+- Bootstrap: `session_bootstrap(sessionId, contextEpoch, host, capabilities)` identifies this context and reports resumable work.
+- Route: `route_request(sessionId, requestId, prompt, target, stack, explicitSkills)` returns the workflow and companion skills. Load them using `skill_load` only when needed.
+- Start: `pipeline_start(pipeline, task, workspace, acceptanceCriteria, scope, sessionId)` creates a versioned run. Use `pipeline_use(task, runId)` to resume the same run.
+- Execute: `pipeline_next(task, runId, sessionId, role, requestId)` reserves an attempt. Native host agents perform the work; the coordinator controls transitions.
+- Verify: `pipeline_verify` records authorized argv execution under the run workspace. `pipeline_checkpoint` references evidence IDs for completion and supports report, pause, resume, release and criteria actions.
+- Inspect: `pipeline_status` is read-only and does not bind sessions. `pipeline_reset` cancels without deleting history. `pipeline_prepare_merge` only prepares a report.
+- Read-only questions, review and existing test execution do not require a mutation pipeline. Scope-limited changes use the short pipeline; increased risk adds required checks.
+- MCP gates cover proxied calls. Native tool gates and continuation require observed host hooks. Plan Mode and user interruption take precedence.
+- Codegraph failures permit file-search fallback. The proxy refreshes the review graph before impact analysis; it must report failure rather than use stale results.
+- `mcp_agent_health` reports process, initialization and functional readiness separately. `npx apt-mcp-agent-setup doctor` performs read-only configuration inspection.
+
+
+## 🔍 Tool Selection — When to Use What
+
+### Code Search & Navigation
+
+| Situation | Use Tool | NOT | Why |
+|---|---|---|---|
+| Explore file structure & dependencies | `explore_code` | `list_dir` | **PRIMARY TOOL — call FIRST for any code question or before edit** |
+| Find symbol definition, function, class | `code_search` | `grep_search` | Semantic search, understands code structure |
+| Find all callers of a function | `find_callers` | `grep_search` | Follows call graph, not just text match |
+| Find all functions called by a function | `find_callees` | — | Call graph traversal |
+| List files matching a pattern | `list_code_files` | `list_dir` | Faster, code-aware filtering |
+| Search in config files (YAML, JSON, .env) | `grep_search` | `code_search` | Non-code files, literal string match |
+| Search in markdown, docs, comments | `grep_search` | `code_search` | Plain text, not code symbols |
+| Search for exact string literal in code | `grep_search` | `code_search` | Literal match (error messages, magic strings) |
+
+**Rule: explore_code FIRST. grep_search ONLY non-code. No grep loops.**
+
+### Impact Analysis
+
+| Situation | Use Tool | Why |
+|---|---|---|
+| "What breaks if I change this function?" | `impact_analysis` | Blast radius — shows all affected files/functions |
+| Before refactoring a shared module | `impact_analysis` | Prevent unintended side effects |
+| Code review — assessing risk of a PR | `impact_analysis` | Quantify change scope |
+| Simple "where is this used?" | `find_callers` | Lighter weight than full impact analysis |
+
+### Persistent Knowledge
+
+| Situation | Use Tool | Why |
+|---|---|---|
+| Save a decision made this session | `remember` | Cross-session persistence |
+| Save a bug fix (root cause + solution) | `remember` | Future reference when similar bug appears |
+| Recall what was decided about X | `recall` | Search by keyword |
+| Load relevant task knowledge | `recall` | Explicit whole-graph inspection; prefer relevant recall during bootstrap |
+| Connect two related concepts | `link_knowledge` | Build relationship graph |
+| Remove outdated information | `forget` | Keep knowledge graph clean |
+
+---
+
+## 🧠 Memory Auto-Save Protocol (MANDATORY)
+
+Agent MUST auto-call `remember` in these situations — do NOT wait for user to ask:
+
+| Trigger | What to Save |
+|---|---|
+| After completing pipeline step `grill-me` | Design decisions + constraints discussed |
+| After completing pipeline step `diagnose` | Root cause + reproduction steps |
+| After completing pipeline step `tdd` | Implementation decisions + test patterns |
+| After completing pipeline step `improve-architecture` | Architecture improvements + quality findings |
+| User states a preference or convention | What they prefer + context |
+| Non-trivial bug resolved | Root cause, solution, affected files |
+
+**Pipeline checkpoint responses include `memory_action` field — follow it immediately.**
+
+### Google Drive & Online Documents
+
+| Situation | Use Tool | Why |
+|---|---|---|
+| Search files on project Drive | `gdrive-search` | Find specs, testcases, sheets |
+| List files inside folder | `gdrive-list-folder` | Browse project folder structure |
+| Upload specs/testcase (xlsx/docx) | `gdrive-upload-file` | Set `convertToGoogleFormat: true` to auto-convert to Sheets/Docs |
+| Update specific row/cell in Sheets | `gdrive-update-sheet-cell` | Modify cells for real-time QC collaboration |
+| Share sheet/doc with bank stakeholder | `gdrive-share-file` | Invite collaborators (editor/viewer) |
+
+---
+
+## 🔄 Index Management — When to Rebuild
+
+### code_search index (auto-managed)
+
+| Event | Action | Notes |
+|---|---|---|
+| Files changed on disk | **Auto-update** (file watcher) | No manual action needed |
+| Large refactor (50+ files) | Agent runs `code_search` after changes | Index catches up automatically |
+| New project setup | **Auto-index** on first query | May be slow first time |
+
+**Rule: NEVER ask the user to rebuild the code search index. It auto-manages.**
+
+### impact_analysis index (MANUAL update required)
+
+| Event | Action Required |
+|---|---|
+| Before ANY impact analysis query | Agent MUST run index update first |
+| After committing changes (git) | Agent MUST run index update before next query |
+| User manages git manually (SourceTree, etc.) | Agent auto-runs update, NEVER asks user |
+
+**Rule: ALWAYS update impact_analysis index before querying. Do it silently — never ask the user.**
+
+Before calling `impact_analysis`:
+1. Run index update (silent, no user prompt)
+2. Wait for completion
+3. Then execute the impact query
+
+---
+
+## 🪜 Code Writing — Laziness Ladder
+
+Before writing ANY code, stop at the **first rung** that holds:
+
+| Rung | Check | Tool to Use | If Yes → |
+|---|---|---|---|
+| 1. YAGNI | Does this need to exist? | Think first | Skip it, explain why in one line |
+| 2. Reuse | Already in codebase? | `explore_code` | Reuse existing helper/util/pattern |
+| 3. Stdlib | Standard library does it? | Language docs | Use stdlib |
+| 4. Platform | Native platform feature? | — | Use it (CSS > JS, `<input type="date">` > picker lib, DB constraint > app code) |
+| 5. Installed dep | Already-installed dependency? | `explore_code` on package.json/pubspec | Use existing dep. No new deps for what a few lines do |
+| 6. One-liner | Can it be one line? | — | One line |
+| 7. Minimum | Only when above fail | — | Write minimum code that works |
+
+**Rule: The ladder runs AFTER understanding the problem. Read the code it touches (`explore_code`), trace the real flow, THEN climb.**
+
+**Bug fix rule: Root cause, not symptom.** Grep every caller (`find_callers`), fix the shared function once — not each caller path.
+
+---
+
+## 🧠 Memory Conventions — When to Save & Read
+
+### When to SAVE (`remember`)
+
+| Trigger | Entity Type | What to Save |
+|---|---|---|
+| Resolved a non-trivial bug | `bug-fix` | Root cause, solution, affected files, how to detect similar |
+| Made an architecture/design decision | `decision` | What was decided, alternatives considered, rationale |
+| Completed a feature milestone | `feature` | What was built, key files, design choices |
+| Discovered a workflow/convention | `convention` | The pattern, why it exists, when to apply it |
+| User stated a preference | `preference` | What they prefer, context |
+| Completed project setup | `setup` | What was configured, tool versions, settings |
+
+**Save format:**
+```
+Entity: [descriptive-name]
+Type: [bug-fix | decision | feature | convention | preference | setup]
+Content: [structured description]
+Tags: [relevant, searchable, keywords]
+```
+
+### When to READ (`recall` / `read_knowledge`)
+
+| Trigger | Action | Tool |
+|---|---|---|
+| **Session start** | Load relevant task knowledge | `recall` |
+| Before investigating known-problematic areas | Search for related bug-fixes | `recall` with keywords |
+| Before making design decisions | Search for prior decisions on same topic | `recall` with topic |
+| Before touching a module with history | Search for conventions/gotchas | `recall` with module name |
+| User asks "what did we decide about X?" | Search explicitly | `recall` with X |
+
+### Memory Architecture (2-tier)
+
+| Source | Purpose | Mutability | Location |
+|---|---|---|---|
+| `.agents/memory/MEMORY.md` | Static conventions, user preferences, coding standards | Manual edit only | Project repo |
+| `.memory/memory.jsonl` | Dynamic project knowledge graph | Agent read/write via MCP tools | Project root (gitignored) |
+
+**Rule: NEVER save to `.agents/memory/MEMORY.md` via MCP tools. That file is manually curated. MCP `remember`/`recall` always targets `.memory/memory.jsonl`.**
+
+### Memory Isolation
+
+- Each project has its own `.memory/memory.jsonl` (configured via `.mcp.json`)
+- Global fallback: `~/.anhdh/memory/global.json` (neutral, for cross-project knowledge)
+- `.mcp.json` per project overrides global config → no data leakage between projects