@dv.nghiem/flowdeck 0.3.7 → 0.3.9

package/src/commands/fd-quick.md

@@ -1,63 +1,311 @@
 ---
-description: Quick task execution — analyze, implement, review, or investigate a specific piece of work without the full discuss -> plan -> execute workflow
+description: Autonomous workflow launcher — classifies the task, selects the correct existing workflow, and runs the full stage sequence (discuss → plan → execute → verify and variants) end-to-end with minimal user input
 argument-hint: [task description]
 ---
 
-# Quick Task
+# Quick — Autonomous Workflow Launcher
 
-Execute a focused task without the full workflow. Analyzes the request, selects the best specialist agent, and returns the result directly.
+Run the correct FlowDeck workflow automatically for any task. This command:
+- Explores the codebase first before asking any questions
+- Classifies the task type using both text signals and repo evidence
+- Selects the appropriate existing workflow and stage sequence
+- Routes all clarifying questions through `@supervisor` (only when evidence cannot answer)
+- Executes each stage in order using the existing registered commands
+- Stops only when blocked, awaiting approval, or fully verified
 
 **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 |
-|-----------|-----------------|-------|
-| Backend code implementation | api, server, service, database, migration, endpoint, repository | `@backend-coder` |
-| Frontend code implementation | ui, frontend, component, page, css, style, react, screen | `@frontend-coder` |
-| DevOps and infra implementation | ci, cd, deploy, pipeline, workflow, docker, kubernetes, terraform | `@devops` |
-| 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` |
-| UI design-first planning | landing page, dashboard, admin panel, onboarding UX, app screen, wireframe, design system | `@design` |
-| 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.
+---
+
+## Step 0: Autonomous Preflight Exploration
+
+**Before asking the human anything**, explore the repository to build evidence.
+
+Invoke `@code-explorer` to inspect the following in parallel:
+
+1. **Repository structure** — `.planning/STATE.md`, `.planning/PROJECT.md`, `AGENTS.md`
+2. **Available commands** — enumerate `src/commands/*.md` filenames
+3. **Available agents** — enumerate `src/agents/*.ts` filenames
+4. **Available skills** — enumerate `src/skills/` directory names
+5. **Workflow config** — read `flowdeck.json` if present (governance, models)
+6. **Tech stack** — read `package.json`, `go.mod`, `Cargo.toml`, `pyproject.toml`
+7. **Implementation patterns** — inspect `src/` top-level directories
+8. **Prior decisions** — check `.planning/phases/*/DISCUSS.md` files
+9. **Relevant files** — find source files matching keywords in `$ARGUMENTS`
+
+Store the exploration snapshot in STATE.md under `quick_run.preflightExploration`:
+
+```yaml
+quick_run:
+  preflightExploration:
+    exploredAt: <ISO timestamp>
+    techStack: [...]
+    availableCommands: [...]
+    availableSkills: [...]
+    implementationPatterns: [...]
+    evidenceCount: <N>
+    clarificationResolvedByEvidence: false
+    suppressedQuestions: []
+```
+
+**This step is mandatory. Do not proceed to Step 1 until exploration is complete.**
+
+### Question suppression rule
+
+After exploration, invoke the question guard before emitting any question:
+
+> A question may only be forwarded to `@supervisor` if:
+> 1. It cannot be answered by the exploration evidence
+> 2. It has not already been asked in the current session
+> 3. It is required to safely select the correct workflow
+
+If the question can be answered from repo evidence, suppress it and log it in
+`quick_run.suppressedQuestions`. Do not present it to the user.
+
+---
+
+## Step 1: Pre-flight State Check
+
+1. Check `.planning/STATE.md` exists — if not, error: "Run /fd-new-project first."
+2. Read `.planning/STATE.md` to determine if a `quick_run` entry already exists for this session.
+   - If `quick_run.outcome` is `running` or `blocked`: **resume from the last completed stage** (skip to Step 5).
+   - If `quick_run.preflightExploration` exists and `exploredAt` is recent (< 5 min): reuse it, skip Step 0.
+   - Otherwise: proceed to Step 0 then Step 2.
+
+---
+
+## Step 2: Classify the Task
+
+Use **both** text-signal matching and preflight exploration evidence:
+
+Call `classifyTaskWithContext(description, explorationResult)` from `quick-router.ts`.
+
+This resolves ambiguous descriptions using repo evidence before flagging
+`clarificationNeeded`. Most short descriptions that would normally prompt a
+question are resolved by evidence (e.g., tech stack, existing patterns, prior decisions).
+
+### Signal Classification Table
+
+| Task Type | Strong Signal Keywords | Stage Sequence |
+|-----------|------------------------|----------------|
+| **bugfix** | fix, bug, broken, not working, error, crash, regression, debug, exception, failing, root cause, why is, stack trace | `discuss → fix-bug → verify` |
+| **ui-feature** | landing page, dashboard, admin panel, app screen, onboarding, wireframe, design system, ux flow, web app, website, responsive layout, navbar, modal, sidebar, frontend page | `discuss → design → plan → execute → verify` |
+| **docs** | docs, documentation, readme, api docs, usage guide, write docs, document, changelog, tutorial, docstring | `discuss → write-docs → verify` |
+| **simple** | rename, move file, minor, typo, update constant, update config, bump version, one-liner | `execute → verify` |
+| **feature** | (substantive description, 8+ words, no above signals) | `discuss → plan → execute → verify` |
+| **ambiguous** | (short, vague, or unclear — only after exploration cannot resolve) | *(clarify via supervisor — see Step 3)* |
+
+### Classification Rules
+
+1. **Bug signals dominate**: if the description contains "fix", "bug", "error", "crash", "exception", "broken", or "regression", classify as `bugfix` even if it also mentions UI elements.
+2. **UI signals for design-first**: if 1+ UI-heavy signal is present and no dominant bug signal, classify as `ui-feature`.
+3. **Docs signals**: if "docs", "documentation", "readme", or "write docs" is present without implementation signals, classify as `docs`.
+4. **Simple**: if "rename", "typo", "minor", or "move file" is present and description is a single, scoped operation.
+5. **Feature**: substantive description (8+ words) with no specific signal type.
+6. **Ambiguous** (only when exploration cannot resolve): description is too short (<5 words) or matches a bare imperative with no object (e.g., "improve", "add", "make it better") AND repo evidence does not clarify scope or type.
+
+Record the classification result:
+```yaml
+quick_run:
+  taskDescription: "$ARGUMENTS"
+  taskType: <feature|ui-feature|bugfix|docs|simple|ambiguous>
+  requiresDesign: <true|false>
+  requiresTDD: <true|false>
+  stageSequence: [<ordered stage names>]
+  completedStages: []
+  currentStage: <first stage name>
+  supervisorDecisions: {}
+  startedAt: <ISO timestamp>
+  outcome: running
+```
+
+---
+
+## Step 3: Supervisor-Gated Clarification (only when exploration cannot resolve)
+
+**Only proceed to Step 4 when classification confidence is sufficient.**
+
+If classification is `ambiguous` AND exploration evidence did not resolve it:
+
+1. Invoke `@supervisor` (preflight review of `fd-quick` command) with:
+   - The partial task description
+   - The preflight exploration snapshot (tech stack, patterns, prior decisions)
+   - The `clarificationPrompt` from the classification (already enriched with context)
+2. `@supervisor` presents the single clarifying question to the user. **Ask ONE question only.**
+3. Wait for the user's answer.
+4. Re-classify using the combined original description + the user's answer.
+5. If confidence is still low after one clarification round, route to `feature` with a note in STATE.md.
+
+**All clarification goes through `@supervisor`. Do not have specialist agents ask questions directly.**
+**Do not ask questions that can be answered from the exploration evidence.**
+
+Example supervisor clarification questions (only when evidence is absent):
+- "Is this a new feature, a bug fix, or a documentation task?"
+- "Does this involve building or changing a user-facing UI (page, dashboard, component)?"
+- "Can you describe the specific bug — what is the expected vs actual behavior?"
+- "Is the scope a single file change, or does it span multiple modules?"
+
+---
+
+## Step 4: Confirm Stage Sequence
+
+Present the classification and planned stage sequence to the user before proceeding:
+
+```
+Task classified as: <task type>
+Stage sequence:     <stage-1> → <stage-2> → ... → <stage-N>
+Requires design:    <yes / no>
+Requires TDD:       <yes / no>
+Evidence used:      <N> items from preflight exploration
+
+Running /fd-quick autonomously. I will proceed through each stage and pause only
+if I need approval, encounter a blocker, or complete the full sequence.
+```
+
+Proceed automatically — do not wait for additional input unless approval is explicitly required by a stage.
+
+---
+
+## Step 5: Execute Stage Sequence Autonomously
+
+For **each stage** in the sequence (in order), execute the following loop:
+
+### 5a. Announce Stage Start
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Stage: <stage-name>  Command: /<command>
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+### 5b. Supervisor Preflight Review
+
+Before executing the stage, invoke `@supervisor` (preflight) on the stage's command:
+- Pass: `taskDescription`, `currentPhase` (= current stage name), `prerequisitesMet`, `designApprovalPresent`, `regressionTestPresent` as known from STATE.md.
+
+**Handle supervisor decision:**
+
+| Decision | Action |
+|----------|--------|
+| `approve` | Proceed to 5c immediately |
+| `revise` | Resolve the listed `requiredChanges` (e.g., confirm PLAN.md, run preceding step) then re-run the stage |
+| `block` | Stop. Report why. Show what is blocked. Ask user for the specific missing input or approval. Update `quick_run.outcome = blocked` in STATE.md. |
+| `escalate` | Pause. Present the escalation reason to the user. Request explicit approval. On approval: continue. On denial: stop and summarize. |
+
+### 5c. Execute the Stage
+
+Execute the stage using its existing command with full context from the preflight
+exploration snapshot (available in `quick_run.preflightExploration`). Pass it to
+each stage so worker agents can use evidence directly.
+
+**Stage → Command Mapping:**
+
+| Stage | Command | Key Behavior |
+|-------|---------|--------------|
+| `discuss` | `/fd-discuss` | Runs `@discusser` structured Q&A. Passes preflight exploration so questions already answered by evidence are skipped. Saves `DISCUSS.md`. One question at a time. |
+| `design` | `/fd-design --mode=draft` | Runs design-first pipeline. Required for `ui-feature` tasks. Produces design artifact + approval. |
+| `plan` | `/fd-plan` | Creates `PLAN.md` from `DISCUSS.md` decisions. **Pauses for user CONFIRM before saving.** |
+| `execute` | `/fd-execute` | TDD pipeline: BEHAVIOR → RED → GREEN → REFACTOR per step. Delegates to appropriate coder agents. |
+| `fix-bug` | `/fd-fix-bug` | TDD bugfix: explore → RED regression test → GREEN fix → REFACTOR → record in FAILURES.json. |
+| `write-docs` | `/fd-write-docs` | Explore APIs → `@writer` drafts → `@reviewer` accuracy check → finalize. |
+| `verify` | `/fd-verify` | Full verification: tests + code review + security scan + deploy check. Reports verdict. |
+
+### 5d. Stage Completion Check
+
+After the stage command completes:
+1. Invoke `@supervisor` (post-stage) to confirm the stage output is valid.
+2. If supervisor returns `approve` or `revise` with fixable issues: mark the stage complete.
+3. If supervisor returns `block`: halt, report, update state.
+4. Update STATE.md:
+   ```yaml
+   quick_run:
+     completedStages: [<all completed stage names>]
+     currentStage: <next stage name or null>
+     supervisorDecisions:
+       <stage-name>:
+         decision: <decision>
+         reasons: [...]
+         timestamp: <ISO>
+   ```
+5. Proceed to next stage.
+
+### 5e. Approval Gate (plan stage only)
+
+The `plan` stage requires explicit user CONFIRM per the `/fd-plan` command's D-06 rule.
+`/fd-quick` does NOT bypass this gate. Present the plan to the user and wait for CONFIRM.
+
+---
+
+## Step 6: Completion
+
+When all stages complete:
+
+1. Update STATE.md:
+   ```yaml
+   quick_run:
+     completedStages: [<all stages>]
+     currentStage: null
+     outcome: complete
+   ```
+
+2. Present final summary:
+   ```
+   ════════════════════════════════════════════════
+   /fd-quick Complete — <task type>
+   ════════════════════════════════════════════════
+   Task:      $ARGUMENTS
+   Workflow:  <stage-1> → ... → <stage-N>
+   Outcome:   ✅ COMPLETE
+   Evidence:  <N> preflight items used (0 human questions asked before exploration)
+   ────────────────────────────────────────────────
+   Verify result: /fd-verify
+   Save state:    /fd-checkpoint
+   ════════════════════════════════════════════════
+   ```
+
+---
+
+## Step 7: Block / Failure Handling
+
+If execution cannot continue at any stage:
+
+1. Update STATE.md: `quick_run.outcome = blocked`
+2. Report:
+   ```
+   ════════════════════════════════════════════════
+   /fd-quick Blocked
+   ════════════════════════════════════════════════
+   Stage reached:    <stage-name>
+   Why stopped:      <clear reason>
+   Blocked at:       <command name>
+   What is needed:   <exact missing input or approval>
+   ────────────────────────────────────────────────
+   To resume:        /fd-quick $ARGUMENTS
+     (will continue from <next-stage-name>)
+   To fix manually:  /<blocked-command> [args]
+   ════════════════════════════════════════════════
+   ```
+
+---
+
+## Workflow Discipline (Non-Negotiable)
+
+These gates from the existing workflow system are **never bypassed by /fd-quick**:
+
+- **Design-first**: `ui-feature` tasks MUST complete the `design` stage (with `@design` approval and handoff) before `execute` can begin. No `--override` unless user explicitly requests it.
+- **TDD**: `execute` and `fix-bug` stages enforce RED → GREEN → REFACTOR. `/fd-quick` does not skip tests.
+- **Plan CONFIRM**: The `plan` stage requires explicit user CONFIRM. `/fd-quick` presents the plan and waits.
+- **Regression test**: `fix-bug` requires a failing regression test before implementation (per `/fd-fix-bug`).
+- **Verify**: All workflows end with `/fd-verify` to confirm all checks pass before marking complete.
+
+---
+
+## Existing Commands Remain Independent
+
+`/fd-quick` is a workflow launcher. The commands it invokes (`/fd-discuss`, `/fd-plan`, etc.) remain fully operational as standalone commands. Running `/fd-quick` does not lock out any other command.
+
+---
+
+## State Visibility
+
+All routing and execution progress is recorded in `.planning/STATE.md` under the `quick_run` key. Use `/fd-status` to inspect current state. Use `/fd-resume` to reload context after a session break.

package/src/rules/common/behavioral.md

@@ -0,0 +1,63 @@
+Behavioral guidelines to reduce common LLM coding mistakes. Merge with project-specific instructions as needed.
+
+**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.
+
+## 1. Think Before Coding
+
+**Don't assume. Don't hide confusion. Surface tradeoffs.**
+
+Before implementing:
+- State your assumptions explicitly. If uncertain, ask.
+- If multiple interpretations exist, present them - don't pick silently.
+- If a simpler approach exists, say so. Push back when warranted.
+- If something is unclear, stop. Name what's confusing. Ask.
+
+## 2. Simplicity First
+
+**Minimum code that solves the problem. Nothing speculative.**
+
+- No features beyond what was asked.
+- No abstractions for single-use code.
+- No "flexibility" or "configurability" that wasn't requested.
+- No error handling for impossible scenarios.
+- If you write 200 lines and it could be 50, rewrite it.
+
+Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
+
+## 3. Surgical Changes
+
+**Touch only what you must. Clean up only your own mess.**
+
+When editing existing code:
+- Don't "improve" adjacent code, comments, or formatting.
+- Don't refactor things that aren't broken.
+- Match existing style, even if you'd do it differently.
+- If you notice unrelated dead code, mention it - don't delete it.
+
+When your changes create orphans:
+- Remove imports/variables/functions that YOUR changes made unused.
+- Don't remove pre-existing dead code unless asked.
+
+The test: Every changed line should trace directly to the user's request.
+
+## 4. Goal-Driven Execution
+
+**Define success criteria. Loop until verified.**
+
+Transform tasks into verifiable goals:
+- "Add validation" → "Write tests for invalid inputs, then make them pass"
+- "Fix the bug" → "Write a test that reproduces it, then make it pass"
+- "Refactor X" → "Ensure tests pass before and after"
+
+For multi-step tasks, state a brief plan:
+```
+1. [Step] → verify: [check]
+2. [Step] → verify: [check]
+3. [Step] → verify: [check]
+```
+
+Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
+
+---
+
+**These guidelines are working if:** fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes.

package/src/skills/blast-radius-preview/SKILL.md

@@ -6,7 +6,7 @@ origin: FlowDeck
 
 # Blast Radius Preview
 
-Before committing to a change, map every system that could break. Run `/blast-radius` with a change description.
+Before committing to a change, map every system that could break. Activate this skill by providing a change description to the agent.
 
 ## When to Activate
 

package/src/skills/change-impact-radar/SKILL.md

@@ -6,7 +6,7 @@ origin: FlowDeck
 
 # Change Impact Radar
 
-Predicts blast surface before the AI touches a single file. Run `/impact-radar` with a description of the intended change.
+Predicts blast surface before the AI touches a single file. Activate this skill by providing the intended change description to the agent.
 
 ## When to Activate
 
@@ -58,6 +58,6 @@ Activate before:
 
 ## Guidance
 
-- If MEMORY.json does not exist, run `/map-codebase` first to build the graph.
+- If MEMORY.json does not exist, run `/fd-map-codebase` first to build the graph.
 - If a file has no test coverage and is indirectly impacted, flag it as "coverage gap".
 - Never proceed with a HIGH impact change without human confirmation.

package/src/skills/codebase-mapping/SKILL.md

@@ -12,7 +12,7 @@ Produces structured documentation of a codebase that agents can read to answer "
 
 - Starting work on an unfamiliar codebase
 - Before a major feature that spans multiple modules
-- When `/map-codebase` command is invoked
+- When `/fd-map-codebase` command is invoked
 - When `.codebase/` is missing or stale
 
 ## Output Files

package/src/skills/confidence-aware-planning/SKILL.md

@@ -33,7 +33,7 @@ Before planning ANY task:
 2. Scan affected files for context
 3. Estimate confidence level
 4. Act based on level:
-   - HIGH: proceed to `/plan`
+   - HIGH: proceed to `/fd-plan`
    - MEDIUM: write explicit assumptions at the top of PLAN.md, flag 3 highest risks
    - LOW: stop, ask clarifying questions, do not write PLAN.md until answered
 

package/src/skills/context-load/SKILL.md

@@ -60,4 +60,4 @@ After loading context, produce this briefing:
 **Key Conventions**: [2-3 most important patterns]
 ```
 
