maxsimcli 4.8.0 → 4.9.0

package/dist/assets/templates/skills/roadmap-writing/SKILL.md

@@ -1,22 +1,21 @@
 ---
 name: roadmap-writing
 description: >-
-  Creates structured project roadmaps with phased planning, dependency graphs,
-  and testable success criteria in MAXSIM-compatible format. Use when creating a
-  new roadmap, restructuring project phases, or planning milestones.
+  Phased planning with dependency graphs, success criteria, and requirement
+  mapping. Produces roadmaps with observable truths as success criteria.
+  Use when creating project roadmaps, breaking features into phases, or
+  structuring multi-phase work.
 ---
 
 # Roadmap Writing
 
 A roadmap without success criteria is a wish list. Define what done looks like for every phase.
 
-**HARD GATE: No phase without success criteria and dependencies. Every phase must have a number, name, goal, testable success criteria, and explicit dependencies. Violating this rule is a violation, not flexibility.**
-
 ## Process
 
 ### 1. SCOPE -- Understand the Project
 
-Before writing phases, understand what you are planning:
+Before writing phases:
 
 - Read PROJECT.md for vision and constraints
 - Read REQUIREMENTS.md for v1/v2/out-of-scope boundaries
@@ -29,7 +28,7 @@ Each phase should be:
 
 | Property | Requirement |
 |----------|------------|
-| **Independently deliverable** | The phase produces a working increment, not a half-built feature |
+| **Independently deliverable** | Produces a working increment, not a half-built feature |
 | **1-3 days of work** | Larger phases should be split; smaller ones should be merged |
 | **Clear boundary** | You can tell when the phase is done without ambiguity |
 | **Ordered by dependency** | No phase depends on a later phase |
@@ -42,28 +41,25 @@ Phase numbering convention:
 | `01A`, `01B` | Parallel sub-phases that can execute concurrently |
 | `01.1`, `01.2` | Sequential sub-phases within a parent phase |
 
-Sort order: `01` then `01A` then `01B` then `01.1` then `01.2` then `02`.
-
 ### 3. DEFINE -- Write Each Phase
 
-Every phase must include all of these fields:
+Every phase must include:
 
 ```markdown
 ### Phase {number}: {name}
 **Goal**: {one sentence -- what this phase achieves}
 **Depends on**: {phase numbers, or "Nothing" for the first phase}
-**Requirements**: {requirement IDs from REQUIREMENTS.md, if applicable}
+**Requirements**: {requirement IDs from REQUIREMENTS.md}
 **Success Criteria** (what must be TRUE):
-  1. {Testable statement -- can be verified with a command, test, or inspection}
-  2. {Testable statement}
-  3. {Testable statement}
+  1. {Observable truth -- verifiable by command, test, or inspection}
+  2. {Observable truth}
 **Plans**: TBD
 ```
 
 Success criteria rules:
 - Each criterion must be testable -- "code is clean" is not testable; "no lint warnings" is testable
 - Include at least 2 criteria per phase
-- At least one criterion should be verifiable by running a command (test, build, lint)
+- At least one criterion should be verifiable by running a command
 - Criteria describe the end state, not the process ("tests pass" not "write tests")
 
 ### 4. CONNECT -- Map Dependencies
@@ -71,42 +67,54 @@ Success criteria rules:
 - Which phases can run in parallel? (Use letter suffixes: `03A`, `03B`)
 - Which phases are strictly sequential? (Use number suffixes: `03.1`, `03.2`)
 - Are there any circular dependencies? (This is a design error -- restructure)
+- Every phase except the first must declare at least one dependency
+
+### 5. MAP REQUIREMENTS -- Ensure Coverage
 
-Every phase except the first must declare at least one dependency.
+Every requirement ID from REQUIREMENTS.md must appear in at least one phase. Produce a coverage map:
 
-### 5. MILESTONE -- Group Into Milestones
+```
+REQUIREMENT-ID -> Phase N
+```
 
-Group phases into milestones that represent user-visible releases. Each milestone should be a coherent deliverable that could ship independently.
+If any requirement is unmapped, either add it to a phase or explicitly mark it as out-of-scope.
+
+### 6. MILESTONE -- Group Into Milestones
+
+Group phases into milestones that represent user-visible releases:
 
 ```markdown
 ## Milestones
-
 - **v1.0 MVP** -- Phases 1-4
 - **v1.1 Polish** -- Phases 5-7
-- **v2.0 Scale** -- Phases 8-10
 ```
 
