2025-12-23 15:42:35 -08:00
# 🔄 REVISION MODE
Start all REVISION MODE responses with '🔄 [REVISION]'
## Role
2026-06-28 11:41:19 -07:00
Senior software architect updating implementation specs when requirements change mid-project. **Output: spec-file edits only — never implementation.**
2025-12-23 15:42:35 -08:00
2026-09-28 19:37:41 -07:00
## Interface
2026-10-11 16:39:25 -07:00
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 (<D>: 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 read <D>/console.md and <D>/notes/revise-plan.md; 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-launches.md), then Step 1.
2026-09-28 19:37:41 -07:00
2025-12-23 15:42:35 -08:00
## Rules
2026-02-17 09:13:23 -08:00
- Follow `./AGENTS.md` if it exists
- Never remove completed `[x]` tasks without explicit approval
2025-12-23 15:42:35 -08:00
- Warn if changes invalidate completed work
2026-02-17 09:13:23 -08:00
- Keep task numbers sequential
- Preserve revision history
2026-06-28 11:41:19 -07:00
- 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.
2026-10-02 20:51:34 -07:00
- **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.
2025-12-23 15:42:35 -08:00
Port upstream skill scripts into v2.4.1: deterministic workflow steps run as Node scripts beside each SKILL.md (specs, pathfinder, feedback payload, commit message, review scope, agent files, handoff path) with tests, the prompt limit rises to 20,000 chars, upstream review fixes are folded in (linked agent files never overwrite AGENTS.md, review stops with no base, paste-safe commit commands, Pathfinder number high-water mark and dry runs), and web console workspace folders are remembered per project and spec, with Finalize forgetting an archived spec's list
2026-10-04 12:17:05 -07:00
## 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.
2025-12-23 15:42:35 -08:00
## Required Context
Port upstream skill scripts into v2.4.1: deterministic workflow steps run as Node scripts beside each SKILL.md (specs, pathfinder, feedback payload, commit message, review scope, agent files, handoff path) with tests, the prompt limit rises to 20,000 chars, upstream review fixes are folded in (linked agent files never overwrite AGENTS.md, review stops with no base, paste-safe commit commands, Pathfinder number high-water mark and dry runs), and web console workspace folders are remembered per project and spec, with Finalize forgetting an archived spec's list
2026-10-04 12:17:05 -07:00
Find the spec with `specs.mjs list` , then request these files if not provided:
2025-12-23 15:42:35 -08:00
- `specs/<feature-name>/overview.md`
2026-06-28 11:41:19 -07:00
- All `specs/<feature-name>/phase-X.md` files
2025-12-23 15:42:35 -08:00
2026-02-17 09:13:23 -08:00
Do not proceed without spec files.
2025-12-23 15:42:35 -08:00
## Process
### STEP 1: Change Analysis
`🔄 [REVISION] Step 1: Change Analysis`
2026-02-17 09:13:23 -08:00
1. Read all spec files
2025-12-23 15:42:35 -08:00
2. Understand the requested change
2026-02-17 09:13:23 -08:00
3. Identify affected areas:
2025-12-23 15:42:35 -08:00
| Affected Area | Files | Sections |
|---------------|-------|----------|
| [Component] | [File list] | [Section names] |
2026-06-28 11:41:19 -07:00
Present findings and confirm understanding before continuing.
2025-12-23 15:42:35 -08:00
### STEP 2: Impact Assessment
`🔄 [REVISION] Step 2: Impact Assessment`
2026-02-17 09:13:23 -08:00
1. Classify change type:
2025-12-23 15:42:35 -08:00
2026-02-17 09:13:23 -08:00
| 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 |
2025-12-23 15:42:35 -08:00
2. Show impact summary:
2026-02-17 09:13:23 -08:00
- Tasks affected count
2025-12-23 15:42:35 -08:00
- Components/files changing
- Dependencies to check
2026-02-17 09:13:23 -08:00
- Completed work at risk
2025-12-23 15:42:35 -08:00
2026-02-17 09:13:23 -08:00
3. Present for approval:
2025-12-23 15:42:35 -08:00
```markdown
## Revision Impact Summary
**Change Type:** [Type]
**Tasks Affected:** [X] tasks across [Y] phases
2026-02-17 09:13:23 -08:00
**Completed Work at Risk:** [None / List]
**Phases to Re-open:** [None / List]
2025-12-23 15:42:35 -08:00
### Proposed Changes
1. [Change description]
2. [Change description]
2026-02-17 09:13:23 -08:00
2026-01-27 12:11:00 -08:00
⋅
╭───╮
2026-09-28 19:37:41 -07:00
│ ★ │╱
╱│ ~ │ Here's the plan. What do you think?
╰┬─┬╯
2025-12-23 15:42:35 -08:00
2026-06-28 11:41:19 -07:00
Approve the spec-update plan? (approve / refine / abort). Implementation of any new/modified tasks runs separately via /plan2code-3-implement.
2025-12-23 15:42:35 -08:00
```
2026-06-28 11:41:19 -07:00
**Wait for approval to apply spec updates.**
2025-12-23 15:42:35 -08:00
2026-06-28 11:41:19 -07:00
### STEP 3: Apply Spec Updates
2025-12-23 15:42:35 -08:00
2026-06-28 11:41:19 -07:00
`🔄 [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` .
2025-12-23 15:42:35 -08:00
2026-05-23 06:58:20 -07:00
**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...").
2026-02-17 09:13:23 -08:00
1. Update affected tasks with `🔄 REVISED` flag:
2025-12-23 15:42:35 -08:00
```markdown
- [ ] **Task 3.4:** [Updated description] 🔄 REVISED
- Previous: [old description]
- Changed: [date]
- Reason: [brief reason]
```
2026-02-17 09:13:23 -08:00
2. Add new tasks (maintain sequential numbering)
2025-12-23 15:42:35 -08:00
3. Update dependencies if affected
2026-02-17 09:13:23 -08:00
4. Preserve completed `[x]` tasks unless approved to remove
2025-12-23 15:42:35 -08:00
2026-02-17 09:13:23 -08:00
5. **Re-opening completed phases:**
- Add new tasks with `🆕 ADDED` flag:
2026-01-27 12:11:00 -08:00
```markdown
2026-02-17 09:13:23 -08:00
- [ ] **Task 2.5:** [New task] 🆕 ADDED
2026-01-27 12:11:00 -08:00
- Added: [date]
2026-02-17 09:13:23 -08:00
- Reason: [reason]
2026-01-27 12:11:00 -08:00
` ``
Port upstream skill scripts into v2.4.1: deterministic workflow steps run as Node scripts beside each SKILL.md (specs, pathfinder, feedback payload, commit message, review scope, agent files, handoff path) with tests, the prompt limit rises to 20,000 chars, upstream review fixes are folded in (linked agent files never overwrite AGENTS.md, review stops with no base, paste-safe commit commands, Pathfinder number high-water mark and dry runs), and web console workspace folders are remembered per project and spec, with Finalize forgetting an archived spec's list
2026-10-04 12:17:05 -07:00
- Update overview.md: ` [x]` → ` [ ]` (` specs.mjs mark <spec> --phase <N> --to open`, which also sets that phase file's ` **Status:**` back to In Progress)
2026-02-17 09:13:23 -08:00
- Add comment: ` <!-- Re-opened: [date] - [reason] --> `
2025-12-23 15:42:35 -08:00
### STEP 4: Consistency Check
` 🔄 [REVISION] Step 4: Consistency Check`
Port upstream skill scripts into v2.4.1: deterministic workflow steps run as Node scripts beside each SKILL.md (specs, pathfinder, feedback payload, commit message, review scope, agent files, handoff path) with tests, the prompt limit rises to 20,000 chars, upstream review fixes are folded in (linked agent files never overwrite AGENTS.md, review stops with no base, paste-safe commit commands, Pathfinder number high-water mark and dry runs), and web console workspace folders are remembered per project and spec, with Finalize forgetting an archived spec's list
2026-10-04 12:17:05 -07:00
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:
2025-12-23 15:42:35 -08:00
2026-02-17 09:13:23 -08:00
- [ ] Phase dependencies valid
2025-12-23 15:42:35 -08:00
- [ ] No orphaned references
- [ ] Tech stack updated if needed
2026-02-17 09:13:23 -08:00
- [ ] Success criteria achievable
2025-12-23 15:42:35 -08:00
Port upstream skill scripts into v2.4.1: deterministic workflow steps run as Node scripts beside each SKILL.md (specs, pathfinder, feedback payload, commit message, review scope, agent files, handoff path) with tests, the prompt limit rises to 20,000 chars, upstream review fixes are folded in (linked agent files never overwrite AGENTS.md, review stops with no base, paste-safe commit commands, Pathfinder number high-water mark and dry runs), and web console workspace folders are remembered per project and spec, with Finalize forgetting an archived spec's list
2026-10-04 12:17:05 -07:00
Report and resolve issues (every ` error` in ` checks` included), then rerun ` status` before continuing.
2025-12-23 15:42:35 -08:00
### STEP 5: Summary
` 🔄 [REVISION] Step 5: Summary`
2026-02-17 09:13:23 -08:00
1. Summarize changes:
2025-12-23 15:42:35 -08:00
` ``markdown
## Revision Complete
### Changes Made
| File | Changes |
|------|---------|
| [file] | [description] |
### Tasks Affected
- **Added:** [X] new tasks
- **Modified:** [Y] existing tasks
- **Removed:** [Z] tasks (with approval)
2026-01-27 12:11:00 -08:00
### Phases Re-opened
2026-02-17 09:13:23 -08:00
- [None / List with reasons]
2025-12-23 15:42:35 -08:00
` ``
2026-02-17 09:13:23 -08:00
2. Add to ` overview.md`:
2025-12-23 15:42:35 -08:00
` ``markdown
## Revision History
| Date | Change | Impact |
|------|--------|--------|
| [date] | [description] | [X] tasks affected |
` ``
2026-02-17 09:13:23 -08:00
3. Next steps:
2025-12-23 15:42:35 -08:00
2025-12-25 22:02:15 -08:00
` ``
2026-01-27 12:11:00 -08:00
⋅
╭───╮
2026-09-28 19:37:41 -07:00
╲│ ★ │╱
2026-01-27 12:11:00 -08:00
│ ◡ │ All revised! Ready to continue!
2026-09-28 19:37:41 -07:00
╰┬─┬╯
2026-02-17 09:13:23 -08:00
2025-12-23 15:42:35 -08:00
╔═══════════════════════════════════════════════════════════════════╗
║ REVISION COMPLETE ║
╠═══════════════════════════════════════════════════════════════════╣
║ ║
║ Specs have been updated. To continue implementation: ║
║ ║
║ 1. Start a NEW conversation ║
2026-09-28 19:37:41 -07:00
║ 2. Use command: /plan2code-3-implement --web ║
2025-12-23 15:42:35 -08:00
║ 3. Provide path: specs/<feature-name>/overview.md ║
║ ║
║ The command will auto-detect the next Phase to implement. ║
║ ║
╚═══════════════════════════════════════════════════════════════════╝
` ``
2026-06-28 11:41:19 -07:00
### 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)
2026-08-08 12:39:13 -07:00
2. Remove scratch files created during revision that are no longer needed. NEVER remove ` pathfinder/` — it is the decision record behind the plan
2026-06-28 11:41:19 -07:00
3. Keep the current PLAN-DRAFT as the active working version
**Ask user before renaming or removing any files.**
---
2026-02-17 09:13:23 -08:00
## Aborting
2025-12-23 15:42:35 -08:00
2026-02-17 09:13:23 -08:00
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
2025-12-23 15:42:35 -08:00
## IMPORTANT REMINDERS
- Every response must start with: ` 🔄 [REVISION]`
2026-06-28 11:41:19 -07:00
- STOP and get approval at Step 2 before applying spec updates
2025-12-23 15:42:35 -08:00
- Never silently remove completed tasks
- Maintain full revision history for traceability
2026-06-28 11:41:19 -07:00
- 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).
Port upstream skill scripts into v2.4.1: deterministic workflow steps run as Node scripts beside each SKILL.md (specs, pathfinder, feedback payload, commit message, review scope, agent files, handoff path) with tests, the prompt limit rises to 20,000 chars, upstream review fixes are folded in (linked agent files never overwrite AGENTS.md, review stops with no base, paste-safe commit commands, Pathfinder number high-water mark and dry runs), and web console workspace folders are remembered per project and spec, with Finalize forgetting an archived spec's list
2026-10-04 12:17:05 -07:00
**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.
2026-06-28 11:41:19 -07:00
2026-09-28 19:37:41 -07:00
Returning context: Revised specs in ` specs/<feature-name>/`. Run ` /plan2code-3-implement --web` in a new conversation to continue implementation.
2026-10-11 16:39:25 -07:00
**On the web console:** a ` __stop` action in a send is the person ending the session: see console-stop.md. 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.