@dv.nghiem/flowdeck 0.1.0

package/src/workflows/refactor-flow.md

@@ -0,0 +1,122 @@
+---
+name: refactor-flow
+description: "Safe refactoring workflow: baseline tests → one transform at a time → verify green → commit. No behavior changes."
+triggers:
+  - /refactor
+steps:
+  - name: baseline
+    agent: "@tester"
+    action: Run test suite and confirm green before any changes
+  - name: identify_targets
+    agent: "@mapper"
+    action: Mapper identifies refactoring candidates (large files, duplication, complexity)
+  - name: plan_transforms
+    agent: "@refactor-guide"
+    action: List specific transforms in low-to-high risk order
+  - name: apply_transform
+    agent: "@coder"
+    action: Coder applies one transform at a time
+  - name: verify
+    agent: "@tester"
+    action: Run test suite after each transform — must stay green
+  - name: commit
+    agent: "@orchestrator"
+    action: Commit each transform separately with descriptive message
+---
+
+# Refactor Flow
+
+## Purpose
+
+Improve code structure without changing behavior. Each step must leave the test suite green.
+
+## Rules
+
+1. Tests must pass **before** you start — if broken, fix tests first
+2. One transform per commit — never combine multiple in one step
+3. No behavior changes — if a test breaks, undo and investigate
+4. No new features during refactoring — separate PRs
+
+## Process
+
+### Step 1: Baseline
+
+```bash
+npm test
+# Must be 100% GREEN before proceeding
+```
+
+If tests fail: fix them first. Do not refactor on a broken baseline.
+
+### Step 2: Identify Refactoring Targets
+
+Spawn `@mapper` to find:
+- Files over 400 lines
+- Functions over 50 lines
+- Duplicated logic (3+ occurrences of same pattern)
+- Deep nesting (> 4 levels)
+- Unclear names
+
+Prioritize: most impactful changes first.
+
+### Step 3: Plan Transforms
+
+List transforms in low-to-high risk order:
+
+**Low risk** (one at a time):
+- Rename variable/function within a file
+- Extract constant from magic number
+- Remove unused imports
+- Reorder parameters (update all call sites)
+
+**Medium risk** (test after each):
+- Extract function from long method
+- Move function to appropriate module
+- Replace duplication with shared utility
+
+**Higher risk** (full test run mandatory):
+- Split large file into modules
+- Change data shape
+- Reorganize module structure
+
+### Step 4: Apply One Transform
+
+Spawn `@coder` to apply exactly ONE transform.
+
+Example commit messages:
+- `refactor: extract validateEmail from UserService`
+- `refactor: rename userId to userID for consistency`
+- `refactor: move auth helpers to auth/utils.ts`
+
+### Step 5: Verify Green
+
+```bash
+npm test
+# Still GREEN? Proceed to next transform.
+# RED? Undo the transform, investigate why.
+```
+
+Never proceed to the next transform with a failing test.
+
+### Step 6: Commit and Repeat
+
+```bash
+git commit -m "refactor: <what changed>"
+# Return to Step 4 for next transform
+```
+
+## Output
+
+After all transforms complete:
+
+```
+## Refactor Complete
+
+Transforms applied: N
+Files changed: N
+Test suite: ✅ N/N passing
+
+Changes:
+- refactor: [description]
+- refactor: [description]
+```

package/src/workflows/review-code-flow.md

@@ -0,0 +1,105 @@
+---
+name: review-code-flow
+description: "Parallel code review workflow: security + quality + convention checks with CRITICAL/HIGH/MEDIUM/LOW severity classification"
+triggers:
+  - /review-code
+steps:
+  - name: identify_scope
+    agent: "@orchestrator"
+    action: Determine files to review (changed files, or explicit scope argument)
+  - name: parallel_review
+    agent: "@parallel-coordinator"
+    action: Spawn @reviewer, @researcher, @tester in parallel
+  - name: security_check
+    agent: "@reviewer"
+    action: Reviewer checks for vulnerabilities (injection, secrets, auth)
+  - name: quality_check
+    agent: "@reviewer"
+    action: Reviewer checks code quality and convention adherence
+  - name: context_check
+    agent: "@researcher"
+    action: Researcher provides best-practice context for flagged areas
+  - name: test_check
+    agent: "@tester"
+    action: Tester verifies test coverage for changed code
+  - name: aggregate
+    agent: "@orchestrator"
+    action: Aggregate findings by severity, present unified report
+---
+
+# Review Code Flow
+
+## Purpose
+
+Run a thorough parallel code review before merging or deploying.
+
+## Process
+
+### Step 1: Identify Scope
+
+If `/review-code [scope]` provided: review files matching scope.
+If no scope: review all files changed since last commit.
+
+```bash
+git diff --name-only HEAD~1
+```
+
+### Step 2: Parallel Review
+
+Spawn three agents simultaneously:
+
+**@reviewer**
+- Security: secrets, injection, auth, XSS
+- Quality: function size, nesting, error handling
+- Conventions: naming, import style, patterns
+
+**@researcher**
+- Look up best practices for flagged patterns
+- Check if flagged patterns are known vulnerabilities
+- Provide context for MEDIUM findings
+
+**@tester**
+- Check coverage for changed files
+- Identify untested paths
+- Run existing tests
+
+### Step 3: Aggregate Results
+
+Merge all findings by severity:
+
+```
+## Code Review: <scope>
+
+### 🔴 CRITICAL (block merge)
+- [finding with file:line and fix]
+
+### 🟠 HIGH (strongly recommend fix)
+- [finding]
+
+### 🟡 MEDIUM (consider fixing)
+- [finding]
+
+### 🟢 LOW (optional)
+- [finding]
+
+### Coverage
+- Changed files: N%
+- Untested paths: [list]
+
+### Verdict: PASS | FAIL | PASS_WITH_NOTES
+```
+
+### Step 4: Decision
+
+- **CRITICAL found** → Block. Fix before merge.
+- **HIGH found** → Strongly recommend fix. Document if proceeding anyway.
+- **MEDIUM/LOW** → Document. Proceed.
+- **PASS** → Ready to merge.
+
+## Agent configuration
+
+| Agent | Model | Purpose |
+|-------|-------|---------|
+| @reviewer | google/gemini-2.5-flash | Security and quality |
+| @researcher | anthropic/claude-sonnet-4-5 | Context and best practices |
+| @tester | anthropic/claude-sonnet-4-5 | Coverage analysis |

