@fro.bot/systematic 3.26.3 → 3.27.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 +55 -15
- package/README.md +8 -2
- package/agents/research/learnings-researcher.md +5 -0
- package/dist/cli.js +2 -2
- package/dist/{index-1dyb2x0z.js → index-608preny.js} +1 -1
- package/dist/index.d.ts +7 -3
- package/dist/index.js +742 -93
- package/dist/lib/asset-plan.d.ts +86 -0
- package/dist/lib/bootstrap.d.ts +17 -0
- package/dist/lib/config-handler.d.ts +30 -10
- package/dist/lib/opencode-v1.d.ts +17 -0
- package/dist/lib/opencode-v2-bootstrap.d.ts +37 -0
- package/dist/lib/opencode-v2-commands.d.ts +36 -0
- package/dist/lib/opencode-v2-permissions.d.ts +32 -0
- package/dist/lib/opencode-v2-skills.d.ts +66 -0
- package/dist/lib/opencode-v2.d.ts +96 -0
- package/dist/lib/skill-tool.d.ts +46 -0
- package/package.json +20 -5
- package/skills/ce-compound/SKILL.md +3 -3
- package/skills/ce-compound/assets/resolution-template.md +2 -2
- package/skills/ce-compound-refresh/SKILL.md +1 -1
- package/skills/ce-compound-refresh/assets/resolution-template.md +2 -2
- package/skills/compound-docs/SKILL.md +9 -9
- package/skills/compound-docs/assets/resolution-template.md +2 -2
- package/skills/git-commit/SKILL.md +3 -5
- package/skills/git-commit-push-pr/SKILL.md +3 -5
- package/skills/using-systematic/references/opencode-v2-profile.md +75 -0
|
@@ -82,7 +82,7 @@ For each candidate artifact, classify it into one of five outcomes:
|
|
|
82
82
|
- the user has provided enough concrete replacement context to document the successor honestly, or
|
|
83
83
|
- the codebase investigation found the current approach and can document it as the successor, or
|
|
84
84
|
- newer docs, pattern docs, PRs, or issues provide strong successor evidence.
|
|
85
|
-
8. **Delete when the code is gone.** If the referenced code, module, or workflow no longer exists in the codebase and no successor can be found, delete the file — don't default to Keep just because the general advice is still "sound." A learning about a deleted feature misleads readers into thinking that feature still exists.
|
|
85
|
+
8. **Delete when the code is gone.** If the referenced code, module, or workflow no longer exists in the codebase and no successor can be found, delete the file — don't default to Keep just because the general advice is still "sound." A learning about a deleted feature misleads readers into thinking that feature still exists. A missing referenced file with no matching code is strong evidence that the implementation is gone, not proof that the learning is obsolete. Before deleting, apply the problem-domain check in Phase 2 ("Before deleting"): if the problem domain is gone too, Delete; if it persists, Replace. When in doubt between Keep and Delete, ask the user (in interactive mode) or mark as stale (in autofix mode).
|
|
86
86
|
9. **Evaluate document-set design, not just accuracy.** In addition to checking whether each doc is accurate, evaluate whether it is still the right unit of knowledge. If two or more docs overlap heavily, determine whether they should remain separate, be cross-scoped more clearly, or be consolidated into one canonical document. Redundant docs are dangerous because they drift silently — two docs saying the same thing will eventually say different things.
|
|
87
87
|
10. **Delete, don't archive.** There is no `_archived/` directory. When a doc is no longer useful, delete it. Git history preserves every deleted file — that is the archive. A dedicated archive directory creates problems: archived docs accumulate, pollute search results, and nobody reads them. If someone needs a deleted doc, `git log --diff-filter=D -- docs/solutions/` will find it.
|
|
88
88
|
11. **Preserve legacy values.** Existing docs may carry values that `references/schema.yaml` lists under `legacy_values` (older `component` values, the `root_cause` and `resolution_type` values listed there) and the version field that the schema marks LEGACY. They are valid. Do not report them as off-vocabulary and do not rewrite them. Only a new doc, such as a Replace successor, reads the offered `values`.
|
|
@@ -14,7 +14,7 @@ Use for: `build_error`, `test_failure`, `runtime_error`, `performance_issue`, `d
|
|
|
14
14
|
---
|
|
15
15
|
title: [Clear problem title]
|
|
16
16
|
date: [YYYY-MM-DD]
|
|
17
|
-
category: [docs/solutions
|
|
17
|
+
category: [directory name under docs/solutions/, e.g. best-practices]
|
|
18
18
|
module: [Module or area]
|
|
19
19
|
problem_type: [schema enum]
|
|
20
20
|
component: [schema enum]
|
|
@@ -60,7 +60,7 @@ Use for: `best_practice`, `documentation_gap`, `workflow_issue`, `developer_expe
|
|
|
60
60
|
---
|
|
61
61
|
title: [Clear, descriptive title]
|
|
62
62
|
date: [YYYY-MM-DD]
|
|
63
|
-
category: [docs/solutions
|
|
63
|
+
category: [directory name under docs/solutions/, e.g. best-practices]
|
|
64
64
|
module: [Module or area]
|
|
65
65
|
problem_type: [schema enum]
|
|
66
66
|
component: [schema enum]
|
|
@@ -138,9 +138,9 @@ Proceed directly to Step 4 (no user interaction needed).
|
|
|
138
138
|
<step number="4" required="true" depends_on="2">
|
|
139
139
|
### Step 4: Generate Filename
|
|
140
140
|
|
|
141
|
-
Format: `[sanitized-
|
|
141
|
+
Format: `[sanitized-slug]-[YYYY-MM-DD].md`
|
|
142
142
|
|
|
143
|
-
|
|
143
|
+
The slug is the symptom for bug-track docs. Knowledge-track docs have no symptom, so the slug is a short sanitized title of the guidance.
|
|
144
144
|
|
|
145
145
|
**Sanitization rules:**
|
|
146
146
|
|
|
@@ -151,10 +151,10 @@ Bug-track docs name the file after the symptom. Knowledge-track docs have no sym
|
|
|
151
151
|
|
|
152
152
|
**Examples:**
|
|
153
153
|
|
|
154
|
-
- `n-plus-one-report-generation-
|
|
155
|
-
- `parameter-not-saving-state-
|
|
156
|
-
- `webview-crash-on-resize-
|
|
157
|
-
- `prefer-explicit-request-timeouts-
|
|
154
|
+
- `n-plus-one-report-generation-2025-11-10.md` (bug track)
|
|
155
|
+
- `parameter-not-saving-state-2025-11-10.md` (bug track)
|
|
156
|
+
- `webview-crash-on-resize-2025-11-10.md` (bug track)
|
|
157
|
+
- `prefer-explicit-request-timeouts-2025-11-10.md` (knowledge track)
|
|
158
158
|
</step>
|
|
159
159
|
|
|
160
160
|
<step number="5" required="true" depends_on="4" blocking="true">
|
|
@@ -418,7 +418,7 @@ Documentation is successful when ALL of the following are true:
|
|
|
418
418
|
- Solution: Loaded the comments for all reports in one eager-loaded query
|
|
419
419
|
- Root cause: Missing eager loading causing a separate database query per comment thread
|
|
420
420
|
3. **Check existing:** No similar issue found
|
|
421
|
-
4. **Generate filename:** `n-plus-one-report-generation-
|
|
421
|
+
4. **Generate filename:** `n-plus-one-report-generation-2025-11-10.md`
|
|
422
422
|
5. **Validate YAML:**
|
|
423
423
|
```yaml
|
|
424
424
|
module: Report Service
|
|
@@ -434,7 +434,7 @@ Documentation is successful when ALL of the following are true:
|
|
|
434
434
|
```
|
|
435
435
|
✅ Valid
|
|
436
436
|
6. **Create documentation:**
|
|
437
|
-
- `docs/solutions/performance-issues/n-plus-one-report-generation-
|
|
437
|
+
- `docs/solutions/performance-issues/n-plus-one-report-generation-2025-11-10.md`
|
|
438
438
|
7. **Cross-reference:** None needed (no similar issues)
|
|
439
439
|
|
|
440
440
|
**Output:**
|
|
@@ -443,7 +443,7 @@ Documentation is successful when ALL of the following are true:
|
|
|
443
443
|
✓ Solution documented
|
|
444
444
|
|
|
445
445
|
File created:
|
|
446
|
-
- docs/solutions/performance-issues/n-plus-one-report-generation-
|
|
446
|
+
- docs/solutions/performance-issues/n-plus-one-report-generation-2025-11-10.md
|
|
447
447
|
|
|
448
448
|
What's next?
|
|
449
449
|
1. Continue workflow (recommended)
|
|
@@ -14,7 +14,7 @@ Use for: `build_error`, `test_failure`, `runtime_error`, `performance_issue`, `d
|
|
|
14
14
|
---
|
|
15
15
|
title: [Clear problem title]
|
|
16
16
|
date: [YYYY-MM-DD]
|
|
17
|
-
category: [docs/solutions
|
|
17
|
+
category: [directory name under docs/solutions/, e.g. best-practices]
|
|
18
18
|
module: [Module or area]
|
|
19
19
|
problem_type: [schema enum]
|
|
20
20
|
component: [schema enum]
|
|
@@ -60,7 +60,7 @@ Use for: `best_practice`, `documentation_gap`, `workflow_issue`, `developer_expe
|
|
|
60
60
|
---
|
|
61
61
|
title: [Clear, descriptive title]
|
|
62
62
|
date: [YYYY-MM-DD]
|
|
63
|
-
category: [docs/solutions
|
|
63
|
+
category: [directory name under docs/solutions/, e.g. best-practices]
|
|
64
64
|
module: [Module or area]
|
|
65
65
|
problem_type: [schema enum]
|
|
66
66
|
component: [schema enum]
|
|
@@ -9,9 +9,7 @@ Create a single, well-crafted git commit from the current working tree changes.
|
|
|
9
9
|
|
|
10
10
|
## Context
|
|
11
11
|
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
**If you are OpenCode**, the five labeled sections below (Git status, Working tree diff, Current branch, Recent commits, Remote default branch) contain pre-populated data. Use them directly throughout this skill -- do not re-run these commands.
|
|
12
|
+
The five labeled sections below (Git status, Working tree diff, Current branch, Recent commits, Remote default branch) may be filled in by the host before you read them. If any section is empty, or still shows its raw command line instead of output, the host did not run the commands: run the command in the "Context fallback" section below and use its output instead. Otherwise, use the data directly throughout this skill and do not re-run these commands.
|
|
15
13
|
|
|
16
14
|
**Git status:**
|
|
17
15
|
!`git status`
|
|
@@ -30,7 +28,7 @@ Create a single, well-crafted git commit from the current working tree changes.
|
|
|
30
28
|
|
|
31
29
|
### Context fallback
|
|
32
30
|
|
|
33
|
-
**
|
|
31
|
+
**Run this only when the sections above are empty or still show raw command lines.**
|
|
34
32
|
|
|
35
33
|
Run this single command to gather all context:
|
|
36
34
|
|
|
@@ -44,7 +42,7 @@ printf '=== STATUS ===\n'; git status; printf '\n=== DIFF ===\n'; git diff HEAD;
|
|
|
44
42
|
|
|
45
43
|
### Step 1: Gather context
|
|
46
44
|
|
|
47
|
-
Use the context above (git status, working tree diff, current branch, recent commits, remote default branch)
|
|
45
|
+
Use the context above (git status, working tree diff, current branch, recent commits, remote default branch), or the output of the Context fallback command if the sections were empty. Do not re-run commands whose output you already have.
|
|
48
46
|
|
|
49
47
|
The remote default branch value returns something like `origin/main`. Strip the `origin/` prefix to get the branch name. If it returned `__DEFAULT_BRANCH_UNRESOLVED__` or a bare `HEAD`, try:
|
|
50
48
|
|
|
@@ -17,9 +17,7 @@ For description-only updates, follow the Description Update workflow below. Othe
|
|
|
17
17
|
|
|
18
18
|
## Context
|
|
19
19
|
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
**If you are OpenCode**, the six labeled sections below contain pre-populated data. Use them directly -- do not re-run these commands.
|
|
20
|
+
The six labeled sections below (Git status, Working tree diff, Current branch, Recent commits, Remote default branch, Existing PR check) may be filled in by the host before you read them. If any section is empty, or still shows its raw command line instead of output, the host did not run the commands: run the command in the "Context fallback" section below and use its output instead. Otherwise, use the data directly throughout this skill and do not re-run these commands.
|
|
23
21
|
|
|
24
22
|
**Git status:**
|
|
25
23
|
!`git status`
|
|
@@ -41,7 +39,7 @@ For description-only updates, follow the Description Update workflow below. Othe
|
|
|
41
39
|
|
|
42
40
|
### Context fallback
|
|
43
41
|
|
|
44
|
-
**
|
|
42
|
+
**Run this only when the sections above are empty or still show raw command lines.**
|
|
45
43
|
|
|
46
44
|
Run this single command to gather all context:
|
|
47
45
|
|
|
@@ -110,7 +108,7 @@ Report the PR URL.
|
|
|
110
108
|
|
|
111
109
|
### Step 1: Gather context
|
|
112
110
|
|
|
113
|
-
Use the context above
|
|
111
|
+
Use the context above, or the output of the Context fallback command if the sections were empty. This covers this step and Step 3. Do not re-run commands whose output you already have.
|
|
114
112
|
|
|
115
113
|
The remote default branch value returns something like `origin/main`. Strip the `origin/` prefix. If it returned `DEFAULT_BRANCH_UNRESOLVED` or a bare `HEAD`, try:
|
|
116
114
|
|
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
# OpenCode v2 Capability Profile
|
|
2
|
+
|
|
3
|
+
Evidence registry: see [`HARNESSES.md`](../../../HARNESSES.md).
|
|
4
|
+
|
|
5
|
+
| Capability | Mechanism | Status | Fallback |
|
|
6
|
+
|---|---|---|---|
|
|
7
|
+
| Subagent delegation | `subagent` tool; `agent` selects a specialist, `sessionID` resumes a session, `background: true` runs it asynchronously | supported; foreground by default | Dispatch in the foreground, serially or in small batches |
|
|
8
|
+
| Blocking user interaction | `question` tool | supported | Present numbered options in chat and wait |
|
|
9
|
+
| Task tracking | `todowrite` tool | conditional: only offered when the host's experimental `todo` option is on | Maintain a visible task list in responses |
|
|
10
|
+
| Skill loading | `systematic_skill` for bundled skills, with arguments; `skill` tool (by `id`) for non-Systematic skills | supported | Read the skill instructions listed by the active harness |
|
|
11
|
+
|
|
12
|
+
## Invocation examples
|
|
13
|
+
|
|
14
|
+
### Subagent delegation
|
|
15
|
+
|
|
16
|
+
```typescript
|
|
17
|
+
subagent({
|
|
18
|
+
agent: "systematic-implementer",
|
|
19
|
+
description: "Implement auth module",
|
|
20
|
+
prompt: "Implement the auth module and return the changed files.",
|
|
21
|
+
})
|
|
22
|
+
|
|
23
|
+
// Background dispatch (a background run returns immediately; its result is available later):
|
|
24
|
+
subagent({
|
|
25
|
+
agent: "repo-research-analyst",
|
|
26
|
+
description: "Map fixture patterns",
|
|
27
|
+
prompt: "…",
|
|
28
|
+
background: true,
|
|
29
|
+
})
|
|
30
|
+
|
|
31
|
+
// Resume a prior specialist session:
|
|
32
|
+
subagent({ agent: "systematic-implementer", sessionID: "<prior-session-id>", description: "Resume the implementation task", prompt: "…" })
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
Skill text that names OpenCode's `task` tool with `subagent_type` means the `subagent` tool with `agent` on this host, and `task_id` means `sessionID`.
|
|
36
|
+
|
|
37
|
+
`agent` takes a bare agent stem — OpenCode registers bundled agents under
|
|
38
|
+
their filename stem, not a namespaced identifier. Prose that *refers* to an agent
|
|
39
|
+
uses the canonical `systematic:<category>:<name>` form instead, which the
|
|
40
|
+
content-integrity gate validates against real agent files. Leave `model` unset
|
|
41
|
+
unless the user names a model.
|
|
42
|
+
|
|
43
|
+
Both forms are enforced. Examples in bundled content must name agents this
|
|
44
|
+
package actually ships, so they work for every reader. A host may provide
|
|
45
|
+
additional agents through the user's own configuration; those are available at
|
|
46
|
+
runtime but must not appear in bundled examples.
|
|
47
|
+
|
|
48
|
+
### Blocking user interaction
|
|
49
|
+
|
|
50
|
+
```typescript
|
|
51
|
+
question({
|
|
52
|
+
questions: [{ question: "Which deployment target should I use?", header: "Deployment target",
|
|
53
|
+
options: [{ label: "Staging", description: "Deploy to staging" }] }],
|
|
54
|
+
})
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
### Task tracking
|
|
58
|
+
|
|
59
|
+
```typescript
|
|
60
|
+
todowrite({
|
|
61
|
+
todos: [{ content: "Run validation", status: "pending" }],
|
|
62
|
+
})
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
`status` is one of `pending`, `in_progress`, `completed`, `cancelled`. When `todowrite` is not offered, keep the task list in your responses instead.
|
|
66
|
+
|
|
67
|
+
### Skill loading
|
|
68
|
+
|
|
69
|
+
```typescript
|
|
70
|
+
systematic_skill({ name: "systematic:using-systematic" })
|
|
71
|
+
systematic_skill({ name: "systematic:reproduce-bug", arguments: "ISSUE-123" })
|
|
72
|
+
skill({ id: "external-skill" })
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
Pass `arguments` to `systematic_skill` only when the user supplied them; the `skill` tool takes no arguments.
|