Update Implementation Plan

Update implementation plan

Update or create an implementation plan so it is deterministic, self-contained, machine-readable and machine-parseable, and executable by AI agents or humans without hidden interpretation, decision-making, or loss of self-containment.

When to invoke

• "Update this implementation plan with the new requirements."
• "Revise the plan file for this refactor."
• "Create an AI-executable implementation plan."
• "Add package upgrade tasks to the plan."
• "Generate a phased architecture or infrastructure plan under /plan/."

Inputs

Use the user's target file, selected file, or ${file} as the implementation plan to update. If no file exists, create a new plan under /plan/ using the naming convention [purpose]-[component]-[version].md.

Purpose prefixes are upgrade, refactor, feature, data, infrastructure, process, architecture, and design. Examples: upgrade-system-command-4.md and feature-auth-module-1.md.

Plan standards

Procedure

1. Read the existing implementation plan, new or updated requirements, and relevant code references.
2. Preserve valid existing plan content unless it conflicts with new requirements.
3. Normalize phases so each has measurable completion criteria and clear cross-phase dependency boundaries.
4. Convert vague work into atomic tasks with paths, functions, implementation details, completion state, and date fields.
5. Update front matter and status badge consistently.
6. Validate every required section, table column, identifier prefix, and placeholder before saving.

Template requirements

All implementation plans must use this exact top-level structure and fully populate each section:

Allowed statuses are Completed, In progress, Planned, Deprecated, and On Hold. Use badge colors bright green, yellow, blue, red, and orange respectively.

Mandatory plan template

---
goal: [Concise Title Describing the Package Implementation Plan's Goal]
version: [Optional: e.g., 1.0, Date]
date_created: [YYYY-MM-DD]
last_updated: [Optional: YYYY-MM-DD]
owner: [Optional: Team/Individual responsible for this spec]
status: 'Completed'|'In progress'|'Planned'|'Deprecated'|'On Hold'
tags: [Optional: List of relevant tags or categories, e.g., `feature`, `upgrade`, `chore`, `architecture`, `migration`, `bug` etc]
---

# Introduction

![Status: <status>](https://img.shields.io/badge/status-<status>-<status_color>)

[A short concise introduction to the plan and the goal it is intended to achieve.]

## 1. Requirements & Constraints

- **REQ-001**: Requirement 1
- **SEC-001**: Security Requirement 1
- **[3 LETTERS]-001**: Other Requirement 1
- **CON-001**: Constraint 1
- **GUD-001**: Guideline 1
- **PAT-001**: Pattern to follow 1

## 2. Implementation Steps

### Implementation Phase 1

- GOAL-001: [Describe the goal of this phase, e.g., "Implement feature X", "Refactor module Y", etc.]

| Task | Description | Completed | Date |
|------|-------------|-----------|------|
| TASK-001 | Description of task 1 | Yes | 2025-04-25 |
| TASK-002 | Description of task 2 | |  |
| TASK-003 | Description of task 3 | |  |

### Implementation Phase 2

- GOAL-002: [Describe the goal of this phase, e.g., "Implement feature X", "Refactor module Y", etc.]

| Task | Description | Completed | Date |
|------|-------------|-----------|------|
| TASK-004 | Description of task 4 | |  |
| TASK-005 | Description of task 5 | |  |
| TASK-006 | Description of task 6 | |  |

## 3. Alternatives

- **ALT-001**: Alternative approach 1
- **ALT-002**: Alternative approach 2

## 4. Dependencies

- **DEP-001**: Dependency 1
- **DEP-002**: Dependency 2

## 5. Files

- **FILE-001**: Description of file 1
- **FILE-002**: Description of file 2

## 6. Testing

- **TEST-001**: Description of test 1
- **TEST-002**: Description of test 2

## 7. Risks & Assumptions

- **RISK-001**: Risk 1
- **ASSUMPTION-001**: Assumption 1

## 8. Related Specifications / Further Reading

[Link to related spec 1]
[Link to relevant external documentation]

Template validation rules

• All front matter fields are present and properly formatted.
• Section headers match exactly and are case-sensitive.
• Identifier prefixes follow the specified format.
• Task tables include Task, Description, Completed, and Date columns.
• No placeholder text remains in the final output.
• Status in front matter and badge agree.

Gotchas

• Do not leave human interpretation tasks; replace them with explicit decisions, dependencies, or assumptions.
• Do not omit file paths or function names when code changes are known; specificity is required for autonomous execution.
• Do not create plans outside /plan/ unless updating an explicitly supplied existing file.
• Do not mismatch status color and status text; the badge must reflect the front matter.

Output template

## Implementation plan update

**Status:** updated | created | blocked
**Plan file:** `/plan/<purpose>-<component>-<version>.md`
**Plan status:** `<Completed|In progress|Planned|Deprecated|On Hold>`

### Changes made
| Section | Update |
| --- | --- |
| Requirements & Constraints | <summary> |
| Implementation Steps | <summary> |
| Testing | <summary> |

### Validation
- Required sections: <pass|fail>
- Identifier prefixes: <pass|fail>
- Placeholders removed: <pass|fail>
- Status badge: <pass|fail>

Quality gate

• The target ${file} or a new /plan/[purpose]-[component]-[version].md path is identified.
• All required front matter fields and plan sections are present.
• Status is one of Completed, In progress, Planned, Deprecated, or On Hold and the badge uses the matching color.
• Requirements, phases, tasks, dependencies, files, tests, risks, and assumptions use standardized identifiers.
• Tasks are atomic, deterministic, and include specific paths, functions, or configuration details when known.
• No placeholder text remains in the final plan.

References

• Shields.io status badge