@fro.bot/systematic 1.23.2 → 2.0.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 +75 -61
- package/agents/research/best-practices-researcher.md +2 -3
- package/agents/research/issue-intelligence-analyst.md +2 -3
- package/package.json +2 -3
- package/skills/ce-brainstorm/SKILL.md +10 -11
- package/skills/ce-compound/SKILL.md +11 -11
- package/skills/ce-compound-refresh/SKILL.md +2 -2
- package/skills/ce-ideate/SKILL.md +3 -4
- package/skills/ce-plan/SKILL.md +8 -8
- package/skills/ce-plan-beta/SKILL.md +9 -10
- package/skills/ce-review/SKILL.md +7 -7
- package/skills/ce-work/SKILL.md +4 -4
- package/skills/ce-work-beta/SKILL.md +556 -0
- package/skills/claude-permissions-optimizer/SKILL.md +161 -0
- package/skills/claude-permissions-optimizer/scripts/extract-commands.mjs +805 -0
- package/skills/deepen-plan/SKILL.md +15 -15
- package/skills/deepen-plan-beta/SKILL.md +3 -3
- package/skills/deploy-docs/SKILL.md +8 -8
- package/skills/file-todos/SKILL.md +2 -1
- package/skills/generate_command/SKILL.md +1 -1
- package/skills/{report-bug → report-bug-ce}/SKILL.md +38 -33
- package/skills/resolve-todo-parallel/SKILL.md +65 -0
- package/skills/setup/SKILL.md +3 -3
- package/skills/test-browser/SKILL.md +3 -4
- package/commands/.gitkeep +0 -0
- package/skills/create-agent-skill/SKILL.md +0 -10
- package/skills/create-agent-skills/SKILL.md +0 -265
- package/skills/create-agent-skills/references/api-security.md +0 -226
- package/skills/create-agent-skills/references/be-clear-and-direct.md +0 -531
- package/skills/create-agent-skills/references/best-practices.md +0 -404
- package/skills/create-agent-skills/references/common-patterns.md +0 -595
- package/skills/create-agent-skills/references/core-principles.md +0 -437
- package/skills/create-agent-skills/references/executable-code.md +0 -175
- package/skills/create-agent-skills/references/iteration-and-testing.md +0 -474
- package/skills/create-agent-skills/references/official-spec.md +0 -134
- package/skills/create-agent-skills/references/recommended-structure.md +0 -168
- package/skills/create-agent-skills/references/skill-structure.md +0 -152
- package/skills/create-agent-skills/references/using-scripts.md +0 -113
- package/skills/create-agent-skills/references/using-templates.md +0 -112
- package/skills/create-agent-skills/references/workflows-and-validation.md +0 -510
- package/skills/create-agent-skills/templates/router-skill.md +0 -73
- package/skills/create-agent-skills/templates/simple-skill.md +0 -33
- package/skills/create-agent-skills/workflows/add-reference.md +0 -96
- package/skills/create-agent-skills/workflows/add-script.md +0 -93
- package/skills/create-agent-skills/workflows/add-template.md +0 -74
- package/skills/create-agent-skills/workflows/add-workflow.md +0 -126
- package/skills/create-agent-skills/workflows/audit-skill.md +0 -138
- package/skills/create-agent-skills/workflows/create-domain-expertise-skill.md +0 -605
- package/skills/create-agent-skills/workflows/create-new-skill.md +0 -197
- package/skills/create-agent-skills/workflows/get-guidance.md +0 -121
- package/skills/create-agent-skills/workflows/upgrade-to-router.md +0 -161
- package/skills/create-agent-skills/workflows/verify-skill.md +0 -204
- package/skills/heal-skill/SKILL.md +0 -148
- package/skills/resolve_parallel/SKILL.md +0 -36
- package/skills/resolve_todo_parallel/SKILL.md +0 -38
package/README.md
CHANGED
|
@@ -15,7 +15,7 @@
|
|
|
15
15
|
|
|
16
16
|
<br>
|
|
17
17
|
|
|
18
|
-
**[Overview](#overview)** · **[Quick Start](#quick-start)** · **[Skills](#skills)** · **[Agents](#agents)** · **[
|
|
18
|
+
**[Overview](#overview)** · **[Quick Start](#quick-start)** · **[Skills](#skills)** · **[Agents](#agents)** · **[CLI](#cli)** · **[Configuration](#configuration)** · **[Development](#development)**
|
|
19
19
|
|
|
20
20
|
</div>
|
|
21
21
|
|
|
@@ -38,11 +38,11 @@ Most AI coding assistants respond to requests without structure or methodology.
|
|
|
38
38
|
|
|
39
39
|
### Key Features
|
|
40
40
|
|
|
41
|
-
- **Structured Skills** — Pre-built workflows for brainstorming, planning,
|
|
42
|
-
- **Specialized Agents** — Purpose-built subagents for architecture, security, and
|
|
41
|
+
- **Structured Skills** — Pre-built workflows for brainstorming, planning, code review, and more
|
|
42
|
+
- **Specialized Agents** — Purpose-built subagents for architecture, security, performance, and research
|
|
43
43
|
- **Zero Configuration** — Works immediately after installation via config hooks
|
|
44
|
-
- **Extensible** — Add project-specific skills and
|
|
45
|
-
- **Batteries Included** —
|
|
44
|
+
- **Extensible** — Add project-specific skills and agents alongside bundled ones
|
|
45
|
+
- **Batteries Included** — 48 skills and 29 agents ship with the npm package
|
|
46
46
|
- **CLI Tooling** — Inspect, list, and convert assets from the command line
|
|
47
47
|
|
|
48
48
|
## Quick Start
|
|
@@ -62,7 +62,7 @@ Install the plugin by adding it to your OpenCode configuration (`~/.config/openc
|
|
|
62
62
|
}
|
|
63
63
|
```
|
|
64
64
|
|
|
65
|
-
Restart OpenCode to activate the plugin. All bundled skills
|
|
65
|
+
Restart OpenCode to activate the plugin. All bundled skills and agents will be available immediately.
|
|
66
66
|
|
|
67
67
|
> [!NOTE]
|
|
68
68
|
> Systematic uses OpenCode's `config` hook to automatically register all bundled content. No manual file copying required.
|
|
@@ -80,9 +80,8 @@ ocx add systematic/brainstorming
|
|
|
80
80
|
ocx add systematic/agent-architecture-strategist
|
|
81
81
|
|
|
82
82
|
# Or install bundles
|
|
83
|
-
ocx add systematic/skills # All
|
|
84
|
-
ocx add systematic/agents # All
|
|
85
|
-
ocx add systematic/commands # All 9 commands
|
|
83
|
+
ocx add systematic/skills # All 48 skills
|
|
84
|
+
ocx add systematic/agents # All 29 agents
|
|
86
85
|
|
|
87
86
|
# Or use a profile (requires --global registry)
|
|
88
87
|
ocx registry add https://fro.bot/systematic --name systematic --global
|
|
@@ -110,21 +109,52 @@ Once verified, explore these guides to master the Systematic workflow:
|
|
|
110
109
|
|
|
111
110
|
## Skills
|
|
112
111
|
|
|
113
|
-
Skills are structured workflows that guide the AI through systematic engineering processes. They're loaded via the `systematic_skill` tool.
|
|
112
|
+
Skills are structured workflows that guide the AI through systematic engineering processes. They're loaded via the `systematic_skill` tool and invocable as slash commands (e.g., `/ce:brainstorm`).
|
|
113
|
+
|
|
114
|
+
### Core Workflows
|
|
115
|
+
|
|
116
|
+
The Compound Engineering loop — the heart of Systematic:
|
|
117
|
+
|
|
118
|
+
| Skill | Description |
|
|
119
|
+
|-------|-------------|
|
|
120
|
+
| `ce:brainstorm` | Explore requirements through collaborative dialogue before planning |
|
|
121
|
+
| `ce:plan` | Transform feature descriptions into structured implementation plans |
|
|
122
|
+
| `ce:review` | Perform exhaustive code reviews using multi-agent analysis |
|
|
123
|
+
| `ce:work` | Execute work plans efficiently while maintaining quality |
|
|
124
|
+
| `ce:compound` | Document recently solved problems to compound team knowledge |
|
|
125
|
+
| `ce:ideate` | Generate and critically evaluate grounded improvement ideas |
|
|
126
|
+
| `ce:compound-refresh` | Refresh stale learnings and pattern docs against current codebase |
|
|
127
|
+
|
|
128
|
+
### Development Tools
|
|
114
129
|
|
|
115
130
|
| Skill | Description |
|
|
116
131
|
|-------|-------------|
|
|
117
132
|
| `using-systematic` | Bootstrap skill — teaches the AI how to discover and use other skills |
|
|
118
|
-
| `brainstorming` | Collaborative design workflow for exploring ideas before planning |
|
|
119
133
|
| `agent-browser` | Browser automation using Vercel's agent-browser CLI |
|
|
120
134
|
| `agent-native-architecture` | Design systems where AI agents are first-class citizens |
|
|
135
|
+
| `create-agent-skill` | Expert guidance for writing and refining OpenCode skills |
|
|
121
136
|
| `compound-docs` | Capture solved problems as categorized documentation |
|
|
122
|
-
| `
|
|
123
|
-
| `
|
|
137
|
+
| `document-review` | Refine requirements or plan documents before proceeding |
|
|
138
|
+
| `deepen-plan` | Enhance a plan with parallel research for each section |
|
|
124
139
|
| `file-todos` | File-based todo tracking with status and dependency management |
|
|
125
|
-
| `frontend-design` | Create distinctive, production-grade frontend interfaces
|
|
140
|
+
| `frontend-design` | Create distinctive, production-grade frontend interfaces |
|
|
126
141
|
| `git-worktree` | Manage git worktrees for isolated parallel development |
|
|
127
|
-
| `orchestrating-swarms` | Coordinate multi-agent swarms
|
|
142
|
+
| `orchestrating-swarms` | Coordinate multi-agent swarms and pipeline workflows |
|
|
143
|
+
| `lfg` | Full autonomous engineering workflow — plan, then execute |
|
|
144
|
+
|
|
145
|
+
### Specialized Skills
|
|
146
|
+
|
|
147
|
+
| Skill | Description |
|
|
148
|
+
|-------|-------------|
|
|
149
|
+
| `dhh-rails-style` | Write Ruby and Rails code in DHH's distinctive 37signals style |
|
|
150
|
+
| `andrew-kane-gem-writer` | Write Ruby gems following Andrew Kane's proven patterns |
|
|
151
|
+
| `dspy-ruby` | Build type-safe LLM applications with DSPy.rb |
|
|
152
|
+
| `every-style-editor` | Review and edit copy for style guide compliance |
|
|
153
|
+
| `gemini-imagegen` | Generate and edit images using the Gemini API |
|
|
154
|
+
| `proof` | Create, edit, and share markdown documents via Proof |
|
|
155
|
+
| `rclone` | Upload, sync, and manage files across cloud storage providers |
|
|
156
|
+
|
|
157
|
+
> **[View all 48 skills →](https://fro.bot/systematic/reference/skills/)**
|
|
128
158
|
|
|
129
159
|
### How Skills Work
|
|
130
160
|
|
|
@@ -151,9 +181,15 @@ Agents are specialized subagents with pre-configured prompts and expertise. They
|
|
|
151
181
|
|
|
152
182
|
| Agent | Purpose |
|
|
153
183
|
|-------|---------|
|
|
154
|
-
| `design-implementation-reviewer` |
|
|
155
|
-
| `design-iterator` |
|
|
156
|
-
| `figma-design-sync` | Detect and fix visual differences between web implementation and Figma
|
|
184
|
+
| `design-implementation-reviewer` | Visually compare live UI against Figma designs and report discrepancies |
|
|
185
|
+
| `design-iterator` | Iteratively refine UI design through screenshot-analyze-improve cycles |
|
|
186
|
+
| `figma-design-sync` | Detect and fix visual differences between web implementation and Figma |
|
|
187
|
+
|
|
188
|
+
### Docs Agents
|
|
189
|
+
|
|
190
|
+
| Agent | Purpose |
|
|
191
|
+
|-------|---------|
|
|
192
|
+
| `ankane-readme-writer` | Create or update README files following Ankane-style template for Ruby gems |
|
|
157
193
|
|
|
158
194
|
### Research Agents
|
|
159
195
|
|
|
@@ -161,7 +197,8 @@ Agents are specialized subagents with pre-configured prompts and expertise. They
|
|
|
161
197
|
|-------|---------|
|
|
162
198
|
| `best-practices-researcher` | Research external best practices, documentation, and examples for any technology |
|
|
163
199
|
| `framework-docs-researcher` | Gather framework documentation and best practices |
|
|
164
|
-
| `git-history-analyzer` | Archaeological analysis of git history to trace code evolution and
|
|
200
|
+
| `git-history-analyzer` | Archaeological analysis of git history to trace code evolution and patterns |
|
|
201
|
+
| `issue-intelligence-analyst` | Analyze GitHub issues to surface recurring themes, pain patterns, and severity trends |
|
|
165
202
|
| `learnings-researcher` | Search past solutions in docs/solutions/ to surface institutional knowledge |
|
|
166
203
|
| `repo-research-analyst` | Research repository structure, documentation, conventions, and implementation patterns |
|
|
167
204
|
|
|
@@ -176,10 +213,13 @@ Agents are specialized subagents with pre-configured prompts and expertise. They
|
|
|
176
213
|
| `data-migration-expert` | Validate data migrations, backfills, and production data transformations |
|
|
177
214
|
| `deployment-verification-agent` | Produce Go/No-Go deployment checklists with verification queries and rollback procedures |
|
|
178
215
|
| `dhh-rails-reviewer` | Brutally honest Rails code review from DHH's perspective |
|
|
179
|
-
| `
|
|
216
|
+
| `julik-frontend-races-reviewer` | Review JavaScript and Stimulus code for race conditions and timing issues |
|
|
217
|
+
| `kieran-python-reviewer` | High quality bar Python review for Pythonic patterns, type safety, and maintainability |
|
|
218
|
+
| `kieran-rails-reviewer` | High quality bar Rails review for conventions, clarity, and maintainability |
|
|
180
219
|
| `kieran-typescript-reviewer` | High quality bar TypeScript review for type safety, modern patterns, and maintainability |
|
|
181
220
|
| `pattern-recognition-specialist` | Detect design patterns, anti-patterns, and code smells |
|
|
182
221
|
| `performance-oracle` | Performance analysis, bottleneck identification, scalability |
|
|
222
|
+
| `schema-drift-detector` | Detect unrelated schema.rb changes by cross-referencing against included migrations |
|
|
183
223
|
| `security-sentinel` | Security audits, vulnerability assessment, OWASP compliance |
|
|
184
224
|
|
|
185
225
|
### Workflow Agents
|
|
@@ -199,35 +239,12 @@ Agents are invoked via OpenCode's `@mention` syntax or `task`:
|
|
|
199
239
|
@architecture-strategist Review the authentication refactoring in this PR
|
|
200
240
|
```
|
|
201
241
|
|
|
202
|
-
Or programmatically in skills
|
|
242
|
+
Or programmatically in skills:
|
|
203
243
|
|
|
204
244
|
```
|
|
205
245
|
task(subagent_type="architecture-strategist", prompt="Review...")
|
|
206
246
|
```
|
|
207
247
|
|
|
208
|
-
## Commands
|
|
209
|
-
|
|
210
|
-
Commands are slash-invokable shortcuts that trigger workflows or actions.
|
|
211
|
-
|
|
212
|
-
### Workflow Commands
|
|
213
|
-
|
|
214
|
-
| Command | Description |
|
|
215
|
-
|---------|-------------|
|
|
216
|
-
| `/workflows:brainstorm` | Explore requirements through collaborative dialogue |
|
|
217
|
-
| `/workflows:plan` | Create detailed implementation plans |
|
|
218
|
-
| `/workflows:review` | Run code review with specialized agents |
|
|
219
|
-
| `/workflows:work` | Execute planned work systematically |
|
|
220
|
-
| `/workflows:compound` | Document recently solved problems to build team knowledge |
|
|
221
|
-
|
|
222
|
-
### Utility Commands
|
|
223
|
-
|
|
224
|
-
| Command | Description |
|
|
225
|
-
|---------|-------------|
|
|
226
|
-
| `/systematic:lfg` | Full autonomous engineering workflow — plan, then execute |
|
|
227
|
-
| `/systematic:create-agent-skill` | Create a new skill with expert guidance |
|
|
228
|
-
| `/systematic:deepen-plan` | Enhance a plan with parallel research for each section |
|
|
229
|
-
| `/systematic:agent-native-audit` | Audit code for agent-native architecture patterns |
|
|
230
|
-
|
|
231
248
|
## CLI
|
|
232
249
|
|
|
233
250
|
Systematic includes a CLI for inspecting and converting assets outside of OpenCode.
|
|
@@ -280,7 +297,6 @@ Configuration is loaded from multiple locations and merged (later sources overri
|
|
|
280
297
|
{
|
|
281
298
|
"disabled_skills": ["git-worktree"],
|
|
282
299
|
"disabled_agents": [],
|
|
283
|
-
"disabled_commands": [],
|
|
284
300
|
"bootstrap": {
|
|
285
301
|
"enabled": true
|
|
286
302
|
}
|
|
@@ -291,23 +307,20 @@ Configuration is loaded from multiple locations and merged (later sources overri
|
|
|
291
307
|
|--------|------|---------|-------------|
|
|
292
308
|
| `disabled_skills` | `string[]` | `[]` | Skills to exclude from registration |
|
|
293
309
|
| `disabled_agents` | `string[]` | `[]` | Agents to exclude from registration |
|
|
294
|
-
| `disabled_commands` | `string[]` | `[]` | Commands to exclude from registration |
|
|
295
310
|
| `bootstrap.enabled` | `boolean` | `true` | Inject the `using-systematic` guide into system prompts |
|
|
296
311
|
| `bootstrap.file` | `string` | — | Custom bootstrap file path (overrides default) |
|
|
297
312
|
|
|
298
313
|
### Project-Specific Content
|
|
299
314
|
|
|
300
|
-
Add your own skills
|
|
315
|
+
Add your own skills and agents alongside bundled ones:
|
|
301
316
|
|
|
302
317
|
```
|
|
303
318
|
.opencode/
|
|
304
319
|
├── skills/
|
|
305
320
|
│ └── my-skill/
|
|
306
321
|
│ └── SKILL.md
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
└── commands/
|
|
310
|
-
└── my-command.md
|
|
322
|
+
└── agents/
|
|
323
|
+
└── my-agent.md
|
|
311
324
|
```
|
|
312
325
|
|
|
313
326
|
Project-level content takes precedence over bundled content with the same name.
|
|
@@ -333,7 +346,7 @@ flowchart TB
|
|
|
333
346
|
A --> C[tool hook]
|
|
334
347
|
A --> D[system.transform hook]
|
|
335
348
|
|
|
336
|
-
B --> E[Merge bundled agents
|
|
349
|
+
B --> E[Merge bundled agents and skills into OpenCode config]
|
|
337
350
|
C --> F[Register systematic_skill tool]
|
|
338
351
|
D --> G[Inject bootstrap prompt into every conversation]
|
|
339
352
|
|
|
@@ -346,11 +359,11 @@ flowchart TB
|
|
|
346
359
|
style G fill:#0f0f23,stroke:#F5A623,color:#B2F5EA
|
|
347
360
|
```
|
|
348
361
|
|
|
349
|
-
1. **`config` hook** — Discovers and merges bundled skills
|
|
362
|
+
1. **`config` hook** — Discovers and merges bundled skills and agents into your OpenCode configuration. Existing config takes precedence over bundled content. Skills are registered as slash commands with the `systematic:` prefix.
|
|
350
363
|
2. **`tool` hook** — Registers the `systematic_skill` tool, which lists available skills in its XML description and loads skill content on demand.
|
|
351
364
|
3. **`system.transform` hook** — Injects the "Using Systematic" bootstrap guide into system prompts, teaching the AI how to discover and invoke skills.
|
|
352
365
|
|
|
353
|
-
This architecture ensures skills
|
|
366
|
+
This architecture ensures skills and agents are available immediately without manual setup.
|
|
354
367
|
|
|
355
368
|
## Development
|
|
356
369
|
|
|
@@ -398,18 +411,19 @@ systematic/
|
|
|
398
411
|
│ ├── skill-loader.ts # Skill content loading + formatting
|
|
399
412
|
│ ├── skills.ts # Skill discovery
|
|
400
413
|
│ ├── agents.ts # Agent discovery
|
|
401
|
-
│ ├── commands.ts # Command discovery
|
|
414
|
+
│ ├── commands.ts # Command discovery (backward compat)
|
|
402
415
|
│ ├── frontmatter.ts # YAML frontmatter parsing
|
|
403
416
|
│ ├── manifest.ts # Upstream sync manifest tracking
|
|
404
417
|
│ ├── validation.ts # Agent config validation + type guards
|
|
405
418
|
│ └── walk-dir.ts # Recursive directory walker
|
|
406
|
-
├── skills/ #
|
|
407
|
-
├── agents/ #
|
|
408
|
-
├── commands/ # 9 bundled commands (with workflows/ subdir)
|
|
419
|
+
├── skills/ # 48 bundled skills (SKILL.md files)
|
|
420
|
+
├── agents/ # 29 bundled agents (5 categories)
|
|
409
421
|
├── docs/ # Starlight documentation site
|
|
422
|
+
├── registry/ # OCX registry config + profiles
|
|
423
|
+
├── scripts/ # Build and utility scripts
|
|
410
424
|
├── tests/
|
|
411
|
-
│ ├── unit/ #
|
|
412
|
-
│ └── integration/ #
|
|
425
|
+
│ ├── unit/ # 13 unit test files
|
|
426
|
+
│ └── integration/ # 2 integration test files
|
|
413
427
|
└── dist/ # Build output
|
|
414
428
|
```
|
|
415
429
|
|
|
@@ -435,7 +449,7 @@ See [`AGENTS.md`](./AGENTS.md) for detailed development guidelines, code style c
|
|
|
435
449
|
|
|
436
450
|
## Converting from Claude Code
|
|
437
451
|
|
|
438
|
-
Migrating skills
|
|
452
|
+
Migrating skills or agents from CEP or other Claude Code-format sources to Systematic? See the [Conversion Guide](https://fro.bot/systematic/guides/conversion-guide/) for field mappings and examples.
|
|
439
453
|
|
|
440
454
|
## References
|
|
441
455
|
|
|
@@ -32,8 +32,8 @@ Before going online, check if curated knowledge already exists in skills:
|
|
|
32
32
|
|
|
33
33
|
1. **Discover Available Skills**:
|
|
34
34
|
- Use the platform's native file-search/glob capability to find `SKILL.md` files in the active skill locations
|
|
35
|
-
- For maximum compatibility, check project/workspace skill directories in `.
|
|
36
|
-
- Also check user/home skill directories in `~/.
|
|
35
|
+
- For maximum compatibility, check project/workspace skill directories in `.opencode/skills/**/SKILL.md`, `.codex/skills/**/SKILL.md`, and `.agents/skills/**/SKILL.md`
|
|
36
|
+
- Also check user/home skill directories in `~/.config/opencode/skills/**/SKILL.md`, `~/.codex/skills/**/SKILL.md`, and `~/.agents/skills/**/SKILL.md`
|
|
37
37
|
- In Codex environments, `.agents/skills/` may be discovered from the current working directory upward to the repository root, not only from a single fixed repo root location
|
|
38
38
|
- If the current environment provides an `AGENTS.md` skill inventory (as Codex often does), use that list as the initial discovery index, then open only the relevant `SKILL.md` files
|
|
39
39
|
- Use the platform's native file-read capability to examine skill descriptions and understand what each covers
|
|
@@ -130,4 +130,3 @@ If you encounter conflicting advice, present the different viewpoints and explai
|
|
|
130
130
|
**Tool Selection:** Use native file-search/glob (e.g., `Glob`), content-search (e.g., `Grep`), and file-read (e.g., `Read`) tools for repository exploration. Only use shell for commands with no native equivalent (e.g., `bundle show`), one command at a time.
|
|
131
131
|
|
|
132
132
|
Your research should be thorough but focused on practical application. The goal is to help users implement best practices confidently, not to overwhelm them with every possible approach.
|
|
133
|
-
|
|
@@ -217,8 +217,8 @@ Every theme MUST include ALL of the following fields. Do not skip fields, merge
|
|
|
217
217
|
- **Always use `--jq` for field extraction and filtering** from `gh` JSON output (e.g., `gh issue list --json title --jq '.[].title'`, `gh issue list --json stateReason --jq '[.[] | select(.stateReason == "COMPLETED")]'`). The `gh` CLI has full jq support built in.
|
|
218
218
|
- **Never write inline scripts** (`python3 -c`, `node -e`, `ruby -e`) to process, filter, sort, or transform issue data. Reason over the data directly after reading it — you are an LLM, you can filter and cluster in context without running code.
|
|
219
219
|
- **Never pipe** `gh` output through any command (`| python3`, `| jq`, `| grep`, `| sort`). Use `--jq` flags instead, or read the output and reason over it.
|
|
220
|
-
- Use native file-search/glob tools (e.g., `Glob` in
|
|
221
|
-
- Use native content-search/grep tools (e.g., `Grep` in
|
|
220
|
+
- Use native file-search/glob tools (e.g., `Glob` in OpenCode) for any repo file exploration
|
|
221
|
+
- Use native content-search/grep tools (e.g., `Grep` in OpenCode) for searching file contents
|
|
222
222
|
- Do not use shell commands for tasks that have native tool equivalents (no `find`, `cat`, `rg` through shell)
|
|
223
223
|
|
|
224
224
|
## Integration Points
|
|
@@ -229,4 +229,3 @@ This agent is designed to be invoked by:
|
|
|
229
229
|
- Other skills or workflows — any context where understanding issue patterns is valuable
|
|
230
230
|
|
|
231
231
|
The output is self-contained and not coupled to any specific caller's context.
|
|
232
|
-
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@fro.bot/systematic",
|
|
3
|
-
"version": "
|
|
3
|
+
"version": "2.0.0",
|
|
4
4
|
"description": "Structured engineering workflows for OpenCode",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"homepage": "https://fro.bot/systematic",
|
|
@@ -17,8 +17,7 @@
|
|
|
17
17
|
"files": [
|
|
18
18
|
"dist",
|
|
19
19
|
"skills",
|
|
20
|
-
"agents"
|
|
21
|
-
"commands"
|
|
20
|
+
"agents"
|
|
22
21
|
],
|
|
23
22
|
"workspaces": [
|
|
24
23
|
"docs"
|
|
@@ -8,7 +8,7 @@ argument-hint: '[feature idea or problem to explore]'
|
|
|
8
8
|
|
|
9
9
|
**Note: The current year is 2026.** Use this when dating requirements documents.
|
|
10
10
|
|
|
11
|
-
Brainstorming helps answer **WHAT** to build through collaborative dialogue. It precedes `/
|
|
11
|
+
Brainstorming helps answer **WHAT** to build through collaborative dialogue. It precedes `/ce:plan`, which answers **HOW** to build it.
|
|
12
12
|
|
|
13
13
|
The durable output of this workflow is a **requirements document**. In other workflows this might be called a lightweight PRD or feature brief. In compound engineering, keep the workflow name `brainstorm`, but make the written artifact strong enough that planning does not need to invent product behavior, scope boundaries, or success criteria.
|
|
14
14
|
|
|
@@ -28,7 +28,7 @@ This skill does not implement code. It explores, clarifies, and documents decisi
|
|
|
28
28
|
1. **Ask one question at a time** - Do not batch several unrelated questions into one message.
|
|
29
29
|
2. **Prefer single-select multiple choice** - Use single-select when choosing one direction, one priority, or one next step.
|
|
30
30
|
3. **Use multi-select rarely and intentionally** - Use it only for compatible sets such as goals, constraints, non-goals, or success criteria that can all coexist. If prioritization matters, follow up by asking which selected item is primary.
|
|
31
|
-
4. **Use the platform's question tool when available** - When asking the user a question, prefer the platform's blocking question tool if one exists (`
|
|
31
|
+
4. **Use the platform's question tool when available** - When asking the user a question, prefer the platform's blocking question tool if one exists (`question` in OpenCode, `request_user_input` in Codex, `ask_user` in Gemini). Otherwise, present numbered options in chat and wait for the user's reply before proceeding.
|
|
32
32
|
|
|
33
33
|
## Output Guidance
|
|
34
34
|
|
|
@@ -83,7 +83,7 @@ Scan the repo before substantive brainstorming. Match depth to scope:
|
|
|
83
83
|
|
|
84
84
|
**Standard and Deep** — Two passes:
|
|
85
85
|
|
|
86
|
-
*Constraint Check* — Check project instruction files (`AGENTS.md
|
|
86
|
+
*Constraint Check* — Check project instruction files (`AGENTS.md`) for workflow, product, or scope constraints that affect the brainstorm. If these add nothing, move on.
|
|
87
87
|
|
|
88
88
|
*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.
|
|
89
89
|
|
|
@@ -211,8 +211,8 @@ topic: <kebab-case-topic>
|
|
|
211
211
|
- [Affects R2][Needs research] [Question that likely requires research during planning]
|
|
212
212
|
|
|
213
213
|
## Next Steps
|
|
214
|
-
[If `Resolve Before Planning` is empty: `→ /
|
|
215
|
-
[If `Resolve Before Planning` is not empty: `→ Resume /
|
|
214
|
+
[If `Resolve Before Planning` is empty: `→ /ce:plan` for structured implementation planning]
|
|
215
|
+
[If `Resolve Before Planning` is not empty: `→ Resume /ce:brainstorm` to resolve blocking questions before planning]
|
|
216
216
|
```
|
|
217
217
|
|
|
218
218
|
For **Standard** and **Deep** brainstorms, a requirements document is usually warranted.
|
|
@@ -260,7 +260,7 @@ If `Resolve Before Planning` contains any items:
|
|
|
260
260
|
**Question when blocking questions remain and user wants to pause:** "Brainstorm paused. Planning is blocked until the remaining questions are resolved. What would you like to do next?"
|
|
261
261
|
|
|
262
262
|
Present only the options that apply:
|
|
263
|
-
- **Proceed to planning (Recommended)** - Run `/
|
|
263
|
+
- **Proceed to planning (Recommended)** - Run `/ce:plan` for structured implementation planning
|
|
264
264
|
- **Proceed directly to work** - Only offer this when scope is lightweight, success criteria are clear, scope boundaries are clear, and no meaningful technical or research questions remain
|
|
265
265
|
- **Review and refine** - Offer this only when a requirements document exists and can be improved through structured review
|
|
266
266
|
- **Ask more questions** - Continue clarifying scope, preferences, or edge cases
|
|
@@ -273,11 +273,11 @@ If the direct-to-work gate is not satisfied, omit that option entirely.
|
|
|
273
273
|
|
|
274
274
|
**If user selects "Proceed to planning (Recommended)":**
|
|
275
275
|
|
|
276
|
-
Immediately run `/
|
|
276
|
+
Immediately run `/ce:plan` in the current session. Pass the requirements document path when one exists; otherwise pass a concise summary of the finalized brainstorm decisions. Do not print the closing summary first.
|
|
277
277
|
|
|
278
278
|
**If user selects "Proceed directly to work":**
|
|
279
279
|
|
|
280
|
-
Immediately run `/
|
|
280
|
+
Immediately run `/ce:work` in the current session using the finalized brainstorm output as context. If a compact requirements document exists, pass its path. Do not print the closing summary first.
|
|
281
281
|
|
|
282
282
|
**If user selects "Share to Proof":**
|
|
283
283
|
|
|
@@ -317,7 +317,7 @@ Key decisions:
|
|
|
317
317
|
- [Decision 1]
|
|
318
318
|
- [Decision 2]
|
|
319
319
|
|
|
320
|
-
Recommended next step: `/
|
|
320
|
+
Recommended next step: `/ce:plan`
|
|
321
321
|
```
|
|
322
322
|
|
|
323
323
|
If the user pauses with `Resolve Before Planning` still populated, display:
|
|
@@ -331,6 +331,5 @@ Planning is blocked by:
|
|
|
331
331
|
- [Blocking question 1]
|
|
332
332
|
- [Blocking question 2]
|
|
333
333
|
|
|
334
|
-
Resume with `/
|
|
334
|
+
Resume with `/ce:brainstorm` when ready to resolve these before planning.
|
|
335
335
|
```
|
|
336
|
-
|
|
@@ -17,13 +17,13 @@ Captures problem solutions while context is fresh, creating structured documenta
|
|
|
17
17
|
## Usage
|
|
18
18
|
|
|
19
19
|
```bash
|
|
20
|
-
/
|
|
21
|
-
/
|
|
20
|
+
/ce:compound # Document the most recent fix
|
|
21
|
+
/ce:compound [brief context] # Provide additional context hint
|
|
22
22
|
```
|
|
23
23
|
|
|
24
24
|
## Execution Strategy
|
|
25
25
|
|
|
26
|
-
**Always run full mode by default.** Proceed directly to Phase 1 unless the user explicitly requests compact-safe mode (e.g., `/
|
|
26
|
+
**Always run full mode by default.** Proceed directly to Phase 1 unless the user explicitly requests compact-safe mode (e.g., `/ce:compound --compact` or "use compact mode").
|
|
27
27
|
|
|
28
28
|
Compact-safe mode exists as a lightweight alternative — see the **Compact-Safe Mode** section below. It's there if the user wants it, not something to push.
|
|
29
29
|
|
|
@@ -128,10 +128,10 @@ When invoking or recommending `ce:compound-refresh`, be explicit about the argum
|
|
|
128
128
|
|
|
129
129
|
Examples:
|
|
130
130
|
|
|
131
|
-
- `/
|
|
132
|
-
- `/
|
|
133
|
-
- `/
|
|
134
|
-
- `/
|
|
131
|
+
- `/ce:compound-refresh plugin-versioning-requirements`
|
|
132
|
+
- `/ce:compound-refresh payments`
|
|
133
|
+
- `/ce:compound-refresh performance-issues`
|
|
134
|
+
- `/ce:compound-refresh critical-patterns`
|
|
135
135
|
|
|
136
136
|
A single scope hint may still expand to multiple related docs when the change is cross-cutting within one domain, category, or pattern area.
|
|
137
137
|
|
|
@@ -299,7 +299,7 @@ Build → Test → Find Issue → Research → Improve → Document → Validate
|
|
|
299
299
|
|
|
300
300
|
<auto_invoke> <trigger_phrases> - "that worked" - "it's fixed" - "working now" - "problem solved" </trigger_phrases>
|
|
301
301
|
|
|
302
|
-
<manual_override> Use /
|
|
302
|
+
<manual_override> Use /ce:compound [context] to document immediately without waiting for auto-detection. </manual_override> </auto_invoke>
|
|
303
303
|
|
|
304
304
|
## Routes To
|
|
305
305
|
|
|
@@ -327,11 +327,11 @@ Based on problem type, these agents can enhance documentation:
|
|
|
327
327
|
|
|
328
328
|
### When to Invoke
|
|
329
329
|
- **Auto-triggered** (optional): Agents can run post-documentation for enhancement
|
|
330
|
-
- **Manual trigger**: User can invoke agents after /
|
|
331
|
-
- **Customize agents**: Edit `
|
|
330
|
+
- **Manual trigger**: User can invoke agents after /ce:compound completes for deeper review
|
|
331
|
+
- **Customize agents**: Edit `systematic.local.md` or invoke the `setup` skill to configure which review agents are used across all workflows
|
|
332
332
|
|
|
333
333
|
## Related Commands
|
|
334
334
|
|
|
335
335
|
- `/research [topic]` - Deep investigation (searches docs/solutions/ for patterns)
|
|
336
|
-
- `/
|
|
336
|
+
- `/ce:plan` - Planning workflow (references documented solutions)
|
|
337
337
|
|
|
@@ -33,7 +33,7 @@ Check if `$ARGUMENTS` contains `mode:autonomous`. If present, strip it from argu
|
|
|
33
33
|
|
|
34
34
|
Follow the same interaction style as `ce:brainstorm`:
|
|
35
35
|
|
|
36
|
-
- Ask questions **one at a time** — use the platform's blocking question tool when available (`
|
|
36
|
+
- Ask questions **one at a time** — use the platform's blocking question tool when available (`question` in OpenCode, `request_user_input` in Codex, `ask_user` in Gemini). Otherwise, present numbered options in plain text and wait for the user's reply before continuing
|
|
37
37
|
- Prefer **multiple choice** when natural options exist
|
|
38
38
|
- Start with **scope and intent**, then narrow only when needed
|
|
39
39
|
- Do **not** ask the user to make decisions before you have evidence
|
|
@@ -309,7 +309,7 @@ Do **not** ask questions about whether code changes were intentional, whether th
|
|
|
309
309
|
|
|
310
310
|
#### Question Style
|
|
311
311
|
|
|
312
|
-
Always present choices using the platform's blocking question tool when available (`
|
|
312
|
+
Always present choices using the platform's blocking question tool when available (`question` in OpenCode, `request_user_input` in Codex, `ask_user` in Gemini). Otherwise, present numbered options in plain text and wait for the user's reply before proceeding.
|
|
313
313
|
|
|
314
314
|
Question rules:
|
|
315
315
|
|
|
@@ -18,7 +18,7 @@ This workflow produces a ranked ideation artifact in `docs/ideation/`. It does *
|
|
|
18
18
|
|
|
19
19
|
## Interaction Method
|
|
20
20
|
|
|
21
|
-
Use the platform's blocking question tool when available (`
|
|
21
|
+
Use the platform's blocking question tool when available (`question` in OpenCode, `request_user_input` in Codex, `ask_user` in Gemini). Otherwise, present numbered options in chat and wait for the user's reply before proceeding.
|
|
22
22
|
|
|
23
23
|
Ask one question at a time. Prefer concise single-select choices when natural options exist.
|
|
24
24
|
|
|
@@ -29,7 +29,7 @@ Ask one question at a time. Prefer concise single-select choices when natural op
|
|
|
29
29
|
Interpret any provided argument as optional context. It may be:
|
|
30
30
|
|
|
31
31
|
- a concept such as `DX improvements`
|
|
32
|
-
- a path such as `plugins/
|
|
32
|
+
- a path such as `plugins/systematic/skills/`
|
|
33
33
|
- a constraint such as `low-complexity quick wins`
|
|
34
34
|
- a volume hint such as `top 3`, `100 ideas`, or `raise the bar`
|
|
35
35
|
|
|
@@ -103,7 +103,7 @@ Run agents in parallel in the **foreground** (do not use background dispatch —
|
|
|
103
103
|
|
|
104
104
|
1. **Quick context scan** — dispatch a general-purpose sub-agent with this prompt:
|
|
105
105
|
|
|
106
|
-
|
|
106
|
+
> Read the project's AGENTS.md (or README.md if AGENTS.md is absent), then discover the top-level directory layout using the native file-search/glob tool (e.g., `Glob` with pattern `*` or `*/*` in OpenCode). Return a concise summary (under 30 lines) covering:
|
|
107
107
|
> - project shape (language, framework, top-level directory layout)
|
|
108
108
|
> - notable patterns or conventions
|
|
109
109
|
> - obvious pain points or gaps
|
|
@@ -368,4 +368,3 @@ Before finishing, check:
|
|
|
368
368
|
- survivors are materially better than a naive "give me ideas" list
|
|
369
369
|
- the artifact was written before any handoff, sharing, or session end
|
|
370
370
|
- acting on an idea routes to `ce:brainstorm`, not directly to implementation
|
|
371
|
-
|
package/skills/ce-plan/SKILL.md
CHANGED
|
@@ -49,7 +49,7 @@ ls -la docs/brainstorms/*-requirements.md 2>/dev/null | head -10
|
|
|
49
49
|
5. Use source document content as the **primary input** to research and planning phases
|
|
50
50
|
6. **Critical: The source document is the origin document.** Throughout the plan, reference specific decisions with `(see origin: <source-path>)` when carrying forward conclusions. Do not paraphrase decisions in a way that loses their original context — link back to the source.
|
|
51
51
|
7. **Do not omit source content** — if the source document discussed it, the plan must address it (even if briefly). Scan each section before finalizing the plan to verify nothing was dropped.
|
|
52
|
-
8. **If `Resolve Before Planning` contains any items, stop.** Do not proceed with planning. Tell the user planning is blocked by unanswered brainstorm questions and direct them to resume `/
|
|
52
|
+
8. **If `Resolve Before Planning` contains any items, stop.** Do not proceed with planning. Tell the user planning is blocked by unanswered brainstorm questions and direct them to resume `/ce:brainstorm` or answer those questions first.
|
|
53
53
|
|
|
54
54
|
**If multiple source documents could match:**
|
|
55
55
|
Use **question tool** to ask which source document to use, or whether to proceed without one.
|
|
@@ -582,8 +582,8 @@ After writing the plan file, use the **question tool** to present these options:
|
|
|
582
582
|
2. **Run `/deepen-plan`** - Enhance each section with parallel research agents (best practices, performance, UI)
|
|
583
583
|
3. **Review and refine** - Improve the document through structured self-review
|
|
584
584
|
4. **Share to Proof** - Upload to Proof for collaborative review and sharing
|
|
585
|
-
5. **Start `/
|
|
586
|
-
6. **Start `/
|
|
585
|
+
5. **Start `/ce:work`** - Begin implementing this plan locally
|
|
586
|
+
6. **Start `/ce:work` on remote** - Begin implementing in OpenCode on the web (use `&` to run in background)
|
|
587
587
|
7. **Create Issue** - Create issue in project tracker (GitHub/Linear)
|
|
588
588
|
|
|
589
589
|
Based on selection:
|
|
@@ -600,14 +600,14 @@ Based on selection:
|
|
|
600
600
|
PROOF_URL=$(echo "$RESPONSE" | jq -r '.tokenUrl')
|
|
601
601
|
```
|
|
602
602
|
Display: `View & collaborate in Proof: <PROOF_URL>` — skip silently if curl fails. Then return to options.
|
|
603
|
-
- **`/
|
|
604
|
-
- **`/
|
|
603
|
+
- **`/ce:work`** → Call the /ce:work command with the plan file path
|
|
604
|
+
- **`/ce:work` on remote** → Run `/ce:work docs/plans/<plan_filename>.md &` to start work in background for OpenCode web
|
|
605
605
|
- **Create Issue** → See "Issue Creation" section below
|
|
606
606
|
- **Other** (automatically provided) → Accept free text for rework or specific changes
|
|
607
607
|
|
|
608
|
-
**Note:** If running `/
|
|
608
|
+
**Note:** If running `/ce:plan` with ultrathink enabled, automatically run `/deepen-plan` after plan creation for maximum depth and grounding.
|
|
609
609
|
|
|
610
|
-
Loop back to options after Simplify or Other changes until user selects `/
|
|
610
|
+
Loop back to options after Simplify or Other changes until user selects `/ce:work` or another action.
|
|
611
611
|
|
|
612
612
|
## Issue Creation
|
|
613
613
|
|
|
@@ -637,7 +637,7 @@ When user selects "Create Issue", detect their project tracker from AGENTS.md:
|
|
|
637
637
|
|
|
638
638
|
5. **After creation:**
|
|
639
639
|
- Display the issue URL
|
|
640
|
-
- Ask if they want to proceed to `/
|
|
640
|
+
- Ask if they want to proceed to `/ce:work`
|
|
641
641
|
|
|
642
642
|
NEVER CODE! Just research and write the plan.
|
|
643
643
|
|
|
@@ -15,7 +15,7 @@ This workflow produces a durable implementation plan. It does **not** implement
|
|
|
15
15
|
|
|
16
16
|
## Interaction Method
|
|
17
17
|
|
|
18
|
-
Use the platform's question tool when available. When asking the user a question, prefer the platform's blocking question tool if one exists (`
|
|
18
|
+
Use the platform's question tool when available. When asking the user a question, prefer the platform's blocking question tool if one exists (`question` in OpenCode, `request_user_input` in Codex, `ask_user` in Gemini). Otherwise, present numbered options in chat and wait for the user's reply before proceeding.
|
|
19
19
|
|
|
20
20
|
Ask one question at a time. Prefer a concise single-select choice when natural options exist.
|
|
21
21
|
|
|
@@ -150,7 +150,7 @@ Run these agents in parallel:
|
|
|
150
150
|
Collect:
|
|
151
151
|
- Existing patterns and conventions to follow
|
|
152
152
|
- Relevant files, modules, and tests
|
|
153
|
-
- AGENTS.md
|
|
153
|
+
- AGENTS.md guidance that materially affects the plan
|
|
154
154
|
- Institutional learnings from `docs/solutions/`
|
|
155
155
|
|
|
156
156
|
#### 1.2 Decide on External Research
|
|
@@ -518,8 +518,8 @@ After writing the plan file, present the options using the platform's blocking q
|
|
|
518
518
|
2. **Run `/deepen-plan-beta`** - Stress-test weak sections with targeted research when the plan needs more confidence
|
|
519
519
|
3. **Run `document-review` skill** - Improve the plan through structured document review
|
|
520
520
|
4. **Share to Proof** - Upload the plan for collaborative review and sharing
|
|
521
|
-
5. **Start `/
|
|
522
|
-
6. **Start `/
|
|
521
|
+
5. **Start `/ce:work`** - Begin implementing this plan in the current environment
|
|
522
|
+
6. **Start `/ce:work` in another session** - Begin implementing in a separate agent session when the current platform supports it
|
|
523
523
|
7. **Create Issue** - Create an issue in the configured tracker
|
|
524
524
|
|
|
525
525
|
Based on selection:
|
|
@@ -536,8 +536,8 @@ Based on selection:
|
|
|
536
536
|
PROOF_URL=$(echo "$RESPONSE" | jq -r '.tokenUrl')
|
|
537
537
|
```
|
|
538
538
|
Display `View & collaborate in Proof: <PROOF_URL>` if successful, then return to the options
|
|
539
|
-
- **`/
|
|
540
|
-
- **`/
|
|
539
|
+
- **`/ce:work`** → Call `/ce:work` with the plan path
|
|
540
|
+
- **`/ce:work` in another session** → If the current platform supports launching a separate agent session, start `/ce:work` with the plan path there. Otherwise, explain the limitation briefly and offer to run `/ce:work` in the current session instead.
|
|
541
541
|
- **Create Issue** → Follow the Issue Creation section below
|
|
542
542
|
- **Other** → Accept free text for revisions and loop back to options
|
|
543
543
|
|
|
@@ -545,7 +545,7 @@ If running with ultrathink enabled, or the platform's reasoning/effort level is
|
|
|
545
545
|
|
|
546
546
|
## Issue Creation
|
|
547
547
|
|
|
548
|
-
When the user selects "Create Issue", detect their project tracker from `
|
|
548
|
+
When the user selects "Create Issue", detect their project tracker from `AGENTS.md`:
|
|
549
549
|
|
|
550
550
|
1. Look for `project_tracker: github` or `project_tracker: linear`
|
|
551
551
|
2. If GitHub:
|
|
@@ -562,11 +562,10 @@ When the user selects "Create Issue", detect their project tracker from `CLAUDE.
|
|
|
562
562
|
|
|
563
563
|
4. If no tracker is configured:
|
|
564
564
|
- Ask which tracker they use using the platform's blocking question tool when available (see Interaction Method)
|
|
565
|
-
- Suggest adding the tracker to `
|
|
565
|
+
- Suggest adding the tracker to `AGENTS.md` for future runs
|
|
566
566
|
|
|
567
567
|
After issue creation:
|
|
568
568
|
- Display the issue URL
|
|
569
|
-
- Ask whether to proceed to `/
|
|
569
|
+
- Ask whether to proceed to `/ce:work`
|
|
570
570
|
|
|
571
571
|
NEVER CODE! Research, decide, and write the plan.
|
|
572
|
-
|