Developer

# Session Workflow Template

This document defines the systematic workflow for each development session. Follow these instructions precisely to maintain consistency, quality, and traceability across all development work.

## 🤖 Agent Instructions

You are a **senior developer**. Follow these guidelines as golden rules:

1. **Pick up work** - Find the next open task from beads and initiate or continue the work
2. **Follow this document** - These instructions are your primary workflow guide; ask the user if in doubt
3. **Stay in scope** - Keep work close to the task scope
4. **Handle dependencies** - If implementation depends on future work, add a placeholder with `TODO: will be implemented on story/task/epic N`
5. **Be thorough** - Analyse solutions in detail and keep them robust
6. **Never assume** - Always consult documentation; verify APIs and sources
7. **Maintain consistency** - Follow existing code style, patterns, and reuse code (DRY principle)
8. **One task, one branch** - Each task gets its own branch (feature/, fix/, chore/, etc.)
9. **Go deep** - Be thorough and consistent in your implementation

---

# Session Workflow Template

This document defines the systematic workflow for each development session. Follow these instructions precisely to maintain consistency, quality, and traceability across all development work.

---

## 🎯 Session Objective

Each session focuses on **one task** and its subtasks. Work is atomic, reviewed, and committed per subtask.

---

## 📋 Pre-Session Checklist

Before starting any work, verify:

- [ ] You are in the project root directory
- [ ] Git is clean (`git status` shows no uncommitted changes)
- [ ] bd is synchronized (`bd sync`)

---

## 🚀 Phase 1: Session Initialization

### 1.1 Discover Current State

```bash
# Check for work in progress
bd list --status in_progress --json

# Check current branch
git branch --show-current

# Check git status
git status

1.2 Decision Tree

First read the history/PRODUCT-REQUIREMENTS-DOC-V2.md and history/TECHNICAL-SPECIFICATION-V2.md documents.

If there's a task in_progress:

• Continue from where it left off
• Identify the next open subtask or task

If starting fresh (no in_progress tasks):

• Checkout and pull main
• Identify the next ready task from Phase 0 (or current phase)

# Switch to main and update
git checkout main
git pull origin main
bd sync

# Find next ready task
bd ready --json

1.3 Setup Task Branch

# Create feature branch (naming convention: feature/p0-XX-short-description)
git checkout -b feature/<task-id-kebab-case>

1.4 Start Task

# Set task to in_progress
bd update <task-id> --status in_progress --json

# Sync bd
bd sync

1.5 Load Task Context

CRITICAL: Always read the PLAN-V2.md section for the task before implementation.

# Get task details to find PLAN-V2.md line references
bd show <task-id> --json

Then read the relevant section from history/PLAN-V2.md using the line numbers from the task description (e.g., 📖 history/PLAN-V2.md#L533-950).

---

🔄 Phase 2: Implementation Loop

This phase handles both tasks with subtasks and standalone tasks.

With Subtasks

Repeat the loop (2.1 → 2.9) for each subtask until all are complete.

Without Subtasks

If the task has no subtasks in beads, proceed directly from 2.3 to 2.7, then skip to Phase 3.2 (skip 3.1 since there are no subtasks to verify).

Why no subtasks? Some tasks are tightly coupled and splitting them provides no benefit. The plan may describe logical steps, but if they weren't created as separate beads issues, treat the task as a single unit of work.

2.1 Identify Next Subtask

# Show task with dependents (subtasks)
bd show <parent-task-id> --json

Pick the first subtask with status: "open".

2.2 Start Subtask

# Set subtask to in_progress
bd update <subtask-id> --status in_progress --json

2.3 Implement

Execute the subtask according to its description and the PLAN-V2.md specifications.

During implementation, ensure:

• Follow existing code patterns and conventions
• Add proper documentation (module-level, functions, types)
• Handle errors appropriately
• Consider edge cases

2.4 Review (Critical Step)

Before committing, perform a thorough review:

2.4.1 Code Quality Review

• Robustness: Does the code handle errors and edge cases properly?
• Improvements: Can readability, performance, or patterns be improved?
• Consistency: Does it follow the project's existing patterns?
• Documentation: Are modules, structs, functions, and types documented?
• Clean Code: No dead code, TODOs, or temporary comments?
• No Assumptions: All APIs and sources verified, not assumed?

2.4.2 Acceptance Criteria Check

Review the subtask description and verify all requirements are met.

2.4.3 Technical DoD (Definition of Done)

Run validations when applicable:

# Lint check (when biome is configured)
pnpm lint

# Type check (when TypeScript is configured)
pnpm typecheck

# Run tests (when tests exist)
pnpm test

2.5 Decision Point

If review PASSES:

• Create changeset
• Proceed to commit

If review FAILS:

• Fix the issues
• Return to step 2.4

2.6 Create Workspace Changeset

CRITICAL: Every feature branch MUST have an associated changeset for version control and changelog generation.

# Create changeset for this branch (interactive mode)
workspace changeset create

# Or use non-interactive mode with explicit options
workspace changeset create --bump <patch|minor|major> --message "<description>" --non-interactive

Command Options:

Option	Description
--bump <TYPE>	Bump type: major, minor, or patch
--message <TEXT>	Description of the changes
--packages <LIST>	Comma-separated list of packages (auto-detected if omitted)
`--env <LIST
```