Resources

scripts/
  validate-dpb-compliance.sh
references/
  examples-and-checklists.md

Discover-Plan-Batch Protocol (Strict 3-Call Workflow)

The DPB loop enforces a strict 3-call-per-cycle workflow that eliminates token waste from excessive tool calls. This is NOT a suggestion — it is a MANDATORY execution pattern for all GoodVibes agents.

THE EXACT WORKFLOW

0. LOAD SKILLS (once, before any DPB cycle)
   - Call get_skill_content for role-relevant skills
   - This is NOT part of the DPB cycle itself

1. D — DISCOVER (1 tool call)
   - Single `discover` call with ALL queries batched inside
   - Multiple query types (glob, grep, symbols, structural) in one call
   - Can search file content via grep/symbols queries
   - Output: files_only or locations (minimal verbosity)

2. P — PLAN (0 tool calls, cognitive only)
   - Agent thinks about what it needs from discovery results
   - Plans which files to read (with extract modes), what patterns to grep
   - Plans the EXACT precision_read/precision_grep/precision_glob call
   - All token INPUT operations get planned here

3. B — BATCH INPUT (1 tool call)
   - Single precision_read with multiple files batched internally
   - OR single precision_grep with multiple queries batched internally  
   - Key: 1 call, everything batched inside it

4. P — PLAN (0 tool calls, cognitive only)
   - Agent now has all the information it needs
   - Plans which files to write/create and which edits to make
   - Plans the EXACT precision_write/precision_edit call
   - All token OUTPUT operations get planned here

5. B — BATCH OUTPUT (1 tool call)
   - Single precision_write with multiple files batched internally
   - OR single precision_edit with multiple edits batched internally
   - Key: 1 call, everything batched inside it

6. LOOP — Back to D if:
   - Results didn't match expectations
   - Scope changed
   - Validation failed (run precision_exec to validate, then loop)

CALL BUDGET PER CYCLE

Validation (precision_exec) is OPTIONAL and happens AFTER the cycle completes, not during.

Note on sequential calls: Sequential calls are acceptable but not preferred. Always prefer true batching via internal precision tool arrays (files array, edits array, commands array).

KEY RULES (NON-NEGOTIABLE)

1. discover batches ALL discovery queries into 1 call — NEVER use separate precision_glob, precision_grep, precision_read for discovery
2. Plan steps produce ZERO tool calls — they are cognitive (agent thinks in text)
3. Batch input = 1 call — use internal batching (files array, queries array)
4. Batch output = 1 call — use internal batching (files array, edits array)
5. NEVER make sequential calls of the same tool type — if you need 3 files read, batch them in 1 precision_read call
6. ToolSearch is NOT part of DPB — load tools once at start, don’t search mid-cycle

Phase 1: DISCOVER (1 call)

The discover Tool

The discover tool runs multiple grep/glob/symbols/structural queries in parallel, returning results keyed by query ID. This is your ONLY discovery mechanism.

Pattern: Batch ALL discovery queries

# GOOD: 1 discover call with everything
discover:
  queries:
    - id: existing_files
      type: glob
      patterns: ["src/features/auth/**/*.ts"]
    - id: existing_patterns
      type: grep
      pattern: "export (function|const|class)"
      glob: "src/features/**/*.ts"
    - id: exported_hooks
      type: symbols
      query: "use"
      kinds: ["function"]
    - id: console_logs
      type: structural
      structural_pattern: "console.log($$$ARGS)"
  verbosity: files_only

Query types:

• glob – Find files by path patterns
• grep – Find files containing patterns
• symbols – Find exported functions/types/classes
• structural – Find AST patterns (e.g., function calls)

Output modes:

• count_only – Just counts (scope estimation)
• files_only – File paths only (building target lists) ← USE THIS
• locations – File paths + line numbers (when you need exact locations)

Reading Full File Contents

