opencode-auto-agent 1.0.0

package/README.md

@@ -0,0 +1,84 @@
+# opencode-auto-agent
+
+`opencode-auto-agent` is a lightweight starter template for running a reusable AI agent team with **Ralphy + OpenCode**.
+
+It scaffolds a standard project integration folder, ships language-agnostic agent definitions, and supports stack presets like Java, Spring Boot, and Next.js.
+
+## Features
+
+- One-command project setup
+- Reusable agent team (orchestrator, planner, developer, qa, reviewer, docs)
+- Preset-based context (Java, Spring Boot, Next.js)
+- Orchestrated workflow: plan -> implement -> test -> verify
+- Auto-release pipeline with semantic-release (GitHub Actions)
+
+## Installation
+
+Run directly with npx:
+
+```bash
+npx opencode-auto-agent init
+```
+
+Or install globally:
+
+```bash
+npm install -g opencode-auto-agent
+```
+
+## CLI
+
+```bash
+opencode-auto-agent init [--preset=<name>]
+opencode-auto-agent run [--engine=<name>]
+opencode-auto-agent setup <preset>
+opencode-auto-agent doctor
+```
+
+### Presets
+
+- `java`
+- `springboot`
+- `nextjs`
+
+## Quick Start
+
+```bash
+npx opencode-auto-agent init --preset=nextjs
+npx opencode-auto-agent doctor
+npx opencode-auto-agent run
+```
+
+## Generated Structure
+
+The `init` command creates:
+
+```text
+.ai-starter-kit/
+  agents/
+  presets/
+  context/
+  rules/
+  config.json
+```
+
+Plus helper config files:
+
+- `opencode.json`
+- `.ralphy/config.yaml`
+
+## Requirements
+
+- Node.js 18+
+- OpenCode CLI installed and configured
+- Ralphy CLI installed
+
+## Releasing
+
+Releases are fully automated via semantic-release on pushes to `main`.
+
+See `Docs/releasing.md` for details.
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+
+/**
+ * opencode-auto-agent CLI
+ *
+ * Commands:
+ *   init              Scaffold .ai-starter-kit/ into the current repo
+ *   run               Start the orchestrator (Ralphy + OpenCode agents)
+ *   setup <preset>    Apply or switch a preset (java, springboot, nextjs, ...)
+ *   doctor            Validate configuration and tool availability
+ */
+
+import { resolve, basename } from "node:path";
+import { argv, exit, cwd } from "node:process";
+
+// ── arg parsing (zero-dep) ─────────────────────────────────────────────────
+const args = argv.slice(2);
+const command = args[0] || "help";
+const positional = args.slice(1).filter((a) => !a.startsWith("--"));
+const flags = Object.fromEntries(
+  args
+    .filter((a) => a.startsWith("--"))
+    .map((a) => {
+      const [k, v] = a.replace(/^--/, "").split("=");
+      return [k, v ?? true];
+    })
+);
+
+const TARGET_DIR = resolve(flags.dir || cwd());
+
+// ── dynamic import of command modules ──────────────────────────────────────
+async function main() {
+  switch (command) {
+    case "init": {
+      const { init } = await import("../src/commands/init.js");
+      await init(TARGET_DIR, { preset: positional[0] || flags.preset });
+      break;
+    }
+    case "run": {
+      const { run } = await import("../src/commands/run.js");
+      await run(TARGET_DIR, flags);
+      break;
+    }
+    case "setup": {
+      const { setup } = await import("../src/commands/setup.js");
+      const preset = positional[0] || flags.preset;
+      if (!preset) {
+        console.error("Usage: opencode-auto-agent setup <preset>");
+        console.error("Available presets: java, springboot, nextjs");
+        exit(1);
+      }
+      await setup(TARGET_DIR, preset);
+      break;
+    }
+    case "doctor": {
+      const { doctor } = await import("../src/commands/doctor.js");
+      await doctor(TARGET_DIR);
+      break;
+    }
+    case "help":
+    case "--help":
+    case "-h":
+    default:
+      printHelp();
+      break;
+  }
+}
+
+function printHelp() {
+  const name = "opencode-auto-agent";
+  console.log(`
+${name} v0.1.0 — AI agent team starter kit (Ralphy + OpenCode)
+
+USAGE
+  npx ${name} <command> [options]
+
+COMMANDS
+  init [--preset=<name>]   Scaffold .ai-starter-kit/ into the current project
+  run  [--engine=<name>]   Start the orchestrator (Ralphy task loop)
+  setup <preset>           Apply or switch a preset (java | springboot | nextjs)
+  doctor                   Validate config, tools, and agent definitions
+
+OPTIONS
+  --dir=<path>             Target directory (default: cwd)
+  --preset=<name>          Preset to apply during init
+  --engine=<name>          Ralphy engine (opencode | claude | cursor, default: opencode)
+
+PRESETS
+  java         General Java project (Maven/Gradle)
+  springboot   Spring Boot web application
+  nextjs       Next.js (React) application
+
+EXAMPLES
+  npx ${name} init --preset=nextjs
+  npx ${name} run
+  npx ${name} setup springboot
+  npx ${name} doctor
+`);
+}
+
+main().catch((err) => {
+  console.error("Fatal:", err.message || err);
+  exit(1);
+});

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "opencode-auto-agent",
+  "version": "1.0.0",
+  "description": "Scaffold and run an AI agent team powered by Ralphy + OpenCode. Presets for Java, Spring Boot, Next.js, and more.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "opencode-auto-agent": "./bin/cli.js",
+    "aisk": "./bin/cli.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "templates/"
+  ],
+  "scripts": {
+    "dev": "node bin/cli.js",
+    "test": "node --test src/**/*.test.js 2>/dev/null || true",
+    "verify": "node bin/cli.js help"
+  },
+  "keywords": [
+    "ai",
+    "agents",
+    "opencode",
+    "ralphy",
+    "scaffolding",
+    "cli",
+    "orchestrator",
+    "starter-kit",
+    "code-generation"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/maystudios/opencode-auto-agent.git"
+  },
+  "homepage": "https://github.com/maystudios/opencode-auto-agent#readme",
+  "bugs": {
+    "url": "https://github.com/maystudios/opencode-auto-agent/issues"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "semantic-release": "^24.2.1",
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/github": "^11.0.1",
+    "@semantic-release/npm": "^12.0.1",
+    "@semantic-release/commit-analyzer": "^13.0.1",
+    "@semantic-release/release-notes-generator": "^14.0.3",
+    "conventional-changelog-conventionalcommits": "^8.0.0"
+  }
+}

