@dv.nghiem/flowdeck 0.2.3 → 0.3.0

package/src/workflows/multi-repo-flow.md

@@ -1,226 +0,0 @@
----
-name: multi-repo-flow
-description: "Cross-repo change orchestration — analyze-repos → identify-dependencies → plan-changes → execute-per-repo → verify-integration"
-steps:
-  - name: analyze_repos
-    agent: "@multi-repo-coordinator"
-    action: Read .planning/config.json sub_repos, verify all paths exist, load tech stacks
-  - name: identify_dependencies
-    agent: "@multi-repo-coordinator + @architect"
-    action: Build dependency graph from service roles and API references; classify change as breaking or non-breaking
-  - name: plan_changes
-    agent: "@architect"
-    action: Write contract-first change spec and per-repo CHANGE PLAN ordered by dependency graph
-  - name: execute_per_repo
-    agent: "@coder + @tester"
-    action: Implement changes in each repo in dependency order; upstream before downstream
-  - name: verify_integration
-    agent: "@tester + @reviewer"
-    action: Run cross-repo integration tests; verify no consumer broke; reviewer signs off on each repo
----
-
-# Multi-Repo Flow
-
-## Purpose
-
-Orchestrates a feature or fix that spans multiple repositories in a microservice architecture. Ensures changes propagate in the correct dependency order, API contracts are agreed before implementation, and integration is verified end-to-end before any service ships to production.
-
-## When to Use
-
-- A feature requires changes in two or more services
-- An API contract is changing in an upstream service with downstream consumers
-- A shared library is being upgraded with a breaking change
-- You need a coordinated rollout across services (canary → stage → prod in dependency order)
-
-Do not use for single-repo work. Use `/new-feature` instead.
-
-## Prerequisites
-
-Before running this flow:
-1. `.planning/config.json` has a `sub_repos` array with the relevant repos registered
-2. All `path` values in the registry resolve to actual directories on disk
-3. A description of the intended change is available (from `/discuss` or passed directly)
-
-If the registry is empty or not set up, run `/multi-repo --add` first.
-
-## Step-by-Step Execution
-
-### Step 1: Analyze Repos
-
-`@multi-repo-coordinator` reads `.planning/config.json` and produces a registry summary:
-
-```
-Registry Summary
-  user-service     ../user-service     upstream-api         node+typescript
-  order-service    ../order-service    downstream-consumer  node+typescript
-  shared-types     ../shared-types     shared-lib           node+typescript
-  api-gateway      ../api-gateway      gateway              nginx+lua
-
-Path check: all 4 repos resolved ✅
-```
-
-If any path fails to resolve, the flow stops here with a clear error. The registry must be clean before proceeding.
-
-### Step 2: Identify Dependencies
-
-`@multi-repo-coordinator` and `@architect` work together to:
-
-1. Build the dependency graph from service roles and actual API references (scan client code, package.json, service mesh config)
-2. Classify the requested change as breaking or non-breaking for each affected service
-3. Produce the ordered change list
-
-```
-Dependency Graph
-  shared-types (shared-lib)
-    └── user-service
-    └── order-service
-  user-service (upstream-api)
-    └── order-service  ← calls GET /users/:id
-  api-gateway (gateway)
-    └── user-service
-    └── order-service
-
-Change classification:
-  shared-types: additive (non-breaking)
-  user-service: new endpoint (non-breaking)
-  order-service: client update required (triggered by user-service change)
-  api-gateway: new route entry (non-breaking)
-```
-
-If any circular dependency is detected, the flow stops and reports the cycle. Circular dependencies cannot be resolved automatically.
-
-### Step 3: Plan Changes
-
-`@architect` produces the cross-repo CHANGE PLAN using contract-first development:
-
-1. Write the new API contract or type definition before any implementation starts
-2. Confirm the contract covers all required changes without unnecessary scope creep
-3. Produce a per-repo task list ordered by the dependency graph
-
-Contract format (example):
-```typescript
-// shared-types: new interface
-interface UserPreferences {
-  userId: string;
-  notificationsEnabled: boolean;
-  timezone: string;              // new field
-}
-```
-
-Per-repo CHANGE PLAN format:
-```
-Repo 1: shared-types  (deploy first)
-  Task: Add `timezone: string` to UserPreferences
-  File: src/types/user.ts
-  Breaking: No
-
-Repo 2: user-service  (deploy after shared-types)
-  Task: Expose PATCH /users/:id/preferences including timezone
-  Files: src/routes/preferences.ts, src/handlers/preferences.ts
-  Breaking: No (new endpoint)
-  Contract: shared-types UserPreferences v1.1
-
-Repo 3: order-service  (deploy after user-service)
-  Task: Read timezone from user preferences when scheduling order notifications
-  Files: src/services/notification.ts
-  Breaking: No
-  Depends on: user-service PATCH /users/:id/preferences live
-
-Repo 4: api-gateway  (deploy last)
-  Task: Route PATCH /users/:id/preferences to user-service
-  Files: config/routes.yaml
-  Breaking: No
-```
-
-### Step 4: Execute Per Repo
-
-Changes execute in dependency order. For each repo:
-
-1. `@coder` implements the changes in that repo
-2. `@tester` writes and runs tests for that repo's changes
-3. No downstream repo starts until the upstream repo's changes pass tests
-
-For non-breaking changes, `@coder` and `@tester` for a given repo run in parallel (Wave 3 pattern from parallel-execution-flow). For breaking changes, `@tester` must verify the upstream before `@coder` starts on any downstream.
-
-**Upstream repo execution:**
-```
-@coder (user-service): implement PATCH /users/:id/preferences
-@tester (user-service): write integration tests for new endpoint
-→ both run in parallel within this repo
-→ all tests must pass before order-service changes begin
-```
-
-**Downstream repo execution (after upstream confirmed):**
-```
-@coder (order-service): update notification service to read timezone
-@tester (order-service): verify notification scheduling with timezone
-→ both run in parallel within this repo
-```
-
-If a repo's `@coder` or `@tester` fails, that repo and all downstream repos in the dependency chain are paused. Upstream repos that completed are not rolled back — they remain deployed. The flow resumes once the failing repo is fixed.
-
-### Step 5: Verify Integration
-
-After all per-repo changes are complete, `@tester` and `@reviewer` run cross-repo verification:
-
-**@tester (integration):**
-```
-Task: Run end-to-end integration tests covering the full change path
-Scope: user-service → order-service interaction via the new preferences endpoint
-Test environment: staging (all services deployed to stage)
-```
-
-**@reviewer (cross-repo review):**
-```
-Task: Review all changed files across all repos
-Check: contract adherence, no breaking changes introduced unintentionally,
-       consistent error handling patterns across services
-```
-
-Both run in parallel. Integration tests failing in stage block the production rollout for the entire change set.
-
-## Rollout After Integration Pass
-
-Once integration is verified in staging, deploy in dependency order:
-
-```
-1. shared-types  →  publish to package registry (semver minor)
-2. user-service  →  canary (5% traffic, 15 min) → stage ✅ → prod
-3. order-service →  canary (after user-service prod) → stage ✅ → prod
-4. api-gateway   →  canary (after order-service prod) → stage ✅ → prod
-```
-
-No downstream service enters its canary phase until the upstream service is confirmed stable in production.
-
-## Conflict Handling
-
-If `@multi-repo-coordinator` detects a conflict during Step 2 or Step 3 (two concurrent changes that are incompatible), the flow pauses:
-
-```
-FLOW PAUSED — Conflict Requires Resolution
-
-  Service A (user-service): removing `legacyUserId` from response
-  Service B (order-service PR #47): new consumer of `legacyUserId`
-  Classification: Breaking API collision
-
-  Resolution options:
-    A. Versioned endpoint: keep /v1/users (with legacyUserId) + add /v2/users (without)
-    B. Coordinate: block order-service PR #47 until user-service migration is complete
-    C. Reverse: defer the user-service removal until order-service removes its dependency
-
-  Owner teams: platform (user-service), commerce (order-service)
-  Decision required before this flow can continue.
-```
-
-The flow does not auto-resolve conflicts. It surfaces them clearly, names the options, and waits for human direction.
-
-## Error Conditions
-
-| Condition | Action |
-|-----------|--------|
-| Registry path not found on disk | Stop at Step 1; report which path failed |
-| Circular dependency in graph | Stop at Step 2; show the cycle |
-| Contract review rejected | Stop at Step 3; rework contract before proceeding |
-| Repo's tests fail | Pause that repo and all dependents; upstream remains deployed |
-| Integration test fails | Block production rollout; report which test failed and why |
-| Conflict detected | Pause flow; surface options; wait for human decision |

