plan-editing-conventions

Plan Editing Conventions

Conventions for creating and modifying implementation plans stored as plan.json.

Plan Structure Rules

• Keep prose concise and actionable; include concrete file paths (relative/path.ts)
• Never include time estimates. Use qualitative Complexity per task: S (≤ ~120 LOC), M (~120–300 LOC), L (> ~300 LOC)
• Do not hardcode colors or tokens; reference semantic tokens when citing UI work

plan.json Format

The plan is stored as plan.json with these key fields:

{
  "content": "# Implementation Plan\n\n## Stage 1: ...\n\n### T-1.1: Task Title\n...",
  "acceptanceCriteria": [...],
  "pendingTasks": [...],
  "completedTasks": [...],
  "manualTasks": [...],
  "openQuestions": [...],
  "answeredQuestions": [...],
  "gaps": [...],
  "amendments": [...]
}

• content: The full markdown plan as a JSON string with escaped newlines (\n). This is the human-readable plan text.
• Structured arrays: Mirror the plan content for programmatic access (pendingTasks, completedTasks, etc.)

Editing plan.json Content Field

CRITICAL: The content field is a JSON string. When editing:

• Use \n escape sequences for newlines, NOT literal line breaks
• Ensure proper JSON escaping of quotes and special characters
• After editing, always sync plan.md via the code:extract-plan-md skill

Task Format

Tasks use the T-X.Y ID convention where X is the stage number and Y is the task number within that stage.

Each task in the plan content should follow this structure:

### T-X.Y: [Task Title]

**Files:** `path/to/file.ext`
**Complexity:** S | M | L
**AC Refs:** AC-001, AC-002

**Description:** Brief description of what this task accomplishes.

**Implementation Details:**

[Include one or more of the following as appropriate:]

**Mapping Table:** (for distribution/transformation tasks)
| Source | Target | Notes |
|--------|--------|-------|
| category_a | target_file_a.md | Section: XYZ |
| category_b | target_file_b.md | Section: ABC |

**Algorithm:** (for logic-heavy tasks)
1. Load input from `source_path`
2. Parse using `specific_method()`
3. For each item:
   a. Transform using pattern X
   b. Validate against schema Y
4. Write output to `target_path`

**Code Template:** (for new file creation)
```python