@fro.bot/systematic 2.6.1 → 2.7.0

package/agents/review/api-contract-reviewer.md

@@ -1,6 +1,7 @@
 ---
 name: api-contract-reviewer
 description: Conditional code-review persona, selected when the diff touches API routes, request/response types, serialization, versioning, or exported type signatures. Reviews code for breaking contract changes.
+model: inherit
 tools: Read, Grep, Glob, Bash
 color: blue
 mode: subagent
@@ -46,4 +47,3 @@ Return your findings as JSON matching the findings schema. No prose outside the
   "testing_gaps": []
 }
 ```
-

package/agents/review/correctness-reviewer.md

@@ -1,6 +1,7 @@
 ---
 name: correctness-reviewer
 description: Always-on code-review persona. Reviews code for logic errors, edge cases, state management bugs, error propagation failures, and intent-vs-implementation mismatches.
+model: inherit
 tools: Read, Grep, Glob, Bash
 color: blue
 mode: subagent
@@ -46,4 +47,3 @@ Return your findings as JSON matching the findings schema. No prose outside the
   "testing_gaps": []
 }
 ```
-

package/agents/review/data-migrations-reviewer.md

@@ -1,6 +1,7 @@
 ---
 name: data-migrations-reviewer
 description: Conditional code-review persona, selected when the diff touches migration files, schema changes, data transformations, or backfill scripts. Reviews code for data integrity and migration safety.
+model: inherit
 tools: Read, Grep, Glob, Bash
 color: blue
 mode: subagent
@@ -50,4 +51,3 @@ Return your findings as JSON matching the findings schema. No prose outside the
   "testing_gaps": []
 }
 ```
-

package/agents/review/dhh-rails-reviewer.md

@@ -1,6 +1,7 @@
 ---
 name: dhh-rails-reviewer
 description: Conditional code-review persona, selected when Rails diffs introduce architectural choices, abstractions, or frontend patterns that may fight the framework. Reviews code from an opinionated DHH perspective.
+model: inherit
 tools: Read, Grep, Glob, Bash
 color: blue
 mode: subagent
@@ -44,4 +45,3 @@ Return your findings as JSON matching the findings schema. No prose outside the
   "testing_gaps": []
 }
 ```
-

package/agents/review/julik-frontend-races-reviewer.md

@@ -1,6 +1,7 @@
 ---
 name: julik-frontend-races-reviewer
 description: Conditional code-review persona, selected when the diff touches async UI code, Stimulus/Turbo lifecycles, or DOM-timing-sensitive frontend behavior. Reviews code for race conditions and janky UI failure modes.
+model: inherit
 tools: Read, Grep, Glob, Bash
 color: blue
 mode: subagent
@@ -47,4 +48,3 @@ Return your findings as JSON matching the findings schema. No prose outside the
 ```
 
 Discourage the user from pulling in too many dependencies, explaining that the job is to first understand the race conditions, and then pick a tool for removing them. That tool is usually just a dozen lines, if not less - no need to pull in half of NPM for that.
-

package/agents/review/kieran-python-reviewer.md

@@ -1,6 +1,7 @@
 ---
 name: kieran-python-reviewer
 description: Conditional code-review persona, selected when the diff touches Python code. Reviews changes with Kieran's strict bar for Pythonic clarity, type hints, and maintainability.
+model: inherit
 tools: Read, Grep, Glob, Bash
 color: blue
 mode: subagent
@@ -45,4 +46,3 @@ Return your findings as JSON matching the findings schema. No prose outside the
   "testing_gaps": []
 }
 ```
-

package/agents/review/kieran-rails-reviewer.md

@@ -1,6 +1,7 @@
 ---
 name: kieran-rails-reviewer
 description: Conditional code-review persona, selected when the diff touches Rails application code. Reviews Rails changes with Kieran's strict bar for clarity, conventions, and maintainability.
+model: inherit
 tools: Read, Grep, Glob, Bash
 color: blue
 mode: subagent
@@ -45,4 +46,3 @@ Return your findings as JSON matching the findings schema. No prose outside the
   "testing_gaps": []
 }
 ```
-

package/agents/review/kieran-typescript-reviewer.md

@@ -1,6 +1,7 @@
 ---
 name: kieran-typescript-reviewer
 description: Conditional code-review persona, selected when the diff touches TypeScript code. Reviews changes with Kieran's strict bar for type safety, clarity, and maintainability.
+model: inherit
 tools: Read, Grep, Glob, Bash
 color: blue
 mode: subagent
@@ -45,4 +46,3 @@ Return your findings as JSON matching the findings schema. No prose outside the
   "testing_gaps": []
 }
 ```
