@dv.nghiem/flowdeck 0.1.0 → 0.1.2

package/src/commands/fd-guarded-edit.md

@@ -0,0 +1,69 @@
+---
+description: Edit gate — decides auto-approve / require-confirmation / require-review / block based on policy, trust score, volatility, and arch constraints
+argument-hint: [change description or file path]
+---
+
+# Guarded Edit
+
+Evaluate a proposed edit against all safety gates before allowing it to proceed.
+
+**Input:** $ARGUMENTS — description or file path of the proposed edit
+
+## Gates (evaluated in order)
+
+### Gate 1 — Policy Check
+
+Read `.planning/config.json` for active policies:
+- `approval_required`: if true, all edits need explicit approval
+- `volatility_threshold`: edits touching files above this score need confirmation
+
+### Gate 2 — Volatility Check
+
+Check `.codebase/VOLATILITY.json` for the files in `$ARGUMENTS`.
+- Score ≥ 0.8 → REQUIRE REVIEW
+- Score ≥ 0.6 → REQUIRE CONFIRMATION
+- Score < 0.6 → proceed
+
+### Gate 3 — Architecture Constraints
+
+Read `.codebase/ARCHITECTURE.md` and check if the edit:
+- Crosses defined service boundaries
+- Modifies public API contracts
+- Touches security-critical paths (auth, payments, PII)
+
+### Gate 4 — Trust Score
+
+Check `.codebase/FAILURES.json` for prior failures in the same path.
+- 3+ prior failures in this area → REQUIRE REVIEW
+- 1-2 prior failures → REQUIRE CONFIRMATION
+
+## Decision Matrix
+
+| Condition | Decision |
+|-----------|----------|
+| Any BLOCK signal | ❌ BLOCK |
+| REQUIRE REVIEW signal | 👁️ REQUIRE REVIEW |
+| REQUIRE CONFIRMATION signal | ⚠️ REQUIRE CONFIRMATION |
+| All gates pass | ✅ AUTO-APPROVE |
+
+## Report
+
+```
+════════════════════════════════════
+GUARDED EDIT GATE
+════════════════════════════════════
+Edit: <summary>
+
+Gate 1 — Policy:      <pass|flag>
+Gate 2 — Volatility:  <score> → <pass|confirm|review>
+Gate 3 — Arch:        <pass|flag>
+Gate 4 — Trust:       <failures count> → <pass|confirm|review>
+
+DECISION: AUTO-APPROVE / CONFIRM / REVIEW / BLOCK
+
+<if BLOCK or REVIEW: explain what needs to happen first>
+════════════════════════════════════
+```
+
+If BLOCK: do not proceed with the edit. Explain what must change first.
+If CONFIRM: present to user and wait for explicit "yes" before proceeding.

package/src/commands/fd-impact-radar.md

@@ -0,0 +1,51 @@
+---
+description: Change Impact Radar — predict which files, modules, APIs, tests, and DB paths are affected before editing anything
+argument-hint: [change description]
+---
+
+# Impact Radar
+
+Predict the blast area of a proposed change before any code is written.
+
+**Input:** $ARGUMENTS — description of the proposed change
+
+## Steps
+
+Run three agents in parallel:
+
+- **@researcher**: Trace dependency graph from the paths mentioned in `$ARGUMENTS`; find all files that import or are imported by those modules; map 2 levels deep
+
+- **@architect**: Identify API contracts and service boundaries at risk; flag any public interfaces that would change; check for DB schema impacts
+
+- **@tester**: Find test files that cover the affected paths; identify which tests would need updating; spot gaps (changed files with no tests)
+
+## Report
+
+```
+════════════════════════════════════════════
+CHANGE IMPACT RADAR
+════════════════════════════════════════════
+Change: <summary of $ARGUMENTS>
+Risk score: <low|medium|high>
+
+Affected Files (<N>):
+  - <file> (<reason>)
+
+API Contracts at Risk:
+  - <interface/endpoint> — <risk>
+
+Tests to Update (<N>):
+  - <test file>
+
+Test Gaps (<N> files with no tests):
+  - <file>
+
+DB / Schema Impact:
+  - <none | description>
+
+Recommendation:
+  <proceed with caution | review required | block>
+════════════════════════════════════════════
+```
+
+If no impact found: "No significant impact detected. Proceed with standard review."

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

