@dv.nghiem/flowdeck 0.3.8 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (136) hide show
  1. package/README.md +13 -122
  2. package/dist/agents/code-explorer.d.ts.map +1 -1
  3. package/dist/agents/mapper.d.ts.map +1 -1
  4. package/dist/agents/orchestrator.d.ts.map +1 -1
  5. package/dist/agents/planner.d.ts.map +1 -1
  6. package/dist/agents/specialist.d.ts.map +1 -1
  7. package/dist/dashboard/server.mjs +12 -2
  8. package/dist/hooks/compaction-hook.d.ts.map +1 -1
  9. package/dist/hooks/file-tracker.d.ts +6 -0
  10. package/dist/hooks/file-tracker.d.ts.map +1 -1
  11. package/dist/hooks/notifications.d.ts.map +1 -1
  12. package/dist/index.d.ts.map +1 -1
  13. package/dist/index.js +752 -785
  14. package/dist/lib/completion-validator.d.ts +51 -0
  15. package/dist/lib/completion-validator.d.ts.map +1 -0
  16. package/dist/lib/recommended-question.d.ts +24 -0
  17. package/dist/lib/recommended-question.d.ts.map +1 -0
  18. package/dist/lib/research-gate.d.ts +97 -0
  19. package/dist/lib/research-gate.d.ts.map +1 -0
  20. package/dist/lib/research-gate.test.d.ts +2 -0
  21. package/dist/lib/research-gate.test.d.ts.map +1 -0
  22. package/dist/mcp/index.d.ts +14 -3
  23. package/dist/mcp/index.d.ts.map +1 -1
  24. package/dist/services/codegraph.d.ts +36 -0
  25. package/dist/services/codegraph.d.ts.map +1 -0
  26. package/dist/services/codegraph.test.d.ts +2 -0
  27. package/dist/services/codegraph.test.d.ts.map +1 -0
  28. package/dist/services/command-validator.d.ts +11 -0
  29. package/dist/services/command-validator.d.ts.map +1 -1
  30. package/dist/services/preflight-explorer.d.ts +130 -0
  31. package/dist/services/preflight-explorer.d.ts.map +1 -0
  32. package/dist/services/preflight-explorer.test.d.ts +25 -0
  33. package/dist/services/preflight-explorer.test.d.ts.map +1 -0
  34. package/dist/services/question-guard.d.ts +96 -0
  35. package/dist/services/question-guard.d.ts.map +1 -0
  36. package/dist/services/quick-router.d.ts +40 -1
  37. package/dist/services/quick-router.d.ts.map +1 -1
  38. package/dist/services/recommended-question.test.d.ts +2 -0
  39. package/dist/services/recommended-question.test.d.ts.map +1 -0
  40. package/dist/services/supervisor-binding.d.ts +3 -1
  41. package/dist/services/supervisor-binding.d.ts.map +1 -1
  42. package/dist/tools/codebase-index.d.ts +30 -0
  43. package/dist/tools/codebase-index.d.ts.map +1 -0
  44. package/dist/tools/codebase-index.test.d.ts +2 -0
  45. package/dist/tools/codebase-index.test.d.ts.map +1 -0
  46. package/dist/tools/codegraph-tool.d.ts +3 -0
  47. package/dist/tools/codegraph-tool.d.ts.map +1 -0
  48. package/dist/tools/planning-state-lib.d.ts +23 -0
  49. package/dist/tools/planning-state-lib.d.ts.map +1 -1
  50. package/docs/agents/index.md +154 -0
  51. package/docs/commands/fd-ask.md +71 -39
  52. package/docs/commands/fd-checkpoint.md +63 -8
  53. package/docs/commands/fd-deploy-check.md +166 -9
  54. package/docs/commands/fd-design.md +101 -0
  55. package/docs/commands/fd-discuss.md +87 -20
  56. package/docs/commands/fd-doctor.md +100 -13
  57. package/docs/commands/fd-done.md +215 -0
  58. package/docs/commands/fd-execute.md +104 -0
  59. package/docs/commands/fd-fix-bug.md +144 -24
  60. package/docs/commands/fd-map-codebase.md +85 -21
  61. package/docs/commands/fd-multi-repo.md +155 -40
  62. package/docs/commands/fd-new-feature.md +63 -19
  63. package/docs/commands/fd-plan.md +80 -27
  64. package/docs/commands/fd-quick.md +143 -29
  65. package/docs/commands/fd-reflect.md +81 -13
  66. package/docs/commands/fd-resume.md +65 -8
  67. package/docs/commands/fd-status.md +80 -12
  68. package/docs/commands/fd-suggest.md +114 -0
  69. package/docs/commands/fd-translate-intent.md +69 -9
  70. package/docs/commands/fd-verify.md +71 -14
  71. package/docs/commands/fd-write-docs.md +121 -8
  72. package/docs/concepts/architecture.md +163 -0
  73. package/docs/concepts/governance.md +242 -0
  74. package/docs/concepts/intelligence.md +145 -0
  75. package/docs/concepts/multi-repo.md +227 -0
  76. package/docs/concepts/workflows.md +205 -0
  77. package/docs/configuration/index.md +208 -0
  78. package/docs/configuration/opencode-settings.md +98 -0
  79. package/docs/getting-started/first-project.md +126 -0
  80. package/docs/getting-started/installation.md +73 -0
  81. package/docs/getting-started/quick-start.md +74 -0
  82. package/docs/index.md +36 -72
  83. package/docs/reference/hooks.md +176 -0
  84. package/docs/reference/rules.md +109 -0
  85. package/docs/skills/code-review.md +47 -0
  86. package/docs/skills/index.md +148 -0
  87. package/docs/skills/planning.md +39 -0
  88. package/package.json +1 -1
  89. package/src/commands/fd-deploy-check.md +2 -2
  90. package/src/commands/fd-discuss.md +128 -7
  91. package/src/commands/fd-done.md +196 -0
  92. package/src/commands/fd-execute.md +43 -6
  93. package/src/commands/fd-fix-bug.md +43 -6
  94. package/src/commands/fd-map-codebase.md +100 -20
  95. package/src/commands/fd-multi-repo.md +1 -1
  96. package/src/commands/fd-new-feature.md +14 -5
  97. package/src/commands/fd-plan.md +38 -1
  98. package/src/commands/fd-quick.md +77 -14
  99. package/src/commands/fd-resume.md +1 -1
  100. package/src/commands/fd-status.md +1 -1
  101. package/src/commands/fd-verify.md +16 -2
  102. package/src/commands/fd-write-docs.md +30 -5
  103. package/src/rules/common/behavioral.md +63 -0
  104. package/src/skills/codebase-mapping/SKILL.md +1 -1
  105. package/src/skills/context-load/SKILL.md +1 -1
  106. package/src/skills/multi-repo/SKILL.md +1 -1
  107. package/src/skills/repo-memory-graph/SKILL.md +1 -1
  108. package/dist/hooks/memory-hook.d.ts +0 -28
  109. package/dist/hooks/memory-hook.d.ts.map +0 -1
  110. package/dist/services/memory-store.d.ts +0 -73
  111. package/dist/services/memory-store.d.ts.map +0 -1
  112. package/dist/services/memory-store.test.d.ts +0 -2
  113. package/dist/services/memory-store.test.d.ts.map +0 -1
  114. package/dist/tools/memory-search.d.ts +0 -3
  115. package/dist/tools/memory-search.d.ts.map +0 -1
  116. package/dist/tools/memory-status.d.ts +0 -3
  117. package/dist/tools/memory-status.d.ts.map +0 -1
  118. package/docs/USER_GUIDE.md +0 -20
  119. package/docs/agents.md +0 -544
  120. package/docs/best-practices.md +0 -47
  121. package/docs/commands/fd-new-project.md +0 -24
  122. package/docs/commands.md +0 -557
  123. package/docs/configuration.md +0 -325
  124. package/docs/design-first-workflow.md +0 -94
  125. package/docs/feature-integration-architecture.md +0 -227
  126. package/docs/installation.md +0 -123
  127. package/docs/intelligence.md +0 -370
  128. package/docs/memory.md +0 -69
  129. package/docs/multi-repo.md +0 -201
  130. package/docs/notifications.md +0 -170
  131. package/docs/optimization-baseline.md +0 -21
  132. package/docs/quick-start.md +0 -197
  133. package/docs/rules.md +0 -432
  134. package/docs/skills.md +0 -417
  135. package/docs/workflows.md +0 -134
  136. package/src/commands/fd-new-project.md +0 -114
