@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.
- package/README.md +13 -122
- package/dist/agents/code-explorer.d.ts.map +1 -1
- package/dist/agents/mapper.d.ts.map +1 -1
- package/dist/agents/orchestrator.d.ts.map +1 -1
- package/dist/agents/planner.d.ts.map +1 -1
- package/dist/agents/specialist.d.ts.map +1 -1
- package/dist/dashboard/server.mjs +12 -2
- package/dist/hooks/compaction-hook.d.ts.map +1 -1
- package/dist/hooks/file-tracker.d.ts +6 -0
- package/dist/hooks/file-tracker.d.ts.map +1 -1
- package/dist/hooks/notifications.d.ts.map +1 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +752 -785
- package/dist/lib/completion-validator.d.ts +51 -0
- package/dist/lib/completion-validator.d.ts.map +1 -0
- package/dist/lib/recommended-question.d.ts +24 -0
- package/dist/lib/recommended-question.d.ts.map +1 -0
- package/dist/lib/research-gate.d.ts +97 -0
- package/dist/lib/research-gate.d.ts.map +1 -0
- package/dist/lib/research-gate.test.d.ts +2 -0
- package/dist/lib/research-gate.test.d.ts.map +1 -0
- package/dist/mcp/index.d.ts +14 -3
- package/dist/mcp/index.d.ts.map +1 -1
- package/dist/services/codegraph.d.ts +36 -0
- package/dist/services/codegraph.d.ts.map +1 -0
- package/dist/services/codegraph.test.d.ts +2 -0
- package/dist/services/codegraph.test.d.ts.map +1 -0
- package/dist/services/command-validator.d.ts +11 -0
- package/dist/services/command-validator.d.ts.map +1 -1
- package/dist/services/preflight-explorer.d.ts +130 -0
- package/dist/services/preflight-explorer.d.ts.map +1 -0
- package/dist/services/preflight-explorer.test.d.ts +25 -0
- package/dist/services/preflight-explorer.test.d.ts.map +1 -0
- package/dist/services/question-guard.d.ts +96 -0
- package/dist/services/question-guard.d.ts.map +1 -0
- package/dist/services/quick-router.d.ts +40 -1
- package/dist/services/quick-router.d.ts.map +1 -1
- package/dist/services/recommended-question.test.d.ts +2 -0
- package/dist/services/recommended-question.test.d.ts.map +1 -0
- package/dist/services/supervisor-binding.d.ts +3 -1
- package/dist/services/supervisor-binding.d.ts.map +1 -1
- package/dist/tools/codebase-index.d.ts +30 -0
- package/dist/tools/codebase-index.d.ts.map +1 -0
- package/dist/tools/codebase-index.test.d.ts +2 -0
- package/dist/tools/codebase-index.test.d.ts.map +1 -0
- package/dist/tools/codegraph-tool.d.ts +3 -0
- package/dist/tools/codegraph-tool.d.ts.map +1 -0
- package/dist/tools/planning-state-lib.d.ts +23 -0
- package/dist/tools/planning-state-lib.d.ts.map +1 -1
- package/docs/agents/index.md +154 -0
- package/docs/commands/fd-ask.md +71 -39
- package/docs/commands/fd-checkpoint.md +63 -8
- package/docs/commands/fd-deploy-check.md +166 -9
- package/docs/commands/fd-design.md +101 -0
- package/docs/commands/fd-discuss.md +87 -20
- package/docs/commands/fd-doctor.md +100 -13
- package/docs/commands/fd-done.md +215 -0
- package/docs/commands/fd-execute.md +104 -0
- package/docs/commands/fd-fix-bug.md +144 -24
- package/docs/commands/fd-map-codebase.md +85 -21
- package/docs/commands/fd-multi-repo.md +155 -40
- package/docs/commands/fd-new-feature.md +63 -19
- package/docs/commands/fd-plan.md +80 -27
- package/docs/commands/fd-quick.md +143 -29
- package/docs/commands/fd-reflect.md +81 -13
- package/docs/commands/fd-resume.md +65 -8
- package/docs/commands/fd-status.md +80 -12
- package/docs/commands/fd-suggest.md +114 -0
- package/docs/commands/fd-translate-intent.md +69 -9
- package/docs/commands/fd-verify.md +71 -14
- package/docs/commands/fd-write-docs.md +121 -8
- package/docs/concepts/architecture.md +163 -0
- package/docs/concepts/governance.md +242 -0
- package/docs/concepts/intelligence.md +145 -0
- package/docs/concepts/multi-repo.md +227 -0
- package/docs/concepts/workflows.md +205 -0
- package/docs/configuration/index.md +208 -0
- package/docs/configuration/opencode-settings.md +98 -0
- package/docs/getting-started/first-project.md +126 -0
- package/docs/getting-started/installation.md +73 -0
- package/docs/getting-started/quick-start.md +74 -0
- package/docs/index.md +36 -72
- package/docs/reference/hooks.md +176 -0
- package/docs/reference/rules.md +109 -0
- package/docs/skills/code-review.md +47 -0
- package/docs/skills/index.md +148 -0
- package/docs/skills/planning.md +39 -0
- package/package.json +1 -1
- package/src/commands/fd-deploy-check.md +2 -2
- package/src/commands/fd-discuss.md +128 -7
- package/src/commands/fd-done.md +196 -0
- package/src/commands/fd-execute.md +43 -6
- package/src/commands/fd-fix-bug.md +43 -6
- package/src/commands/fd-map-codebase.md +100 -20
- package/src/commands/fd-multi-repo.md +1 -1
- package/src/commands/fd-new-feature.md +14 -5
- package/src/commands/fd-plan.md +38 -1
- package/src/commands/fd-quick.md +77 -14
- package/src/commands/fd-resume.md +1 -1
- package/src/commands/fd-status.md +1 -1
- package/src/commands/fd-verify.md +16 -2
- package/src/commands/fd-write-docs.md +30 -5
- package/src/rules/common/behavioral.md +63 -0
- package/src/skills/codebase-mapping/SKILL.md +1 -1
- package/src/skills/context-load/SKILL.md +1 -1
- package/src/skills/multi-repo/SKILL.md +1 -1
- package/src/skills/repo-memory-graph/SKILL.md +1 -1
- package/dist/hooks/memory-hook.d.ts +0 -28
- package/dist/hooks/memory-hook.d.ts.map +0 -1
- package/dist/services/memory-store.d.ts +0 -73
- package/dist/services/memory-store.d.ts.map +0 -1
- package/dist/services/memory-store.test.d.ts +0 -2
- package/dist/services/memory-store.test.d.ts.map +0 -1
- package/dist/tools/memory-search.d.ts +0 -3
- package/dist/tools/memory-search.d.ts.map +0 -1
- package/dist/tools/memory-status.d.ts +0 -3
- package/dist/tools/memory-status.d.ts.map +0 -1
- package/docs/USER_GUIDE.md +0 -20
- package/docs/agents.md +0 -544
- package/docs/best-practices.md +0 -47
- package/docs/commands/fd-new-project.md +0 -24
- package/docs/commands.md +0 -557
- package/docs/configuration.md +0 -325
- package/docs/design-first-workflow.md +0 -94
- package/docs/feature-integration-architecture.md +0 -227
- package/docs/installation.md +0 -123
- package/docs/intelligence.md +0 -370
- package/docs/memory.md +0 -69
- package/docs/multi-repo.md +0 -201
- package/docs/notifications.md +0 -170
- package/docs/optimization-baseline.md +0 -21
- package/docs/quick-start.md +0 -197
- package/docs/rules.md +0 -432
- package/docs/skills.md +0 -417
- package/docs/workflows.md +0 -134
- package/src/commands/fd-new-project.md +0 -114
package/src/commands/fd-quick.md
CHANGED
|
@@ -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
|
-
-
|
|
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
|
|
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
|
-
-
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
|
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`
|
|
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
|
|
76
|
-
|
|
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 (
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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:
|
|
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
|
|
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
|
|
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
|
-
|
|
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-
|
|
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 +0,0 @@
|
|
|
1
|
-
{"version":3,"file":"memory-store.test.d.ts","sourceRoot":"","sources":["../../src/services/memory-store.test.ts"],"names":[],"mappings":""}
|
|
@@ -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 +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"}
|
package/docs/USER_GUIDE.md
DELETED
|
@@ -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) |
|