@dv.nghiem/flowdeck 0.1.0

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

@@ -0,0 +1,105 @@
+# /fd-guarded-edit
+
+**Edit gate command** — evaluates a proposed file change before it is applied and returns a binding gate decision.
+
+Combines: patch trust scoring, architectural constraint checking, policy enforcement, volatility analysis, and failure history into a single pass/block decision.
+
+---
+
+## Usage
+
+```
+/fd-guarded-edit --file "<path>" --change "<description>" [flags]
+```
+
+## Arguments
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--file` | string | — | File path being changed |
+| `--change` | string | — | Plain-language description of the change |
+| `--dry-run` | boolean | false | Evaluate without recording or side effects |
+| `--json` | boolean | false | Return raw JSON instead of table |
+
+At least one of `--file` or `--change` is required.
+
+---
+
+## Gate decisions
+
+| Decision | Meaning |
+|----------|---------|
+| `auto-approve` | Apply — no action needed (trust ≥70, no violations, stable file) |
+| `require-confirmation` | Review the diff carefully, then confirm (volatile file, guarded mode, or prior failures) |
+| `require-review` | Route to human reviewer — do not auto-apply (trust <40 or policy violation) |
+| `block` | Do NOT apply — arch constraint violation or critical policy breach |
+
+### Decision priority (highest first)
+
+1. Arch constraint violated → **block**
+2. Policy violation + trust < 30 → **block**
+3. `review-only` execution mode → **require-review**
+4. Trust < 40 OR any policy violation → **require-review**
+5. `guarded` execution mode OR volatile file OR prior failures → **require-confirmation**
+6. All else → **auto-approve**
+
+---
+
+## Output
+
+```
+════════════════════════════════════════════════════════════
+fd-guarded-edit
+────────────────────────────────────────────────────────────
+  File:   src/auth/token.ts
+  Change: replace jwt secret rotation logic
+────────────────────────────────────────────────────────────
+  ⚑ Decision:    REQUIRE-REVIEW
+  Reason:       High risk: trust score 32/100, 0 policy violation(s)
+  Risk score:   32/100 (high-risk)
+  Exec mode:    guarded
+  Prior fails:  F-023, F-031
+────────────────────────────────────────────────────────────
+  → Route to human reviewer before applying — do not auto-apply
+════════════════════════════════════════════════════════════
+```
+
+### Fields returned
+
+| Field | Description |
+|-------|-------------|
+| `decision` | Gate decision string |
+| `reason` | Explanation for the decision |
+| `risk_score` | Patch trust score 0–100 |
+| `execution_mode` | Current repo execution mode (auto/guarded/review-only) |
+| `policy_violations` | Policy rule strings that were triggered |
+| `volatile_files` | Files that matched volatile/critical zones |
+| `prior_failures` | Failure IDs for prior failures on this path |
+| `arch_constraint` | Whether an architectural constraint was violated |
+| `recommended_action` | Plain-language next step |
+
+---
+
+## Examples
+
+```bash
+# Check before editing auth token logic
+/fd-guarded-edit --file "src/auth/token.ts" --change "replace secret rotation"
+
+# Dry run (evaluate without recording)
+/fd-guarded-edit --file "src/payment/webhook.ts" --change "update stripe handler" --dry-run
+
+# JSON for CI/CD pipeline integration
+/fd-guarded-edit --file "src/core/engine.ts" --change "patch core engine" --json
+```
+
+---
+
+## Data sources read
+
+- `.codebase/POLICIES.json` — active policy rules
+- `.codebase/VOLATILITY.json` — volatile/critical paths
+- `.codebase/FAILURES.json` — unresolved prior failures per path
+- `.codebase/CONSTRAINTS.md` — forbidden path patterns
+- `.planning/config.json` — execution mode setting
+- Patch trust scorer — keyword + volatility scoring

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

@@ -0,0 +1,27 @@
+---
+description: Map the codebase structure into .codebase/ files for AI context
+argument-hint: "[--full] [--update]"
+---
+
+Analyze and document the codebase for AI agent context.
+
+**What this does:**
+1. Scans the project structure (entry points, modules, dependencies)
+2. Identifies key files, patterns, and conventions
+3. Writes structured summaries to `.codebase/`:
+   - `ARCHITECTURE.md` — high-level system design
+   - `CONVENTIONS.md` — naming, style, and patterns used in this project
+   - `DEPENDENCIES.md` — external packages and what they're used for
+   - `INDEX.md` — file-by-file inventory
+
+**Flags:**
+- `--full` — Deep scan (reads every file, slower but thorough)
+- `--update` — Refresh existing `.codebase/` files with recent changes
+
+**Why this matters:** Agents use `.codebase/` for context instead of re-scanning on every task.
+
+## What Next?
+
+1. **Start discussion** → `/fd-discuss`
+2. **Write documentation** → `/fd-write-docs`
+3. **View dashboard** → `/fd-dashboard`

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

@@ -0,0 +1,63 @@
+---
+description: Initialize or manage multi-repo configuration for microservice architecture. Adds, lists, checks status of, or removes repos from .planning/config.json.
+argument-hint: "[--add <path> <role> | --list | --status | --remove <name>]"
+---
+
+Manage the multi-repo registry in `.planning/config.json`.
+
+**With no arguments:** show the current list of registered repos from `sub_repos`.
+
+**Arguments:**
+
+`--add <path> <role>` — Register a new repo. `path` is relative to the root repo's parent directory. `role` must be one of: `upstream-api`, `downstream-consumer`, `shared-lib`, `gateway`, `worker`. Prompts for `name`, `tech_stack`, and `owner_team` if not inferred.
+
+`--list` — Print all registered repos as a table: name, path, role, tech_stack, owner_team.
+
+`--status` — For each registered repo, check if the path resolves on disk, report the current git branch, and show whether a `.planning/` directory exists in that repo.
+
+`--remove <name>` — Remove a repo from the registry by name. Does not delete the repo on disk.
+
+**What this does:**
+
+1. Reads `.planning/config.json`; creates the file with an empty `sub_repos: []` array if it does not exist
+2. For `--add`: resolves the path, infers `name` from the directory name if not provided, writes the new entry to `sub_repos`
+3. For `--list`: formats the `sub_repos` array as a readable table
+4. For `--status`: walks each entry, checks `path` existence, runs `git -C <resolved_path> branch --show-current`
+5. For `--remove`: removes the matching entry by `name`, writes back to config.json
+
+**Example output (no args):**
+
+```
+Multi-Repo Registry (.planning/config.json)
+
+  Name                 Path                   Role                  Stack             Team
+  ───────────────────  ─────────────────────  ────────────────────  ────────────────  ────────
+  user-service         ../user-service        upstream-api          node+typescript   platform
+  order-service        ../order-service       downstream-consumer   node+typescript   commerce
+  shared-types         ../shared-types        shared-lib            node+typescript   platform
+  api-gateway          ../api-gateway         gateway               nginx+lua         infra
+
+4 repos registered. Run /fd-multi-repo --status to check path health.
+```
+
+**Example output (--status):**
+
+```
+Multi-Repo Status
+
+  Name              Path               Exists   Branch            .planning/
+  ────────────────  ─────────────────  ───────  ────────────────  ──────────
+  user-service      ../user-service    ✅        main              ✅
+  order-service     ../order-service   ✅        feature/checkout  ❌
+  shared-types      ../shared-types    ✅        main              ❌
+  api-gateway       ../api-gateway     ❌        —                 —
+
+Warning: api-gateway path does not exist on disk.
+Warning: order-service and shared-types have no .planning/ — cross-repo planning context unavailable.
+```
+
+**What Next?**
+
+- `/fd-discuss` — discuss a change that spans multiple repos before planning it
+- `/fd-new-feature` — plan and execute a feature; use with multi-repo context loaded
+- `/fd-dashboard` — view progress across all registered repos

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

@@ -0,0 +1,25 @@
+---
+description: Execute feature implementation workflow — orchestrator + parallel coder/researcher + reviewer + tester
+argument-hint: "[feature-description]"
+---
+
+Execute a new feature using FlowDeck's multi-agent workflow.
+
+**What this does:**
+1. If a confirmed PLAN.md exists: delegates steps to `@coder` in order
+2. If no plan: first runs discuss → plan → confirm, then executes
+3. Runs `@researcher` in parallel for any external APIs or docs needed
+4. Runs `@reviewer` after each significant step to catch issues early
+5. Runs `@tester` to write and run tests for implemented code
+6. Updates STATE.md after each step
+
+**Phase gate:** Requires `plan_confirmed = true` in STATE.md before execution begins.
+
+**Parallel execution:** Independent steps are delegated simultaneously to maximize speed.
+
+## What Next?
+
+1. **Review the code** → `/fd-review-code`
+2. **Write documentation** → `/fd-write-docs`
+3. **Deploy check** → `/fd-deploy-check`
+4. **Start next feature** → `/fd-new-feature [description]`

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

@@ -0,0 +1,24 @@
+---
+description: Initialize a new FlowDeck project — creates .planning/ directory structure
+argument-hint: "[project-name]"
+---
+
+Initialize FlowDeck in the current project directory.
+
+**What this does:**
+1. Creates `.planning/` directory structure:
+   - `STATE.md` — current phase and status
+   - `PROJECT.md` — project overview (you fill this in)
+   - `phases/` — one subdirectory per roadmap phase
+2. Optionally runs `/fd-map-codebase` to analyze existing code
+3. Guides you to set the initial phase
+
+**Use this when:** Starting a new feature sprint, onboarding to an existing project, or setting up FlowDeck for the first time.
+
+**Next step:** Run `/fd-map-codebase` to document the codebase, then `/fd-discuss` to start planning.
+
+## What Next?
+
+1. **Map codebase** → `/fd-map-codebase`
+2. **Start discussion** → `/fd-discuss`
+3. **View dashboard** → `/fd-dashboard`

package/docs/commands/fd-plan.md

@@ -0,0 +1,33 @@
+---
+description: Create a detailed implementation plan from requirements — saves PLAN.md, requires confirmation before execution
+argument-hint: "[phase-number]"
+---
+
+Create a step-by-step implementation plan for the current (or specified) phase.
+
+**What this does:**
+1. Reads `.planning/phases/phase-N/DISCUSS.md` for locked decisions
+2. Reads `.codebase/ARCHITECTURE.md` for system context (if mapped)
+3. Breaks the feature into ordered, atomic steps
+4. Identifies dependencies between steps
+5. Saves to `.planning/phases/phase-N/PLAN.md`
+6. Asks for your confirmation before marking phase as `execute`-ready
+
+**Plan format:**
+```
+## Phase N: [Name]
+### Step 1: [Action] — [file path]
+### Step 2: [Action] — [file path]
+...
+```
+
+**Next step:** Run `/fd-new-feature` to execute the confirmed plan.
+
+## What Next?
+
+After plan is confirmed, choose your next step:
+
+1. **Start feature implementation** → `/fd-new-feature [description]`
+2. **Revisit discussion** → `/fd-discuss [phase-number]`
+3. **View progress** → `/fd-progress`
+4. **Check dashboard** → `/fd-dashboard`

package/docs/commands/fd-progress.md

@@ -0,0 +1,11 @@
+---
+description: Display current STATE.md, active PLAN.md, and recent results
+---
+Run the FlowDeck progress command to see current project state.
+
+## What Next?
+
+1. **Continue feature work** → `/fd-new-feature [description]`
+2. **Fix a bug** → `/fd-fix-bug [issue]`
+3. **View dashboard** → `/fd-dashboard`
+4. **Check roadmap** → `/fd-roadmap`

package/docs/commands/fd-resume.md

@@ -0,0 +1,10 @@
+---
+description: Resume from last checkpoint — reloads STATE.md and PLAN.md context
+---
+Run the FlowDeck resume workflow to reload project context and continue from where you stopped.
+
+## What Next?
+
+1. **Continue feature work** → `/fd-new-feature [description]`
+2. **View progress** → `/fd-progress`
+3. **Check dashboard** → `/fd-dashboard`

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

@@ -0,0 +1,29 @@
+---
+description: Parallel code review — reviewer + researcher + tester — aggregates into critical/major/minor report
+argument-hint: "[scope: file, directory, or 'staged']"
+---
+
+Run a comprehensive parallel code review.
+
+**What this does:**
+1. Determines scope: staged changes, a file/directory, or the whole PR
+2. Runs `@reviewer` (security, quality, logic), `@researcher` (API correctness), and `@tester` (test coverage) in parallel
+3. Aggregates findings into a single report ranked: CRITICAL → HIGH → MEDIUM → LOW
+4. Proposes fixes for every CRITICAL and HIGH finding
+5. Skips stylistic preferences — only real bugs and security issues
+
+**Output format:**
+```
+## Code Review Report
+### CRITICAL [n]
+- [finding]: [file:line] — [fix]
+### HIGH [n]
+...
+```
+
+## What Next?
+
+1. **Fix critical issues found** → `/fd-fix-bug [issue description]`
+2. **Deploy check** → `/fd-deploy-check`
+3. **Update documentation** → `/fd-write-docs`
+4. **Check project progress** → `/fd-progress`

package/docs/commands/fd-roadmap.md

@@ -0,0 +1,10 @@
+---
+description: View or update the project roadmap — shows phase statuses and milestones
+---
+Run the FlowDeck roadmap workflow to view or update project phases and milestones.
+
+## What Next?
+
+1. **Start next phase** → `/fd-new-feature [description]`
+2. **View progress** → `/fd-progress`
+3. **Check dashboard** → `/fd-dashboard`

package/docs/commands/fd-settings.md

@@ -0,0 +1,10 @@
+---
+description: View or update FlowDeck settings — model assignments, guard enforcement, workspace mode
+---
+Run the FlowDeck settings command to view or modify configuration.
+
+## What Next?
+
+1. **View dashboard** → `/fd-dashboard`
+2. **Check progress** → `/fd-progress`
+3. **Start working** → `/fd-new-feature [description]`

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

@@ -0,0 +1,10 @@
+---
+description: Write documentation — explore public APIs, writer drafts, reviewer accuracy check
+---
+Run the FlowDeck write-docs workflow to generate accurate project documentation.
+
+## What Next?
+
+1. **Review documentation** → `/fd-review-code staged`
+2. **Deploy check** → `/fd-deploy-check`
+3. **Create checkpoint** → `/fd-checkpoint`