@@ -6,9 +6,10 @@ argument-hint: [task description]
6
6
  # Quick — Autonomous Workflow Launcher
7
7
 
8
8
  Run the correct FlowDeck workflow automatically for any task. This command:
9
- - Classifies the task type
9
+ - Explores the codebase first before asking any questions
10
+ - Classifies the task type using both text signals and repo evidence
10
11
  - Selects the appropriate existing workflow and stage sequence
11
- - Routes all clarifying questions through `@supervisor`
12
+ - Routes all clarifying questions through `@supervisor` (only when evidence cannot answer)
12
13
  - Executes each stage in order using the existing registered commands
13
14
  - Stops only when blocked, awaiting approval, or fully verified
14
15
 
@@ -16,18 +17,72 @@ Run the correct FlowDeck workflow automatically for any task. This command:
16
17
 
17
18
  ---
18
19
 
20
+ ## Step 0: Autonomous Preflight Exploration
21
+
22
+ **Before asking the human anything**, explore the repository to build evidence.
23
+
24
+ Invoke `@code-explorer` to inspect the following in parallel:
25
+
26
+ 1. **Repository structure** — `.planning/STATE.md`, `.planning/PROJECT.md`, `AGENTS.md`
27
+ 2. **Available commands** — enumerate `src/commands/*.md` filenames
28
+ 3. **Available agents** — enumerate `src/agents/*.ts` filenames
29
+ 4. **Available skills** — enumerate `src/skills/` directory names
30
+ 5. **Workflow config** — read `flowdeck.json` if present (governance, models)
31
+ 6. **Tech stack** — read `package.json`, `go.mod`, `Cargo.toml`, `pyproject.toml`
32
+ 7. **Implementation patterns** — inspect `src/` top-level directories
33
+ 8. **Prior decisions** — check `.planning/phases/*/DISCUSS.md` files
34
+ 9. **Relevant files** — find source files matching keywords in `$ARGUMENTS`
35
+
36
+ Store the exploration snapshot in STATE.md under `quick_run.preflightExploration`:
37
+
38
+ ```yaml
39
+ quick_run:
40
+ preflightExploration:
41
+ exploredAt: <ISO timestamp>
42
+ techStack: [...]
43
+ availableCommands: [...]
44
+ availableSkills: [...]
45
+ implementationPatterns: [...]
46
+ evidenceCount: <N>
47
+ clarificationResolvedByEvidence: false
48
+ suppressedQuestions: []
49
+ ```
50
+
51
+ **This step is mandatory. Do not proceed to Step 1 until exploration is complete.**
52
+
53
+ ### Question suppression rule
54
+
55
+ After exploration, invoke the question guard before emitting any question:
56
+
57
+ > A question may only be forwarded to `@supervisor` if:
58
+ > 1. It cannot be answered by the exploration evidence
59
+ > 2. It has not already been asked in the current session
60
+ > 3. It is required to safely select the correct workflow
61
+
62
+ If the question can be answered from repo evidence, suppress it and log it in
63
+ `quick_run.suppressedQuestions`. Do not present it to the user.
64
+
65
+ ---
66
+
19
67
  ## Step 1: Pre-flight State Check
