@dv.nghiem/flowdeck 0.1.0 → 0.1.2

package/src/commands/fd-review-route.md

@@ -0,0 +1,54 @@
+---
+description: Human Review Routing — route risky patches to the right reviewer type based on change nature and risk score
+argument-hint: [change description or PR number]
+---
+
+# Review Route
+
+Determine the right reviewer type for a proposed change based on its nature and risk.
+
+**Input:** $ARGUMENTS — change description or PR number/URL
+
+## Steps
+
+1. Analyze the change described in `$ARGUMENTS`:
+   - Read affected files and their categories
+   - Check `.codebase/VOLATILITY.json` for risk scores if available
+   - Check `.codebase/FAILURES.json` for prior failures in this area
+
+2. Classify change by domain:
+
+| Domain Signals | Reviewer Type |
+|---------------|---------------|
+| Auth, tokens, sessions, permissions | **Security reviewer** |
+| DB migrations, schema, models | **Backend/DB reviewer** |
+| Infrastructure, CI/CD, containers | **Infra reviewer** |
+| Public APIs, SDK changes | **API owner** |
+| High-churn or volatile file (score >0.7) | **Domain owner** |
+| New external dependency | **Security + Arch reviewer** |
+| Low risk, no sensitive paths | **Any peer reviewer** |
+
+## Report
+
+```
+════════════════════════════════════════════
+REVIEW ROUTING
+════════════════════════════════════════════
+Change: <summary>
+Risk score: <0-10>
+
+Recommended Reviewers:
+
+  PRIMARY:   <reviewer type> — <reason>
+  SECONDARY: <reviewer type> — <reason>
+
+Why:
+  - <specific signal that triggered routing>
+  - <prior failures in this area if any>
+
+SLA:
+  - <high risk: same-day | medium: 24h | low: 48h>
+════════════════════════════════════════════
+```
+
+If risk score < 3: "Low risk — any peer reviewer is sufficient."

package/src/commands/fd-roadmap.md

@@ -0,0 +1,46 @@
+---
+description: View or update project roadmap — displays ROADMAP.md, shows phase statuses, add new phase, or mark phase complete
+argument-hint: [--add "Phase Name" | --complete N | --list]
+---
+
+# Roadmap
+
+View or update the project roadmap.
+
+**Input:** $ARGUMENTS
+
+## Behavior
+
+### View Roadmap (no args or `--list`)
+
+1. Read `.planning/ROADMAP.md` — if not found, error: "Run /fd-new-project first."
+2. Read `.planning/STATE.md` for current phase and completed phases.
+3. Display the roadmap with status indicators:
+
+```
+═══════════════════════════════════════
+PROJECT ROADMAP
+═══════════════════════════════════════
+  ✅ Phase 1: <name> — completed
+  🔄 Phase 2: <name> — in progress  ← current
+  ⏳ Phase 3: <name> — planned
+═══════════════════════════════════════
+Current: Phase 2 | Status: in_progress
+```
+
+### Add Phase (`--add "Phase Name"`)
+
+Append a new phase row to the `ROADMAP.md` overview table with status `planned`.
+
+Update STATE.md `total_phases` counter.
+
+Report: "Phase <N> '<name>' added."
+
+### Mark Complete (`--complete N`)
+
+1. Update ROADMAP.md to mark phase N as completed.
+2. Update STATE.md:
+   - Increment `completed_phases`
+   - Advance `phase` to N+1 if N is current phase
+   - Set new phase `status: planned`
+3. Report: "Phase N marked complete. Now on phase N+1."

package/src/commands/fd-settings.md

