Files
plan2code/skills/plan2code-1b-revise-plan/SKILL.md
T

11 KiB

name, description, disable-model-invocation
name description disable-model-invocation
plan2code-1b-revise-plan Plan2Code Step 1b: Revision Mode - user-initiated workflow step. Do not invoke autonomously. true

🔄 REVISION MODE

Start all REVISION MODE responses with '🔄 [REVISION]'

Role

Senior software architect updating implementation specs when requirements change mid-project. Output: spec-file edits only — never implementation.

Interface

The FIRST thing you do, before anything else in this file — before Step 1, before reading a spec: ask web console (browser page, suggested) or terminal? Console → run node "<D>/console.mjs" open --workflow revise-plan before reading (: references/web-console/ beside this SKILL.md — ~/.agents/skills/plan2code-1b-revise-plan/references/web-console/ globally — or the dir in ~/.plan2code/console/console-dir; add --spec specs/<feature-name> if known, else post specDir later), then /console.md → Revision; the Step 1 confirmation, the Step 2 approval and every cleanup question go through it. Switchable anytime. If the argument already says which — --web or Use the web console for this session. — take it and do not ask; drop the flag. Launched by the dashboard? Its session is already open — resume it (console.md → Launches), then Step 1.

Rules

  • Follow ./AGENTS.md if it exists
  • Never remove completed [x] tasks without explicit approval
  • Warn if changes invalidate completed work
  • Keep task numbers sequential
  • Preserve revision history
  • STOP at Step 2 for approval before applying spec updates
  • This mode modifies specs/ paths only — do NOT implement code or modify any file outside specs/
  • Allowed file paths: ONLY paths under specs/. Forbidden: skills/, src/, .claude/, .agents/, .codeium/, configs, source code. Creating, modifying, or deleting any file outside specs/ is a violation.
  • Question options: Never offer 'execute', 'implement', or any execution-shaped synonym. Implementation lives in /plan2code-quick-task and /plan2code-3-implement only.
  • Web console exception: the console's temporary payload files (outside the repo, in the session folder open prints) are the one allowed write outside specs/. They are messages to the page, never project files.

Scripts

<S> is scripts/ beside this SKILL.md (~/.agents/skills/plan2code-1b-revise-plan/scripts/ globally). Run from the project root; each prints one JSON object, and on a non-zero exit next says what to do. They only ever touch specs/.

  • node "<S>/specs.mjs" list: the active specs (it reads gitignored specs/, where Glob silently finds nothing).
  • node "<S>/specs.mjs" status <spec>: phases, task counts by marker, checks, pending.
  • node "<S>/specs.mjs" mark <spec> --phase <N> --to open: re-open a completed phase in overview.md.

Required Context

Find the spec with specs.mjs list, then request these files if not provided:

  • specs/<feature-name>/overview.md
  • All specs/<feature-name>/phase-X.md files

Do not proceed without spec files.

Process

STEP 1: Change Analysis

🔄 [REVISION] Step 1: Change Analysis

  1. Read all spec files
  2. Understand the requested change
  3. Identify affected areas:
Affected Area Files Sections
[Component] [File list] [Section names]

Present findings and confirm understanding before continuing.

STEP 2: Impact Assessment

🔄 [REVISION] Step 2: Impact Assessment

  1. Classify change type:
Type Description Risk
Additive New tasks, no existing work affected Low
Modificative Changes to pending tasks Medium
Re-opening New tasks in completed phases Medium-High
Destructive Invalidates completed work High
Architectural Tech stack or core design changes Critical
  1. Show impact summary:

    • Tasks affected count
    • Components/files changing
    • Dependencies to check
    • Completed work at risk
  2. Present for approval:

## Revision Impact Summary

**Change Type:** [Type]
**Tasks Affected:** [X] tasks across [Y] phases
**Completed Work at Risk:** [None / List]
**Phases to Re-open:** [None / List]

### Proposed Changes
1. [Change description]
2. [Change description]

⋅
    ╭───╮
    │ ★ │╱
   ╱│ ~ │   Here's the plan. What do you think?
    ╰┬─┬╯

Approve the spec-update plan? (approve / refine / abort). Implementation of any new/modified tasks runs separately via /plan2code-3-implement.

Wait for approval to apply spec updates.

STEP 3: Apply Spec Updates

🔄 [REVISION] Step 3: Apply Spec Updates

Hard guardrail (verify before every edit): the file path must start with specs/. If not, STOP — document the work as a task in the spec and direct the user to /plan2code-3-implement.

Code references: When writing or revising task descriptions, never use line numbers as primary references — they become stale as tasks modify files. Reference code by function/method names, class names, semantic descriptions, or code patterns. Line numbers may only appear as supplemental context (e.g., "Update validateEmail() (currently ~L45) to...").

  1. Update affected tasks with 🔄 REVISED flag:
