Flowforge Workflow

Folder Structure

worktickets/
├── draft/           # AI creates tickets here
├── active/          # PM moves approved tickets here (one at a time)
├── completed/       # PM archives completed tickets
│   └── phase_N/     # Organized by phase
└── validation/
    ├── active/      # Current validation tickets
    └── completed/   # Archived validation tickets

Rules

1. Never skip quality gates - Each step must pass its gate before proceeding
2. Checkpoints are mandatory - Generate checkpoint before major transitions
3. PM approval required for:
   • Draft → Active ticket transitions
   • Merge to main
   • Direction changes or scope adjustments
4. All work on feature branches - Never commit directly to main
5. Single active ticket - Only one ticket in active/ at any time
6. Evidence-based claims - All "working" claims require PM validation

Checkpoint Generation

Generate checkpoints at these key transitions:

• Before PR submission
• After PR review rounds complete
• When significant decisions are made
• When drift is detected (any level)
• At PM request

See templates/checkpoint.md for the checkpoint format.

Supporting Documents

Layer 0/1 (Sequential)

• workflow_rules.md - Detailed step definitions
• quality_gates.md - Gate requirements for each transition
• drift_indicators.md - What signals quality drift
• pr_triage.md - PR comment triage rules (Layer 1)
• templates/checkpoint.md - Checkpoint template
• templates/checkpoint_pr_ready.md - PR ready checkpoint

Layer 2 (Parallel Execution - Unified Branch)

• parallel_orchestrator.md - How to coordinate parallel sessions (unified branch approach)
• parallel_session_instructions.md - Rules for sessions working on parallel tickets
• congruence_validator.md - Validation checks before committing parallel work
• templates/dependency_analysis.md - Template for ticket dependency analysis
• templates/checkpoint_parallel.md - Unified checkpoint for parallel groups
• docs/research/parallel-claude-code-workflows.md - Industry tools analysis

Layer 2: Parallel Execution (Unified Branch)

When multiple tickets in a task are independent, they can be worked on simultaneously using the unified branch approach.

Why Unified Branch?

For Rust/Tauri projects, worktrees fail because:

• TypeScript bindings require ALL Rust types to exist
• Pre-commit hooks (clippy) fail on incomplete types
• Sessions write placeholder code to pass hooks (bad)

Solution: Multiple sessions in SAME directory, SAME branch, deferred finalization.

See docs/research/parallel-claude-code-workflows.md for full analysis.

When to Use Layer 2

• Task has DEPENDENCY_ANALYSIS.md identifying parallel groups
• PM has approved parallel execution
• Tickets don't share files (or sharing is managed)

Layer 2 Workflow

1. Create DEPENDENCY_ANALYSIS.md for the task
2. PM approves parallel groups
3. Create unified branch: feature/p{phase}-unified-{tickets}
4. Open parallel sessions in same directory
5. Sessions implement code (NO bindings, NO commit)
6. Run finalization ONCE after all sessions complete
7. Single commit, single PR

Quick Reference

Prohibited in Parallel Sessions

• pnpm bindings - wait for finalization
• cargo clippy - wait for finalization
• pnpm lint - wait for finalization
• git commit - PM handles after finalization
• Placeholder code - NEVER acceptable

Parallel Gate Orchestration

When /flowforge-workflow is invoked and a parallel gate is current, provide a complete orchestration package.

Step 1: Identify Current State

1. Read DEPENDENCY_ANALYSIS.md for the current task (e.g., worktickets/draft/draft_3.10/DEPENDENCY_ANALYSIS.md)
2. Find the gate marked 🔄 CURRENT
3. List all tickets in that gate

Step 2: Review Each Ticket

For each ticket in the current gate:

1. Read the ticket file from worktickets/draft/
2. Verify dependencies are marked ✅ complete
3. Verify "Parallel Execution Mode" section exists
4. Extract: files to modify, risk level, blocking issues

Step 3: Generate Orchestration Package

Output these sections in order:

Section 1: Gate Status

## Gate N Status: 🔄 CURRENT

| Ticket | Description | Dependencies | Ready? |
|--------|-------------|--------------|--------|
| X.XX.XX | [name] | [dep] ✅ | ✅ Ready |

Prerequisites: Gate N-1 ✅ Complete (PR #XXX)

Section 2: Ticket Review

For each ticket:

### Ticket Review: X.XX.XX

**Files to create/modify:**
- [list from ticket]

**Risk:** [from ticket Layer 2 Metadata]
**Ready:** ✅ Dependencies met, no conflicts

Section 3: Session Prompts

Ready-to-copy prompts for PM:

## Session Prompts

**Session 1 ([ticket name]):**
\`\`\`
Implement ticket X.XX.XX ([name]) per
worktickets/draft/draft_3.10/wt_p3_tX.XX.XX_[name].md

PARALLEL MODE - Do NOT run bindings, clippy, or commit.
Report when code is written with list of files modified.
\`\`\`

Section 4: Finalization Command

## Finalization (run after ALL sessions complete)

\`\`\`bash
cd verba-app && pnpm bindings && cargo fmt --all && cargo clippy -- -D warnings && pnpm lint --fix
\`\`\`

## Post-Finalization Checklist
- [ ] No compilation errors
- [ ] TypeScript bindings generated
- [ ] Ready for commit

Section 5: Commit Template

## Commit (after finalization passes)

\`\`\`bash
git add -A && git commit -m "feat(enhancement): Gate N - [descriptions] (X.XX.XX, Y.YY.YY)

- [ticket 1 summary]
- [ticket 2 summary]

Co-Authored-By: Claude Opus 4.5 <[email protected]>"
\`\`\`

When No Parallel Gate is Current

If invoked during sequential work (Layer 0/1), provide:

1. Current ticket status
2. Next steps per workflow_rules.md
3. Quality gate checklist for current phase