Dev Workflow

How does the engineering team ship new features and fix existing issues without blocking either?

Overview

Two parallel streams, two worktrees, one repo. New PRD features build forward. Existing issues fix backward. Neither blocks the other.

main
 ├── worktree: feature/{prd-name}   ← new capabilities from PRD specs
 └── worktree: fix/{issue-number}   ← existing issues from issues log

Worktrees Workflow

Git worktrees let you check out multiple branches of the same repo simultaneously in separate directories. No stashing, no context switching, no lost work.

Setup

# From the main repo directory
git worktree add ../sm-feature feature/prd-sales-crm
git worktree add ../sm-fix fix/issue-14-deal-detail

Each worktree is a full working copy with its own branch, sharing the same .git history.

Two Streams

Stream	Worktree	Input	Branch Pattern	Output
Build	../sm-feature	PRD spec (src/pages/priorities/prd-*/spec/)	feature/{prd-name}	New capabilities at L1-L2
Fix	../sm-fix	Issues Log	fix/{issue-number}-{slug}	Issues resolved, capabilities promoted L2-L3-L4

Build Stream

Engineering reads the PRD spec and builds new features.

1. Read PRD: src/pages/priorities/prd-{name}/index.md and spec/index.md
2. Create worktree: git worktree add ../sm-feature feature/prd-{name}
3. Build against the feature table in the spec
4. PR to main when feature is deployable
5. Commissioner verifies on production → capability promoted

Fix Stream

Engineering reads the issues log and fixes bugs.

1. Read issues: src/pages/priorities/issues-log.md
2. Pick highest severity issue
3. Create worktree: git worktree add ../sm-fix fix/{issue-number}-{slug}
4. Fix, test, PR to main
5. Commissioner verifies on production → issue moved to Resolved

Lifecycle

Commissioner dogfoods app
    ├── finds issue → issues-log.md → fix worktree → PR → verify → resolved
    └── finds gap  → PRD spec update → build worktree → PR → verify → promoted

Cleanup

# After PR is merged
git worktree remove ../sm-fix
git branch -d fix/issue-14-deal-detail

Agent Workflow

AI agents follow the same two-stream pattern. The agent reads either a PRD spec (build) or the issues log (fix), never both in the same session.

Agent Mode	Reads	Produces	Commissioning
project-from-prd	PRD spec + feature table	New routes, components, API endpoints	L1 → L2
fix-from-issues	Issues log + reproduction steps	Bug fixes, missing routes, redirects	L2 → L3

Dig Deeper

• Outer Loop Validation — Capability map for validating engineering reality from the dream repo
• Flow Engineering — Maps that produce code artifacts
• Type-First Development — Types before implementation
• AI Coding — Agent configuration and coding patterns

Context

• Issues Log — The fix queue
• Business Factory Requirements — The build queue (table order = build order)
• Commissioning Dashboard — Capability status
• Commissioning Protocol — L0-L4 maturity

Questions

What's the cost of context-switching between building and fixing in the same worktree?

• If the fix stream consistently outpaces the build stream, what does that signal about spec quality?
• When should an issue graduate from "fix" to "new PRD feature"?
• How do you prevent the fix worktree from becoming a graveyard of LOW-severity cosmetic issues?