20
68
 
21
- 1. Check `.planning/STATE.md` exists — if not, error: "Run /fd-new-project first."
69
+ 1. Check `.planning/STATE.md` exists — if not, error: "No active feature. Run `/fd-map-codebase` then `/fd-new-feature` to start a feature."
22
70
  2. Read `.planning/STATE.md` to determine if a `quick_run` entry already exists for this session.
23
71
  - If `quick_run.outcome` is `running` or `blocked`: **resume from the last completed stage** (skip to Step 5).
24
- - Otherwise: proceed to Step 2.
72
+ - If `quick_run.preflightExploration` exists and `exploredAt` is recent (< 5 min): reuse it, skip Step 0.
73
+ - Otherwise: proceed to Step 0 then Step 2.
25
74
 
26
75
  ---
27
76
 
28
77
  ## Step 2: Classify the Task
29
78
 
30
- Parse `$ARGUMENTS` using the signal table below to determine task type and required stage sequence.
79
+ Use **both** text-signal matching and preflight exploration evidence:
80
+
81
+ Call `classifyTaskWithContext(description, explorationResult)` from `quick-router.ts`.
82
+
83
+ This resolves ambiguous descriptions using repo evidence before flagging
84
+ `clarificationNeeded`. Most short descriptions that would normally prompt a
85
+ question are resolved by evidence (e.g., tech stack, existing patterns, prior decisions).
31
86
 
32
87
  ### Signal Classification Table
33
88
 
@@ -38,7 +93,7 @@ Parse `$ARGUMENTS` using the signal table below to determine task type and requi
38
93
  | **docs** | docs, documentation, readme, api docs, usage guide, write docs, document, changelog, tutorial, docstring | `discuss → write-docs → verify` |
39
94
  | **simple** | rename, move file, minor, typo, update constant, update config, bump version, one-liner | `execute → verify` |
40
95
  | **feature** | (substantive description, 8+ words, no above signals) | `discuss → plan → execute → verify` |
41
- | **ambiguous** | (short, vague, or unclear input) | *(clarify first — see Step 3)* |
96
+ | **ambiguous** | (short, vague, or unclear — only after exploration cannot resolve) | *(clarify via supervisor — see Step 3)* |
42
97
 
43
98
  ### Classification Rules
