Files

2025-11-01 19:22:39 +08:00

8.7 KiB

Raw Blame History

Phase 4: Implementation

Overview

Phase 4 is where planning transitions into actual development. This phase manages the iterative implementation of stories defined in the epic files, tracking their progress through a well-defined status workflow.

Status Definitions

Epic Status

Epics progress through a simple two-state flow:

Status	Description	Next Status
backlog	Epic exists in epic file but technical context has not been created	contexted
contexted	Epic technical context has been created via `epic-tech-context` workflow. This is a prerequisite before any stories in the epic can be drafted.	-

File Indicators:

backlog: No epic-{n}-context.md file exists
contexted: {output_folder}/epic-{n}-context.md file exists

Story Status

Stories progress through a six-state flow representing their journey from idea to implementation:

Status	Description	Set By	Next Status
backlog	Story only exists in the epic file, no work has begun	Initial state	drafted
drafted	Story file has been created via `create-story` workflow	SM Agent	ready-for-dev
ready-for-dev	Story has been drafted, approved, and context created via `story-context` workflow	SM Agent	in-progress
in-progress	Developer is actively implementing the story	Dev Agent	review
review	Implementation complete, under SM review via `code-review` workflow	Dev Agent	done
done	Story has been reviewed and completed	Dev Agent	-

File Indicators:

backlog: No story file exists
drafted: {story_dir}/{story-key}.md file exists (e.g., 1-1-user-auth.md)
ready-for-dev: Both story file and context exist (e.g., 1-1-user-auth-context.md)
in-progress, review, done: Manual status updates in sprint-status.yaml

Retrospective Status

Optional retrospectives can be completed after an epic:

Status	Description
optional	Retrospective can be completed but is not required
completed	Retrospective has been completed

Status Transitions

Epic Flow

graph LR
    backlog --> contexted[contexted via epic-tech-context]

Story Flow

graph LR
    backlog --> drafted[drafted via create-story]
    drafted --> ready[ready-for-dev via story-context]
    ready --> progress[in-progress - dev starts]
    progress --> review[review via code-review]
    review --> done[done - dev completes]

Sprint Status Management

The sprint-status.yaml file is the single source of truth for tracking all work items. It contains:

All epics with their current status
All stories with their current status
Retrospective placeholders for each epic
Clear documentation of status definitions

Example Sprint Status File

development_status:
  epic-1: contexted
  1-1-project-foundation: done
  1-2-app-shell: done
  1-3-user-authentication: in-progress
  1-4-plant-data-model: ready-for-dev
  1-5-add-plant-manual: drafted
  1-6-photo-identification: backlog
  1-7-plant-naming: backlog
  epic-1-retrospective: optional

  epic-2: backlog
  2-1-personality-system: backlog
  2-2-chat-interface: backlog
  2-3-llm-integration: backlog
  epic-2-retrospective: optional

Workflows in Phase 4

Core Workflows

Workflow	Purpose	Updates Status
sprint-planning	Generate/update sprint-status.yaml from epic files	Auto-detects file-based statuses
epic-tech-context	Create technical context for an epic	epic: backlog → contexted
create-story	Draft a story from epics/PRD	story: backlog → drafted
story-context	Add implementation context to story	story: drafted → ready-for-dev
dev-story	Developer implements the story	story: ready-for-dev → in-progress
code-review	SM reviews implementation	story: in-progress → review
retrospective	Conduct epic retrospective	retrospective: optional → completed
correct-course	Course correction when needed	Various status updates

Sprint Planning Workflow

The sprint-planning workflow is the foundation of Phase 4. It:

Parses all epic files (epic*.md or epics.md)
Extracts all epics and stories maintaining their order
Auto-detects current status based on existing files:
- Checks for epic context files
- Checks for story files
- Checks for story context files
Generates sprint-status.yaml with current reality
Preserves manual status updates (won't downgrade statuses)

Run this workflow:

Initially after Phase 3 completion
After creating epic contexts
Periodically to sync file-based status
To verify current project state

Workflow Guidelines

Epic Context First: Epics should be contexted before drafting their stories
Flexible Parallelism: Multiple stories can be in-progress based on team capacity
Sequential Default: Stories within an epic are typically worked in order
Learning Transfer: SM drafts next story after previous is done, incorporating learnings
Review Flow: Dev moves to review, SM reviews, Dev moves to done

Agent Responsibilities

SM (Scrum Master) Agent

Run sprint-planning to generate initial status
Create epic contexts (epic-tech-context)
Draft stories (create-story)
Create story contexts (story-context)
Review completed work (code-review)
Update status in sprint-status.yaml

Developer Agent

Check sprint-status.yaml for ready-for-dev stories
Update status to in-progress when starting
Implement stories (dev-story)
Move to review when complete
Address review feedback
Update to done after approval

Test Architect

Monitor stories entering review status
Track epic progress
Identify when retrospectives needed
Validate implementation quality

Best Practices

Always run sprint-planning first to establish current state
Update status immediately as work progresses
Check sprint-status.yaml before starting any work
Preserve learning by drafting stories sequentially when possible
Document decisions in story and context files

Naming Conventions

Story File Naming

Format: {epic}-{story}-{kebab-title}.md
Example: 1-1-user-authentication.md
Avoids YAML float parsing issues (1.1 vs 1.10)
Makes files self-descriptive

Git Branch Naming

Format: feat/{epic}-{story}-{kebab-title}
Example: feat/1-1-user-authentication
Consistent with story file naming
Clean for branch management

File Structure

{output_folder}/
├── sprint-status.yaml                      # Sprint status tracking
├── epic*.md or epics.md                    # Epic definitions
├── epic-1-context.md                       # Epic technical contexts
├── epic-2-context.md
└── stories/
    ├── 1-1-user-authentication.md          # Story drafts
    ├── 1-1-user-authentication-context.md  # Story contexts
    ├── 1-2-account-management.md
    ├── 1-2-account-management-context.md
    └── ...

Next Steps

After Phase 4 implementation, projects typically move to:

Deployment and release
User acceptance testing
Production monitoring
Maintenance and updates

The sprint-status.yaml file provides a complete audit trail of the development process and can be used for project reporting and retrospectives.

8.7 KiB Raw Blame History