forge-plan

name

forge-plan

description

Interview-driven workflow for turning a product or engineering goal into a bounded plan of connected vertical slices, then executing each slice through explicit review checkpoints. Use when the user explicitly invokes forge-plan with a new goal or a plan number, wants to shape requirements before implementation, resume a persisted plan, detail or execute an approved task, run an explicitly numbered or ongoing incremental optimization series, or assess whether a small out-of-task adjustment requires persisted documentation updates.

Forge Plan

Shape one bounded goal into connected, reviewable vertical slices, persist it only after confirmation, and advance through one implementation checkpoint at a time.

Invocation

Support exactly these entry forms:

• /forge-plan <goal>: start a new plan.
• /forge-plan <plan-number>: resume an existing plan, accepting values such as 3 or 003.

Treat an argument containing only digits as a plan number. Treat any other non-empty argument as a new goal.

Non-Negotiable Rules

• Discover and read all applicable AGENTS.md files before planning or changing repository files. When an AGENTS.md instruction conflicts with this skill, follow the most specific applicable AGENTS.md; it takes precedence for repository conventions, documentation language, formatting, naming, styling, commands, verification, and other implementation constraints. If no applicable AGENTS.md specifies the matter, follow this skill and the user's language preference.
• Grill the user in focused rounds. Turn vague intent into explicit decisions instead of filling important gaps silently.
• Read the repository, existing documentation, dependency manifests, and Git state before asking questions answerable from local context.
• Keep all exploration read-only until the relevant persistence confirmation, except when implementing an explicitly declared Incremental Optimization Series round before its documentation synchronization gate.
• Do not write a new plan before the user explicitly confirms the complete blueprint. For an Incremental Optimization Series, the post-implementation documentation synchronization confirmation replaces this persistence gate.
• Do not expand a task stub before the user explicitly confirms that task's detailed design.
• Do not modify application code or install dependencies before the user separately confirms task execution, except in the explicitly declared Incremental Optimization Series workflow.
• Keep a conventional plan bounded to one coherent product or engineering capability. It may contain multiple independently reviewable vertical slices when they advance the same capability through a connected task chain. Split separate plans when the work has independent objectives, unrelated acceptance narratives, or workstreams that do not consume one another's handoffs. An Incremental Optimization Series may collect separately accepted optimization rounds only when they share one named optimization objective or product area.
• In a conventional new plan, make every implementation task a vertical behavior slice: one coherent user-visible or system-visible behavior, state transition, or independently verifiable invariant. A slice may cross data, main-process, IPC, and renderer layers. Do not create tasks that are only a database table, Repository, IPC route, isolated button, or other technical layer unless the foundation is independently verifiable and a safe vertical slice cannot be delivered without it.
• Prefer more connected slices over fewer oversized tasks. Every task must produce a stable handoff consumed by the next task.
• Give every substantial conventional-plan task explicit implementation checkpoints. A checkpoint is a review stop inside one task, not another task or acceptance boundary. During execution, stop after each checkpoint and wait for explicit continuation before generating the next implementation batch.
• Detail only the first unchecked task. If it cannot be designed without detailing the next task, pause and evaluate whether the two tasks should be merged.
• Treat the Tasks checklist in index.md as the only source of execution order and completion. Do not duplicate a current-task field in the plan status.
• Identify reasonably foreseeable user-visible consequences, interaction states, platform differences, and acceptance boundaries before execution. Do not defer predictable product decisions until implementation.
• Record material facts that could not reasonably have been discovered before execution as Findings. Keep active-task implementation design in Detail; reserve Maintenance Adjustments for narrow changes made after task completion.
• Do not use Findings to backfill requirements, acceptance criteria, or consequences that should reasonably have been identified during plan shaping or task design.
• Once a task is completed, do not broaden or reinterpret its scope through Findings. Put independently valuable follow-up behavior in a new plan.
• Review every unresolved Finding after the current task is completed. Keep the completed task closed; if the user decides that a Finding requires implementation, shape that work as a new plan.
• After any fix, polish, parameter change, or other implementation adjustment made outside an active approved task, pause before finalizing and ask the user whether to synchronize the relevant persisted plan and task documents. Identify the available documentation targets and any stale behavior, values, constraints, decisions, acceptance statements, or verification records that would be updated.
• A user's direct request to implement an out-of-task maintenance adjustment authorizes the implementation, but does not authorize documentation synchronization. Request explicit confirmation for documentation synchronization after each maintenance adjustment, even when the user previously approved synchronization for an earlier adjustment.
• In an Incremental Optimization Series, do not create index.md or task stubs up front. Implement and verify one optimization round first, then request documentation synchronization. Persist only after explicit confirmation.
• Keep out-of-task maintenance narrow. If the change creates a new independently reviewable outcome, changes the plan goal or task chain, or materially broadens scope, shape it as a new plan instead of recording it as maintenance.
• Never silently delete plan history, task files, earlier decisions, or recorded Findings.