44
99
 
@@ -47,7 +102,7 @@ Parse `$ARGUMENTS` using the signal table below to determine task type and requi
47
102
  3. **Docs signals**: if "docs", "documentation", "readme", or "write docs" is present without implementation signals, classify as `docs`.
48
103
  4. **Simple**: if "rename", "typo", "minor", or "move file" is present and description is a single, scoped operation.
49
104
  5. **Feature**: substantive description (8+ words) with no specific signal type.
50
- 6. **Ambiguous**: description is too short (<5 words) or matches a bare imperative with no object (e.g., "improve", "add", "make it better").
105
+ 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.
51
106
 
52
107
  Record the classification result:
53
108
  ```yaml
@@ -66,21 +121,25 @@ quick_run:
66
121
 
67
122
  ---
68
123
 
69
- ## Step 3: Supervisor-Gated Clarification (when needed)
124
+ ## Step 3: Supervisor-Gated Clarification (only when exploration cannot resolve)
70
125
 
71
126
  **Only proceed to Step 4 when classification confidence is sufficient.**
72
127
 
73
- If classification is `ambiguous` OR confidence is low (description < 5 words or no clear signal):
128
+ If classification is `ambiguous` AND exploration evidence did not resolve it:
74
129
 
75
- 1. Invoke `@supervisor` (preflight review of `fd-quick` command) with the partial task description.
76
- 2. Present the supervisor's single clarifying question to the user. **Ask ONE question only.**
130
+ 1. Invoke `@supervisor` (preflight review of `fd-quick` command) with:
131
+ - The partial task description
132
+ - The preflight exploration snapshot (tech stack, patterns, prior decisions)
133
+ - The `clarificationPrompt` from the classification (already enriched with context)
134
+ 2. `@supervisor` presents the single clarifying question to the user. **Ask ONE question only.**
77
135
  3. Wait for the user's answer.
78
136
  4. Re-classify using the combined original description + the user's answer.
79
137
  5. If confidence is still low after one clarification round, route to `feature` with a note in STATE.md.
80
138
 
81
139
  **All clarification goes through `@supervisor`. Do not have specialist agents ask questions directly.**
140
+ **Do not ask questions that can be answered from the exploration evidence.**
82
141
 
83
- Example supervisor clarification questions (the supervisor selects the most relevant):
142
+ Example supervisor clarification questions (only when evidence is absent):
84
143
  - "Is this a new feature, a bug fix, or a documentation task?"
85
144
  - "Does this involve building or changing a user-facing UI (page, dashboard, component)?"
86
145
  - "Can you describe the specific bug — what is the expected vs actual behavior?"
@@ -97,6 +156,7 @@ Task classified as: <task type>
97
156
  Stage sequence: <stage-1> → <stage-2> → ... → <stage-N>
98
157
  Requires design: <yes / no>
99
158
  Requires TDD: <yes / no>
159
+ Evidence used: <N> items from preflight exploration
100
160
 
101
161
  Running /fd-quick autonomously. I will proceed through each stage and pause only
102
162
  if I need approval, encounter a blocker, or complete the full sequence.
@@ -134,13 +194,15 @@ Before executing the stage, invoke `@supervisor` (preflight) on the stage's comm
134
194
 
135
195
  ### 5c. Execute the Stage
136
196
 
137
- Execute the stage using its existing command with full context:
197
+ Execute the stage using its existing command with full context from the preflight
198
+ exploration snapshot (available in `quick_run.preflightExploration`). Pass it to
199
+ each stage so worker agents can use evidence directly.
138
200
 
139
201
  **Stage → Command Mapping:**
140
202
 
141
203
  | Stage | Command | Key Behavior |
142
204
  |-------|---------|--------------|
143
- | `discuss` | `/fd-discuss` | Runs `@discusser` structured Q&A. Saves `DISCUSS.md`. One question at a time. |
205
+ | `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. |
144
206
  | `design` | `/fd-design --mode=draft` | Runs design-first pipeline. Required for `ui-feature` tasks. Produces design artifact + approval. |
145
207
  | `plan` | `/fd-plan` | Creates `PLAN.md` from `DISCUSS.md` decisions. **Pauses for user CONFIRM before saving.** |
146
208
  | `execute` | `/fd-execute` | TDD pipeline: BEHAVIOR → RED → GREEN → REFACTOR per step. Delegates to appropriate coder agents. |
@@ -194,6 +256,7 @@ When all stages complete:
194
256
  Task: $ARGUMENTS
195
257
  Workflow: <stage-1> → ... → <stage-N>
196
258
  Outcome: ✅ COMPLETE
259
+ Evidence: <N> preflight items used (0 human questions asked before exploration)
197
260
  ────────────────────────────────────────────────
