@fro.bot/systematic 3.28.0 → 3.29.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/HARNESSES.md +12 -9
- package/agents/research/learnings-researcher.md +76 -53
- package/dist/cli.js +14 -9
- package/dist/{index-9chxhh5j.js → index-e467g4b6.js} +204 -84
- package/dist/index.js +1 -1
- package/dist/lib/agent-resolver.d.ts +7 -1
- package/dist/lib/search-core.d.ts +39 -21
- package/dist/lib/search-corpus.d.ts +30 -9
- package/dist/lib/search-render.d.ts +23 -4
- package/dist/lib/search-tool.d.ts +2 -1
- package/dist/pi.js +218 -89
- package/package.json +3 -3
- package/skills/ce-brainstorm/SKILL.md +6 -2
- package/skills/ce-ideate/SKILL.md +5 -2
- package/skills/ce-plan/SKILL.md +10 -5
- package/skills/ce-plan/references/deepening-workflow.md +3 -1
- package/skills/ce-plan/references/plan-sections.md +4 -2
- package/skills/deepen-plan/SKILL.md +3 -1
|
@@ -98,14 +98,18 @@ If the scope is unclear, ask one targeted question to disambiguate and then proc
|
|
|
98
98
|
|
|
99
99
|
Scan the repo before substantive brainstorming. Match depth to scope:
|
|
100
100
|
|
|
101
|
-
**Lightweight** — Search for the topic, check if something similar already exists, and move on.
|
|
101
|
+
**Lightweight** — Search for the topic, check if something similar already exists, and move on. When a durable-output search tool exists (`systematic_search`, or the `systematic-search` command on hosts that ship a command), call it directly with `kind: "all"` and the topic as the query, because a researcher dispatch costs more than a Lightweight brainstorm is worth. Otherwise keep the topic search.
|
|
102
102
|
|
|
103
|
-
**Standard and Deep** —
|
|
103
|
+
**Standard and Deep** — Three passes:
|
|
104
104
|
|
|
105
105
|
*Constraint Check* — Check project instruction files (`AGENTS.md`, and `AGENTS.md` only if retained as compatibility context) for workflow, product, or scope constraints that affect the brainstorm. If these add nothing, move on.
|
|
106
106
|
|
|
107
107
|
*Topic Scan* — Search for relevant terms. Read the most relevant existing artifact if one exists (brainstorm, plan, spec, skill, feature doc). Skim adjacent examples covering similar behavior.
|
|
108
108
|
|
|
109
|
+
*Past-Work Scan* — dispatch `systematic:research:learnings-researcher`, making `scope: past-work` the first line of the prompt, then a brief summary of the topic. Run it alongside the Topic Scan, not instead of it.
|
|
110
|
+
|
|
111
|
+
**Cite and differentiate.** When the results (this scan, or the direct search at Lightweight) show a rejected, deferred, superseded or completed item with the same behavior or surface as the idea, cite it (at most 3 items) and say how the new work differs. Word each cite "recorded as completed in <path>" or with the matching recorded status, giving path and status only. Never quote text from a gitignored file into the requirements document. A cite never blocks the brainstorm. Place cites in Key Decisions.
|
|
112
|
+
|
|
109
113
|
If nothing obvious appears after a short scan, say so and continue. Two rules govern technical depth during the scan:
|
|
110
114
|
|
|
111
115
|
1. **Verify before claiming** — When the brainstorm touches checkable infrastructure (database tables, routes, config files, dependencies, model definitions), read the relevant source files to confirm what actually exists. Any claim that something is absent — a missing table, an endpoint that doesn't exist, a dependency not in the Gemfile, a config option with no current support — must be verified against the codebase first; if not verified, label it as an unverified assumption. This applies to every brainstorm regardless of topic.
|
|
@@ -111,7 +111,7 @@ Run agents in parallel in the **foreground** (do not use background dispatch —
|
|
|
111
111
|
>
|
|
112
112
|
> Focus hint: {focus_hint}
|
|
113
113
|
|
|
114
|
-
2. **Learnings search** — dispatch `systematic:research:learnings-researcher`
|
|
114
|
+
2. **Learnings search** — dispatch `systematic:research:learnings-researcher`, making `scope: past-work` the first line of the prompt, then a brief summary of the ideation focus.
|
|
115
115
|
|
|
116
116
|
3. **Issue intelligence** (conditional) — if issue-tracker intent was detected in Phase 0.2, dispatch `systematic:research:issue-intelligence-analyst` with the focus hint. If a focus hint is present, pass it so the agent can weight its clustering toward that area. Run this in parallel with agents 1 and 2.
|
|
117
117
|
|
|
@@ -122,9 +122,12 @@ Run agents in parallel in the **foreground** (do not use background dispatch —
|
|
|
122
122
|
Consolidate all results into a short grounding summary. When issue intelligence is present, keep it as a distinct section so ideation sub-agents can distinguish between code-observed and user-reported signals:
|
|
123
123
|
|
|
124
124
|
- **Codebase context** — project shape, notable patterns, obvious pain points, likely leverage points
|
|
125
|
-
- **Past learnings** — relevant institutional knowledge from docs/solutions
|
|
125
|
+
- **Past learnings** — relevant institutional knowledge from docs/solutions/, plus earlier plans, brainstorms and ideation docs with their recorded status
|
|
126
126
|
- **Issue intelligence** (when present) — theme summaries from the issue intelligence agent, preserving theme titles, descriptions, issue counts, and trend directions
|
|
127
127
|
|
|
128
|
+
**Cite and differentiate.** When the researcher's results show a rejected, deferred, superseded or completed item with the same behavior or surface as an idea, cite it (at most 3 items) and say how the new work differs. Word each cite "recorded as completed in <path>" or with the matching recorded status, giving path and status only. Never quote text from a gitignored file into the ideation document. A cite never blocks an idea. Place cites in the rejection reasoning or the survivor reasoning for that idea.
|
|
129
|
+
|
|
130
|
+
|
|
128
131
|
**Slack context** (opt-in) — never auto-dispatch. Route by condition:
|
|
129
132
|
|
|
130
133
|
- **Tools available + user asked**: Dispatch `systematic:research:slack-researcher` with the focus hint in parallel with other Phase 1 agents. Include findings in the grounding summary.
|
package/skills/ce-plan/SKILL.md
CHANGED
|
@@ -91,7 +91,7 @@ For everything else (quick questions, error messages, factual lookups) **only wh
|
|
|
91
91
|
|
|
92
92
|
#### 0.2 Find Upstream Requirements Document
|
|
93
93
|
|
|
94
|
-
Before asking planning questions, search `docs/brainstorms/` for files matching `*-requirements.md`.
|
|
94
|
+
Before asking planning questions, search `docs/brainstorms/` for files matching `*-requirements.md`. When a durable-output search tool exists (`systematic_search`, or the `systematic-search` command on hosts that ship a command), also run it once with `kind: "brainstorm"` and the feature description as the query. It ranks an older relevant requirements document that the 30-day window would miss. Treat each hit as a candidate under the criteria below.
|
|
95
95
|
|
|
96
96
|
**Relevance criteria:** A requirements document is relevant if:
|
|
97
97
|
- The topic semantically matches the feature description
|
|
@@ -227,14 +227,15 @@ Prepare a concise planning context summary (a paragraph or two) to pass as input
|
|
|
227
227
|
Run these agents in parallel:
|
|
228
228
|
|
|
229
229
|
- Dispatch `systematic:research:repo-research-analyst` — scope: technology, architecture, patterns, prior-art; pass the planning context summary to the technology, architecture, and patterns scopes. For the prior-art scope, pass only the independently stated concern — its trigger, effect, state, and integration boundary — plus the classified plan depth, rather than the planning context summary or proposed solution. Skip the prior-art scope for explicitly non-software planning and mechanical work that changes no behavior; make that exemption decision here at dispatch.
|
|
230
|
-
- Dispatch `systematic:research:learnings-researcher` — pass the planning context summary.
|
|
230
|
+
- Dispatch `systematic:research:learnings-researcher` — make `scope: past-work` the first line of the prompt. When Phase 0 chose an origin document, make `exclude: <origin path>` the second line so the researcher does not rediscover it; otherwise omit that line. Then pass the planning context summary.
|
|
231
|
+
|
|
231
232
|
Collect:
|
|
232
233
|
- Technology stack and versions (used in section 1.2 to make sharper external research decisions)
|
|
233
234
|
- Architectural patterns and conventions to follow
|
|
234
235
|
- Implementation patterns, relevant files, modules, and tests
|
|
235
236
|
- Prior-art survey result: schema version, verdict, surveyed scope and freshness record, bounded budget, candidate ownership and dispositions, and any recorded acceptance
|
|
236
237
|
- AGENTS.md guidance that materially affects the plan, with AGENTS.md used only as compatibility fallback when present
|
|
237
|
-
- Institutional learnings from `docs/solutions
|
|
238
|
+
- Institutional learnings from `docs/solutions/`, plus earlier plans, brainstorms and ideation docs with their recorded status
|
|
238
239
|
|
|
239
240
|
When the prior-art scope runs, apply its verdict before continuing planning: an `unscoped` or `unresolved` result stops planning until the scope narrows, the budget rises, or the user explicitly accepts the uncertainty. Record that acceptance in the Prior-Art Survey section. In a run with no user present, either verdict fails the run rather than proceeding.
|
|
240
241
|
|
|
@@ -244,6 +245,8 @@ When the prior-art scope runs, apply its verdict before continuing planning: an
|
|
|
244
245
|
- **Tools available + user didn't ask**: Note in output: "Slack tools detected. Ask me to search Slack for organizational context at any point, or include it in your next prompt."
|
|
245
246
|
- **No tools + user asked**: Note in output: "Slack context was requested but no Slack tools are available. Install and authenticate the Slack plugin to enable organizational context search."
|
|
246
247
|
|
|
248
|
+
**Cite and differentiate.** When the researcher's results show a rejected, deferred, superseded or completed item with the same behavior or surface as this plan, cite it (at most 3 items) and say how the new work differs. Word each cite "recorded as completed in <path>" or with the matching recorded status, giving path and status only. Never quote text from a gitignored file into the plan. A cite never blocks planning. Place cites in Sources & References or Key Technical Decisions, never in the Prior-Art Survey JSON.
|
|
249
|
+
|
|
247
250
|
#### 1.1b Detect Execution Posture Signals
|
|
248
251
|
|
|
249
252
|
Decide whether the plan should carry a lightweight execution posture signal.
|
|
@@ -305,7 +308,7 @@ If Step 1.2 indicates external research is useful, run these agents in parallel:
|
|
|
305
308
|
|
|
306
309
|
Summarize:
|
|
307
310
|
- Relevant codebase patterns and file paths
|
|
308
|
-
- Relevant institutional learnings
|
|
311
|
+
- Relevant institutional learnings and overlapping past work, with recorded status
|
|
309
312
|
- Organizational context from Slack conversations, if gathered (prior discussions, decisions, or domain knowledge relevant to the feature)
|
|
310
313
|
- External references and best practices, if gathered
|
|
311
314
|
- Related issues, PRs, or prior art
|
|
@@ -354,6 +357,7 @@ Ask the user only when the answer materially affects architecture, scope, sequen
|
|
|
354
357
|
#### 3.1 Title and File Naming
|
|
355
358
|
|
|
356
359
|
- Draft a clear, searchable title using conventional format such as `feat: Add user authentication` or `fix: Prevent checkout double-submit`
|
|
360
|
+
- Quote the title in the frontmatter (`title: "feat: Add user authentication"`): a conventional-commit title contains a colon, which YAML reads as a mapping, and the plan then fails to parse
|
|
357
361
|
- Determine the plan type: `feat`, `fix`, or `refactor`
|
|
358
362
|
- Build the filename following the repository convention: `docs/plans/YYYY-MM-DD-NNN-<type>-<descriptive-name>-plan.md`
|
|
359
363
|
- Create `docs/plans/` if it does not exist
|
|
@@ -510,7 +514,7 @@ Omit clearly inapplicable optional sections, especially for Lightweight plans.
|
|
|
510
514
|
|
|
511
515
|
```markdown
|
|
512
516
|
---
|
|
513
|
-
title: [Plan Title]
|
|
517
|
+
title: "[Plan Title]"
|
|
514
518
|
type: [feat|fix|refactor]
|
|
515
519
|
status: active
|
|
516
520
|
date: YYYY-MM-DD
|
|
@@ -684,6 +688,7 @@ Omit `scopes_considered` unless the verdict is `unscoped`, and omit `acceptance`
|
|
|
684
688
|
reader cloning the repo will not find it, and a bare link cannot tell them
|
|
685
689
|
whether they are missing context or whether it was always local. -->
|
|
686
690
|
- Related code: [path or symbol]
|
|
691
|
+
- Related past work: [path], recorded [status]. [How this plan differs]
|
|
687
692
|
- Related PRs/issues: #[number]
|
|
688
693
|
- External docs: [url]
|
|
689
694
|
```
|
|
@@ -103,7 +103,7 @@ Use fully-qualified agent names inside Task calls.
|
|
|
103
103
|
- `systematic:research:repo-research-analyst` (Scope: `architecture, patterns`) for repo-grounded patterns, conventions, and implementation reality checks
|
|
104
104
|
|
|
105
105
|
**Context & Research / Sources & References gaps**
|
|
106
|
-
- `systematic:research:learnings-researcher` for institutional knowledge
|
|
106
|
+
- `systematic:research:learnings-researcher` (make `scope: past-work` the first line of the prompt and `exclude: <path of the plan being deepened>` the second line) for institutional knowledge, past solved problems, and earlier plans, brainstorms and ideation docs
|
|
107
107
|
- `systematic:research:framework-docs-researcher` for official framework or library behavior
|
|
108
108
|
- `systematic:research:best-practices-researcher` for current external patterns and industry guidance
|
|
109
109
|
- Add `systematic:research:git-history-analyzer` only when historical rationale or prior art is materially missing
|
|
@@ -221,6 +221,8 @@ If findings were accepted and the plan was modified, proceed through 5.3.7 and 5
|
|
|
221
221
|
|
|
222
222
|
Strengthen only the selected sections. Keep the plan coherent and preserve its overall structure.
|
|
223
223
|
|
|
224
|
+
**Cite and differentiate.** Where findings are integrated into the plan, and the researcher's results show a rejected, deferred, superseded or completed item with the same behavior or surface as the plan's work, cite it (at most 3 items) and say how the new work differs. Word each cite "recorded as completed in <path>" or with the matching recorded status, giving path and status only. Never quote text from a gitignored file into the plan. A cite never blocks the plan.
|
|
225
|
+
|
|
224
226
|
**In interactive mode:** Only integrate findings the user accepted in 5.3.6b. If some findings from different agents touch the same section, reconcile them coherently but do not reintroduce rejected findings.
|
|
225
227
|
|
|
226
228
|
Allowed changes:
|
|
@@ -88,8 +88,10 @@ revisions — never rename or repurpose a field.
|
|
|
88
88
|
|
|
89
89
|
### Required
|
|
90
90
|
|
|
91
|
-
- **`title`** — verbatim plan title
|
|
92
|
-
|
|
91
|
+
- **`title`** — verbatim plan title, written as a double-quoted string
|
|
92
|
+
(`title: "feat: Add x"`). Matches the H1 heading so file metadata and visible
|
|
93
|
+
heading don't drift. Quote it because a conventional-commit title contains a
|
|
94
|
+
colon, which YAML reads as a mapping and the plan then fails to parse.
|
|
93
95
|
- **`type`** — conventional-commit-prefix-aligned classification (`feat`,
|
|
94
96
|
`fix`, `refactor`, `chore`, `docs`, `perf`, `test`, etc.). Carries the
|
|
95
97
|
intent the eventual commit message should reflect.
|
|
@@ -213,7 +213,7 @@ Use fully-qualified agent names inside Task calls.
|
|
|
213
213
|
- `systematic:research:repo-research-analyst` (Scope: `architecture, patterns`) for repo-grounded patterns, conventions, and implementation reality checks
|
|
214
214
|
|
|
215
215
|
**Context & Research / Sources & References gaps**
|
|
216
|
-
- `systematic:research:learnings-researcher` for institutional knowledge
|
|
216
|
+
- `systematic:research:learnings-researcher` (make `scope: past-work` the first line of the prompt and `exclude: <path of the plan being deepened>` the second line) for institutional knowledge, past solved problems, and earlier plans, brainstorms and ideation docs
|
|
217
217
|
- `systematic:research:framework-docs-researcher` for official framework or library behavior
|
|
218
218
|
- `systematic:research:best-practices-researcher` for current external patterns and industry guidance
|
|
219
219
|
- Add `systematic:research:git-history-analyzer` only when historical rationale or prior art is materially missing
|
|
@@ -335,6 +335,8 @@ If agent outputs conflict:
|
|
|
335
335
|
|
|
336
336
|
Strengthen only the selected sections. Keep the plan coherent and preserve its overall structure.
|
|
337
337
|
|
|
338
|
+
**Cite and differentiate.** Where findings are integrated into the plan, and the researcher's results show a rejected, deferred, superseded or completed item with the same behavior or surface as the plan's work, cite it (at most 3 items) and say how the new work differs. Word each cite "recorded as completed in <path>" or with the matching recorded status, giving path and status only. Never quote text from a gitignored file into the plan. A cite never blocks the plan.
|
|
339
|
+
|
|
338
340
|
If artifact-backed mode was used:
|
|
339
341
|
- read the plan, origin document if present, and the selected section artifacts
|
|
340
342
|
- also incorporate any findings already returned inline from direct-mode agents before a mid-run switch, so early results are not silently dropped
|