bros-harness 0.1.0

package/assets/templates.manifest.json

@@ -0,0 +1,55 @@
+{
+  "area": "templates",
+  "counts": {
+    "candidates": 9,
+    "imported": 9,
+    "skipped": 0
+  },
+  "entries": [
+    {
+      "area": "templates",
+      "path": "assets/opencode/templates/bros/adr.md",
+      "sourceRef": "opencode-template"
+    },
+    {
+      "area": "templates",
+      "path": "assets/opencode/templates/bros/delivery-report.md",
+      "sourceRef": "opencode-template"
+    },
+    {
+      "area": "templates",
+      "path": "assets/opencode/templates/bros/explorer-evidence-packet.md",
+      "sourceRef": "opencode-template"
+    },
+    {
+      "area": "templates",
+      "path": "assets/opencode/templates/bros/prd.md",
+      "sourceRef": "opencode-template"
+    },
+    {
+      "area": "templates",
+      "path": "assets/opencode/templates/bros/security-review.md",
+      "sourceRef": "opencode-template"
+    },
+    {
+      "area": "templates",
+      "path": "assets/opencode/templates/bros/status-board.md",
+      "sourceRef": "opencode-template"
+    },
+    {
+      "area": "templates",
+      "path": "assets/opencode/templates/bros/task-packet.md",
+      "sourceRef": "opencode-template"
+    },
+    {
+      "area": "templates",
+      "path": "assets/opencode/templates/bros/test-strategy.md",
+      "sourceRef": "opencode-template"
+    },
+    {
+      "area": "templates",
+      "path": "assets/opencode/templates/bros/ui-implementation-packet.md",
+      "sourceRef": "opencode-template"
+    }
+  ]
+}

package/bin/bros.mjs

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+import { access, readFile, readdir } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+const assetRoot = join(packageRoot, "assets", "opencode");
+const manifestPath = join(packageRoot, "assets", "manifest.json");
+
+const commands = [
+  ["help", "Show available BROS Harness commands."],
+  ["snippet", "Print the package-first OpenCode plugin snippet."],
+  ["doctor", "Validate package asset directories and manifest shape without mutation."],
+  ["list-assets", "Summarize packaged OpenCode agent, command, skill, doc, and template counts."],
+  ["agent-install-prompt", "Print a safe prompt an AI agent can follow to add the plugin snippet."]
+];
+
+const requiredPaths = [
+  "assets/opencode/agents",
+  "assets/opencode/commands",
+  "assets/opencode/skills",
+  "assets/opencode/templates",
+  "assets/opencode/docs",
+  "assets/manifest.json",
+  "src/plugin.mjs",
+  "package.json"
+];
+
+function printHelp() {
+  console.log("BROS Harness CLI");
+  console.log("");
+  console.log("Usage: bros <command>");
+  console.log("");
+  console.log("Commands:");
+  for (const [name, description] of commands) {
+    console.log(`  ${name.padEnd(22)} ${description}`);
+  }
+  console.log("");
+  console.log("All commands are read-only. This CLI does not edit live OpenCode config.");
+}
+
+function printSnippet() {
+  console.log(JSON.stringify({ plugin: ["bros-harness"] }, null, 2));
+}
+
+async function readJson(path) {
+  return JSON.parse(await readFile(path, "utf8"));
+}
+
+async function doctor() {
+  for (const relativePath of requiredPaths) {
+    await access(join(packageRoot, relativePath));
+  }
+
+  const [manifest, packageJson] = await Promise.all([
+    readJson(manifestPath),
+    readJson(join(packageRoot, "package.json"))
+  ]);
+
+  if (packageJson.name !== "bros-harness") throw new Error("package.json name must be bros-harness.");
+  if (packageJson.main !== "./src/plugin.mjs") throw new Error("package.json main must point to ./src/plugin.mjs.");
+  if (packageJson.exports?.["."] !== "./src/plugin.mjs") throw new Error("package.json exports must expose ./src/plugin.mjs.");
+  if (!packageJson.bin?.bros) throw new Error("package.json must expose the bros CLI bin.");
+  if (manifest.name !== "bros-harness" || !Array.isArray(manifest.entries)) throw new Error("Invalid asset manifest shape.");
+  if (manifest.counts?.skills?.skipped !== 3) throw new Error("Expected exactly 3 skipped skills to remain skipped.");
+
+  console.log("BROS Harness doctor: ok");
+  console.log(`Manifest entries: ${manifest.entries.length}`);
+  console.log("No filesystem changes were made.");
+}
+
+async function countMarkdownFiles(relativeDir) {
+  const files = await readdir(join(assetRoot, relativeDir));
+  return files.filter((file) => file.endsWith(".md")).length;
+}
+
+async function listAssets() {
+  const manifest = await readJson(manifestPath);
+  const counts = manifest.counts ?? {};
+  console.log("BROS Harness packaged assets");
+  console.log(`Agents: ${counts.agents?.imported ?? await countMarkdownFiles("agents")}`);
+  console.log(`Commands: ${counts.commands?.imported ?? await countMarkdownFiles("commands")}`);
+  console.log(`Skills: ${counts.skills?.imported ?? "unknown"} imported, ${counts.skills?.skipped ?? "unknown"} skipped`);
+  console.log(`Docs: ${counts.docs?.imported ?? await countMarkdownFiles("docs")}`);
+  console.log(`Templates: ${counts.templates?.imported ?? "unknown"}`);
+}
+
+function printAgentInstallPrompt() {
+  console.log(`Add BROS Harness to OpenCode using the package plugin snippet only.\n\nConstraints:\n- Do not install dependencies unless the human explicitly approves it.\n- Do not publish packages.\n- Do not edit provider, MCP, permission, telemetry, secret, or credential settings.\n- Do not overwrite existing config. Merge only the plugin entry if OpenCode config exists.\n- If unsure, show the diff and ask.\n\nSnippet to add:\n{\n  "plugin": ["bros-harness"]\n}\n\nAfter editing OpenCode config, tell the human to restart OpenCode because config is loaded at startup.`);
+}
+
+const command = process.argv[2] ?? "help";
+
+try {
+  switch (command) {
+    case "help":
+    case "--help":
+    case "-h":
+      printHelp();
+      break;
+    case "snippet":
+      printSnippet();
+      break;
+    case "doctor":
+      await doctor();
+      break;
+    case "list-assets":
+      await listAssets();
+      break;
+    case "agent-install-prompt":
+      printAgentInstallPrompt();
+      break;
+    default:
+      console.error(`Unknown command: ${command}`);
+      printHelp();
+      process.exitCode = 1;
+  }
+} catch (error) {
+  console.error(`BROS Harness ${command}: failed`);
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+}