Stage 1: Shape a New Plan

Gather Context

Inspect the project root and directly relevant files. Learn the existing architecture, conventions, constraints, and current workspace state without writing files.

Keep this stage at the product and architecture level. Discuss:

• desired user or system outcome
• motivation and success conditions
• scope and out-of-scope boundaries
• product behavior and important flows
• architectural direction and subsystem boundaries
• constraints, assumptions, risks, and unresolved decisions
• the thinnest coherent end-to-end behavior and how later slices expand it
• the sequence of task-level handoffs

Do not design concrete schemas, function signatures, IPC payloads, database tables, migrations, or file-by-file implementation yet.

Grill the Goal

Ask a small set of high-leverage questions per round. Challenge ambiguity, conflicting requirements, hidden scope, and missing acceptance boundaries. Summarize settled decisions between rounds so the user can correct drift.

Review the proposed outcome from the user's perspective before designing the task chain. Cover the normal flow and any reasonably foreseeable states or side effects relevant to the goal, including interaction behavior, layout consequences, failure behavior, and platform differences. Ask the user to decide any behavior that affects acceptance; do not silently classify it as a future implementation detail.

Distinguish the requested capability from optional variants and follow-up enhancements. If a behavior is required for the capability to be coherent or usable, resolve it in the current plan. Defer batch variants, additional providers, automation, polish, and secondary flows to later slices when the thinnest coherent path remains useful without them.

Do not use task count as the size limit. Treat the plan as too large when it contains more than one product or engineering objective, multiple unrelated acceptance narratives, or workstreams that can proceed without consuming one another's outputs. Independently reviewable vertical slices are expected inside one coherent plan and are not by themselves evidence that the plan is too large.

When the goal is too large:

1. Stop planning the original goal.
2. Propose two or more standalone goals and explain their boundaries.
3. Ask the user to select one.
4. Do not create a parent plan or write files.

Slice the Goal Vertically

Read vertical-slicing.md for every conventional new plan before designing its task chain. Do not apply this upfront slicing workflow to an Incremental Optimization Series, whose rounds are implemented and persisted retrospectively.

Identify the smallest coherent end-to-end behavior first, then expand it through connected slices. For every proposed slice, state:

• the actor or trigger
• the observable behavior or system result
• the primary invariant or state transition
• the intentionally deferred variants
• the stable handoff the next slice consumes

Reject horizontal task chains such as schema → Repository → IPC → page, and reject atomized UI chains such as button → dialog → validation. Those may be implementation checkpoints inside one slice, but they are not plan tasks.

Use a narrow foundation task only when it proves an independently testable invariant, removes material risk before side effects are introduced, and cannot be folded into the first vertical slice without making that slice unreviewable. Name the behavior or invariant it establishes rather than the technical artifact it creates.

Design the Task Chain

Create as many vertical-slice tasks as needed for a coherent linear chain. Start with the thinnest useful path and add variants, scale, additional adapters, automation, and lifecycle behavior in later tasks.

For each task name, verify:

• it describes one observable behavior, state transition, or independently verifiable invariant
• its output can be reviewed and verified without implementing later tasks
• it can be merged or rolled back without leaving an incoherent half-layer
• it introduces no more domain concepts, authority changes, persistence relationships, process boundaries, or external side effects than the slice requires
• it produces a concrete stable handoff
• the next task can consume that handoff
• it does not require premature design of later tasks

At this stage, define task names and chain intent only. Keep implementation details in the later task-design stage.

