@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.
@@ -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. When in doubt between Keep and Delete, ask the user (in interactive mode) or mark as stale (in autofix mode). But missing referenced files with no matching code is **not** a doubt case — it is strong, unambiguous Delete evidence. Auto-delete it.
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 subdirectory]
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 subdirectory]
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-symptom-or-title]-[module]-[YYYYMMDD].md`
141
+ Format: `[sanitized-slug]-[YYYY-MM-DD].md`
142
142
 
143
- Bug-track docs name the file after the symptom. Knowledge-track docs have no symptom, so they use a short sanitized title of the guidance.
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-ReportService-20251110.md` (bug track)
155
- - `parameter-not-saving-state-Checkout-20251110.md` (bug track)
156
- - `webview-crash-on-resize-Assistant-20251110.md` (bug track)
157
- - `prefer-explicit-request-timeouts-HttpClient-20251110.md` (knowledge track)
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-ReportService-20251110.md`
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-ReportService-20251110.md`
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-ReportService-20251110.md
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 subdirectory]
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 subdirectory]
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
- **If you are not OpenCode**, skip to the "Context fallback" section below and run the command there to gather context.
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
- **If you are OpenCode, skip this section — the data above is already available.**
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). All data needed for this step is already available -- do not re-run those commands.
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
- **If you are not OpenCode**, skip to the "Context fallback" section below and run the command there to gather context.
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
- **If you are OpenCode, skip this section — the data above is already available.**
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. All data needed for this step and Step 3 is already available -- do not re-run those commands.
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.