Plans and Workflows

RunWield routes requests by intent so answers stay lightweight, ideas get sharpened before planning, operations stay simple, bounded quick fixes get mechanical validation, and larger changes get reviewable plans.

Routing intents

Intent	Meaning	Primary role
INQUIRY	Direct answer, explanation, repository guidance, or general help.	Guide
IDEATION	Research, interview, PRD, or idea-sharpening before implementation.	Ideator
OPERATION	Direct non-code repository or environment operation.	Operator
QUICK_FIX	Bounded no-plan code implementation.	Engineer
FEATURE	Non-trivial implementation that needs a plan first.	Planner
PROJECT	Large work that needs architecture, approval, and feature slicing.	Architect

INQUIRY

An INQUIRY is handled by Guide. It is for answers, explanations, repository guidance, and other answer-focused help. Guide should answer directly and can send the user back to Router if the conversation turns into implementation work. If the user explicitly asks to preserve or update Guide’s explanation, walkthrough, or report as an ordinary .md document, Guide may load the Documentation Skill and use docs-only Markdown tools. Plans, PRDs, ADRs, docs/domain-language.md, Work Records, Agent Definitions, Skills, prompt templates, source files, and configuration remain outside Guide’s scope.

IDEATION

An IDEATION request is handled by Ideator. It is for exploring an unclear idea, interviewing the user, researching options, or drafting a PRD/synthesis before implementation planning. When the user is ready to build, the next implementation request should go back through Router so it can be classified as FEATURE or PROJECT.

OPERATION

An OPERATION is handled directly by the Operator. It covers non-code repository or environment work such as status, commit, one-off commands, memory maintenance, and explicitly requested dependency upgrades while they do not require code edits. It creates no saved plan and no RunWield validation loop runs after task_completed; the Operator self-verifies.

QUICK_FIX

A QUICK_FIX is handled directly by the Engineer for bounded no-plan code changes. It creates no saved executable plan. After Engineer calls task_completed, the accepted tool call publishes a Workflow Tool Event. RunWield claims that event and runs no-plan Mechanical Validation using the configured local CI command. Each CI repair runs as an independent Engineer session with a bounded failure packet, then RunWield stops after three total repair attempts. It does not run Reviewer, Plannotator code review, Plan Events, Plan Status changes, or worktree merge-back.

FEATURE

A FEATURE creates a Markdown plan under docs/plans/ and sends it through review before execution.

Typical flow:

1. An Agent, usually Router, submits triage_report; the accepted call publishes the routing Workflow Tool Event.
2. Planner writes a plan.
3. The user reviews it in Plannotator. FEATURE Plan Review exposes structured execution controls for executionAgent and collaborationRecommendation; sending Feedback does not persist temporary control changes.
4. On approval, RunWield writes the selected canonical execution metadata and marks the Plan ready for work.
5. RunWield dispatches the recorded executionAgent. Browser UI FEATURE Plans may use Frontend Engineer; other Plans use Engineer. Either execution owner can run autonomously or, in a capable TUI, through blocking Pair checkpoints.
6. RunWield runs workflow validation.
7. The plan is marked verified only after validation records explicit delivery evidence and, for worktree execution, Git proves the sealed implementation commit and verified metadata were merged to the target branch.

Executable FEATURE Plans express ownership with executionAgent: "engineer" | "frontend-engineer". Either owner may use collaborationRecommendation: "autonomous" | "pair" to capture Planner guidance. Pair is a runtime style, not a separate Agent. PROJECT Epics are non-executable containers and should not receive an execution Agent solely because their child work may include browser UI.

The legacy frontend field is retired from new Plan writes and active nonterminal Plans. For compatibility, a legacy executable FEATURE with frontend: true resolves to Frontend Engineer plus autonomous execution; frontend: false has no effect. Legacy PROJECT Epics remain non-executable and any old value is only historical child-slicing context.

Runtime collaboration style is ephemeral active-workflow state, not durable Plan execution metadata. Each execution or recovery derives the style from the current Plan recommendation and current host capability: any executable Plan with collaborationRecommendation: "pair" uses Pair only in a capable TUI, while ACP, headless, and other incapable hosts run autonomously without writing a fallback style to the Plan. If runtime context is lost, recovery re-derives from the Plan and host instead of restoring or asking for a stored selection. Validation repairs preserve the original execution owner but run in an independent Agent session. The repair packet names the checkout, worktree identity when available, Plan file path, and current feedback. It does not copy the implementation transcript or inline the Plan.

Pair checkpoints are implementation-time steering points only. They may approve an increment, request revision, switch the remaining work to autonomous execution, or stop the run in progress; they are not Task Completion, Manual QA, Workflow Validation, semantic review, or browser verification evidence.

PROJECT