@@ -0,0 +1,36 @@
+---
+description: Analyze codebase and generate .codebase/ documentation — STACK, ARCHITECTURE, STRUCTURE, CONVENTIONS, TESTING, CONCERNS
+argument-hint: [--incremental]
+---
+
+# Map Codebase
+
+Analyze the current codebase and generate comprehensive documentation under `.codebase/`.
+
+**Input:** $ARGUMENTS (pass `--incremental` to only process changed files)
+
+## Steps
+
+1. Create `.codebase/` directory if it does not exist.
+
+2. Run parallel analysis — delegate to specialist agents:
+   - **@researcher**: Scan package files (`package.json`, `go.mod`, `pyproject.toml`, `Cargo.toml`, etc.) to identify tech stack, frameworks, and dependencies
+   - **@architect**: Analyze directory structure, module boundaries, key entry points, and architectural patterns
+   - **@code-explorer**: Scan source files for naming conventions, code style patterns, import conventions, and anti-patterns
+   - **@tester**: Find test files, identify testing frameworks, coverage configuration, and testing patterns
+   - **@researcher** (second pass): Scan for TODO/FIXME/HACK comments, large files (>500 lines), duplicated code patterns, and security concerns
+
+3. Write the following files based on analysis results:
+
+   - **`.codebase/STACK.md`** — tech stack, frameworks, key dependencies with versions
+   - **`.codebase/ARCHITECTURE.md`** — system design, module boundaries, key flows, data models
+   - **`.codebase/STRUCTURE.md`** — directory layout with explanations of each major directory
+   - **`.codebase/CONVENTIONS.md`** — naming rules, code style, import conventions, patterns to follow
+   - **`.codebase/TESTING.md`** — test frameworks, test patterns, how to run tests, coverage targets
+   - **`.codebase/CONCERNS.md`** — technical debt, risky areas, TODO clusters, large files, security flags
+
+4. If `--incremental`: only update files where the underlying source has changed since the last map (check `.codebase/last_mapped` timestamp).
+
+5. Write timestamp to `.codebase/last_mapped`.
+
+6. Report summary: files created/updated, key findings per category.

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

