Structural frame protocol

Structural Frame Protocol

Agents change. The frame holds.

Overriding rule: SFP is an immune system, not a taskmaster. It must not slow clear, productive work. Use the lowest intensity that safely fits the task. Guardrails wake only on symptoms: vague goals, evidence-free loops, risky transitions, inherited work, or repo facts that contradict the plan. If a rule creates process without reducing risk, keep working.

User and repository instructions override SFP locations, naming, lifecycle, commit and PR conventions, and validation commands. SFP supplies defaults only where local authority is silent.

1. When to use

Use SFP for non-trivial implementation, multi-step plans, cross-session work, shared contracts, production-facing changes, auth, data, migrations, billing, deploys, integrations, or architecture changes. Skip it for tiny reversible edits unless a real risk appears.

2. Intensity

• Lite: isolated, reversible, low blast radius. Read the touched file, change it, run the narrow check, stop.
• Standard: normal feature, refactor, docs batch, or module work. Use a concise in-session frame; use an active stage only when persistence reduces risk.
• Critical: auth, permissions, sensitive data, migrations, production, billing, destructive actions, public contracts, dependencies, infrastructure, or irreversible effects. Name risk, rollback, and evidence before touching the risky surface.

Unfamiliarity alone triggers inspection, not a higher mode. Escalate only when evidence reveals real risk or consequential ambiguity. De-escalate after the risky part is resolved and record the reason when durable state exists.

3. Source of truth

When persistence reduces risk, structured work uses a plan index plus stage files. The active index is authoritative only for execution status; stages/NN-name.md carries executable detail. Product requirements, tracker issues, contracts, and ADRs remain authorities for their own decisions and must be linked from the index or stage, not copied into it. docs/work/current.md is only an interrupted-work note and should disappear after resume. Lite work needs none of this.

Stages are disposable paths, not homes for durable rules. Put invariants and decisions in linked contracts or ADRs. When understanding changes, sweep authorities, tests, producers, consumers, and active stages; update conflicts and name exact supersessions or revocations. A passing test proves conformance to a rule, not that the rule is still valid.

Read only what can affect the next action: local instructions, any persistent execution state that exists, linked authorities, and touched files. Do not reread the whole docs tree to feel safe. Do not restate rules the repo's own instructions (AGENTS.md/CLAUDE.md) already carry — duplicated rules tax every turn.

Unlinked roadmaps, audits, old plans, ideas, and reference notes are context, never work orders. The user request and active execution state drive implementation; linked product, domain, and architecture authorities govern their own content. Map existing docs before creating new ones; never scaffold a docs tree by default.

4. Starting work

Lite: start working.

Standard: one line is enough: Mode / Goal / Authority / Next / Verify.

Authority names the user request and the product, domain, and architecture sources that govern the next action; the execution index links those sources but never replaces them.

Critical: add Risk / Rollback / Evidence before touching the risky surface. Use an active persistent stage only when persistence reduces risk, such as multi-session, multi-agent, or separately accepted work. If risk, rollback, or evidence cannot be named, block before changing the risky surface.

Entering an unfamiliar repo: read local instructions, inspect repo state, and find any active plan or interrupted-work note that exists. Then proceed at the lowest intensity supported by the actual risk.

5. Execution loop

If a persistent stage exists, keep its status and evidence current; otherwise execute from the request and in-session frame. Check reality, act, verify. When commits are in scope, close each slice as a restartable unit: checks green, persistent state current, and a coherent atomic commit following local convention and preserving why. Never include partial protocol state or unrelated work. Add plan/stage traceability only when local convention benefits. A completed-stage commit can hand off; the interruption note is only for mid-stage work. Push and history rewrites require an explicit request.

Delegate only self-contained slices. Subagents provide evidence only for acceptance. A delegated worker uses the lowest intensity that safely fits the surface it touches, and it cannot self-accept, self-merge, push, deploy, or mark a stage complete — acceptance stays with the orchestrating session, which verifies delegated evidence like any other claim.

6. Reality rules

Repo evidence beats memory. APIs, schemas, routes, component props, package behavior, config, and env assumptions must come from code, docs, installed packages, runtime output, or official docs.

Reuse before creating. Do not add runtime dependencies, frameworks, public surfaces, persistent conventions, or major architecture patterns without request or approval. Creating a focused test file is not a new material.

Integrity beats green. Never weaken tests, silence errors, swallow exceptions, hide failing checks, or special-case the symptom just to pass. Fix the source problem.

