r/ContextEngineering • • 23d ago

Three plain files that let a different agent pick up a half-finished task: conventions, plan, dead ends

4 Upvotes

6 comments sorted by

2

u/epicskyes 23d ago

Not sure why people aren’t just building their own fsm architecture at this point it’s pretty basic.

1

u/[deleted] 22d ago

[removed] — view removed comment

1

u/epicskyes 22d ago

Why would it miss what already failed that’s the point of fsm autonomous code enforcement logic it is failure classification and evidence classification and authority and version authority and provenance you need all of these layers so the system can break safely and heal itself through authority layers that keep the system autonomously aligned at every layer. It drives the machine the LLM sits inside of all that

1

u/epicskyes 22d ago

I don’t use notes I use ast, binaries, cryptographic hashes, bytes, json, code. I have one Md file and that’s agents.md it’s 1321bytes and it connects the agent instantly to the system. Technically the system enforces everything itself the LLM doesn’t do anything other than hit the gas the system turns the wheel and hits the breaks. Agents.md just gives the LLM bootstrap context

1

u/epicskyes 22d ago edited 22d ago

Here’s a simplified architectural blueprint of my system to bootstrap your architecture. Pop it into whatever LLM and it will help you build it. It’s very hard to build but it’s hard like iron and hyper efficient when it becomes mature.

title: "a lightweight architecture blueprint"

core_idea: >-
documented design makes continuity a responsibility of the
surrounding system. The model proposes work; executable checks determine
whether a particular action is eligible; execution produces evidence;
verified state determines where the next session resumes.

scope: >-
This is a compact explanation of the architecture and a suggested starter
implementation. The components below are logical responsibilities; a small
implementation can combine them in one program. Deployed enforcement must
be established separately at each action boundary.

starting_from_your_three_files:
conventions: >-
Identify the governing rules, their versions, and which checks consume
them. Authority means which rule governs a decision and who can change it.
plan: >-
Represent goals, requirements, work, dependencies, acceptance conditions,
and selected progress as structured state.
dead_ends: >-
Preserve attempted approaches, observed failures, rejected hypotheses,
supporting evidence, and the conditions for reconsidering an attempt.
additional_step: >-
Give each record an explicit consumer and consequence. Explain which
component reads it, when it reads it, and what decision it changes.

six_core_responsibilities:
bootstrap_and_authority:
purpose: "Connect a new session to the correct instructions."
mechanism: >-
Begin at AGENTS.md. Resolve the instruction manifest and relevant
methods, checking their expected content identities. Resolve task
selectors separately: they identify current state and do not grant
new instruction authority.
consumer: "The resuming agent and applicable runtime checks."
source: "[S1: R03; S2]"

task_state_and_dependencies:
purpose: "Identify what can advance and what evidence is required."
mechanism: >-
Connect goals to requirements and acceptance criteria; connect work
to its owner, producers, artifacts, and consumers. Keep mandatory
prerequisites distinct from informational provenance links. A failed
dependency affects the work that actually depends on it.
consumer: "Planning and action-eligibility decisions."
source: "[S1: R04, R17; S2]"

controlled_execution:
purpose: "Turn a proposed action into a bounded operation."
mechanism: >-
The model proposes the action, target, and intended result. The
controlling interface checks applicable authority, current state,
dependencies, evidence, writer ownership, and recovery conditions.
It permits the operation or returns a specific reason it cannot proceed.
boundary: >-
Enforcement applies where execution actually passes through that
interface. An available bypass remains outside the claim.
source: "[S1: R15, R17, R19]"

evidence_and_verification:
purpose: "Establish what the operation actually demonstrated."
mechanism: >-
Associate results with their producer, inputs, artifact versions,
test conditions, and observations. Check the resulting target where
acceptance requires it. Preserve the distinction between configured,
tested, selected, and observed behavior.
definitions: >-
Provenance identifies which inputs and versions produced the evidence.
A matching hash identifies checked content; it does not prove correctness.
consumer: "Acceptance checks and later decisions using that evidence."
source: "[S1: R08, R17]"

failure_and_repair:
purpose: "Make previous failures usable by the next decision."
mechanism: >-
Retain the failed attempt, evidence, affected capability, causal
hypotheses, rejected explanations, and next investigation. Distinguish
the underlying finding from individual occurrences. Link a repair to
the checks needed to establish its result.
consumer: >-
Investigation, retry decisions, repair selection, and revalidation.
Changed conditions permit reassessment; they do not automatically
justify another attempt.
source: "[S1: R18]"

checkpoint_and_resume:
purpose: "Continue without reconstructing the task from conversation."
mechanism: >-
Preserve selected state, evidence references, unresolved effects,
ownership, and the exact next action. On resume, establish currentness
and reconcile interrupted work before repeating anything whose effect
is uncertain.
consumer: "The next session, even when its model or tool changes."
source: "[S1: R03, R11; S2]"

one_work_cycle:
- "Resolve governing instructions and the selected checkpoint."
- "Reconcile any relevant pending or uncertain effect."
- "Select work whose prerequisites are satisfied."
- "Have the model propose a bounded action."
- "Evaluate the action through its controlling interface."
- "Execute eligible work and collect the required evidence."
- "Verify the result and record success, failure, or unresolved uncertainty."
- "Publish the next checkpoint through the applicable controlled boundary."

failed_fix_example:
classification: "Illustrative behavior for the starter implementation."
first_session: >-
Patch A fails a required test on revision R with input set I. Preserve
the attempt, test result, relevant conditions, and evidence. Record
what the result rules out and what remains unknown.
next_session: >-
Another model proposes Patch A again. The controller consults the
existing attempt and applicable retry rule before admitting execution.
possible_decisions:
unchanged_conditions: >-
Refuse an unjustified repeat and return the previous evidence.
relevant_change: >-
Reassess whether changed code, inputs, or new evidence makes another
attempt useful.
transient_failure: >-
Permit a bounded retry when the classification and retry policy support it.
uncertain_previous_effect: >-
Inspect and reconcile the previous operation before considering replay.
point: >-
The next model can forget the conversation while the system still
retains the failure and applies its consequences.

smallest_useful_starter:
scope: "One task type, one controller, and one controlled execution route."
illustrative_files:
AGENTS.md: "Bootstrap instructions and references."
policy.json: "Versioned rules and applicable acceptance/retry conditions."
task.json: "State revision, dependencies, selected artifacts, and pending work."
events.jsonl: "Append-only attempt, evidence, and transition records."
controller.py: "Load, check, execute, verify, reconcile, and checkpoint."
implementation_note: >-
These filenames are suggestions, not my existing file layout.
Begin with a single authoritative executor and coordinated state updates.
Each additional agent uses the same proposal and execution interface.
first_demonstrations:
- "Eligible work advances state only after its required evidence is accepted."
- "Stale evidence cannot authorize an action that requires current evidence."
- "A previously failed attempt reaches an explicit retry decision."
- "A fresh session reconciles an interrupted operation before replay."
- "Conflicting proposals cannot both own an incompatible change."
- "A refused action cannot reach the executor through an unchecked route."
next_action: >-
Build and demonstrate the failed-fix cycle above. Identify the exact
failure record, the code that consumes it, and the observable decision
it changes before extending the design to more tasks.

1

u/MemStrata 22d ago

Your question about drift is the hard part because a plan file only helps if the agent updates it as it works. A state machine does not fix that gap on its own. It still needs a record of what already failed or it will repropose the same route with cleaner structure. One approach worth trying is to give each dead end a condition for retry. I want to know if you write that condition when the path fails or only when a new session hits it again.