A PROJECT is represented as an Epic: a container for the larger design and decomposition state, not a single executable implementation unit. RunWield uses this when the work is too large or ambiguous to run as one plan.

Typical flow:

1. Architect writes the high-level Epic design plan with classification: PROJECT.
2. The user reviews and approves the design in Plannotator.
3. RunWield moves the Epic to ready_for_decomposition.
4. Slicer opens as an interactive PM/lead-engineer session. It discusses vertical slice boundaries, sequencing, dependencies, MVP scope, and deferred work with the user.
5. After explicit user confirmation, Slicer writes draft child FEATURE plans under docs/plans/<epic-name>/.
6. Slicer finalizes decomposition, moving the Epic to ready_for_work for child selection.
7. RunWield advances through child FEATURE plans in Epic order. After a child verifies, RunWield records that child’s advisory Manual QA section in docs/plans/<epic-name>/manual-qa.md before delivery when possible. Work Record handoff then finishes in the old Session, and RunWield creates a fresh Session and starts the next child automatically.

Child FEATURE plans are ordinary FEATURE plans with parentPlan: <epic-name> and optional sibling dependencies. They carry their own lifecycle, worktree, review, validation, and merge history. The parent Epic can later be marked “done enough for now” without pretending it produced an implementation diff.

Epic continuation is strict and enabled by default. RunWield skips terminal child plans (verified, user_verified, and closed_without_verification), examines the earliest remaining child, and stops there if it is on hold, needs recovery, has unmet dependencies, or has an unsupported status. A draft or feedback child opens Planner in the fresh Session; an approved child records readiness and executes; a ready_for_work child executes immediately. Explicit planning outcomes such as “approve for later” stop the chain instead of being converted into execution.

Project decomposition is described in Core product requirements.

Delegated Agent Sessions

Agents may use delegate_agent for bounded foreground assistance without sharing their conversation or tool history. A read delegation can inspect with the parent’s available read-only tools; up to three read delegations may run at once. A write delegation receives the parent’s available write tools, runs synchronously and exclusively in the current worktree, and preserves any partial edits if it fails so the parent can inspect and report them.

Delegated children receive only the brief plus project/repository context. They cannot route workflows, complete parent workflow phases, mutate memory, interview the user, recursively delegate, commit changes, or exceed the parent’s tool permissions.

Plan files

Plans are Markdown files with YAML front matter in docs/plans/. Standalone plans live directly under docs/plans/; child FEATURE plans for an Epic live under docs/plans/<epic-name>/ and point back to the parent with parentPlan.

Use:

wld plans
wld load-plan <name-or-path>

wld plans groups child FEATURE plans beneath their Epic when the parent exists. wld load-plan is Epic-aware: loading an Epic opens or resumes Slicer decomposition, offers child FEATURE selection once decomposition is finalized, or lets the user mark the Epic done enough for now. Loading a child FEATURE follows the normal FEATURE workflow and warns about unverified sibling dependencies when present. Once a child FEATURE is RunWield Verified, the automatic Epic continuation flow uses the same canonical child ordering and dependency checks without a manual “proceed anyway” escape hatch.

For the durable state machine, see Plan Lifecycle.

Remote Shared Spaces

Collaborative planning uses remote-canonical Shared Spaces without replacing the local Plan Lifecycle. A maintainer runs wld plans share <plan> to encrypt a Plan and publish it to a Plan Server. While shared, the local Plan carries non-secret collaboration Front Matter and enters a Shared Plan Lock so normal local mutation is blocked. Collaboration-aware commands own the loop:

• wld plans pull <maintainer-url-or-plan> fetches and decrypts remote Revisions/comments, then launches Planner or Architect with review context.
• wld plans push <plan> publishes the accepted local revision as the next encrypted remote Revision.
• wld plans unshare <plan> destructively deletes the remote Shared Space with maintainer authorization and clears local collaboration metadata only after safe remote delete or explicit deleted-remote cleanup.

The browser review page is for reading, commenting, resolving, reopening, and switching Revisions. Browser push, unshare/delete, and Plan body editing are intentionally deferred. See Self-hosted collaborative planning.

Worktrees and validation

RunWield can execute saved plan work in a linked git worktree. The primary checkout remains the lifecycle metadata root for plan files and worktree registry state. Workflow Validation does not run an automatic Plan Amendment approval gate and does not silently adopt Plan body or definition edits from the execution worktree.

CI repairs run in independent Reviewer-Feedback Engineer sessions. A live repair task_completed result returns only to the validation invocation that dispatched it. It is not written to the root Task Completion journal. The validation owner then reruns Mechanical Validation, so checks, not the Agent report text, decide whether the workflow advances.