198
261
  Verify result: /fd-verify
199
262
  Save state: /fd-checkpoint
@@ -11,7 +11,7 @@ Resume a previously interrupted FlowDeck session.
11
11
 
12
12
  ## Steps
13
13
 
14
- 1. Check `.planning/STATE.md` exists — if not, error: "No active project. Run /fd-new-project first."
14
+ 1. Check `.planning/STATE.md` exists — if not, error: "No active feature. Run `/fd-map-codebase` then `/fd-new-feature` to start a feature."
15
15
 
16
16
  2. Read STATE.md and parse current state:
17
17
  - Phase, status, last_updated, plan_confirmed
@@ -80,5 +80,5 @@ Steps:
80
80
 
81
81
  ## Error Handling
82
82
 
83
- - If `.planning/STATE.md` not found: "No active project. Run /fd-new-project first."
83
+ - If `.planning/STATE.md` not found: "No active feature. Run `/fd-map-codebase` then `/fd-new-feature` to start a feature."
84
84
  - If `--phase` requested but phase directory doesn't exist: "Phase N not found."
@@ -11,7 +11,7 @@ Run the full verification pipeline for the current feature: tests, code review,
11
11
 
12
12
  ## Pre-flight
13
13
 
14
- 1. Check `.planning/STATE.md` exists — if not, error: "Run /fd-new-project first."
14
+ 1. Check `.planning/STATE.md` exists — if not, error: "No active feature. Run `/fd-map-codebase` then `/fd-new-feature` to start a feature."
15
15
  2. Read current phase N from STATE.md.
16
16
  3. Confirm `steps_complete` in STATE.md is non-empty — if empty, warn: "No steps completed yet. Run /fd-execute first."
17
17
 
@@ -26,6 +26,19 @@ git diff --name-only HEAD
26
26
 
27
27
  If no changed files, use all files in the current phase directory as scope.
28
28
 
29
+ **CodeGraph Impact Check (when available):**
30
+
31
+ ```
32
+ codegraph action=check
33
+ ```
34
+
35
+ If codegraph is installed and indexed:
36
+ - Use `codegraph_impact` on each changed file to surface any dependent modules not caught by `git diff`
37
+ - Log: "codegraph impact analysis: [N] dependent symbols detected"
38
+ - Expand review scope to include impacted modules flagged by codegraph
39
+
40
+ This ensures verification covers caller/callee relationships, not just directly-changed files.
41
+
29
42
  ### Step 2: Run Checks in Parallel
30
43
 
31
44
  Launch all four checks simultaneously:
@@ -122,7 +135,7 @@ verified_at: "<timestamp>"
122
135
 
123
136
  ## Error Handling
124
137
 
125
- - If `.planning/` not found: error "Run /fd-new-project first."
138
+ - If `.planning/` not found: error "No active feature. Run `/fd-map-codebase` then `/fd-new-feature` to start a feature."
126
139
  - If STATE.md not found: error "Project not initialized."
127
140
  - If test runner not found: error with remediation (e.g., "No test script in package.json")
128
141
  - No partial state update on error.
@@ -130,3 +143,4 @@ verified_at: "<timestamp>"
130
143
  ## Completion
131
144
 
132
145
  Report: verification result, check statuses, any required fixes, and suggested next step.
146
+ Next step: run `/fd-done` or `/fd-fix-bug`.
@@ -14,7 +14,30 @@ Default: all formats
14
14
 
15
15
  ## Process
16
16
 
17
- ### Step 1: Explore APIs
17
+ ### Step 1: CodeGraph Intelligence Check
18
+
19
+ Before any file exploration, check if codegraph provides a pre-built symbol index:
20
+
21
+ ```
22
+ codegraph action=check
23
+ ```
24
+
25
+ - **If codegraph indexed (fresh)**: Use `codegraph_search`, `codegraph_explore`, `codegraph_node` to enumerate exported symbols and API entry points. This is faster and more complete than grep.
26
+ - Log: "codegraph available — using symbol index for API discovery"
27
+ - **If codegraph absent or stale**: Fall through to @mapper-based exploration
28
+
29
+ ### Step 2: Explore APIs
30
+
31
+ **If codegraph is available:**
32
+
33
+ Use codegraph MCP tools to find all exported symbols:
34
+ ```
35
+ codegraph_search("export ") # exported symbols
36
+ codegraph_explore("<scope or src/>") # survey module structure
37
+ codegraph_context("<key entry points>") # full context per area
38
+ ```
39
+
40
+ **If codegraph is not available:**
18
41
 
19
42
  Spawn `@mapper` to:
20
43
  - Find all exported functions, classes, and types
