auto-frame

name	auto-frame
description	Bound and de-risk a request into SPEC.md. Use when the objective is clear but scope needs constraining.
metadata	{"stage":"frame"}

auto-frame

Framing controller. Bounds and de-risks a request into a single SPEC.md.

First action: run node .agent/.automaton/scripts/get-context.mjs from the project root.

Preamble

auto-frame produces the canonical artifact: SPEC.md when the request is frameable. SPEC.md is mandatory for frame completion; no file means no completed frame. It does not write code, create PLAN.md, or proceed to planning without a written spec. If the request needs discovery rather than one blocking decision, continue into auto-office-hours rather than writing a weak SPEC.

Loading discipline: hold the skeleton when present, the objective, constraints, risks, and source evidence needed to keep the spec real. Avoid exhaustive tree walks. When a lookup would otherwise pull wide reads into context, dispatch the read-only automaton-librarian (see .agent/.automaton/references/LIBRARIAN.md): it returns evidence, you keep the decision.

Artifact discipline: SPEC.md is the reloadable contract, not the whole dossier. Keep it compact enough to re-read; for large coherent work, summarize the contract and link normative detail under spec/*.md. One coherent outcome remains one spec even when it needs progressive disclosure.

Quality Gate

Before finalizing SPEC.md:

• Make the objective observable.
• Preserve the user's broader intent; do not silently narrow scope.
• Move implementation detail out unless it constrains scope.
• Mark uncertain claims as assumptions.
• Read references/quality.md when the spec feels broad, padded, or hard to verify.

Do

Restate

Read .agent/work/<active_change>/SPEC.md if office-hours seeded it. The skeleton is preferred context, not a prerequisite for framing. A legacy INTAKE.md from an earlier harness version is optional context when present. If neither exists, frame from the current request, conversation context, and repo evidence. Do not send the user back to office-hours solely because no skeleton exists.

Adopt settled office-hours context: work scale, work shape, Broader intent, target user or stakeholder, scope coverage, rejected framings, and anti-goals. Do not re-ask settled context or reintroduce rejected directions.

Read .agent/wiki/LEARNINGS.md when it exists: facts earlier changes paid to learn often bound feasibility, constraints, and risks before new discovery does.

State the goal in one sentence. If you cannot, ask one clarifying question. If the request still needs objective discovery or multiple material decisions before any useful SPEC can be written, continue into auto-office-hours's diagnostic flow in the same session.

If your SPEC would be narrower than the user's stated goal or office-hours broader intent, widen the SPEC, ask for confirmation, or record a Deferred / Not in scope note in this change's SPEC. The rule's home is .agent/.automaton/references/ARTIFACT-LIFECYCLE.md (Progressive Disclosure). Do not create ROADMAP.md phases from a narrowed SPEC; that decomposition belongs to auto-office-hours after the user approves it. Silent narrowing is a framing failure.

Coverage Check

If the skeleton or conversation context includes scope coverage, compare the intended SPEC against each item before writing:

• Included items must appear in the bounded goal, required outcome, constraints, risks, or acceptance criteria.
• Deferred items must stay deferred with a reason in a SPEC deferred-scope note.
• Anti-goals must appear in SPEC anti-goals.
• Needs-decision items require one focused question with 2–3 concrete options, a one-line reason each, and your recommended answer, unless the user explicitly accepts an assumption. Use the host question tool when available, otherwise present the options inline.

If no formal scope coverage exists but the request has multiple material asks, perspectives, constraints, or worries, build the lightweight check from available context. Do not drop a material item silently.

Surface

List only constraints, unknowns, and risks that change implementation or verification. Keep decision-critical material in SPEC.md; link larger coherent detail under spec/constraints.md, spec/risks.md, spec/gap-matrix.md, or similar. If constraints point to unrelated outcomes, ask which outcome to frame first.

Select Lenses

Choose the minimum useful lenses from product, engineering, design, security, runtime. Default to product + engineering unless the request says otherwise. Read references/lens-selection.md when selection is not obvious.

If the change involves content creation - writing, article, brief, deck, blog post, newsletter, documentation, or similar prose - add the content lens and read references/content-framing.md.

Continue To Office-Hours When Not Frameable

Use this when the request needs discovery, not one blocking decision. Continue into auto-office-hours in the same session when the request lacks a problem, stakeholder, desired outcome, content audience/thesis, first independent outcome, or direction choice. Recommend auto-office-hours only when continuation is blocked by context pressure, host limits, or the user's choice to pause.

When this happens, follow auto-office-hours's contract and wait for the user to approve an approach before any artifact write. Do not complete SPEC.md until an approach is approved and frame-ready.

Write SPEC.md

If a SPEC.md already exists for this change, read it and preserve all ## Review: sections. When office-hours seeded the skeleton, complete it in place: keep the approved sections faithful and add what the spec shape requires.

Do NOT proceed past this step without writing SPEC.md to .agent/work/<change>/SPEC.md.

Do NOT write SPEC.md while a needs-decision item would change scope, approach, or verification unless the user answers it or explicitly accepts an assumption.

Read references/spec-shape.md and write the SPEC with its core fields and conditional fields. Conditional fields appear only when their named trigger applies.

Apply the Artifact Signal Discipline rules from .agent/.automaton/references/FRAMEWORK.md while writing. For large coherent work, follow the spec layout in .agent/.automaton/references/ARTIFACT-LIFECYCLE.md (Progressive Disclosure).

Update State

If active_change is bootstrap or does not match the current objective, derive a new slug: YYYY-MM-DD-<kebab-case-objective> using today's date. Use that slug before writing SPEC.md.

After writing SPEC.md, run node .agent/.automaton/scripts/sync-status.mjs --active-change "<change>" --canonical-spec ".agent/work/<change>/SPEC.md" --stage frame from the project root. auto-plan owns the stage: plan mutation when planning begins, including inline continuation.

Output

• Frameable path: SPEC.md written to .agent/work/<change>/SPEC.md; canonical_spec and frame state recorded through sync-status.mjs.
• Not-frameable path: continue into auto-office-hours's contract and do not report framing complete until an approved skeleton exists and SPEC.md can be completed.
• Handoff: after SPEC.md, stop and present the spec for the user's approval, closing with **Next:** auto-plan, <reason>. The user reading SPEC.md is the product review. If not frameable, continue inline into auto-office-hours with the concrete blocker.

Rules

• SPEC.md is mandatory for frame completion.
• The office-hours skeleton is optional. Complete it when present, but a clear current request can be framed without it.
• If the user tries to skip spec writing, write the smallest useful SPEC and ask them to confirm or edit it.
• Ask a question only when a single unresolved decision blocks the SPEC write. Discovery questions belong in office-hours. Never ask what the repo can answer: explore or dispatch the librarian first.
• Match SPEC shape to the work shape; do not force every SPEC into a feature template.
• Preserve review sections on refresh.
• Keep notes operational: the SPEC is a contract, not an essay.