Project Planning Workflow

A workflow for generating a structured project plan from a goal.md file for well-defined, low-uncertainty projects — typically single-repo changes with a clear path forward, 1-15 tasks, and 0-2 straightforward design decisions.

For projects involving significant uncertainty, multi-repo coordination, or 3+ design decisions with trade-offs, use Complex Project Definition and Planning instead, which adds a design document, decision log, and iterative dialog protocol.

Inputs

Before generating plan documents, identify:

The goal file (goal.md) — either explicitly designated or present in the current project directory.
The project type:
- Greenfield — New functionality with no existing implementation.
- Modification — Changes to existing code requiring a gap analysis.
- Testing and Documentation — No changes to functionality; only tests and documentation.
The project directory — Where all plan documents will be placed. It should be a sibling of the goal file. All produced documents go here; nothing outside this directory is modified during planning.

Phase 1: Analysis (Modification Projects Only)

When the project type is Modification, create analysis.md before other deliverables. This documents the gap between the current implementation and the specification, and drives prioritization of the work.

`analysis.md` structure

# Analysis: <Goal Title>

## Executive Summary

High-level summary of the comparison between specification and implementation.

## Specification vs. Implementation Comparison

### Category 1: Significant Gaps (Features Not Implemented)

Features specified but not implemented. Include:
- Specification reference (quote or link)
- Current implementation state (file, line numbers)
- Impact assessment

### Category 2: Behavioral Differences

Implementation differs from specification.

### Category 3: Missing API Exposure

Internal functionality not exposed as intended.

### Category 4: Minor Discrepancies

Naming, casing, or structural inconsistencies.

## Summary Table

| Specification Requirement | Status | Notes |
| ------------------------- | ------ | ----- |
| ...                       | gap/ok | ...   |

## Prioritized Recommendations

### Priority 1: Breaking Behaviors
Changes that contradict specifications and could cause data integrity issues.

### Priority 2: Data Integrity
Changes needed to ensure data consistency and correctness.

### Priority 3: Completeness
Missing features, API exposures, or polish items.

Phase 2: Core Deliverables

For all project types, create these three documents in the project directory.

`requirements.md`

Content: Functional requirements and system behaviors once implemented (endpoints, atomicity rules, validation, input/output schemas).
Constraint: Do NOT include internal tasks, engineering processes, coding styles, unit test requirements, or verification steps.
Structure: Assign a unique identifier to each requirement (e.g., REQ-BULK-001).

`verification.md`

Content: Bidirectional traceability between requirements and tests.
Constraint: Use anchor links to requirements.md — do not repeat requirement titles verbatim.
Structure: Single traceability table with a status column.

`specification.md`

Content: Acts as a driving document for the implementing engineer. References requirements.md and verification.md.
Explicitly states: Task requirements, quality guidelines, and a checklist of all acceptance criteria.
Structure: Includes detailed phases with explicit STOP points for review and approval.

Open Questions and Decisions section

Every specification.md MUST include an Open Questions and Decisions section placed after the main content but before any exit gate or verification section:

## Open Questions and Decisions

| # | Question | Options | Recommendation | Decision |
|---|----------|---------|----------------|----------|

Populate the table with any ambiguities, option trade-offs, or unresolved scope questions identified during planning. This gives the implementing engineer a structured record of what was clarified and what remains open. For projects with 3+ questions, consider upgrading to the Complex Project Planning workflow, which provides a full decision log with rounds and traceability.

Phase 2.5: Worktree Strategy (Multi-Agent Plans)

When any plan has 2+ agents working in parallel on the same repository, include a Worktree Strategy section in specification.md or the relevant plan document.

Naming

Worktrees are grouped under a parent directory at the workspace root:

${projectName}-worktrees/${taskName}

projectName — short project name (e.g., fe-coverage, ops-bulk)
taskName — agent task or phase identifier (e.g., sp1-infra, run-2)
Example: fe-coverage-worktrees/sp1-infra

Branch names

Each worktree checks out a branch following: ${githubUsername}/${projectName}/${taskName}

Integration branch (recommended merge workflow)

Identify the base branch (typically main). Record it explicitly. The base branch is never modified locally.
Create an integration branch from the base branch before work starts: <username>/<project-name>-integration.
Each worktree branch merges into the integration branch (not the base branch) as tasks complete.
A single PR is opened from the integration branch to the base branch.

Alternative workflows (sequential merge, separate PRs per sub-task) must be explicitly justified in the plan.

Cleanup

The plan must include a final step that removes all worktrees after all work is merged.

If worktrees are not needed (single agent, sequential writes, or different repositories), state this explicitly: “Single directory — no worktrees needed.”

Phase 3: Detailed Implementation Documents

When the project has multiple tasks or significant complexity, also generate:

`implementation-changes.md`

Content: Precise code modification instructions for the implementing engineer.
When to produce: When specification.md references multiple tasks or when the implementation requires step-by-step guidance.

Phase 4: Phased Project Structure (Large Projects)

When the goal or analysis reveals multiple distinct implementation phases, organize work into a phased directory structure:

<project-directory>/
├── goal.md
├── analysis.md                      (if modification project)
├── required-updates.md              (optional overall project plan)
│
├── <project-num>-1-<phase-name>/
│   ├── specification.md
│   ├── requirements.md
│   ├── verification.md
│   ├── implementation-changes.md
│   ├── byproducts/
│   │   ├── changelog.md
│   │   ├── learnings.md
│   │   ├── suggestions.md
│   │   ├── alternatives.md
│   │   ├── skipped.md
│   │   └── specification-post.md
│   └── session/
│
├── <project-num>-2-<phase-name>/
│   └── (same structure)
│
└── <project-num>-3-<phase-name>/
    └── (same structure)

Phase naming

Format: {project-number}.{phase-number}-{phase-name}/

Example: 5.1-breaking-behaviors/, 5.2-data-integrity/, 5.3-completeness/

Recommended phase categories for modification projects

Priority	Category	Description
P1	Breaking Behaviors	Changes that contradict specifications and could cause data integrity issues
P2	Data Integrity	Changes needed to ensure data consistency and correctness
P3	Completeness	Missing features, API exposures, or polish items

Release Lifecycle (Multi-Repository Projects)

When a phased project spans multiple repositories, include a Release phase at the end covering:

CHANGELOG updates for each repository
PR merge ordering (upstream before downstream)
Version catalog updates

See Release Lifecycle conventions for the full per-repository release sequence.

Formatting Rules

All documents produced during project planning must follow these conventions:

Cross-repository links: Use /repo-name/path/file
Same-directory links: Use standard relative paths (./, ../)
Link text: Use descriptive text extracted from document titles
No absolute paths: Never use /Users/... or similar system-absolute paths

Complex Project Definition and Planning — for high-uncertainty, multi-repo projects
Project Decomposition — for splitting large plans into sequenced runs