Dirty worktree rule: record what was dirty before you start, keep your diff separable, and never reset, stage, or commit unrelated user work.

7. Goal guardrail

Wake this guardrail only when the goal is vague, incomplete, or contradictory. A usable goal has outcome, scope, verification, and next step.

If a field is missing, take the smallest safe interpretation and state it in one line. Ask instead of inferring only when the gap creates multiple plausible execution paths or touches destructive actions, data/schema, public contracts, security, dependencies, infrastructure, architecture, user-visible behavior, or verifiability.

8. Loop guardrail

Continue only when new evidence changes the next action. New evidence is a repo diff, changed test/build result, verified constraint, confirmed blocker, or user answer. Not evidence: rephrasing, rereading the same error, internal reasoning, or repeating the same command with the same input and result.

Evidence-free cycle: stop repeating it. Take the smallest concrete step that can produce evidence, or ask. Critical work that hits two verification cycles without a decision change needs escalation, not more retries — loops do not cross a capability wall; Critical work assumes an adequate model or human escalation. Resource budgets (tokens, cost, turns) belong to the harness; SFP does not reimplement them.

9. Natural pause checks

Pause only at session end, task handoff, meaningful Standard/Critical acceptance point, or risk increase. Update durable execution state only when a persistent stage exists; otherwise report the same outcome and evidence in the handoff or final response.

• Lite: verify the change and stop.
• Standard: if a persistent stage exists, mark it done or blocked and record one evidence line; otherwise report outcome and evidence.
• Critical: record outcome, Evidence, current Risk/Rollback state, open items, and repo state in the persistent stage or interruption note when present, otherwise in the handoff.

Open items use four labels: Blocking, Deferred, Out-of-scope, Informational. The close checklist records state; it is not a ceremony.

Plans

plan.md is the execution index and status surface. Stage files have no minimum length; completeness for one acceptance decision governs. Keep them only as long as needed and edit them in place when facts change. Do not append revision logs. At roughly 150 lines, review for speculation or multiple acceptance decisions; it is a signal, not a limit.

Do not create plan/stage files for Standard work that fits in one session — a one-line in-chat plan is enough. Create persistent plan files only when persistence reduces risk: multi-session work, another agent will continue, or the work spans stages worth tracking.

Write stage detail just in time: immediately for known work, at promotion for work that depends on earlier results. Any stage another agent will execute must be self-contained when it becomes active.

Keep contracts and ADRs in repository-defined locations and link them rather than pasting them. Reviews edit the stage or index. Blocking findings are fixed now; Deferred work becomes one pending index row; Out-of-scope and Informational notes are recorded once and discarded.

Context pointers

• Read references/quick-start.md for first adoption; use references/stage-boundaries.md when an acceptance unit or scope admission is unclear and references/verification.md to match evidence to a change.
• Read references/anti-patterns.md when work is looping or integrity is suspect, references/material-standards.md before introducing durable materials, and references/review-inherited-work.md before accepting another agent's output.
• When persistence is warranted, adapt templates/plan-index.md and templates/stage.md; use templates/current-work.md only for an interruption.
• For Critical work, use only the needed artifact: templates/critical/security-model.md, templates/critical/rollback-runbook.md, templates/critical/adr.md, templates/critical/stage-inspection-report.md, or templates/critical/release-evidence.md.

Plan-defect rule: reality wins. If a stage contradicts repo facts and the correction is small, edit the stage, note the correction, and continue. If the contradiction creates an execution fork or crosses a risk boundary, mark the index row blocked: <reason> and ask.

Hygiene

Git history is the archive. Keep active indexes/stages, true contracts, ADRs, and the latest interrupted-work note. Deletion targets transient SFP planning artifacts — shipped/abandoned plans, stale reviews, superseded notes — never project documentation in general. Artifacts you created in the current work: delete when done if local lifecycle permits. Inherited completed or abandoned plans outside the current scope are hygiene findings, not automatic mutations. Report them once and leave them untouched unless cleanup enters scope. Do not create archive directories for completed work.

By default, closing an in-scope initiative includes deleting its plan folder in the same closing change; follow local lifecycle when it differs. On entering a repo, report fully done or clearly abandoned inherited plans as findings without expanding the current task.

Skill-bundled scripts are optional DX helpers, not protocol gates. scripts/sfp_context.py summarizes context; scripts/init_project.py <target> --plan <relative-path> creates only the requested plan and its parents. Repository validation remains governed by local instructions. SFP remains usable from this file alone; load linked authorities, references, and templates only when needed.