package/src/workflows/parallel-execution-flow.md

@@ -1,236 +0,0 @@
----
-name: parallel-execution-flow
-description: "Wave-based parallel agent execution — analyze → assign waves → execute wave 1 → execute wave 2 → merge → review"
-steps:
-  - name: analyze
-    agent: "@parallel-coordinator"
-    action: Read PLAN.md, identify all tasks, classify each as blocking or independent
-  - name: assign_waves
-    agent: "@parallel-coordinator"
-    action: Group tasks into waves based on dependency graph, emit WAVE TABLE
-  - name: execute_wave_1
-    agent: "@researcher + @code-explorer"
-    action: Run discovery tracks simultaneously — research external APIs, map unfamiliar code
-  - name: execute_wave_2
-    agent: "@architect"
-    action: Design interfaces and produce ADR using Wave 1 findings — serial, gates Wave 3
-  - name: execute_wave_3
-    agent: "@coder + @tester"
-    action: Implement code and write tests in parallel from @architect contracts
-  - name: merge
-    agent: "@parallel-coordinator"
-    action: Compare file sets from Wave 3 tracks, detect overlaps, run conflict resolution if needed
-  - name: review
-    agent: "@reviewer + @security-auditor"
-    action: Validate code quality and security simultaneously, log non-blocking issues
----
-
-# Parallel Execution Flow
-
-## Purpose
-
-Executes a PLAN.md using the wave-based parallel model. Maximizes agent throughput by running independent tracks simultaneously while respecting dependency gates between waves.
-
-## When to Use
-
-- A PLAN.md has tasks that can be classified as independent of each other
-- Estimated sequential time exceeds 30 minutes
-- Tasks span research, design, implementation, and testing — roles that don't share files
-
-## Wave Architecture
-
-The flow organizes work into four standard waves. Not every job needs all four — omit waves with no work.
-
-```
-Wave 1: Discovery
-  @researcher ──────────────────────┐
-  @code-explorer ───────────────────┤ (parallel)
-                                    ▼
-Wave 2: Architecture            [gate: wait]
-  @architect ───────────────────────┐ (serial)
-                                    ▼
-Wave 3: Implementation          [gate: wait]
-  @coder ───────────────────────────┤
-  @tester ──────────────────────────┤ (parallel)
-                                    ▼
-Wave 4: Validation              [gate: wait]
-  @reviewer ────────────────────────┤
-  @security-auditor ────────────────┘ (parallel)
-```
-
-Each wave gate waits for all **blocking** slots in the wave to complete before the next wave starts. Independent failures in a wave are retried asynchronously without blocking the gate.
-
-## Step-by-Step Execution
-
-### Step 1: Analyze
-
-`@parallel-coordinator` reads PLAN.md and produces:
-- A task list with estimated duration per task
-- Dependency classification: which tasks block others
-- Slot assignment: which agent handles each task
-
-If PLAN.md is missing or unconfirmed, abort:
-```
-Error: No confirmed PLAN.md found.
-Run /plan to produce a plan, then re-run this flow.
-```
-
-### Step 2: Assign Waves
-
-`@parallel-coordinator` groups tasks into waves and emits the WAVE TABLE:
-
-```
-╔══════════════════════════════════════════════════════════════╗
-║  WAVE TABLE — [Feature Name]                                 ║
-╠══════════════════════════════════════════════════════════════╣
-║  Wave 1 (parallel)  │ @researcher + @code-explorer          ║
-║  Wave 2 (serial)    │ @architect                             ║
-║  Wave 3 (parallel)  │ @coder + @tester                      ║
-║  Wave 4 (parallel)  │ @reviewer + @security-auditor         ║
-╠══════════════════════════════════════════════════════════════╣
-║  Blocking locks:    │ W3 blocked on W2; W4 blocked on W3    ║
-╚══════════════════════════════════════════════════════════════╝
-```
-
-Print this before spawning any agents. It is the execution contract for the job.
-
-### Step 3: Execute Wave 1
-
-Delegate to `@researcher` and `@code-explorer` simultaneously:
-
-**@researcher brief:**
-```
-Task: [specific research objective]
-Deliverable: .planning/research/[topic].md
-Sources to check: [list]
-Do NOT touch any source files.
-```
-
-**@code-explorer brief:**
-```
-Task: Map [module/directory] — produce a file inventory with function signatures
-Deliverable: .codebase/[module]-map.md
-Do NOT touch any source files.
-```
-
-Both briefs are sent at the same time. `@parallel-coordinator` waits for both to complete before Wave 2.
-
-### Step 4: Execute Wave 2
-
-Delegate to `@architect` with Wave 1 outputs attached:
-
-**@architect brief:**
-```
-Task: [design objective]
-Inputs:
-  - Wave 1 research: .planning/research/[topic].md
-  - Wave 1 code map: .codebase/[module]-map.md
-Deliverables:
-  - .planning/adr/[name].md
-  - Interface contracts (TypeScript interfaces or equivalent)
-Do NOT touch source files — contracts only.
-```
-
-`@parallel-coordinator` waits for `@architect` to complete before Wave 3.
-
-### Step 5: Execute Wave 3
-
-Delegate to `@coder` and `@tester` simultaneously using `@architect` output as the shared source of truth:
-
-**@coder brief:**
-```
-Task: Implement [feature] per the interface contracts
-Inputs:
-  - Contracts: .planning/adr/[name].md
-  - Research: .planning/research/[topic].md
-Files to create/modify: [list]
-Do NOT modify the contract file.
-```
-
-**@tester brief:**
-```
-Task: Write tests for [feature] per the interface contracts
-Inputs:
-  - Contracts: .planning/adr/[name].md  ← use this, not @coder output
-Test file: [path]
-Coverage target: all public interface methods + error paths
-Do NOT read or depend on @coder's implementation files.
-```
-
-Both are sent at the same time. `@tester` works from contracts, not from `@coder`'s code, so they are truly parallel.
-
-### Step 6: Merge
-
-`@parallel-coordinator` compares Wave 3 outputs:
-
-1. Collect file lists from `@coder` and `@tester`
-2. Check for overlapping files
-3. If no overlap: apply both, proceed to Wave 4
-4. If overlap detected: classify (additive vs structural vs contradictory) and resolve per the conflict resolution protocol
-
-Merge report format:
-```
-Wave 3 Merge Check
-  @coder touched: src/auth/service.ts, src/auth/session.ts
-  @tester touched: src/auth/service.test.ts
-  Overlap: none ✅
-```
-
-If conflict:
-```
-Wave 3 Merge Check
-  Overlap: src/types/user.ts
-  Classification: Structural — incompatible interface definitions
-  Resolution: delegating to @coder for sequential reconciliation
-```
-
-### Step 7: Review
-
-Delegate to `@reviewer` and `@security-auditor` simultaneously:
-
-**@reviewer brief:**
-```
-Review all files changed in Wave 3: [list]
-Flag: logic errors, code style violations, missing error handling
-Do NOT refactor — flag issues only.
-```
-
-**@security-auditor brief:**
-```
-Audit entry points and data flows in: [list]
-Focus: injection surfaces, auth bypass paths, unvalidated inputs
-Report all findings, severity-tagged.
-```
-
-Both are sent at the same time. Either may fail independently without blocking the other.
-
-## Failure Recovery
-
-| Failure Type | Action |
-|-------------|--------|
-| Blocking slot fails | Pause dependent downstream slots; retry with fallback brief |
-| Independent slot fails | Log and continue; retry async after wave closes |
-| Merge conflict detected | Invoke conflict resolution; re-run affected downstream slots |
-| All slots in a wave fail | Abort job; report which wave failed and why |
-
-## Output: Execution Summary
-
-After all waves complete, `@parallel-coordinator` produces:
-
-```markdown
-## Parallel Execution Summary
-
-Feature: [name]
-Total elapsed: [time] (vs [sequential estimate] sequential)
-
-| Wave | Agents | Status | Key Outputs |
-|------|--------|--------|-------------|
-| 1 | @researcher, @code-explorer | ✅ | research doc, code map |
-| 2 | @architect | ✅ | ADR, contracts |
-| 3 | @coder, @tester | ✅ | implementation, 14 tests |
-| 4 | @reviewer, @security-auditor | ⚠️ | 2 issues filed; audit retry pending |
-
-Conflicts resolved: 0
-Files changed: [N]
-Tests: [N passing]
-```