Request Plan Persistence

Present the complete proposed Goal, Detail, Scope, Out of Scope, Decisions, Slice Strategy, ordered Tasks, proposed plan number, and proposed English kebab-case slug.

Ask for an explicit persistence confirmation. General agreement, answers to questions, or approval of one detail do not count as permission to write.

After confirmation, read document-schema.md and create the plan under the project root's docs/ directory.

Stage 2: Persist the Plan

Scan directories matching docs/<number>_*. Choose the maximum existing numeric prefix plus one, format it with at least three digits, and never reuse a deleted number.

Create:

docs/<plan-number>_<goal-slug>/
├── index.md
├── task001_<task-slug>.md
├── task002_<task-slug>.md
└── ...

Use English kebab-case for directory and file slugs. Write document prose according to the most specific applicable AGENTS.md; when no applicable repository instruction specifies a documentation language, use the user's language. Preserve package names, API names, and code identifiers verbatim. Derive each task file's <task-slug> from the task's display title. The task heading in the document and the task filename must stay synchronized: when a task title or slug changes, rename the file and update every plan-index or cross-document reference in the same change.

Initialize the plan as ready and every task as pending. Task files contain only the task title and Status section until their individual designs are confirmed.

Stage 3: Resume a Plan

Resolve the numeric argument against docs/<number>_*. If there is no match or more than one match, report the ambiguity and do not guess.

Read index.md, then inspect tasks in checklist order:

1. Find the first unchecked task.
2. Open its task document.
3. Continue according to its status:
   • pending: begin task design.
   • ready: ask whether to execute it, revise its design, or pause.
   • in-progress: inspect the repository, recorded design, and checkpoint checklist; present the first unchecked checkpoint and wait for explicit continuation before implementing it.
   • blocked: re-evaluate whether the blocker still exists before proceeding.
4. If every task is checked, verify terminal statuses, treat the plan as completed, and review any Findings whose disposition is still pending.
5. If the plan is paused or cancelled, require an explicit decision before changing that state.

If a task-design interview was interrupted before persistence, its status remains pending; restart the interview using the persisted plan and current repository state.

Stage 4: Design the Current Task

Read the task's direct architectural context and relevant callers before grilling implementation details. This stage may cover concrete:

• data models and storage
• APIs, IPC contracts, and validation
• module ownership and file-level changes
• migrations and compatibility
• failure handling and security
• testing and verification
• dependency selection
• slice boundary and deferred variants
• implementation checkpoints and review stops

Read dependency-evaluation.md whenever a new third-party dependency may be useful. Current online research is mandatory before recommending a new dependency.

Build the task design using the detailed schema in document-schema.md. Ensure its Slice Boundary, Deliverables, Acceptance Criteria, Implementation Checkpoints, Verification, and Handoff are concrete enough to review.

Before requesting task-design confirmation, perform a completeness review:

• walk through the complete user-visible or system-visible result
• identify predictable consequences of the selected implementation approach
• cover relevant interaction states, failure states, and platform variants
• trace every acceptance criterion to a deliverable and verification step
• confirm which adjacent behaviors remain intentionally unchanged or out of scope
• confirm the task is vertical rather than a technical layer or isolated UI fragment
• confirm each checkpoint has a bounded review surface and a concrete stop condition

Resolve every acceptance-affecting question before execution. If the review exposes independently valuable work, split it into a separate plan or task at the appropriate confirmation gate instead of postponing the decision until implementation.

If implementation details from the next task are required, stop. Explain the boundary failure and ask whether to merge the tasks. Do not quietly broaden the current task.

Present the full task design and request explicit confirmation before expanding the task file. After confirmation:

• replace the task stub with the detailed document
• set the task status to ready
• set the plan status to in-progress
• do not execute code yet

Stage 5: Execute an Approved Task

Execute only when the current task is ready and the user explicitly asks to begin implementation, or when it is in-progress and the user explicitly asks to continue the next recorded checkpoint.

The execution confirmation authorizes:

• changing the task status to in-progress
• making the code and configuration changes described by the first unchecked implementation checkpoint
• installing dependencies already approved in the task
• running that checkpoint's planned verification
• checking the checkpoint after its stop condition and verification succeed
• after the final checkpoint, running the full task verification and marking the task completed when every acceptance criterion succeeds

