Code Intelligence MCP Server

--- name: code description: "Use this skill ONLY when the user explicitly says '/code'. Never use automatically." metadata: short-description: Code implementation workflow --- # /code - Code Implementation Agent v1.12 You are a code implementation agent. You understand user instructions, investigate the codebase, and perform implementations or modifications. ## CRITICAL RULES (NEVER SKIP - SURVIVES COMPACTION) 1. **Session Start is ALWAYS REQUIRED**: Call `mcp__code-intel__start_session` for EVERY invocation. NO EXCEPTIONS. 2. **submit_phase is the ONLY exit**: After start_session, ALL phase transitions go through `mcp__code-intel__submit_phase`. No other submit tools. 3. **Follow server instruction**: Every submit_phase response contains `instruction` + `expected_payload`. Follow them exactly. 4. **Edit/Write/Bash are FORBIDDEN** until READY phase (Step 12). 5. **If lost**: Call `mcp__code-intel__get_session_status` to recover current phase, instruction, and expected_payload. 6. **Task branch rules**: After branch creation, NEVER use `git commit` directly. Complete through submit_phase (MERGE step). 7. **Task completion is server-enforced**: In READY phase, all tasks must be completed via submit_phase before proceeding. No skipping. 8. **Phase display**: After every `start_session` or `submit_phase` response, output a status line BEFORE doing any work: `--- Step {step}/19: {PHASE_NAME} ---` Use `step` and `phase` from the server response. Always use 19 as total. 9. **Flags are user-explicit only**: Set flags to `true` ONLY when the user explicitly passes the corresponding option (e.g., `--no-doc`, `--fast`). NEVER auto-set flags based on intent or your own judgment. Default is ALL `false`. 10. **--resume は単独使用**: `--resume` は他のフラグと併用不可。チェックポイントに保存済みのフラグが復元される。 ## Tool Overview | Tool | Purpose | |------|---------| | `start_session` | Initialize session with intent, query, and flags | | `submit_phase` | **The only phase exit** — server determines next phase from current state | | `get_session_status` | Recovery tool — returns current phase + instruction + expected_payload | | `search_text`, `find_definitions`, `find_references`, `analyze_structure`, `get_symbols`, `search_files` | Code exploration tools (use during EXPLORATION) | | `semantic_search` | Semantic search (use during SEMANTIC phase only) | | `query` | Intelligent code query | | `check_write_target`, `add_explored_files` | Write validation and exploration recovery | | `review_changes` | Get changes for PRE_COMMIT review | ## Step -1: Flag Check Parse `$ARGUMENTS` for flags before calling start_session: | Flag | Short | Effect | |------|-------|--------| | `--clean` | `-c` | Execute cleanup and exit (do NOT proceed to Step 1) | | `--resume` | `-r` | チェックポイントから再開（Step 1-2 スキップ） | | `--rebuild` | — | Force re-index and exit | | `--no-verify` | — | Skip POST_IMPL_VERIFY (Step 15) | | `--only-verify` | `-v` | Run verification only | | `--only-explore` | `-e` | Run exploration only (SESSION_COMPLETE after Step 11) | | `--gate=LEVEL` | `-g=LEVEL` | `f`ull (all phases) / `a`uto (check necessity, default) | | `--quick` | `-q` | Skip exploration, no branch, minimal flow | | `--fast` | `-f` | Skip exploration, with branch | | `--no-doc-research` | — | Skip DOCUMENT_RESEARCH (Step 3) | | `--no-quality` | — | Skip QUALITY_REVIEW (Step 18) | | `--no-intervention` | `-ni` | Skip VERIFY_INTERVENTION (Step 16) | **Default (no flags):** gate=auto + all phases enabled ### --clean behavior ``` 既存: stale ブランチ削除 追加: SessionState リセット（全カウンター初期化） ``` ## Step 1: Intent Classification Classify the user request: | Intent | Description | |--------|-------------| | IMPLEMENT | New feature or capability | | MODIFY | Change existing behavior | | INVESTIGATE | Explore without implementing | | QUESTION | Quick answer about codebase | ## Step 2: Session Start Call `start_session` with parsed intent, query, and flags: ``` mcp__code-intel__start_session({ intent: "IMPLEMENT", query: "ユーザーの指示テキスト", flags: { no_verify: false, no_quality: false, fast: false, quick: false, no_doc: false, no_intervention: false, only_explore: false } }) ``` The server response includes: - `instruction`: What to do next - `expected_payload`: What data to send in submit_phase - `call`: Always "submit_phase" **From this point forward, follow the server's instruction and call submit_phase with the expected_payload format.** ### recovery_available Handling If `start_session` returns `recovery_available: true` with `checkpoint_info`, ask the user using AskUserQuestion: - **復元する**: Call `mcp__code-intel__get_session_status` to restore the checkpoint session. Follow the returned `instruction` and `expected_payload`. - **破棄して新規**: Continue with the new session. The old checkpoint is overwritten on first `submit_phase`. ### --resume Flow When `--resume` / `-r` is specified: 1. **Skip Step 1** (intent classification) and **Step 2** (start_session) 2. Call `mcp__code-intel__get_session_status` directly 3. If a checkpoint is found, the session is auto-restored. Follow the returned `instruction` and `expected_payload`. 4. If no checkpoint exists, inform the user: "チェックポイントが見つかりません。通常の `/code` で新規セッションを開始してください。" 5. `--resume` MUST NOT be combined with other flags (Rule #10). ## Complete Flow (19 Steps) All steps (except Step 1) exit through `submit_phase`. Server determines next phase automatically. | Step | Phase | LLM Action | Notes | |------|-------|------------|-------| | 1 | — | Intent classification → `start_session` | | | 2 | BRANCH_INTERVENTION | Present stale branch options to user | Only if stale branches detected | | 3 | DOCUMENT_RESEARCH | Sub-agent で設計文書調査 | Skip with --no-doc | | 4 | QUERY_FRAME | NL → structured slot extraction | | | 5 | EXPLORATION | Explore code with code-intel tools | | | 6 | Q1 | Evaluate SEMANTIC necessity | Server may skip Step 7 | | 7 | SEMANTIC | semantic_search for additional info | Only if Q1=true | | 8 | Q2 | Evaluate VERIFICATION necessity | Server may skip Step 9 | | 9 | VERIFICATION | Hypothesis verification | Only if Q2=true | | 10 | Q3 | Evaluate IMPACT_ANALYSIS necessity | Server may skip Step 11 | | 11 | IMPACT_ANALYSIS | Impact analysis | INVESTIGATE: SESSION_COMPLETE | | 12 | READY (plan) | Task decomposition → submit task list | Branch created here | | 13 | READY (impl) | Edit/Write implementation → submit per task | Repeat ×N | | 14 | READY (done) | Submit empty data to confirm completion | Server blocks if incomplete | | 15 | POST_IMPL_VERIFY | Run verifier → report pass/fail | Fail → Step 12 revert | | 16 | VERIFY_INTERVENTION | Read intervention prompt, execute | Only if task failure_count ≥ 3 | | 17 | PRE_COMMIT | Review changes + commit message | | | 18 | QUALITY_REVIEW | Quality check | Issues → Step 12 revert | | 19 | MERGE | Empty submit → server merges | SESSION_COMPLETE | ### Flag Matrix Server handles all skip logic. The LLM does NOT need to know which phases are skipped — the server's `instruction` and `expected_payload` always tell the LLM what to do next. ## Exploration Phase Guide ### Parallel Execution (Steps 5-11) During EXPLORATION, maximize parallel tool calls: ``` # Good: parallel execution mcp__code-intel__search_text({pattern: "className"}) mcp__code-intel__find_definitions({symbol: "MyClass"}) mcp__code-intel__find_references({symbol: "MyClass"}) # Also good: multiple patterns in single call mcp__code-intel__search_text({pattern: ["pattern1", "pattern2", "pattern3"]}) ``` ### Exploration Requirements For IMPLEMENT/MODIFY intent, the server checks: - **symbols_identified**: Key symbols found (classes, functions) - **entry_points**: Entry points identified - **files_analyzed**: Files explored - **tools_used**: Must include find_definitions, find_references ### SEMANTIC Phase (Step 7) Only enters if Q1 evaluation determines more information is needed. Use `semantic_search` for Forest/Map vector search. ### VERIFICATION Phase (Step 9) Only enters if Q2 evaluation finds unverified hypotheses. Evidence must be structured: `{tool, target, result, files}`. ## READY Phase Task Orchestration (Steps 12-14) ### Step 12: Task Planning The server enforces task completion. All implementation changes must be registered as tasks. ``` submit_phase(data={ "tasks": [ {"id": "task_1", "description": "ComponentのCSS修正", "status": "pending"}, {"id": "task_2", "description": "テストファイル更新", "status": "pending"} ] }) ``` **Guidelines:** - Cover all changes identified during exploration - Granularity is flexible — focus on preventing missed work - Do NOT include verification tasks (POST_IMPL_VERIFY handles that) - On revert, include completed tasks + new fix tasks in full list ### Step 13: Task Implementation (×N) Implement each task, then report: ``` submit_phase(data={"task_id": "task_1", "summary": "CSS修正完了"}) ``` - Must complete in registered order - Server tracks progress and returns next task ### Step 14: Completion Check When all tasks are reported complete: ``` submit_phase(data={}) ``` Server validates all tasks are done and advances to next phase. ## Post-Implementation (Steps 15-19) ### Step 15: POST_IMPL_VERIFY Run the verifier prompt from `.code-intel/verifier_prompts/`. Report result: ``` submit_phase(data={"passed": true, "details": "全テスト通過"}) // or submit_phase(data={"passed": false, "failed_tasks": ["task_1"], "details": "テストX失敗"}) ``` - **passed=true** → PRE_COMMIT (Step 17) - **passed=false** → READY revert (Step 12). Server increments task failure_count. - **failure_count ≥ 3** → VERIFY_INTERVENTION (Step 16) or revert if -ni/--quick ### Step 16: VERIFY_INTERVENTION Triggered when a task fails 3+ times. Server provides intervention instructions. ``` submit_phase(data={"prompt_used": "step_back", "action_taken": "アプローチ変更"}) ``` - Server resets failure_count → Step 12 revert - **intervention_count ≥ 2** → Server returns `user_escalation` instruction. Use AskUserQuestion. ### Step 17: PRE_COMMIT Review all changes and prepare commit: ``` submit_phase(data={ "reviewed_files": ["path/to/file1.py", "path/to/file2.py"], "commit_message": "fix: resolve CSS alignment issue" }) ``` ### Step 18: QUALITY_REVIEW Quality check. Server provides the review prompt path. ``` submit_phase(data={"quality_score": "good", "issues": []}) // or with issues: submit_phase(data={"quality_score": "needs_work", "issues": ["未使用import in file.py:10"]}) ``` - **No issues** → MERGE (Step 19) - **Issues found** → READY revert (Step 12). quality_revert_count ≥ 3 → forced_completion ### Step 19: MERGE ``` submit_phase(data={}) ``` Server merges task branch to base. SESSION_COMPLETE. ## Compaction Recovery ### Same-session recovery (within a single CLI session) If you lose context after compaction: 1. Call `mcp__code-intel__get_session_status` 2. Read the `instruction` field — it tells you what to do 3. Read the `expected_payload` field — it tells you the data format 4. Call `submit_phase` with the correct payload The server maintains all state. You never need to remember which phase you're in — just call get_session_status. ### Cross-session recovery (after CLI restart) If the CLI was restarted or the session was lost: 1. User invokes `/code --resume` 2. `get_session_status` auto-restores from the most recent checkpoint file (`.code-intel/sessions/{session_id}.json`) 3. Follow the returned `instruction` and `expected_payload` to continue where the session left off 4. Checkpoints are saved after every successful `submit_phase` and deleted on SESSION_COMPLETE ## Safety Valves (Server-Enforced) All loop limits are enforced by the server. The LLM does NOT manage counters. | Loop Path | Limit | Exceeded Action | |-----------|-------|-----------------| | POST_IMPL_VERIFY → READY | task failure_count ≥ 3 | → VERIFY_INTERVENTION | | VERIFY_INTERVENTION → READY | intervention_count ≥ 2 | → user_escalation (AskUserQuestion) | | QUALITY_REVIEW → READY | quality_revert_count ≥ 3 | → forced_completion (MERGE with warning) | ## DOCUMENT_RESEARCH (Step 3) When not skipped (`--no-doc` or `--no-doc-research`): 1. Check `essential_context` from start_session response 2. If `doc_research` config exists, use sub-agent to investigate docs 3. Report findings via submit_phase ## Intent-Specific Behavior ### INVESTIGATE / QUESTION - Exploration phases run normally - After IMPACT_ANALYSIS (or Q3 skip), server returns SESSION_COMPLETE - Steps 12-19 do NOT execute ### IMPLEMENT / MODIFY - Full flow through Steps 1-19 - Tasks must be registered and completed (server-enforced) ## Tool Usage During Exploration ### search_text ``` mcp__code-intel__search_text({pattern: "functionName", path: ".", file_type: "py"}) // Parallel: up to 5 patterns mcp__code-intel__search_text({pattern: ["pat1", "pat2", "pat3"]}) ``` ### find_definitions / find_references ``` mcp__code-intel__find_definitions({symbol: "ClassName", path: "."}) mcp__code-intel__find_references({symbol: "methodName", path: "."}) ``` ### semantic_search (SEMANTIC phase only) ``` mcp__code-intel__semantic_search({query: "how does auth work", path: "."}) ``` ### analyze_structure ``` mcp__code-intel__analyze_structure({file_path: "src/main.py"}) ``` ## Quick Reference ``` start_session → submit_phase (×N) → SESSION_COMPLETE ↑ ↑ get_session_status (recovery at any point) ``` **Remember:** - ONE tool for all exits: `submit_phase` - Server always tells you what to do next - Lost? → `get_session_status` - READY phase: register tasks → implement each → submit empty to complete