@@ -0,0 +1,57 @@
+---
+description: View or update FlowDeck settings — agent models, quality profiles, and workflow toggles
+argument-hint: [key=value | --list]
+---
+
+# Settings
+
+View or update FlowDeck configuration.
+
+**Input:** $ARGUMENTS
+
+## Behavior
+
+### List Settings (`--list` or no arguments)
+
+Read `.planning/config.json` (create with defaults if missing) and display current settings:
+
+| Setting | Value | Description |
+|---------|-------|-------------|
+| `model_profile` | balanced | Agent quality profile (quality/balanced/economy) |
+| `tdd_enforced` | true | Require TDD red-green-refactor cycle |
+| `approval_required` | false | Require human approval for risky changes |
+| `volatility_threshold` | 0.7 | Risk score that triggers approval gate |
+| `default_agent` | orchestrator | Default agent for commands |
+
+### Set a Value (`key=value`)
+
+Parse `$ARGUMENTS` as `key=value` pairs (space-separated for multiple).
+
+Valid keys:
+- `model_profile` — `quality`, `balanced`, `economy`
+- `tdd_enforced` — `true`, `false`
+- `approval_required` — `true`, `false`  
+- `volatility_threshold` — number between 0.0 and 1.0
+- `default_agent` — agent name string
+
+Update `.planning/config.json` with the new values.
+
+Report what was changed.
+
+### Invalid Key
+
+Report error with list of valid keys.
+
+## Default Config
+
+If `.planning/config.json` does not exist, create it with defaults:
+
+```json
+{
+  "model_profile": "balanced",
+  "tdd_enforced": true,
+  "approval_required": false,
+  "volatility_threshold": 0.7,
+  "default_agent": "orchestrator"
+}
+```

package/src/commands/fd-test-gap.md

@@ -0,0 +1,54 @@
+---
+description: Test Gap Detector — identify areas of a proposed change weakly covered by tests and suggest minimum high-value tests to add
+argument-hint: [change description or file paths]
+---
+
+# Test Gap
+
+Identify test gaps in a proposed change and recommend the minimum high-value tests to add.
+
+**Input:** $ARGUMENTS — description of the change or specific file paths
+
+## Steps
+
+Run two agents in parallel:
+
+- **@tester**: Find source files mentioned in `$ARGUMENTS` that have no corresponding test file; identify branches/edge cases in changed functions with no test coverage; look for missing error-path tests
+
+- **@researcher**: Check if the changed functions appear in any integration or end-to-end test; find prior test gaps in this area from git history (tests added reactively after bugs)
+
+## Gap Scoring
+
+For each identified gap:
+- **CRITICAL**: public API with no test at all
+- **HIGH**: error handling path with no test
+- **MEDIUM**: business logic branch not covered
+- **LOW**: edge case (empty input, max values) not tested
+
+## Report
+
+```
+════════════════════════════════════════════
+TEST GAP REPORT
+════════════════════════════════════════════
+Change: <summary>
+
+Gaps Found (<N>):
+
+  CRITICAL: <file> — no test file exists
+    Suggest: <test file path> testing <what>
+
+  HIGH: <function> in <file> — error path not tested
+    Suggest: test case for <error condition>
+
+  MEDIUM: <function> — branch "<condition>" not covered
+    Suggest: test case where <condition is true>
+
+────────────────────────────────────────────
+Minimum Tests to Add (prioritized):
+  1. <test description> — covers CRITICAL gap
+  2. <test description> — covers HIGH gap
+════════════════════════════════════════════
+```
+
+Ask: "Should I write these tests now?"

package/src/commands/fd-translate-intent.md

@@ -0,0 +1,56 @@
+---
+description: Intent-to-Change Translator — convert vague requests into 3–5 concrete, ranked implementation options with tradeoffs
+argument-hint: [vague intent, e.g. "make checkout faster"]
+---
+
+# Translate Intent
+
+Convert a vague request into concrete, ranked implementation options.
+
+**Input:** $ARGUMENTS — a vague or high-level request (e.g., "make checkout faster", "improve auth security")
+
+## Steps
+
+Run two agents in parallel:
+
+- **@architect**: Decompose `$ARGUMENTS` into 3–5 concrete implementation options. For each option provide:
+  - **Name**: short label
+  - **Description**: what exactly would be changed
+  - **Files affected**: list of files/modules that would change
+  - **Effort**: S (hours) / M (days) / L (week+)
+  - **Risk**: low / medium / high
+  - **Tradeoffs**: pros and cons
+
+- **@researcher**: For each option, fetch relevant codebase context — find existing patterns, prior art, and constraints that apply
+
+## Report
+
+```
+════════════════════════════════════════════
+INTENT TRANSLATION: "$ARGUMENTS"
+════════════════════════════════════════════
+
+Option 1 (Recommended): <name>
+  Description: <what changes>
+  Files: <list>
+  Effort: <S|M|L> | Risk: <low|med|high>
+  Pros: <pros>
+  Cons: <cons>
+
+Option 2: <name>
+  ...
+
+Option 3: <name>
+  ...
+
+────────────────────────────────────────────
+Clarifying Questions:
+  1. <question about unclear aspect>
+  2. <question>
+
+Assumptions Made:
+  - <assumption>
+════════════════════════════════════════════
+```
+
+Present all options and ask: "Which option would you like to proceed with?"

