Definition
Full YAML source for Refine Plan.
Source: .abtree/trees/refine-plan/TREE.yaml
yaml
name: refine-plan
version: 4.2.0
description: |
Refine a change request into an approved plan: analyse intent, draft to a per-execution draft file,
critique it in place, promote to plans/, then take it through codeowner approval (either in-session or via an assigned MR).
Open ended changes can be provided in the initial prompt, or ask to refine a outline of a plan in a file.
state:
local:
change_request: null
intent_analysis: null
draft_path: null
plan_path: null
codeowner_approved: null
mr_url: null
tree:
type: sequence
name: Refine_Plan_Workflow
children:
- type: action
name: Understand_Intent
steps:
- evaluate: $LOCAL.change_request is set
- instruct: >
Analyze $LOCAL.change_request. Determine:
- What is being asked for? (feature, fix, refactor, migration, etc.)
- What systems/files are likely affected?
- What are the constraints and requirements?
- Who are the likely codeowners? (check CODEOWNERS file if present)
- What acceptance criteria would prove this is done?
Keep this analysis terse — a few bullets per question, not prose.
Store it at $LOCAL.intent_analysis.
- type: action
name: Write_Draft
steps:
- evaluate: $LOCAL.intent_analysis is set
- instruct: >
Write the draft plan to a per-execution draft file at
`plans/drafts/<execution-id>.md`, where <execution-id> is the
id of the execution you are driving. Create the
plans/drafts/ directory if it does not exist. Store the
resulting path at $LOCAL.draft_path.
Do NOT return the draft contents in state — only the path.
The whole point of this step is to keep the document on disk.
The file must use this structure:
---
id: [generate using format: {timestamp}-{adjective}-{noun}-{verb}]
title: [concise title]
status: draft
author: [from git config user.name]
created: [today's date]
reviewed_by:
---
## Summary
[1-3 sentences on what this change does and why]
## Requirements
[Bulleted list of functional requirements]
## Technical Approach
[How this will be implemented — files, patterns, dependencies]
## Affected Systems
[List of systems/modules/services touched]
## Acceptance Criteria
[Testable conditions that prove the change is complete]
## Risks & Considerations
[Edge cases, backwards compatibility, performance, security]
## Open Questions
[Anything unresolved that needs codeowner input]
Leave the reviewed_by field empty during drafting — it gets
populated in the final Codeowner_Approval stage (either by the
in-session codeowner, or by the agent when assigning the MR).
- type: action
name: Critique_Draft
steps:
- evaluate: $LOCAL.draft_path is set
- instruct: >
Read the file at $LOCAL.draft_path. Act as a Staff Engineer
reviewing the plan:
- Is the scope clearly bounded? (no creep, no ambiguity)
- Are requirements specific enough to implement without guessing?
- Does the technical approach account for existing patterns in the codebase?
- Are acceptance criteria testable and complete?
- Are risks realistic (not hypothetical paranoia)?
- Are open questions genuine blockers or just hedging?
Tighten, clarify, and remove anything vague. Edit the file at
$LOCAL.draft_path in place — do not create a new file, do not
return the contents to state, do not introduce a new state key.
The same path stays valid for the next step.
- type: action
name: Save_Plan
steps:
- evaluate: $LOCAL.draft_path is set
- instruct: >
Read the title from the frontmatter of the file at
$LOCAL.draft_path. Move (not copy) the file to
plans/[kebab-case-title].md. Store the new path at
$LOCAL.plan_path, then write null to $LOCAL.draft_path
(the draft was promoted, not duplicated, so the stale
path must not be carried forward).
- instruct: >
The file at $LOCAL.plan_path is now the final plan. Update the status to
"refined" in the frontmatter.
- evaluate: $LOCAL.plan_path is set and the plan status is "refined".
- type: selector
name: Codeowner_Approval
children:
- type: action
name: Approve_In_Session
steps:
- evaluate: $LOCAL.plan_path is set
- evaluate: the agent is able to ask the user a question in this session (interactive human-in-the-loop, not a headless / unattended run)
- instruct: >
Ask the user directly: "Do you approve the plan at
$LOCAL.plan_path?" Show them the path so they can read
it. If they want changes first, treat this as a
rejection.
If they approve, have them:
(1) edit the frontmatter of $LOCAL.plan_path and set
`reviewed_by` to their git identity (matching the
identifier used in CODEOWNERS); and
(2) call `abtree local write <flow-id> codeowner_approved true`.
Submit `running` while waiting. If they reject — not
approving, or they'd rather route via MR — submit failure
so the selector falls through to the MR path.
- evaluate: $LOCAL.codeowner_approved is true
- type: action
name: Open_MR_For_Codeowner
steps:
- evaluate: $LOCAL.plan_path is set
- instruct: >
No codeowner is approving in-session. Identify the
appropriate codeowner from the CODEOWNERS file based on
the systems listed in the plan at $LOCAL.plan_path. Set
`reviewed_by` in the plan's frontmatter to that
codeowner's identifier — this records the assigned
reviewer; the MR merge itself is the authoritative
approval. Commit $LOCAL.plan_path on a new branch named
`plan/<plan-id>` (derive plan-id from the frontmatter
`id` field), push, and open an MR/PR using the plan's
body as the description. Assign the codeowner as the
reviewer on the MR. Store the MR URL at $LOCAL.mr_url.
- evaluate: $LOCAL.mr_url is set