If the process stops around such a repair, RunWield reclaims the durable validation checkpoint and reruns Mechanical Validation against the current worktree. It does not replay the repair Agent turn and does not require a second Task Completion. A repair Agent that is blocked stops in plain text rather than reporting completion, and that closing text becomes the pause message so the user sees what stopped it. If a repair turn returns without task_completed, the checkpoint stays paused; retry starts from the saved Plan state and may dispatch a new bounded repair after fresh checks fail.

Workflow validation applies to executable saved plan work: standalone FEATURE plans, child FEATURE plans, and legacy non-Epic PROJECT plans. PROJECT Epics do not run an implementation validation loop themselves; their child FEATURE plans run local validation, semantic review, delivery evidence capture, and merge-back proof before being marked verified. Semantic review runs in narrowing rounds — two full Plan reviews, then verification-only rounds — with findings carried across rounds in a Review Issue Ledger owned by the durable validation checkpoint and repaired by the Reviewer-Feedback Engineer in an independent repair session. Session workflow data projects that checkpoint and cannot close findings or advance validation. The repair’s exact generation is recorded once before checks resume. The repair Agent reads the Plan from the linked worktree path when needed. See docs/plan-lifecycle.md for the full sequence. Missing worktree context for a Git-backed FEATURE is a hard validation failure unless RunWield can recover the exact plan/worktree identity from durable plan metadata, the worktree registry, and Git facts. The full canonical-store, writer, cleanup, and resume rules are documented in Workflow Validation Authority.

Completion-time Work Records

After a supported terminal Plan outcome is durably recorded, RunWield attempts Work Record auto-generation or reconciliation when workRecords.autoGenerateOnPlanCompletion is not set to literal false.

Supported automatic hooks:

• standalone FEATURE validation: after in-place validation_passed, or after worktree merge-back makes the verified Plan visible in the primary checkout;
• post-validation parent Epic resolution: a child FEATURE never receives a record, but if validating a child advances its parent Epic to done_enough, the parent receives one Epic Work Record;
• wld load-plan: after the epic_done_enough lifecycle event succeeds;
• Workspace: after a canonical close-without-verification action succeeds.

For verified standalone FEATURE plans, Manual QA checklist generation and Recorder Work Record generation start together after the Plan is terminal. Manual QA uses the hosted session prompt; Recorder uses a separate non-interactive session, so the two handoffs can overlap safely. RunWield waits for both before printing the Work Record result.

For verified Epic children, Manual QA is different. RunWield asks the Manual QA Agent to call qa_checklist_generated before publication. A valid call appends one section to docs/plans/<epic-name>/manual-qa.md, and that file is delivered with the child and verified Plan metadata. If the Agent omits the tool, gives invalid content, or the write fails, RunWield warns and continues. The checklist is advisory and does not affect verification, delivery, dependencies, Work Records, Epic completion, or continuation.

Automatic generation is best-effort and non-authoritative. A Recorder, Markdown, backlink, or index failure is reported on the calling surface but does not undo verified, done_enough, or closed_without_verification, or user_verified. Successful Markdown writes with index warnings remain successful and can be repaired with wld wr index rebuild; missing or failed records can be retried with wld wr backfill. Automatic hooks target only the Plan that just completed and its needed Epic-child context; broad active+archived discovery belongs to explicit backfill.

User Verified completion

wld load-plan and Workspace Plan detail can mark board-safe FEATURE Plans or PROJECT Epics as User Verified after collecting a required user verification note. This records manual_user_verified, sets status: user_verified, userVerifiedAt, and userVerificationNote, and explicitly does not claim RunWield Workflow Validation, verifiedAt, or new Delivery Evidence. Existing failure, worktree, execution, validation, and human-review metadata remains historical evidence.

User Verified children satisfy dependencies and count toward Epic completion, but summaries split RunWield Verified and User Verified counts. The manual action may complete a ready parent Epic when every child is RunWield Verified with appropriate Delivery Evidence or User Verified, but it does not automatically execute another child.

Transactional lifecycle and recovery

For saved Plans, RunWield treats each lifecycle action as one transaction. Starting execution, finishing implementation, recording validation failure, publishing Direct Delivery, holding/resuming, User Verification, review reopen, and archive/restore all go through the same mutation boundary. Callers should not update Plan Front Matter, the worktree registry, and Git state separately.

The transaction writes a short recovery record when an interrupted operation cannot be safely completed or rolled back. wld load-plan <plan> and wld plans doctor use that record to show concrete actions, such as retrying validation from the recorded worktree, inspecting a merge target, abandoning a specific attempt, or repairing malformed Front Matter.

Direct Delivery verifies a worktree-backed FEATURE only after Git proves the validated candidate commit and verified Plan metadata reached the target branch. Cleanup and Work Record generation happen after that proof; if they fail, the Plan stays verified and the remaining work is recoverable bookkeeping.

Projects without Git skip worktree and branch operations. FEATURE work runs in the current checkout after explicit non-Git execution consent, and lifecycle transactions still protect Plan status and recovery metadata.