@rexeus/agentic 0.3.1

package/opencode/guardrails.mjs

@@ -0,0 +1,172 @@
+import { readFileSync } from "node:fs";
+import { execSync } from "node:child_process";
+
+const SECRET_ASSIGNMENT_QUOTED =
+  /(password|passwd|secret|api_?key|access_?key|private_?key)"?[\t ]*[:=][\t ]*["'][^\s"']{4,}/i;
+const SECRET_ASSIGNMENT_UNQUOTED =
+  /(password|passwd|secret|api_?key|access_?key|private_?key)[\t ]*=[\t ]*[^\s"'=,;}{]{4,}/i;
+const TOKEN_PATTERN =
+  /(sk-[a-zA-Z0-9]{20,}|ghp_[a-zA-Z0-9]{36,}|gho_[a-zA-Z0-9]{36,}|github_pat_[a-zA-Z0-9_]{20,}|aws_[a-zA-Z0-9/+=]{20,}|AKIA[A-Z0-9]{16}|sk_live_[a-zA-Z0-9]{20,}|sk_test_[a-zA-Z0-9]{20,}|xoxb-[a-zA-Z0-9-]{20,}|xoxp-[a-zA-Z0-9-]{20,})/;
+const COMMIT_TYPES = "feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert";
+const COMMIT_HEADER_RE = new RegExp(`^(${COMMIT_TYPES})(\\([a-zA-Z0-9_./-]+\\))?!?:[\\t ].+`);
+
+let conventionalHistoryCache;
+
+const JS_TS_FILE_RE = /\.(ts|tsx|js|jsx|mjs|cjs)$/;
+const BINARY_OR_GENERATED_RE =
+  /\.(png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot|lock|min\.js|min\.css|map)$/;
+
+const getFirstString = (...values) => {
+  for (const value of values) {
+    if (typeof value === "string" && value.length > 0) {
+      return value;
+    }
+  }
+  return "";
+};
+
+export const extractFilePath = (args) =>
+  getFirstString(args?.filePath, args?.file_path, args?.path);
+
+export const extractWriteContent = (args) =>
+  getFirstString(args?.content, args?.newString, args?.new_string);
+
+export const findSecretViolations = ({ filePath, content }) => {
+  if (!content) {
+    return [];
+  }
+
+  const fileLabel = filePath ?? "file";
+  const violations = [];
+
+  if (SECRET_ASSIGNMENT_QUOTED.test(content) || SECRET_ASSIGNMENT_UNQUOTED.test(content)) {
+    violations.push(
+      `Possible hardcoded secret detected - do not write credentials to ${fileLabel}`,
+    );
+  }
+
+  if (TOKEN_PATTERN.test(content)) {
+    violations.push(`Possible API token detected - do not write tokens to ${fileLabel}`);
+  }
+
+  return violations;
+};
+
+const extractCommitMessage = (command) => {
+  if (!command || !/(^|&&|;|\|)[\t ]*git[\t ]+commit/.test(command)) {
+    return "";
+  }
+
+  const heredocMatch = command.match(/cat <<.*EOF([\s\S]*?)\nEOF\n?/);
+  if (heredocMatch && heredocMatch[1]) {
+    return heredocMatch[1].trim();
+  }
+
+  const quotedMatch = command.match(/-[a-z]*m[\t ]*["']([^"']+)["']/);
+  if (quotedMatch && quotedMatch[1]) {
+    return quotedMatch[1];
+  }
+
+  return "";
+};
+
+export const validateConventionalCommitCommand = (command) => {
+  const message = extractCommitMessage(command);
+
+  if (!message) {
+    return [];
+  }
+
+  if (!projectUsesConventionalCommits()) {
+    return [];
+  }
+
+  const header = message.split("\n")[0] ?? "";
+  const issues = [];
+
+  if (!new RegExp(`^(${COMMIT_TYPES})`).test(header)) {
+    issues.push(`First line must start with a valid type (${COMMIT_TYPES})`);
+  }
+
+  if (!COMMIT_HEADER_RE.test(header)) {
+    issues.push("Format must be: type[optional scope]: description - colon and space required");
+  }
+
+  const description = header.replace(/^[^:]*:[\t ]*/, "");
+  if (description) {
+    const firstChar = description[0];
+    if (/[A-Z]/.test(firstChar)) {
+      issues.push("Description should start lowercase after ': '");
+    }
+
+    if (description.endsWith(".")) {
+      issues.push("Description should not end with a period");
+    }
+  }
+
+  if (header.length > 100) {
+    issues.push(`First line exceeds 100 characters (found ${header.length})`);
+  }
+
+  return issues;
+};
+
+const projectUsesConventionalCommits = () => {
+  if (typeof conventionalHistoryCache === "boolean") {
+    return conventionalHistoryCache;
+  }
+
+  try {
+    const recent = execSync("git log --format=%s -10", {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    })
+      .split("\n")
+      .map((line) => line.trim())
+      .filter(Boolean);
+
+    if (recent.length < 4) {
+      conventionalHistoryCache = true;
+      return conventionalHistoryCache;
+    }
+
+    const typeMatcher = new RegExp(`^(${COMMIT_TYPES})`);
+    const matching = recent.filter((line) => typeMatcher.test(line)).length;
+    conventionalHistoryCache = matching >= Math.floor(recent.length / 2);
+    return conventionalHistoryCache;
+  } catch {
+    conventionalHistoryCache = true;
+    return conventionalHistoryCache;
+  }
+};
+
+export const getConventionWarningsForFile = (filePath) => {
+  if (!filePath || BINARY_OR_GENERATED_RE.test(filePath)) {
+    return [];
+  }
+
+  let content;
+  try {
+    content = readFileSync(filePath, "utf8");
+  } catch {
+    return [];
+  }
+
+  const warnings = [];
+
+  if (/^(<<<<<<<|=======|>>>>>>>)/m.test(content)) {
+    warnings.push(`Merge conflict markers found in ${filePath} - resolve before committing`);
+  }
+
+  if (JS_TS_FILE_RE.test(filePath)) {
+    if (/(console\.log|console\.debug|\bdebugger\b)/.test(content)) {
+      warnings.push(`Debug statement found in ${filePath} - remove before committing`);
+    }
+
+    if (/(^|[^A-Za-z])TODO([^(A-Za-z)]|$)/.test(content)) {
+      warnings.push(`Unowned TODO in ${filePath} - use TODO(name) or TODO(#123)`);
+    }
+  }
+
+  return warnings;
+};

package/opencode/install.mjs

@@ -0,0 +1,48 @@
+import {
+  backupConfigFile,
+  ensureOpenCodeConfigDir,
+  ensurePluginEntry,
+  getDoctorStatus,
+  installGlobalAgents,
+  installGlobalCommands,
+  installGlobalSkills,
+  readOpenCodeConfig,
+  validateOpenCodeConfigForMutation,
+  writeOpenCodeConfig,
+} from "./config.mjs";
+
+export const installOpenCode = async () => {
+  const configDir = ensureOpenCodeConfigDir();
+  const { configPath, config, error } = readOpenCodeConfig(configDir);
+
+  if (error) {
+    throw new Error(error);
+  }
+
+  const mutationError = validateOpenCodeConfigForMutation(configPath, config);
+  if (mutationError) {
+    throw new Error(mutationError);
+  }
+
+  const backupPath = await backupConfigFile(configPath);
+  const updated = ensurePluginEntry(config);
+
+  await writeOpenCodeConfig(configPath, updated);
+  const commandsDir = await installGlobalCommands(configDir);
+  const agentsDir = await installGlobalAgents(configDir);
+  const skillsDir = await installGlobalSkills(configDir);
+  const status = await getDoctorStatus(configDir, updated);
+
+  return {
+    configPath,
+    backupPath,
+    commandsDir,
+    agentsDir,
+    skillsDir,
+    conflicts: {
+      commands: status.conflictingCommands,
+      agents: status.conflictingAgents,
+      skills: status.conflictingSkills,
+    },
+  };
+};

package/opencode/manifest.mjs

@@ -0,0 +1,34 @@
+export const COMMAND_FILES = [
+  "agentic-plan.md",
+  "agentic-develop.md",
+  "agentic-review.md",
+  "agentic-verify.md",
+  "agentic-simplify.md",
+  "agentic-polish.md",
+  "agentic-commit.md",
+  "agentic-pr.md",
+];
+
+export const AGENT_FILES = [
+  "lead.md",
+  "scout.md",
+  "analyst.md",
+  "architect.md",
+  "developer.md",
+  "reviewer.md",
+  "tester.md",
+  "refiner.md",
+];
+
+export const SKILL_NAMES = [
+  "conventions",
+  "git-conventions",
+  "quality-patterns",
+  "security",
+  "setup",
+  "testing",
+];
+
+export const COMMAND_PREFIX = "agentic-";
+export const PLUGIN_NAME = "@rexeus/agentic";
+export const LOCAL_PLUGIN_PREFIX = "agentic";

package/opencode/plugin.mjs

@@ -0,0 +1,53 @@
+import {
+  extractFilePath,
+  extractWriteContent,
+  findSecretViolations,
+  getConventionWarningsForFile,
+  validateConventionalCommitCommand,
+} from "./guardrails.mjs";
+
+const AgenticPlugin = async () => ({
+  name: "agentic",
+
+  "tool.execute.before": async (input, output) => {
+    if (input.tool === "write" || input.tool === "edit") {
+      const filePath = extractFilePath(output.args);
+      const content = extractWriteContent(output.args);
+      const violations = findSecretViolations({ filePath, content });
+      if (violations.length > 0) {
+        throw new Error(violations.join("\n"));
+      }
+      return;
+    }
+
+    if (input.tool === "bash") {
+      const command = output?.args?.command;
+      if (typeof command !== "string" || command.length === 0) {
+        return;
+      }
+
+      const issues = validateConventionalCommitCommand(command);
+      if (issues.length > 0) {
+        throw new Error(`Commit message validation failed:\n${issues.join("\n")}`);
+      }
+    }
+  },
+
+  "tool.execute.after": async (input, output) => {
+    if (input.tool !== "write" && input.tool !== "edit") {
+      return;
+    }
+
+    const filePath = extractFilePath(input.args);
+    const warnings = getConventionWarningsForFile(filePath);
+
+    if (warnings.length === 0) {
+      return;
+    }
+
+    const warningText = `[agentic warnings]\n${warnings.map((warning) => `- ${warning}`).join("\n")}`;
+    output.output = output.output ? `${output.output}\n\n${warningText}` : warningText;
+  },
+});
+
+export default AgenticPlugin;

package/opencode/uninstall.mjs

@@ -0,0 +1,64 @@
+import { existsSync } from "node:fs";
+
+import {
+  backupConfigFile,
+  getDoctorStatus,
+  getOpenCodeConfigDir,
+  readOpenCodeConfig,
+  removePluginEntry,
+  uninstallGlobalAgents,
+  uninstallGlobalCommands,
+  uninstallGlobalSkills,
+  validateOpenCodeConfigForMutation,
+  writeOpenCodeConfig,
+} from "./config.mjs";
+
+export const uninstallOpenCode = async () => {
+  const configDir = getOpenCodeConfigDir();
+  const { configPath, config, error } = readOpenCodeConfig(configDir);
+
+  if (error) {
+    throw new Error(error);
+  }
+
+  const mutationError = validateOpenCodeConfigForMutation(configPath, config);
+  if (mutationError) {
+    throw new Error(mutationError);
+  }
+
+  const installStatus = await getDoctorStatus(configDir, config);
+  const hasManagedAssets =
+    installStatus.commands.installedFiles.length > 0 ||
+    installStatus.agents.installedFiles.length > 0 ||
+    installStatus.skills.installedFiles.length > 0;
+
+  if (!installStatus.pluginSources.config && !hasManagedAssets) {
+    return {
+      configPath,
+      backupPath: null,
+      removedCommands: 0,
+      removedAgents: 0,
+      removedSkills: 0,
+    };
+  }
+
+  const updated = removePluginEntry(config);
+  const hasConfigFile = existsSync(configPath);
+
+  const backupPath = hasConfigFile ? await backupConfigFile(configPath) : null;
+
+  if (hasConfigFile) {
+    await writeOpenCodeConfig(configPath, updated);
+  }
+  const removedCommands = await uninstallGlobalCommands(configDir);
+  const removedAgents = await uninstallGlobalAgents(configDir);
+  const removedSkills = await uninstallGlobalSkills(configDir);
+
+  return {
+    configPath,
+    backupPath,
+    removedCommands,
+    removedAgents,
+    removedSkills,
+  };
+};

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@rexeus/agentic",
+  "version": "0.3.1",
+  "description": "Multi-agent development toolkit for Claude Code and OpenCode. Specialized agents, conventions, review workflows, and quality guardrails for TypeScript and JavaScript projects.",
+  "keywords": [
+    "agentic-coding",
+    "claude-code",
+    "code-quality",
+    "code-review",
+    "conventions",
+    "opencode",
+    "plugin",
+    "refactoring"
+  ],
+  "homepage": "https://github.com/rexeus/agentic#readme",
+  "bugs": {
+    "url": "https://github.com/rexeus/agentic/issues"
+  },
+  "license": "Apache-2.0",
+  "author": "Dennis Wentzien <dw@rexeus.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rexeus/agentic.git"
+  },
+  "bin": {
+    "agentic": "./bin/agentic.js"
+  },
+  "files": [
+    "assets/opencode/agents",
+    "assets/opencode/commands",
+    "bin",
+    "opencode",
+    "skills",
+    "README.md",
+    "LICENSE*"
+  ],
+  "type": "module",
+  "main": "./opencode/plugin.mjs",
+  "exports": {
+    ".": "./opencode/plugin.mjs"
+  },
+  "scripts": {
+    "test": "bash tests/run.sh",
+    "format": "oxfmt",
+    "sync:opencode-agents": "node scripts/sync-opencode-agents.mjs",
+    "sync:opencode-commands": "node scripts/sync-opencode-commands.mjs",
+    "check:agent-parity": "node scripts/check-agent-parity.mjs",
+    "check:command-parity": "node scripts/check-command-parity.mjs",
+    "check:opencode": "bash tests/run.sh opencode-cli",
+    "sync:versions": "node scripts/sync-versions.mjs",
+    "check:versions": "node scripts/sync-versions.mjs --check",
+    "release": "changeset",
+    "version-packages": "changeset version && pnpm run sync:versions",
+    "ci:publish": "pnpm publish --access public"
+  },
+  "dependencies": {
+    "jsonc-parser": "^3.3.1"
+  },
+  "devDependencies": {
+    "@changesets/cli": "2.29.6",
+    "oxfmt": "^0.36.0"
+  },
+  "packageManager": "pnpm@10.19.0",
+  "pnpm": {
+    "patchedDependencies": {
+      "@changesets/assemble-release-plan@6.0.9": "patches/@changesets__assemble-release-plan@6.0.9.patch"
+    }
+  }
+}