@@ -28,7 +51,7 @@ grep -rn "export " src/ --include="*.ts"
28
51
  grep -rn "export interface\|export type\|export class" src/ --include="*.ts"
29
52
  ```
30
53
 
31
- ### Step 2: Draft Documentation
54
+ ### Step 3: Draft Documentation
32
55
 
33
56
  Spawn `@writer` to produce:
34
57
 
@@ -57,7 +80,7 @@ const result = functionName(value);
57
80
  **Troubleshooting**
58
81
  - Common errors and their solutions
59
82
 
60
- ### Step 3: Review for Accuracy
83
+ ### Step 4: Review for Accuracy
61
84
 
62
85
  Spawn `@reviewer` to verify:
63
86
  - Every documented function/method actually exists
@@ -65,7 +88,9 @@ Spawn `@reviewer` to verify:
65
88
  - Examples are syntactically correct
66
89
  - No outdated API references
67
90
 
68
- ### Step 4: Finalize
91
+ If codegraph is available: use `codegraph_node` to verify specific function signatures against documentation.
92
+
93
+ ### Step 5: Finalize
69
94
 
70
95
  Writer incorporates feedback and writes final docs to:
71
96
  - `README.md` — project overview and quick start
@@ -79,4 +104,4 @@ Updated documentation files with:
79
104
  - Working code examples
80
105
  - Clear explanations of behavior
81
106
 
82
- Report: files written/updated, public APIs documented, any gaps found.
107
+ Report: files written/updated, public APIs documented, any gaps found, codegraph used ✅/❌.
@@ -0,0 +1,63 @@
1
+ Behavioral guidelines to reduce common LLM coding mistakes. Merge with project-specific instructions as needed.
2
+
3
+ **Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.
4
+
5
+ ## 1. Think Before Coding
6
+
7
+ **Don't assume. Don't hide confusion. Surface tradeoffs.**
8
+
9
+ Before implementing:
10
+ - State your assumptions explicitly. If uncertain, ask.
11
+ - If multiple interpretations exist, present them - don't pick silently.
12
+ - If a simpler approach exists, say so. Push back when warranted.
13
+ - If something is unclear, stop. Name what's confusing. Ask.
14
+
15
+ ## 2. Simplicity First
16
+
17
+ **Minimum code that solves the problem. Nothing speculative.**
18
+
19
+ - No features beyond what was asked.
20
+ - No abstractions for single-use code.
21
+ - No "flexibility" or "configurability" that wasn't requested.
22
+ - No error handling for impossible scenarios.
23
+ - If you write 200 lines and it could be 50, rewrite it.
24
+
25
+ Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
26
+
27
+ ## 3. Surgical Changes
28
+
29
+ **Touch only what you must. Clean up only your own mess.**
30
+
31
+ When editing existing code:
32
+ - Don't "improve" adjacent code, comments, or formatting.
33
+ - Don't refactor things that aren't broken.
34
+ - Match existing style, even if you'd do it differently.
35
+ - If you notice unrelated dead code, mention it - don't delete it.
36
+
37
+ When your changes create orphans:
38
+ - Remove imports/variables/functions that YOUR changes made unused.
39
+ - Don't remove pre-existing dead code unless asked.
40
+
41
+ The test: Every changed line should trace directly to the user's request.
42
+
43
+ ## 4. Goal-Driven Execution
44
+
45
+ **Define success criteria. Loop until verified.**
46
+
47
+ Transform tasks into verifiable goals:
48
+ - "Add validation" → "Write tests for invalid inputs, then make them pass"
49
+ - "Fix the bug" → "Write a test that reproduces it, then make it pass"
50
+ - "Refactor X" → "Ensure tests pass before and after"
51
+
52
+ For multi-step tasks, state a brief plan:
53
+ ```
54
+ 1. [Step] → verify: [check]
55
+ 2. [Step] → verify: [check]
56
+ 3. [Step] → verify: [check]
57
+ ```
58
+
59
+ Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
60
+
61
+ ---
62
+
63
+ **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.
@@ -12,7 +12,7 @@ Produces structured documentation of a codebase that agents can read to answer "
12
12
 
13
13
  - Starting work on an unfamiliar codebase
14
14
  - Before a major feature that spans multiple modules
15
- - When `/map-codebase` command is invoked
15
+ - When `/fd-map-codebase` command is invoked
16
16
  - When `.codebase/` is missing or stale
17
17
 
18
18
  ## Output Files
@@ -60,4 +60,4 @@ After loading context, produce this briefing:
60
60
  **Key Conventions**: [2-3 most important patterns]
61
61
  ```
62
62
 
