Development Workflow Guide

Version: 1.6.1 | Last reviewed: 2026-03-24

Overview

PARA Workspace organizes development into 4 core workflow streams:

┌──────────────────────────────────────────────────────────────────────┐
│                                                                      │
│  0. PLANNING          1. DAILY DEV        2. RELEASE      3. OPS    │
│  ────────────         ──────────          ──────────      ────────  │
│  /brainstorm          /open               /release        /retro    │
│     ↓                    ↓                   ↓            /inbox    │
│  /docs (strategy)     [coding + hot lane]                           │
│     ↓                    ↓                                          │
│  /plan create         /push                                         │
│     ↓                    ↓                                          │
│  /backlog sync        /end (sync + plan check)                      │
│                                                                      │
└──────────────────────────────────────────────────────────────────────┘

0. Planning Flow (New Projects)

Runs once when starting a large project (>5 tasks).

/new-project [name]
    ↓
/brainstorm           → Brainstorm, capture decisions (optional)
    ↓
/docs new (strategy)  → docs/strategy/strategy.md (v1.6.1, optional)
    ↓
/plan create          → Choose: 🗺️ Roadmap or 📐 Detail Plan (v1.6.1)
    ↓                    (sets active_plan if Detail Plan)
/backlog sync         → Create backlog items from mapped phases
    ↓
/open [project]       → Start Daily Dev Flow

The 3-Tier Model (v1.6.1): Strategy → Roadmap → Detail Plan. Use as many tiers as the project scope demands. See the Strategy Plan Flow Guide for details. Not every project needs a Plan. See the Planning Guide for decision criteria.

1. Daily Development Flow

This flow happens daily as the developer works.

/open [project]
    │
    │  📋 Read session log + backlog summary (~10 lines)
    │  🔥 Read Hot Lane (sprint-current.md)
    │  📐 View current phase (if active_plan set)
    │  💡 Get task recommendations (prioritizing current phase)
    │
    ▼
[Coding & Testing]
    │
    │  🔧 Develop features
    │  🧪 Test locally
    │  🔥 Quick task appears? → Write `- [ ]` to sprint-current.md
    │  ✅ Done with quick task? → Tick `[x]` immediately
    │
    ▼
/push ["message"]
    │
    │  📝 Update CHANGELOG
    │  ⬆️ Push to GitHub
    │
    ▼
/end [project] [done]
    │
    │  💾 Save session tracking log
    │  🔥 Hot Lane Sync: [x] → done.md (#session), [ ] → ask to keep/promote
    │  💡 Smart Suggest: prompts to mark strategic tasks Done from session log
    │  📐 Check plan phase progress
    │  🧹 Automatically untick active_plan (if marked 'done')

⚠️ DO NOT run /backlog update mid-session. /end is the sole sync point.

Hot Lane: Quick Tasks

sprint-current.md is the Hot Lane — an agent-writable buffer region for ad-hoc tasks generated while coding. It is NOT a sprint board.

## Quick Tasks

- [x] Fix typo in README ← done during this session
- [ ] Add error handling to API ← left open

## Notes

Sprint focus: Phase 2 tasks

Upon running /end:

• Items with [x] → relocated to done.md with the #session tag
• Items with [ ] → prompts user: retain for next session or promote to backlog proper

2. Release Cycle Flow

This flow triggers upon software release/version cycle completion.

/plan review          → View completed phase progress
    ↓
/backlog review       → Check task statuses for the current active phase
    ↓
[Development Sprint]  → 1-2 days/phase average
    ↓
/release [project]    → Generates CHANGELOG, Git tags, push sequence
    ↓
/deploy               → Production verification & QA

Plan Archiving Lifecycle

When all phases = 100%, /plan review performs an automated cleanup:

1. Translocates plan to artifacts/plans/done/[plan-name].md
2. Creates a completion review at artifacts/plans/done/[plan-name]-review.md
3. Strips active_plan indicator from target project.md
4. Recommends initializing /retro procedure

Both plan & review rest together in the done/ folder context. /retro acts centrally to read a single organized location.

3. Operations Flow

Executes on-demand (never daily).

Artifact Relationship Architecture

project.md (active_plan, has_rules)
    │
    │ points to
    ▼
Plan (artifacts/plans/)              ← HOW & ORDER
    │                                   archived to: plans/done/ (+ review)
    │ maps against
    ▼
Backlog (artifacts/tasks/backlog.md) ← WHAT & STATUS (strategic anchor)
    │
    │ buffer quick tasks during session
    ▼
Hot Lane (sprint-current.md)         ← BUFFER (ad-hoc, agent-writable)
    │
    │ /end syncs both to
    ▼
Done (artifacts/tasks/done.md)       ← FULL RECORD (#backlog + #session tags)
    │
    │ captures session evidence
    ▼
Session Log (sessions/YYYY-MM-DD.md) ← DAILY EVIDENCE
    │
    │ parses and renders on release process
    ▼
CHANGELOG → GitHub Release           ← PUBLIC DISTRIBUTION RECORD

CLI System: update vs install

⚠️ install DOES NOT pull targets from GitHub. Always apply update to acquire the highest version available directly.

Best Practices

✅ DO

• Always launch environments bridging context via /open.
• Conduct iterative saves invoking /push frequently (small atomic commits > 1 massive block).
• Unexpected task occurs → note down - [ ] into sprint-current.md BEFORE coding it out.
• Tie off shifts with /end — single sync anchor (auto Hot Lane Sync + Smart Suggest algorithms).
• Use ./para update if GitHub alignment is essential.

❌ DON’T

• Circumvent /open to code directly bare.
• Ignore /end, resulting in lost context arrays the consequent day.
• Run /backlog update amidst session workflow stream — allow /end to mitigate and synchronize properly.
• Load totality of backlog/plan documents during /open — parse only the grep summaries contextually.
• Mistakenly trigger ./para install --force looking for fresh GitHub repo data sources.

Related Knowledge Tracks

• Strategy Plan Flow Guide — Tri-tier routing framework Strategy → Roadmap → Plan (v1.6.1)
• Planning Guide — Complete granular instructions regarding Plan + Backlog structuring.
• Workflows Reference — Official registry versions & capabilities index for AI Workflows.
• Architecture — Repo ↔ Workspace interplay definitions.

Updated in v1.6.1 (Strategy 3-tier scaling map, Planning Flow sequence overhauled)