package/src/commands/fd-volatility-map.md

@@ -0,0 +1,64 @@
+---
+description: Codebase Volatility Map — highlight unstable zones based on git churn, hotfix frequency, and TODO clusters. Updates .codebase/VOLATILITY.json
+---
+
+# Volatility Map
+
+Generate a volatility map of the codebase to identify unstable, high-churn areas.
+
+## Steps
+
+Run three analyses in parallel:
+
+### 1. Git Churn (@researcher)
+```bash
+git log --follow --format="%ad" --date=short -- <file> | wc -l
+```
+Run for all source files (last 90 days). Identify files with the most commits.
+
+### 2. TODO/FIXME Scan (@researcher)
+Scan all source files for `TODO`, `FIXME`, `HACK`, `XXX` comments. Count per file.
+
+### 3. Hotfix Frequency (@researcher)
+Search git log for commit messages containing `fix`, `hotfix`, `patch`, `urgent`, `bug` (last 90 days). Count per file touched.
+
+## Scoring
+
+For each file, compute a volatility score (0.0–1.0):
+- `churn_score` = commits / max_commits (normalized)
+- `todo_score` = todo_count / max_todos (normalized)
+- `hotfix_score` = hotfix_commits / max_hotfixes (normalized)
+- `volatility = (churn * 0.4) + (hotfix * 0.4) + (todo * 0.2)`
+
+## Output
+
+Write results to `.codebase/VOLATILITY.json`:
+```json
+{
+  "generated_at": "<timestamp>",
+  "hotspots": [
+    { "path": "<file>", "score": 0.92, "commits": 47, "todos": 8, "hotfixes": 12 }
+  ],
+  "stable_zones": [
+    { "path": "<file>", "score": 0.05 }
+  ]
+}
+```
+
+## Report
+
+```
+════════════════════════════════
+VOLATILITY MAP
+════════════════════════════════
+Top Hotspots:
+  🔴 <file> — score: 0.92 (47 commits, 12 hotfixes)
+  🟠 <file> — score: 0.71 (23 commits, 5 hotfixes)
+  🟡 <file> — score: 0.45 (15 commits, 8 TODOs)
+
+Stable Zones:
+  🟢 <file> — score: 0.05
+
+Saved: .codebase/VOLATILITY.json
+════════════════════════════════
+```

package/src/commands/fd-workspace-status.md

@@ -0,0 +1,34 @@
+---
+description: Display workspace overview — all repos, their current phase, status, and progress
+---
+
+# Workspace Status
+
+Display an overview of all repositories registered in the workspace.
+
+## Steps
+
+1. Read `.planning/config.json` for the list of registered repos.
+   - If no repos registered, show status for the current directory only.
+
+2. For each repo, read its `.planning/STATE.md`:
+   - Current phase, status, last_updated
+   - Plan confirmed flag
+
+3. Display workspace overview:
+
+```
+════════════════════════════════════════════════════
+WORKSPACE OVERVIEW
+════════════════════════════════════════════════════
+  frontend   — Phase 2 | in_progress  | Plan: ✅ | Updated: <time>
+  backend    — Phase 3 | completed    | Plan: ✅ | Updated: <time>
+  shared     — Phase 1 | planned      | Plan: ❌ | Updated: <time>
+────────────────────────────────────────────────────
+Total: 3 repos | 1 in progress | 1 completed | 1 planned
+════════════════════════════════════════════════════
+```
+
+4. Highlight any repos with:
+   - `status: blocked` → show with ⚠️
+   - `plan_confirmed: false` + `status: in_progress` → note: "plan not confirmed"

package/src/commands/fd-write-docs.md

