Resources

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

Gather-Plan-Apply Protocol (GPA Workflow)

The GPA loop enforces a one-call-per-tool-type-per-phase 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 GPA cycle)
   - Call get_skill_content for role-relevant skills
   - This is NOT part of the GPA cycle itself

1. G — GATHER (1-2 tool calls)
   - Check .goodvibes/memory/ files FIRST (failures, patterns, decisions)
   - 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
   - Batch any file reads that need full content alongside discover
   - Output: files_only or locations (minimal verbosity)

2. P — PLAN (0 tool calls, cognitive only)
   - Agent thinks about what it learned from GATHER
   - Plans which files to create/write/edit
   - Plans which commands to run for validation
   - Identifies ALL batch opportunities — same-type ops go in one call
   - Plans the EXACT apply call structure

3. A — APPLY (1-2 tool calls)
   - Writes and edits batched into one precision_write or precision_edit call
   - Validation commands batched into one precision_exec call
   - Key: one call per tool type, everything batched inside it

4. LOOP — Back to G if:
   - Results didn't match expectations
   - Scope changed
   - Validation failed

CALL BUDGET PER CYCLE

Phase	Tool Calls	Type	Purpose
G (Gather)	1-2	`discover` + optional `precision_read`	All discovery + memory reads
P (Plan)	0	Cognitive	Plan apply operations
A (Apply)	1-2	`precision_write`/`precision_edit` + `precision_exec`	All writes/edits + validation
TOTAL	2-4

Core rule: One call per tool type per phase. Never make two precision_read calls in the same phase — batch both files into the one call.

Note on sequential calls: Sequential calls are acceptable when operations depend on each other (e.g., write then verify). Always prefer true batching via internal precision tool arrays (files array, edits array, commands array).

KEY RULES (NON-NEGOTIABLE)

discover batches ALL discovery queries into 1 call — NEVER use separate precision_glob, precision_grep for discovery
Plan steps produce ZERO tool calls — they are cognitive (agent thinks in text)
One call per tool type per phase — if you need 3 files read, batch them in 1 precision_read call
APPLY output = 1-2 calls — precision_write/edit for files, precision_exec for commands
ToolSearch is NOT part of GPA — load tools once at start, don't search mid-cycle
Check memory FIRST — always read .goodvibes/memory/ before implementing

Phase 1: GATHER (1-2 calls)

Initial Setup: Check Memory

Before discovering files, check what's already known. Batch memory reads with your discover call or as a separate read:

# GOOD: Memory reads batched with file content reads
precision_read:
  files:
    - path: ".goodvibes/memory/failures.json"
    - path: ".goodvibes/memory/patterns.json"
    - path: ".goodvibes/memory/decisions.json"
  verbosity: minimal

The `discover` Tool

The discover tool runs multiple grep/glob/symbols/structural queries in parallel, returning results keyed by query ID. This is your primary 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

For reading full file contents, use precision_read in the GATHER phase, batched with memory reads or as a second call if discover results are needed first.

[BAD] vs [GOOD] Gather Patterns

[BAD] — Sequential discovery queries (multiple 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 + batched memory reads (2 tool calls)

# 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

# GOOD: Memory reads in one batched call
precision_read:
  files:
    - path: ".goodvibes/memory/failures.json"
    - path: ".goodvibes/memory/patterns.json"
    - path: ".goodvibes/memory/decisions.json"
  verbosity: minimal

Phase 2: PLAN (0 calls, cognitive only)

Purpose

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

Which files to create/write
Which files to edit (with exact find/replace)
Which commands to run for validation
ALL batch opportunities — same-type ops must be batched

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. Edit the following files:
   - src/app/layout.tsx — wrap App with AuthProvider

3. Validate:
   - npm run typecheck (expect exit 0)
   - npm run lint (expect exit 0)

4. Batch plan:
   - Call 1 (Apply): precision_write with 3 files + precision_edit with 1 edit
   - Call 2 (Apply): precision_exec with 2 commands

[BAD] vs [GOOD] Planning

[BAD] — Vague plan that leads to sequential calls

Plan:
- Create some files
- Maybe edit layout
- Run typecheck

This leads to:

precision_write: ...   # 1st call
precision_write: ...   # 2nd call! (should be batched)
precision_edit: ...    # 3rd call! (could combine with above pattern)

[GOOD] — Specific plan with exact batch structure

Plan:
1. Write 3 files in 1 precision_write call:
   - src/features/auth/types.ts (symbols)
   - src/features/auth/hooks.ts (content)
   - src/features/auth/index.ts (content)

2. Edit 1 file in 1 precision_edit call:
   - src/app/layout.tsx — wrap with AuthProvider

3. Validate in 1 precision_exec call:
   - npm run typecheck
   - npm run lint

Phase 3: APPLY (1-2 calls)

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: count_only

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

Validation via precision_exec (second Apply call):

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

[BAD] vs [GOOD] Apply 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: count_only

Phase 4: LOOP (When to Return to Gather)

Loop Triggers

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

Loop Pattern

# Initial GPA cycle
discover: ...          # Gather call 1
precision_read: ...    # Gather call 2 (memory + key files)
precision_write: ...   # Apply call 1
precision_exec: ...    # Apply call 2 — FAILS typecheck

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

precision_edit: ...    # Apply call 1 (new cycle) - fix the issue
precision_exec: ...    # Apply call 2 (new cycle) - re-validate

Complete Example: Implementing Auth Feature

Cycle 1: Initial Implementation

Step 1 — GATHER (2 calls)

# Call 1: Check memory
precision_read:
  files:
    - path: ".goodvibes/memory/failures.json"
    - path: ".goodvibes/memory/decisions.json"
  verbosity: minimal

# Call 2: Discover landscape
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)

Gather results:
- No memory failures for auth
- No existing auth files
- No auth patterns in use
- User type exists in src/types/user.ts

Plan:
Apply Call 1 (precision_write): Create 3 auth files
Apply Call 2 (precision_exec): typecheck + lint

Step 3 — APPLY (2 calls)

# Call 1: Create files
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: count_only

# Call 2: Validate
precision_exec:
  commands:
    - cmd: "npm run typecheck"
      expect:
        exit_code: 0
    - cmd: "npm run lint"
      expect:
        exit_code: 0
  verbosity: minimal

# Result: typecheck FAILS — missing @clerk/nextjs

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

Cycle 2: Fix Missing Dependency

Step 1 — GATHER (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