@@ -0,0 +1,63 @@
+---
+description: Manage multi-repo registry in .planning/config.json — add, list, status, or remove repos
+argument-hint: [list | add <path> [name] | remove <name> | status]
+---
+
+# Multi-Repo
+
+Manage a multi-repository workspace registry.
+
+**Input:** $ARGUMENTS
+
+## Behavior
+
+### List (`list` or no arguments)
+
+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)
+════════════════════════════════════
+```
+
+### Add (`add <path> [name]`)
+
+1. Verify `<path>` exists and has a `.planning/STATE.md`
+2. Derive `name` from directory basename if not provided
+3. Add to `.planning/config.json` → `repos` array
+4. Report: "Added '<name>' at <path>."
+
+### Remove (`remove <name>`)
+
+Remove matching repo from registry. Report: "Removed '<name>'."
+
+### Status (`status`)
+
+For each registered repo, read its STATE.md and display:
+
+```
+════════════════════════════════════
+WORKSPACE STATUS
+════════════════════════════════════
+  frontend  — Phase 2 | in_progress | Updated: <time>
+  backend   — Phase 3 | completed   | Updated: <time>
+  shared    — Phase 1 | planned     | Updated: <time>
+════════════════════════════════════
+Overall: 1 in progress, 1 complete, 1 planned
+```
+
+## Config Format
+
+`.planning/config.json` repos entry:
+```json
+{
+  "repos": [
+    { "name": "frontend", "path": "./packages/frontend" }
+  ]
+}
+```

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

@@ -0,0 +1,49 @@
+---
+description: Execute feature implementation — guard check, parallel coder + researcher, reviewer, tester, STATE.md update
+argument-hint: [feature description]
+---
+
+# New Feature
+
+Implement a new feature using the full FlowDeck agent pipeline.
+
+**Input:** $ARGUMENTS — description of the feature to implement
+
+## Pre-flight
+
+1. Check `.planning/STATE.md` 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
+
+Run the following agent pipeline for feature: **$ARGUMENTS**
+
+### 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
+
+### 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)
+
+### Phase 3 — Validation (parallel)
+- **@tester**: Run test suite, verify new tests pass, check coverage
+- **@reviewer**: Review implementation for quality, security, and convention compliance
+
+### Phase 4 — State Update
+- Update `.planning/STATE.md` with completed steps
+- Write summary to `.planning/phases/phase-<N>/RESULT.md`
+
+## Guard Rails
+
+- 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
+
+## Completion
+
+Report: feature implemented, tests status, reviewer findings, files changed.

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

@@ -0,0 +1,103 @@
+---
+description: Initialize .planning/ structure for a new project — creates PROJECT.md, REQUIREMENTS.md, ROADMAP.md, and STATE.md
+argument-hint: [project-name]
+---
+
+# New Project
+
+Initialize FlowDeck planning structure for the current workspace.
+
+## Steps
+
+1. Check if `.planning/` already exists — if it does, warn the user and ask before overwriting.
+
+2. Create the `.planning/` directory and the following files if they do not exist:
+
+**`.planning/PROJECT.md`**
+```markdown
+# Project
+
+**Name:** $ARGUMENTS
+**Description:** (set via /fd-discuss)
+**Tech stack:** (set via /fd-discuss)
+
+---
+
+## Goals
+
+-
+
+## Non-negotiables
+
+-
+
+## Out of Scope
+
+-
+```
+
+**`.planning/REQUIREMENTS.md`**
+```markdown
+# Requirements
+
+**Project:** $ARGUMENTS
+**Version:** 1.0
+
+---
+
+## v1 Requirements
+
+```
+
+**`.planning/ROADMAP.md`**
+```markdown
+# Roadmap
+
+**Project:** $ARGUMENTS
+**Version:** 1.0
+
+---
+
+## Overview
+
+| Phase | Name | Purpose |
+|-------|------|---------|
+| 1 | Setup | |
+
+---
+```
+
+**`.planning/STATE.md`**
+```markdown
+---
+flowdeck_state_version: 1.0
+milestone: v1.0
+last_updated: "<current timestamp>"
+progress:
+  total_phases: 1
+  completed_phases: 0
+---
+
+# State
+
+**Project:** $ARGUMENTS
+**Last updated:** <current timestamp>
+
+## Current Phase
+
+phase: 1
+status: planned
+plan_file: none
+plan_confirmed: false
+confirmed_at: none
+
+## Progress
+
+- [ ] Phase 1: Setup
+```
+
+3. Also create `.planning/phases/phase-1/` directory.
+
+4. 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

package/src/commands/fd-plan.md

@@ -0,0 +1,80 @@
+---
+description: Create detailed implementation plan from DISCUSS.md decisions — save PLAN.md, update STATE.md, require CONFIRM before execution
+argument-hint: [--phase=N] [--yes]
+---
+
+# Plan
+
+Create a detailed implementation plan from confirmed discussion decisions.
+
+**Input:** $ARGUMENTS (optional `--phase=N` to target a specific phase, `--yes` to skip confirmation)
+
+## Pre-flight
+
+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."
+
+## Confirmation Gate
+
+Unless `--yes` is passed or STATE.md already has `plan_confirmed: true`:
+
+Show a preview of the DISCUSS.md decisions found and ask:
+
+```
+═══════════════════════════════════════════
+PLAN PHASE <N> — AWAITING CONFIRMATION
+═══════════════════════════════════════════
+
+Found <X> decisions in DISCUSS.md:
+<preview of D-XX lines>
+
+Type CONFIRM to save PLAN.md and enable execution.
+═══════════════════════════════════════════
+```
+
+**PAUSE** — wait for user to type CONFIRM before proceeding.
+
+## Plan Generation
+
+After confirmation:
+
+1. Read all `D-XX: <decision>` lines from DISCUSS.md.
+2. Generate `.planning/phases/phase-<N>/PLAN.md`:
+
+```markdown
+# Implementation Plan
+
+**Phase:** <N>
+**Created:** <timestamp>
+**Source:** DISCUSS.md (<X> decisions)
+
+## Decisions
+
+- D-01: <decision>
+- D-02: <decision>
+
+## Steps
+
+- [ ] Step 1: <concrete implementation step traced to decision>
+- [ ] Step 2: <concrete implementation step>
+- [ ] Step 3: <concrete implementation step>
+
+## Acceptance Criteria
+
+- [ ] <criterion from DISCUSS.md>
+- [ ] <criterion from DISCUSS.md>
+
+## Status
+
+CONFIRMED
+```
+
+3. Update `.planning/STATE.md`:
+   - Set `plan_confirmed: true`
+   - Set `confirmed_at: <timestamp>`
+   - Set `status: in_progress`
+
+## Completion
+
+Report: plan saved, decisions count, file path, next step: run `/fd-new-feature` or `/fd-fix-bug`.

package/src/commands/fd-progress.md

@@ -0,0 +1,50 @@
+---
+description: Display project progress — STATE.md summary, active PLAN.md steps, and recent results
+argument-hint: [--json]
+---
+
+# Progress
+
+Display current project progress from planning files.
+
+**Input:** $ARGUMENTS (pass `--json` for machine-readable output)
+
+## Steps
+
+1. Check `.planning/STATE.md` exists — if not, return error: "Initialize project first with /fd-new-project."
+
+2. Read STATE.md and parse:
+   - Current phase number
+   - Status (planned/in_progress/completed)
+   - Last updated timestamp
+   - `plan_confirmed` flag
+
+3. Read `.planning/phases/phase-<N>/PLAN.md` if it exists:
+   - Count total steps (lines matching `- [ ]` or `- [x]`)
+   - Count completed steps (lines matching `- [x]`)
+
+4. Check for recent RESULT.md files in the last 3 phases.
+
+5. Display:
+
+```
+════════════════════════════════════════════════════════════
+Phase: <N>  |  Status: <status>  |  Updated: <timestamp>
+────────────────────────────────────────────────────────────
+Plan: <X> steps (<Y> complete)
+Plan confirmed: <yes/no>
+Recent results: Phase <N-1>, Phase <N>
+════════════════════════════════════════════════════════════
+```
+
+If `--json`, output structured JSON instead:
+```json
+{
+  "phase": N,
+  "status": "...",
+  "plan_confirmed": true,
+  "steps_total": X,
+  "steps_complete": Y,
+  "last_updated": "..."
+}
+```

package/src/commands/fd-regression-predict.md

@@ -0,0 +1,57 @@
+---
+description: Regression Prediction — estimate the most likely regression categories for a proposed change
+argument-hint: [change description]
+---
+
+# Regression Predict
+
+Predict the most likely regression categories for a proposed change before implementing it.
+
+**Input:** $ARGUMENTS — description of the proposed change
+
+## Steps
+
+Run two agents in parallel:
+
+- **@researcher**: Map the changed code paths in `$ARGUMENTS` to regression category keywords and patterns; check `.codebase/FAILURES.json` for prior regressions in the same area
+
+- **@tester**: Analyze existing test coverage for the affected paths; identify which regression categories are under-tested
+
+## Regression Categories
+
+| Category | Indicators |
+|----------|-----------|
+| **Performance** | touching caching, DB queries, loops, response serialization |
+| **Auth / Security** | touching middleware, tokens, sessions, permissions |
+| **Schema / Data** | touching DB models, migrations, serializers |
+| **UI States** | touching frontend components, state management, events |
+| **Async Flows** | touching queues, workers, webhooks, timeouts |
+| **API Contracts** | touching public endpoints, request/response shapes |
+| **Integration** | touching external service calls, adapters |
+
+## Report
+
+```
+════════════════════════════════════════════
+REGRESSION PREDICTION
+════════════════════════════════════════════
+Change: <summary of $ARGUMENTS>
+
+Likely Regressions (ranked by probability):
+
+  🔴 HIGH — Auth/Security
+     Reason: change touches middleware X
+     Prior: FAILURES.json F-12 (×3 recurrences)
+
+  🟠 MEDIUM — API Contracts  
+     Reason: modifies response shape of /api/checkout
+
+  🟡 LOW — Performance
+     Reason: adds DB query in hot path
+
+────────────────────────────────────────────
+Recommended Tests to Add:
+  1. <specific test scenario>
+  2. <specific test scenario>
+════════════════════════════════════════════
+```

package/src/commands/fd-resume.md

@@ -0,0 +1,46 @@
+---
+description: Reload STATE.md + last PLAN.md + DISCUSS.md — brief the user, PAUSE for confirmation, then continue from where stopped
+argument-hint: [--yes]
+---
+
+# Resume
+
+Resume a previously interrupted FlowDeck session.
+
+**Input:** $ARGUMENTS (pass `--yes` to skip confirmation pause)
+
+## Steps
+
+1. Check `.planning/STATE.md` exists — if not, error: "No active project. Run /fd-new-project first."
+
+2. Read STATE.md and parse current state:
+   - Phase, status, last_updated, plan_confirmed
+
+3. Read `.planning/phases/phase-<N>/PLAN.md` if it exists — show preview (first 20 lines).
+
+4. Read `.planning/phases/phase-<N>/DISCUSS.md` if it exists — show decision count.
+
+5. Present session summary:
+
+```
+═══════════════════════════════════════════════
+RESUMING SESSION
+═══════════════════════════════════════════════
+Phase: <N>  |  Status: <status>
+Last updated: <timestamp>
+Plan confirmed: <yes/no>
+Decisions: <X> from DISCUSS.md
+
+Plan preview:
+<first 10 lines of PLAN.md>
+───────────────────────────────────────────────
+Type CONFIRM to resume execution from this point.
+═══════════════════════════════════════════════
+```
+
+6. Unless `--yes` is passed, **PAUSE** and wait for user to type CONFIRM.
+
+7. After confirmation, continue execution:
+   - If `plan_confirmed: true` and there are uncompleted steps in PLAN.md → proceed with implementation
+   - If no plan → suggest running `/fd-plan`
+   - Brief the user on what the next step is before starting

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

@@ -0,0 +1,62 @@
+---
+description: Parallel reviewer + researcher + tester — aggregates findings into critical/major/minor report
+argument-hint: [--scope=path | --focus=security,quality,tdd]
+---
+
+# Review Code
+
+Run a comprehensive parallel code review.
+
+**Input:** $ARGUMENTS — optional `--scope=<path>` and `--focus=<areas>`
+
+## Steps
+
+1. Determine scope: use `--scope` if provided, else review uncommitted changes (`git diff --name-only HEAD`).
+2. If no changes found, report: "Nothing to review."
+
+## Parallel Review
+
+Run three reviewers in parallel:
+
+- **@reviewer**: Quality, security, convention compliance, TDD discipline
+  - CRITICAL: hardcoded secrets, SQL injection, XSS, auth gaps
+  - HIGH: logic errors, missing error handling, unsafe casts
+  - MEDIUM: functions >50 lines, nesting >4 deep, missing tests
+  - LOW: naming nits, missing comments on public APIs
+
+- **@researcher**: API contracts, edge cases, hidden dependencies, integration risks
+
+- **@tester**: Test coverage, missing test cases, test quality, regression risks
+
+## Report
+
+Aggregate findings into:
+
+```
+════════════════════════════════════════════
+CODE REVIEW REPORT
+════════════════════════════════════════════
+Files reviewed: <N>
+
+CRITICAL (<count>)
+  - <file>:<line> — <issue>
+
+HIGH (<count>)
+  - <file>:<line> — <issue>
+
+MEDIUM (<count>)
+  - <file>:<line> — <issue>
+
+LOW (<count>)
+  - <file>:<line> — <issue>
+
+Test Coverage: <findings>
+────────────────────────────────────────────
+Verdict: PASS / NEEDS CHANGES / BLOCK
+════════════════════════════════════════════
+```
+
+**Verdict rules:**
+- CRITICAL issues → BLOCK
+- HIGH issues → NEEDS CHANGES
+- Only MEDIUM/LOW → PASS with comments