package/skills/conventions/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: conventions
+description: Code conventions and style convictions. Applied when writing, reviewing, or analyzing code. These are non-negotiable standards, not preferences.
+user-invokable: false
+---
+
+# Code Conventions
+
+These conventions target **TypeScript and JavaScript** projects. For other
+languages, adapt the principles to idiomatic equivalents.
+
+These are convictions, not suggestions. Apply them to all code you write or review.
+
+## Certainty Over Ambiguity
+
+- Use `??` over `||`. Nullish is not falsy. Mean what you say.
+- Use strict equality (`===`). Loose comparisons hide bugs.
+- Discriminated unions over optional fields when states are mutually exclusive.
+
+## Immutability Is Clarity
+
+- `const` by default. `let` only when mutation is required and justified.
+- Mark properties `readonly` unless mutation is the explicit intent.
+- Mutable state is opt-in, never opt-out.
+
+## Types, Not Interfaces
+
+- Use `type` for composition, algebraic types, and everything internal.
+- Use `interface` only for contracts with external consumers.
+- If in doubt, use `type`.
+
+## Say It With Access Modifiers
+
+- `public`, `private`, `protected` on every method and constructor parameter.
+- No ambiguity. No guessing. Declare intent explicitly.
+
+## Naming Is Design
+
+- Variables and functions: camelCase. Descriptive. `getUserById` not `getUser`.
+- Types and classes: PascalCase. Nouns for data, adjectives for capabilities.
+- Constants: SCREAMING_SNAKE_CASE only for true compile-time constants.
+- Booleans: prefix with `is`, `has`, `can`, `should`. Never ambiguous.
+- Files: match the primary export. `UserService.ts` exports `UserService`.
+- If you can't name it clearly, you don't understand it yet.
+
+## Small Functions, Clear Purpose
+
+- Every function does one thing. If you need "and" to describe it, split it.
+- Aim for 20 lines or fewer. If significantly longer, consider extracting.
+- Aim for 300 lines or fewer per file. If significantly longer, consider decomposing.
+- Maximum nesting: 3 levels. Early returns over deep nesting.
+
+## Errors Are First-Class Citizens
+
+- Never swallow errors. Every `catch` must log, rethrow, or transform.
+- Typed errors with meaningful messages. `new AuthError("Token expired")` not `new Error("error")`.
+- Handle errors at the appropriate boundary. Don't catch what you can't handle.
+- Prefer `Result<T, E>` patterns where the language supports it.
+- The unhappy path deserves as much care as the happy path.
+
+## Imports & Dependencies
+
+- Named exports only. Default exports create ambiguity.
+- Import order: stdlib, external packages, internal packages, relative imports.
+- Every dependency is a decision. Lightweight, well-maintained, truly needed — or don't add it.
+
+## Comments Are a Last Resort
+
+- If the code needs a comment to be understood, the code isn't done yet.
+- Comments explain _why_, never _what_. Only when the reasoning is non-obvious.
+- TODO comments include an owner or issue link. Orphan TODOs are technical debt.
+- JSDoc only for public API surfaces.
+
+## Adapting to the Project
+
+These conventions are the baseline. The project's voice takes precedence:
+
+1. Check for CLAUDE.md files in the repository
+2. Examine recent commits for naming and style patterns
+3. Look at existing tests for testing conventions
+4. If the project has its own standards, those override these defaults
+
+Your code should look like it was always there.

