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

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  
   - OR batch_engine batch wrapping multiple precision_* tools if DIFFERENT tool types needed
   - 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
   - OR batch_engine batch wrapping precision_write + precision_edit if both needed
   - 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)

# 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

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

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

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

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

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: ...}]

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

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

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

batch:
  operations:
    read:
      - files:
          - path: "src/types/user.ts"
            extract: symbols
    query:
      - type: grep
        queries:
          - id: exports
            pattern: "export function"
            glob: "src/**/*.ts"

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"

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

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

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

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

batch:
  operations:
    write:
      - files:
          - path: "src/features/auth/types.ts"
            content: "..."
          - path: "src/features/auth/hooks.ts"
            content: "..."
    edit:
      - edits:
          - path: "src/app/layout.tsx"
            find: "<App />"
            replace: "<AuthProvider><App /></AuthProvider>"

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: "..."

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

# 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

# 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

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

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

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

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

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

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

# Result: FAILS — missing @clerk/nextjs import

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

Discovery: @clerk/nextjs not in package.json

Plan:
1. Install @clerk/nextjs via precision_exec

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

No output operations needed (package installed)

# 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

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

# Result: PASSES