package/src/workflows/plan-flow.md

@@ -1,126 +0,0 @@
----
-name: plan-flow
-description: "Orchestrates plan phase (guard check → context load → draft plan → validate → review → PAUSE CONFIRM → save)"
-triggers:
-  - /plan
-steps:
-  - name: guard_check
-    agent: "@orchestrator"
-    priority: first
-    action: Verify DISCUSS.md exists and is confirmed; abort if not
-  - name: load_context
-    agent: "@orchestrator"
-    action: Load PROJECT.md, STATE.md, DISCUSS.md with D-XX decisions
-  - name: draft_plan
-    agent: "@planner"
-    action: Create PLAN.md with tasks traced to D-XX decisions from DISCUSS.md
-  - name: validate_plan
-    agent: "@plan-checker"
-    action: Verify all requirements covered, all D-XX decisions addressed
-  - name: review_plan
-    agent: "@orchestrator"
-    action: Present draft plan for user review
-  - name: pause_confirm
-    agent: "@orchestrator"
-    action: "PAUSE — wait for user CONFIRM before saving"
-  - name: save_plan
-    agent: "@orchestrator"
-    action: Save confirmed PLAN.md to .planning/phases/phase-N/
-  - name: update_state
-    agent: "@orchestrator"
-    action: Update STATE.md with plan file path
----
-
-# Plan Flow
-
-## Purpose
-
-Create a detailed implementation plan from confirmed DISCUSS.md decisions.
-
-## Process
-
-### Step 1: Guard Check
-
-D-06: Verify DISCUSS.md exists and is confirmed.
-
-If no DISCUSS.md found:
-```
-Error: DISCUSS.md not found. Run /discuss [topic] first.
-```
-
-If DISCUSS.md exists but not confirmed:
-```
-Error: DISCUSS.md not yet confirmed. Complete the discuss phase first.
-```
-
-Abort with clear error message in both cases.
-
-### Step 2: Load Context
-
-Read:
-- PROJECT.md (project context)
-- STATE.md (current phase and position)
-- DISCUSS.md (D-XX decisions to trace in plan)
-
-### Step 3: Draft Plan
-
-Create PLAN.md with:
-- Tasks that trace to D-XX decisions from DISCUSS.md
-- Each task includes `<action>` referencing relevant D-XX decisions
-- Wave assignments for parallel execution
-- File dependencies between tasks
-
-### Step 4: Validate Plan
-
-Verify:
-- All requirements from ROADMAP.md for current phase are addressed
-- All D-XX decisions from DISCUSS.md are traced in plan tasks
-- No tasks that contradict prior decisions
-
-If validation fails, return to Step 3 to revise.
-
-### Step 5: Review Plan
-
-Present draft plan to user:
-- Show all tasks and their D-XX decision traces
-- Show wave structure
-- Show file dependencies
-
-### Step 6: PAUSE CONFIRM
-
-D-06: "PAUSE — wait for user CONFIRM before saving"
-
-Present:
-```
-Ready to save PLAN.md?
-Type CONFIRM to save, or describe changes needed.
-```
-
-If user types CONFIRM, proceed to Step 7.
-If user requests changes, return to Step 3 with feedback.
-
-### Step 7: Save Plan
-
-Save PLAN.md to `.planning/phases/phase-N/PLAN.md`.
-Commit with message: `docs(phase-N): save confirmed plan`
-
-### Step 8: Update State
-
-Update STATE.md:
-- Set plan_file to path of saved PLAN.md
-- Set plan_confirmed: true
-- Update last_action to "Plan confirmed"
-
-## D-06 Compliance
-
-- Requires confirmed DISCUSS.md before proceeding
-- Aborts with clear error if DISCUSS.md not confirmed
-- Creates PLAN.md tracing D-XX decisions
-- Pauses for user CONFIRM before saving
-
-## Error Handling
-
-D-03: Fail fast with clear error
-- If guard check fails: abort with clear error and remediation
-- If plan validation fails: show what's missing
-- No partial plan saved on error