package/src/workflows/spec-driven-flow.md

@@ -0,0 +1,43 @@
+# Spec-Driven Development (SDD) Workflow
+
+This workflow enforces a strict separation between planning and execution.
+
+## Phases
+
+### 1. Discuss (Gated)
+- Goal: Capture all requirements and architectural decisions.
+- Tool: `/discuss`
+- Restriction: **Write access to codebase is BLOCKED.**
+
+### 2. Plan (Gated)
+- Goal: Create a detailed implementation plan and acceptance criteria.
+- Tool: `/fd-plan`
+- Review: `/fd-plan --confirm` (User must approve)
+- Restriction: **Write access to codebase is BLOCKED.**
+
+### 3. Execute
+- Goal: Implement the plan.
+- Tool: `/fd-execute` (Orchestrator takes over)
+- Restriction: Write access is ENABLED.
+
+### 4. Review
+- Goal: Verify implementation against acceptance criteria.
+- Tool: `/review-code`
+
+---
+Strict enforcement ensures that AI agents don't start coding until the design is solid.
+
+## Best Practices
+
+### 1. Leverage the Council
+For complex architectural decisions in the **Discuss** phase, use `/fd-council`. This runs multiple "hero" agents (Architect, Oracle, Reviewer) and provides a synthesized consensus.
+- *Example*: `/fd-council "Should we use a relational or NoSQL database for the audit log?"`
+
+### 2. Verify with Hash-Edits
+When implementation starts in the **Execute** phase, ensure agents use `fd-hash-edit` for critical files. This prevents stale-line errors if multiple agents are working in the same area.
+
+### 3. Maintain Context
+Run `context-generator` at the start of each new phase to ensure `AGENTS.md` reflects the current roadmap and decisions. This helps sub-agents stay grounded.
+
+### 4. Health Check
+Run `/fd-doctor` before starting a major execution wave to ensure your environment and configuration are correctly set up.

package/src/workflows/write-docs-flow.md

@@ -0,0 +1,95 @@
+---
+name: write-docs-flow
+description: "Documentation workflow: explore public APIs → draft docs → review for accuracy → finalize"
+triggers:
+  - /write-docs
+steps:
+  - name: explore_apis
+    agent: "@code-explorer"
+    action: Mapper explores public APIs, exports, and interfaces in the codebase
+  - name: draft
+    agent: "@writer"
+    action: Writer drafts documentation covering API reference, examples, and usage
+  - name: review
+    agent: "@reviewer"
+    action: Reviewer checks accuracy against actual code behavior
+  - name: revise
+    agent: "@writer"
+    action: Writer incorporates review feedback
+  - name: finalize
+    agent: "@doc-updater"
+    action: Write final docs to appropriate location
+---
+
+# Write Docs Flow
+
+## Purpose
+
+Generate accurate, up-to-date documentation from the codebase.
+
+## Process
+
+### Step 1: Explore APIs
+
+Spawn `@mapper` to:
+- Find all exported functions, classes, and types
+- Identify public API entry points
+- Map key workflows and integration points
+
+```bash
+# Find exports
+grep -rn "export " src/ --include="*.ts"
+# Find public interfaces
+grep -rn "export interface\|export type\|export class" src/ --include="*.ts"
+```
+
+### Step 2: Draft Documentation
+
+Spawn `@writer` to produce:
+
+**API Reference**
+```markdown
+## functionName(param: Type): ReturnType
+
+Description of what the function does.
+
+**Parameters:**
+- `param` (Type) — description
+
+**Returns:** description
+
+**Example:**
+\`\`\`typescript
+const result = functionName(value);
+\`\`\`
+```
+
+**Usage Guide**
+- Step-by-step workflow with examples
+- Common patterns and best practices
+- Configuration options
+
+**Troubleshooting**
+- Common errors and their solutions
+
+### Step 3: Review for Accuracy
+
+Spawn `@reviewer` to verify:
+- Every documented function/method actually exists
+- Parameter types match the actual signatures
+- Examples are syntactically correct
+- No outdated API references
+
+### Step 4: Finalize
+
+Writer incorporates feedback and writes final docs to:
+- `README.md` — project overview and quick start
+- `docs/API.md` — complete API reference
+- `docs/USER_GUIDE.md` — detailed usage guide
+
+## Output
+
+Updated documentation files with:
+- Accurate function signatures
+- Working code examples
+- Clear explanations of behavior