63
- If any file is missing, note it: "STATE.md not found — run `/fd-new-project` to initialize."
63
+ If any file is missing, note it: "STATE.md not found — run `/fd-map-codebase` then `/fd-new-feature` to initialize."
@@ -180,7 +180,7 @@ Conflicts must be resolved before any CHANGE PLAN is executed. The `@multi-repo-
180
180
 
181
181
  ## Independence Check Before Executing
182
182
 
183
- Before running `/multi-repo`:
183
+ Before running `/fd-multi-repo`:
184
184
  - [ ] `.planning/config.json` has a `sub_repos` array with at least two entries
185
185
  - [ ] All `path` values resolve to actual directories on disk
186
186
  - [ ] Each repo has its own `.git` directory (they are separate repos, not subtrees)
@@ -19,7 +19,7 @@ The Repo Memory Graph is FlowDeck's long-term knowledge store about this specifi
19
19
  ## When to Update
20
20
 
21
21
  Update the graph:
22
- - After running `/map-codebase`
22
+ - After running `/fd-map-codebase`
23
23
  - When onboarding a new module
24
24
  - When a bug fix reveals a recurring pattern (add to `bug_history`)
25
25
  - When a refactor changes module ownership
@@ -1,28 +0,0 @@
1
- import { type Session } from "../services/memory-store";
2
- export declare function onSessionCreated(directory: string, contentSessionId: string, prompt?: string): Session;
3
- export declare function onToolExecuted(contentSessionId: string, toolName: string, toolInput: Record<string, unknown>, toolResponse: string | null, directory: string): void;
4
- export declare function onMessageUpdated(contentSessionId: string, role: string, content: string, directory: string): void;
5
- /**
6
- * Called when OpenCode compacts a session (session.compacted event).
7
- *
8
- * Previously this silently dropped the summary if the session was not in
9
- * activeSessions (e.g. after plugin reload or cross-process sessions). Now it
10
- * falls back to a DB lookup so the summary is never lost.
11
- */
12
- export declare function onSessionCompact(contentSessionId: string, summary: string): void;
13
- export declare function onSessionEnd(contentSessionId: string, lastMessage?: string): void;
14
- export declare function getSessionContext(directory: string, contentSessionId: string): {
15
- context: string;
16
- previousSessions: Session[];
17
- };
18
- export declare function clearSession(contentSessionId: string): void;
19
- export declare const memoryHook: {
20
- onSessionCreated: typeof onSessionCreated;
21
- onToolExecuted: typeof onToolExecuted;
22
- onMessageUpdated: typeof onMessageUpdated;
23
- onSessionCompact: typeof onSessionCompact;
24
- onSessionEnd: typeof onSessionEnd;
25
- getSessionContext: typeof getSessionContext;
26
- clearSession: typeof clearSession;
27
- };
28
- //# sourceMappingURL=memory-hook.d.ts.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"memory-hook.d.ts","sourceRoot":"","sources":["../../src/hooks/memory-hook.ts"],"names":[],"mappings":"AAAA,OAAO,EAQL,KAAK,OAAO,EAGb,MAAM,0BAA0B,CAAA;AAgGjC,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAYtG;AAED,wBAAgB,cAAc,CAC5B,gBAAgB,EAAE,MAAM,EACxB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClC,YAAY,EAAE,MAAM,GAAG,IAAI,EAC3B,SAAS,EAAE,MAAM,GAChB,IAAI,CA4BN;AAED,wBAAgB,gBAAgB,CAC9B,gBAAgB,EAAE,MAAM,EACxB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,GAChB,IAAI,CA6BN;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,gBAAgB,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CA+BhF;AAED,wBAAgB,YAAY,CAAC,gBAAgB,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CA2BjF;AAED,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,GAAG;IAC9E,OAAO,EAAE,MAAM,CAAA;IACf,gBAAgB,EAAE,OAAO,EAAE,CAAA;CAC5B,CAIA;AAED,wBAAgB,YAAY,CAAC,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAE3D;AAED,eAAO,MAAM,UAAU;;;;;;;;CAQtB,CAAA"}
@@ -1,73 +0,0 @@
1
- /**
2
- * Structured handoff artifact persisted alongside the text summary.
3
- * Derived from observations + LLM compaction output.
4
- */
5
- export interface HandoffMetadata {
6
- workflow_name: string | null;
7
- current_status: string;
8
- current_stage: string | null;
9
- completed_stages: string[];
10
- pending_stages: string[];
11
- key_decisions: string[];
12
- blockers: string[];
13
- important_files: string[];
14
- approvals: string[];
15
- open_questions: string[];
16
- next_steps: string[];
17
- tool_names_used: string[];
18
- observation_count: number;
19
- updated_at: string;
20
- }
21
- export interface Observation {
22
- id?: number;
23
- session_id: number;
24
- tool_name: string;
25
- tool_input: Record<string, unknown> | null;
26
- tool_response: string | null;
27
- directory: string;
28
- created_at?: string;
29
- }
30
- export interface Session {
31
- id?: number;
32
- content_session_id: string;
33
- project: string;
34
- directory: string;
35
- created_at?: string;
36
- last_active_at?: string;
37
- summary?: string | null;
38
- prompt_count?: number;
39
- }
40
- export interface Summary {
41
- id?: number;
42
- session_id: number;
43
- content: string;
44
- metadata?: HandoffMetadata | null;
45
- created_at?: string;
46
- }
47
- export interface SearchResult {
48
- observation: Observation;
49
- session: Session;
50
- }
51
- export declare function initSession(contentSessionId: string, project: string, directory: string): Session;
52
- export declare function storeObservation(sessionId: number, toolName: string, toolInput: unknown, toolResponse: string | null, directory: string): Observation;
53
- export declare function storeSummary(sessionId: number, content: string, metadata?: HandoffMetadata | null): Summary;
54
- export declare function getRecentSessions(directory: string, limit?: number): Session[];
55
- export declare function getObservationsForSession(sessionId: number): Observation[];
56
- export declare function getSessionSummary(sessionId: number): Summary | null;
57
- export declare function getSessionByContentSessionId(contentSessionId: string): Session | null;
58
- export declare function getRecentObservations(directory: string, limit?: number): SearchResult[];
59
- export declare function searchObservations(directory: string, query: string, limit?: number): SearchResult[];
60
- export declare function getContextForDirectory(directory: string, maxObservations?: number): string;
61
- export declare function closeDatabase(): void;
62
- /**
63
- * Returns current connection-level PRAGMA values.
64
- * Intended for diagnostics and tests — queries via the shared singleton so the
65
- * values reflect what this module actually set, not a second connection.
66
- */
67
- export declare function getDbSettings(): {
68
- journal_mode: string;
69
- busy_timeout: number;
70
- synchronous: number;
71
- wal_autocheckpoint: number;
72
- };
73
- //# sourceMappingURL=memory-store.d.ts.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"memory-store.d.ts","sourceRoot":"","sources":["../../src/services/memory-store.ts"],"names":[],"mappings":"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"}
@@ -1,2 +0,0 @@
1
- export {};
2
- //# sourceMappingURL=memory-store.test.d.ts.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"memory-store.test.d.ts","sourceRoot":"","sources":["../../src/services/memory-store.test.ts"],"names":[],"mappings":""}
@@ -1,3 +0,0 @@
1
- import { type ToolDefinition } from "@opencode-ai/plugin";
2
- export declare const memorySearchTool: ToolDefinition;
3
- //# sourceMappingURL=memory-search.d.ts.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"memory-search.d.ts","sourceRoot":"","sources":["../../src/tools/memory-search.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,KAAK,cAAc,EAAE,MAAM,qBAAqB,CAAA;AAQ/D,eAAO,MAAM,gBAAgB,EAAE,cAgF7B,CAAA"}
@@ -1,3 +0,0 @@
1
- import { type ToolDefinition } from "@opencode-ai/plugin";
2
- export declare const memoryStatusTool: ToolDefinition;
3
- //# sourceMappingURL=memory-status.d.ts.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"memory-status.d.ts","sourceRoot":"","sources":["../../src/tools/memory-status.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,KAAK,cAAc,EAAE,MAAM,qBAAqB,CAAA;AAU/D,eAAO,MAAM,gBAAgB,EAAE,cAkE7B,CAAA"}
@@ -1,20 +0,0 @@
1
- # FlowDeck User Guide
2
-
3
- > **This file is superseded by the modular documentation.**
4
- > See **[docs/index.md](./index.md)** for the full table of contents.
5
-
6
- ## Quick links
7
-
8
- | Topic | File |
9
- |-------|------|
10
- | Installation & setup | [installation.md](./installation.md) |
11
- | First 15 minutes | [quick-start.md](./quick-start.md) |
12
- | Configuration reference | [configuration.md](./configuration.md) |
13
- | All agents | [agents.md](./agents.md) |
14
- | All skills | [skills.md](./skills.md) |
15
- | All workflows | [workflows.md](./workflows.md) |
16
- | All commands | [commands.md](./commands.md) |
17
- | Language rules | [rules.md](./rules.md) |
18
- | Parallel execution | [parallel-execution.md](./parallel-execution.md) |
19
- | Multi-repo / microservices | [multi-repo.md](./fd-multi-repo.md) |
20
- | System notifications | [notifications.md](./notifications.md) |