package/skills/git-conventions/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: git-conventions
+description: Provides git workflow conventions including Conventional Commits, branch naming, and PR descriptions. Applied when committing, branching, or creating pull requests.
+user-invokable: false
+---
+
+# Git Conventions
+
+Commits tell a story. Reading `git log --oneline` should explain the
+evolution of a project — every change purposeful, every message clear.
+When this skill is active, apply these conventions to all git operations.
+
+## Conventional Commits
+
+Follow the Conventional Commits 1.0.0 specification (conventionalcommits.org):
+
+```
+<type>[optional scope][optional !]: <description>
+
+[optional body]
+
+[optional footer(s)]
+```
+
+### Types
+
+| Type       | When to use                     | Semver impact |
+| ---------- | ------------------------------- | ------------- |
+| `feat`     | New feature for the user        | MINOR         |
+| `fix`      | Bug fix                         | PATCH         |
+| `docs`     | Documentation only              | —             |
+| `style`    | Formatting, no logic change     | —             |
+| `refactor` | Code change, no feature or fix  | —             |
+| `perf`     | Performance improvement         | PATCH         |
+| `test`     | Adding or correcting tests      | —             |
+| `build`    | Build system or dependencies    | —             |
+| `ci`       | CI/CD configuration             | —             |
+| `chore`    | Maintenance, no production code | —             |
+| `revert`   | Reverts a previous commit       | —             |
+
+### Rules
+
+- **Description**: imperative mood, lowercase, no period. Max 100 characters.
+  Good: `feat(auth): add token refresh endpoint`
+  Bad: `feat(auth): Added Token Refresh Endpoint.`
+- **Scope**: optional. Use the module or component name.
+  `feat(auth)`, `fix(api)`, `refactor(db)`
+- **Body**: explain WHAT changed and WHY. The diff shows HOW.
+  Wrap at 72 characters. Separate from description with a blank line.
+  Multiple paragraphs are allowed — separate them with blank lines.
+- **Breaking changes**: add `!` after type/scope OR `BREAKING CHANGE:` in footer.
+  `BREAKING-CHANGE` (hyphen) is a valid synonym.
+  `feat(api)!: change authentication to OAuth2`
+
+### Choosing the Right Type
+
+- Changed behavior for the user? → `feat` or `fix`
+- Changed internals without affecting behavior? → `refactor`
+- Only moved or renamed things? → `refactor`
+- Only changed comments or docs? → `docs`
+- Only changed tests? → `test`
+- Undoing a previous commit? → `revert`
+- Multiple types in one commit? → The commit is too large. Split it.
+
+### Footers
+
+Footers follow `git-trailer` format: `Token: value` or `Token #value`.
+They appear after the body, separated by a blank line. One footer per line.
+Multi-word tokens use `-` (exception: `BREAKING CHANGE` with space).
+
+| Footer            | Purpose           | Example                                 |
+| ----------------- | ----------------- | --------------------------------------- |
+| `BREAKING CHANGE` | Describe breakage | `BREAKING CHANGE: removed v1 endpoints` |
+| `Fixes`           | Close an issue    | `Fixes #42`                             |
+| `Refs`            | Reference issues  | `Refs #123, #456`                       |
+| `Co-authored-by`  | Credit co-author  | `Co-authored-by: Name <email>`          |
+| `Reviewed-by`     | Credit reviewer   | `Reviewed-by: Name <email>`             |
+
+### Examples
+
+Minimal — title only:
+
+```
+fix(auth): prevent token expiry race condition
+```
+
+With body and issue reference:
+
+```
+feat(api): add batch processing endpoint
+
+Process up to 100 items in a single request. Uses chunked
+transfer encoding for large payloads.
+
+Fixes #234
+```
+
+Breaking change with footer:
+
+```
+refactor(db)!: migrate from MySQL to PostgreSQL
+
+Replace all MySQL-specific queries with PostgreSQL equivalents.
+Connection pooling now uses pgBouncer.
+
+BREAKING CHANGE: database connection string format changed,
+requires migration script before deployment
+Refs #89
+```
+
+## Branch Naming
+
+Pattern: `<type>/<short-description>`
+
+```
+feat/token-refresh
+fix/null-reference-login
+refactor/extract-auth-service
+```
+
+- Use lowercase and hyphens
+- Keep it short but descriptive
+- Match the type to Conventional Commits types
+
+## Commit Discipline
+
+- **One logical change per commit.** If you need "and" to describe it, split it.
+- **Never commit generated files** (dist/, build/, node_modules/).
+- **Never commit secrets** (.env, credentials, API keys).
+- **Never commit debug code** (console.log, debugger, TODO: remove).
+- **Commit messages tell a story.** Reading `git log --oneline` should
+  explain the evolution of the project.
+
+## Adapting to the Project
+
+Before applying these conventions:
+
+1. Read the last 20 commit messages: `git log --oneline -20`
+2. Check for a CONTRIBUTING.md or commit message guidelines
+3. If the project uses a different convention, follow theirs
+4. Match the language of existing commits (English, German, etc.)