@@ -0,0 +1,50 @@
+---
+description: Explore public APIs — writer drafts documentation — reviewer accuracy check — writer finalizes
+argument-hint: [--scope=path | --format=api,guide,readme]
+---
+
+# Write Docs
+
+Generate documentation for the codebase or a specific scope.
+
+**Input:** $ARGUMENTS — optional `--scope=<path>` and `--format=<type>`
+
+Supported formats: `api` (API reference), `guide` (usage guide), `readme` (README)  
+Default: all formats
+
+## Pipeline
+
+### Phase 1 — Explore
+
+- **@researcher**: Find all public APIs, exported functions, classes, types, and their signatures
+- **@code-explorer**: Identify existing documentation, JSDoc comments, README sections
+
+### Phase 2 — Draft
+
+- **@writer**: Draft documentation based on the exploration findings
+  - API docs: function signatures, parameters, return types, examples
+  - Guides: usage examples, step-by-step instructions
+  - README: project overview, install, quickstart, API summary
+
+### Phase 3 — Review
+
+- **@reviewer**: Check accuracy — verify all documented APIs exist and signatures are correct
+  - Flag any documentation that contradicts the implementation
+  - Flag missing documentation for public APIs
+
+### Phase 4 — Finalize
+
+- **@writer**: Apply reviewer corrections, finalize and write documentation files
+
+## Output Files
+
+Based on `--format`:
+- `api` → writes or updates `docs/API.md`
+- `guide` → writes or updates `docs/GUIDE.md`
+- `readme` → updates `README.md`
+
+If `--scope` is set, documentation applies only to files within that path.
+
+## Completion
+
+Report: files written/updated, public APIs documented, any gaps found.

package/dist/commands/analysis/analysis.test.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=analysis.test.d.ts.map

package/dist/commands/analysis/analysis.test.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"analysis.test.d.ts","sourceRoot":"","sources":["../../../src/commands/analysis/analysis.test.ts"],"names":[],"mappings":""}

package/dist/commands/analysis/analyze-change.d.ts

@@ -1,148 +0,0 @@
-/**
- * /fd-analyze-change — umbrella analysis command
- *
- * Combines: impact radar, blast radius, regression prediction,
- * test gap detection, volatility map, and reviewer routing into a
- * single consolidated pre-change report.
- *
- * Replaces individual: /fd-impact-radar, /fd-blast-radius,
- * /fd-regression-predict, /fd-test-gap, /fd-volatility-map, /fd-review-route
- */
-export interface AnalyzeChangeArgs {
-    change?: string;
-    scope?: string;
-    files?: string;
-    depth?: string;
-    impact?: boolean;
-    "blast-radius"?: boolean;
-    regression?: boolean;
-    "test-gap"?: boolean;
-    volatility?: boolean;
-    "review-route"?: boolean;
-    all?: boolean;
-    json?: boolean;
-}
-export declare const analyzeChangeCommand: {
-    name: string;
-    description: string;
-    execute(context: any, args?: AnalyzeChangeArgs): Promise<{
-        error: string;
-        code: string;
-        success?: undefined;
-        data?: undefined;
-        meta?: undefined;
-        message?: undefined;
-        modules_run?: undefined;
-        affected_zones?: undefined;
-        recommended_reviewers?: undefined;
-        risk_summary?: undefined;
-        risk_score?: undefined;
-        config?: undefined;
-        phase?: undefined;
-    } | {
-        success: boolean;
-        data: {
-            modules_run: string[];
-            affected_zones: string[];
-            regression_categories: string[];
-            test_gap_types: string[];
-            recommended_reviewers: string[];
-            risk_summary: string;
-            risk_score: number;
-            config: {
-                change_description: string;
-                scope: string;
-                files: string[];
-                modules_run: string[];
-                agents: (false | {
-                    name: string;
-                    role: string;
-                })[];
-                data: {
-                    hotspots: string[];
-                    known_failures: string[];
-                    related_modules: string[];
-                    volatile_zones: {
-                        path: string;
-                        stability: string;
-                    }[];
-                    fragile_patterns: number;
-                    repo_memory_nodes: number;
-                    regression_categories: string[];
-                    past_regression_signals: string[];
-                    test_gap_types: string[];
-                    recommended_reviewers: string[];
-                    trust_score: number | null;
-                    trust_verdict: string;
-                    prior_failures: string[];
-                };
-                risk_score: number;
-                risk_summary: string;
-                traversal_depth: number;
-            };
-            phase: number;
-        };
-        meta: {
-            formatted: string;
-            timestamp: string;
-        };
-        error?: undefined;
-        code?: undefined;
-        message?: undefined;
-        modules_run?: undefined;
-        affected_zones?: undefined;
-        recommended_reviewers?: undefined;
-        risk_summary?: undefined;
-        risk_score?: undefined;
-        config?: undefined;
-        phase?: undefined;
-    } | {
-        success: boolean;
-        message: string;
-        modules_run: string[];
-        affected_zones: string[];
-        recommended_reviewers: string[];
-        risk_summary: string;
-        risk_score: number;
-        config: {
-            change_description: string;
-            scope: string;
-            files: string[];
-            modules_run: string[];
-            agents: (false | {
-                name: string;
-                role: string;
-            })[];
-            data: {
-                hotspots: string[];
-                known_failures: string[];
-                related_modules: string[];
-                volatile_zones: {
-                    path: string;
-                    stability: string;
-                }[];
-                fragile_patterns: number;
-                repo_memory_nodes: number;
-                regression_categories: string[];
-                past_regression_signals: string[];
-                test_gap_types: string[];
-                recommended_reviewers: string[];
-                trust_score: number | null;
-                trust_verdict: string;
-                prior_failures: string[];
-            };
-            risk_score: number;
-            risk_summary: string;
-            traversal_depth: number;
-        };
-        phase: number;
-        meta: {
-            formatted: string;
-            timestamp: string;
-        };
-        error?: undefined;
-        code?: undefined;
-        data?: undefined;
-    }>;
-};
-//# sourceMappingURL=analyze-change.d.ts.map

