Plan Start

# Plan & Start Session

Enhanced version of `trellis-start` 鈥?adds a **Plan Phase** before execution.
First builds a structured plan document for user review, then executes confirmed tasks through the standard trellis workflow.

---

## Operation Types

| Marker | Meaning | Executor |
|--------|---------|----------|
| `[AI]` | Bash scripts or file reads executed by AI | You (AI) |
| `[USER]` | Decisions or slash commands by user | User |
| `[COLLAB]` | AI proposes, user confirms/adjusts | Both |

---

## Phase 0: Initialization `[AI]`

Same as `/trellis-start`:

### Step 0.1: Understand Trellis Workflow

```bash
cat .trellis/workflow.md

Step 0.2: Initialize Developer Identity (Actant Agent)

Ensure your Actant Agent identity is initialized. Check if already set, if not, initialize:

bash ./.trellis/scripts/get-developer.sh || bash ./.trellis/scripts/init-developer.sh actant-cursor-agent

Actant Agent 韬唤: AI 寮€鍙戣€呮槸涓€涓?Actant Agent 瀹炰緥銆侰ursor AI 浣跨敤 actant-cursor-agent 浣滀负韬唤鏍囪瘑銆?

Step 0.3: Get Current Status

bash ./.trellis/scripts/get-context.sh

Step 0.4: Read Project Guidelines

Read relevant spec docs based on context:

cat .trellis/spec/frontend/index.md
cat .trellis/spec/backend/index.md
cat .trellis/spec/guides/index.md

Step 0.5: Check Active Tasks

bash ./.trellis/scripts/task.sh list

Step 0.6: Report Ready Status

Output initialization summary (same as trellis-start), then:

Initialization complete. Please describe your task 鈥?I'll create a plan for us to review before starting.

---

Phase 1: Plan Construction [COLLAB]

Step 1.1: Gather Requirements [AI]

When user describes their task:

1. Ask clarifying questions if the scope is unclear
2. Classify the task type (frontend / backend / fullstack / docs / infra)
3. Identify affected areas of the codebase

Step 1.2: Research Codebase [AI]

Perform deep analysis:

1. Search for relevant spec files in .trellis/spec/
2. Find existing code patterns (2-3 representative examples)
3. Identify files that need modification
4. Identify potential risks and dependencies

Step 1.3: Generate Plan Document [AI]

Create a plan file at: c:\Users\{user}\.cursor\plans\{slug}_{hash}.plan.md

The plan document uses the following format:

---
name: <Plan Title>
overview: <One-line description of what this plan achieves>
todos:
  - id: <kebab-case-id>
    content: "<Priority>: <Task description>"
    status: pending
  - id: <kebab-case-id>
    content: "<Priority>: <Task description>"
    status: pending
  # ... more todos
isProject: false
---

# <Plan Title>

<Brief context paragraph explaining the goal and scope>

---

## 涓€銆佽儗鏅垎鏋?

<Why this task is needed, what problem it solves>

## 浜屻€佹柟妗堣璁?

<Technical approach, architecture decisions, alternatives considered>

## 涓夈€佸疄鏂借鍒?

### Phase 1: <Phase Name>

| # | Task | Priority | Dependencies | Estimated Effort |
|---|------|----------|--------------|-----------------|
| 1 | <task> | P0 | - | <effort> |
| 2 | <task> | P1 | #1 | <effort> |

### Phase 2: <Phase Name>

| # | Task | Priority | Dependencies | Estimated Effort |
|---|------|----------|--------------|-----------------|
| 3 | <task> | P1 | Phase 1 | <effort> |

## 鍥涖€佸奖鍝嶈寖鍥?

### Files to Modify
- `<path>`: <what changes>

### New Files
- `<path>`: <purpose>

### Risk Assessment
- <risk 1>: <mitigation>
- <risk 2>: <mitigation>

## 浜斻€侀獙鏀舵爣鍑?

- [ ] <Criterion 1>
- [ ] <Criterion 2>

## 鍏€佺浉鍏冲弬鑰?

- <spec/code/doc references>

Plan Document Rules:

• Todos in frontmatter must map 1:1 to actionable implementation steps
• Priority levels: P0 (must-have), P1 (important), P2 (nice-to-have)
• Status values: pending, in_progress, completed
• Dependencies must be explicit 鈥?no circular references
• Keep the plan concise but complete 鈥?the user should be able to understand the full scope at a glance

Step 1.4: Present Plan to User [COLLAB]

Output the plan and ask:

## 馃搵 Plan Ready for Review

I've created the plan document: `<plan-file-path>`

### Summary
- **Total tasks**: {count}
- **P0 (must-have)**: {count}
- **P1 (important)**: {count}
- **P2 (nice-to-have)**: {count}
- **Estimated scope**: {files} files, {phases} phases

### Key Decisions
1. <decision 1 鈥?why this approach>
2. <decision 2 鈥?trade-off made>

---

Please review the plan. You can:
- **Approve**: "LGTM" or "approved" to start execution
- **Adjust**: Tell me what to change (add/remove/reorder tasks, change priorities)
- **Reject**: "reject" to start over with different requirements

Step 1.5: Iterate on Plan [COLLAB]

If user requests changes:

1. Update the plan document with requested modifications
2. Re-present the updated summary
3. Repeat until user approves

Important: Do NOT proceed to Phase 2 until the user explicitly approves.

---

Phase 2: Execute Plan [AI]

Once the user approves the plan, execute using the standard trellis task workflow.

Step 2.1: Create Task from Plan [AI]

TASK_DIR=$(bash ./.trellis/scripts/task.sh create "<plan title>" --slug <plan-slug>)

Step 2.2: Configure Context [AI]

Initialize context based on task type identified in the plan:

bash ./.trellis/scripts/task.sh init-context "$TASK_DIR" <type>
# type: backend | frontend | fullstack

Add specs discovered during research:

bash ./.trellis/scripts/task.sh add-context "$TASK_DIR" implement "<path>" "<reason>"
bash ./.trellis/scripts/task.sh add-context "$TASK_DIR" check "<path>" "<reason>"

Step 2.3: Write PRD from Plan [AI]

Convert the approved plan into prd.md in the task directory:

# <Plan Title>

## Goal
<From plan overview>

## Requirements
<From plan body - section 浜?

## Acceptance Criteria
<From plan body - section 浜?

## Implementation Plan
<From plan body - section 涓? include todo references>

## Technical Notes
<Fr