@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
|
@@ -0,0 +1,86 @@
|
|
|
1
|
+
import type { AgentConfig } from '@opencode-ai/sdk';
|
|
2
|
+
import type { SourcedOverlayConfigMap, SystematicConfig } from './config.js';
|
|
3
|
+
import { type PermissionSetting } from './validation.js';
|
|
4
|
+
/**
|
|
5
|
+
* Host-neutral asset plan: which agents, commands and enabled skills the
|
|
6
|
+
* plugin contributes, computed from the already-loaded Systematic config and
|
|
7
|
+
* the bundled asset directories.
|
|
8
|
+
*
|
|
9
|
+
* The plan never reads or writes a host config object and never loads
|
|
10
|
+
* `systematic.json` itself. Invalid config therefore stays a loader concern:
|
|
11
|
+
* on OpenCode v1 `loadConfigWithSources` throws before a plan is built.
|
|
12
|
+
*
|
|
13
|
+
* Permissions are an ordered list of triples, not an object map. A JS object
|
|
14
|
+
* hoists integer-like keys, so a map cannot carry a skills list such as
|
|
15
|
+
* `['10', 'alpha', '2']` in true insertion order. The v1 adapter folds the
|
|
16
|
+
* list into today's map; other adapters translate the list directly.
|
|
17
|
+
*/
|
|
18
|
+
/**
|
|
19
|
+
* One permission rule. Within a `permission`, rules apply in list order and
|
|
20
|
+
* the last matching rule wins, so a repeated pattern moves to the end.
|
|
21
|
+
*/
|
|
22
|
+
export interface PermissionRuleTriple {
|
|
23
|
+
permission: string;
|
|
24
|
+
pattern: string;
|
|
25
|
+
setting: PermissionSetting;
|
|
26
|
+
}
|
|
27
|
+
/**
|
|
28
|
+
* Permission state of a planned agent.
|
|
29
|
+
*
|
|
30
|
+
* - `unmanaged`: no overlay controls permissions. The agent's own
|
|
31
|
+
* `config.permission` (from its frontmatter) applies untouched.
|
|
32
|
+
* - `managed`: overlays control permissions. `rules` replaces
|
|
33
|
+
* `config.permission` entirely; an empty list means "no permission".
|
|
34
|
+
*/
|
|
35
|
+
export type PlannedAgentPermission = {
|
|
36
|
+
kind: 'unmanaged';
|
|
37
|
+
} | {
|
|
38
|
+
kind: 'managed';
|
|
39
|
+
rules: readonly PermissionRuleTriple[];
|
|
40
|
+
};
|
|
41
|
+
export interface PlannedAgent {
|
|
42
|
+
/** Emitted agent key (the bare agent name, category dropped). */
|
|
43
|
+
name: string;
|
|
44
|
+
/** Agent config with every overlay applied except a managed permission. */
|
|
45
|
+
config: AgentConfig;
|
|
46
|
+
permission: PlannedAgentPermission;
|
|
47
|
+
}
|
|
48
|
+
export interface PlannedCommand {
|
|
49
|
+
template: string;
|
|
50
|
+
description?: string;
|
|
51
|
+
agent?: string;
|
|
52
|
+
model?: string;
|
|
53
|
+
subtask?: boolean;
|
|
54
|
+
}
|
|
55
|
+
export interface AssetPlan {
|
|
56
|
+
/** Bundled skills directory, for hosts that register it for native discovery. */
|
|
57
|
+
skillsDir: string;
|
|
58
|
+
/** Bundled skill names that are not disabled. */
|
|
59
|
+
enabledSkills: readonly string[];
|
|
60
|
+
/** Agents keyed by emitted agent name, in discovery order. */
|
|
61
|
+
agents: Record<string, PlannedAgent>;
|
|
62
|
+
/** Commands keyed by emitted command name: bundled commands, then skills, then discovered skills. */
|
|
63
|
+
commands: Record<string, PlannedCommand>;
|
|
64
|
+
}
|
|
65
|
+
export interface AssetPlanInput {
|
|
66
|
+
/** Loaded Systematic config. The builder reads only the disabled lists and `skills_as_commands`. */
|
|
67
|
+
config: Pick<SystematicConfig, 'disabled_skills' | 'disabled_agents' | 'disabled_commands' | 'skills_as_commands'>;
|
|
68
|
+
overlays: SourcedOverlayConfigMap;
|
|
69
|
+
/** Agent names the user or host already owns. A bundled agent of the same name is not emitted. */
|
|
70
|
+
nativeAgentNames: readonly string[];
|
|
71
|
+
directory: string;
|
|
72
|
+
bundledSkillsDir: string;
|
|
73
|
+
bundledAgentsDir: string;
|
|
74
|
+
bundledCommandsDir: string;
|
|
75
|
+
homeDir: string;
|
|
76
|
+
opencodeConfigDir: string;
|
|
77
|
+
opencodeConfigDirOverride?: string;
|
|
78
|
+
}
|
|
79
|
+
export declare function toTitleCase(name: string): string;
|
|
80
|
+
export declare function formatAgentDescription(name: string, description: string | undefined): string;
|
|
81
|
+
/**
|
|
82
|
+
* Build the asset plan. The collection order below is load-bearing: warnings
|
|
83
|
+
* and diagnostics from the collectors reach the console in this order, and the
|
|
84
|
+
* v1 goldens pin them.
|
|
85
|
+
*/
|
|
86
|
+
export declare function buildAssetPlan(input: AssetPlanInput): AssetPlan;
|
package/dist/lib/bootstrap.d.ts
CHANGED
|
@@ -46,4 +46,21 @@ export declare function computeBootstrapContentSafe(deps: BootstrapDeps, reportE
|
|
|
46
46
|
/** Composes an existing system prompt with nullable bootstrap content; returns null when bootstrapContent is null. */
|
|
47
47
|
export declare function composeSystemPromptWithBootstrap(existingSystemPrompt: string, bootstrapContent: string | null): string | null;
|
|
48
48
|
export declare function getBootstrapContent(config: BootstrapContentConfig, deps: BootstrapDeps): string | null;
|
|
49
|
+
export interface BootstrapCompositionOptions {
|
|
50
|
+
bundledSkillsDir: string;
|
|
51
|
+
/** Harness profile name, read from `using-systematic/references/<profile>-profile.md`. */
|
|
52
|
+
profile: string;
|
|
53
|
+
/** Skill usage block. Omit to use the OpenCode v1 default. */
|
|
54
|
+
usageTemplate?: string;
|
|
55
|
+
}
|
|
56
|
+
/**
|
|
57
|
+
* Host-neutral bootstrap composition: reads the placement rule and the named
|
|
58
|
+
* harness profile from the packaged references, then composes the block.
|
|
59
|
+
*
|
|
60
|
+
* A host selects its profile and skill usage template here without touching
|
|
61
|
+
* another host's wiring. Read failures are logged by the readers and leave the
|
|
62
|
+
* section out, as before. Reading order (rule, then profile) is kept because
|
|
63
|
+
* it decides the order of any logged errors.
|
|
64
|
+
*/
|
|
65
|
+
export declare function composeBootstrapContent(config: BootstrapContentConfig, options: BootstrapCompositionOptions): string | null;
|
|
49
66
|
export {};
|
|
@@ -1,6 +1,8 @@
|
|
|
1
1
|
import type { Config } from '@opencode-ai/plugin';
|
|
2
2
|
import type { AgentConfig } from '@opencode-ai/sdk';
|
|
3
|
-
import { type
|
|
3
|
+
import { type PermissionRuleTriple, type PlannedAgent } from './asset-plan.js';
|
|
4
|
+
import type { PermissionSetting } from './validation.js';
|
|
5
|
+
export { formatAgentDescription, toTitleCase } from './asset-plan.js';
|
|
4
6
|
export interface ConfigHandlerDeps {
|
|
5
7
|
directory: string;
|
|
6
8
|
bundledSkillsDir: string;
|
|
@@ -11,10 +13,8 @@ export interface ConfigHandlerDeps {
|
|
|
11
13
|
/** OpenCode global config directory override for discovered-skill lookups. Defaults to `<homeDir>/.config/opencode`. */
|
|
12
14
|
opencodeConfigDir?: string;
|
|
13
15
|
}
|
|
14
|
-
export declare function toTitleCase(name: string): string;
|
|
15
|
-
export declare function formatAgentDescription(name: string, description: string | undefined): string;
|
|
16
16
|
/**
|
|
17
|
-
* Per-tool permission rule map as actually emitted by {@link
|
|
17
|
+
* Per-tool permission rule map as actually emitted by {@link foldPermissionRulesToV1Map}:
|
|
18
18
|
* each key is a match pattern (`'*'` or an exact name) mapped to a setting.
|
|
19
19
|
*/
|
|
20
20
|
export type AgentPermissionRuleMap = Record<string, PermissionSetting>;
|
|
@@ -23,14 +23,14 @@ export type AgentPermissionRuleMap = Record<string, PermissionSetting>;
|
|
|
23
23
|
* this module's boundary to include `skill`. The `@opencode-ai/sdk` v1 `Config`
|
|
24
24
|
* type this module targets omits `skill` from `AgentConfig['permission']`
|
|
25
25
|
* (it only appears on the SDK's v2 `PermissionRuleConfig` surface), but
|
|
26
|
-
* `
|
|
27
|
-
*
|
|
26
|
+
* `toV1AgentConfig` genuinely writes a `skill` rule map identical in shape
|
|
27
|
+
* to `bash`. This type documents and reads that
|
|
28
28
|
* real runtime shape without migrating the module to the v2 type surface.
|
|
29
29
|
*
|
|
30
|
-
* `
|
|
31
|
-
*
|
|
32
|
-
* `PermissionConfig` in validation.ts and the `task` overlay field applied
|
|
33
|
-
*
|
|
30
|
+
* `foldPermissionRulesToV1Map` emits a rule map for whatever permission key
|
|
31
|
+
* appears in the rule list — not just the named keys below (e.g. `task`, per
|
|
32
|
+
* `PermissionConfig` in validation.ts and the `task` overlay field applied in
|
|
33
|
+
* the asset plan's overlay pass). The named keys stay for documentation of
|
|
34
34
|
* the common cases; the index signature covers every other emitted tool key.
|
|
35
35
|
*/
|
|
36
36
|
export interface EmittedAgentPermission {
|
|
@@ -48,6 +48,26 @@ export interface EmittedAgentPermission {
|
|
|
48
48
|
* when a caller needs to observe the `skill` rule map this module writes.
|
|
49
49
|
*/
|
|
50
50
|
export declare function readEmittedAgentPermission(agent: AgentConfig | undefined): EmittedAgentPermission | undefined;
|
|
51
|
+
/**
|
|
52
|
+
* Fold the shared core's ordered permission list into the v1 object map.
|
|
53
|
+
*
|
|
54
|
+
* This is the v1-only step that loses information: a plain object hoists
|
|
55
|
+
* integer-like keys, so a skills list such as `['10', 'alpha', '2']` becomes
|
|
56
|
+
* `{2, 10, *, alpha}` here even though the list kept true insertion order.
|
|
57
|
+
* That hoisting is today's v1 behavior (pinned by the v1 golden tests) and is
|
|
58
|
+
* reproduced on purpose.
|
|
59
|
+
*
|
|
60
|
+
* A repeated permission and pattern is last-match-wins and moves to the end,
|
|
61
|
+
* as in the accumulator that produced the list. Returns `undefined` for an
|
|
62
|
+
* empty list.
|
|
63
|
+
*/
|
|
64
|
+
export declare function foldPermissionRulesToV1Map(rules: readonly PermissionRuleTriple[]): Record<string, Record<string, PermissionSetting>> | undefined;
|
|
65
|
+
/**
|
|
66
|
+
* Turn a planned agent into the v1 `config.agent` entry. A managed
|
|
67
|
+
* permission replaces the agent's own permission in place (key position is
|
|
68
|
+
* kept) or removes it when the folded map is empty.
|
|
69
|
+
*/
|
|
70
|
+
export declare function toV1AgentConfig(planned: PlannedAgent): AgentConfig;
|
|
51
71
|
/**
|
|
52
72
|
* Create the config hook handler for the Systematic plugin.
|
|
53
73
|
*
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
import type { Hooks, PluginInput } from '@opencode-ai/plugin';
|
|
2
|
+
export interface OpenCodeV1Deps {
|
|
3
|
+
/**
|
|
4
|
+
* Directory holding `skills/`, `agents/`, `commands/` and `package.json`.
|
|
5
|
+
*
|
|
6
|
+
* The caller supplies it because only the entry point knows where it sits
|
|
7
|
+
* relative to the package root: `src/index.ts` and the bundled `dist/*.js`
|
|
8
|
+
* chunks are both one level down, while this module is two levels down in
|
|
9
|
+
* source. Computing it here would break the built artifact.
|
|
10
|
+
*/
|
|
11
|
+
packageRoot: string;
|
|
12
|
+
}
|
|
13
|
+
/**
|
|
14
|
+
* OpenCode v1 adapter: wires the shared core into the five v1 hooks. Its output is
|
|
15
|
+
* pinned byte for byte by the v1 golden tests.
|
|
16
|
+
*/
|
|
17
|
+
export declare const createOpenCodeV1Hooks: ({ client, directory }: PluginInput, { packageRoot }: OpenCodeV1Deps) => Promise<Hooks>;
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
import type { V2Installer } from './opencode-v2.js';
|
|
2
|
+
/**
|
|
3
|
+
* The Systematic bootstrap on OpenCode v2.
|
|
4
|
+
*
|
|
5
|
+
* v2 has an instruction entry store: a keyed value per session that the host
|
|
6
|
+
* puts in the first system message as `<context key="...">`. Title requests
|
|
7
|
+
* leave it out, compaction and the requests after it carry it once, and
|
|
8
|
+
* putting the same value again changes nothing. So the bootstrap is one entry
|
|
9
|
+
* per session, and nothing edits the system prompt.
|
|
10
|
+
*
|
|
11
|
+
* The entry is put from the `prompt` hook, which fires for every admitted
|
|
12
|
+
* prompt: new, resumed and subagent sessions alike. The `session.created`
|
|
13
|
+
* event is not used. A plugin whose location is booted by the very
|
|
14
|
+
* `session.create` call never sees that event, so the first session after each
|
|
15
|
+
* service start would go without the bootstrap.
|
|
16
|
+
*
|
|
17
|
+
* A put that fails is reported and never thrown: a throwing `prompt` hook
|
|
18
|
+
* fails the prompt with an HTTP 500.
|
|
19
|
+
*
|
|
20
|
+
* Two host behaviors are accepted and documented rather than worked around:
|
|
21
|
+
* a bootstrap that changes between runs freezes the system block at the old
|
|
22
|
+
* text and adds a `<system-update>` message with the new one, and entries stay
|
|
23
|
+
* with their sessions after the plugin is removed.
|
|
24
|
+
*/
|
|
25
|
+
/** One stable key, so a changed bootstrap replaces the old value in place. */
|
|
26
|
+
export declare const BOOTSTRAP_ENTRY_KEY = "systematic.bootstrap";
|
|
27
|
+
/** The host rejects an entry value over 256 KiB of JSON. */
|
|
28
|
+
export declare const BOOTSTRAP_MAX_BYTES: number;
|
|
29
|
+
/**
|
|
30
|
+
* The skill usage block for v2. It names only what v2 registers:
|
|
31
|
+
* `systematic_skill` (with arguments) and the host's own `skill` tool, which
|
|
32
|
+
* takes only an id.
|
|
33
|
+
*/
|
|
34
|
+
export declare const OPENCODE_V2_USAGE_TEMPLATE = "**Skills naming:**\n- Systematic bundled skills use the `systematic:` prefix (e.g., `systematic:onboarding`)\n- Workflow skills with their own namespace keep it (e.g., `ce:brainstorm`)\n- Skills can also be invoked without prefix if unambiguous\n\n**Skills usage:**\n- Use `systematic_skill` to load Systematic bundled skills; pass `arguments` only when the user supplied them\n- Use the `skill` tool, which takes the skill `id`, for non-Systematic skills\n\n**Skills location:**\nBundled skills ship with the Systematic plugin and are discoverable via `systematic_skill`.";
|
|
35
|
+
/** The size the host measures: the JSON text of the value, in bytes. */
|
|
36
|
+
export declare function entryValueBytes(content: string): number;
|
|
37
|
+
export declare const installBootstrap: V2Installer;
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
import type { Plugin } from '@opencode/plugin';
|
|
2
|
+
import type { PlannedCommand } from './asset-plan.js';
|
|
3
|
+
import type { V2Installer } from './opencode-v2.js';
|
|
4
|
+
/**
|
|
5
|
+
* Systematic commands on OpenCode v2.
|
|
6
|
+
*
|
|
7
|
+
* A v2 plugin command receives the text typed after its name, untouched, and
|
|
8
|
+
* submits its own prompt. So this module does what OpenCode's own command path
|
|
9
|
+
* does for a stored command's text: expand `$ARGUMENTS` and `$1..$N`, then
|
|
10
|
+
* submit one prompt on the invoking session with the invocation's delivery and
|
|
11
|
+
* attachments. It never runs `!`-backtick blocks; their text stays literal in
|
|
12
|
+
* the prompt.
|
|
13
|
+
*
|
|
14
|
+
* It does not route. A v2 plugin command cannot choose an agent or a model for
|
|
15
|
+
* its prompt, and switching the session around the turn leaves the user's
|
|
16
|
+
* session changed. A command that declares `agent`, `model` or `subtask` is
|
|
17
|
+
* refused with a message instead; OpenCode commands written in Markdown or JSON
|
|
18
|
+
* can do that routing.
|
|
19
|
+
*/
|
|
20
|
+
type CommandEditor = Parameters<Parameters<Plugin.Context['command']['transform']>[0]>[0];
|
|
21
|
+
export type V2CommandDefinition = Parameters<CommandEditor['add']>[0];
|
|
22
|
+
export interface CommandRuntime {
|
|
23
|
+
ctx: Plugin.Context;
|
|
24
|
+
report: (message: string) => void;
|
|
25
|
+
/** Diagnostics already written, so a command run twice reports once. */
|
|
26
|
+
reported: Set<string>;
|
|
27
|
+
}
|
|
28
|
+
export declare function createCommandRuntime(ctx: Plugin.Context, report: (message: string) => void): CommandRuntime;
|
|
29
|
+
/**
|
|
30
|
+
* One command. A failure in `execute` is written to the log and thrown on: the
|
|
31
|
+
* host turns it into an error for whoever ran the command and keeps the plugin
|
|
32
|
+
* loaded, so the user hears about it. Swallowing it would not.
|
|
33
|
+
*/
|
|
34
|
+
export declare function buildCommand(runtime: CommandRuntime, name: string, planned: PlannedCommand): V2CommandDefinition;
|
|
35
|
+
export declare const installCommands: V2Installer;
|
|
36
|
+
export {};
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
import type { PermissionRuleTriple } from './asset-plan.js';
|
|
2
|
+
/**
|
|
3
|
+
* Translation from the shared asset plan's ordered permission triples to the
|
|
4
|
+
* rule list OpenCode v2 evaluates.
|
|
5
|
+
*
|
|
6
|
+
* The plan lists rules in true order, and v2 uses the same last-match-wins
|
|
7
|
+
* rule over an ordered list, so the translation is one rule per triple in the
|
|
8
|
+
* same order. Nothing is merged, sorted or de-duplicated here: integer-like
|
|
9
|
+
* skill ids keep their place (the v1 object fold cannot), and a managed skills
|
|
10
|
+
* list stays `deny *` followed by one allow per skill.
|
|
11
|
+
*
|
|
12
|
+
* Operations that touch several resources (a compound shell command) are
|
|
13
|
+
* denied when any resource is denied. The translation never depends on a later
|
|
14
|
+
* allow undoing an earlier deny across resources.
|
|
15
|
+
*/
|
|
16
|
+
export interface V2PermissionRule {
|
|
17
|
+
action: string;
|
|
18
|
+
resource: string;
|
|
19
|
+
effect: 'allow' | 'ask' | 'deny';
|
|
20
|
+
}
|
|
21
|
+
/**
|
|
22
|
+
* Ordered triples to v2 rules. Every other action name passes through
|
|
23
|
+
* unchanged: v2 action names are open strings, and `skill` carries the bare
|
|
24
|
+
* skill id as its resource.
|
|
25
|
+
*/
|
|
26
|
+
export declare function translatePermissionRules(rules: readonly PermissionRuleTriple[]): V2PermissionRule[];
|
|
27
|
+
/**
|
|
28
|
+
* A v1 permission object (`{edit: 'deny', bash: {'*': 'ask'}}`) as triples, in
|
|
29
|
+
* key order. A bare setting applies to `*`. Anything that is not a permission
|
|
30
|
+
* setting is ignored, as the v1 plan builder does.
|
|
31
|
+
*/
|
|
32
|
+
export declare function permissionMapToTriples(permission: unknown): PermissionRuleTriple[];
|
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
import type { V2Installer } from './opencode-v2.js';
|
|
2
|
+
import { type SkillOutputStore, type SkillToolDescriptor } from './skill-tool.js';
|
|
3
|
+
/**
|
|
4
|
+
* Skills on OpenCode v2: the enabled bundled skills are registered with the
|
|
5
|
+
* host so its native `skill` tool and `<available_skills>` list see them, and
|
|
6
|
+
* `systematic_skill` is ported through the tool domain because the native tool
|
|
7
|
+
* takes only an id: it cannot pass `$ARGUMENTS`.
|
|
8
|
+
*
|
|
9
|
+
* The host cuts a tool result at 2000 lines or 51200 bytes after the plugin
|
|
10
|
+
* has returned it, and three bundled skills are larger. The full text is kept
|
|
11
|
+
* by call id and put back into the request before each model call.
|
|
12
|
+
*/
|
|
13
|
+
/** The part of a v2 skill this module writes. The host's own skill type is assignable to it. */
|
|
14
|
+
export interface V2SkillRecord {
|
|
15
|
+
id: string;
|
|
16
|
+
name: string;
|
|
17
|
+
description?: string;
|
|
18
|
+
autoinvoke?: boolean;
|
|
19
|
+
path: string;
|
|
20
|
+
content: string;
|
|
21
|
+
}
|
|
22
|
+
export interface V2SkillEditor {
|
|
23
|
+
get(id: string): unknown;
|
|
24
|
+
add(skill: V2SkillRecord): void;
|
|
25
|
+
}
|
|
26
|
+
/** What `execute` receives. The host's own context type is assignable to it. */
|
|
27
|
+
export interface V2ToolContext {
|
|
28
|
+
sessionID: string;
|
|
29
|
+
agent: string;
|
|
30
|
+
messageID: string;
|
|
31
|
+
id: string;
|
|
32
|
+
progress(update: Record<string, unknown>): Promise<void>;
|
|
33
|
+
}
|
|
34
|
+
export interface V2ToolDefinition {
|
|
35
|
+
name: string;
|
|
36
|
+
description: string;
|
|
37
|
+
input: SkillToolDescriptor['input'];
|
|
38
|
+
options: {
|
|
39
|
+
codemode: false;
|
|
40
|
+
};
|
|
41
|
+
execute(input: unknown, context: V2ToolContext): Promise<{
|
|
42
|
+
content: string;
|
|
43
|
+
metadata: Record<string, unknown>;
|
|
44
|
+
}>;
|
|
45
|
+
}
|
|
46
|
+
export interface V2ToolEditor {
|
|
47
|
+
get(id: string): unknown;
|
|
48
|
+
add(tool: V2ToolDefinition): void;
|
|
49
|
+
}
|
|
50
|
+
/** The enabled bundled skills as v2 records, in name order. */
|
|
51
|
+
export declare function readBundledSkills(bundledSkillsDir: string, enabledSkills: readonly string[], report: (message: string) => void): V2SkillRecord[];
|
|
52
|
+
/**
|
|
53
|
+
* Add one skill to a transform editor. An id that already exists belongs to an
|
|
54
|
+
* earlier plugin and is left alone. A user or on-disk skill of the same id
|
|
55
|
+
* replaces this one after every plugin transform has run, and that cannot be
|
|
56
|
+
* seen from here, so it is silent.
|
|
57
|
+
*/
|
|
58
|
+
export declare function addBundledSkill(editor: V2SkillEditor, skill: V2SkillRecord, reported: Set<string>, report: (message: string) => void): void;
|
|
59
|
+
/**
|
|
60
|
+
* Put the full text back into the tool results of a model request. Matching is
|
|
61
|
+
* by session, tool name and call id. Nothing depends on the host's marker
|
|
62
|
+
* text. The store is read, not emptied: the host builds each request from
|
|
63
|
+
* history, so the same result is restored on every later request.
|
|
64
|
+
*/
|
|
65
|
+
export declare function restoreSkillResults(store: SkillOutputStore, event: unknown): void;
|
|
66
|
+
export declare const installSkills: V2Installer;
|
|
@@ -0,0 +1,96 @@
|
|
|
1
|
+
import type { Plugin } from '@opencode/plugin';
|
|
2
|
+
import { type AssetPlan, type PlannedAgent } from './asset-plan.js';
|
|
3
|
+
import { type SystematicConfig } from './config.js';
|
|
4
|
+
import { type V2PermissionRule } from './opencode-v2-permissions.js';
|
|
5
|
+
export interface SafeGuard {
|
|
6
|
+
/** Wraps a synchronous callback. A throw is reported and the call returns `undefined`. */
|
|
7
|
+
sync<Args extends unknown[], Result>(label: string, callback: (...args: Args) => Result): (...args: Args) => Result | undefined;
|
|
8
|
+
/** Wraps an async callback. A throw or rejection is reported and the call resolves to `undefined`. */
|
|
9
|
+
async<Args extends unknown[], Result>(label: string, callback: (...args: Args) => Promise<Result> | Result): (...args: Args) => Promise<Result | undefined>;
|
|
10
|
+
}
|
|
11
|
+
/** Builds the never-throw wrapper that every installer and registered callback runs through. */
|
|
12
|
+
export declare function createSafeGuard(): SafeGuard;
|
|
13
|
+
/** Everything the installers share. Built once per `setup`, frozen, never rebuilt. */
|
|
14
|
+
export interface V2Snapshot {
|
|
15
|
+
readonly config: SystematicConfig;
|
|
16
|
+
readonly plan: AssetPlan;
|
|
17
|
+
/** The composed bootstrap block, or `null` when bootstrap is disabled or empty. */
|
|
18
|
+
readonly bootstrapContent: string | null;
|
|
19
|
+
/** The project directory the config was loaded for. */
|
|
20
|
+
readonly directory: string;
|
|
21
|
+
readonly packageRoot: string;
|
|
22
|
+
}
|
|
23
|
+
export interface V2InstallInput {
|
|
24
|
+
readonly ctx: Plugin.Context;
|
|
25
|
+
readonly snapshot: V2Snapshot;
|
|
26
|
+
/** Wrap every callback registered with the host in this guard. */
|
|
27
|
+
readonly guard: SafeGuard;
|
|
28
|
+
/** Writes one `systematic:`-prefixed diagnostic line. */
|
|
29
|
+
readonly report: (message: string) => void;
|
|
30
|
+
}
|
|
31
|
+
export type V2Installer = (input: V2InstallInput) => Promise<void> | void;
|
|
32
|
+
export interface V2Installers {
|
|
33
|
+
agents: V2Installer;
|
|
34
|
+
skills: V2Installer;
|
|
35
|
+
commands: V2Installer;
|
|
36
|
+
bootstrap: V2Installer;
|
|
37
|
+
}
|
|
38
|
+
/**
|
|
39
|
+
* The part of a v2 agent this module reads and writes. The host's own agent
|
|
40
|
+
* type is wider; it is assignable to this one, so no cast is needed.
|
|
41
|
+
*/
|
|
42
|
+
export interface V2AgentRecord {
|
|
43
|
+
system?: string;
|
|
44
|
+
description?: string;
|
|
45
|
+
mode: 'primary' | 'subagent' | 'all';
|
|
46
|
+
hidden: boolean;
|
|
47
|
+
color?: string;
|
|
48
|
+
steps?: number;
|
|
49
|
+
model?: {
|
|
50
|
+
providerID: string;
|
|
51
|
+
id: string;
|
|
52
|
+
variant?: string;
|
|
53
|
+
};
|
|
54
|
+
request: {
|
|
55
|
+
body: Record<string, unknown>;
|
|
56
|
+
};
|
|
57
|
+
permissions: V2PermissionRule[];
|
|
58
|
+
}
|
|
59
|
+
export interface V2AgentEditor {
|
|
60
|
+
get(id: string): unknown;
|
|
61
|
+
update(id: string, update: (agent: V2AgentRecord) => void): void;
|
|
62
|
+
}
|
|
63
|
+
/**
|
|
64
|
+
* Create one planned agent on a transform editor. An id that already exists
|
|
65
|
+
* belongs to the host or another plugin and is left alone. A same-named user
|
|
66
|
+
* agent needs no check: user config applies after every plugin transform and
|
|
67
|
+
* overlays what is created here.
|
|
68
|
+
*/
|
|
69
|
+
export declare function applyPlannedAgent(editor: V2AgentEditor, planned: PlannedAgent, reported?: Set<string>): void;
|
|
70
|
+
/**
|
|
71
|
+
* Registers the planned agents through one transform. Each agent runs under
|
|
72
|
+
* its own guard, so one failing `update` leaves the others registered. The
|
|
73
|
+
* diagnostic set belongs to this `setup`; it only keeps a replay from
|
|
74
|
+
* repeating a message and never changes what a replay produces.
|
|
75
|
+
*/
|
|
76
|
+
export declare const installAgents: V2Installer;
|
|
77
|
+
export interface OpenCodeV2Deps {
|
|
78
|
+
/**
|
|
79
|
+
* Directory holding `skills/`, `agents/`, `commands/` and `package.json`.
|
|
80
|
+
* Supplied by the entry point for the same reason as on v1: only the entry
|
|
81
|
+
* point knows how far below the package root it sits.
|
|
82
|
+
*/
|
|
83
|
+
packageRoot: string;
|
|
84
|
+
/** Home directory for user-level config and skill discovery. Defaults to `os.homedir()`; tests inject a temp dir. */
|
|
85
|
+
homeDir?: string;
|
|
86
|
+
/** User-level OpenCode config directory. Defaults to `<homeDir>/.config/opencode`. */
|
|
87
|
+
opencodeConfigDir?: string;
|
|
88
|
+
/** Replaces individual installer slots. Slots left out use the domain's own installer. */
|
|
89
|
+
installers?: Partial<V2Installers>;
|
|
90
|
+
}
|
|
91
|
+
/**
|
|
92
|
+
* Runs the v2 `setup` for one location: one config load, one snapshot, then
|
|
93
|
+
* each installer in turn. Rejects on invalid config. An installer failure is
|
|
94
|
+
* reported and never stops the next installer.
|
|
95
|
+
*/
|
|
96
|
+
export declare function setupOpenCodeV2(ctx: Plugin.Context, deps: OpenCodeV2Deps): Promise<void>;
|
package/dist/lib/skill-tool.d.ts
CHANGED
|
@@ -4,7 +4,10 @@ export { discoverSkillFiles } from './skill-resolver.js';
|
|
|
4
4
|
export declare const SKILL_TOOL_NAME = "systematic_skill";
|
|
5
5
|
export interface SkillOutputStore {
|
|
6
6
|
put(sessionID: string, callID: string, output: string): void;
|
|
7
|
+
/** Returns the entry and removes it. */
|
|
7
8
|
take(sessionID: string, callID: string): string | undefined;
|
|
9
|
+
/** Returns the entry and keeps it, for hosts that read the same output on every request. */
|
|
10
|
+
peek(sessionID: string, callID: string): string | undefined;
|
|
8
11
|
}
|
|
9
12
|
interface SkillOutputStoreOptions {
|
|
10
13
|
maxEntries?: number;
|
|
@@ -31,3 +34,46 @@ export interface SkillToolOptions {
|
|
|
31
34
|
outputStore?: SkillOutputStore;
|
|
32
35
|
}
|
|
33
36
|
export declare function createSkillTool(options: SkillToolOptions): ToolDefinition;
|
|
37
|
+
export interface SkillToolInput {
|
|
38
|
+
name: string;
|
|
39
|
+
arguments?: string;
|
|
40
|
+
}
|
|
41
|
+
export interface LoadedSkillOutput {
|
|
42
|
+
/** The bare skill name: the permission resource, whichever form was asked for. */
|
|
43
|
+
skillName: string;
|
|
44
|
+
/** The `systematic:`-prefixed form, as shown to the user and the model. */
|
|
45
|
+
prefixedName: string;
|
|
46
|
+
/** `Loaded skill: <prefixed name>`, for progress reporting. */
|
|
47
|
+
title: string;
|
|
48
|
+
/** The `<skill_content>` text the model receives. */
|
|
49
|
+
output: string;
|
|
50
|
+
/** The skill's base directory. */
|
|
51
|
+
dir: string;
|
|
52
|
+
}
|
|
53
|
+
/**
|
|
54
|
+
* A host-neutral description of the skill tool, with no zod and no host import.
|
|
55
|
+
* An adapter whose host takes JSON Schema (OpenCode v2) registers `input`
|
|
56
|
+
* as is and calls `load` from its own `execute`. `load` throws the shared
|
|
57
|
+
* not-found error, which is also what a disabled skill gets.
|
|
58
|
+
*/
|
|
59
|
+
export interface SkillToolDescriptor {
|
|
60
|
+
name: typeof SKILL_TOOL_NAME;
|
|
61
|
+
description: string;
|
|
62
|
+
input: {
|
|
63
|
+
type: 'object';
|
|
64
|
+
properties: {
|
|
65
|
+
name: {
|
|
66
|
+
type: 'string';
|
|
67
|
+
description: string;
|
|
68
|
+
};
|
|
69
|
+
arguments: {
|
|
70
|
+
type: 'string';
|
|
71
|
+
description: string;
|
|
72
|
+
};
|
|
73
|
+
};
|
|
74
|
+
required: ['name'];
|
|
75
|
+
additionalProperties: false;
|
|
76
|
+
};
|
|
77
|
+
load(args: SkillToolInput): LoadedSkillOutput;
|
|
78
|
+
}
|
|
79
|
+
export declare function createSkillToolDescriptor(options: Pick<SkillToolOptions, 'bundledSkillsDir' | 'disabledSkills'>): SkillToolDescriptor;
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@fro.bot/systematic",
|
|
3
|
-
"version": "3.
|
|
3
|
+
"version": "3.27.0",
|
|
4
4
|
"description": "Compound-engineering loops for OpenCode, Pi, and Claude Code",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"homepage": "https://fro.bot/systematic",
|
|
@@ -39,7 +39,7 @@
|
|
|
39
39
|
],
|
|
40
40
|
"scripts": {
|
|
41
41
|
"clean": "rimraf dist",
|
|
42
|
-
"build": "bun run clean && bun build src/index.ts src/cli.ts --outdir dist --target bun --splitting --external @opencode-ai/plugin --external js-yaml && bun build src/pi.ts --outdir dist --target node --external @earendil-works/pi-coding-agent --external typebox --external jsonc-parser && tsc --emitDeclarationOnly && bun scripts/build-pi-package-agents.ts",
|
|
42
|
+
"build": "bun run clean && bun build src/index.ts src/cli.ts --outdir dist --target bun --splitting --external @opencode-ai/plugin --external @opencode/plugin --external js-yaml && bun build src/pi.ts --outdir dist --target node --external @earendil-works/pi-coding-agent --external typebox --external jsonc-parser && tsc --emitDeclarationOnly && bun scripts/build-pi-package-agents.ts",
|
|
43
43
|
"dev": "bun --watch src/index.ts",
|
|
44
44
|
"test": "bun test tests/unit",
|
|
45
45
|
"test:integration": "bun test tests/integration",
|
|
@@ -53,6 +53,8 @@
|
|
|
53
53
|
"docs:build": "bun run docs:generate && bun run --cwd docs build",
|
|
54
54
|
"docs:preview": "bun run --cwd docs preview",
|
|
55
55
|
"docs:verify": "bun install --frozen-lockfile && bun run --cwd docs playwright install --with-deps chromium && bun run docs:build",
|
|
56
|
+
"config-reference:generate": "bun docs/scripts/generate-config-reference.ts",
|
|
57
|
+
"config-reference:drift": "bun docs/scripts/generate-config-reference.ts --check",
|
|
56
58
|
"docs:generate": "bun docs/scripts/generate-stats.ts && bun docs/scripts/transform-content.ts && bun scripts/generate-config-schema.ts && bun docs/scripts/generate-config-reference.ts && bun docs/scripts/generate-release-notes.ts && bun docs/scripts/generate-changelog-page.ts",
|
|
57
59
|
"schema:generate": "bun scripts/generate-config-schema.ts",
|
|
58
60
|
"schema:drift": "bun scripts/generate-config-schema.ts --check",
|
|
@@ -62,11 +64,17 @@
|
|
|
62
64
|
"ce-review-validator:drift": "bun scripts/generate-ce-review-validator.ts --check",
|
|
63
65
|
"agent-browser:build": "bun scripts/generate-agent-browser-skill.ts",
|
|
64
66
|
"agent-browser:drift": "bun scripts/generate-agent-browser-skill.ts --check",
|
|
67
|
+
"pi-personas:generate": "bun scripts/generate-pi-subagents-personas.ts",
|
|
68
|
+
"pi-personas:drift": "bun scripts/generate-pi-subagents-personas.ts --check",
|
|
65
69
|
"registry:build": "bun scripts/build-registry.ts",
|
|
70
|
+
"registry:generate": "bun scripts/generate-registry.ts",
|
|
66
71
|
"registry:drift": "bun scripts/generate-registry.ts --check",
|
|
67
72
|
"registry:validate": "bun scripts/build-registry.ts --validate-only",
|
|
73
|
+
"surfaces:regen": "bun scripts/generated-surfaces.ts regen",
|
|
74
|
+
"surfaces:drift": "bun scripts/generated-surfaces.ts drift",
|
|
75
|
+
"surfaces:affected": "bun scripts/generated-surfaces.ts affected",
|
|
68
76
|
"claude-code:build": "bun scripts/build-claude-code-plugin.ts",
|
|
69
|
-
"postupgrade": "bun run build && bun run
|
|
77
|
+
"postupgrade": "bun run build && bun run surfaces:regen",
|
|
70
78
|
"prepublishOnly": "bun run build && bun run schema:generate"
|
|
71
79
|
},
|
|
72
80
|
"keywords": [
|
|
@@ -87,7 +95,8 @@
|
|
|
87
95
|
"node": ">=18"
|
|
88
96
|
},
|
|
89
97
|
"peerDependencies": {
|
|
90
|
-
"@opencode-ai/plugin": "
|
|
98
|
+
"@opencode-ai/plugin": ">=1.18.29",
|
|
99
|
+
"@opencode/plugin": ">=2.2.0",
|
|
91
100
|
"@earendil-works/pi-coding-agent": "^1.0.0",
|
|
92
101
|
"typebox": "^1.1.38"
|
|
93
102
|
},
|
|
@@ -95,6 +104,9 @@
|
|
|
95
104
|
"@opencode-ai/plugin": {
|
|
96
105
|
"optional": true
|
|
97
106
|
},
|
|
107
|
+
"@opencode/plugin": {
|
|
108
|
+
"optional": true
|
|
109
|
+
},
|
|
98
110
|
"@earendil-works/pi-coding-agent": {
|
|
99
111
|
"optional": true
|
|
100
112
|
},
|
|
@@ -103,10 +115,13 @@
|
|
|
103
115
|
}
|
|
104
116
|
},
|
|
105
117
|
"devDependencies": {
|
|
106
|
-
"@biomejs/biome": "2.6.
|
|
118
|
+
"@biomejs/biome": "2.6.3",
|
|
107
119
|
"@earendil-works/pi-coding-agent": "1.4.0",
|
|
108
120
|
"@opencode-ai/plugin": "1.19.4",
|
|
109
121
|
"@opencode-ai/sdk": "1.19.4",
|
|
122
|
+
"@opencode/client": "2.2.0",
|
|
123
|
+
"@opencode/plugin": "2.2.0",
|
|
124
|
+
"@opencode/sdk": "2.2.0",
|
|
110
125
|
"@semantic-release/exec": "7.1.0",
|
|
111
126
|
"@tintinweb/pi-subagents": "0.22.0",
|
|
112
127
|
"@types/bun": "latest",
|
|
@@ -95,7 +95,7 @@ Launch research subagents. Each returns text data to the orchestrator.
|
|
|
95
95
|
- **Knowledge track**: applies_when (symptoms/root_cause/resolution_type optional)
|
|
96
96
|
- Incorporates auto memory excerpts (if provided by the orchestrator) as supplementary evidence
|
|
97
97
|
- Reads `references/yaml-schema.md` for category mapping into `docs/solutions/`
|
|
98
|
-
- Suggests a filename using the pattern `[sanitized-
|
|
98
|
+
- Suggests a filename using the pattern `[sanitized-slug]-[YYYY-MM-DD].md`, where the slug is the symptom for bug-track docs and a short title of the guidance for knowledge-track docs
|
|
99
99
|
- Returns: YAML frontmatter skeleton (must include `category:` field mapped from problem_type), category directory path, suggested filename, and which track applies
|
|
100
100
|
- Does not invent enum values, categories, or frontmatter fields from memory; reads the schema and mapping files above
|
|
101
101
|
- Does not force bug-track fields onto knowledge-track learnings or vice versa
|
|
@@ -133,7 +133,7 @@ Launch research subagents. Each returns text data to the orchestrator.
|
|
|
133
133
|
- **Low**: 0-1 dimensions match — related but distinct
|
|
134
134
|
|
|
135
135
|
The score is a function of the count, not a separate judgment about how related the docs feel. Two docs on the same topic that match on one dimension score Low. When the score you are inclined to write disagrees with the count, the count wins.
|
|
136
|
-
- Returns: Links, relationships, refresh candidates, and overlap assessment.
|
|
136
|
+
- Returns: Links, relationships, refresh candidates, and overlap assessment. Ask for the overlap assessment in the dispatch and take it back as one `Overlap:` line per compared doc (the researcher's format), with the per-dimension verdicts first, then the count, then the score, in that order. Phase 2 reads the score from those lines. Two consistency checks apply in sequence and both must hold: the score follows the count, and the recommendation follows the score. High overlap means update the existing doc, so an assessment that scores High while recommending a new doc has broken the second check even if the first one held. Either break is a defect to re-derive, not a nuance to note.
|
|
137
137
|
|
|
138
138
|
**Search strategy (grep-first filtering for efficiency):**
|
|
139
139
|
|
|
@@ -164,7 +164,7 @@ Launch research subagents. Each returns text data to the orchestrator.
|
|
|
164
164
|
The orchestrating agent (main conversation) performs these steps:
|
|
165
165
|
|
|
166
166
|
1. Collect all text results from Phase 1 subagents
|
|
167
|
-
2. **Check the overlap assessment** from the Related Docs Finder before deciding what to write:
|
|
167
|
+
2. **Check the overlap assessment** from the Related Docs Finder (the `score=` value of its `Overlap:` lines) before deciding what to write:
|
|
168
168
|
|
|
169
169
|
| Overlap | Action |
|
|
170
170
|
|---------|--------|
|
|
@@ -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]
|