@fro.bot/systematic 2.33.3 → 3.0.0

package/ATTRIBUTIONS.md

@@ -35,7 +35,7 @@ The two `SKILL.md` files (`skills/test-driven-development/SKILL.md` and `skills/
 
 - Adaptation was light: rewrote upstream's `@filename` force-load syntax to repo-local `references/` paths; rewrote `superpowers:<skill-name>` namespace cross-references to bare names (matching Systematic's runtime convention where the `systematic:` prefix is applied at load time); swapped `~/.claude/skills` path mentions to the canonical OpenCode path `~/.agents/skills/`; renamed the `CLAUDE_MD_TESTING.md` worked example to `skill-testing-walkthrough.md` to fit Systematic's descriptive-filename convention.
 - Per-file copyright comments are deliberately omitted. Frontmatter `license: MIT` plus this attribution file constitute the full attribution surface.
-- These files are load-bearing for `ce:work`, `ce:plan`, and `writing-systematic-skills` cross-references. Future contributors editing them should preserve the discipline-enforcing prose (e.g., the Iron Law, the rationalization tables, the RED-GREEN-REFACTOR cycle).
+- These files are load-bearing for `ce:work`, `ce:plan`, and the "Systematic Bundled Skills" section of `writing-skills` itself. Future contributors editing them should preserve the discipline-enforcing prose (e.g., the Iron Law, the rationalization tables, the RED-GREEN-REFACTOR cycle).
 
 ### Future refresh discipline
 

package/agents/design/design-iterator.md

@@ -4,6 +4,7 @@ description: "Iteratively refines UI design through N screenshot-analyze-improve
 color: accent
 mode: subagent
 temperature: 0.6
+tools: Read, Grep, Glob, Edit, Write, Bash
 ---
 
 You are an expert UI/UX design iterator specializing in systematic, progressive refinement of web components. Your methodology combines visual analysis, competitor research, and incremental improvements to transform ordinary interfaces into polished, professional designs.

package/agents/research/best-practices-researcher.md

@@ -25,13 +25,11 @@ Before going online, check if curated knowledge already exists in skills:
 
 2. **Identify Relevant Skills**:
    Match the research topic to available skills. Common mappings:
-   - Rails/Ruby → `dhh-rails-style`, `andrew-kane-gem-writer`, `dspy-ruby`
-   - Frontend/Design → `frontend-design`, `swiss-design`
-   - TypeScript/React → `react-best-practices`
+   - Frontend/Design → `frontend-design`
    - AI/Agents → `agent-native-architecture`
-  - Documentation → `ce:compound`, `every-style-editor`
-   - File operations → `rclone`, `git-worktree`
-   - Image generation → `gemini-imagegen`
+   - Documentation → `ce:compound`, `compound-docs`
+   - Git workflows → `git-worktree`, `git-commit-push-pr`
+   - Testing → `test-driven-development`, `test-browser`
 
 3. **Extract Patterns from Skills**:
    - Read the full content of relevant SKILL.md files
@@ -83,7 +81,7 @@ Only after checking skills AND verifying API availability, gather additional inf
 
 2. **Organize Discoveries**:
    - Organize into clear categories (e.g., "Must Have", "Recommended", "Optional")
-   - Clearly indicate source: "From skill: dhh-rails-style" vs "From official docs" vs "Community consensus"
+   - Clearly indicate source: "From skill: frontend-design" vs "From official docs" vs "Community consensus"
    - Provide specific examples from real projects when possible
    - Explain the reasoning behind each best practice
    - Highlight any technology-specific or domain-specific considerations
@@ -106,7 +104,7 @@ For GitHub issue best practices specifically, you will research:
 ## Source Attribution
 
 Always cite your sources and indicate the authority level:
-- **Skill-based**: "The dhh-rails-style skill recommends..." (highest authority - curated)
+- **Skill-based**: "The frontend-design skill recommends..." (highest authority - curated)
 - **Official docs**: "Official GitHub documentation recommends..."
 - **Community**: "Many successful projects tend to..."
 

package/agents/review/pattern-recognition-specialist.md

@@ -36,7 +36,7 @@ Your primary responsibilities:
 
 Your workflow:
 
-1. Start with a broad pattern search using the built-in Grep tool (or `ast-grep` for structural AST matching when needed)
+1. Start with a broad pattern search using the built-in grep tool (or `ast-grep` for structural AST matching when needed)
 2. Compile a comprehensive list of identified patterns and their locations
 3. Search for common anti-pattern indicators (TODO, FIXME, HACK, XXX)
 4. Analyze naming conventions by sampling representative files

package/agents/workflow/systematic-implementer.md

@@ -3,6 +3,7 @@ name: systematic-implementer
 description: Implements one plan unit in a fresh subagent context and reports bounded changes back to the orchestrator.
 mode: subagent
 temperature: 0.2
+tools: Read, Grep, Glob, Edit, Write, Bash
 ---
 
 You are a focused implementer dispatched by a parent OpenCode session orchestrating a multi-unit plan. You implement one unit's worth of changes and report back to the orchestrator.

package/dist/cli.js

@@ -1,22 +1,323 @@
 #!/usr/bin/env node
 // @bun
 import {
-  convertContent,
+  applyEdits,
   findAgentsInDir,
   findCommandsInDir,
   findSkillsInDir,
-  getConfigPaths
-} from "./index-vyzhzvap.js";
+  getConfigPaths,
+  modify,
+  parse,
+  parseTree
+} from "./index-yskzf7vh.js";
 
 // src/cli.ts
+import fs2 from "fs";
+import path2 from "path";
+
+// src/lib/setup.ts
 import fs from "fs";
 import path from "path";
+var SYSTEMATIC_PACKAGE_NAME = "@fro.bot/systematic";
+var PI_PACKAGE_IDENTIFIER = `npm:${SYSTEMATIC_PACKAGE_NAME}`;
+var SETUP_ERROR_NAME = "SetupError";
+function createSetupError(message) {
+  const error = new Error(message);
+  error.name = SETUP_ERROR_NAME;
+  return error;
+}
+var DEFAULT_OPS = {
+  writeFileSync: fs.writeFileSync,
+  renameSync: fs.renameSync,
+  unlinkSync: fs.unlinkSync,
+  chmodSync: fs.chmodSync
+};
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function matchesIdentity(identifier, base) {
+  if (identifier === base)
+    return true;
+  const prefix = `${base}@`;
+  return identifier.startsWith(prefix) && identifier.length > prefix.length;
+}
+function isSystematicIdentifier(identifier) {
+  return matchesIdentity(identifier, SYSTEMATIC_PACKAGE_NAME);
+}
+function isPiSystematicIdentifier(identifier) {
+  return matchesIdentity(identifier, PI_PACKAGE_IDENTIFIER);
+}
+function lstatOrNull(targetPath) {
+  try {
+    return fs.lstatSync(targetPath);
+  } catch (error) {
+    if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+      return null;
+    }
+    throw error;
+  }
+}
+function assertRealpathUnderCwd(dir, cwd) {
+  const realDir = fs.realpathSync(dir);
+  const realCwd = fs.realpathSync(cwd);
+  const relative = path.relative(realCwd, realDir);
+  if (relative.startsWith("..") || path.isAbsolute(relative)) {
+    throw createSetupError(`Refusing to write under ${dir}: resolved directory escapes the project root`);
+  }
+}
+function assertParentTrusted(parentDir, cwd) {
+  const stat = lstatOrNull(parentDir);
+  if (stat) {
+    if (stat.isSymbolicLink() || !stat.isDirectory()) {
+      throw createSetupError(`Refusing to write under ${parentDir}: not a real directory`);
+    }
+    assertRealpathUnderCwd(parentDir, cwd);
+    return;
+  }
+  fs.mkdirSync(parentDir, { recursive: true });
+  assertRealpathUnderCwd(parentDir, cwd);
+}
+var OPENCODE_TARGET_CANDIDATES = [
+  ".opencode/opencode.jsonc",
+  ".opencode/opencode.json",
+  "opencode.jsonc",
+  "opencode.json"
+];
+function resolveOpenCodeTargetPath(cwd) {
+  const opencodeDirStat = lstatOrNull(path.join(cwd, ".opencode"));
+  if (opencodeDirStat?.isSymbolicLink()) {
+    return path.join(cwd, OPENCODE_TARGET_CANDIDATES[0]);
+  }
+  for (const candidate of OPENCODE_TARGET_CANDIDATES) {
+    const candidatePath = path.join(cwd, candidate);
+    if (lstatOrNull(candidatePath) !== null)
+      return candidatePath;
+  }
+  return path.join(cwd, "opencode.jsonc");
+}
+var IS_WINDOWS = process.platform === "win32";
+var OPEN_FLAGS = IS_WINDOWS ? fs.constants.O_RDONLY : fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW | fs.constants.O_NONBLOCK;
+function assertWindowsPreOpenTrust(targetPath) {
+  const preStat = lstatOrNull(targetPath);
+  if (preStat && (preStat.isSymbolicLink() || !preStat.isFile())) {
+    throw createSetupError(`Refusing to read ${targetPath}: not a regular file`);
+  }
+}
+function openTrustedExisting(targetPath) {
+  if (IS_WINDOWS)
+    assertWindowsPreOpenTrust(targetPath);
+  let fd;
+  try {
+    fd = fs.openSync(targetPath, OPEN_FLAGS);
+  } catch (error) {
+    if (error instanceof Error && "code" in error) {
+      if (error.code === "ENOENT")
+        return null;
+      if (error.code === "ELOOP") {
+        throw createSetupError(`Refusing to read ${targetPath}: target is a symlink`);
+      }
+    }
+    throw error;
+  }
+  try {
+    const stat = fs.fstatSync(fd);
+    if (!stat.isFile()) {
+      throw createSetupError(`Refusing to read ${targetPath}: not a regular file`);
+    }
+    return { bytes: fs.readFileSync(fd), mode: stat.mode & 511 };
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+function atomicWrite(targetPath, content, originalBytes, mode, ops) {
+  const preserveMode = originalBytes !== null;
+  if (originalBytes !== null) {
+    const backupPath = `${targetPath}.bak`;
+    if (lstatOrNull(backupPath) !== null) {
+      throw createSetupError(`Refusing to write backup ${backupPath}: a file already exists at that path`);
+    }
+    writeTempAndRename(backupPath, originalBytes, mode, preserveMode, ops);
+  }
+  writeTempAndRename(targetPath, content, mode, preserveMode, ops);
+}
+function writeTempAndRename(destPath, content, mode, preserveExactMode, ops) {
+  const parentDir = path.dirname(destPath);
+  const tempPath = makeTempPath(parentDir, path.basename(destPath));
+  try {
+    ops.writeFileSync(tempPath, content, { flag: "wx", mode });
+    if (preserveExactMode) {
+      ops.chmodSync(tempPath, mode);
+    }
+    ops.renameSync(tempPath, destPath);
+  } catch (error) {
+    cleanupTemp(tempPath, ops);
+    throw error;
+  }
+}
+function makeTempPath(parentDir, basename) {
+  return path.join(parentDir, `.${basename}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+}
+function cleanupTemp(tempPath, ops) {
+  if (!fs.existsSync(tempPath))
+    return;
+  try {
+    ops.unlinkSync(tempPath);
+  } catch {}
+}
+function assertNoDuplicateTopLevelKeys(rawText, targetPath, names, diagnosticContext) {
+  const root = parseTree(rawText);
+  if (!root?.children)
+    return;
+  const seen = new Set;
+  for (const child of root.children) {
+    const keyNode = child.children?.[0];
+    const key = keyNode?.value;
+    if (typeof key !== "string" || !names.includes(key))
+      continue;
+    if (seen.has(key)) {
+      throw createSetupError(`Invalid ${diagnosticContext} in ${targetPath}: duplicate top-level \`${key}\` key`);
+    }
+    seen.add(key);
+  }
+}
+function parseOpenCodeJsonc(rawText, targetPath) {
+  const errors = [];
+  const parsed = parse(rawText, errors, {
+    allowTrailingComma: true
+  });
+  if (errors.length > 0) {
+    throw createSetupError(`Invalid OpenCode config in ${targetPath}: JSONC parse error (code ${errors[0]?.error})`);
+  }
+  return parsed;
+}
+function setupOpenCode(cwd, ops) {
+  const targetPath = resolveOpenCodeTargetPath(cwd);
+  assertParentTrusted(path.dirname(targetPath), cwd);
+  const existing = openTrustedExisting(targetPath);
+  if (existing === null) {
+    const content = `${JSON.stringify({ plugin: [SYSTEMATIC_PACKAGE_NAME] }, null, 2)}
+`;
+    atomicWrite(targetPath, content, null, 420, ops);
+    return { status: "configured", targetPath };
+  }
+  const rawText = existing.bytes.toString("utf8");
+  assertNoDuplicateTopLevelKeys(rawText, targetPath, ["plugin", "plugins"], "OpenCode config");
+  const parsed = parseOpenCodeJsonc(rawText, targetPath);
+  if (!isRecord(parsed)) {
+    throw createSetupError(`Invalid OpenCode config in ${targetPath}: root must be an object`);
+  }
+  if (Object.hasOwn(parsed, "plugins")) {
+    throw createSetupError(`Invalid OpenCode config in ${targetPath}: \`plugins\` (plural) is not supported by OpenCode's schema; use singular \`plugin\``);
+  }
+  if (!Object.hasOwn(parsed, "plugin")) {
+    const edits2 = modify(rawText, ["plugin"], [SYSTEMATIC_PACKAGE_NAME], {});
+    atomicWrite(targetPath, applyEdits(rawText, edits2), existing.bytes, existing.mode, ops);
+    return { status: "configured", targetPath };
+  }
+  const existingValue = parsed.plugin;
+  if (!Array.isArray(existingValue)) {
+    throw createSetupError(`Invalid OpenCode config in ${targetPath}: \`plugin\` must be an array`);
+  }
+  const identifiers = [];
+  for (const entry of existingValue) {
+    if (typeof entry !== "string") {
+      throw createSetupError(`Invalid OpenCode config in ${targetPath}: \`plugin\` contains a non-string entry`);
+    }
+    identifiers.push(entry);
+  }
+  if (identifiers.some((identifier) => isSystematicIdentifier(identifier))) {
+    return { status: "already-configured", targetPath };
+  }
+  const edits = modify(rawText, ["plugin", existingValue.length], SYSTEMATIC_PACKAGE_NAME, {});
+  atomicWrite(targetPath, applyEdits(rawText, edits), existing.bytes, existing.mode, ops);
+  return { status: "configured", targetPath };
+}
+function getPiEntryIdentifier(entry) {
+  if (typeof entry === "string")
+    return entry;
+  if (isRecord(entry) && typeof entry.source === "string")
+    return entry.source;
+  return null;
+}
+function assertPiTaggedEntryUsable(entry, targetPath) {
+  if (!isRecord(entry))
+    return;
+  if (entry.autoload === false) {
+    throw createSetupError(`Invalid Pi settings in ${targetPath}: the existing \`${SYSTEMATIC_PACKAGE_NAME}\` package entry has \`autoload: false\`, which may prevent Systematic from loading; remove that flag or the entry before re-running setup`);
+  }
+  if (Object.hasOwn(entry, "extensions") || Object.hasOwn(entry, "skills")) {
+    throw createSetupError(`Invalid Pi settings in ${targetPath}: the existing \`${SYSTEMATIC_PACKAGE_NAME}\` package entry declares an \`extensions\`/\`skills\` filter, which cannot be proven safe for Systematic's extension/skills; adjust the filter before re-running setup`);
+  }
+}
+function setupPi(cwd, ops) {
+  const targetPath = path.join(cwd, ".pi", "settings.json");
+  assertParentTrusted(path.dirname(targetPath), cwd);
+  const existing = openTrustedExisting(targetPath);
+  if (existing === null) {
+    const content = `${JSON.stringify({ packages: [PI_PACKAGE_IDENTIFIER] }, null, 2)}
+`;
+    atomicWrite(targetPath, content, null, 420, ops);
+    return { status: "configured", targetPath };
+  }
+  const rawText = existing.bytes.toString("utf8");
+  assertNoDuplicateTopLevelKeys(rawText, targetPath, ["packages"], "Pi settings");
+  let parsed;
+  try {
+    parsed = JSON.parse(rawText);
+  } catch (error) {
+    throw createSetupError(`Invalid Pi settings in ${targetPath}: unable to parse JSON (${errorMessage(error)})`);
+  }
+  if (!isRecord(parsed)) {
+    throw createSetupError(`Invalid Pi settings in ${targetPath}: root must be an object`);
+  }
+  const existingPackages = parsed.packages;
+  if (existingPackages === undefined) {
+    const edits2 = modify(rawText, ["packages"], [PI_PACKAGE_IDENTIFIER], {});
+    atomicWrite(targetPath, applyEdits(rawText, edits2), existing.bytes, existing.mode, ops);
+    return { status: "configured", targetPath };
+  }
+  if (!Array.isArray(existingPackages)) {
+    throw createSetupError(`Invalid Pi settings in ${targetPath}: \`packages\` must be an array`);
+  }
+  const identifiers = [];
+  for (const entry of existingPackages) {
+    const identifier = getPiEntryIdentifier(entry);
+    if (identifier === null) {
+      throw createSetupError(`Invalid Pi settings in ${targetPath}: \`packages\` contains an entry of unsupported shape`);
+    }
+    identifiers.push(identifier);
+  }
+  const matchIndex = identifiers.findIndex((identifier) => isPiSystematicIdentifier(identifier));
+  if (matchIndex !== -1) {
+    assertPiTaggedEntryUsable(existingPackages[matchIndex], targetPath);
+    return { status: "already-configured", targetPath };
+  }
+  const edits = modify(rawText, ["packages", existingPackages.length], PI_PACKAGE_IDENTIFIER, {});
+  atomicWrite(targetPath, applyEdits(rawText, edits), existing.bytes, existing.mode, ops);
+  return { status: "configured", targetPath };
+}
+function setupHarness(harness, cwd, opsOverride) {
+  const ops = { ...DEFAULT_OPS, ...opsOverride };
+  switch (harness) {
+    case "opencode":
+      return setupOpenCode(cwd, ops);
+    case "pi":
+      return setupPi(cwd, ops);
+    default:
+      throw createSetupError(`Unknown harness: ${String(harness)}. Use: opencode, pi`);
+  }
+}
+
+// src/cli.ts
 var getPackageVersion = () => {
   try {
-    const packageJsonPath = path.resolve(import.meta.dirname, "..", "package.json");
-    if (!fs.existsSync(packageJsonPath))
+    const packageJsonPath = path2.resolve(import.meta.dirname, "..", "package.json");
+    if (!fs2.existsSync(packageJsonPath))
       return "unknown";
-    const content = fs.readFileSync(packageJsonPath, "utf8");
+    const content = fs2.readFileSync(packageJsonPath, "utf8");
     const parsed = JSON.parse(content);
     return parsed.version ?? "unknown";
   } catch {
@@ -31,12 +332,11 @@ Usage:
   systematic <command> [options]
 
 Commands:
-  list [type]          List available skills, agents, or commands
-  convert <type> <file> [--mode=primary|subagent]
-                       Convert and inspect a file (outputs to stdout)
-  config [subcommand]  Configuration management
-    show               Show configuration
-    path               Print config file locations
+  list [type]                  List available skills, agents, or commands
+  config [subcommand]          Configuration management
+    show                       Show configuration
+    path                       Print config file locations
+  setup --harness opencode|pi  Configure a harness to load Systematic (project-local only)
 
 Options:
   -h, --help           Show this help message
@@ -45,13 +345,38 @@ Options:
 Examples:
   systematic list skills
   systematic list agents
-  systematic convert agent ./agents/my-agent.md
-  systematic convert agent ./agents/my-agent.md --mode=primary
-  systematic convert skill ./skills/my-skill/SKILL.md
   systematic config show
+  systematic setup --harness opencode
+  systematic setup --harness pi
 `;
+function isHarness(value) {
+  return value === "opencode" || value === "pi";
+}
+function setupCommand(rest) {
+  if (rest[0] !== "--harness" || rest.length !== 2) {
+    console.error("Usage: systematic setup --harness opencode|pi (project-local only, no --global)");
+    process.exit(1);
+  }
+  const harnessArg = rest[1];
+  if (!harnessArg || !isHarness(harnessArg)) {
+    console.error(`Unknown or missing --harness value: ${harnessArg ?? ""}`);
+    console.error("Available: opencode, pi");
+    process.exit(1);
+  }
+  try {
+    const result = setupHarness(harnessArg, process.cwd());
+    if (result.status === "already-configured") {
+      console.log(`Already configured: ${result.targetPath}`);
+    } else {
+      console.log(`Configured: ${result.targetPath}`);
+    }
+  } catch (error) {
+    console.error(`Setup failed: ${error instanceof Error ? error.message : String(error)}`);
+    process.exit(1);
+  }
+}
 function listItems(type) {
-  const packageRoot = path.resolve(import.meta.dirname, "..");
+  const packageRoot = path2.resolve(import.meta.dirname, "..");
   const bundledDir = packageRoot;
   let finder;
   let subdir;
@@ -72,7 +397,7 @@ function listItems(type) {
       console.error(`Unknown type: ${type}. Use: skills, agents, commands`);
       process.exit(1);
   }
-  const items = finder(path.join(bundledDir, subdir));
+  const items = finder(path2.join(bundledDir, subdir));
   if (items.length === 0) {
     console.log(`No ${type} found.`);
     return;
@@ -83,46 +408,21 @@ function listItems(type) {
     console.log(`  ${item.name}`);
   }
 }
-function runConvert(type, filePath, modeArg) {
-  const validTypes = ["skill", "agent", "command"];
-  if (!validTypes.includes(type)) {
-    console.error(`Invalid type: ${type}. Must be one of: ${validTypes.join(", ")}`);
-    process.exit(1);
-  }
-  const resolvedPath = path.resolve(filePath);
-  if (!fs.existsSync(resolvedPath)) {
-    console.error(`File not found: ${resolvedPath}`);
-    process.exit(1);
-  }
-  let agentMode = "subagent";
-  if (modeArg) {
-    const modeMatch = modeArg.match(/^--mode=(primary|subagent)$/);
-    if (modeMatch) {
-      agentMode = modeMatch[1];
-    } else {
-      console.error("Invalid --mode flag. Use: --mode=primary or --mode=subagent");
-      process.exit(1);
-    }
-  }
-  const content = fs.readFileSync(resolvedPath, "utf8");
-  const converted = convertContent(content, type, { agentMode });
-  console.log(converted);
-}
 function configShow() {
   const paths = getConfigPaths(process.cwd());
   console.log(`Configuration locations:
 `);
   console.log(`  User config:    ${paths.userConfig}`);
   console.log(`  Project config: ${paths.projectConfig}`);
-  if (fs.existsSync(paths.projectConfig)) {
+  if (fs2.existsSync(paths.projectConfig)) {
     console.log(`
 Project configuration:`);
-    console.log(fs.readFileSync(paths.projectConfig, "utf-8"));
+    console.log(fs2.readFileSync(paths.projectConfig, "utf-8"));
   }
-  if (fs.existsSync(paths.userConfig)) {
+  if (fs2.existsSync(paths.userConfig)) {
     console.log(`
 User configuration:`);
-    console.log(fs.readFileSync(paths.userConfig, "utf-8"));
+    console.log(fs2.readFileSync(paths.userConfig, "utf-8"));
   }
 }
 function configPath() {
@@ -137,13 +437,8 @@ switch (command) {
   case "list":
     listItems(args[1] || "skills");
     break;
-  case "convert":
-    if (!args[1] || !args[2]) {
-      console.error("Usage: systematic convert <type> <file> [--mode=primary|subagent]");
-      console.error("  type: skill, agent, or command");
-      process.exit(1);
-    }
-    runConvert(args[1], args[2], args[3]);
+  case "setup":
+    setupCommand(args.slice(1));
     break;
   case "config":
     switch (args[1]) {