package/docs/compatibility.md

@@ -0,0 +1,9 @@
+# Compatibility
+
+## OpenCode
+
+OpenCode is the supported first target. Assets are organized under `assets/opencode/` using familiar agent, command, skill, template, and documentation areas.
+
+## Claude, Codex, and IDEs
+
+Claude, Codex, and IDE integrations are roadmap targets. The adapter SDK currently defines interfaces only and does not provide working installers for those environments.

package/docs/installation.md

@@ -0,0 +1,66 @@
+# Installation
+
+BROS Harness is structured as a package-first OpenCode plugin. The primary configuration path is the package snippet, not copying local development folders.
+
+## For humans
+
+Add the plugin package to OpenCode config:
+
+```json
+{
+  "plugin": ["bros-harness"]
+}
+```
+
+Restart OpenCode after editing config. The running session keeps the config it loaded at startup.
+
+Optional read-only checks after the package is available:
+
+```bash
+bros snippet
+bros doctor
+bros list-assets
+```
+
+## For AI agents
+
+Use a bounded instruction:
+
+```text
+Configure BROS Harness with { "plugin": ["bros-harness"] }. Do not install dependencies, publish, mutate provider/MCP/permission/telemetry/secret settings, or overwrite existing config files. Merge only the plugin entry if approved, show the proposed diff, and remind the human to restart OpenCode.
+```
+
+The package helper can print this prompt:
+
+```bash
+bros agent-install-prompt
+```
+
+## What the plugin changes
+
+- Uses OpenCode's in-memory `config(cfg)` hook at startup.
+- Adds package-relative BROS skills to `skills.paths` only when the existing field shape is schema-compatible.
+- Adds packaged BROS command prompt entries to `command` without replacing existing command keys.
+
+## What the plugin does not change
+
+- No providers.
+- No MCP servers.
+- No permission changes.
+- No telemetry.
+- No secrets or credential validation.
+- No provider, MCP, permission, telemetry, or secret registration.
+- No filesystem writes.
+- No live user config file mutation; `opencode.json`, `.opencode/`, and global config files are not written by the package plugin.
+
+## Local contributor checks
+
+For repository development only:
+
+```bash
+npm run validate
+node bin/bros.mjs doctor
+```
+
+Publishing and dependency installation remain separate gated actions.
+Asset import is maintainer-only source maintenance for repository asset refreshes, not part of package installation. Package users should rely on the plugin snippet and read-only CLI helpers above; import tooling is not exposed as an installed package command.

