07 PAG Guide

🧩 PAG Syntax — Quick Reference

Condensed from the PAG practical guide.

_{See also: PAG Keywords · PAG Grammar (BNF) · Full Specification}

---

· 📄 Document Structure

---
name: document-name
version: 1.0.0
type: AGENT | WORKFLOW | POLICY | TEMPLATE | CHECKLIST | PROTOCOL | TASK
---

THIS {TYPE} {VERB} {description}

%% META %%:
  intent: "What this achieves"
  objective: "Measurable goal"
  context: "Execution environment"
  priority: high | medium | low
  recursion_limit: 3

PHASE 1: Phase Name
    @purpose: "What this phase achieves"

    DECLARE variable: type
    SET variable = value

    VALIDATION GATE:
        ✅ Condition verified
        IF FAIL: REPORT "BLOCKER: reason"

ALWAYS:
    - invariant rule

NEVER:
    - prohibition

---

· 📝 Statement Syntax

VERB target PREPOSITION source [INTO destination]

Pattern	Example
Read	READ "config.json" INTO config
Write	WRITE content TO "output.txt"
Edit	EDIT file old_string: "foo" new_string: "bar"
Search	GREP "pattern" IN "src/" INTO matches
Discover	GLOB "**/*.md" INTO files
Execute	BASH "npm test" WITH timeout: 60000
Spawn agent	TASK "analyze" WITH subagent_type: "Explore" -> result

---

· 📦 Variable Declaration

DECLARE config: object
DECLARE items: array
DECLARE counter: number
DECLARE name: string
DECLARE valid: boolean

SET config.mode = "production"
SET counter = 0

DECLARE before SET. Variables have document-wide scope after declaration.

---

· 🔀 Control Flow

IF condition:
    action
ELSE IF other_condition:
    alternative
ELSE:
    fallback
END IF

FOR EACH item IN collection:
    PROCESS item

WHILE condition:
    ITERATE

TRY:
    risky_operation
CATCH error:
    handle_error

MATCH value:
    CASE pattern_a: action_a
    CASE pattern_b: action_b
    DEFAULT: fallback_action

Always FOR EACH, never FOR alone. Always colon after conditions.

---

· 🔧 Error Recovery

ON ERROR file_modified:
TRY:
    READ target_file INTO current
    MERGE changes WITH current INTO updated
    WRITE updated TO target_file
CATCH:
    REPORT "Recovery failed"

---

· ✅ Validation Gates

Every phase ends with a gate. 3-5 specific, verifiable conditions.

VALIDATION GATE:
    ✅ config loaded and validated
    ✅ source_files.length > 0
    ✅ All records processed
    ASSERT critical_condition
    IF FAIL: REPORT "BLOCKER: reason"

Good: ✅ customer_data.email matches email_pattern Bad: ✅ data looks valid

---

· 🛡️ Constraint Blocks

ALWAYS:
    - READ before WRITE
    - VALIDATE at phase boundaries
    - REPORT state changes

NEVER:
    - SKIP validation gates
    - MODIFY source data directly
    - PROCEED past BLOCKER without confirmation

WHEN processing_sensitive_data:
    ALWAYS:
        - ENCRYPT sensitive fields
    NEVER:
        - LOG plaintext credentials

---

· 🔗 Advanced Constructs

· 🔄 State Machine

STATE_MACHINE workflow:
    STATE pending:
        ENTRY: SEND notification TO reviewer
    STATE approved:
        ENTRY: EXECUTE finalize
    TRANSITION FROM pending TO approved
        ON approval
        GUARD: all_checks_passed

· 📊 DAG

DAG build_pipeline:
    NODE setup:
        READ package_manifest INTO pkg
    NODE build DEPENDS_ON [setup]:
        BASH build_command
    NODE test AFTER build:
        BASH test_command
    PARALLEL_GROUP: lint, typecheck

· 📋 Priority Queue

PRIORITY_QUEUE tasks COMPARE_BY priority:
    ENQUEUE critical_task TO tasks PRIORITY = 10
    ENQUEUE normal_task TO tasks PRIORITY = 5
    DEQUEUE FROM tasks TO next_task

---

· ☑️ Phase Design Checklist

• Each phase has a single objective
• Phase boundaries align with retry/recovery points
• Every phase ends with a validation gate
• Variables declared before use
• Data flow between phases is explicit
• No forward references to later phases

---

· 📄 Document Types and Default Verbs

Type	Verb	Purpose
AGENT	PERFORMS	AI agent behavior
WORKFLOW	EXECUTES	Multi-phase process
POLICY	ENFORCES	Constraint system
TEMPLATE	IMPLEMENTS	Reusable pattern
CHECKLIST	PROVIDES	Task tracking
PROTOCOL	DEFINES	Standard procedures
TASK	EXECUTES	Single objective

---

_{Source: PAG Documentation · Repository}