@dv.nghiem/flowdeck 0.2.3 → 0.3.0

package/src/commands/fd-multi-repo.md

@@ -1,14 +1,32 @@
 ---
-description: Manage multi-repo registry in .planning/config.json — add, list, status, or remove repos
+description: Cross-repo change orchestration — analyze-repos → identify-dependencies → plan-changes → execute-per-repo → verify-integration
 argument-hint: [list | add <path> [name] | remove <name> | status]
 ---
 
 # Multi-Repo
 
-Manage a multi-repository workspace registry.
+Orchestrates a feature or fix that spans multiple repositories in a microservice architecture.
 
 **Input:** $ARGUMENTS
 
+## 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
+
+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.
+
 ## Behavior
 
 ### List (`list` or no arguments)
@@ -19,10 +37,12 @@ Read `.planning/config.json` → `repos` array. Display:
 ════════════════════════════════════
 MULTI-REPO REGISTRY
 ════════════════════════════════════
-  frontend  — ./packages/frontend  (phase 2, in_progress)
-  backend   — ./packages/backend   (phase 3, completed)
-  shared    — ./packages/shared    (phase 1, planned)
-════════════════════════════════════
+  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 ✅
 ```
 
 ### Add (`add <path> [name]`)
@@ -51,6 +71,110 @@ WORKSPACE STATUS
 Overall: 1 in progress, 1 complete, 1 planned
 ```
 
+## Execution Flow
+
+### Step 1: Analyze Repos
+
+`@multi-repo-coordinator` reads `.planning/config.json` and produces a registry summary.
+
+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
+
+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
+
+### 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. For breaking changes, `@tester` must verify the upstream before `@coder` starts on any downstream.
+
+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 Handling
+
+| 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 |
+
 ## Config Format
 
 `.planning/config.json` repos entry:

package/src/commands/fd-new-feature.md

@@ -11,38 +11,181 @@ Implement a new feature using the full FlowDeck agent pipeline.
 
 ## Pre-flight
 
-1. Check `.planning/STATE.md` exists — if not, error: "Run /fd-new-project first."
+1. Check `.planning/` exists — if not, error: "Run /fd-new-project first."
 2. Check `plan_confirmed: true` in STATE.md — if not, error: "Confirm plan first with /fd-plan."
 3. Read `.planning/phases/phase-<N>/PLAN.md` to get implementation steps.
 4. Read `.codebase/ARCHITECTURE.md` if it exists — pass as context.
 
-## Execution Pipeline
+## TDD Cycle Per Step
 
-Run the following agent pipeline for feature: **$ARGUMENTS**
+Each plan step follows the TDD cycle:
 
-### Phase 1 — Analysis (parallel)
-- **@researcher**: Trace how $ARGUMENTS touches existing code, find relevant files, identify API contracts at risk
-- **@architect**: Identify architectural boundaries, flag integration points, check for pattern compliance
+```
+BEHAVIOR → RED → GREEN → REFACTOR → next step
+   ↑_________|        |
+   (loop if needed)  Only if GREEN
+```
 
-### Phase 2 — Implementation
-- **@coder**: Implement the feature following PLAN.md steps, CONVENTIONS.md patterns, and TDD discipline
-  - Write failing tests FIRST (RED)
-  - Implement minimum code to pass (GREEN)  
-  - Refactor if needed (REFACTOR)
+## Process
 
-### Phase 3 — Validation (parallel)
-- **@tester**: Run test suite, verify new tests pass, check coverage
-- **@reviewer**: Review implementation for quality, security, and convention compliance
+### Step 1: Guard Check
 
-### Phase 4 — State Update
-- Update `.planning/STATE.md` with completed steps
-- Write summary to `.planning/phases/phase-<N>/RESULT.md`
+Verify prerequisites:
+- `.planning/` directory exists
+- `.codebase/` directory exists
+- `STATE.md` has `plan_confirmed: true`
+- `PLAN.md` exists in current phase directory
 
-## Guard Rails
+Initialize TDD state:
+```yaml
+tdd:
+  stage: behavior
+  cycle: 1
+  behaviors: []
+  regression_test_links: []
+```
 