The discover tool excels at searching file content via grep/glob/symbols/structural queries. For reading full file contents (like .goodvibes/memory/*.json files), use precision_read in the Batch Input phase (step 3), batched with other file reads.

[BAD] vs [GOOD] Discovery Patterns

[BAD] — Sequential discovery queries (19+ tool calls)

# BAD: 4 separate tool calls for discovery
precision_glob:
  patterns: ["src/**/*.ts"]

precision_grep:
  queries:
    - id: exports
      pattern: "export function"

precision_read:
  files:
    - path: ".goodvibes/memory/failures.json"

precision_grep:
  queries:
    - id: imports
      pattern: "import.*from"

[GOOD] — Single discover call (1 tool call)

# GOOD: 1 discover call with all queries
discover:
  queries:
    - id: files
      type: glob
      patterns: ["src/**/*.ts"]
    - id: exports
      type: grep
      pattern: "export function"
      glob: "src/**/*.ts"
    - id: imports
      type: grep
      pattern: "import.*from"
      glob: "src/**/*.ts"
  verbosity: files_only

# Then batch memory reads with your Batch Input phase

Phase 2: PLAN (0 calls, cognitive only)

Purpose

Planning is cognitive work, not tool calls. You think in text about:

• Which files to read (with extract modes)
• Which patterns to grep
• The EXACT precision_read or precision_grep call structure
• What you’ll do with the results

Output: A written plan with NO tool calls

Plan Structure

Plan:
1. Read the following files:
   - src/types/user.ts (extract: symbols) — need User interface
   - src/config/app.ts (extract: outline) — check structure
   - .goodvibes/memory/decisions.json (content) — check arch decisions

2. Batch into 1 precision_read call with 3 files

3. Expected result: User interface, app config structure, decisions

[BAD] vs [GOOD] Planning

[BAD] — Vague plan that leads to sequential calls

Plan:
- Read some files
- Check patterns
- Maybe grep for something

This leads to:

precision_read: ...
precision_read: ...  # Second call!
precision_grep: ...  # Third call!

[GOOD] — Specific plan with exact batch structure

Plan:
1. Read 3 files in 1 precision_read call:
   - src/types/user.ts (symbols)
   - src/config/app.ts (outline)
   - .goodvibes/memory/decisions.json (content)

2. Batch call structure:
   precision_read:
     files: [{path: ..., extract: symbols}, {path: ..., extract: outline}, {path: ...}]

This leads to:

precision_read:  # Single call
  files:
    - path: "src/types/user.ts"
      extract: symbols
    - path: "src/config/app.ts"
      extract: outline
    - path: ".goodvibes/memory/decisions.json"

Phase 3: BATCH INPUT (1 call)

Pattern: Batch All Reads

Single precision_read with multiple files:

precision_read:
  files:
    - path: "src/types/user.ts"
      extract: symbols
    - path: "src/types/auth.ts"
      extract: symbols
    - path: "src/config/app.ts"
      extract: outline
    - path: ".goodvibes/memory/decisions.json"
  verbosity: minimal

OR single precision_grep with multiple queries:

precision_grep:
  queries:
    - id: auth_usage
      pattern: "useAuth|getSession"
      glob: "src/**/*.tsx"
    - id: api_calls
      pattern: "fetch|axios"
      glob: "src/**/*.ts"
  output:
    format: files_only
  verbosity: minimal

OR use precision_read with files array + precision_grep with queries array as 2 batched calls:

precision_read:
  files:
    - { path: "src/types/user.ts", extract: symbols }
  verbosity: minimal

precision_grep:
  queries:
    - id: exports
      pattern: "export function"
      glob: "src/**/*.ts"
  output:
    format: files_only

[BAD] vs [GOOD] Input Batching

[BAD] — 3 separate precision_read calls

precision_read:
  files:
    - path: "src/types/user.ts"

precision_read:  # Second call!
  files:
    - path: "src/types/auth.ts"

precision_read:  # Third call!
  files:
    - path: "src/config/app.ts"

[GOOD] — 1 precision_read call with 3 files

precision_read:
  files:
    - path: "src/types/user.ts"
    - path: "src/types/auth.ts"
    - path: "src/config/app.ts"
  verbosity: minimal

Phase 4: PLAN (0 calls, cognitive only)

Purpose

You now have all the information from Batch Input. Plan your output operations:

• Which files to create/write
• Which files to edit
• The EXACT precision_write or precision_edit call structure

Output: A written plan with NO tool calls

Plan Structure

Plan:
1. Create the following files:
   - src/features/auth/types.ts (User interface)
   - src/features/auth/hooks.ts (useAuth hook)
   - src/features/auth/index.ts (barrel export)

2. Batch into 1 precision_write call with 3 files

3. Expected result: 3 new files created

Phase 5: BATCH OUTPUT (1 call)

Pattern: Batch All Writes/Edits

Single precision_write with multiple files:

precision_write:
  files:
    - path: "src/features/auth/types.ts"
      content: |
        export interface User {
          id: string;
          email: string;
        }
    - path: "src/features/auth/hooks.ts"
      content: |
        import type { User } from './types';
        export function useAuth(): User | null { /*...*/ }
    - path: "src/features/auth/index.ts"
      content: |
        export * from './types';
        export * from './hooks';
  verbosity: minimal

OR single precision_edit with multiple edits:

precision_edit:
  edits:
    - path: "src/app/layout.tsx"
      find: "<App />"
      replace: "<AuthProvider><App /></AuthProvider>"
    - path: "src/middleware.ts"
      find: "export const config = {}"
      replace: "export const config = { matcher: ['/dashboard/:path*'] }"
    - path: "src/lib/api.ts"
      find: "headers: {}"
      replace: "headers: { Authorization: `Bearer ${token}` }"
  verbosity: minimal

OR use precision_write for new files + precision_edit for edits as 2 separate batched calls:

precision_write:
  files:
    - { path: "src/features/auth/types.ts", content: "..." }
    - { path: "src/features/auth/hooks.ts", content: "..." }
  verbosity: count_only

precision_edit:
  edits:
    - path: "src/app/layout.tsx"
      find: "<App />"
      replace: "<AuthProvider><App /></AuthProvider>"
  verbosity: count_only

[BAD] vs [GOOD] Output Batching

[BAD] — 3 separate precision_write calls

precision_write:
  files:
    - path: "file1.ts"
      content: "..."

precision_write:  # Second call!
  files:
    - path: "file2.ts"
      content: "..."

precision_write:  # Third call!
  files:
    - path: "file3.ts"
      content: "..."

[GOOD] — 1 precision_write call with 3 files

precision_write:
  files:
    - path: "file1.ts"
      content: "..."
    - path: "file2.ts"
      content: "..."
    - path: "file3.ts"
      content: "..."
  verbosity: minimal

Phase 6: LOOP (When to Return to Discovery)

Loop Triggers

1. Results don’t match expectations — Typecheck fails, tests fail, unexpected behavior
2. Scope changed — Discovery revealed different situation than expected
3. New information — Task requirements clarified during execution

Loop Pattern

# Initial DPB cycle
discover: ...  # Call 1
precision_read: ...  # Call 2
precision_write: ...  # Call 3

# Validation reveals issue
precision_exec:  # Optional validation AFTER cycle
  commands:
    - cmd: "npm run typecheck"
      expect:
        exit_code: 0  # FAILS

# LOOP: Start new DPB cycle with refined discovery
discover:  # Call 1 (new cycle)
  queries:
    - id: find_missing_import
      type: grep
      pattern: "export.*User"
      glob: "src/**/*.ts"
  verbosity: locations  # Need exact location

precision_read: ...  # Call 2 (new cycle)
precision_edit: ...  # Call 3 (new cycle) - fix the issue

Validation (AFTER the cycle)

Validation is OPTIONAL and happens AFTER the 3-call cycle completes:

# After completing a DPB cycle (3 calls), validate:
precision_exec:
  commands:
    - cmd: "npm run typecheck"
      expect:
        exit_code: 0
    - cmd: "npm run lint"
      expect:
        exit_code: 0
  verbosity: minimal

If validation fails, LOOP back to Discovery (start a new 3-call cycle).

Complete Example: Implementing Auth Feature

Cycle 1: Initial Implementation

Step 1 — DISCOVER (1 call)

discover:
  queries:
    - id: existing_auth
      type: glob
      patterns: ["src/features/auth/**/*.ts", "src/**/auth*.ts"]
    - id: auth_patterns
      type: grep
      pattern: "(useAuth|getSession|AuthProvider)"
      glob: "src/**/*.{ts,tsx}"
    - id: user_types
      type: symbols
      query: "User"
      kinds: ["interface", "type"]
  verbosity: files_only

Step 2 — PLAN (0 calls, cognitive)

Discovery results:
- No existing auth files
- No auth patterns in use
- User type exists in src/types/user.ts

Plan:
1. Read src/types/user.ts to understand User interface
2. Read .goodvibes/memory/decisions.json for auth constraints
3. Batch into 1 precision_read call

Step 3 — BATCH INPUT (1 call)

precision_read:
  files:
    - path: "src/types/user.ts"
      extract: symbols
    - path: ".goodvibes/memory/decisions.json"
  verbosity: minimal

Step 4 — PLAN (0 calls, cognitive)

Input results:
- User interface has id, email, name fields
- Decisions.json says: use Clerk for auth

Plan:
1. Create src/features/auth/provider.tsx (Clerk wrapper)
2. Create src/features/auth/hooks.ts (useAuth hook)
3. Create src/features/auth/index.ts (barrel export)
4. Batch into 1 precision_write call

Step 5 — BATCH OUTPUT (1 call)

precision_write:
  files:
    - path: "src/features/auth/provider.tsx"
      content: |
        import { ClerkProvider } from '@clerk/nextjs';
        export function AuthProvider({ children }: { children: React.ReactNode }) {
          return <ClerkProvider>{children}</ClerkProvider>;
        }
    - path: "src/features/auth/hooks.ts"
      content: |
        import { useUser } from '@clerk/nextjs';
        import type { User } from '@/types/user';
        export function useAuth(): User | null {
          const { user } = useUser();
          if (!user) return null;
          return { id: user.id, email: user.emailAddresses[0].emailAddress, name: user.fullName };
        }
    - path: "src/features/auth/index.ts"
      content: |
        export { AuthProvider } from './provider';
        export { useAuth } from './hooks';
  verbosity: minimal

Total calls in Cycle 1: 3 (discover + precision_read + precision_write)

Validation (AFTER Cycle 1)

precision_exec:
  commands:
    - cmd: "npm run typecheck"
      expect:
        exit_code: 0
  verbosity: minimal

# Result: FAILS — missing @clerk/nextjs import

Cycle 2: Fix Import Issue

Step 1 — DISCOVER (1 call)

discover:
  queries:
    - id: package_json
      type: glob
      patterns: ["package.json"]
    - id: clerk_usage
      type: grep
      pattern: "@clerk/nextjs"
      glob: "src/**/*.{ts,tsx}"
  verbosity: files_only

Step 2 — PLAN (0 calls, cognitive)

Discovery: @clerk/nextjs not in package.json

Plan:
1. Install @clerk/nextjs via precision_exec

Step 3 — BATCH INPUT (1 call)

precision_exec:
  commands:
    - cmd: "npm install @clerk/nextjs"
  verbosity: minimal

Step 4 — PLAN (0 calls, cognitive)

No output operations needed (package installed)

Step 5 — BATCH OUTPUT (1 call)

# No-op or skip — nothing to write/edit
# If you must make a call, you can read package.json to confirm:
precision_read:
  files:
    - path: "package.json"
      extract: outline
  verbosity: minimal

Total calls in Cycle 2: Target 3 calls per cycle. 2 is acceptable when no output is needed.

Final Validation

precision_exec:
  commands:
    - cmd: "npm run typecheck"
      expect:
        exit_code: 0
  verbosity: minimal

# Result: PASSES

Common Violations and Fixes

Enforcement

If you find yourself making 5+ tool calls in a single DPB cycle, you are violating the protocol. Stop and restructure:

1. Identify which calls are discovery → batch into 1 discover call
2. Identify which calls are input → batch into 1 precision_read/precision_grep call
3. Identify which calls are output → batch into 1 precision_write/precision_edit call
4. Ensure planning happens in text, not via tools

Target: 3 tool calls per DPB cycle.

Summary

• D (Discover): 1 discover call with all queries
• P (Plan): 0 calls (cognitive)
• B (Batch Input): 1 call (precision_read/precision_grep/batch)
• P (Plan): 0 calls (cognitive)
• B (Batch Output): 1 call (precision_write/precision_edit/batch)
• LOOP: Start new cycle if needed
• Validation: AFTER cycle (optional precision_exec)

Total: 3 calls per cycle.

Make this your default mode of operation.