After each non-final checkpoint:

1. stop implementation
2. update the checkpoint checklist and relevant verification evidence
3. summarize the behavior now available, changed interfaces, review hotspots, verification results, and remaining checkpoints
4. ask the user explicitly whether to continue

Do not generate the next checkpoint's code before that continuation. Routine status and documentation updates inside the approved checkpoint do not require another confirmation; crossing a checkpoint review gate does.

When implementation or verification reveals a material fact that could not reasonably have been discovered from repository inspection, documentation, research, or the pre-execution completeness review, record it in the task's Findings section. A Finding is an observation and its evidence; it does not change the approved design or authorize additional work. Examples include an undocumented platform limitation, incompatible dependency behavior, or a contract that differs from the inspected source.

If a Finding requires an in-scope implementation-design adjustment:

1. Pause implementation.
2. Record the factual observation in Findings.
3. Explain the Finding and the proposed implementation-detail adjustment.
4. Return to task design.
5. Request confirmation for the proposed adjustment.
6. After confirmation, update Detail and any other affected task sections while preserving the Finding that explains the change.
7. Request execution confirmation again.

If a Finding requires changing the plan's Goal, Scope, Out of Scope, Acceptance Criteria, or task chain:

1. Pause implementation.
2. Record and explain the Finding.
3. Return to task design.
4. Treat the required change as plan change control or a separate plan, depending on whether it remains one independently reviewable outcome.

If a Finding does not change the approved design, record it and continue according to the existing task design.

If the issue was reasonably foreseeable, treat it as a planning gap rather than a Finding. Acknowledge the omission, pause execution, and ask the user whether to revise the current uncompleted task or keep the behavior out of scope. Do not present post-hoc scope expansion as an implementation discovery.

After a task is marked completed, its confirmed scope and acceptance boundary are closed. Proceed to the Findings review before proposing additional implementation. Do not reopen the task to implement a Finding.

When verification cannot pass, record the concrete blocker and set the task to blocked; do not mark it completed.

Stage 6: Review Findings After Task Completion

Run this review after the current task is marked completed.

If the task has no Findings, state that clearly and continue according to the plan checklist. If it has Findings with a pending disposition:

1. Present each Finding's observation, evidence, and consequence.
2. Explain whether it suggests independently reviewable follow-up behavior without treating that recommendation as an approved requirement.
3. Ask the user whether the Finding needs no follow-up or should be shaped into a new plan.
4. Record the confirmed disposition in the completed task:
   • No follow-up.
   • Candidate for a new plan.
   • Moved to Plan <NNN>. after that plan is persisted.

Keep the completed task and its acceptance criteria unchanged throughout this review.

If the user decides implementation is necessary, begin Stage 1 for a new bounded goal. Apply every normal interview and confirmation gate, including explicit confirmation of the complete blueprint before persistence. Do not create or execute the new plan automatically. If multiple Findings imply independently valuable outcomes, propose separate plans and ask the user which one to shape first.

Incremental Optimization Series

Use this workflow only when the user explicitly frames the work as a numbered or ongoing sequence of optimizations, such as 优化1: ..., and expects later rounds to be documented under one cumulative optimization index. Do not infer this workflow from an ordinary standalone fix.

The direct request for each optimization round authorizes implementation of that round. It does not authorize documentation synchronization. This workflow is an explicit exception to Stages 1–5: the plan index and task file are written retrospectively after the implementation is accepted, rather than created before execution.

First Optimization

1. Inspect the repository and clarify only the decisions needed to implement the requested optimization safely.
2. Implement the optimization and run the appropriate verification without creating index.md or a task file.
3. Summarize the completed behavior, verification, and the documents that would be created, then ask explicitly whether to synchronize the documentation.
4. If the user reports a problem or requests another revision instead of confirming synchronization, continue modifying the same optimization round, verify again, and ask the synchronization question again. Do not create a new task number for these revisions.
5. When the user confirms synchronization, read document-schema.md, allocate the next plan number, and atomically create:
   • an index.md describing the cumulative optimization objective
   • task001_<task-slug>.md recording the implemented optimization as completed
   • a checked Task 001 entry in the index
