english/.opencode/skills/ck-plan/references/plan-organization.md

Plan Creation & Organization

Directory Structure

Plan Location

Use Plan dir: from ## Naming section injected by hooks. This is the full computed path.

Example: plans/251101-1505-authentication/ or ai_docs/feature/MRR-1453/

File Organization

IN CURRENT WORKING PROJECT DIRECTORY:

{plan-dir}/                                    # From `Plan dir:` in ## Naming
├── research/
│   ├── researcher-XX-report.md
│   └── ...
├── reports/
│   ├── scout-report.md
│   ├── researcher-report.md
│   └── ...
├── plan.md                                    # Overview access point
├── phase-01-setup-environment.md              # Setup environment
├── phase-02-implement-database.md             # Database models
├── phase-03-implement-api-endpoints.md        # API endpoints
├── phase-04-implement-ui-components.md        # UI components
├── phase-05-implement-authentication.md       # Auth & authorization
├── phase-06-implement-profile.md              # Profile page
└── phase-07-write-tests.md                    # Tests

Task Hydration

After creating plan.md and phase files, hydrate tasks (unless --no-tasks):

1. TaskCreate per phase with addBlockedBy dependency chain
2. Add critical step tasks for high-risk items
3. See task-management.md for patterns and cook handoff protocol

Active Plan State Tracking

See SKILL.md "Active Plan State" section for full rules. Key points:

• Check ## Plan Context injected by hooks for active/suggested/none state
• After creating plan: node .opencode/scripts/set-active-plan.cjs {plan-dir}
• Active plans use plan-specific reports path; suggested plans use default path

Plan Creation via CLI

After determining phases from research/design:

1. Scaffold via CLI:

   ck plan create \
     --title "{plan title}" \
     --phases "{Phase1},{Phase2},{Phase3}" \
     --dir {plan-dir} \
     --priority {P1|P2|P3} \
     [--issue {N}]
   

2. Fill content sections in plan.md via Edit tool:

   • ## Overview — brief description
   • ## Dependencies — cross-plan dependencies

3. Fill each phase-XX.md with:

   • Architecture, implementation steps, success criteria
   • Requirements, risk assessment, security considerations

4. NEVER edit the Phases table directly — it's CLI-owned. Use ck plan check/uncheck/add-phase for structural changes.

Fallback: If ck CLI is not available (e.g., user hasn't installed), write plan.md directly using the canonical 3-column format.

File Structure

Overview Plan (plan.md)

IMPORTANT: All plan.md files MUST include YAML frontmatter. See output-standards.md for schema.

Example plan.md structure:

---
title: "Feature Implementation Plan"
description: "Add user authentication with OAuth2 support"
status: pending
priority: P1
effort: 8h
issue: 123
branch: kai/feat/oauth-auth
tags: [auth, backend, security]
blockedBy: []
blocks: [260115-0900-user-dashboard]
created: 2025-12-16
---

# Feature Implementation Plan

## Overview

Brief description of what this plan accomplishes.

## Cross-Plan Dependencies

| Relationship | Plan | Status |
|-------------|------|--------|
| Blocks | [260115-0900-user-dashboard](../260115-0900-user-dashboard/plan.md) | pending |

## Phases

| Phase | Name | Status |
|-------|------|--------|
| 1 | [Setup Environment](./phase-01-setup.md) | Pending |
| 2 | [Core Implementation](./phase-02-impl.md) | Pending |
| 3 | [Testing & Validation](./phase-03-test.md) | Pending |

<!-- IMPORTANT: Link text MUST be human-readable names (not filenames).
     Bad:  [phase-01-setup.md](./phase-01-setup.md)
     Good: [Setup Environment](./phase-01-setup.md) -->

## Dependencies

- List key dependencies here

Guidelines:

• Keep generic and under 80 lines
• List each phase with status/progress
• Link to detailed phase files
• Key dependencies

Phase Files (phase-XX-name.md)

Fully respect the ./docs/development-rules.md file. Each phase file should contain:

Context Links

• Links to related reports, files, documentation

Overview

• Priority
• Current status
• Brief description

Key Insights

• Important findings from research
• Critical considerations

Requirements

• Functional requirements
• Non-functional requirements

Architecture

• System design
• Component interactions
• Data flow

Related Code Files

• List of files to modify
• List of files to create
• List of files to delete

Implementation Steps

• Detailed, numbered steps
• Specific instructions

Todo List

• Checkbox list for tracking

Success Criteria

• Definition of done
• Validation methods

Risk Assessment

• Potential issues
• Mitigation strategies

Security Considerations

• Auth/authorization
• Data protection

Next Steps

• Dependencies
• Follow-up tasks