apt-mcp-agent-setup 2.0.1 → 3.0.1

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

package/src/templates/windsurfrules.md

@@ -1,214 +1,13 @@
-# AG Kit — Agent Rules
+# APT workspace contract
 
-> This file defines how the AI (Windsurf Cascade) behaves in this workspace.
+At session start and after context recovery, call `session_bootstrap` for this workspace and read `docs/agents/apt-runtime.md` once per context. Read project conventions in `.agents/memory/MEMORY.md`; retrieve only relevant dynamic memory. Report unavailable backends once and use available fallbacks.
 
-## Agent skills
+For new or changed intent, call `route_request` with the target, stack and explicit skills. Use `skill_load` for selected skills and current-step references. Do not load the full trigger catalog or repeat rules on every tool call.
 
-### Support & issues
+Before code changes, bind `pipeline_status` and `pipeline_start` or `pipeline_use` to an explicit task, runId and workspace. Reserve with `pipeline_next`; verify and checkpoint current code before completion. Read-only questions, review and existing tests need no code-change pipeline. Clarify only unresolved decisions.
 
-For bug reports, feature requests, or licensing questions, contact: `info.alphatechs.ai@gmail.com`
+Use at most four actors including the coordinator and one writer per workspace. Respect host permissions, Plan Mode and user stops. Never claim independent review or native enforcement without observed capability. Keep attempts and evidence across resume; do not reset exhausted budgets.
 
-### Issue tracker
+Preserve custom files. Write concise code and prose, run suitable checks, and review staged, unstaged and relevant new files. Publishing, merging and external messages require authorization. Strong caveman style is opt-in.
 