package/src/commands/doctor.js

@@ -0,0 +1,91 @@
+/**
+ * doctor command — validate configuration and tool availability.
+ */
+
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { execSync } from "node:child_process";
+
+import { SCAFFOLD_DIR, CONFIG_FILE, DIRS, AGENTS, PRESETS } from "../lib/constants.js";
+import { readJsonSync } from "../lib/fs-utils.js";
+
+export async function doctor(targetDir) {
+  const scaffoldDir = join(targetDir, SCAFFOLD_DIR);
+  let errors = 0;
+  let warnings = 0;
+
+  console.log("[doctor] Checking opencode-auto-agent configuration...\n");
+
+  // 1. Scaffold directory exists
+  check("Scaffold directory", existsSync(scaffoldDir), `${SCAFFOLD_DIR}/ not found. Run 'opencode-auto-agent init'.`);
+
+  // 2. Config file
+  const configPath = join(scaffoldDir, CONFIG_FILE);
+  const config = readJsonSync(configPath);
+  check("Config file", !!config, `${CONFIG_FILE} missing or invalid JSON.`);
+
+  if (config) {
+    // 3. Preset is valid
+    const presetFile = join(scaffoldDir, DIRS.presets, `${config.preset}.md`);
+    check(`Preset "${config.preset}"`, existsSync(presetFile), `Preset file not found: presets/${config.preset}.md`);
+
+    // 4. Task file exists
+    const tasksPath = join(targetDir, config.tasksPath || "PRD.md");
+    warn(`Tasks file (${config.tasksPath || "PRD.md"})`, existsSync(tasksPath), "Create a PRD.md or update tasksPath in config.");
+  }
+
+  // 5. Agent markdowns
+  for (const agent of AGENTS) {
+    const agentFile = join(scaffoldDir, DIRS.agents, `${agent}.md`);
+    check(`Agent: ${agent}`, existsSync(agentFile), `Missing agent definition: agents/${agent}.md`);
+  }
+
+  // 6. Rules
+  const rulesDir = join(scaffoldDir, DIRS.rules, "universal.md");
+  check("Universal rules", existsSync(rulesDir), "Missing rules/universal.md");
+
+  // 7. External tools
+  checkTool("ralphy", "npm install -g ralphy-cli");
+  checkTool("opencode", "npm install -g opencode-ai");
+
+  // 8. OpenCode config
+  const ocConfig = join(targetDir, "opencode.json");
+  warn("opencode.json", existsSync(ocConfig), "Run 'opencode-auto-agent init' to generate it.");
+
+  console.log("\n[doctor] ─────────────────────────────────────────");
+  if (errors === 0 && warnings === 0) {
+    console.log("[doctor] All checks passed.");
+  } else {
+    console.log(`[doctor] ${errors} error(s), ${warnings} warning(s).`);
+  }
+
+  // ── helpers ──────────────────────────────────────────────────────────────
+
+  function check(label, ok, hint) {
+    if (ok) {
+      console.log(`  [pass] ${label}`);
+    } else {
+      console.log(`  [FAIL] ${label} — ${hint}`);
+      errors++;
+    }
+  }
+
+  function warn(label, ok, hint) {
+    if (ok) {
+      console.log(`  [pass] ${label}`);
+    } else {
+      console.log(`  [warn] ${label} — ${hint}`);
+      warnings++;
+    }
+  }
+
+  function checkTool(name, installHint) {
+    try {
+      execSync(`${name} --version`, { stdio: "pipe" });
+      console.log(`  [pass] CLI: ${name}`);
+    } catch {
+      console.log(`  [warn] CLI: ${name} not found. Install: ${installHint}`);
+      warnings++;
+    }
+  }
+}