-- Block if `tdd_enforced: true` and no tests were written
-- Block if any CRITICAL security issues found
-- Require explicit confirmation before overwriting existing public APIs
+### Step 2: Load Plan
+
+Read the active PLAN.md from the current phase directory.
+Parse the tasks list and identify which steps are complete.
+
+### Step 3: Define Behaviors
+
+Spawn `@orchestrator` to generate behavior checklist from PLAN.md:
+- Acceptance cases for each step
+- Edge cases to test
+- Expected behaviors
+
+Store in TDD state.
+
+### Step 4: Identify Next Step
+
+From PLAN.md, find the first step NOT in `steps_complete`.
+Check TDD stage — only proceed if stage is appropriate for the step.
+
+### Step 5: Write Failing Tests (RED)
+
+Spawn `@tester` to write tests for the step's behavior:
+- **Tests MUST fail** before implementation
+- Cover acceptance cases and edge cases
+- Use AAA pattern (Arrange-Act-Assert)
+
+### Step 6: Confirm RED
+
+Run failing tests:
+- **GUARD: Do NOT proceed to Step 7 until tests fail**
+- If tests pass unexpectedly, tests don't correctly describe behavior
+
+### Step 7: Implement Minimum (GREEN)
+
+Spawn `@coder` to implement:
+- **Minimum code** to make failing tests pass
+- No speculative features
+- No over-engineering
+
+### Step 8: Confirm GREEN
+
+Run tests:
+- **GUARD: Do NOT proceed to Step 9 until tests pass**
+- If tests fail, return to Step 7
+
+### Step 9: Refactor (REFACTOR)
+
+Only if GREEN:
+- Clean up code for this step
+- Remove dead code
+- Improve readability
+- **GUARD: Do not refactor if not GREEN**
+
+### Step 10: Verify
+
+Run full test suite:
+- All tests must pass
+- If any fails, revert refactoring
+
+### Step 11: Review Step
+
+Spawn `@reviewer` to check:
+- Code quality, security, conventions
+- TDD discipline followed
+- Test coverage >= 80%
+- No missing or weak tests (flag as major finding)
+
+### Step 12: Update State
+
+Mark step complete via planning-state tool:
+```yaml
+steps_complete: [N, ...]
+last_action: "Step N complete via TDD: [behavior]"
+tdd:
+  stage: behavior  # Ready for next step
+```
+
+### Step 13: Loop or Complete
+
+If more steps pending:
+- Return to Step 3 (define behaviors for next step)
+
+If all steps complete:
+- Update phase status to "complete"
+- Update ROADMAP.md progress
+- Present completion summary
+
+## Wave-Based Execution
+
+WF-03 respects wave structure from PLAN.md:
+- Wave 1 steps execute first (with TDD cycle per step)
+- Wave 2 steps execute after Wave 1 completes
+- Wave 3 steps execute after Wave 2 completes
+- No intra-wave dependencies (parallel execution)
+
+## Guards Summary
+
+| Transition | Guard | If Violated |
+|-----------|-------|-------------|
+| behavior → red | Test written and fails | Block until test fails |
+| red → green | Test exists and fails | Block until test passes |
+| green → refactor | Tests are green | Block until green |
+| refactor → verify | All tests pass | Block until all pass |
+
+## Override Mechanism
+
+User can override with `/fd-new-feature --override`:
+- Every override is logged in `override_log`
+- Surface override in next review
+- Flag in deploy check
+
+## Error Handling
+
+D-03: Fail fast with clear error
+- If guard check fails: abort with clear error and remediation
+- If @coder fails: report failure, offer retry or skip
+- If @reviewer finds critical issues: return to Step 7 for fixes
+- No partial state saved on error
+
+## State Updates
+
+STATE.md updates after each step:
+```yaml
+steps_complete: [1, 2]      # Added after step 2
+steps_pending: [3, 4, 5]   # Removed step 2
+last_action: "Step 2 TDD complete: [behavior] (RED→GREEN→REFACTOR)"
+tdd:
+  stage: behavior
+  cycle: 2
+  behaviors_completed: 2
+```
+
+Full phase completion:
+```yaml
+status: complete
+last_action: "Phase N TDD complete — all steps finished"
+tdd:
+  stage: complete
+  cycles_used: N
+  behaviors_completed: M
+```
 
 ## Completion
 

package/src/commands/fd-new-project.md

@@ -98,6 +98,19 @@ confirmed_at: none
 
 3. Also create `.planning/phases/phase-1/` directory.
 