package/docs/integrations/claude.md

@@ -0,0 +1,5 @@
+# Claude Integration
+
+Claude integration is a roadmap item. The current package does not install Claude agents, commands, or skills.
+
+Future work should map BROS Harness concepts into Claude-compatible project assets only after adapter design and security review.

package/docs/integrations/codex.md

@@ -0,0 +1,5 @@
+# Codex and IDE Roadmap
+
+Codex and IDE integrations are future targets. The current scaffold includes adapter interfaces so integration work can be reviewed before implementation.
+
+No Codex or IDE installer is included in this build.

package/docs/integrations/opencode.md

@@ -0,0 +1,39 @@
+# OpenCode Integration
+
+OpenCode is the primary integration target for BROS Harness.
+
+## Package snippet
+
+Use the package plugin entry:
+
+```json
+{
+  "plugin": ["bros-harness"]
+}
+```
+
+This is the preferred path for users and agents. Local path examples are contributor-only.
+
+## Packaged assets
+
+- Agents: `assets/opencode/agents/`
+- Commands: `assets/opencode/commands/`
+- Skills: `assets/opencode/skills/`
+- Templates: `assets/opencode/templates/`
+- Docs: `assets/opencode/docs/`
+
+## Runtime behavior
+
+The package plugin resolves assets relative to its own package root. It validates key asset directories, then uses OpenCode's in-memory `config(cfg)` hook only to add the package-relative skills directory to `skills.paths` when safe and add packaged command prompt entries without overwriting existing commands.
+
+This runtime hook changes only the merged config object OpenCode passes to the plugin at startup. It is distinct from live user config file mutation: the plugin does not write `opencode.json`, `.opencode/`, global config files, or other filesystem config. The plugin does not register providers, MCP servers, permissions, telemetry, or secrets. Agent files are packaged as reviewed assets, but permission-bearing agent registration is intentionally not performed by the default plugin hook.
+
+## Safe agent workflow
+
+Agents should use:
+
+```bash
+bros agent-install-prompt
+```
+
+The prompt instructs agents to merge only `plugin: ["bros-harness"]`, avoid sensitive config surfaces, and ask before writing.

package/docs/migration/from-local-opencode-config.md

@@ -0,0 +1,10 @@
+# Migrating From Local OpenCode Configuration
+
+Do not copy raw local OpenCode configuration into this repository. Local config files can include provider keys, private endpoints, MCP credentials, or other sensitive values.
+
+Recommended migration approach:
+
+1. Inventory local agents, commands, skills, templates, and docs only.
+2. Exclude `opencode.json`, `opencode.jsonc`, `.env*`, logs, caches, package artifacts, and shell history.
+3. Replace any local-only values with placeholders before committing examples.
+4. Run `npm run validate` before review.

package/docs/release-process.md

@@ -0,0 +1,11 @@
+# Release Process
+
+Publishing is not approved in the initial scaffold.
+
+Required release gates:
+
+1. Asset review confirms no private data or local-only assumptions.
+2. Security review approves package contents and examples.
+3. QA validates CLI, manifests, and documentation.
+4. Maintainers confirm package allowlist and changelog.
+5. Release automation is enabled only after explicit approval.

package/docs/repository-structure.md

@@ -0,0 +1,15 @@
+# Repository Structure
+
+```text
+assets/opencode/        Curated OpenCode assets
+bin/                    Executable CLI shim
+docs/                   User and maintainer documentation
+examples/opencode/      Placeholder-only OpenCode examples
+packages/adapter-sdk/   Future adapter interfaces
+packages/cli/           CLI TypeScript source skeleton
+packages/manifest/      Manifest schema and validation helpers
+packages/opencode-plugin/ OpenCode plugin skeleton
+scripts/                Dependency-free validation scripts
+```
+
+Session records are stored under `.bros/` and are not included in the npm package allowlist.

package/docs/roadmap.md