-

package/agents/review/maintainability-reviewer.md

@@ -1,6 +1,7 @@
 ---
 name: maintainability-reviewer
 description: Always-on code-review persona. Reviews code for premature abstraction, unnecessary indirection, dead code, coupling between unrelated modules, and naming that obscures intent.
+model: inherit
 tools: Read, Grep, Glob, Bash
 color: blue
 mode: subagent
@@ -46,4 +47,3 @@ Return your findings as JSON matching the findings schema. No prose outside the
   "testing_gaps": []
 }
 ```
-

package/agents/review/performance-reviewer.md

@@ -1,6 +1,7 @@
 ---
 name: performance-reviewer
 description: Conditional code-review persona, selected when the diff touches database queries, loop-heavy data transforms, caching layers, or I/O-intensive paths. Reviews code for runtime performance and scalability issues.
+model: inherit
 tools: Read, Grep, Glob, Bash
 color: blue
 mode: subagent
@@ -48,4 +49,3 @@ Return your findings as JSON matching the findings schema. No prose outside the
   "testing_gaps": []
 }
 ```
-

package/agents/review/reliability-reviewer.md

@@ -1,6 +1,7 @@
 ---
 name: reliability-reviewer
 description: Conditional code-review persona, selected when the diff touches error handling, retries, circuit breakers, timeouts, health checks, background jobs, or async handlers. Reviews code for production reliability and failure modes.
+model: inherit
 tools: Read, Grep, Glob, Bash
 color: blue
 mode: subagent
@@ -46,4 +47,3 @@ Return your findings as JSON matching the findings schema. No prose outside the
   "testing_gaps": []
 }
 ```
-

package/agents/review/security-reviewer.md

@@ -1,6 +1,7 @@
 ---
 name: security-reviewer
 description: Conditional code-review persona, selected when the diff touches auth middleware, public endpoints, user input handling, or permission checks. Reviews code for exploitable vulnerabilities.
+model: inherit
 tools: Read, Grep, Glob, Bash
 color: blue
 mode: subagent
@@ -48,4 +49,3 @@ Return your findings as JSON matching the findings schema. No prose outside the
   "testing_gaps": []
 }
 ```
-

package/agents/workflow/bug-reproduction-validator.md

@@ -1,6 +1,7 @@
 ---
 name: bug-reproduction-validator
 description: Systematically reproduces and validates bug reports to confirm whether reported behavior is an actual bug. Use when you receive a bug report or issue that needs verification.
+model: inherit
 mode: subagent
 temperature: 0.1
 ---
@@ -81,4 +82,3 @@ Key Principles:
 - If you cannot reproduce after reasonable attempts, clearly state what you tried
 
 When you cannot access certain resources or need additional information, explicitly state what would help validate the bug further. Your goal is to provide definitive validation of whether the reported issue is a genuine bug requiring a fix.
-

package/dist/cli.js

@@ -6,7 +6,7 @@ import {
   findCommandsInDir,
   findSkillsInDir,
   getConfigPaths
-} from "./index-3h7kpmfa.js";
+} from "./index-k9tdxh0p.js";
 
 // src/cli.ts
 import fs from "fs";

package/dist/{index-3h7kpmfa.js → index-k9tdxh0p.js}

@@ -1436,7 +1436,7 @@ function extractFrontmatter(filePath) {
       metadata,
       disableModelInvocation: extractBoolean(data, "disable-model-invocation"),
       userInvocable: extractBoolean(data, "user-invocable"),
-      subtask: data.context === "fork" ? true : undefined,
+      subtask: data.context === "fork" ? true : extractBoolean(data, "subtask") ?? undefined,
       agent: extractNonEmptyString(data, "agent"),
       model: extractNonEmptyString(data, "model"),
       argumentHint: argumentHint !== "" ? argumentHint : undefined,

package/dist/index.d.ts

@@ -1,3 +1,3 @@
 import type { Plugin } from '@opencode-ai/plugin';
-export declare const SystematicPlugin: Plugin;
+declare const SystematicPlugin: Plugin;
 export default SystematicPlugin;

package/dist/index.js

@@ -8,7 +8,7 @@ import {
   findSkillsInDir,
   loadConfig,
   parseFrontmatter
-} from "./index-3h7kpmfa.js";
+} from "./index-k9tdxh0p.js";
 
 // src/index.ts
 import fs3 from "fs";