-4. Report success with the list of files created and next steps:
+4. Create `.planning/config.json` with default settings:
+
+```json
+{
+  "model_profile": "balanced",
+  "tdd_enforced": true,
+  "approval_required": false,
+  "volatility_threshold": 0.7,
+  "default_agent": "orchestrator"
+}
+```
+
+5. Report success with the list of files created and next steps:
    - Run `/fd-discuss` to capture project decisions
    - Run `/fd-plan` to create an implementation plan
+   - Edit `.planning/config.json` directly to change settings

package/src/commands/fd-plan.md

@@ -5,75 +5,97 @@ argument-hint: [--phase=N] [--yes]
 
 # Plan
 
-Create a detailed implementation plan from confirmed discussion decisions.
+Create a detailed implementation plan from confirmed DISCUSS.md decisions.
 
 **Input:** $ARGUMENTS (optional `--phase=N` to target a specific phase, `--yes` to skip confirmation)
 
-## Pre-flight
+## Process
 
-1. Check `.planning/STATE.md` exists — if not, return error: "Run /fd-new-project first."
-2. Determine phase: use `--phase=N` from arguments, or read current phase from STATE.md.
-3. Check `.planning/phases/phase-<N>/DISCUSS.md` exists — if not, return error: "Run /fd-discuss first."
+### Step 1: Guard Check
 
-## Confirmation Gate
+D-06: Verify DISCUSS.md exists and is confirmed.
 
-Unless `--yes` is passed or STATE.md already has `plan_confirmed: true`:
-
-Show a preview of the DISCUSS.md decisions found and ask:
+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.
 ```
-═══════════════════════════════════════════
-PLAN PHASE <N> — AWAITING CONFIRMATION
-═══════════════════════════════════════════
 
-Found <X> decisions in DISCUSS.md:
-<preview of D-XX lines>
+Abort with clear error message in both cases.
 
-Type CONFIRM to save PLAN.md and enable execution.
-═══════════════════════════════════════════
-```
+### Step 2: Load Context
 
-**PAUSE** — wait for user to type CONFIRM before proceeding.
+Read:
+- `.codebase/PROJECT.md` (project context)
+- `.planning/STATE.md` (current phase and position)
+- `.planning/phases/phase-<N>/DISCUSS.md` (D-XX decisions to trace in plan)
 
-## Plan Generation
+### Step 3: Draft Plan
 
-After confirmation:
+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
 
-1. Read all `D-XX: <decision>` lines from DISCUSS.md.
-2. Generate `.planning/phases/phase-<N>/PLAN.md`:
+### Step 4: Validate Plan
 
-```markdown
-# Implementation 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
 
-**Phase:** <N>
-**Created:** <timestamp>
-**Source:** DISCUSS.md (<X> decisions)
+If validation fails, return to Step 3 to revise.
 
-## Decisions
+### Step 5: Review Plan
 
-- D-01: <decision>
-- D-02: <decision>
+Present draft plan to user:
+- Show all tasks and their D-XX decision traces
+- Show wave structure
+- Show file dependencies
 
-## Steps
+### Step 6: PAUSE CONFIRM
 
-- [ ] Step 1: <concrete implementation step traced to decision>
-- [ ] Step 2: <concrete implementation step>
-- [ ] Step 3: <concrete implementation step>
+D-06: "PAUSE — wait for user CONFIRM before saving"
 
-## Acceptance Criteria
+Present:
+```
+Ready to save PLAN.md?
+Type CONFIRM to save, or describe changes needed.
+```
 
-- [ ] <criterion from DISCUSS.md>
-- [ ] <criterion from DISCUSS.md>
+If user types CONFIRM, proceed to Step 7.
+If user requests changes, return to Step 3 with feedback.
 
-## Status
+### Step 7: Save Plan
 
-CONFIRMED
-```
+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
 
-3. Update `.planning/STATE.md`:
-   - Set `plan_confirmed: true`
-   - Set `confirmed_at: <timestamp>`
-   - Set `status: in_progress`
+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
 
 ## Completion
 

package/src/commands/fd-quick.md