-If any file is missing, note it: "STATE.md not found — run `/new-project` to initialize."
+If any file is missing, note it: "STATE.md not found — run `/fd-new-project` to initialize."

package/src/skills/human-review-routing/SKILL.md

@@ -30,11 +30,11 @@ When a patch is flagged as `review-required` or `high-risk` by the Patch Trust S
 
 ## Workflow
 
-Run `/review-route` with `--files` and `--change` to get the routing decision.
+Provide the files and change description to the agent to get the routing decision.
 
-Example:
+Example input:
 ```
-/review-route {"files": "src/services/auth.ts,src/api/payment.ts", "change": "refactor JWT validation"}
+Review route for: files=src/services/auth.ts,src/api/payment.ts change=refactor JWT validation
 ```
 Output:
 ```

package/src/skills/intent-translator/SKILL.md

@@ -6,7 +6,7 @@ origin: FlowDeck
 
 # Intent-to-Change Translator
 
-Run `/translate-intent` with a plain-language description of what you want. Get back a ranked menu of concrete implementation options with tradeoffs — before writing a single line of code.
+Run `/fd-translate-intent` with a plain-language description of what you want. Get back a ranked menu of concrete implementation options with tradeoffs — before writing a single line of code.
 
 ## When to Activate
 
@@ -49,7 +49,7 @@ Run `/translate-intent` with a plain-language description of what you want. Get
 
 ### Recommendation
 Proceed with **Option 1** because [reason].
-To start: run `/plan` after confirming your choice.
+To start: run `/fd-plan` after confirming your choice.
 ```
 
 ## Confidence Rule