@@ -553,6 +553,5 @@ var SystematicPlugin = async ({ client, directory }) => {
 };
 var src_default = SystematicPlugin;
 export {
-  src_default as default,
-  SystematicPlugin
+  src_default as default
 };

package/dist/lib/skills.d.ts

@@ -28,5 +28,6 @@ export interface SkillInfo {
     argumentHint?: string;
     allowedTools?: string;
 }
+export declare const SKILL_FRONTMATTER_FIELDS: readonly ["name", "description", "argument-hint", "disable-model-invocation", "allowed-tools", "license", "compatibility", "metadata", "user-invocable", "agent", "model", "context", "subtask"];
 export declare function extractFrontmatter(filePath: string): SkillFrontmatter;
 export declare function findSkillsInDir(dir: string, maxDepth?: number): SkillInfo[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fro.bot/systematic",
-  "version": "2.6.1",
+  "version": "2.7.0",
   "description": "Structured engineering workflows for OpenCode",
   "type": "module",
   "homepage": "https://fro.bot/systematic",

package/skills/compound-docs/SKILL.md

@@ -7,9 +7,6 @@ allowed-tools:
   - Write
   - Bash
   - Grep
-preconditions:
-  - Problem has been solved (not in-progress)
-  - Solution has been verified working
 ---
 
 # compound-docs Skill
@@ -22,6 +19,8 @@ This skill captures problem solutions immediately after confirmation, creating s
 
 **Organization:** Single-file architecture - each problem documented as one markdown file in its symptom category directory (e.g., `docs/solutions/performance-issues/n-plus-one-briefs.md`). Files use YAML frontmatter for metadata and searchability.
 
+**Prerequisites:** The problem has been solved and the solution has been verified working. Do not document in-progress investigations as finalized solutions.
+
 ---
 
 <critical_sequence name="documentation-capture" enforce_order="strict">

package/skills/writing-systematic-skills/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: writing-systematic-skills
+description: Use when creating, editing, auditing, or fixing bundled Systematic skills, especially when authoring SKILL.md files, adding skill reference files, resolving content-integrity frontmatter failures, or deciding which Systematic conventions apply beyond the general writing-skills guidance.
+---
+
+# Writing Systematic Skills
+
+Systematic skills are OpenCode-native workflow assets. Use this skill after loading the general `writing-skills` foundation; this file only covers the Systematic-specific delta.
+
+## When To Use
+
+Use this skill when you are:
+
+- Creating a new bundled skill under `skills/`
+- Editing an existing bundled skill's frontmatter or file layout
+- Fixing content-integrity frontmatter or sub-file failures
+- Deciding whether a skill needs references, scripts, assets, or templates
+- Auditing bundled skills for provider-portable defaults
+
+Do not use this as a replacement for `~/.agents/skills/writing-skills/SKILL.md`. Load that foundation first when authoring or substantially editing skill content.
+
+## Foundation
+
+`writing-skills` supplies the authoring discipline: pressure scenarios, clear trigger-oriented descriptions, concise bodies, and reference files only when depth earns its keep.
+
+Systematic adds repository-specific constraints:
+
+- Runtime-recognized frontmatter fields are fixed by the skill loader.
+- Skill sub-files live in a small set of conventional directories.
+- Bundled agents must use provider-portable model defaults.
+- Content-integrity enforces the mechanical parts in CI.
+
+For worked examples and judgment calls, read `references/foundation-conventions.md`.
+
+## Frontmatter Rules
+
+Every bundled skill must have YAML frontmatter with:
+
+- `name` - unprefixed skill identifier. The loader adds the `systematic:` command prefix automatically unless the skill intentionally belongs to another namespace such as `ce:`.
+- `description` - third-person trigger conditions. Prefer `Use when...`; describe when to load the skill, not its internal workflow.
+
+Optional fields are allowed only when the runtime loader recognizes them:
+
+| Field | Use |
+|---|---|
+| `argument-hint` | Shows expected invocation arguments. |
+| `disable-model-invocation` | Prevents direct model invocation for dispatcher-style skills. |
+| `allowed-tools` | Declares tool constraints for skill execution. |
+| `license` | Carries skill licensing metadata. |
+| `compatibility` | Notes platform or version compatibility. |
+| `metadata` | String-only metadata map. |
+| `user-invocable` | Marks whether users should invoke the skill directly. |
+| `agent` | Selects a companion agent when the loader supports it. |
+| `model` | Selects a model for skill execution when justified. |
+| `context` | Use `fork` when the skill should run in forked subtask context. |
+| `subtask` | Explicit forked-subtask marker recognized by the runtime. |
+
+`preconditions` is banned. It has no runtime consumer. Put prerequisite guidance in the skill body instead.
+
+## File Layout
+
+The required entry point is:
+
+```text
+skills/<skill-name>/SKILL.md
+```
+
+Optional sub-files must live under one of these directories:
+
+- `references/` - deeper guidance, decision tables, long examples, or API notes
+- `scripts/` - executable helpers an agent can run
+- `assets/` - static files used by the skill
+- `templates/` - reusable stubs or document templates
+
+Keep the main `SKILL.md` small enough to decide whether and how to proceed. Move heavy detail to `references/`, and cite it with a repo-local path such as `references/foundation-conventions.md` so the sub-file integrity gate can verify it exists.
+
+## Identity Defaults
+
+Bundled agents must declare:
+
+```yaml
+model: inherit
+```
+
+Hardcoded provider model IDs break users who do not use that provider. Use `model: inherit` unless a future design explicitly proves a provider-specific dependency and documents the tradeoff.
+
+For agent or API attribution, `ai:systematic` is the machine ID used by Systematic-owned operations, such as Proof's `by` field and `X-Agent-Id` header. It is not a skill cross-reference convention.
+
+## Validator
+
+Run the content-integrity gate before shipping skill changes:
+
+```bash
+bun 'scripts/content-integrity.ts'
+```
+
+The gate checks:
+
+- Skill frontmatter is present and uses only runtime-recognized fields.
+- Required `name` and `description` fields are non-empty.
+- Banned frontmatter such as `preconditions` is absent.
+- Bundled agents use `model: inherit`.
+- Skill references to `references/`, `scripts/`, `assets/`, and `templates/` resolve on disk.
+
+If the gate fails, fix the content rather than broadening the validator unless the runtime loader contract has actually changed.
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---|---|
+| Adding a new frontmatter field because it reads well | Add body prose instead, unless the runtime loader consumes the field. |
+| Summarizing the whole workflow in `description` | Describe trigger conditions only. |
+| Adding provider-specific agent models | Use `model: inherit`. |
+| Linking to a non-existent reference file | Create the file or remove the link. |
+| Duplicating the general writing-skills guidance | Link to the foundation and document only the Systematic delta. |

package/skills/writing-systematic-skills/references/foundation-conventions.md

@@ -0,0 +1,143 @@
+# Foundation Conventions
+
+This reference expands the Systematic-specific rules from `SKILL.md`. The mechanical rules are enforced by `bun scripts/content-integrity.ts`; this file explains the judgment calls behind them.
+
+## Frontmatter
+
+Systematic skill frontmatter mirrors what the runtime loader actually reads. Do not invent fields for documentation structure. If the loader does not consume the field, put the information in the body.
+
+| Field | Required | When To Use | Example |
+|---|---:|---|---|
+| `name` | Yes | Every skill. Use the unprefixed skill identifier unless another namespace is intentional. | `name: writing-systematic-skills` |
+| `description` | Yes | Trigger-oriented discovery text. Third person. Prefer `Use when...`. | `description: Use when fixing bundled skill frontmatter failures...` |
+| `argument-hint` | No | The skill accepts meaningful invocation arguments. | `argument-hint: "[path/to/document.md]"` |
+| `disable-model-invocation` | No | Dispatcher or routing skills that should not be directly model-invoked. | `disable-model-invocation: true` |
+| `allowed-tools` | No | The skill needs an explicit tool allowlist. | `allowed-tools: Bash, Read` |
+| `license` | No | Licensing metadata matters for distribution. | `license: MIT` |
+| `compatibility` | No | A platform or version caveat is real and useful. | `compatibility: OpenCode` |
+| `metadata` | No | String-only metadata map. Keep it boring. | `metadata: { owner: systematic }` |
+| `user-invocable` | No | Direct user invocation should be explicitly advertised or suppressed. | `user-invocable: false` |
+| `agent` | No | A loader-supported companion agent is required. | `agent: general` |
+| `model` | No | A skill-level model choice is justified. Prefer inheritance elsewhere. | `model: inherit` |
+| `context` | No | Forked execution is required. `fork` derives subtask behavior at runtime. | `context: fork` |
+| `subtask` | No | Explicit forked-subtask dispatch marker. | `subtask: true` |
+
+### Required Fields
+
+`name` and `description` must be present. Empty strings are not valid values. Bare YAML keys such as `name:` parse as null and count as missing.
+
+### Banned Field
+
+`preconditions` is banned because it has no runtime consumer. Use a body section instead:
+
+```markdown
+## Prerequisites
+
+Only run this skill after the bug is reproduced and the fix has been verified.
+```
+
+### Runtime-Recognized Forking Fields
+
+`context: fork` and `subtask: true` are allowed. They are runtime-recognized and must not be treated as idiosyncratic frontmatter.
+
+Use them only when the skill genuinely needs forked subtask behavior. Do not cargo-cult them onto normal skills.
+
+### Description Style
+
+Good descriptions answer: should the agent load this skill now?
+
+Good:
+
+```yaml
+description: Use when creating, editing, auditing, or fixing bundled Systematic skills, especially when authoring SKILL.md files or resolving content-integrity frontmatter failures.
+```
+
+Bad:
+
+```yaml
+description: This skill explains frontmatter, file layout, validation, and identity defaults for Systematic skills.
+```
+
+The bad version describes content. The good version describes trigger conditions.
+
+## File Layout
+
+Every skill has exactly one entry point:
+
+```text
+skills/<skill-name>/SKILL.md
+```
+
+Use sub-files only when the content is too bulky or operationally distinct for the main skill.
+
+```text
+skills/<skill-name>/
+├── SKILL.md
+├── references/
+│   └── detailed-guidance.md
+├── scripts/
+│   └── helper.mjs
+├── assets/
+│   └── diagram.svg
+└── templates/
+    └── output-template.md
+```
+
+### Directory Choices
+
+| Directory | Use For | Do Not Use For |
+|---|---|---|
+| `references/` | Long explanations, decision tables, extended examples | Required setup that must be read before deciding to use the skill |
+| `scripts/` | Executable helpers the agent can run | Pseudocode or prose examples |
+| `assets/` | Static images, fixtures, or other bundled files | Markdown guidance that belongs in `references/` |
+| `templates/` | Fillable documents, prompts, or output stubs | Examples that should not be copied verbatim |
+
+### Sub-File Links
+
+When `SKILL.md` mentions a sub-file path, the content-integrity gate verifies it exists. Prefer direct repo-local paths:
+
+```markdown
+Read `references/foundation-conventions.md` for examples.
+```
+
+Avoid ambiguous references such as "the conventions doc". They are harder for agents to follow and impossible for the gate to verify.
+
+## Identity Defaults
+
+### Bundled Agent Model
+
+Bundled agents must use:
+
+```yaml
+model: inherit
+```
+
+This keeps Systematic provider-portable. Hardcoded provider IDs make an agent unusable for users on other providers and are almost never worth the lock-in.
+
+If a future agent truly depends on a specific provider, document the constraint in the plan and get explicit review before adding the hardcoded model.
+
+### Machine ID
+
+`ai:systematic` is a machine identity string for Systematic-owned operations. Proof uses it as the `by` field on operations and the `X-Agent-Id` header. Keep it lowercase and stable.
+
+Do not use `ai:systematic` as a skill-reference pattern. Skill and agent references use their own namespaces, such as `systematic:writing-systematic-skills` or `systematic:research:best-practices-researcher`.
+
+### Public-Facing Voice
+
+Skill text should be reusable guidance, not a session transcript. Avoid first-person process narration, internal note IDs, and references to how a particular implementation session unfolded.
+
+## Validator Workflow
+
+Run:
+
+```bash
+bun scripts/content-integrity.ts --verbose
+```
+
+Use the output as the source of truth for cleanup. If a violation surprises you, check the runtime loader before changing the validator:
+
+- Skill frontmatter rules mirror `src/lib/skills.ts`.
+- YAML parsing behavior comes from `src/lib/frontmatter.ts`.
+- Sub-file directories come from `SUBFILE_DIRECTORY_NAMES` in `scripts/content-integrity.ts`.
+
+When the runtime contract changes, update the loader and validator together. A validator allow-list that drifts from the loader creates false failures or misses real runtime-invisible fields.