DEV Community

Ted Enjtorian
Ted Enjtorian

Posted on

[POG-Task-02] From Governance to Execution: POG Task Design and MVP

#ai #pog #pogtask #promptorchestrationgovernance

From Governance to Execution: POG Task Design and MVP

If governance cannot reach execution, it is merely theory.

Why POG Task Must Be in an "Executable Format"

In the previous article, we established a premise: Prompt Orchestration Governance (POG) cannot hold if it cannot constrain actual execution.

But governance cannot stop at principles or abstract models. It must be able to answer practical questions:

  • Which task is the AI currently executing?
  • Can the state and context of this task be understood by humans?

POG Task v1.1.0 exists precisely to answer these questions.

POG Task v1.1.0 is not a complete task system. It deliberately only satisfies three conditions:

  1. AI can directly read and write it
  2. Humans can directly review it
  3. State can be presented by tools but is not controlled by them

This leads to the entire design logic of v1.1.0.

Physical Structure: File as Truth

Before discussing tools, we must first look at where the data lives. POG Task v0 implemented a strict file structure to ensure portability and reviewability.

Directory Structure

The system exists entirely within your codebase, typically under the pog-task root directory:

pog-task/
├─ README.md                                # Root document
├─ task.schema.json                         # YAML format validation definition
├─ pog-task-agent-instructions.md           # AI Agent "Protocol"
├─ pog-task-design.md                       # System Design
└─ list/                                    # Task list (layered by project/module)
    └── {project}/
        └── {module}/
            ├── {task-title}.yaml           # Structured State Stream (State)
            └── record/{uuid}/record.md     # Execution & Reasoning Log (History)
Enter fullscreen mode Exit fullscreen mode
  • list/{project}/{module}/*.yaml: This is the structured intent of "what needs to be done."
  • record/{uuid}/record.md: This is the reasoning and execution log of "what happened."

Why POG Task Uses YAML as the Task Carrier

In v1.1.0, we chose YAML for its readability and precision.

It satisfies the following:

  • Structured Intent: Supports nested structures and complex checklists.
  • Human and AI Friendly: YAML is extremely easy to read and edit, reducing parsing hallucinations.
  • Strict Validation: Ensures every task complies with specifications through JSON Schema.
  • Git Native: Fits perfectly with Git, diff, and review workflows.

Minimal Task Structure

A POG Task only cares about "governable facts," for example:

type: task
id: "h7a8b9c0-d1e2..."
title: "Improve task governance clarity"
status: "in_progress"
created_at: "2026-02-01T10:32:00Z"
checklist: 
  - task: "Update documentation"
    done: false
Enter fullscreen mode Exit fullscreen mode

This is not a simple workflow, but Structured Intent.

Why Task and Record Must Be Separated

POG Task clearly distinguishes between two types of data:

  • Task List (YAML): What intents currently exist?
  • Record (Markdown): How was this task "executed"?

Therefore, every Task corresponds to an independent execution record file (e.g., record/{uuid}/record.md).

  • Execution steps
  • Rationale for decisions
  • Mid-course corrections
  • Completion condition judgment

This ensures that governance no longer relies on "chat memory" but on re-readable factual records.

POG Task v1.1.0 does not have a dedicated Web UI. The first human interface chosen was VS Code for very pragmatic reasons:

  1. Developers and Agents collaborate here frequently.
  2. Native support for file system and directory semantics.
  3. Plugins can "observe and assist" without "taking over the logic."

Plugin Overview

POG Task Manager Screenshot

The POG Task Manager extension is designed as a passive observer that visualizes your task state without owning the data.

Get POG Task Manager Plugin

1. Explorer View

The plugin doesn't force you to read raw YAML; instead, it provides a structured Tree View in the sidebar:

  • Grouping: Tasks are automatically grouped by project and module.
  • Status Indicators: Icons clearly show if a task is todo, in_progress, or done.
  • Context: The intent is displayed as the primary label.

2. Task ↔ Record Navigation

This is the core "governance action."

  • Clicking a task: Immediately splits the editor.
    • Left side: YAML file.
    • Right side: Corresponding record.md file.
  • If the record doesn't exist, the plugin prompts to create it from a standard template, ensuring every execution has a complete reasoning context.

3. Execution Alignment

  • Copy Prompt: A one-click action to generate a "Handoff Prompt" for your AI agent. This prompt includes the task context and instructions to update the record, bridging the gap between the task definition and the AI's context window.

What the Plugin "Does Not" Do

To maintain a "governance-first" philosophy, the plugin has strict boundaries:

  • No Drag-and-Drop Status Changes: You cannot drag a task to "done." You must update the underlying file or record.
  • No Hidden Database: All data is just text files. If you remove the plugin, your tasks remain 100% readable.

The Role of LLM Agents in POG

In the current architecture, the LLM Agent is responsible for:

  1. Reading task intent
  2. Claiming and executing specified tasks
  3. Writing reasoning processes and artifacts into the record
  4. Updating task status and checklists

The Agent does not have the final say on the task state. It is only responsible for leaving enough clues for humans to understand.

POG Agent Interaction

Agent Protocol: pog-task-agent-instructions.md

To ensure reliable Agent behavior, POG has established a set of strict "Protocols" documented in pog-task-agent-instructions.md. This is not just a document, but an Operation Manual that every Agent must read before acting.

Key highlights of the protocol include:

  1. Layered Path Rules:
    • pog-task/list/{project}/{module}/{task-title}.yaml
  2. Status Transition Protocol:
    • Claiming: Agents must update the status to in_progress and fill in claimed_by.
    • History: Every key action must be appended to the history.
  3. "Intent-First" and "Record Perpetuity":
    • Immediately initialize record.md after creating a task.
    • Original Intent: The user's original request must be recorded in record.md to prevent execution drift.

This protocol transforms the AI execution "black box" into a predictable, observable process.

Conclusion: v1.1.0 as a Governance Defensive Line

POG Task v1.1.0 does not try to make AI faster. It exists to ensure:

Before AI starts "acting autonomously," we still have a full line of sight for governance.

YAML and the VS Code Plugin are not aesthetic choices; they are the embodiment of a governance stance.

10. Roadmap and Future Work

Phase Features
v1.1 Core YAML structure, record.md, Agent flow, VS Code Plugin optimization
v1.2 Nested tasks, automatic Checklist analysis, enhanced history tracking
v2 Web UI + Dashboard, Jira/Git integration, Multi-agent orchestration
v3 Automated evaluation & reporting, KPI metrics, AI governance rules

Complete content at: https://enjtorian.github.io/pog-task/

Top comments (0)