package/src/workflows/plan-phase.md

@@ -1,101 +0,0 @@
----
-name: plan-phase
-description: "Orchestrates /plan-phase — delegates to planner then plan-checker"
-triggers:
-  - /plan-phase
-steps:
-  - name: delegate_to_planner
-    agent: "@planner"
-    action: Spawn planner agent to create PLAN.md
-  - name: verify_plan_quality
-    agent: "@plan-checker"
-    action: Spawn plan-checker agent to verify plan completeness, feasibility, testability
-  - name: present_results
-    agent: "@orchestrator"
-    action: Present results to user — PASS or FAIL with recommendations
----
-
-# Plan Phase Workflow
-
-## Purpose
-
-Execute `/plan-phase [N]` to create a structured implementation plan using FlowDeck agents.
-
-## Process
-
-### Step 1: Delegate to planner
-
-Spawn planner agent with:
-- ROADMAP.md (phase structure)
-- REQUIREMENTS.md (requirements for this phase)
-- PROJECT.md (project context)
-- Phase number N
-
-Agent will produce `.planning/phases/phase-N/PLAN.md`.
-
-### Step 2: Verify Plan Quality
-
-Spawn plan-checker agent to review PLAN.md:
-
-**Completeness checklist:**
-- [ ] All requirements mapped to tasks?
-- [ ] Each task has clear scope?
-- [ ] Dependencies clearly marked?
-
-**Feasibility checklist:**
-- [ ] Each task completable in one session?
-- [ ] No circular dependencies?
-- [ ] Tools/resources available?
-
-**Testability checklist:**
-- [ ] Success criteria observable?
-- [ ] Can verify without running full system?
-- [ ] Edge cases addressed?
-
-### Step 3: Present Results
-
-Return structured output:
-```
-## Plan Phase [N] Results
-
-**Plan:** [plan name]
-**Tasks:** [N] tasks in [waves] waves
-
-### Verification
-- [ ] PASS — Plan ready for execution
-- [ ] FAIL — Issues found:
-
-  ### Recommendations
-  - [issue and fix recommendation]
-```
-
-### Step 4: On PASS
-
-Update STATE.md:
-- Set plan_file to `.planning/phases/phase-N/PLAN.md`
-- Set plan_confirmed: true
-- confirmed_at: [timestamp]
-
-Output: "Plan ready. Run /execute-phase [N] to implement."
-
-### Step 5: On FAIL
-
-Return to user for decisions:
-```
-Plan not yet ready. Review findings above and:
-- Type CONFIRM to proceed anyway (accept gaps)
-- Type FIX to have planner revise the plan
-- Describe specific changes needed
-```
-
-## Agent Configuration
-
-| Agent | Model | Purpose |
-|-------|-------|---------|
-| planner | Sonnet 4.6 | Creates executable PLAN.md with task breakdown |
-| plan-checker | Haiku 4.5 | Reviews plan quality before execution |
-
-## Output Files
-
-- `.planning/phases/phase-N/PLAN.md` — implementation plan
-- `.planning/phases/phase-N/VERIFICATION.md` — checker output (if FAIL)