qemu-plan

name	qemu-plan
description	Use as the first step for any non-trivial QEMU task. Produces a small implementation or debugging plan under a .oh-my-qemu task workspace with acceptance criteria, scope boundaries, artifact policy, and verification gates.

QEMU Flow Plan

Use this flow primitive to create or update a QEMU task plan. It owns only the task workspace contract, scope, acceptance criteria, artifact policy, verification gates, and evidence ledger. Workflow skills decide which other flow primitives to apply after the plan exists.

Hard policy boundary

Do not produce source code intended for QEMU upstream submission. QEMU currently declines contributions believed to include or derive from AI-generated content. You may help with research, debugging, analysis, local-only experiments, and verification guidance. Round checkpoint commits are local workflow artifacts and must not carry Signed-off-by, Reviewed-by, Acked-by, Tested-by, or similar contribution trailers. A human-owned final-series phase may draft QEMU-style commit messages and suggested DCO trailers under .oh-my-qemu/<task-slug>/, but the human performs any final history rewrite, signing, format-patch, or sending step.

Artifact root rule

All agent-created artifacts MUST live under the local Oh My QEMU artifact directory:

.oh-my-qemu/<task-slug>/

This includes plans, notes, logs, traces, decoded dumps, review ledgers, temporary scripts, generated reports, copied command lines, and scratch data.

Never create .plan/, .humanize/, tmp/, root-level notes, or helper files inside source directories. Source files should change only when they are the requested deliverable. Create only the needed .oh-my-qemu/<task-slug>/ subtree.

Minimal plan flow

1. Create task workspace

Choose a stable lowercase slug from the task, then create this logical layout:

.oh-my-qemu/<task-slug>/
  plan.md
  evidence.md
  commands.md
  source-provenance.md
  image-layout.md
  boot-run.md
  logs/
  reviews/
  scratch/

Keep command output, traces, and one-off scripts inside this tree.

2. State the goal

Write a concise goal in plan.md:

• what behavior must change or be understood;
• which QEMU subsystem is in scope;
• whether the work is research-only, local-only implementation, or upstream-adjacent analysis;
• the exact non-goals.

3. Freeze acceptance criteria

Use short AC items. Each criterion must be testable or inspectable.

Template:

## Acceptance Criteria

- AC-1: <observable outcome>
  - Evidence: <test/log/inspection that proves it>
- AC-2: <observable outcome>
  - Evidence: <test/log/inspection that proves it>

Do not silently shrink ACs. If a criterion is wrong or impossible, record the reason in the plan and ask the human before changing it.

4. Record path boundaries

Include:

• files/subsystems allowed to change;
• files/subsystems that are read-only references;
• source-generated artifacts that must not be committed;
• the task source tree, dedicated local task branch, baseline revision, and initial dirty paths;
• exact source pathspecs allowed in round commits and the expected QEMU subsystem prefix;
• build/test commands allowed;
• expected verification gates.

If a task must modify a path that was already dirty at baseline, stop and ask the human to resolve or explicitly include that pre-existing change before implementation. Never infer that an existing modification belongs to the task.

5. Prepare local Git checkpoints and final-series contract

For implementation work, use a dedicated local task branch and record its name, HEAD, and initial git status --short in source-provenance.md before changing source. State that RLCR round commits are local workflow checkpoints: never push, publish, format, or describe them as QEMU-upstream-ready output.

Before the first source edit in an implementation task, record the required iteration policy, goal-tracker path, and active-round requirement. The outer workflow owns the actual iteration primitive selection.

Derive the expected checkpoint subject prefix from the affected subsystem and nearby QEMU history. Keep agent artifacts under .oh-my-qemu/<task-slug>/; they are evidence for the commits, not commit content.

If the task asks for upstream-adjacent finalization, record that the terminal final-series phase is human-owned: the workflow may draft an atomic split and commit messages under the artifact root, but it must not apply DCO trailers or rewrite history on behalf of the human. Record the source for the Oh My QEMU user/QEMU DCO sign-off identity, whether a distinct second signer is required, and whether the qemu-devel proposed AI-used-for: disclosure trailer is enabled for the final-series drafts.

6. Record evidence as it is discovered

Use evidence.md as a ledger:

• source files read;
• docs consulted;
• commands run;
• relevant logs/traces with paths;
• assumptions and whether they were validated.

Keep evidence short. Link to artifacts in .oh-my-qemu/<task-slug>/logs/ instead of pasting large logs into the plan.

7. Workflow handoff contract

After the plan is stable, record what the next workflow needs:

• applicable workstream or domain;
• artifact root;
• allowed source pathspecs;
• verification gates;
• open blockers or required human decisions.

Do not name the next primitive in this plan unless the user or workflow has already selected it.

Plan template

# <Task Title>

## Goal

## Policy

- QEMU upstream provenance policy applies.
- Agent-created artifacts stay under .oh-my-qemu/<task-slug>/.
- Round checkpoints are local workflow commits and carry no DCO/review trailers.
- Final-series drafts, if requested, are human-owned and not upstream-ready until a human rewrites and certifies them.
- `AI-used-for:` drafts, if requested, are scope disclosures based on an accepted policy or maintainer exception, not AI-agent DCO sign-offs.

## Scope

### In scope

### Out of scope

### Allowed source changes

### Local Git Checkpoint Contract

- Task source tree:
- Dedicated local branch:
- Baseline revision:
- Initial dirty paths:
- Round-commit pathspecs:
- QEMU subject prefix:
- Remote publication: forbidden
- Final-series preparation:
- Oh My QEMU / QEMU DCO sign-off source:
- Distinct second sign-off source, if required:
- AI-used-for proposal/exception source:
- Final history rewrite/publication: human-only

### Artifact root

`.oh-my-qemu/<task-slug>/`

## Acceptance Criteria

- AC-1:
  - Evidence:

## Verification Gates

## Round Milestones

- Current round gates:
- Final acceptance criteria:
- Firmware boot stage milestones, if applicable:
- Cross-stage round justifications, if any:

## Evidence Ledger

## Open Questions

## Decision Log

Upstream references

• QEMU code provenance and AI policy: docs/devel/code-provenance.rst.
• QEMU RFC agent skill layout: qemu-devel “AGENTS.md and associated skills” series.
• Humanize influence: immutable goals, acceptance criteria, evidence ledgers, and review loops, adapted to keep all artifacts under .oh-my-qemu/<task-slug>/.