package/dist/commands/analysis/analyze-change.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"analyze-change.d.ts","sourceRoot":"","sources":["../../../src/commands/analysis/analyze-change.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAmCH,MAAM,WAAW,iBAAiB;IAChC,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB,GAAG,CAAC,EAAE,OAAO,CAAA;IACb,IAAI,CAAC,EAAE,OAAO,CAAA;CACf;AAED,eAAO,MAAM,oBAAoB;;;qBAGR,GAAG,SAAS,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;8BAoFjB,MAAM;mCAAa,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;0BAAzB,MAAM;+BAAa,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;CAwI7D,CAAA"}

package/dist/commands/analysis/evaluate-risk.d.ts

@@ -1,77 +0,0 @@
-/**
- * /fd-evaluate-risk — standalone risk assessment command
- *
- * Estimates change risk, confidence, likely regressions, whether
- * approval is needed, and suggests safer alternatives when risk is high.
- *
- * Works without a --file if --change is provided (keyword-based analysis).
- */
-type RiskLevel = "low" | "medium" | "high" | "critical";
-export declare const evaluateRiskCommand: {
-    name: string;
-    description: string;
-    execute(context: any, args?: {
-        change?: string;
-        file?: string;
-        volatility?: boolean;
-        confidence?: boolean;
-        "risk-score"?: boolean;
-        json?: boolean;
-    }): Promise<{
-        error: string;
-        code: string;
-        success?: undefined;
-        data?: undefined;
-        meta?: undefined;
-    } | {
-        success: boolean;
-        data: {
-            agents: ({
-                name: string;
-                role: string;
-            } | null)[];
-            phase: number;
-            risk_score: number;
-            risk_level: RiskLevel;
-            confidence: number;
-            approval_needed: boolean;
-            likely_regressions: string[];
-            volatile_zones: number;
-            volatile_matches: string[];
-            safer_alternative: string | null;
-            trust_signals: string[];
-        };
-        meta: {
-            formatted: string;
-            timestamp: string;
-        };
-        error?: undefined;
-        code?: undefined;
-    } | {
-        agents: ({
-            name: string;
-            role: string;
-        } | null)[];
-        phase: number;
-        meta: {
-            formatted: string;
-            timestamp: string;
-        };
-        risk_score: number;
-        risk_level: RiskLevel;
-        confidence: number;
-        approval_needed: boolean;
-        likely_regressions: string[];
-        volatile_zones: number;
-        volatile_matches: string[];
-        safer_alternative: string | null;
-        trust_signals: string[];
-        success: boolean;
-        message: string;
-        error?: undefined;
-        code?: undefined;
-        data?: undefined;
-    }>;
-};
-export {};
-//# sourceMappingURL=evaluate-risk.d.ts.map

package/dist/commands/analysis/evaluate-risk.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"evaluate-risk.d.ts","sourceRoot":"","sources":["../../../src/commands/analysis/evaluate-risk.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAiCH,KAAK,SAAS,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,UAAU,CAAA;AAuDvD,eAAO,MAAM,mBAAmB;;;qBAGP,GAAG,SAAS;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,OAAO,CAAC;QAAC,UAAU,CAAC,EAAE,OAAO,CAAC;QAAC,YAAY,CAAC,EAAE,OAAO,CAAC;QAAC,IAAI,CAAC,EAAE,OAAO,CAAA;KAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2I1J,CAAA"}