@@ -0,0 +1,20 @@
+# Roadmap
+
+## Now
+
+- Sanitized OpenCode asset scaffold.
+- Package metadata and safe CLI placeholder.
+- Validation scripts and guarded CI.
+
+## Next
+
+- Review imported assets for public readability and policy clarity.
+- Implement manifest-driven OpenCode install flow with explicit user confirmation.
+- Add adapter implementations after design and security review.
+
+## Later
+
+- Claude adapter.
+- Codex adapter.
+- IDE extension guidance.
+- Release automation after final approval.

package/docs/security.md

@@ -0,0 +1,18 @@
+# Security
+
+This repository intentionally avoids raw provider configuration and secret validation. The scaffold includes only curated asset directories and placeholder examples.
+
+## Guardrails
+
+- No raw OpenCode config import.
+- No dependency install, publish, deploy, or production access in the initial build.
+- No examples with live credentials.
+- Runtime plugin config changes are limited to OpenCode's in-memory `config(cfg)` hook for package-relative `skills.paths` and non-overwriting command prompt entries.
+- No live user config file mutation: the package plugin does not write `opencode.json`, `.opencode/`, global config files, or other filesystem config.
+- No provider, MCP, permission, telemetry, or secret registration by the package plugin.
+- Mutating contributor import tooling is maintainer-only and excluded from the published package surface.
+- Final publishing requires a fresh security review.
+
+## Validation
+
+`scripts/verify-no-secrets.mjs` provides dependency-free checks for common secret-like patterns. It is not a replacement for human security review.

package/docs/testing.md

@@ -0,0 +1,9 @@
+# Testing
+
+Current checks are dependency-free:
+
+```bash
+npm run validate
+```
+
+This runs asset manifest validation and secret-pattern scanning. Future tests should cover installer dry runs, adapter contracts, and plugin loading behavior.

package/examples/opencode/README.md

@@ -0,0 +1,11 @@
+# OpenCode Example
+
+The package-first example uses the BROS Harness plugin snippet:
+
+```json
+{
+  "plugin": ["bros-harness"]
+}
+```
+
+This example does not include provider keys, private endpoints, MCP servers, permissions, telemetry, credentials, or local absolute paths. Restart OpenCode after applying an approved config change.

package/examples/opencode/opencode.example.jsonc

@@ -0,0 +1,4 @@
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["bros-harness"]
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "bros-harness",
+  "version": "0.1.0",
+  "description": "Package-first OpenCode plugin for disciplined BROS agent harness assets.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./src/plugin.mjs",
+  "exports": {
+    ".": "./src/plugin.mjs",
+    "./plugin": "./src/plugin.mjs",
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "bros": "./bin/bros.mjs"
+  },
+  "files": [
+    "assets/",
+    "bin/",
+    "docs/",
+    "examples/",
+    "scripts/validate-assets.mjs",
+    "scripts/verify-no-secrets.mjs",
+    "src/",
+    "README.md",
+    "LICENSE",
+    "SECURITY.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "validate": "node scripts/validate-assets.mjs && node scripts/verify-no-secrets.mjs",
+    "validate:assets": "node scripts/validate-assets.mjs",
+    "verify:no-secrets": "node scripts/verify-no-secrets.mjs"
+  },
+  "keywords": [
+    "opencode",
+    "agents",
+    "harness",
+    "cli"
+  ],
+  "engines": {
+    "node": ">=20"
+  }
+}

package/scripts/validate-assets.mjs

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+import { access, readFile } from "node:fs/promises";
+
+const requiredPaths = [
+  "assets/opencode/agents",
+  "assets/opencode/commands",
+  "assets/opencode/skills",
+  "assets/opencode/templates",
+  "assets/opencode/docs",
+  "assets/manifest.json"
+];
+
+for (const path of requiredPaths) {
+  await access(path);
+}
+
+const manifest = JSON.parse(await readFile("assets/manifest.json", "utf8"));
+if (manifest.name !== "bros-harness" || !Array.isArray(manifest.entries)) {
+  throw new Error("Invalid asset manifest shape.");
+}
+
+console.log(`Validated ${manifest.entries.length} manifest entries.`);

