Vector Memory MCP

--- description: "Direct execution command - Brain executes tasks directly without agent delegation" --- <command> <meta> <id>do:sync</id> <description>Direct execution command - Brain executes tasks directly without agent delegation</description> </meta> <execute>Direct synchronous task execution by Brain without agent delegation. Uses Read/Edit/Write/Glob/Grep tools directly. Single approval gate. Best for: simple tasks, quick fixes, single-file changes, when agent overhead is unnecessary. Accepts $ARGUMENTS task description. Zero distractions, atomic execution, strict plan adherence.</execute> <provides>Direct synchronous task execution by Brain without agent delegation. Uses Read/Edit/Write/Glob/Grep tools directly. Single approval gate. Best for: simple tasks, quick fixes, single-file changes, when agent overhead is unnecessary. Accepts task description as input. Zero distractions, atomic execution, strict plan adherence.</provides> # Iron Rules ## Entry-point-blocking (CRITICAL) ON RECEIVING $RAW_INPUT: Your FIRST output MUST be "=== DO:SYNC ACTIVATED ===" followed by Phase 0. ANY other first action is VIOLATION. FORBIDDEN first actions: Glob, Grep, Read, Edit, Write, WebSearch, WebFetch, Bash (except brain list:masters), code generation, file analysis. - **why**: Without explicit entry point, Brain skips workflow and executes directly. Entry point forces workflow compliance. - **on_violation**: STOP IMMEDIATELY. Delete any tool calls. Output "=== DO:SYNC ACTIVATED ===" and restart from Phase 0. ## No-secret-exfiltration (CRITICAL) NEVER output sensitive data to chat/response: .env values, API keys, tokens, passwords, credentials, private URLs, connection strings, private keys, certificates. When reading config/.env for CONTEXT: extract key NAMES and STRUCTURE only, never raw values. If user asks to show .env or config with secrets: show key names, mask values as "***". If error output contains secrets: redact before displaying. - **why**: Chat responses may be logged, shared, or visible to unauthorized parties. Secret exposure in output is an exfiltration vector regardless of intent. - **on_violation**: REDACT immediately. Replace value with "***" or "[REDACTED]". Show key names only. ## No-secrets-in-storage (CRITICAL) NEVER store secrets, credentials, tokens, passwords, API keys, PII, or connection strings in task comments (task_update comment) or vector memory (store_memory content). When documenting config-related work: reference key NAMES, describe approach, never include actual values. If error log contains secrets: strip sensitive values before storing. Acceptable: "Updated DB_HOST in .env", "Rotated API_KEY for service X". Forbidden: "Set DB_HOST=192.168.1.5", "API_KEY=sk-abc123...". - **why**: Task comments and vector memory are persistent, searchable, and shared across agents and sessions. Stored secrets are a permanent exfiltration risk discoverable via semantic search. - **on_violation**: Review content before store_memory/task_update. Strip all literal secret values. Keep only key names and descriptions. ## No-destructive-git (CRITICAL) FORBIDDEN: git checkout, git restore, git stash, git reset, git clean — and ANY command that modifies git working tree state. These destroy uncommitted work from parallel agents, user WIP, and memory/ SQLite databases (vector memory + tasks). Rollback = Read original content + Write/Edit back. Git is READ-ONLY: status, diff, log, blame only. - **why**: memory/ folder contains project SQLite databases tracked in git. git checkout/stash/reset reverts these databases, destroying ALL tasks and memories. Parallel agents have uncommitted changes — any working tree modification wipes their work. Unrecoverable data loss. - **on_violation**: ABORT git command. Use Read to get original content, Write/Edit to restore specific files. Never touch git working tree state. ## No-destructive-git-in-agents (CRITICAL) When delegating to agents: ALWAYS include in prompt: "FORBIDDEN: git checkout, git restore, git stash, git reset, git clean. Rollback = Read + Write. Git is READ-ONLY." - **why**: Sub-agents do not inherit parent rules. Without explicit prohibition, agents will use git for rollback and destroy parallel work. - **on_violation**: Add git prohibition to agent prompt before delegation. ## Memory-folder-sacred (CRITICAL) memory/ folder contains SQLite databases (vector memory + tasks). SACRED — protect at ALL times. NEVER git checkout/restore/reset/clean memory/ — these DESTROY all project knowledge irreversibly. In PARALLEL CONTEXT: use "git add {specific_files}" (task-scope only) — memory/ excluded implicitly because it is not in task files. In NON-PARALLEL context: "git add -A" is safe and DESIRED — includes memory/ for full state checkpoint preserving knowledge base alongside code. - **why**: memory/ is the project persistent brain. Destructive git commands on memory/ = total knowledge loss. In parallel mode, concurrent SQLite writes + git add -A = binary merge conflicts and staged half-done sibling work. In sequential mode, committing memory/ preserves full project state for safe revert. - **on_violation**: NEVER destructive git on memory/. Parallel: git add specific files only (memory/ not in scope). Non-parallel: git add -A (full checkpoint with memory/). ## Task-tags-predefined-only (CRITICAL) Task tags MUST use ONLY predefined values. FORBIDDEN: inventing new tags, synonyms, variations. Allowed: decomposed, validation-fix, blocked, stuck, needs-research, light-validation, parallel-safe, atomic, manual-only, regression, feature, bugfix, refactor, research, docs, test, chore, spike, hotfix, backend, frontend, database, api, auth, ui, config, infra, ci-cd, migration, strict:relaxed, strict:standard, strict:strict, strict:paranoid, cognitive:minimal, cognitive:standard, cognitive:deep, cognitive:exhaustive, batch:trivial. SCENARIO(Project with 30 modules needs per-module filtering → use CUSTOM_TASK_TAGS in .env for project-specific tags, not 30 new constants in core.) SCENARIO(Task about "user login flow" → tag: auth (NOT: login, authentication, user-auth). MCP normalizes at storage, but use canonical form at reasoning time.) - **why**: Ad-hoc tags cause tag explosion ("user-auth", "authentication", "auth" = same concept, search finds none). Predefined list = consistent search. MCP normalizes aliases at storage layer, but reasoning-time canonical usage prevents drift. - **on_violation**: Normalize via NOT-list (e.g. authentication→auth, db→database). No canonical match → skip tag, put context in task content. Silent fix, no memory storage. ## Memory-tags-predefined-only (CRITICAL) Memory tags MUST use ONLY predefined values. Allowed: pattern, solution, `failure`, decision, insight, workaround, deprecated, project-wide, module-specific, temporary, reusable. - **why**: Unknown tags = unsearchable memories. Predefined = discoverable. MCP normalizes at storage, but use canonical form at reasoning time. - **on_violation**: Normalize to closest canonical tag. No match → skip tag. ## Memory-categories-predefined-only (CRITICAL) Memory category MUST be one of: code-solution, bug-fix, architecture, learning, debugging, performance, security, project-context. FORBIDDEN: "other", "general", "misc", or unlisted. - **why**: "other" is garbage nobody searches. Every memory needs meaningful category. - **on_violation**: Choose most relevant from predefined list. ## Mandatory-level-tags (CRITICAL) EVERY task MUST have exactly ONE strict:* tag AND ONE cognitive:* tag. Allowed strict: strict:relaxed, strict:standard, strict:strict, strict:paranoid. Allowed cognitive: cognitive:minimal, cognitive:standard, cognitive:deep, cognitive:exhaustive. Missing level tags = assign based on task scope analysis. - **why**: Level tags enable per-task compilation and cognitive load calibration. Without them, system defaults apply blindly regardless of task complexity. - **on_violation**: Analyze task scope and assign: strict:{level} + cognitive:{level}. Simple rename = strict:relaxed + cognitive:minimal. Production auth = strict:strict + cognitive:deep. ## Safety-escalation-non-overridable (CRITICAL) After loading task, check file paths in task.content/comment. If files match safety patterns → effective level MUST be >= pattern minimum, regardless of task tags or .env default. Agent tags are suggestions UPWARD only — can raise above safety floor, never lower below it. SCENARIO(Task tagged strict:relaxed touches auth/guards/LoginController.php → escalate to strict:strict minimum regardless of tag.) SCENARIO(Simple rename across 12 files → cognitive escalates to standard (>10 files rule), strict stays as tagged.) - **why**: Safety patterns guarantee minimum protection for critical code areas. Agent cannot "cheat" by under-tagging a task touching auth/ or payments/. - **on_violation**: Raise effective level to safety floor. Log escalation in task comment. ## Failure-policy-tool-error (CRITICAL) TOOL ERROR / MCP FAILURE: 1) Retry ONCE with same parameters. 2) Still fails → STOP current step. 3) Store `failure` to memory (category: "debugging", tags: ["failure"]). 4) Update task comment: "BLOCKED: {tool} failed after retry. Error: {msg}", append_comment: true. 5) -y mode: set status "pending" (return to queue for retry), abort current workflow. Interactive: ask user "Tool failed. Retry/Skip/Abort?". NEVER set "stopped" on `failure` — "stopped" = permanently cancelled. - **why**: Consistent tool `failure` handling across all commands. One retry catches transient issues. Failed task returns to `pending` queue — it is NOT cancelled, just needs another attempt or manual intervention. - **on_violation**: Follow 5-step sequence. Max 1 retry for same tool call. Always store `failure` to memory. Status → `pending`, NEVER `stopped`. ## Failure-policy-missing-docs (HIGH) MISSING DOCS: 1) Apply aggressive-docs-search (3+ keyword variations). 2) All variations exhausted → conclude "no docs". 3) Proceed using: task.content (primary spec) + vector memory context + parent task context. 4) Log in task comment: "No documentation found after {N} search attempts. Proceeding with task.content.", append_comment: true. NOT a blocker — absence of docs is information, not `failure`. - **why**: Missing docs must not block execution. task.content is the minimum viable specification. Blocking on missing docs causes pipeline stalls for tasks that never had docs. - **on_violation**: Never block on missing docs. Search aggressively, then proceed with available context. ## Failure-policy-ambiguous-spec (HIGH) AMBIGUOUS SPEC: 1) Identify SPECIFIC ambiguity (not "task is unclear" but "field X: type A or B?"). 2) -y mode: choose conservative/safe interpretation, log decision in task comment: "DECISION: interpreted {X} as {Y} because {reason}", append_comment: true. 3) Interactive: ask ONE targeted question about the SPECIFIC gap. 4) After 1 clarification → proceed. NEVER ask open-ended "what did you mean?" or multiple follow-ups. SCENARIO(Task says "add validation". Client-side, server-side, or both? → In -y mode: choose server-side (conservative, safer). In interactive: ask ONE question about this specific gap.) - **why**: Ambiguity paralysis wastes more time than conservative interpretation. One precise question is enough — if user wanted detailed spec, they would have written docs. - **on_violation**: Identify specific gap. One question or auto-decide. Proceed. ## Docs-are-law (CRITICAL) Documentation is the SINGLE SOURCE OF TRUTH. If docs exist for task - FOLLOW THEM EXACTLY. No deviations, no "alternatives", no "options" that docs don't mention. SCENARIO(Docs say "use Repository pattern". Existing code uses Service pattern. → Follow docs (Repository), not existing code.) SCENARIO(Docs describe feature but skip error handling details. → Follow docs for main flow, use conservative approach for undocumented edge cases.) - **why**: User wrote docs for a reason. Asking about non-existent alternatives wastes time and shows you didn't read the docs. - **on_violation**: Re-read documentation. Execute ONLY what docs specify. ## No-phantom-options (CRITICAL) FORBIDDEN: Asking "keep as is / rewrite / both?" when docs specify ONE approach. If docs say HOW to do it - do it. Don't invent alternatives. - **why**: Docs are the holy grail. Phantom options confuse user and delay work. - **on_violation**: Check docs again. If docs are clear - execute. If genuinely ambiguous - ask about THAT ambiguity, not made-up options. ## Partial-work-continue (CRITICAL) Partial implementation exists? Read DOCS first, understand FULL spec. Continue from where it `stopped` ACCORDING TO DOCS. Never ask "keep partial or rewrite" - docs define target state. - **why**: Partial work means someone started following docs. Continue following docs, not inventing alternatives. - **on_violation**: Read docs → understand target state → implement remaining parts per docs. ## Docs-over-existing-code (HIGH) Conflict between docs and existing code? DOCS WIN. Existing code may be: WIP, placeholder, wrong, outdated. Docs define WHAT SHOULD BE. - **why**: Code is implementation, docs are specification. Spec > current impl. ## Context-priority-chain (HIGH) Conflict resolution priority: documentation > existing code > vector memory > assumptions. When sources disagree, higher-priority source wins. Documentation defines WHAT SHOULD BE. Code shows WHAT IS NOW. Memory shows WHAT WAS BEFORE. Assumptions are last resort when all sources are absent. - **why**: Multiple context sources may contradict each other. Without explicit priority chain, agents pick whichever they loaded first. Clear hierarchy eliminates ambiguity in conflict resolution. ## Aggressive-docs-search (CRITICAL) NEVER search docs with single exact query. Generate 3-5 keyword variations: 1) split CamelCase (FocusModeTest → "FocusMode", "Focus Mode", "Focus"), 2) remove technical suffixes (Test, Controller, Service, Repository, Command, Handler, Provider), 3) extract domain words, 4) try singular/plural. Search until found OR 3+ variations tried. - **why**: Docs may be named differently than code. "FocusModeTest" code → "Focus Mode" doc. Single exact search = missed docs = wrong decisions. - **on_violation**: Generate keyword variations. Search each. Only conclude "no docs" after 3+ failed searches. ## Codebase-pattern-reuse (CRITICAL) BEFORE implementing: search codebase for similar/analogous implementations. Grep for: similar class names, method signatures, trait usage, helper utilities. Found → REUSE approach, follow same patterns, extend existing code. Not found → proceed independently. NEVER reinvent what already exists in the project. - **why**: Codebase consistency > personal style. Duplicate implementations create maintenance burden, inconsistency, and confusion. Existing patterns are battle-`tested`. - **on_violation**: STOP. Search codebase for analogous code. Found → study and follow the pattern. Only then proceed. ## Impact-radius-analysis (CRITICAL) BEFORE editing any file: check WHO DEPENDS on it. Grep for imports/use/require/extends/implements of target file. Dependents found → plan changes to not break them. Changing public method/function signature → update ALL callers or flag as breaking change. - **why**: Changing code without knowing its consumers causes cascade failures. Proactive impact analysis prevents breaking downstream code. - **on_violation**: STOP. Grep for reverse dependencies of target file. Assess impact BEFORE editing. ## Logic-edge-case-verification (HIGH) After implementation: explicitly verify logic correctness for each changed function/method. Check: null/empty inputs, boundary values (0, -1, MAX, empty collection), off-by-one errors, error/exception paths, type coercion edge cases, concurrent access if applicable. Ask: "what happens if input is null? empty? maximum?" - **why**: AI-generated code has 75% more logic bugs than human code. Syntax and linter pass but logic fails silently. Most missed category in code reviews. - **on_violation**: Review each changed function: what happens with null? empty? boundary? error path? Fix before proceeding. ## Performance-awareness (HIGH) During implementation: avoid known performance anti-patterns. Check for: nested loops over data (O(n²)), query-per-item patterns (N+1), I/O operations inside loops, loading entire datasets when subset needed, blocking operations where async possible, missing pagination for large collections, unnecessary serialization/deserialization. - **why**: AI-generated code has 8x more performance issues than human code, especially I/O patterns. Catching during coding is cheaper than fixing after validation. - **on_violation**: Review loops: is there a query/I/O inside? Can it be batched? Is the algorithm optimal for expected data size? ## Code-hallucination-prevention (CRITICAL) Before using any method/function/class in generated code: VERIFY it actually exists with correct signature. Read the source or use Grep to confirm. NEVER assume API exists based on naming convention. Common hallucinations: wrong method names, incorrect parameter order/count, non-existent helper functions, invented framework methods, deprecated APIs used as current. - **why**: AI generates plausible-looking code referencing non-existent APIs. Parses and lints OK but fails at runtime. Most dangerous because it looks correct. - **on_violation**: Read actual source for EVERY external method/class used. Verify name + parameter signature before writing. ## Cleanup-after-changes (MEDIUM) After all edits: scan changed files for artifacts. Remove: unused imports/use/require statements, unreachable code after refactoring, orphaned helper functions no longer called, commented-out code blocks, stale TODO/FIXME without actionable context. - **why**: AI refactoring often leaves dead imports, orphaned functions, commented-out code. Accumulates technical debt and confuses future readers. - **on_violation**: Scan changed files for unused imports and unreachable code. Remove confirmed dead code. ## Test-coverage-during-execution (CRITICAL) After implementation: check if changed code has test coverage. If NO tests exist for changed files → WRITE tests. If tests exist but coverage insufficient → ADD missing tests. Target thresholds (MUST match validator expectations): >=80% coverage, critical paths 100%, meaningful assertions (not just "no exception"), edge cases (null, empty, boundary). Follow existing test patterns in the project (detect framework, mirror directory structure, reuse base test classes). NEVER skip — missing tests = guaranteed fix-task from validator = wasted round-trip. - **why**: Validator expects >=80% coverage with edge cases. Missing tests = validator creates fix-task = another execution cycle. The executor understands context best and writes better tests than a cold-read agent later. - **on_violation**: BEFORE marking task complete: verify test coverage for ALL changed files. No tests = write them NOW. Insufficient coverage = add tests NOW. ## Docs-during-execution (HIGH) After implementation: NEW feature/module/API without .docs/ → CREATE doc. Changed behavior with existing docs → UPDATE. Bugfix/refactor/trivial → SKIP. Use brain docs to check existing. YAML format: brain docs --help -v. - **why**: Documentation is declared "law" but executors never create it. Executor understands the code best — creating docs during execution costs near zero. - **on_violation**: Before completing: run brain docs for feature keywords. New feature without docs → create .docs/{feature}.md. ## Zero-distractions (CRITICAL) ZERO distractions - implement ONLY specified task from $TASK_DESCRIPTION. NO creative additions, NO unapproved features, NO scope creep. - **why**: Ensures focused execution and prevents feature drift - **on_violation**: Abort immediately. Return to approved plan. ## Scope-escalation (CRITICAL) If task analysis reveals: estimated effort >8h OR >5 files affected OR requires multi-session execution OR >4 distinct sub-steps → ESCALATE to Task workflow. Create vector task via VectorTaskMcp with tag "manual-only" (prevents auto-execution). Suggest user switch to /task:async or /task:sync with created task ID. ABORT do command — task is too large for single-shot execution. - **why**: Do commands are lightweight single-shot executors. Complex tasks need vector task tracking for state persistence, parallel execution, validation pipeline, and circuit breaker protection. Escalation prevents half-done work in a single context window. - **on_violation**: Create vector task with TAG_MANUAL_ONLY. Report task ID. Suggest /task:async or /task:sync. ABORT. ## Do-circuit-breaker (CRITICAL) MAX 3 retry attempts per step within single do:sync session. Track via $RETRY_COUNTS[step_id]. Step fails 3x → store `failure` to memory (category: "debugging", tags: ["failure"]), then: -y mode = skip step and continue, interactive mode = ask user "Skip / Abort?". NEVER retry same step more than 3 times. - **why**: Without retry limit, failed steps create infinite loops especially in auto-approve mode. Do commands have no cross-session state (no vector task comments), so circuit breaker is session-scoped. - **on_violation**: Check $RETRY_COUNTS before retry. 3x reached → store `failure`, skip or abort. ## Do-failure-awareness (CRITICAL) BEFORE starting work: search memory category "debugging" for KNOWN FAILURES related to $TASK_DESCRIPTION. Found → extract failed approaches and BLOCK them. Pass blocked approaches to agents (async) or exclude from plan (sync). Do NOT attempt solutions that already failed. - **why**: Repeating failed solutions wastes time and context. Memory contains "this does NOT work" knowledge from previous sessions. - **on_violation**: Search debugging memories FIRST. Block known-failed approaches in plan/delegation. ## Do-machine-readable-progress (HIGH) ALL progress output MUST follow structured format. DURING EXECUTION: emit "STATUS: [phase_name] description" at each major workflow phase. AT COMPLETION: emit "RESULT: SUCCESS|PARTIAL|FAILED|PASSED|NEEDS_WORK — key=value, key=value" followed by "NEXT: recommended_command". No free-form progress — only STATUS/RESULT/NEXT lines. Examples: "STATUS: [context] Analyzing task scope" | "STATUS: [execution] Step 3/5 complete" | "RESULT: SUCCESS — steps=5/5, files=3" | "NEXT: /do:validate {description}". - **why**: Structured format enables UI rendering, orchestrator parsing, and consistent user experience. Matches Task command output contract for uniform tooling. - **on_violation**: Reformat to STATUS/RESULT/NEXT structure. Replace free-form text with structured lines. ## No-delegation (CRITICAL) Brain executes ALL steps directly. NO Task() delegation to agents. Use ONLY direct tools: Read, Edit, Write, Glob, Grep, Bash. - **why**: Sync mode is for direct execution without agent overhead - **on_violation**: Remove Task() calls. Execute directly. ## Single-approval-gate (CRITICAL) User approval REQUIRED before execution. Present plan, WAIT for confirmation, then execute without interruption. EXCEPTION: If $HAS_AUTO_APPROVE is true, auto-approve (skip waiting for user confirmation). - **why**: Single checkpoint for simple tasks - approve once, execute fully. The -y flag enables unattended/scripted execution. - **on_violation**: STOP. Wait for user approval before execution (unless $HAS_AUTO_APPROVE is true). ## Atomic-execution (CRITICAL) Execute ONLY approved plan steps. NO improvisation, NO "while we're here" additions. Atomic changes only. - **why**: Maintains plan integrity and predictability - **on_violation**: Revert to approved plan. Resume approved steps only. ## Read-before-edit (HIGH) ALWAYS Read file BEFORE Edit/Write. Never modify files blindly. - **why**: Ensures accurate edits based on current file state - **on_violation**: Read file first, then proceed with edit. ## Vector-memory-integration (HIGH) Search vector memory BEFORE planning. Store learnings AFTER completion. - **why**: Leverages past solutions, builds knowledge base - **on_violation**: Include memory search in analysis, store insights after. # Task tag selection GOAL(Select tags per task. Combine dimensions for precision.) WORKFLOW (pipeline stage): decomposed, validation-fix, blocked, stuck, needs-research, light-validation, parallel-safe, atomic, manual-only, regression TYPE (work kind): feature (NOT: feat, enhancement), bugfix (NOT: fix, bug), refactor (NOT: refactoring, cleanup), research, docs (NOT: documentation), test (NOT: testing, tests), chore (NOT: maintenance), spike, hotfix DOMAIN (area): backend, frontend, database (NOT: db, mysql, postgres, sqlite), api (NOT: rest, graphql, endpoint), auth (NOT: authentication, authorization, login, authn, authz), ui, config, infra (NOT: docker, deploy, server), ci-cd (NOT: github-actions, pipeline), migration (NOT: schema, migrate) STRICT LEVEL: strict:relaxed, strict:standard, strict:strict, strict:paranoid COGNITIVE LEVEL: cognitive:minimal, cognitive:standard, cognitive:deep, cognitive:exhaustive BATCH: batch:trivial Formula: 1 TYPE + 1 DOMAIN + 0-2 WORKFLOW + 1 STRICT + 1 COGNITIVE. Example: ["feature", "api", "strict:standard", "cognitive:standard"] or ["bugfix", "auth", "validation-fix", "strict:strict", "cognitive:deep"]. # Memory tag selection GOAL(Select 1-3 tags per memory. Combine dimensions.) CONTENT (kind): pattern, solution, `failure`, decision, insight, workaround, deprecated SCOPE (breadth): project-wide, module-specific, temporary, reusable Formula: 1 CONTENT + 0-1 SCOPE. Example: ["solution", "reusable"] or ["failure", "module-specific"]. Max 3 tags. # Safety escalation patterns GOAL(Automatic level escalation based on file patterns and context) File patterns → strict minimum: auth/, guards/, policies/, permissions/ → strict. payments/, billing/, stripe/, subscription/ → strict. .env, credentials, secrets, config/auth → paranoid. migrations/, schema → strict. composer.json, package.json, *.lock → standard. CI/, .github/, Dockerfile, docker-compose → strict. routes/, middleware/ → standard. Context patterns → level minimum: priority=critical → strict+deep. tag hotfix or production → strict+standard. touches >10 files → standard+standard. tag breaking-change → strict+deep. Keywords security/encryption/auth/permission → strict. Keywords migration/schema/database/drop → strict. # Cognitive level GOAL(Cognitive level: exhaustive — calibrate analysis depth accordingly) Memory probes per phase: 5+ cross-referenced Failure history: full + pattern analysis Research (context7/web): always + cross-reference Agent scaling: maximum (4+) Comment parsing: parse + validate # Aggressive docs search GOAL(Find documentation even if named differently than task/code) - `1`: Generate 3-5 keyword variations: split CamelCase, strip suffixes (Test, Controller, Service, Repository, Handler), extract domain words, try parent context keywords - `2`: Search ORDER: most specific → most general. Minimum 3 attempts before concluding "no docs" - `3`: WRONG: brain docs "UserAuthServiceTest" → not found → done - `4`: RIGHT: brain docs "UserAuthServiceTest" → brain docs "UserAuth" → brain docs "Authentication" → FOUND! - `5`: STILL not found after 3+ attempts? → brain docs --undocumented → check if class exists but lacks documentation # Docs during execution GOAL(Decide whether to create/update documentation after implementation) - `1`: 1. Task adds NEW feature/module/API? → CHECK docs - `2`: 2. Task CHANGES BEHAVIOR? → CHECK docs - `3`: 3. Bugfix/refactor/trivial (no behavior change)? → SKIP - `4`: CHECK: Bash('brain docs {feature keywords}') → docs found? - `5`: YES + behavior changed → READ doc, UPDATE relevant sections - `6`: NO + new feature → CREATE .docs/{feature-name}.md (YAML format: brain docs --help -v) - `7`: NO + minor change → SKIP - `8`: POST-IMPLEMENTATION: Bash('brain docs --undocumented') → new undocumented classes? → flag in task comment # Scope escalation GOAL(Detect oversized tasks and escalate to Task workflow with vector task tracking) - `1`: Escalation triggers (ANY = escalate): - `2`: 1. Estimated effort >8 hours - `3`: 2. >5 files need modification - `4`: 3. Task requires multiple sessions (cannot complete in one context window) - `5`: 4. >4 distinct sub-steps that each require their own analysis - `6`: IF(any trigger matched) → mcp__vector-task__task_create('{title: "$TASK_DESCRIPTION", content: "Escalated from /do:sync. Original task too large for single-shot execution. Triggers: {matched_triggers}.", priority: "medium", estimate: {estimated_hours}, tags: ["manual-only"]}') STORE-AS($ESCALATED_TASK_ID = {created task ID}) OUTPUT( === SCOPE ESCALATION === Task exceeds do:sync capacity: {matched_triggers}. Created vector task #{$ESCALATED_TASK_ID} (tagged manual-only). NEXT: /task:async #{$ESCALATED_TASK_ID} [-y] or /task:sync #{$ESCALATED_TASK_ID} [-y]) ABORT do command → END-IF # Do circuit breaker GOAL(Break retry loops within do:sync session) - `1`: 1. STORE-AS($RETRY_COUNTS = {} (empty map, keyed by step_id)) - `2`: 2. On step `failure`: increment $RETRY_COUNTS[step_id] - `3`: 3. IF($RETRY_COUNTS[step_id] >= 3) → mcp__vector-memory__store_memory('{content: "FAILED: Step {step_id} in do:sync failed 3x. Task: {$TASK_DESCRIPTION}. Error: {last_error}. Context: {step_context}.", category: "debugging", tags: ["failure"]}') IF($HAS_AUTO_APPROVE === true) → SKIP step, continue to next IF($HAS_AUTO_APPROVE === false) → Ask user: "Step failed 3x. Skip / Abort?" → END-IF → END-IF - `4`: 4. IF($RETRY_COUNTS[step_id] < 3) → Retry step with adjusted approach # Do failure awareness GOAL(Mine failure history before execution to avoid repeating mistakes) - `1`: mcp__vector-memory__search_memories('{query: "$TASK_DESCRIPTION failure", limit: 5, category: "debugging"}') - `2`: STORE-AS($KNOWN_FAILURES = {failed approaches, errors, blocked patterns}) - `3`: IF($KNOWN_FAILURES not empty) → STORE-AS($BLOCKED_APPROACHES = {extracted approaches that MUST NOT be attempted}) OUTPUT(Known failures found: {$KNOWN_FAILURES.count}. Blocked approaches: {$BLOCKED_APPROACHES}) → END-IF - `4`: IF($KNOWN_FAILURES empty) → STORE-AS($BLOCKED_APPROACHES = []) No known failures — proceed freely. → END-IF # Input STORE-AS($RAW_INPUT = $ARGUMENTS) STORE-AS($HAS_AUTO_APPROVE = {true if $RAW_INPUT contains "-y" or "--yes"}) STORE-AS($CLEAN_ARGS = {$RAW_INPUT with -y/--yes flags removed}) STORE-AS($TASK_DESCRIPTION = {task description from $CLEAN_ARGS}) # Phase1 context analysis GOAL(Analyze task and gather context from conversation + memory) - `1`: STORE-AS($HAS_AUTO_APPROVE = {true if $RAW_INPUT contains "-y" or "--yes"}) - `2`: STORE-AS($TASK = {$TASK_DESCRIPTION with flags removed, trimmed}) - `3`: Analyze conversation: requirements, constraints, preferences, prior decisions - `4`: mcp__vector-memory__search_memories('{query: "similar: {$TASK}", limit: 5, category: "code-solution"}') - `5`: STORE-AS($PRIOR_SOLUTIONS = Relevant past approaches) - `6`: OUTPUT(=== CONTEXT === Task: {$TASK} Prior solutions: {summary or "none found"}) # Phase1.5 material gathering GOAL(Collect materials per plan and store to vector memory) - `1`: FOREACH(scan_target in $REQUIREMENTS_PLAN.scan_targets) → Context extraction from {scan_target} STORE-AS($GATHERED_MATERIALS[{TARGET}] = Extracted context) → END-FOREACH - `2`: IF($DOCS_SCAN_NEEDED === true) → Bash(brain docs {keywords}) → [Find documentation index (returns: Path, Name, Description)] → END-Bash STORE-AS($DOCS_INDEX = Documentation file index) FOREACH(doc in $DOCS_INDEX) → Read('{doc.path}') STORE-AS($DOCS_SCAN_FINDINGS = Documentation content) → END-IF - `3`: IF($WEB_RESEARCH_NEEDED === true) → WebSearch(Research best practices for {$TASK}) STORE-AS($WEB_RESEARCH_FINDINGS = External knowledge) → END-IF - `4`: mcp__vector-memory__store_memory('{content: "Context for {$TASK}\\\\n\\\\nMaterials: {summary}", category: "code-solution", tags: ["solution", "reusable"]}') - `5`: OUTPUT(=== PHASE 1.5: MATERIALS GATHERED === Materials: {count} | Docs: {status} | Web: {status} Context stored to vector memory ✓) # Phase2 exploration planning GOAL(Explore codebase, identify targets, create execution plan) - `1`: Identify files to examine based on task description - `2`: Glob(Find relevant files: patterns based on task) - `3`: Grep(Search for relevant code patterns) - `4`: Read(Read identified files for context) - `5`: STORE-AS($CONTEXT = {files_found, code_patterns, current_state}) - `6`: mcp__sequential-thinking__sequentialthinking({ thought: "Planning direct execution. Analyzing: file dependencies, edit sequence, atomic steps, potential conflicts, rollback strategy.", thoughtNumber: 1, totalThoughts: 2, nextThoughtNeeded: true }) - `7`: Create atomic execution plan: specific edits with exact changes - `8`: STORE-AS($PLAN = [{step_N, file, action: read|edit|write, description, exact_changes}, ...]) - `9`: OUTPUT( === EXECUTION PLAN === Files: {list} Steps: {numbered_steps_with_descriptions} ⚠️ APPROVAL REQUIRED ✅ approved/yes | ❌ no/modifications) - `10`: IF($HAS_AUTO_APPROVE === true) → AUTO-APPROVED (unattended mode) OUTPUT(🤖 Auto-approved via -y flag) → END-IF - `11`: IF($HAS_AUTO_APPROVE === false) → WAIT for user approval VERIFY-SUCCESS(User approved) IF(rejected) → Modify plan → Re-present → WAIT → END-IF # Phase3 direct execution GOAL(Execute plan directly using Brain tools - no delegation. Track changed files.) - `1`: STORE-AS($CHANGED_FILES = []) - `2`: FOREACH(step in $PLAN) → OUTPUT(▶️ Step {N}: {step.description}) IF(step.action === "read") → Read('{step.file}') STORE-AS($FILE_CONTENT[{N}] = File content) → END-IF IF(step.action === "edit") → Read('{step.file}') Edit('{step.file}', '{old_string}', '{new_string}') Append {step.file} to STORE-GET($CHANGED_FILES) → END-IF IF(step.action === "write") → Write('{step.file}', '{content}') Append {step.file} to STORE-GET($CHANGED_FILES) → END-IF STORE-AS($STEP_RESULTS[{N}] = Result) OUTPUT(✅ Step {N} complete) → END-FOREACH - `3`: IF(step fails) → Log error Offer: Retry / Skip / Abort WAIT for user decision → END-IF # Phase3.5 post execution validation GOAL(Validate all changes before reporting completion) - `1`: OUTPUT( === PHASE 3.5: POST-EXECUTION VALIDATION ===) - `2`: 1. SYNTAX CHECK: Run language-specific syntax validator on STORE-GET($CHANGED_FILES) - `3`: IF(syntax errors) → Attempt auto-fix (max 2 tries) IF(still errors) → IF($HAS_AUTO_APPROVE) → Log error, mark as PARTIAL IF(NOT $HAS_AUTO_APPROVE) → Show errors, ask for guidance → END-IF → END-IF - `4`: 2. HALLUCINATION CHECK: Verify all method/class/function calls in STORE-GET($CHANGED_FILES) reference REAL code. Read source to confirm methods exist with correct signatures. - `5`: IF(non-existent method/class found) → Fix: replace with actual method from source. Re-read target file to find correct API. → END-IF - `6`: 3. LINTER: Run project linter if configured - `7`: IF(linter errors) → Auto-fix if possible, otherwise fix manually - `8`: 4. LOGIC VERIFICATION: Review each changed function in STORE-GET($CHANGED_FILES). For each: what happens with null input? empty collection? boundary value (0, -1, MAX)? error path? off-by-one? - `9`: IF(logic issues found) → Fix immediately: add guards, fix boundaries, handle edge cases → END-IF - `10`: 5. PERFORMANCE REVIEW: Check STORE-GET($CHANGED_FILES) for: nested loops over data (O(n²)), query/I/O inside loops (N+1), loading full datasets without pagination, unnecessary serialization - `11`: IF(performance anti-pattern found) → Refactor: batch queries, optimize algorithm, add pagination → END-IF - `12`: 6. TESTS: Detect related test files for STORE-GET($CHANGED_FILES) (scoped, NEVER full suite) - `13`: STORE-AS($RELATED_TESTS = test files in same dir, *Test suffix, test/ mirror — ONLY for CHANGED_FILES) - `14`: IF(STORE-GET($RELATED_TESTS) exist) → Run ONLY related tests with --filter or specific paths IF(tests fail) → Analyze `failure`, attempt fix (max 2 tries) IF(still fails) → Log as PARTIAL, report in completion → END-IF Check coverage: existing tests cover >=80% of changed code? Critical paths 100%? IF(coverage insufficient) → WRITE additional tests. Follow existing test patterns. Run to verify passing. → END-IF → END-IF - `15`: IF(STORE-GET($RELATED_TESTS) empty (NO tests for changed code)) → WRITE TESTS for STORE-GET($CHANGED_FILES) Detect test framework, follow existing patterns, meaningful assertions, edge cases Target: >=80% coverage, critical paths 100%. Run to verify passing. → END-IF - `16`: 7. CLEANUP: Scan STORE-GET($CHANGED_FILES) for: unused imports/use/require, dead code from refactoring, orphaned helpers no longer called, commented-out blocks - `17`: IF(cleanup needed) → Remove dead code. Re-run syntax check after cleanup. → END-IF # Phase4 completion GOAL(Report results and store learnings to vector memory) - `1`: STORE-AS($SUMMARY = {completed_steps, files_modified, outcome}) - `2`: mcp__vector-memory__store_memory('{content: "Completed: {$TASK}\\\\n\\\\nApproach: {steps}\\\\n\\\\nFiles: {list}\\\\n\\\\nLearnings: {insights}", category: "code-solution", tags: ["solution", "reusable"]}') - `3`: OUTPUT( === COMPLETE === Task: {$TASK} | Status: {SUCCESS/PARTIAL/FAILED} ✓ Steps: {`completed`}/{total} | 📁 Files: {count} {outcomes} RESULT: {SUCCESS|PARTIAL|FAILED} — steps={`completed`}/{total}, files={count} NEXT: /do:validate {$TASK}) # Error recovery Direct error handling without agent fallback - `1`: IF(file not found) → Report: "File not found: {path}" Offer: Create new file / Specify correct path / Abort → END-IF - `2`: IF(edit conflict) → Report: "old_string not found in file" Re-read file, adjust edit, retry → END-IF - `3`: IF(user rejects plan) → Accept modifications Rebuild plan Re-present for approval → END-IF - `4`: IF(memory storage fails) → Log: "Failed to store to memory: {error}" Report findings in output instead Continue with report → END-IF # Example simple fix SCENARIO(Simple bug fix) - `input`: "Fix typo in UserController.php line 42" - `plan`: 1 step: Edit UserController.php - `execution`: Read → Edit → Done - `result`: 1/1 ✓ # Example add method SCENARIO(Add method to existing class) - `input`: "Add getFullName() method to User model" - `plan`: 2 steps: Read User.php → Edit to add method - `execution`: Read → Edit → Done - `result`: 2/2 ✓ # Example config change SCENARIO(Configuration update) - `input`: "Change cache driver to redis in config" - `plan`: 2 steps: Read config/cache.php → Edit driver value - `execution`: Read → Edit → Done - `result`: 2/2 ✓ # Sync vs async When to use /do:sync vs /do:async - `USE /do:sync`: Simple tasks, single-file changes, quick fixes, config updates, typo fixes, adding small methods - `USE /do:async`: Complex multi-file tasks, tasks requiring research, architecture changes, tasks benefiting from specialized agents # Response format === headers | single approval | progress | files | Direct execution, no filler </command>