package/src/commands/init.js

@@ -0,0 +1,190 @@
+/**
+ * init command — scaffold .ai-starter-kit/ into the target repository.
+ *
+ * Rules:
+ *  1. Never overwrite files that already exist (safe re-run).
+ *  2. Write config.json with schema version for future upgrades.
+ *  3. Copy agent markdowns, rules, and selected preset.
+ *  4. Create empty context/ folder for runtime context assembly.
+ */
+
+import { existsSync, mkdirSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { SCAFFOLD_DIR, CONFIG_FILE, PRESETS, AGENTS, DIRS, SCHEMA_VERSION } from "../lib/constants.js";
+import { copyDirSync, readJsonSync, writeJsonSync, writeTextSync } from "../lib/fs-utils.js";
+
+const __dirname = fileURLToPath(new URL(".", import.meta.url));
+const TEMPLATES_ROOT = resolve(__dirname, "..", "..", "templates");
+
+/**
+ * Default config written on first init.
+ */
+function makeDefaultConfig(preset) {
+  return {
+    $schema: "https://github.com/opencode-auto-agent/config-schema",
+    version: SCHEMA_VERSION,
+    preset: preset || "java",
+    docsPath: "./Docs",
+    tasksPath: "./PRD.md",
+    outputPath: "./",
+    engine: "opencode",
+    agents: AGENTS.reduce((acc, name) => {
+      acc[name] = { enabled: true };
+      return acc;
+    }, {}),
+    orchestrator: {
+      workflowSteps: ["plan", "implement", "test", "verify"],
+      requirePlanApproval: false,
+    },
+  };
+}
+
+export async function init(targetDir, { preset } = {}) {
+  const scaffoldDir = join(targetDir, SCAFFOLD_DIR);
+  const isUpgrade = existsSync(scaffoldDir);
+
+  if (isUpgrade) {
+    console.log(`[init] Existing ${SCAFFOLD_DIR}/ detected — upgrading (no overwrites).`);
+  } else {
+    console.log(`[init] Scaffolding ${SCAFFOLD_DIR}/ into ${targetDir}`);
+  }
+
+  // 1. Create directory skeleton
+  for (const sub of Object.values(DIRS)) {
+    mkdirSync(join(scaffoldDir, sub), { recursive: true });
+  }
+
+  // 2. Copy agent markdowns (skip existing)
+  const agentsSrc = join(TEMPLATES_ROOT, "agents");
+  const agentsDest = join(scaffoldDir, DIRS.agents);
+  copyDirSync(agentsSrc, agentsDest, { overwrite: false });
+  console.log(`[init] Agents written to ${DIRS.agents}/`);
+
+  // 3. Copy rules (skip existing)
+  const rulesSrc = join(TEMPLATES_ROOT, "rules");
+  const rulesDest = join(scaffoldDir, DIRS.rules);
+  copyDirSync(rulesSrc, rulesDest, { overwrite: false });
+  console.log(`[init] Rules written to ${DIRS.rules}/`);
+
+  // 4. Copy selected preset (or all presets)
+  const presetsSrc = join(TEMPLATES_ROOT, "presets");
+  const presetsDest = join(scaffoldDir, DIRS.presets);
+  copyDirSync(presetsSrc, presetsDest, { overwrite: false });
+  console.log(`[init] Presets written to ${DIRS.presets}/`);
+
+  // 5. Seed empty context readme
+  const contextReadme = join(scaffoldDir, DIRS.context, "README.md");
+  if (!existsSync(contextReadme)) {
+    writeTextSync(
+      contextReadme,
+      "# Runtime Context\n\nThis folder is populated at runtime by the orchestrator.\nDo not manually edit files here; they are regenerated on each `run`.\n"
+    );
+  }
+
+  // 6. Write config.json (only if missing)
+  const configPath = join(scaffoldDir, CONFIG_FILE);
+  if (!existsSync(configPath)) {
+    const chosenPreset = preset && PRESETS.includes(preset) ? preset : undefined;
+    writeJsonSync(configPath, makeDefaultConfig(chosenPreset));
+    console.log(`[init] Config written to ${CONFIG_FILE} (preset: ${chosenPreset || "java"})`);
+  } else {
+    console.log(`[init] Config already exists — skipped.`);
+  }
+
+  // 7. Generate opencode.json at project root if missing
+  const opencodeConfig = join(targetDir, "opencode.json");
+  if (!existsSync(opencodeConfig)) {
+    writeJsonSync(opencodeConfig, buildOpencodeConfig());
+    console.log(`[init] Generated opencode.json at project root.`);
+  }
+
+  // 8. Generate .ralphy/config.yaml stub if missing
+  const ralphyDir = join(targetDir, ".ralphy");
+  const ralphyConfig = join(ralphyDir, "config.yaml");
+  if (!existsSync(ralphyConfig)) {
+    mkdirSync(ralphyDir, { recursive: true });
+    writeTextSync(ralphyConfig, buildRalphyConfig());
+    console.log(`[init] Generated .ralphy/config.yaml`);
+  }
+
+  console.log(`\n[init] Done. Next steps:`);
+  console.log(`  1. Edit ${SCAFFOLD_DIR}/${CONFIG_FILE} to set your preset and paths.`);
+  console.log(`  2. Run: npx opencode-auto-agent doctor`);
+  console.log(`  3. Run: npx opencode-auto-agent run`);
+}
+
+// ── helpers ────────────────────────────────────────────────────────────────
+
+function buildOpencodeConfig() {
+  return {
+    $schema: "https://opencode.ai/config.json",
+    instructions: [
+      ".ai-starter-kit/agents/orchestrator.md",
+      ".ai-starter-kit/rules/universal.md",
+    ],
+    agent: {
+      orchestrator: {
+        description: "Primary orchestrator — routes tasks to specialist sub-agents",
+        mode: "primary",
+        prompt: "You are the orchestrator. Read .ai-starter-kit/context/ for active context. Follow the workflow: plan -> implement -> test -> verify.",
+        tools: { "*": true },
+        permission: {
+          task: { "*": "allow" },
+        },
+      },
+      planner: {
+        description: "Architect & planner — breaks objectives into steps",
+        mode: "subagent",
+        prompt: "You are the planner agent. Produce step-by-step implementation plans. Do not write code. Output plans as numbered markdown lists.",
+        tools: { write: false, edit: false, bash: false },
+      },
+      developer: {
+        description: "Developer — writes and edits production code",
+        mode: "subagent",
+        prompt: "You are the developer agent. Implement code changes per the plan. Follow project conventions. Write clean, tested code.",
+        tools: { "*": true },
+      },
+      qa: {
+        description: "QA / Tester — runs tests, verifies correctness",
+        mode: "subagent",
+        prompt: "You are the QA agent. Run tests, check for regressions, verify acceptance criteria. Report pass/fail status clearly.",
+        tools: { write: false },
+        permission: { bash: "allow" },
+      },
+      reviewer: {
+        description: "Code reviewer — reviews for quality, security, performance",
+        mode: "subagent",
+        prompt: "You are the reviewer agent. Review code for correctness, security issues, performance problems, and style violations. Do not make changes.",
+        tools: { write: false, edit: false, bash: false },
+      },
+      docs: {
+        description: "Documentation — keeps docs aligned with code changes",
+        mode: "subagent",
+        prompt: "You are the docs agent. Update documentation to reflect code changes. Keep README, API docs, and inline comments accurate.",
+        tools: { bash: false },
+      },
+    },
+  };
+}
+
+function buildRalphyConfig() {
+  return `# Ralphy configuration — generated by opencode-auto-agent
+project:
+  name: ""
+  language: ""
+  framework: ""
+  description: ""
+
+commands:
+  test: ""
+  lint: ""
+  build: ""
+
+rules:
+  - "Follow the plan produced by the planner agent before implementing."
+  - "Run tests after every implementation step."
+  - "Do not modify files outside the project source tree."
+`;
+}

package/src/commands/run.js

@@ -0,0 +1,147 @@
+/**
+ * run command — start the orchestrator.
+ *
+ * Flow:
+ *  1. Load config.json
+ *  2. Assemble runtime context (preset rules + base rules + docs)
+ *  3. Write assembled context to .ai-starter-kit/context/
+ *  4. Invoke Ralphy with --opencode engine against the PRD/task file
+ *  5. Ralphy drives OpenCode, which loads the orchestrator agent and delegates
+ */
+
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { execSync, spawn } from "node:child_process";
+
+import { SCAFFOLD_DIR, CONFIG_FILE, DIRS } from "../lib/constants.js";
+import { readJsonSync, readTextSync, writeTextSync } from "../lib/fs-utils.js";
+
+export async function run(targetDir, flags = {}) {
+  const scaffoldDir = join(targetDir, SCAFFOLD_DIR);
+  const configPath = join(scaffoldDir, CONFIG_FILE);
+
+  // 1. Load config
+  const config = readJsonSync(configPath);
+  if (!config) {
+    console.error(`[run] No config found at ${configPath}. Run 'opencode-auto-agent init' first.`);
+    process.exit(1);
+  }
+
+  console.log(`[run] Preset: ${config.preset}`);
+  console.log(`[run] Engine: ${flags.engine || config.engine || "opencode"}`);
+
+  // 2. Assemble runtime context
+  console.log("[run] Assembling runtime context...");
+  const context = assembleContext(targetDir, config);
+  const contextFile = join(scaffoldDir, DIRS.context, "runtime-context.md");
+  writeTextSync(contextFile, context);
+  console.log(`[run] Context written to ${DIRS.context}/runtime-context.md`);
+
+  // 3. Determine task file
+  const tasksPath = join(targetDir, config.tasksPath || "PRD.md");
+  if (!existsSync(tasksPath)) {
+    console.error(`[run] Task file not found: ${tasksPath}`);
+    console.error(`[run] Create a PRD.md or update tasksPath in config.json.`);
+    process.exit(1);
+  }
+
+  // 4. Invoke Ralphy
+  const engine = flags.engine || config.engine || "opencode";
+  const ralphyArgs = [
+    "--prd", tasksPath,
+    `--${engine}`,
+  ];
+
+  console.log(`[run] Starting Ralphy: ralphy ${ralphyArgs.join(" ")}`);
+  console.log("[run] ─────────────────────────────────────────────");
+
+  const child = spawn("ralphy", ralphyArgs, {
+    cwd: targetDir,
+    stdio: "inherit",
+    shell: true,
+    env: {
+      ...process.env,
+      // Pass context location to OpenCode via env
+      AISK_CONTEXT_DIR: join(scaffoldDir, DIRS.context),
+      AISK_CONFIG_PATH: configPath,
+    },
+  });
+
+  child.on("close", (code) => {
+    if (code === 0) {
+      console.log("\n[run] Orchestrator completed successfully.");
+    } else {
+      console.error(`\n[run] Orchestrator exited with code ${code}.`);
+      process.exit(code);
+    }
+  });
+
+  child.on("error", (err) => {
+    if (err.code === "ENOENT") {
+      console.error("[run] 'ralphy' CLI not found. Install it:");
+      console.error("  npm install -g ralphy-cli");
+    } else {
+      console.error("[run] Failed to start Ralphy:", err.message);
+    }
+    process.exit(1);
+  });
+}
+
+// ── context assembly ───────────────────────────────────────────────────────
+
+function assembleContext(targetDir, config) {
+  const scaffoldDir = join(targetDir, SCAFFOLD_DIR);
+  const sections = [];
+
+  sections.push("# Runtime Context (auto-generated)\n");
+  sections.push(`Preset: **${config.preset}**`);
+  sections.push(`Workflow: ${(config.orchestrator?.workflowSteps || []).join(" → ")}\n`);
+
+  // Base rules
+  const rulesDir = join(scaffoldDir, DIRS.rules);
+  if (existsSync(rulesDir)) {
+    for (const file of readdirSync(rulesDir).filter((f) => f.endsWith(".md"))) {
+      const content = readTextSync(join(rulesDir, file));
+      if (content) {
+        sections.push(`## Rules: ${file}\n${content}`);
+      }
+    }
+  }
+
+  // Preset rules
+  const presetFile = join(scaffoldDir, DIRS.presets, `${config.preset}.md`);
+  const presetContent = readTextSync(presetFile);
+  if (presetContent) {
+    sections.push(`## Preset: ${config.preset}\n${presetContent}`);
+  } else {
+    sections.push(`## Preset: ${config.preset}\n(No preset file found at ${presetFile})`);
+  }
+
+  // Repo docs (if configured and present)
+  const docsPath = join(targetDir, config.docsPath || "Docs");
+  if (existsSync(docsPath)) {
+    sections.push(`## Project Documentation\nDocs location: ${docsPath}`);
+    try {
+      const docFiles = readdirSync(docsPath).filter((f) => f.endsWith(".md"));
+      for (const file of docFiles.slice(0, 10)) {
+        const content = readTextSync(join(docsPath, file));
+        if (content) {
+          sections.push(`### ${file}\n${content.slice(0, 2000)}`);
+        }
+      }
+    } catch {
+      // non-fatal
+    }
+  }
+
+  // Agent manifest
+  sections.push("## Agent Team");
+  const agentsDir = join(scaffoldDir, DIRS.agents);
+  if (existsSync(agentsDir)) {
+    for (const file of readdirSync(agentsDir).filter((f) => f.endsWith(".md")).sort()) {
+      sections.push(`- ${file.replace(".md", "")}`);
+    }
+  }
+
+  return sections.join("\n\n");
+}