@@ -0,0 +1,60 @@
+---
+description: Quick task execution — analyze, implement, review, or investigate a specific piece of work without the full discuss -> plan -> execute workflow
+argument-hint: [task description]
+---
+
+# Quick Task
+
+Execute a focused task without the full workflow. Analyzes the request, selects the best specialist agent, and returns the result directly.
+
+**Input:** $ARGUMENTS — what you need done
+
+## Analysis
+
+Parse `$ARGUMENTS` to determine:
+
+1. **Type of task** — what kind of work is it?
+2. **Scope** — single file, directory, or whole codebase?
+3. **Required capability** — what must the agent be able to do?
+
+## Agent Selection Matrix
+
+| Task Type | Signal Keywords | Agent |
+|-----------|-----------------|-------|
+| Write or edit code | implement, add, create, fix, refactor, update | `@coder` |
+| Explore and understand | trace, map, find, explore, understand, what does | `@code-explorer` |
+| Review code quality | review, check, audit, analyze | `@reviewer` |
+| Security review | security, auth, vulnerability, injection, OWASP | `@security-auditor` |
+| Design or architecture | design, architect, schema, API, structure | `@architect` |
+| Write tests | test, coverage, regression, TDD | `@tester` |
+| Documentation | docs, README, document, write | `@writer` |
+| Research | research, find, look up, how to use, compare | `@researcher` |
+| Debug | debug, trace, root cause, why is, fix error | `@debug-specialist` |
+| Performance | performance, slow, optimize, bottleneck | `@performance-optimizer` |
+| Build error | build error, compile, types, missing import | `@build-error-resolver` |
+| Refactoring | refactor, extract, rename, restructure | `@refactor-guide` |
+| Write/update docs | document, write docs, update README | `@doc-updater` |
+
+**Default:** If unclear or mixed, use `@orchestrator`.
+
+## Execution
+
+1. Select the best agent from the matrix above.
+2. Construct a focused prompt with:
+   - The task from `$ARGUMENTS`
+   - Relevant context (file paths, architecture info, existing code)
+   - Clear success criteria
+3. Execute directly — no intermediate steps.
+
+## Output
+
+Return the agent's output with:
+- Which agent was used
+- The result (be direct, no padding)
+- If the task is partial or incomplete, note what still needs doing
+
+## Guardrails
+
+- **Small tasks only** — if the task would require more than ~15 minutes of work, suggest `/fd-new-feature` instead.
+- **Single scope** — do not attempt multi-file refactors or cross-repo changes via this command.
+- **No workflow overhead** — skip STATE.md updates, phase transitions, and plan markers.

package/src/commands/fd-reflect.md

@@ -1,11 +1,22 @@
 ---
-description: Post-session reflection — analyse artifacts and propose self-improvement actions
+description: Post-session reflection and skill capture — analyse artifacts, propose improvements, capture session patterns
+argument-hint: [--mode=reflect,learn]
 ---
 
-# Reflect: Self-Improvement Analysis
+# Reflect
 
 Analyse session artifacts and propose concrete improvements to FlowDeck's knowledge base.
 
+**Input:** $ARGUMENTS — optional `--mode=reflect` (default) or `--mode=learn`
+
+## Modes
+
+### Reflect (default)
+Post-session self-improvement analysis. See Steps below.
+
+### Learn (`--mode=learn`)
+Capture a repeatable pattern from this session as a reusable FlowDeck skill.
+
 ## Steps
 
 1. Call the `reflect` tool to gather session artifacts and generate the reflection context.
@@ -28,3 +39,31 @@ Analyse session artifacts and propose concrete improvements to FlowDeck's knowle
    - What was captured (new skills created)
    - What requires human review (policy proposals, workflow changes)
    - 3–5 bullet summary of this session's most impactful learnings
+
+## Learn Mode
+
+When `--mode=learn`:
+
+1. **Identify what is worth capturing.** Look for:
+   - A novel problem that required figuring out a non-obvious solution
+   - A pattern that required human guidance or clarification to resolve
+   - A workflow or sequence that would save significant time if remembered
+   - A pitfall that was hit and corrected
+
+   If nothing significant was discovered, reply: "No new patterns to capture from this session." and stop.
+
+2. **Draft the skill.** Structure it as:
+   - `## When to Activate` — concrete triggers (e.g., "when X file pattern exists", "when the user asks about Y")
+   - `## Steps` — ordered, concrete steps to apply the skill
+   - `## Examples` — at least one short, concrete example
+   - `## Pitfalls` — common mistakes to avoid
+
+3. **Choose the skill name.** Use `$ARGUMENTS` if provided as skill name, otherwise derive a kebab-case name from the pattern.
+
+4. **Write the skill** using the `create-skill` tool with:
+   - `name`: kebab-case identifier
+   - `description`: one sentence summarising what the skill does
+   - `content`: the full Markdown body from step 2
+   - `tags`: 2–4 relevant tags
+
+5. **Report** what was captured, why it is useful, and remind the user to restart OpenCode to activate it.