-Issues are tracked in GitLab Issues. See `docs/agents/issue-tracker.md`.
-
-### Triage labels
-
-Default label vocabulary (needs-triage, needs-info, ready-for-agent, ready-for-human, wontfix). See `docs/agents/triage-labels.md`.
-
-### Domain docs
-
-Single-context layout — one `CONTEXT.md` + `docs/adr/` at the repo root. See `docs/agents/domain.md`.
-
----
-
-## ⛔ CRITICAL: apt-mcp-agent TOOL USAGE (P0 — READ FIRST)
-
-**You have `apt-mcp-agent` MCP tools available. You MUST use them:**
-- **Before ANY code search**: use `explore_code` or `code_search` — NOT grep_search for code symbols
-- **Before executable changes**: call `pipeline_status`, then `pipeline_start` or `pipeline_use`
-- **After each pipeline step**: call `pipeline_checkpoint` with required `task` and `runId`
-- **Session start**: call `read_knowledge` + `pipeline_status`
-
-Ignoring these tools and using only built-in IDE tools is a **P0 protocol violation**.
-
-## Session Start Protocol (MANDATORY)
-
-At the start of every session:
-1. Read `.agents/ARCHITECTURE.md` to understand Agents, Skills, and Scripts.
-2. Read `.agents/memory/MEMORY.md` to load persistent project conventions, user preferences, and tech decisions.
-3. Read `docs/agents/mcp-tools.md` to load MCP tool selection rules & memory conventions.
-4. Call `read_knowledge` to load dynamic knowledge graph from memory.
-5. **Read `.agents/skill-triggers.json` to load auto-routing rules for all skills/workflows/tools.**
-
-### 🔄 Context Recovery (MANDATORY after any context truncation/compression)
-If your conversation context was truncated, compressed, or you are resuming after a checkpoint:
-1. **Call `pipeline_status()` immediately** — it returns recovery instructions and tool reminders
-2. Re-read the session start files above if not already in context
-3. Classify the current user request before taking any code action
-
-### ⚠️ MCP TOOL ACCESSIBILITY & FALLBACK WARNING (CRITICAL)
-If the specialized MCP tool `code_search` or other core MCP tools (e.g., `recall`, `remember`, `impact_analysis`) are not in your available tools list:
-- **DO NOT silently fall back to basic text search or skip debugging workflows.**
-- **STOP immediately, warn the user** that the `apt-mcp-agent` server did not start successfully or has been disabled in the IDE settings, and recommend they run `npx apt-mcp-agent-setup status` to check their setup.
-- Only proceed with fallback tools (e.g. `grep_search`) if the user explicitly approves it.
-
-### 🛠️ ENFORCED DEVELOPER PIPELINES (MANDATORY — MCP TOOL GATE)
-
-Before writing any code or implementing features, you MUST follow one of the three enforced pipelines below.
-**Start or bind a run with `pipeline_start(pipeline, task, workspace)` or `pipeline_use(task, runId)`.**
-**After each step call `pipeline_checkpoint(task, runId, step, status="completed", summary)`.**
-
-Content-only documentation changes that do not affect executable behavior are exempt from PRD, issue, and TDD pipeline steps. Agent contracts such as `AGENTS.md`, `SKILL.md`, trigger maps, pipeline definitions, and runtime configuration are operational and are not exempt.
-Skipping steps or executing out-of-order is a **P0 protocol violation** — the tool will REJECT invalid transitions.
-
-#### 🚀 Feature Development Pipeline (5 steps — NO EXCEPTIONS, NO SKIP)
-```
-/grill-me → /to-prd → /to-issues → /tdd → /improve-codebase-architecture
-```
-1. **`/grill-me`** → Stress-test the plan/design with relentless Socratic questions. Challenge edge cases, security, performance.
-2. **`/to-prd`** → Synthesize the grill-me session and conversation context into a formal PRD document.
-3. **`/to-issues`** → Break PRD into vertical-slice issues on the issue tracker. Create `{task-slug}.md` for tracking.
-4. **`/tdd`** → Implement code test-first using RED-GREEN-REFACTOR cycle.
-5. **`/improve-codebase-architecture`** → Review and deepen architecture. Generate HTML report + grill-me session on codebase quality.
-
-#### 🐛 Bug Fix Pipeline (5 steps — NO EXCEPTIONS, NO SKIP)
-```
-/diagnose → /grill-me → /to-prd → /to-issues → /tdd
-```
-1. **`/diagnose`** → Build feedback loop: reproduce → minimize → hypothesize → fix.
-2. **`/grill-me`** → Challenge the fix design. Stress-test the proposed solution.
-3. **`/to-prd`** → Document the fix as a formal PRD with root cause analysis.
-4. **`/to-issues`** → Create tracking issues for the fix and any follow-up work.
-5. **`/tdd`** → Write regression tests first, then implement the fix.
-
-#### 🔧 Hotfix Pipeline (2 steps — for small, isolated changes ≤3 files)
-```
-/verify-scope → /fix-and-test
-```
-1. **`/verify-scope`** → Confirm change is small (≤3 files, no new API, no dependency changes). Provide scope justification in summary.
-2. **`/fix-and-test`** → Apply fix + write regression test if applicable.
-
-**When to use hotfix:** typos, config values, minor CSS, off-by-one errors, missing imports, small bug fixes with obvious root cause. If the change grows beyond scope, reset and escalate to `bugfix` or `feature` pipeline.
-
-**ENFORCEMENT PROTOCOL:**
-- After each step completion → call `pipeline_checkpoint(task, runId, step, "completed", summary)`
-- Before each step start → call `pipeline_status(task, runId)`
-- To cancel a run → call `pipeline_reset(task, runId, confirm=true)`; history is preserved
-- The MCP tool enforces ordering at runtime — out-of-order calls are **rejected with error**
-
-
----
-
-## MCP Tool Selection
-
-| Situation | Use Tool | NOT | Why |
-|---|---|---|---|
-| 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 |
-| Explore file structure & dependencies | `explore_code` | `list_dir` | Understands imports, exports, relationships |
-| Search in config/docs (YAML, JSON, .env, markdown) | `grep_search` | `code_search` | Non-code files, literal string match |
-| "What breaks if I change this?" | `impact_analysis` | — | Blast radius — always update index first |
-| Save a decision/bug-fix/convention | `remember` | — | Cross-session persistence |
-| Recall what was decided about X | `recall` | — | Search by keyword |
-| Load full knowledge graph | `read_knowledge` | — | Session start, get full context |
-
-**Rule: DEFAULT to `code_search` for code. Fall back to `grep_search` ONLY for non-code files or literal strings.**
-
----
-
-## Auto-Trigger Skills (MANDATORY)
-
-### Workflow Skills
-
-| Skill | Trigger Conditions | Agent Action |
-|---|---|---|
-| `spec-clarification` | Design decision, architecture choice, plan review | Load SKILL.md → Start alignment session |
-| `bug-diagnostics` | Bug report, error log, "fails", "crashes" | Load SKILL.md → Reproduce → minimise → hypothesise → fix |
-| `task-breakdown` | Plan/PRD completed, "break down", "create tickets" | Load SKILL.md → Convert plan to vertical-slice issues |
-| `prd-gen` | New feature/product description with enough context | Load SKILL.md → Extract PRD from conversation context |
-| `prototype` | "mockup", "explore options", unclear UI/logic | Load SKILL.md → Build throwaway prototype |
-| `tdd-loop` | Feature implementation, bug fix, "write tests" | Load SKILL.md → Apply RED-GREEN-REFACTOR loop |
-
-### UI/UX Design Skills
-
-| Skill | Trigger Conditions | Agent Action |
-|---|---|---|
-| `ui-style-rules` | Any web UI task: page layout, component styling | Load SKILL.md → Apply anti-slop design rules |
-| `web-mockup-gen` | Web UI concept needed before coding | Load SKILL.md → Generate web design reference images |
-| `mobile-mockup-gen` | Mobile UI concept needed before coding | Load SKILL.md → Generate mobile screen mockups |
-| `mobile-rules` | Any mobile UI implementation: Flutter, touch interaction | Load SKILL.md → Apply platform conventions |
-| `stitch-design-flow` | "stitch", "tạo trên stitch", "/stitch-flow", design UI (khi stitch preset active) | Load SKILL.md → Collaborative 8-step Stitch design flow |
-| `figma-handoff` | Figma URL detected (`figma.com/...`), "figma", "/figma", "code theo Figma" (khi figma preset active) | Load SKILL.md → Extract design → generate code |
-| `design-to-code` | "code theo design", "pull code", "/design-to-code", design-to-code conversion | Load SKILL.md → Auto-detect input → route to correct design tool |
-| `flutter-fix-layout-issues` | "overflow", "unbounded height", `RenderFlex`, layout error | Load SKILL.md → Fix overflow/constraint issues |
-| `flutter-build-responsive-layout` | "responsive", "tablet", "media query", adaptive layout | Load SKILL.md → Build adaptive layout |
-| `flutter-setup-declarative-routing` | "routing", "deep link", "go_router", URL navigation | Load SKILL.md → Configure declarative routing |
-| `flutter-add-widget-test` | "widget test", "test component", "verify UI rendering" | Load SKILL.md → Write widget test |
-| `flutter-add-integration-test` | "integration test", "e2e", "Flutter Driver" | Load SKILL.md → Add integration test |
-| `flutter-implement-json-serialization` | "fromJson", "toJson", "model class", API mapping | Load SKILL.md → Create JSON serialization |
-| `flutter-setup-localization` | "localization", "i18n", "intl", ".arb" | Load SKILL.md → Setup l10n |
-| `flutter-apply-architecture-best-practices` | "architecture", "layer", project structure | Load SKILL.md → Apply layered architecture |
-| `flutter-add-widget-preview` | "preview", "widget catalog", "golden test" | Load SKILL.md → Add widget preview |
-| `flutter-use-http-package` | "http request", "REST API", "fetch data" | Load SKILL.md → Use http package |
-
-### BA/QC Skills — auto-trigger for requirements and testing:
-
-| Skill | Trigger Conditions | Agent Action |
-|---|---|---|
-| `ba-urd-decomposer` | "URD", "phân rã URD", "feature list", .pdf (BA context) | Load SKILL.md → Parse URD → feature list |
-| `ba-clarification-session` | "làm rõ yêu cầu", "clarify", "hỏi PO" | Load SKILL.md → Generate Q&A questions |
-| `ba-specs-writer` | "viết specs", "đặc tả", "tạo specs", "PTTK" | Load SKILL.md → Generate Specs document |
-| `ba-feature-tracker` | "tiến độ BA", "feature tracker", "BA progress" | Load SKILL.md → Show BA dashboard |
-| `ba-requirements-generator` | "BRD", "user story", "sinh BRD", "tạo BRD" | Load SKILL.md → Generate BRD/User Story |
-| `pdf-specs-parser` | "parse PDF specs", "đọc PTTK", .pdf (specs context) | Load SKILL.md → Extract API/UI definitions |
-| `qc-template-parser` | "mẫu QC", "import QC template", .xlsx (QC context) | Load SKILL.md → Learn Excel template |
-| `qc-bidv-workflow` | "tạo testcase BIDV", "QC workflow" | Load SKILL.md → Run BIDV QC pipeline |
-| `testcase-generator` | "sinh test case", "generate TCs", "tạo testcase" | Load SKILL.md → Generate Excel testcase |
-| `mindmap-reader` | "mindmap", "xmind", .xmind/.mm file | Load SKILL.md → Parse mindmap → JSON |
-| `specs-to-mindmap` | "specs sang mindmap", "tạo outline từ specs" | Load SKILL.md → Specs → outline |
-| `requirement-coverage` | "bao phủ yêu cầu", "traceability", "coverage" | Load SKILL.md → Requirements vs test cases |
-| `webapp-testing` | "E2E test", "Playwright", "test trình duyệt" | Load SKILL.md → E2E/Playwright audit |
-
-### ⚠️ DOMAIN SKILL LOADING (CRITICAL — DO NOT SKIP)
-
-Before writing ANY UI, design, or visual code:
-1. **Web UI** → READ `.agents/skills/ui-style-rules/SKILL.md` — MANDATORY
-2. **Mobile UI** → READ `.agents/skills/mobile-rules/SKILL.md` — MANDATORY
-3. **Image/asset gen (web)** → READ `.agents/skills/web-mockup-gen/SKILL.md`
-4. **Image/asset gen (mobile)** → READ `.agents/skills/mobile-mockup-gen/SKILL.md`
-5. **Architecture decision** → READ `.agents/skills/stress-test-plan/SKILL.md`
-
-**Violation = SLOP output. Writing UI code without design skill = P0 violation.**
-
-## Socratic Gate
-
-Every user request must pass through the Socratic Gate before ANY implementation:
-
-| Request Type | Strategy | Required Action |
-|---|---|---|
-| **New Feature / Build** | Deep Discovery | ASK minimum 3 strategic questions |
-| **Code Edit / Bug Fix** | Context Check | Confirm understanding + ask impact questions |
-| **Vague / Simple** | Clarification | Ask Purpose, Users, and Scope |
-
-> [!IMPORTANT]
-> **STRICT SOCRATIC & WORKFLOW ENFORCEMENT:**
-> - **DO NOT write any code logic, execute modifications, or create plans before completing the required Socratic Gate action.** Bypassing the Socratic Gate is a P0 protocol violation.
-> - **DO NOT bypass specialized workflow skills** (like `bug-diagnostics` for debugging, `spec-clarification` for specifications, `tdd-loop` for writing code/tests) even if the task or error log seems simple or clear. Bypassing skills is a P0 protocol violation.
-
----
-
-## Universal Rules
-
-### Clean Code (Global Mandatory)
-- **Code**: Concise, direct, no over-engineering. Self-documenting.
-- **Laziness Ladder**: Before writing code, stop at the first rung that holds: YAGNI → Reuse existing → Stdlib → Native platform → Installed dep → One-liner → Minimum viable. The ladder runs AFTER understanding the problem.
-- **Bug Fix**: Root cause, not symptom. Grep every caller, fix the shared function once.
-- **No Bloat**: No unrequested abstractions, no scaffolding "for later", deletion > addition, fewest files.
-- **Testing**: Mandatory. Pyramid (Unit > Int > E2E) + AAA Pattern.
-- **Performance**: Measure first. Adhere to current Core Web Vitals standards.
-
-### Quick Reference
-- **Masters**: `orchestrator`, `project-planner`, `security-auditor`, `backend-specialist`, `frontend-specialist`, `mobile-developer`, `debugger`
-- **Key Skills**: `clean-code`, `brainstorming`, `ui-style-rules`, `mobile-rules`, `web-mockup-gen`, `mobile-mockup-gen`, `stitch-design-flow`, `bug-diagnostics`, `tdd-loop`, `spec-clarification`, `prd-gen`, `task-breakdown`, `prototype`, `stress-test-plan`, `skill-generator`, `git-safety-guardrails`, `git-hook-setup`, `test-type-migration`, `exercise-scaffold`, `interactive-teaching`, `writing-flow`, `raw-idea-collector`, `draft-shaper`, `project-config-wizard`, `skill-writing-guide`, `architecture-rules`, `solution-decision-map`, `task-implementation`, `git-conflict-resolver`, `workflow-navigator`, `terse-communication`, `session-handoff`
+Tool interfaces: `docs/agents/mcp-tools.md`. Project/domain and issue conventions: `docs/agents/domain.md` and `docs/agents/issue-tracker.md`. Support: info.alphatechs.ai@gmail.com.