PGF (PPR/Gantree Framework) v2.5

PG가 프로그래밍 언어라면, PGF는 라이브러리다. PG로 자주 실행하는 유용한 패턴(설계, 실행, 검증, 발견, 창조 등)을 정규화한 것이다.

PG 기반 의존성

PGF는 PG(PPR/Gantree Notation)를 기반 언어로 사용한다. PG의 핵심 속성(Parser-Free, Co-evolutionary, DL/OCME, AI_ 함수, → 파이프라인, [parallel], Gantree 노드 문법)은 PG 스킬에 정의되어 있으며, PGF는 이를 상속한다.

PG 표기법 참조: PG 스킬을 로드하여 Gantree 노드 문법, PPR 구문(AI_/AI_make_ 접두사, → 파이프라인, [parallel], acceptance_criteria, Convergence Loop, Failure Strategy), 데이터 타입, 원자 노드 판단 기준을 확인할 것.

PGF가 PG 위에 추가하는 것:

• 실행 모드 — design, plan, execute, full-cycle, loop, discover, create, micro, delegate
• WORKPLAN + POLICY — 실행 계획과 정책 블록
• status JSON — 노드별 실행 상태 추적
• Phase transition — 모드 간 자동 전환 조건
• Session Learning — 세션 간 학습과 전략 적응
• Epigenetic PPR — 컨텍스트 적응 실행, extract-ppr.py 자동 통합
• Runtime Continuation — hook/heartbeat/manual 등 런타임별 adapter 기반 장기 실행 보호
• Design Review — 구현 전 3관점 사전 검증

Current Project PGF State

To check the current PGF state, scan the project's .pgf/ directory:

• List *.md and *.json files in .pgf/
• Read status-*.json for execution progress (summary.done / summary.total)
• Check .pgf/runtime/pgf-loop-state.json for active pgf-loop status. Runtime adapters may mirror this state elsewhere, but .pgf/runtime/ is canonical.

PGF Notation Extensions

PG defines the canonical Gantree node syntax and 6 base status codes (done, in-progress, designing, blocked, decomposed, needs-verify). PGF adds 3 delegation status codes used in delegate mode and AI-to-AI handoffs:

State transition: (designing) → (delegated) → (awaiting-return) → (returned) → (done) (or (blocked) on validation failure).

All other notation rules (5-level depth, [parallel], @dep:, PPR def blocks, Convergence Loop, Failure Strategy, atomicity 15-minute rule) follow PG skill verbatim.

Reference Document Guide

Path convention: {SKILL_DIR} is a runtime-neutral placeholder denoting this skill's root directory (the directory containing SKILL.md). Every agent runtime (Claude Code, Kimi, Gemini, MCP, Agent SDK, etc.) substitutes it with the local path where the pgf skill is installed. Use {SKILL_DIR}/... for all internal references — never hard-code absolute paths or runtime-specific env vars.

Reference documents for this skill are located in the {SKILL_DIR} directory. Load the appropriate file with the Read tool depending on the execution mode and need.

Base Notation (PG 스킬)

PG 표기법의 핵심 문법은 PG 스킬에 정의되어 있다. PGF 실행 시 PG 스킬이 자동 로드된다.

PG 스킬에 정의된 내용은 PGF의 모든 레퍼런스 문서에서 재정의하지 않는다. 중복 발견 시 PG 스킬이 정본(canonical source)이다.

Always Reference

Execution Discipline & Playbooks (실행 규율 — 본질 활용)

모드가 무엇을 하는지는 아래 Phase별 reference가, 어떻게 실수 없이 수행하는가는 이 3종이 준다.

Design Phase (design mode)

Gantree 노드 문법, PPR 구문(AI_/→/[parallel] 등), 데이터 타입, Convergence Loop, Failure Strategy, 원자 노드 판단(15분 룰), 기본 체크리스트는 **PG 스킬(canonical)**을 참조. PGF가 추가하는 표기/검사 항목은 아래 "PGF Notation Extensions"와 "PGF Execution Checklist" 섹션을 참조.

Execution Phase (plan / execute / loop mode)

Discovery/Creation Phase (discover / create mode)

create mode (5-phase autonomous: DISCOVER + DESIGN→VERIFY) and full-cycle mode (4-phase) share the same pipeline spec — see reference/cycle-reference.md in the Execution Phase table above.

Agent Communication & Delegation

Advanced Reference (as needed)

Future protocols (vision, no current implementation): PGF-MCP (typed intent execution over MCP), PGF-A2A (typed subtree handoff between agents). Use the existing execution modes and agent-protocol.md TaskSpec for current AI-to-AI communication needs.

Persona Agents (discover/create mode)

Discovery Engine's 14 personas are independently defined as agent files in {SKILL_DIR}/agents/:

Execution Modes

PGF supports the following execution modes via $ARGUMENTS.

Invocation examples: /PGF design MyProject, /PGF full-cycle ChatApp, /PGF loop start, /PGF discover, /PGF create

$ARGUMENTS parsing rules:

• $ARGUMENTS[0]: mode keyword
• $ARGUMENTS[1:]: project name or target description
• No mode keyword → infer from context (e.g., presence of files in .pgf/ directory)
• Project name only → defaults to design mode

File Path Rules

<project-root>/
    .pgf/
        DESIGN-{Name}.md          # System design (Gantree + PPR)
        WORKPLAN-{Name}.md        # Executable work plan
        status-{Name}.json        # Execution state tracking

{Name} = CamelCase project/task name. Multiple tasks can coexist in the same .pgf/.

Progress Reporting

[PGF] ✓ NodeName (done) | 3/12 nodes done | next: NextNode
[PGF] ✗ NodeName (blocked) | blocker: reason | skip → NextNode

Integrated Execution Process

아래 Step들은 순차 프로세스가 아닌 독립 모드다. 사용자 지시나 PGF 모드에 따라 필요한 것만 실행한다. full-cycle/create 모드만이 여러 Step을 순차 연결한다.

Step 1: design — Gantree Structure Design

Top-Down BFS hierarchical decomposition → down to atomic nodes. Reference: PG skill (Gantree/PPR canonical) + this SKILL.md "PGF Notation Extensions" section for PGF-specific status codes.

Completion criteria: (1) All leaves = atomic nodes (2) PPR def written for complex nodes (3) No circular @dep (4) Checklist passed

Step 2: plan — WORKPLAN Generation

DESIGN-{Name}.md → WORKPLAN-{Name}.md conversion. Reference: workplan-reference.md §2

Step 3: execute — Sequential Node Execution

Node execution based on WORKPLAN-{Name}.md. For [parallel] nodes, use the current runtime's parallel subagent/worktree capability when available; otherwise execute sequentially while preserving dependency order. Reference: workplan-reference.md §4

Step 4: verify — Cross-Verification

Details: {SKILL_DIR}/reference/verify-reference.md

3-perspective verification:

1. Acceptance Criteria — Re-check acceptance_criteria from DESIGN PPR (Lightweight: # criteria: inline)
2. Code Quality — runtime review/simplify capability or direct inspection, verifying reuse/quality/efficiency of changed code
3. Architecture — Compare DESIGN Gantree ↔ actual implementation structure (Lightweight: skip)

Result: passed → complete / rework → rollback target node + re-execute subtree / blocked → report to user. Rework iterations are allowed up to POLICY.max_verify_cycles.

full-cycle

Details: {SKILL_DIR}/reference/cycle-reference.md (covers both full-cycle and create modes)

Automatically execute design → plan → execute → verify as one continuous process. On rework during verify, roll back only the affected subtree and re-execute (up to POLICY.max_verify_cycles times). On session interruption, resume from the last Phase recorded in WORKPLAN/status JSON.

Phase transition conditions:

Opt-in design review (--with-review[=N])

기본 풀사이클은 변경하지 않는다. 사용자가 명시적으로 --with-review 플래그를 줄 때만 design → plan 사이에 review 게이트를 삽입한다.

review 게이트 동작 (reference/design-review-reference.md 참조):

1. design 완료 직후 다관점 SubAgent 검토 실행 (PG/PGF 표기법, 보안, 프로토콜, 아키텍처)
2. 결과 분류: Critical=0, High≤2 → plan 진행. 그 외 → DESIGN revise 후 재검토
3. revise 횟수 ≤ N. N회 초과 시 잔여 이슈 보고 + 사용자 승인 시 plan 진행 (강제 차단 아님)
4. status JSON에 review_iterations, unresolved_issues 만 추가 — 기존 키 불변

Skip rules (Level 1/Micro에 강제 적용 시 과잉이므로 자동 스킵):

• Level 1 (≤3 노드) → 플래그 무시, review 스킵
• micro 모드 → 플래그 무시
• Level 2 이상 → 플래그 적용

Step 5: loop — Runtime-Adapter Auto-Execution

Details: {SKILL_DIR}/loop/loop-reference.md

On /PGF loop start or natural-language equivalent: (1) Verify WORKPLAN exists (2) initialize .pgf/runtime/pgf-loop-state.json (3) Determine mode (DESIGN exists → Standard / absent → Lightweight) (4) Select first node + load execution spec (5) Begin implementation. Afterwards, a runtime adapter continues the next node automatically when supported, or emits the next-node prompt for manual/agent continuation.

Lightweight mode: Loop execution with WORKPLAN only, without DESIGN. # inline comments under WORKPLAN nodes serve as PPR substitutes. Suitable for simple tasks, documentation, refactoring, etc.

Step 6: discover — IdeaFirst Persona Multi-Agent Discovery

Details: {SKILL_DIR}/discovery/discovery-reference.md

Invoke 14 {SKILL_DIR}/agents/pgf-persona-p*.md personas in parallel when the runtime supports subagents. If not, simulate personas sequentially in the current runtime. Model hints inside persona files are advisory only. Integrate results from each stage → save to .pgf/discovery/{step}.md. HAO principle: do not enforce output format, preserve originals unedited.

Step 7: create — Autonomous Creation Cycle

Details: {SKILL_DIR}/reference/cycle-reference.md (unified spec — create is the 5-phase autonomous variant)

Fully autonomous execution without user approval. STEP 7 is replaced by auto_select_idea (vote-based automatic selection).

Step 8: micro — Zero-Overhead Small Task Execution

Details: {SKILL_DIR}/reference/micro-reference.md

Entry: nodes ≤ 10, depth ≤ 3, no external deps, ≤ 30 min. Bypasses WORKPLAN/POLICY/status JSON. In-memory status only. Auto-promotes to full WORKPLAN if bounds exceeded.

Step 9: delegate — AI-to-AI Task Handoff

Details: {SKILL_DIR}/reference/delegate-reference.md

Auto-triggered during execute when should_delegate() → True (capability gap, load balancing, parallel opportunity). Packages context into PG TaskSpec with AuthorityBounds → handshake → await result → validate → merge. Delegation chain tracks depth (max 3) and prevents cycles.

Session Learning (횡단 — 모든 모드)

Details: {SKILL_DIR}/reference/session-learning-reference.md

• Session start: Load .pgf/patterns/ → adapt POLICY defaults
• Session end: Record SessionOutcome to .pgf/sessions/{id}.outcome.json
• Every 10 sessions: Re-accumulate patterns (successful strategies, common blockers)

Scale Detection and Strategy

PG는 3-Level(Level 1~3)을 정의한다. PGF는 이를 상속하고 Large/Multi-agent를 추가한다.

Progressive Formalization: Level 판단은 자동. 자연어 입력 → AI가 복잡도 평가 → 적합한 Level 선택. 실행 중 승격 시 기존 상태 보존.

Execution Rules

1. Parse Gantree → determine hierarchy via indentation
2. Status codes → decide execute/skip
3. @dep: → determine execution order
4. [parallel] → concurrent processing
5. PPR def present → interpret and execute / AI_ inline → execute directly / no PPR → recurse into children
6. Atomicity judgment → 15-minute rule
7. Failure → Failure Strategy + AI Redesign Authority
8. Agent dispatch → PG TaskSpec — 에이전트 파견 시 자연어 대신 agent-protocol.md의 PG TaskSpec 형식 사용. 입출력 타입, acceptance_criteria, failure_strategy를 구조화하여 전달
9. Session start → load patterns — .pgf/patterns/에서 과거 패턴 로드 → POLICY 자동 적응
10. Session end → record outcome — .pgf/sessions/{id}.outcome.json에 SessionOutcome 자동 기록

Runtime Integration

PGF Execution Checklist

기본 Gantree/PPR 작성 체크리스트는 PG 스킬 참조. 아래는 PGF 실행 단계 고유 항목.

Execution Phase

• WORKPLAN-{Name}.md의 모든 노드 status가 terminal(done/blocked)인가
• status-{Name}.json의 summary가 WORKPLAN과 일치하는가
• (blocked) 노드에 blocker 사유가 기록되었는가

Verify Phase (3-Perspective)

• Acceptance: 완료된 각 노드의 acceptance_criteria 재검증 (Lightweight: # criteria: 인라인)
• Code Quality: 변경된 코드를 런타임의 review/simplify 도구 또는 직접 검토로 재사용/품질/효율성 검증
• Architecture: DESIGN Gantree ↔ 실제 구현 구조 비교 (Lightweight: skip)
• Verdict 기록: passed / rework / blocked
• Rework 시: 대상 노드 + 자식 롤백 → 재실행 → 재검증 (max_verify_cycles 이내)
• Blocked 시: 사유 문서화 + 사용자 보고

full-cycle Mode

• design → plan 전이 전 4가지 완료 기준 충족
• plan → execute 전이 시 WORKPLAN + status JSON 존재 확인
• execute → verify 전이 시 모든 노드 terminal 확인
• Verify rework 시 대상 서브트리만 롤백 (전체 reset 금지)
• max_verify_cycles 초과 시 산출물 보존 + abort 보고
• 세션 중단 시 WORKPLAN/status JSON에서 재개 가능 확인

Discovery Archive

• 실행 완료 후 archive-discovery 스크립트 실행
• 아카이브 디렉토리가 날짜(YYYY-MM-DD) 단위로 분리되었는가
• create 모드: Phase 1 완료 직후 자동 아카이브

Delegation & Micro Extensions

• AI_make_ 사역 패턴이 필요한 곳에 사용되었는가
• ≤10 노드 작업에 micro 모드 사용을 검토했는가
• 병렬 에이전트 파견 시 PG TaskSpec 형식을 사용했는가
• delegate 시 AuthorityBounds(can_create/can_modify/forbidden)를 명시했는가
• Delegation chain depth ≤ 3 확인했는가
• 세션 완료 시 SessionOutcome을 기록했는가
• (delegated)/(awaiting-return)/(returned) status를 적절히 사용했는가