-### 6. WRITE -- Produce the Roadmap
+### 7. VALIDATE -- Check the Roadmap
+
+| Check | How to Verify |
+|-------|--------------|
+| Every phase has success criteria | Read each phase detail section |
+| Dependencies are acyclic | Trace the dependency chain -- no loops |
+| Phase numbering is sequential | Numbers increase, no gaps larger than 1 |
+| Milestones cover all phases | Every phase appears in exactly one milestone |
+| Success criteria are testable | Each criterion can be verified by command, test, or inspection |
+| Requirements are covered | Every requirement ID maps to at least one phase |
 
-Assemble the complete ROADMAP.md:
+## Roadmap Format
 
 ```markdown
 # Roadmap: {project name}
 
 ## Overview
-
-{2-3 sentences: what the project is, what this roadmap covers, delivery strategy}
+{2-3 sentences: what the project is, what this roadmap covers}
 
 ## Milestones
-
 - **{milestone name}** -- Phases {range} ({status})
 
 ## Phases
-
 - [ ] **Phase {N}: {name}** - {one-line summary}
 
 ## Phase Details
-
 ### Phase {N}: {name}
 **Goal**: ...
 **Depends on**: ...
@@ -114,51 +122,25 @@ Assemble the complete ROADMAP.md:
 **Success Criteria** (what must be TRUE):
   1. ...
 **Plans**: TBD
-```
 