package/scripts/verify-no-secrets.mjs

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+import { readdir, readFile } from "node:fs/promises";
+import { join, relative } from "node:path";
+
+const root = process.cwd();
+const ignored = new Set([".git", "node_modules", "dist", "coverage"]);
+const secretPatterns = [
+  /api[_-]?key\s*[:=]\s*['\"][^'\"]{8,}/i,
+  /authorization\s*[:=]\s*['\"]?bearer\s+[a-z0-9._-]{8,}/i,
+  /-----BEGIN (?:RSA |OPENSSH |EC |DSA )?PRIVATE KEY-----/,
+  /(?:token|secret|password)\s*[:=]\s*['\"][^'\"]{8,}/i
+];
+
+async function* walk(dir) {
+  for (const entry of await readdir(dir, { withFileTypes: true })) {
+    if (ignored.has(entry.name)) continue;
+    const path = join(dir, entry.name);
+    if (entry.isDirectory()) yield* walk(path);
+    else yield path;
+  }
+}
+
+const findings = [];
+for await (const file of walk(root)) {
+  const rel = relative(root, file);
+  const text = await readFile(file, "utf8").catch(() => "");
+  for (const pattern of secretPatterns) {
+    if (pattern.test(text)) findings.push(rel);
+  }
+}
+
+if (findings.length > 0) {
+  console.error("Potential secret-like content found in files:");
+  for (const file of findings) console.error(`- ${file}`);
+  process.exit(1);
+}
+
+console.log("No secret-like content detected by scaffold patterns.");

package/src/plugin.mjs

@@ -0,0 +1,98 @@
+import { access, readdir, readFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+const assetRoot = join(packageRoot, "assets", "opencode");
+
+export const brosHarness = Object.freeze({
+  name: "bros-harness",
+  packageRoot,
+  assetRoot,
+  agentsDir: join(assetRoot, "agents"),
+  commandsDir: join(assetRoot, "commands"),
+  skillsDir: join(assetRoot, "skills"),
+  docsDir: join(assetRoot, "docs"),
+  templatesDir: join(assetRoot, "templates")
+});
+
+const requiredAssetDirs = [
+  brosHarness.agentsDir,
+  brosHarness.commandsDir,
+  brosHarness.skillsDir,
+  brosHarness.docsDir,
+  brosHarness.templatesDir
+];
+
+export async function verifyBrosHarnessAssets() {
+  await Promise.all(requiredAssetDirs.map((path) => access(path)));
+  return brosHarness;
+}
+
+function parseCommandMarkdown(markdown) {
+  const match = markdown.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+  if (!match) {
+    return { description: "BROS Harness command.", prompt: markdown.trim() };
+  }
+
+  const descriptionMatch = match[1].match(/^description:\s*(.+)$/m);
+  const description = descriptionMatch?.[1]?.replace(/^['\"]|['\"]$/g, "").trim();
+  return {
+    description: description || "BROS Harness command.",
+    prompt: match[2].trim()
+  };
+}
+
+async function loadPackagedCommands() {
+  const files = (await readdir(brosHarness.commandsDir))
+    .filter((file) => file.endsWith(".md"))
+    .filter((file) => file !== "README.md")
+    .sort();
+
+  const commands = {};
+  for (const file of files) {
+    const name = file.replace(/\.md$/, "");
+    const markdown = await readFile(join(brosHarness.commandsDir, file), "utf8");
+    commands[name] = parseCommandMarkdown(markdown);
+  }
+  return commands;
+}
+
+function mergeSkillsPath(cfg) {
+  if (cfg.skills !== undefined && (cfg.skills === null || typeof cfg.skills !== "object" || Array.isArray(cfg.skills))) {
+    return;
+  }
+
+  cfg.skills ??= {};
+  if (cfg.skills.paths !== undefined && !Array.isArray(cfg.skills.paths)) {
+    return;
+  }
+
+  cfg.skills.paths ??= [];
+  if (!cfg.skills.paths.includes(brosHarness.skillsDir)) {
+    cfg.skills.paths.push(brosHarness.skillsDir);
+  }
+}
+
+function mergeCommands(cfg, commands) {
+  if (cfg.command !== undefined && (cfg.command === null || typeof cfg.command !== "object" || Array.isArray(cfg.command))) {
+    return;
+  }
+
+  cfg.command ??= {};
+  for (const [name, command] of Object.entries(commands)) {
+    cfg.command[name] ??= command;
+  }
+}
+
+export default async function brosHarnessPlugin(_input = {}, _options = {}) {
+  await verifyBrosHarnessAssets();
+  const commands = await loadPackagedCommands();
+
+  return {
+    config(cfg) {
+      mergeSkillsPath(cfg);
+      mergeCommands(cfg, commands);
+    }
+  };
+}