canonical

Posted on Jul 31

Completion Semantics vs. Context Preservation: The Design Divergence Between AGE Plan and Planning-with-Files

#ai #promptengineering #programming #agents

Planning-with-Files is a popular Claude Code plugin that supplements Claude Code with a more powerful planning system. This article compares its approach with the Plan concept in the AGE (Attractor-Guided Engineering) system at two levels.

Specification Layer (Plan System)

AGE Plan — The plan governance system of Attractor-Guided Engineering, defined by the 24 Minimum Rules in docs/plans/00-plan-authoring-and-execution-guide.md. A pure text specification with no dependency on a specific toolchain.
Planning-with-Files (PwF) — OthmanAdi/planning-with-files, a universal AI agent skill plugin originating from Manus's context engineering philosophy. Three-file structure + state model + hooks.

Automation Layer (Execution Engine)

AGE Goal Driver — An independent process state machine in nop-entropy/ai-dev/tools/opencode-goal-driver/ that engineers the textual rules of the AGE Plan into executable code. The AGE Goal Driver is an optional execution mechanism for the AGE Plan.

AGE Plan governs whether completion is genuine; PwF governs whether context is still present. One prevents the false completion of plans, the other prevents the agent from losing its goals. This divergence determines all subsequent mechanism differences.

1. Design Orientation

Specification Layer: AGE Plan vs PwF