-### 7. VALIDATE -- Check the Roadmap
-
-Before finalizing, verify:
-
-| Check | How to Verify |
-|-------|--------------|
-| Every phase has success criteria | Read each phase detail section |
-| Dependencies are acyclic | Trace the dependency chain -- no loops |
-| Phase numbering is sequential | Numbers increase, no gaps larger than 1 |
-| Milestones cover all phases | Every phase appears in exactly one milestone |
-| Success criteria are testable | Each criterion can be verified by command, test, or inspection |
+## Coverage Map
+REQUIREMENT-ID -> Phase N
+```
 
 ## Common Pitfalls
 
 | Pitfall | Why It Fails |
 |---------|-------------|
 | "We don't know enough to plan" | Plan what you know. Unknown phases get a research spike first. |
-| "The roadmap will change anyway" | Plans change -- that is expected. No plan guarantees drift. |
 | "Success criteria are too rigid" | Vague criteria are useless. Rigid criteria are adjustable. |
 | "One big phase is simpler" | Big phases hide complexity and delay feedback. Split them. |
 | "Dependencies are obvious" | Obvious to you now. Not obvious to the agent running phase 5 next week. |
 | "We'll add details later" | Later never comes. Write the details now while context is fresh. |
 
-Stop if you catch yourself writing a phase without success criteria, creating phases longer than 3 days of work, skipping dependency declarations, writing vague criteria like "code is good", creating circular dependencies, or putting all work in one or two massive phases.
-
-## Verification
-
-Before finalizing a roadmap, confirm:
-
-- [ ] Every phase has a number, name, goal, dependencies, and success criteria
-- [ ] Success criteria are testable (verifiable by command, test, or inspection)
-- [ ] Dependencies form a DAG (no circular dependencies)
-- [ ] Phase numbering follows MAXSIM convention (01, 01A, 01B, 01.1, etc.)
-- [ ] Phases are 1-3 days of work each
-- [ ] Milestones group phases into coherent deliverables
-- [ ] ROADMAP.md matches the expected format for MAXSIM CLI parsing
-- [ ] Overview section summarizes the project and delivery strategy
+Stop if you catch yourself writing a phase without success criteria, creating phases longer than 3 days of work, skipping dependency declarations, or writing vague criteria like "code is good".
 
 ## MAXSIM Integration
 
-Roadmap writing integrates with the MAXSIM lifecycle:
-- Use during project initialization to create the initial roadmap
-- Use when restructuring after a significant scope change or pivot
 - The roadmap is read by MAXSIM agents via `roadmap read` -- format compliance is mandatory
-- Phase numbering must be parseable by `normalizePhaseName()` and `comparePhaseNum()` in core
+- Phase numbering must be parseable by `normalizePhaseName()` and `comparePhaseNum()`
 - Config `model_profile` in `.planning/config.json` affects agent assignment per phase

package/dist/assets/templates/skills/sdd/SKILL.md

@@ -1,84 +1,66 @@
 ---
 name: sdd
 description: >-
-  Executes plan tasks sequentially, each in a fresh subagent with minimal context,
-  with mandatory two-stage review between tasks. Use when executing sequential
-  tasks where context rot is a concern or running spec-driven dispatch.
+  Spec-driven development with fresh-agent-per-task execution. Prevents context
+  rot by isolating each task in a clean context window with its spec. Use when
+  executing multi-task plans, orchestrating agent work, or when context
+  accumulation degrades quality.
 ---
 
-# Spec-Driven Dispatch (SDD)
+# Spec-Driven Development (SDD)
 
-Execute tasks sequentially, each in a fresh subagent with clean context. Review every task before moving to the next.
+Execute tasks sequentially, each in a fresh agent with clean context. Verify every task before moving to the next.
 
-**HARD GATE** -- No task starts until the previous task passes two-stage review. If the review found issues, they must be fixed before the next task begins. No exceptions, no deferral, no skipping review for simple tasks.
+## Why SDD
 
-## Process
+Context rot is the primary failure mode for multi-task execution. As an agent processes more tasks, earlier context competes with later instructions. Quality degrades predictably after 3-5 tasks in a single context window. SDD solves this by giving each task a fresh context with only its specification.
+
+## The SDD Process
 
 ### 1. LOAD -- Read the Plan
 
 - Read the plan file (PLAN.md) to get the ordered task list
-- For each task, identify: description, acceptance criteria, relevant files
-- Confirm task order makes sense (later tasks may depend on earlier ones)
+- For each task: description, acceptance criteria, relevant files
+- Confirm task order respects dependencies
 
 ### 2. DISPATCH -- Spawn Fresh Agent Per Task
 
 For each task in order:
 
-1. Assemble the task context:
+1. Assemble minimal task context:
    - Task description and acceptance criteria from the plan
    - Only the files relevant to this specific task
    - Results from previous tasks (commit hashes, created files) -- NOT the full previous context
 2. Spawn a fresh agent with this minimal context
-3. The agent implements the task, runs tests, and commits
+3. The agent implements the task, runs verification, and commits
 
 ### 3. REVIEW -- Two-Stage Quality Gate
 
-After each task completes, run two review stages before proceeding:
-
-**Stage 1: Spec Compliance**
-
-- Does the implementation match the task description?
-- Are all acceptance criteria met?
-- Were only the specified files modified (no scope creep)?
-- Do the changes align with the plan's intent?
-
-Verdict: PASS or FAIL with specific issues.
+After each task completes:
 
-**Stage 2: Code Quality**
+**Stage 1: Spec Compliance** -- Does the implementation match the task spec? Are all acceptance criteria met? Were only specified files modified?
 
-- Are there obvious bugs, edge cases, or error handling gaps?
-- Is the code readable and consistent with codebase conventions?
-- Are there unnecessary complications or dead code?
-- Do all tests pass?
+**Stage 2: Code Quality** -- Are there bugs, edge cases, or error handling gaps? Is the code consistent with codebase conventions? Do all tests pass?
 
-Verdict: PASS or FAIL with specific issues.
+Verdict: PASS or FAIL with specific issues per stage.
 
 ### 4. FIX -- Address Review Failures
 
 If either review stage fails:
 
-1. Spawn a NEW fresh agent with the original task description, the review feedback, and the current file state
-2. The fix agent addresses ONLY the review issues -- no new features
-3. Re-run both review stages on the fixed code
-4. If 3 fix attempts fail: STOP and escalate to the user
+1. Spawn a NEW fresh agent with original task spec + review feedback + current file state
+2. Fix agent addresses ONLY the review issues -- no new features
+3. Re-run both review stages
+4. If 3 fix attempts fail: STOP and escalate
 
 ### 5. ADVANCE -- Move to Next Task
 
 Only after both review stages pass:
 
-- Record the task as complete
-- Note the commit hash and any files created or modified
-- Pass this minimal summary (not full context) to the next task's agent
-
-### 6. REPORT -- Final Summary
-
-After all tasks complete:
-
-- List each task with its status and commit hash
-- Note any tasks that required fix iterations
-- Summarize the total changes made
+- Record task as complete with commit hash
+- Pass minimal summary (not full context) to the next task
 
-## Context Management Rules
+## Context Management
 
 Each agent receives ONLY what it needs:
 
@@ -89,38 +71,21 @@ Each agent receives ONLY what it needs:
 | Previous task commit hashes | Always |
 | Previous task full diff | Never |
 | Previous task agent conversation | Never |
-| PROJECT.md / REQUIREMENTS.md | Only if task references project-level concerns |
 | Full codebase | Never -- only specified files |
 
 The point of SDD is fresh context. Loading the previous agent's full context defeats the purpose.
 
+## When to Use SDD
+
+- **Good fit:** Multi-task plans (3+ tasks), sequential work where each task builds on the previous, implementations where quality degrades over time
+- **Poor fit:** Single-task work, highly interactive tasks requiring user feedback, tasks that share significant overlapping context
+
 ## Common Pitfalls
 
-| Pitfall | Why it matters |
+| Pitfall | Why It Matters |
 |---|---|
-| Skipping review for simple tasks | Simple tasks still have bugs. Review takes seconds for simple code. |
-| Passing full context forward | Full context causes context rot. Minimal summaries keep agents effective. |
+| Skipping review for simple tasks | Simple tasks still have bugs. Review catches what the implementer missed. |
+| Passing full context forward | Full context causes the exact rot SDD is designed to prevent. |
 | Deferring fixes to the next task | The next task's agent does not know about the bug. Fix it now. |
-| Accumulating fix-later items across tasks | Each task must be clean before the next starts. |
-
-## Verification
-
-Before reporting completion, confirm:
-
-- [ ] Every task was executed by a fresh agent with minimal context
-- [ ] Every task passed both spec compliance and code quality review
-- [ ] No task was skipped or started before the previous task passed review
-- [ ] Fix iterations (if any) are documented
-- [ ] All tests pass after the final task
-- [ ] Summary includes per-task status and commit hashes
-
-## MAXSIM Integration
-
-When a plan specifies `skill: "sdd"`:
 
-- The orchestrator reads tasks from PLAN.md in order
-- Each task is dispatched to a fresh subagent
-- Two-stage review runs between every task
-- Failed reviews trigger fix agents (up to 3 attempts)
-- Progress is tracked in STATE.md via decision entries
-- Final results are recorded in SUMMARY.md
+See also: `/verification-before-completion` for the evidence-based verification methodology used within each SDD task.

package/dist/assets/templates/skills/systematic-debugging/SKILL.md

@@ -1,18 +1,18 @@
 ---
 name: systematic-debugging
 description: >-
-  Investigates bugs through systematic root-cause analysis: reproduce, hypothesize,
-  isolate, verify, fix, confirm. Use when encountering any bug, test failure,
-  unexpected behavior, or error message.
+  Systematic debugging via reproduce-hypothesize-isolate-verify-fix cycle.
+  Requires evidence at each step. Use when investigating bugs, test failures,
+  unexpected behavior, or runtime errors.
 ---
 
 # Systematic Debugging
 
 Find the root cause first. Random fixes waste time and create new bugs.
 
-**HARD GATE -- No fix attempts without understanding root cause. If you have not completed the REPRODUCE and HYPOTHESIZE steps, you cannot propose a fix.**
+**No fix attempts without understanding root cause.** If you have not completed the REPRODUCE and HYPOTHESIZE steps, you cannot propose a fix.
 
-## Process
+## The 5-Step Process
 
 ### 1. REPRODUCE -- Confirm the Problem
 
@@ -52,6 +52,19 @@ Find the root cause first. Random fixes waste time and create new bugs.
 - Run the full test suite: no regressions.
 - Verify the original error no longer occurs.
 
+## Hypothesis Testing Protocol
+
+For each hypothesis:
+
+1. **Form:** "I think X is the root cause because Y."
+2. **Design test:** "If X is the cause, then changing Z should produce W."
+3. **Run test:** Execute the change and observe the result.
+4. **Evaluate:** Did the result match the prediction? If yes, proceed to FIX. If no, form a new hypothesis.
+
+## Escalation
+
+If 3+ fix attempts have failed, the issue is likely architectural. Document what you have tried (hypotheses tested, evidence gathered, fixes attempted) and escalate.
+
 ## Common Pitfalls
 
 | Excuse | Reality |
@@ -61,25 +74,6 @@ Find the root cause first. Random fixes waste time and create new bugs.
 | "Multiple changes at once saves time" | You cannot isolate what worked. You will create new bugs. |
 | "The issue is simple" | Simple bugs have root causes too. The process is fast for simple bugs. |
 
-Stop immediately if you catch yourself changing code before reproducing, proposing a fix before reading the full error, trying random fixes, or changing multiple things at once. If any of these triggers, return to step 1.
-
-If 3+ fix attempts have failed, the issue is likely architectural. Document what you have tried and escalate to the user.
-
-## Verification
-
-Before claiming a bug is fixed, confirm:
-
-- [ ] The original error has been reproduced reliably
-- [ ] Root cause has been identified with evidence (not guessed)
-- [ ] A failing test reproduces the bug
-- [ ] A single, targeted fix addresses the root cause
-- [ ] The failing test now passes
-- [ ] The full test suite passes (no regressions)
-- [ ] The original error no longer occurs when running the original steps
-
-## MAXSIM Integration
+Stop immediately if you catch yourself changing code before reproducing, proposing a fix before reading the full error, trying random fixes, or changing multiple things at once.
 
-When debugging during plan execution, MAXSIM deviation rules apply:
-- **Rule 1 (Auto-fix bugs):** You may auto-fix bugs found during execution, but you must still follow this debugging process.
-- **Rule 4 (Architectural changes):** If 3+ fix attempts fail, STOP and return a checkpoint -- this is an architectural decision for the user.
-- Track all debugging deviations for SUMMARY.md documentation.
+See also: `/verification-before-completion` for evidence-based confirmation after fixes.

package/dist/assets/templates/skills/tdd/SKILL.md

@@ -1,18 +1,23 @@
 ---
 name: tdd
 description: >-
-  Enforces test-driven development with the Red-Green-Refactor cycle: write a
-  failing test first, implement minimal code to pass, then refactor. Use when
-  implementing features, fixing bugs, or adding new behavior.
+  Test-driven development with red-green-refactor cycle and atomic commits.
+  Write failing test first, then minimal passing code, then refactor. Use when
+  implementing business logic, API endpoints, data transformations, validation
+  rules, or algorithms.
 ---
 
 # Test-Driven Development (TDD)
 
 Write the test first. Watch it fail. Write minimal code to pass. Clean up.
 
-**HARD GATE: No implementation code without a failing test first. If you wrote production code before the test, delete it and start over. No exceptions.**
+## When to Use TDD
 
-## Process
+**Good fit:** Business logic with defined I/O, API endpoints with contracts, data transformations, validation rules, algorithms, state machines.
+
+**Poor fit:** UI layout, configuration files, build scripts, one-off scripts, mechanical renames.
+
+## The Red-Green-Refactor Cycle
 
 ### 1. RED -- Write One Failing Test
 
@@ -46,40 +51,27 @@ Write the test first. Watch it fail. Write minimal code to pass. Clean up.
 
 ### 6. REPEAT -- Next failing test for next behavior
 
+## Commit Pattern
+
+Each TDD cycle produces 2-3 atomic commits:
+
+- **RED commit:** `test({scope}): add failing test for [feature]`
+- **GREEN commit:** `feat({scope}): implement [feature]`
+- **REFACTOR commit (if changes made):** `refactor({scope}): clean up [feature]`
+
+## Context Budget
+
+TDD uses approximately 40% more context than direct implementation due to the RED-GREEN-REFACTOR overhead. Plan accordingly for long task lists.
+
 ## Common Pitfalls
 
-| Excuse | Why it fails |
+| Excuse | Why It Fails |
 |--------|-------------|
 | "Too simple to test" | Simple code breaks. The test takes 30 seconds. |
 | "I'll add tests after" | Tests written after pass immediately -- they prove nothing. |
 | "I know the code works" | Knowledge is not evidence. A passing test is evidence. |
 | "TDD is slower" | TDD is faster than debugging. Every skip creates debt. |
-| "Let me keep the code as reference" | You will adapt it instead of writing test-first. Delete means delete. |
-
-Stop immediately if you catch yourself:
-
-- Writing implementation code before writing a test
-- Writing a test that passes on the first run
-- Skipping the VERIFY RED step
-- Adding features beyond what the current test requires
-- Keeping pre-TDD code "as reference"
-
-## Verification
-
-Before claiming TDD compliance, confirm:
-
-- [ ] Every new function/method has a corresponding test
-- [ ] Each test was written BEFORE its implementation
-- [ ] Each test was observed to FAIL before implementation was written
-- [ ] Each test failed for the expected reason (missing behavior, not syntax error)
-- [ ] Minimal code was written to pass each test
-- [ ] All tests pass after implementation
-- [ ] Refactoring (if any) did not break any tests
-
-## MAXSIM Integration
 
-In MAXSIM plan execution, tasks marked `tdd="true"` follow this cycle with per-step commits:
+Stop immediately if you catch yourself writing implementation code before writing a test, writing a test that passes on the first run, skipping the VERIFY RED step, or adding features beyond what the current test requires.
 
-- **RED commit:** `test({phase}-{plan}): add failing test for [feature]`
-- **GREEN commit:** `feat({phase}-{plan}): implement [feature]`
-- **REFACTOR commit (if changes made):** `refactor({phase}-{plan}): clean up [feature]`
+See also: `/verification-before-completion` for evidence-based completion claims after TDD cycles.

package/dist/assets/templates/skills/tool-priority-guide/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: tool-priority-guide
+description: >-
+  Tool selection guide for Claude Code operations. Maps common tasks to preferred
+  tools, explaining when to use Read over cat, Grep over rg, Glob over find,
+  Write over echo, and Edit over sed. Use when deciding which tool to use for
+  file operations, search, content modification, or web content retrieval.
+user-invocable: false
+---
+
+# Tool Priority Guide
+
+Use dedicated Claude Code tools over Bash equivalents. Dedicated tools provide better permissions handling, output formatting, and user experience.
+
+## File Reading
+
+| Task | Use | Not |
+|------|-----|-----|
+| Read file contents | **Read tool** | `cat`, `head`, `tail` via Bash |
+| Read specific lines | **Read tool** (with offset/limit) | `sed -n 'X,Yp'` via Bash |
+| Read images | **Read tool** (multimodal) | Not possible via Bash |
+| Read PDFs | **Read tool** (with pages param) | `pdftotext` via Bash |
+
+**Why Read:** Handles permissions, large files, binary formats. Returns line-numbered output.
+
+## File Writing
+
+| Task | Use | Not |
+|------|-----|-----|
+| Create new file | **Write tool** | `echo > file`, `cat <<EOF` via Bash |
+| Rewrite entire file | **Write tool** (after Read) | `cat > file` via Bash |
+| Modify part of file | **Edit tool** | `sed`, `awk` via Bash |
+| Rename string across file | **Edit tool** (replace_all) | `sed -i 's/old/new/g'` via Bash |
+
+**Why Write/Edit:** Atomic operations, preserves encoding, provides diff view for review.
+
+## Searching
+
+| Task | Use | Not |
+|------|-----|-----|
+| Search file contents | **Grep tool** | `grep`, `rg` via Bash |
+| Find files by pattern | **Glob tool** | `find`, `ls -R` via Bash |
+| Search with context | **Grep tool** (-A, -B, -C params) | `grep -C N` via Bash |
+| Count matches | **Grep tool** (output_mode: count) | `grep -c` via Bash |
+
+**Why Grep/Glob:** Optimized permissions, structured output, result limiting.
+
+## Web Content
+
+| Task | Use | Not |
+|------|-----|-----|
+| Fetch documentation | **WebFetch tool** | `curl` via Bash |
+| Read API responses | **WebFetch tool** | `curl | jq` via Bash |
+| Download files | **Bash** (`curl -O`) | WebFetch (not for binary downloads) |
+
+**Why WebFetch:** Handles authentication, follows redirects, parses HTML.
+
+## When Bash IS the Right Tool
+
+| Task | Why Bash |
+|------|---------|
+| Run build/test commands | `npm test`, `npm run build` -- no dedicated tool |
+| Git operations | `git status`, `git commit` -- no dedicated tool |
+| Install dependencies | `npm install` -- no dedicated tool |
+| Check file existence | `test -f path` -- lightweight, often part of larger commands |
+| Run project CLI tools | Project-specific commands -- no dedicated tool |
+| Chained operations | Multiple sequential commands with `&&` |
+
+## Quick Reference
+
+```
+Read file    --> Read tool
+Write file   --> Write tool (new) or Edit tool (modify)
+Search code  --> Grep tool
+Find files   --> Glob tool
+Fetch URL    --> WebFetch tool
+Run commands --> Bash tool
+```
+
+The general principle: if a dedicated tool exists for the operation, use it. Fall back to Bash only when no dedicated tool covers the task.