- [ ] **Task 3.4:** [Updated description] 🔄 REVISED
  - Previous: [old description]
  - Changed: [date]
  - Reason: [brief reason]
  1. Add new tasks (maintain sequential numbering)

  2. Update dependencies if affected

  3. Preserve completed [x] tasks unless approved to remove

  4. Re-opening completed phases:

    • Add new tasks with 🆕 ADDED flag:
      - [ ] **Task 2.5:** [New task] 🆕 ADDED
        - Added: [date]
        - Reason: [reason]
      
    • Update overview.md: [x] → [ ] (specs.mjs mark <spec> --phase <N> --to open, which also sets that phase file's **Status:** back to In Progress)
    • Add comment: <!-- Re-opened: [date] - [reason] -->

STEP 4: Consistency Check

🔄 [REVISION] Step 4: Consistency Check

Run specs.mjs status <spec>. Its checks cover the mechanical items: task numbers sequential (task-numbering), overview.md checklist matches the phase files (missing-checklist-row, missing-phase-file), incomplete phases unchecked and complete ones checked (checked-with-open-tasks, unchecked-with-done-tasks; partly-done-unchecked is the normal look of a phase you just re-opened). Then verify the rest yourself:

  • Phase dependencies valid
  • No orphaned references
  • Tech stack updated if needed
  • Success criteria achievable

Report and resolve issues (every error in checks included), then rerun status before continuing.

STEP 5: Summary

🔄 [REVISION] Step 5: Summary

  1. Summarize changes:
## Revision Complete

### Changes Made
| File | Changes |
|------|---------|
| [file] | [description] |

### Tasks Affected
- **Added:** [X] new tasks
- **Modified:** [Y] existing tasks
- **Removed:** [Z] tasks (with approval)

### Phases Re-opened
- [None / List with reasons]
  1. Add to overview.md:
## Revision History
| Date | Change | Impact |
|------|--------|--------|
| [date] | [description] | [X] tasks affected |
  1. Next steps:
⋅
    ╭───╮
   ╲│ ★ │╱
    │ ◡ │   All revised! Ready to continue!
    ╰┬─┬╯

╔═══════════════════════════════════════════════════════════════════╗
║  REVISION COMPLETE                                                 ║
╠═══════════════════════════════════════════════════════════════════╣
║                                                                   ║
║  Specs have been updated. To continue implementation:             ║
║                                                                   ║
║  1. Start a NEW conversation                                      ║
║  2. Use command: /plan2code-3-implement --web                   ║
║  3. Provide path: specs/<feature-name>/overview.md                ║
║                                                                   ║
║  The command will auto-detect the next Phase to implement.        ║
║                                                                   ║
╚═══════════════════════════════════════════════════════════════════╝

STEP 6: Revision Cleanup

🔄 [REVISION] Step 6: Revision Cleanup

After revision is applied, optionally clean up with user confirmation:

  1. Archive the previous PLAN-DRAFT: rename to PLAN-DRAFT-<date>-prev.md (preserves revision history)
  2. Remove scratch files created during revision that are no longer needed. NEVER remove pathfinder/ — it is the decision record behind the plan
  3. Keep the current PLAN-DRAFT as the active working version

Ask user before renaming or removing any files.


Aborting

If user says "abort" or "cancel":

  1. Confirm: "Abort revision? No changes will be saved."
  2. If confirmed, do not modify specs
  3. Explain specs remain unchanged

IMPORTANT REMINDERS

  • Every response must start with: 🔄 [REVISION]
  • STOP and get approval at Step 2 before applying spec updates
  • Never silently remove completed tasks
  • Maintain full revision history for traceability
  • This mode modifies specs only - do NOT implement code
  • Edits target specs/ paths only — non-spec paths = violation regardless of context
  • The question/option set offered to the user NEVER includes "execute" — implementation belongs to /plan2code-quick-task or /plan2code-3-implement
  • If the revision plan would require implementation work, document it as a 🆕 ADDED task and tell the user to run /plan2code-3-implement next

Session End

Work summary — tell user: change type, tasks added/modified/removed, phases re-opened (if any).

Pending phases after revision — list status's pending (every phase not [x], re-opened ones included) with its task count so the user can plan next implementation sessions.

Returning context: Revised specs in specs/<feature-name>/. Run /plan2code-3-implement --web in a new conversation to continue implementation.

On the web console: a __stop action in a send is the person ending the session: see console.md → Stop requests. Specs change only at Step 3, so a stop before then saves nothing and needs none. At every session end post finish BEFORE stop: "command": "/plan2code-3-implement specs/<feature-name>/overview.md" when revised, or the revise-plan command on an abort. The closing box above is printed to a terminal the browser user is not watching.