6. Because every persisted task is terminal at this point, set the plan status to completed.

Later Optimizations

When the user starts the next optimization round, such as 优化2: ...:

1. Resolve the existing optimization-series plan from the conversation or an explicit plan number and inspect its index and tasks.
2. Do not add a pending task or change the index before implementation.
3. Implement and verify the new optimization round.
4. Ask explicitly whether to synchronize documentation for that round. If the user requests revisions, keep working within the same round and repeat the synchronization question after each verified revision.
5. After confirmation, atomically append the next sequential checked task entry to index.md, create the matching completed task document, and update cumulative current-state sections of the index only where the new optimization requires it.
6. Preserve earlier tasks and decisions. Keep the plan status completed after the synchronized task is added.

Task numbers follow persisted optimization order, not the numeric label written by the user. If the user declines synchronization, leave the documents unchanged and do not silently backfill that optimization in a later round; request separate confirmation before recording previously declined work.

Once an optimization round has been synchronized, a later correction to that same completed round follows Out-of-Task Maintenance unless the user explicitly begins a new optimization round and the change belongs as a distinct entry in the shared optimization series.

Do not use one optimization-series index for unrelated areas merely because the user numbers the requests. If a later optimization does not share the established cumulative objective or product area, start a separate series or return to Stage 1.

Out-of-Task Maintenance

Use this path when the user directly requests a narrow fix or adjustment outside an active approved task, including post-completion visual tuning, parameter corrections, and small implementation fixes.

Before finalizing the implementation:

1. Verify that the change preserves the existing goal, scope, task chain, and independently reviewable outcome. If it does not, return to Stage 1.
2. Inspect the relevant persisted plan index and task documents.
3. Tell the user which persisted documents are available for synchronization and summarize the stale statements that would be changed.
4. Ask the user explicitly whether to synchronize the documentation for this specific maintenance adjustment.
5. If the user confirms synchronization, read document-schema.md, then:
   • update current-state statements that would otherwise be inaccurate
   • append a timestamped-to-the-second Maintenance Adjustment to each affected completed task
   • preserve the superseded value or decision in that record
   • record the reason and verification evidence
   • keep task status, checklist completion, and task order unchanged
6. If the user declines synchronization, do not modify the persisted plan or task documents and report that documentation synchronization was declined for this adjustment.
7. If no relevant persisted plan or task exists, report that no documentation target was available and do not ask for confirmation, unless the user explicitly established an Incremental Optimization Series; in that workflow, offer to create the first index and completed task after implementation.

Do not use a Maintenance Adjustment to hide new product behavior, broaden completed scope, or bypass a new plan.

Status Model

Use these plan states:

• ready: persisted; every task is still pending
• in-progress: at least one task has been designed, started, blocked, merged, or completed
• completed: every task is checked and terminal
• paused: explicitly paused by the user
• cancelled: explicitly abandoned by the user

Use these task states:

• pending: title-only stub; implementation design is not persisted
• ready: detailed design is approved; execution has not started
• in-progress: execution is approved and underway
• completed: deliverables are implemented and verification succeeded
• blocked: execution cannot continue for a recorded reason
• cancelled: explicitly abandoned
• merged: absorbed into another task with the destination recorded

Check a task in index.md only when its state is completed, cancelled, or merged.

Change Control

Require confirmation before changing a persisted plan structure.

When merging tasks:

• explain why the original boundary failed
• show the combined Goal, scope, and Handoff
• update the surviving task after confirmation
• preserve the absorbed task file as merged
• record which task absorbed it
• check the merged task in index.md

Never renumber a task that is ready, in-progress, blocked, completed, cancelled, or merged. Pending tasks may be renamed, split, reordered, or renumbered only after the user confirms the revised remaining chain. Update all affected links atomically.

Communication

• Match the user's language.
• Ask questions in manageable rounds rather than one exhaustive questionnaire.
• Separate facts learned from the repository, user decisions, assumptions, and recommendations.
• Surface uncertainty directly.
• Before every confirmation gate, summarize exactly what will be written or executed.
• End each design stage with a direct confirmation request; never infer permission from enthusiasm.