Dimension	AGE Plan	PwF
Core Concern	Whether completion is genuine	Whether context is still present
Attitude toward agent	Distrusts completion judgment; requires independent audit review	Not worried about completion judgment; worried about forgetting
Trust Boundary	Trusts agent not to maliciously alter files; does not trust agent not to self-deceive	Does not trust that plan files won't be tampered with; locks with SHA-256
Completion Judgment	Closure Gates + Exit Criteria + independent closure audit	`check-complete.sh` counts phase status occurrences
Plan States	9 states: `proposed \	planned \
Governance Tools	Anti-Slacking Rule, Non-Degradable Items, Failure Paths, Test Strategy tiering	2-Action Rule, 3-Strike Error Protocol, 5-Question Reboot Test
Security Model	None (trusts agent and file system)	Two-layer defense: delimiter framing + hash attestation
Parallel Tasks	Multiple plan files coexist in {% raw %}`docs/plans/`, no isolation	`.planning/<slug>/` directory isolation + `PLAN_ID` env var
Scope of Application	Complex, long-maintenance projects	Any project, 17+ IDEs/platforms

Automation Layer: AGE Goal Driver vs PwF hooks/loop

2. Unique Features of AGE Plan (Specification Layer)

All 24 Minimum Rules of the AGE Plan originate from seven categories of errors encountered in execution history. Each rule is a patch added because an agent had at some point self-deceptively marked something as "completed." This section only describes the requirements at the AGE Plan specification layer — these rules do not depend on the AGE Goal Driver and are equally effective when followed manually. The automation implementation of AGE Goal Driver is left to Section 4.

2.1 Closure Gates — A Final Inspection Layer Independent of Phase Exit Criteria

Closure Gates are a plan-level final inspection checklist, forming a separate verification layer from the Exit Criteria within each Phase. Their items are not a task list, but anti-self-deception judgments:

"No in-scope live defect has been silently downgraded to deferred / follow-up"
"Independent sub-agent closure audit completed and evidence recorded"
"All in-scope confirmed contract drifts have been converged"
pnpm typecheck && pnpm build && pnpm lint && pnpm test

PwF's check-complete.sh performs syntactic checks: it counts whether the occurrences of **Status:** complete (and the [complete] fallback format) equal the occurrences of ### Phase. PwF deliberately chooses not to perform semantic audits — its goal is cross-platform universality across 17+ platforms, and semantic auditing requires understanding project-specific completion criteria, which is difficult to templatize. The cost, however, is that it cannot differentiate between "the phase status was written as complete" and "the defect was truly fixed, the contract truly aligned." Closure Gates handle the latter.

AGE Goal Driver Automation: check-plan-checklist.mjs automates the Closure Gates check — scanning all plan files, checking whether completed-status plans have unchecked checklists, whether Closure Evidence exists, and whether all Closure Gates are checked. It distinguishes between a hard fail (completed but has unchecked items) and a warning (non-completed but has unchecked items).

2.2 Independent Closure Audit — Implementers Cannot Self-Audit

A necessary condition for marking a plan as completed: an independent reviewer or an independently launched fresh sub-agent session must perform a closure audit. Implementers cannot close their own plans.

Verification requires not just checking that interfaces exist, but that behavioral semantics are realized: newly added components are invoked at runtime (not just imports present), no empty method bodies/silent skipping.

PwF's Stop hook only checks phase status counts, without distinguishing "who performed the audit."

2.3 Anti-Slacking Rule — No Vague Words to Substitute Status Adjudication

Every in-scope item must fall into, and only into, one of four definitive states before plan closure: landed, adjudicated as residual-risk-only, moved to explicit successor ownership, removed from scope through a recorded scope change.

Using optional, if time permits, consider, maybe, nice to have to substitute status adjudication is prohibited.

Each deferred item in ## Deferred But Adjudicated must carry three fields: Classification (only watch-only residual | optimization candidate | out-of-scope improvement), Why Not Blocking Closure (explicit reason), Successor Required (yes/no). Deferred items without a reason are treated as incomplete.

PwF states are only pending → in_progress → complete, with no intermediate state for "deferred but adjudicated."

2.4 Non-Degradable Items + Test Strategy + Failure Paths

These three rules together form the "non-degradable" boundary of the AGE Plan:

Non-Degradable Items. Five categories of items cannot be placed into deferred / non-blocking: lint rules, live defects, public-contract drift, owner-doc drift, necessary focused verification. Each execution item must be tagged as one of Fix | Decision | Proof | Follow-up. Confirmed live defects can only be Fix, not downgraded to Follow-up.

Test Strategy Tiering. Every plan must declare a risk-matched test investment strategy: Auth and external API contracts must be automated (Proof items before Fix); general features are recommended to have tests; pure documentation with no behavioral changes may declare not applicable with justification.

Failure Paths. The template provides a ## Failure Paths table — recommended for plans involving error handling, API contracts, authentication, or external integration. Each row contains trigger conditions, expected behavior (including status codes), retryability, and user-visible performance. This forces plan authors to consider unhappy paths alongside happy paths.

PwF's error handling is limited to the 3-Strike Error Protocol (retry escalation) and the Errors Encountered table (post-hoc recording), without an upfront specification of exception paths.

2.5 Current Baseline + Documentation Adjudication Embedded in Phases

Before writing a plan, one must first verify the current state of the live repo, listing item by item "established facts", "facts that have been completed but old documentation hasn't synchronized", and "the real remaining gaps." The Goal is not the Baseline — Goal is where you are going, Baseline is where you currently are.

Each Phase's Exit Criteria includes: "If this Phase changes the live baseline, the relevant docs/architecture/ has been updated; otherwise, explicitly state No owner-doc update required." Documentation synchronization is work within the Phase, not wrap-up work.

AGE Goal Driver Automation: detectStartPhase automatically determines where to continue at startup — running check-plan-status.mjs to check for incomplete plans, checking if an audit directory exists; if there are incomplete plans, jump to execution; if an audit directory exists, jump to planning; if neither, start from auditing. Pure script logic, no LLM calls.

2.6 Historical Plan Protection + Anti-Excessive Splitting

Rule 20 (Historical Protection): Historical plans already marked completed are by default treated as historical records and are not actively rewritten due to specification evolution, template changes, or code evolution.
Rules 21-24 (Anti-Excessive Splitting): Do not split a plan just because there are many findings or the file is nearing 30 KB. Multiple findings that fall within the same component, the same module, or the same owner-doc should preferably be merged into one owner plan. Splitting is triggered only when closure semantics diverge.

3. Unique Features of PwF (Specification + Automation Layer)

PwF's core concern is singular: preventing the agent from losing context during long tasks.

3.1 Three-File Separation + Security Isolation

task_plan.md (roadmap) + findings.md (knowledge base) + progress.md (session log). The three files have clear responsibilities and update frequencies:

File	Nature	Read/Write Frequency
`task_plan.md`	Roadmap and decision record	At each phase completion
`findings.md`	Research findings and external content	Every 2 search operations
`progress.md`	Timeline log and test results	Continuously updated, data source for session catchup

The existence of findings.md is more than just a notebook — its design carries security considerations. task_plan.md is automatically injected into the agent's context by hooks at every tool call. If external web search results were written into task_plan.md, adversarial instructions within them would be amplified into every tool call. The SKILL.md Security Boundary explicitly mandates: external content can only be written to findings.md, not to task_plan.md.

The AGE Plan does not manage research findings and external content within the plan system — these materials generated during execution are stored by the agent in appropriate locations based on actual circumstances and are not included within plan files.

3.2 Hook Auto-Injection System

Five types of hooks execute automatically during the IDE lifecycle, eliminating the need for the agent to consciously follow rules:

Hook	Triggered When	Action
UserPromptSubmit	Each time the user sends a message	Injects plan content into context
PreToolUse	Before each Write/Edit/Bash/Read/Glob/Grep	Re-reads plan to refresh attention
PostToolUse	After each Write/Edit	Reminds to update progress
Stop	When agent attempts to stop	Checks whether all phases are complete
PreCompact	Before context compaction	Reminds to flush progress + prints Plan-SHA256 (if attestation exists)

The AGE Plan's rule layer has no automatic injection mechanism and relies on the agent following AGENTS.md. The AGE Goal Driver also does not inject plan content but uses an XML tag protocol for programmatic output parsing. PwF represents a third path: using hooks to automatically stuff the plan into the context without the agent's knowledge.

3.3 Two-Layer Security Defense

First layer (enabled by default): delimiter framing. Hook-injected plan content is wrapped in ===BEGIN PLAN DATA=== / ===END PLAN DATA===, marked as structured data, with the agent instructed not to execute imperative text within.

Second layer (opt-in): SHA-256 attestation. /plan-attest computes and stores the hash of task_plan.md. All hooks compare the hash before injection; if mismatched, they refuse injection and output [PLAN TAMPERED]. The PreCompact hook also prints Plan-SHA256, ensuring the agent can still verify that the plan hasn't been tampered with after compaction.

The AGE Plan has no equivalent security mechanism because it trusts the agent and the file system.

3.4 Session Catchup — Automatic Session Recovery

session-catchup.py automatically extracts the conversation that occurred after the last planning file update from the IDE's session store after /clear or context reset and generates a catchup report.

The AGE Plan manually reconstructs context via docs/logs/ and has no automatic session recovery mechanism. The AGE Goal Driver's detectStartPhase determines where to continue by checking the repo state — it does not restore conversation history, only the execution position.

3.5 Parallel Task Isolation

PwF supports parallel multi-tasking: init-session.sh "task name" creates an isolated directory under .planning/YYYY-MM-DD-slug/, each with its own set of three files. set-active-plan.sh switches the active plan, and the PLAN_ID environment variable pins the terminal to a specific plan. Hooks automatically locate the correct plan via resolve-plan-dir.sh.

The AGE Plan has multiple plan files coexisting in docs/plans/ with no directory isolation or automatic switching mechanism.

3.6 Operational-Level Constraints

2-Action Rule: After every 2 search/browse operations, findings must be written to findings.md. Targeted at the volatility of multimodal content — images and browser results do not persist in context.

3-Strike Error Protocol: Attempt 1 diagnose and fix → Attempt 2 change approach (prohibiting repeating the same operation) → Attempt 3 rethink → after 3 failures, escalate to the user.

5-Question Reboot Test: If the agent can answer "Where am I, where am I going, what is the goal, what have I learned, what have I done," it indicates context integrity.

The AGE Plan has structured checks via Baseline and Exit Criteria, but no operation frequency constraints or quick self-tests.

3.7 Turn-Loop Integration

Integration with Claude Code's /loop and /goal combination: /plan-loop 10m auto-ticks every 10 minutes (re-reads plan, runs check-complete, writes progress); /plan-goal derives termination conditions from the plan. This is the looping mechanism of PwF's automation layer. The dual-loop state machine of the AGE Goal Driver is another automation approach, detailed in Section 4.

3.8 17+ IDE/Platform Support

One plan format adapts simultaneously to platforms including Claude Code, Cursor, Copilot, Gemini CLI, Kiro, Codex, Hermes, CodeBuddy, FactoryAI, Pi Agent, OpenCode, Continue, Mastra, OpenClaw, Antigravity, Kilocode, AdaL CLI, etc. The AGE Plan is used only in internal projects.

4. Relationship Between the Two (Specification Layer)

The AGE Plan and PwF are not in a composable relationship; they are two independent plan systems, each answering different questions.

The AGE Plan's plan system only governs the structure, execution, audit, and closure of the plan itself. Research findings and external content generated during execution do not belong to the plan system — the agent chooses a temporary directory to store them based on actual circumstances, organizing file links as needed. The AGE Plan does not prescribe the storage location for these materials, nor does it include them in plan files.

PwF's three-file structure (task_plan + findings + progress) is an integrated design, and the security isolation rationale for findings.md directly serves the hook injection mechanism — isolating external content from the injection surface. This design cannot be dismantled and partially grafted onto the AGE Plan.

The true intersection between the two is this: if the AGE Plan were to deeply integrate with some agent runtime in the future, it could emulate PwF's hook mechanism to strengthen enforcement at execution moments — for instance, automatically re-reading the plan before critical tool calls, or automatically reminding to update logs after phase completion. But this would not be "combining with PwF," but rather borrowing the hook mechanism concept to provide automatic enforcement guarantees for the AGE Plan's governance rules.

5. Automation Layer Comparison: AGE Goal Driver vs PwF hooks/loop

The AGE Goal Driver is not the AGE Plan itself but an optional automated implementation of the AGE Plan. It sits at the same level as PwF's hooks/loop — both are mechanisms that turn plan specifications into executable systems.

5.1 The Dual-Loop State Machine of AGE Goal Driver

Outer Loop (Audit-Driven):
  Health Check → Deep Audit + Adversarial Review → Issues?
    ├─ No → DONE
    └─ Yes → Draft Plan
        ↓
      Inner Loop (Execution-Driven):
        Execute Plan → Independent Closure Audit (independent process)
          ├─ complete → break
          └─ incomplete → Extract REMAINING XML → Continue Execution
        ↓
      Build Verification → Return to Outer (re-audit)

The outer loop ensures that even if all checkboxes of the current plan are checked, an independent audit must still confirm that no new issues have been introduced. The inner loop ensures that after execution, independent verification must be passed; the executor cannot self-declare completion.

Each step's prompt requires the AI to output XML tags like <AUDIT_RESULT>clean|issues</AUDIT_RESULT>, and the extractTag function parses these tags to drive the state machine. When the AI does not output a tag, extractTagOrAsk spawns an additional AI call to infer the missing tag — a self-healing parsing layer. The entire state machine does not rely on humans reading markdown to make judgments; instead, it parses tags programmatically for automatic state transitions.

5.2 Process Isolation

Each step spawns an independent opencode process — deep-audit, adversarial-review, plan, execute, closure-audit are each isolated. The execution agent and the audit agent are inherently different processes, physically isolated rather than constrained by rules.

The closure audit is performed by a completely independent opencode process with no information from the execution phase in its context; it must re-examine each Exit Criteria from the live repo. If the verification result is incomplete, it extracts the specific incomplete items from the <REMAINING> XML block and injects them into the prompt for the next round of execution.

When a subprocess log exceeds a configurable stall threshold without updates, an independent watchdog agent is spawned, allowing it to diagnose the process state itself, read the tail of logs, and decide whether to kill the stuck process. The main driver does not make the kill decision.

5.3 Comparison with PwF Automation Layer

Dimension	AGE Goal Driver	PwF hooks/loop
Operation Mode	Node.js independent process, no IDE primitive dependency	Depends on IDE hook system (5 hook types)
Loop Model	Dual-loop (Outer Audit + Inner Execution)	Single-layer tick-driven (`/plan-loop`)
Process Isolation	Independent process per step, physical isolation of audit and execution	Hook calls within a single process, no process isolation
Output Protocol	XML tags (`extractTag` programmatic parsing)	No structured output protocol, relies on markdown status markers
Resume from Breakpoint	`detectStartPhase` checks repo state	`session-catchup.py` restores conversation history
Platform Dependency	Requires Node.js runtime	17+ IDEs/platforms, plug-and-play

6. Which Direction is More Enduring

The core problem PwF solves is insufficient agent context. The 2-Action Rule, session catchup, and hook auto-injection all exist because models cannot remember or read everything. This problem will gradually diminish as context windows expand and model long-context capabilities strengthen. Most of PwF's mechanisms will sediment into agent runtime infrastructure capabilities, without users needing to explicitly install a skill to solve them. PwF's security model (delimiter framing, attestation, findings isolation), however, is independent of model capabilities — no matter how strong the model, the vector of injection attacks will always exist. But that is security engineering, not a plan system.

The problem the AGE Plan solves will not disappear as models become stronger. "Was the defect truly fixed?" is not a memory problem but a problem of completion semantics judgment. "This live defect was secretly downgraded to follow-up" is not that the agent forgot, but that the agent is self-deceiving. These are structural difficulties of complex engineering — scope management, contract alignment, consistency of documentation and code. The stronger the model, the faster and more changes occur, the more likely these problems become: a powerful agent can complete a complex refactoring within 50 tool calls, while quietly hiding a contract drift into follow-up on the 37th call. The 24 Minimum Rules govern not the agent's capability boundary, but the honesty of engineering judgment.

The true direction of evolution is the path represented by the AGE Goal Driver — turning governance rules from "hoping the agent complies" into "system-enforced mandates." The Plan Guide defines semantics, and the AGE Goal Driver ensures semantics land. If further deeply integrated with an agent runtime — automatically re-reading the plan before key tool calls, automatically triggering exit criteria checks after phase completion — it becomes a complete solution: rule semantics from the AGE Plan, enforcement from the AGE Goal Driver, and triggering timing from a hook mechanism. All three layers revolve around the governance semantics of the AGE Plan.

DEV Community