package/src/skills/multi-repo/SKILL.md

@@ -180,7 +180,7 @@ Conflicts must be resolved before any CHANGE PLAN is executed. The `@multi-repo-
 
 ## Independence Check Before Executing
 
-Before running `/multi-repo`:
+Before running `/fd-multi-repo`:
 - [ ] `.planning/config.json` has a `sub_repos` array with at least two entries
 - [ ] All `path` values resolve to actual directories on disk
 - [ ] Each repo has its own `.git` directory (they are separate repos, not subtrees)

package/src/skills/regression-prediction/SKILL.md

@@ -6,7 +6,7 @@ origin: FlowDeck
 
 # Regression Prediction
 
-Before merging, predict what is most likely to break. Run `/regression-predict` with a description of the change and the files affected.
+Before merging, predict what is most likely to break. Activate this skill by providing the change description and affected files to the agent.
 
 ## Regression Categories
 

package/src/skills/repo-memory-graph/SKILL.md

@@ -19,7 +19,7 @@ The Repo Memory Graph is FlowDeck's long-term knowledge store about this specifi
 ## When to Update
 
 Update the graph:
-- After running `/map-codebase`
+- After running `/fd-map-codebase`
 - When onboarding a new module
 - When a bug fix reveals a recurring pattern (add to `bug_history`)
 - When a refactor changes module ownership

package/src/skills/test-gap-detector/SKILL.md

@@ -6,7 +6,7 @@ origin: FlowDeck
 
 # Test Gap Detector
 
-Run `/test-gap` before implementing a feature or fix. Get back a ranked list of coverage gaps and the minimum viable tests to close them.
+Activate this skill before implementing a feature or fix. Get back a ranked list of coverage gaps and the minimum viable tests to close them.
 
 ## Gap Categories
 

package/src/skills/volatility-map/SKILL.md

@@ -6,7 +6,7 @@ origin: FlowDeck
 
 # Codebase Volatility Map
 
-Run `/volatility-map` to generate a heatmap of the most unstable parts of the codebase. Results are stored in `.codebase/VOLATILITY.json` for use by other FlowDeck features.
+Activate this skill to generate a heatmap of the most unstable parts of the codebase. Results are stored in `.codebase/VOLATILITY.json` for use by other FlowDeck features.
 
 ## Stability Levels