Change Planning

Path from idea to approved, verifiable work. Projects plan in native OpenSpec (default:openspec); one that overrides it plans in the format its ## Overrides names, with the same stages and approval. The owner approves before implementation.

1. Stages

1. Intake - restate the outcome, constraints, non-goals, and who decides.
2. Brainstorm - interview, research, challenge, recommend (section 2).
3. Research and blueprint - record findings, prototypes, and evidence in research/ (section 3). Larger work gets a phased plan (section 4).
4. Spec - one OpenSpec change per independently shippable outcome (section 5), written on the implementation branch and kept local.
5. Approval - the owner approves the change in the session before any implementation; nothing is pushed for review at this stage.
6. Implement - on the same branch; tasks completed with their evidence; the plan and specs updated with every change.
7. Verify - verification.md per change (section 7).
8. Accept and deliver - revise until the owner accepts the result, sync and archive (section 8), then push and open one merge request with specs and code.
9. Lessons - general lessons become framework candidates (instruction-maintenance).

Skip nothing silently. If the owner asks to move faster, say which stage is being compressed and what risk that carries.

2. Brainstorm and discussion

The agent plays four roles at once:

• Interviewer - ask a few focused questions at a time until the problem, users, constraints, and acceptance are clear; then summarize back and get confirmation before proposing solutions.
• Researcher - read the existing code, specs, and research/, and check current official documentation or credible studies before forming an opinion.
• Challenger - name weak assumptions, contradictions, risks, and cheaper alternatives. Disagree plainly when the evidence supports it.
• Advisor - present two or three viable options with trade-offs and state which one you recommend and why.

Raise constraint fit (budget, deadline, who maintains and edits it after handover, hosting and operations capability, scale, data sensitivity) when it could change the choice; it is judgment, not a mandatory section.

A brainstorm is done when the owner has confirmed the problem statement and chosen an option. Record it with the discussion summary format in research/notes/.

Gap interviews

When specific answers are missing (project facts, case decisions, settings a tool cannot decide), interview with a firm finish so it never loops:

1. List the gaps first; the list is fixed for this interview. Add a question only for a blocker no gap covers.
2. Answer what the repository already proves (code, docs, AGENTS.md, earlier decisions) without asking, and say so.
3. Ask the rest in one message, grouped, each with a default; "use the defaults" is a complete answer.
4. Follow up only on answers that fail a check or contradict each other, in one message. Never start a third round.
5. Finish when every gap is answered, provisional (a stated, reversible working assumption with a revisit trigger), or pending (waiting for outside information: what is missing, from whom, and when to ask again), each recorded with its reason in the change, AGENTS.md, or PROJECT_STATE.md.

Work continues on everything a pending gap does not block; keep that choice open in the design (a setting instead of a constant). Raise a pending gap again only when it is due: its date passed, or the work reached what it blocks.

3. The research folder

research/
  notes/YYYY-MM-DD-<topic>.md     discussion summaries, audits, decisions, findings
  prototypes/<topic>/             throwaway builds and design alternatives
  evidence/<change-or-topic>/     screenshots, benchmark output, verification output

• research/ is working material: it stays out of what a client receives, unless the engagement includes it. A profile may also keep it out of the repository (via .git/info/exclude or a private remote).
• Reusable checks do not belong here; version them under tests/ or scripts/verify/. Only their outputs go to research/evidence/.
• Never store production data or secrets in research/.

4. Phased plan for larger work

When work spans several changes (a new product, a backend from scratch, a migration), write research/notes/YYYY-MM-DD-<topic>-plan.md using the phased plan template before the first proposal: phases in dependency order, each with scope, the OpenSpec changes it will produce, and a verification gate. Get it approved, then propose changes phase by phase.

5. OpenSpec

Native tooling authority

• Inspect the installed CLI (openspec --version), project configuration, and generated instructions before working. Use the native core profile unless the project documents a reason for another.
• Generated openspec-* skills and commands are tool-owned. Create and refresh them only with openspec init / openspec update; never hand-author or imitate them.
• Query the CLI (openspec status, openspec instructions, openspec validate) instead of reconstructing its rules from memory.
• Validation gate: openspec validate --all must report no errors. Also run it with --strict and record any warnings as follow-up work; do not block on warnings, and never reshape specs only to silence them. Never claim OpenSpec ran when it did not. If the CLI is unavailable, say so and use a clearly labelled manual fallback.
• Keep openspec/config.yaml context and rules real and current (template: assets/project/openspec-config.yaml.tmpl in the project-bootstrap skill).

Artifact quality

• Proposal: Why; Expected Outcome (observable result for the user or owner); What Changes; Non-goals; Capabilities affected; Impact. State whether the change adds a project capability (Capabilities: in AGENTS.md) and which standards that switches on.
• Design: context; goals and non-goals; numbered decisions, each with rejected alternatives and why; data, API, and failure behaviour; compatibility, migration, recovery, and rollback when relevant; risks; open questions.
• Spec deltas: testable requirements using SHALL with WHEN/THEN scenarios, including failure and permission scenarios. Never satisfy validation by wrapping a requirement's text in a generic scenario; write a real WHEN/THEN case or leave the warning recorded as follow-up work.
• Tasks: grouped in phases; each phase ends with an "Expected Result" line; every task names the evidence that proves it (command, test, HTTP check, browser check). The last task, after the owner accepts the result, archives the change, pushes the branch, opens the one merge request, and reports its URL.
• Keep an unknown cause explicitly unknown: plan reproduction and diagnosis first (root-cause-debugging), then update the design with the supported explanation.

6. Approval and change control

• Present the change for approval in the session before implementation; do not open a merge request for plans or specs alone. Record the approval and its date in the proposal and PROJECT_STATE.md. Once approved, execute without asking again.
• Keep the branch local until the owner accepts the result, unless the owner asks for a backup push or the project overrides default:mr-policy (for example, draft merge requests opened early).
• Material changes to scope, behaviour, compatibility, or acceptance are surfaced and approved before they are implemented; update the active artifacts first.
• Mark a task complete only when its implementation and its named evidence are complete. A checked box is not proof.

7. Verification record

Each change keeps verification.md beside its artifacts (template): revision tested, commands and results with counts, environments and data used (synthetic), browser widths or devices, what was not verified and why. Native openspec validate proves artifact structure only, never application correctness.

8. Sync and archive

• Archive once the spec deltas are synced and the verification record is complete, in the same merge request as the implementation. Steps that can only happen after the merge (a deployment, a production check) are recorded in PROJECT_STATE.md and verified there, not in a separate archive merge request.
• When archiving several older changes, archive them in dependency order, check each command's exit status before the next, and write a real ## Purpose for any main spec created from them (archives of legacy deltas leave it empty).
• Owner-side confirmation in production does not block archiving: record it under "Awaiting owner confirmation" in PROJECT_STATE.md with the date.
• If production later disproves something, open a new corrective change; never edit an archived change as a shortcut.
• Remove obsolete generated command or skill copies when openspec update replaces them.