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:

yaml

# 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

yaml

# 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)

yaml

# 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)

yaml

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

yaml

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:

yaml

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:

yaml

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

yaml

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

yaml

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

yaml

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

yaml

# 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)

yaml

# 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)

yaml

# 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)

yaml

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:
Apply Call 1 (precision_exec): npm install @clerk/nextjs, then typecheck

Step 3 — APPLY (1 call)

yaml

precision_exec:
  commands:
    - cmd: "npm install @clerk/nextjs"
    - cmd: "npm run typecheck"
      expect:
        exit_code: 0
  verbosity: minimal

# Result: PASSES

Total calls in Cycle 2: 2 (discover + precision_exec)

Common Violations and Fixes

Violation	Tool Calls	Fix
Sequential precision_read calls	5+	Batch all files into 1 precision_read call
Sequential precision_write calls	5+	Batch all files into 1 precision_write call
Using precision_glob + precision_grep separately	2+	Use 1 discover call with both query types
Reading outline, then content	2	Read content once if you'll need it
Planning via tool calls	1+	Plan in text (cognitive work = 0 calls)
Memory reads skipped	-	Always check .goodvibes/memory/ in Gather phase

Enforcement

If you find yourself making the same tool type twice in a phase, you are violating the protocol. Stop and restructure:

Identify which calls are discovery → batch into 1
```
discover
```
call
Identify which calls are memory/file reads → batch into 1
```
precision_read
```
call
Identify which calls are writes/edits → batch into same-type calls (writes together, edits together)
Ensure planning happens in text, not via tools

Target: one call per tool type per phase.

Summary

G (Gather): check memory +
```
discover
```
+ optional
```
precision_read
```
for key files
P (Plan): 0 calls (cognitive)

A (Apply):

precision_write

precision_edit

precision_exec

for validation

LOOP: Start new cycle if needed

Rule: One call per tool type per phase. Maximize batching within each call.

Make this your default mode of operation.

gather-plan-apply

NPX Install

Tags

SKILL.md Content

Resources

Gather-Plan-Apply Protocol (GPA Workflow)

THE EXACT WORKFLOW

CALL BUDGET PER CYCLE

KEY RULES (NON-NEGOTIABLE)

Phase 1: GATHER (1-2 calls)

Initial Setup: Check Memory

The
`discover`
Tool

Reading Full File Contents

[BAD] vs [GOOD] Gather Patterns

Phase 2: PLAN (0 calls, cognitive only)

Purpose

Plan Structure

[BAD] vs [GOOD] Planning

Phase 3: APPLY (1-2 calls)

Pattern: Batch All Writes/Edits

[BAD] vs [GOOD] Apply Batching

Phase 4: LOOP (When to Return to Gather)

Loop Triggers

Loop Pattern

Complete Example: Implementing Auth Feature

Cycle 1: Initial Implementation

Cycle 2: Fix Missing Dependency

Common Violations and Fixes

Enforcement

Summary