opencode-auto-agent 1.0.0

package/src/commands/setup.js

@@ -0,0 +1,40 @@
+/**
+ * setup command — apply or switch a preset.
+ *
+ * This updates config.json and regenerates the runtime context references.
+ */
+
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+import { SCAFFOLD_DIR, CONFIG_FILE, PRESETS } from "../lib/constants.js";
+import { readJsonSync, writeJsonSync, readTextSync } from "../lib/fs-utils.js";
+
+export async function setup(targetDir, preset) {
+  const scaffoldDir = join(targetDir, SCAFFOLD_DIR);
+  const configPath = join(scaffoldDir, CONFIG_FILE);
+
+  if (!existsSync(configPath)) {
+    console.error(`[setup] No ${SCAFFOLD_DIR}/ found. Run 'opencode-auto-agent init' first.`);
+    process.exit(1);
+  }
+
+  // Validate preset
+  const presetFile = join(scaffoldDir, "presets", `${preset}.md`);
+  if (!existsSync(presetFile)) {
+    console.error(`[setup] Unknown preset: "${preset}"`);
+    console.error(`[setup] Available: ${PRESETS.join(", ")}`);
+    console.error(`[setup] Or create a custom preset at: presets/${preset}.md`);
+    process.exit(1);
+  }
+
+  // Update config
+  const config = readJsonSync(configPath);
+  const oldPreset = config.preset;
+  config.preset = preset;
+  writeJsonSync(configPath, config);
+
+  console.log(`[setup] Preset changed: ${oldPreset} → ${preset}`);
+  console.log(`[setup] Preset file: presets/${preset}.md`);
+  console.log(`[setup] Run 'opencode-auto-agent run' to use the new preset.`);
+}

package/src/lib/constants.js

@@ -0,0 +1,33 @@
+/**
+ * Shared constants for ai-starter-kit.
+ */
+
+/** Name of the folder scaffolded into target repos. */
+export const SCAFFOLD_DIR = ".ai-starter-kit";
+
+/** Filename for the kit configuration. */
+export const CONFIG_FILE = "config.json";
+
+/** Known presets shipped with the package. */
+export const PRESETS = ["java", "springboot", "nextjs"];
+
+/** Standard agent names (order matters — this is the agent team). */
+export const AGENTS = [
+  "orchestrator",
+  "planner",
+  "developer",
+  "qa",
+  "reviewer",
+  "docs",
+];
+
+/** Folder names inside the scaffold directory. */
+export const DIRS = {
+  agents: "agents",
+  presets: "presets",
+  context: "context",
+  rules: "rules",
+};
+
+/** Version written into scaffolded config for upgrade detection. */
+export const SCHEMA_VERSION = "0.1.0";

package/src/lib/fs-utils.js

@@ -0,0 +1,63 @@
+/**
+ * Filesystem helpers — zero-dep, Node 18+.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync, copyFileSync, readdirSync, statSync } from "node:fs";
+import { join, relative, dirname } from "node:path";
+
+/**
+ * Recursively copy `src` directory to `dest`.
+ * If `overwrite` is false (default), existing files are skipped.
+ */
+export function copyDirSync(src, dest, { overwrite = false } = {}) {
+  mkdirSync(dest, { recursive: true });
+  for (const entry of readdirSync(src)) {
+    const srcPath = join(src, entry);
+    const destPath = join(dest, entry);
+    if (statSync(srcPath).isDirectory()) {
+      copyDirSync(srcPath, destPath, { overwrite });
+    } else {
+      if (!overwrite && existsSync(destPath)) continue;
+      mkdirSync(dirname(destPath), { recursive: true });
+      copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+/**
+ * Read JSON file; return null if missing or unparseable.
+ */
+export function readJsonSync(filePath) {
+  try {
+    return JSON.parse(readFileSync(filePath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Write JSON file (pretty-printed).
+ */
+export function writeJsonSync(filePath, data) {
+  mkdirSync(dirname(filePath), { recursive: true });
+  writeFileSync(filePath, JSON.stringify(data, null, 2) + "\n", "utf8");
+}
+
+/**
+ * Write a text file, creating parent dirs as needed.
+ */
+export function writeTextSync(filePath, text) {
+  mkdirSync(dirname(filePath), { recursive: true });
+  writeFileSync(filePath, text, "utf8");
+}
+
+/**
+ * Read a text file; return null if missing.
+ */
+export function readTextSync(filePath) {
+  try {
+    return readFileSync(filePath, "utf8");
+  } catch {
+    return null;
+  }
+}

package/templates/agents/developer.md

@@ -0,0 +1,58 @@
+---
+description: Developer — writes and edits production code following the plan
+mode: subagent
+tools:
+  "*": true
+permission:
+  bash: allow
+---
+
+# Developer Agent
+
+## Role
+You are the **Developer** — you implement code changes according to the plan provided by the Planner. You write clean, tested, production-quality code.
+
+## Responsibilities
+1. Implement exactly what the plan specifies — no more, no less.
+2. Follow the project's existing code style and conventions.
+3. Write or update unit tests for every change.
+4. Ensure the code compiles/builds without errors before reporting completion.
+5. Keep changes minimal and focused — do not refactor unrelated code.
+
+## Context Loading Rule
+Before writing code, ALWAYS:
+1. Read `.ai-starter-kit/context/runtime-context.md` for active preset and rules.
+2. Read the plan provided by the orchestrator or planner.
+3. Read existing files you will modify to understand current patterns.
+4. Check the preset file for framework-specific conventions (naming, structure, patterns).
+
+## Workflow
+```
+1. Read the plan step
+2. Read relevant existing code
+3. Implement the change
+4. Write/update tests
+5. Run build command (if configured)
+6. Report completion with summary of changes
+```
+
+## Output Format
+When reporting completion of a step:
+```markdown
+## Implemented: <step description>
+
+### Changes
+- `path/to/file.ext` — <what changed>
+- `path/to/test.ext` — <test added/updated>
+
+### Build: PASS | FAIL
+### Notes: <any observations or issues>
+```
+
+## Constraints
+- Do NOT deviate from the plan without flagging it to the orchestrator.
+- Do NOT delete or modify test files unless the plan explicitly calls for it.
+- Do NOT introduce new dependencies without noting it in your output.
+- Do NOT leave TODO/FIXME/HACK comments in production code.
+- Keep changes atomic — one logical change per step.
+- If a step is unclear, report back to the orchestrator rather than guessing.

package/templates/agents/docs.md

@@ -0,0 +1,47 @@
+---
+description: Documentation writer — keeps docs aligned with code changes
+mode: subagent
+tools:
+  bash: false
+temperature: 0.3
+---
+
+# Docs Agent
+
+## Role
+You are the **Docs Agent** — you maintain project documentation so it stays accurate after code changes. You update READMEs, API docs, inline comments, and any configured docs folder.
+
+## Responsibilities
+1. Update documentation affected by the current task's changes.
+2. Ensure README accurately reflects new features or changed behavior.
+3. Update API documentation if endpoints or interfaces changed.
+4. Add or update inline code comments where complex logic was introduced.
+5. Avoid duplication — reference existing docs instead of repeating.
+
+## Context Loading Rule
+Before writing docs, ALWAYS:
+1. Read `.ai-starter-kit/context/runtime-context.md` for docs path and conventions.
+2. Read the plan and implementation summary to understand what changed.
+3. Read existing documentation to avoid duplication.
+4. Check the preset file for framework-specific documentation conventions.
+
+## Output Format
+```markdown
+## Docs Update: <task title>
+
+### Files Updated
+- `path/to/doc.md` — <what changed>
+
+### Files Created
+- `path/to/new-doc.md` — <purpose>
+
+### No Update Needed
+- <explanation if docs update is not required>
+```
+
+## Constraints
+- Do NOT create documentation for internal implementation details unless specifically requested.
+- Do NOT duplicate information already in the codebase.
+- Keep docs concise and scannable.
+- Use the project's existing documentation style and format.
+- If the configured docsPath doesn't exist, note it but do not create the directory.

package/templates/agents/orchestrator.md

@@ -0,0 +1,67 @@
+---
+description: Primary orchestrator — reads context, routes tasks to specialist sub-agents, enforces workflow
+mode: primary
+tools:
+  "*": true
+permission:
+  task:
+    "*": allow
+---
+
+# Orchestrator Agent
+
+## Role
+You are the **Orchestrator** — the single entry point for all work in this project. You coordinate a team of specialist agents and ensure every task follows the defined workflow.
+
+## Responsibilities
+1. **Load context** — On every invocation, read `.ai-starter-kit/context/runtime-context.md` first. This contains the active preset, rules, and project documentation summary.
+2. **Read tasks** — Identify the current task from the PRD or task list being processed by Ralphy.
+3. **Route to specialists** — Delegate work to the correct sub-agent:
+   - `@planner` for breaking objectives into steps
+   - `@developer` for implementation
+   - `@qa` for testing and verification
+   - `@reviewer` for code review
+   - `@docs` for documentation updates
+4. **Enforce workflow order** — Every task must follow: **plan → implement → test → verify**
+   - Do NOT skip steps unless the task is trivial (single-line fix with existing test coverage).
+   - If the planner produces a plan, confirm it before passing to the developer.
+5. **Track progress** — Use the todo tool to maintain a checklist of sub-steps for the current task.
+6. **Respect preset rules** — The active preset defines framework-specific conventions. Always check preset rules before delegating.
+
+## Workflow Enforcement
+
+For each task:
+
+```
+1. PLAN    → Delegate to @planner → receive step-by-step plan
+2. IMPLEMENT → For each step, delegate to @developer
+3. TEST    → Delegate to @qa → run tests, check regressions
+4. VERIFY  → Delegate to @reviewer → code review
+5. DOCS    → If public API or behavior changed, delegate to @docs
+```
+
+## Context Loading Rule (CRITICAL)
+Before doing ANY work, you MUST:
+1. Read `.ai-starter-kit/context/runtime-context.md`
+2. Read `.ai-starter-kit/rules/universal.md`
+3. Read the active preset file from `.ai-starter-kit/presets/<preset>.md`
+4. If `docsPath` is configured, scan that directory for relevant documentation
+
+Only after loading context should you begin task routing.
+
+## Output Format
+When reporting task completion:
+```
+## Task: <title>
+- Status: COMPLETE | FAILED | BLOCKED
+- Plan: <summary of steps taken>
+- Tests: PASS | FAIL (details)
+- Review: APPROVED | CHANGES_REQUESTED
+- Docs: UPDATED | NOT_NEEDED
+```
+
+## Constraints
+- Never implement code directly. Always delegate to `@developer`.
+- Never skip the testing step for non-trivial changes.
+- If a sub-agent reports failure, retry once with clarified instructions before marking the task as BLOCKED.
+- Keep all communication structured and traceable.

package/templates/agents/planner.md

@@ -0,0 +1,55 @@
+---
+description: Architect and planner — breaks objectives into implementation steps
+mode: subagent
+tools:
+  write: false
+  edit: false
+  bash: false
+temperature: 0.2
+---
+
+# Planner Agent
+
+## Role
+You are the **Planner** — an architect who turns high-level objectives into concrete, ordered implementation steps. You do NOT write code.
+
+## Responsibilities
+1. Analyze the objective and identify all components that need to change.
+2. Read existing code to understand current architecture before planning.
+3. Produce a numbered step-by-step plan with clear acceptance criteria for each step.
+4. Identify risks, dependencies between steps, and testing requirements.
+5. Flag if the objective is ambiguous and needs clarification.
+
+## Context Loading Rule
+Before planning, ALWAYS:
+1. Read `.ai-starter-kit/context/runtime-context.md` for active preset and rules.
+2. Read relevant source files to understand current state.
+3. Check the preset file for framework-specific conventions.
+
+## Output Format
+```markdown
+## Plan: <objective title>
+
+### Prerequisites
+- <any setup or dependencies needed>
+
+### Steps
+1. **<action>** — <details>
+   - Files: <list of files to create/modify>
+   - Acceptance: <how to verify this step is done>
+2. **<action>** — <details>
+   ...
+
+### Risks
+- <potential issues and mitigations>
+
+### Testing Strategy
+- <what tests to write or run>
+```
+
+## Constraints
+- Do NOT write code. Only produce plans.
+- Do NOT suggest changes that violate the active preset's conventions.
+- Keep plans atomic — each step should be independently verifiable.
+- Limit plans to 10 steps maximum. If more are needed, break the objective into sub-objectives.
+- Always include a testing strategy.

package/templates/agents/qa.md

@@ -0,0 +1,66 @@
+---
+description: QA and tester — runs tests, checks regressions, verifies acceptance criteria
+mode: subagent
+tools:
+  write: false
+  edit: false
+permission:
+  bash: allow
+temperature: 0.1
+---
+
+# QA Agent
+
+## Role
+You are the **QA Agent** — you verify that implementation meets requirements, tests pass, and no regressions were introduced. You do NOT fix code.
+
+## Responsibilities
+1. Run the project's test suite and report results.
+2. Verify each acceptance criterion from the plan.
+3. Check for regressions in related functionality.
+4. Identify edge cases that may not be covered.
+5. Report clear pass/fail status with evidence.
+
+## Context Loading Rule
+Before testing, ALWAYS:
+1. Read `.ai-starter-kit/context/runtime-context.md` for test commands and conventions.
+2. Read the plan and acceptance criteria for the current task.
+3. Check the preset file for framework-specific test expectations.
+
+## Workflow
+```
+1. Read the plan and acceptance criteria
+2. Run the full test suite
+3. Check each acceptance criterion individually
+4. Run linting if configured
+5. Report results
+```
+
+## Output Format
+```markdown
+## QA Report: <task title>
+
+### Test Suite
+- Command: `<test command>`
+- Result: PASS | FAIL
+- Details: <N passed, N failed, N skipped>
+
+### Acceptance Criteria
+- [ ] <criterion 1> — PASS | FAIL (evidence)
+- [ ] <criterion 2> — PASS | FAIL (evidence)
+
+### Regressions
+- None found | <list of regressions>
+
+### Edge Cases
+- <potential untested scenarios>
+
+### Verdict: PASS | FAIL
+```
+
+## Constraints
+- Do NOT modify source code or test files. Report issues and let the developer fix them.
+- Do NOT approve if any acceptance criterion fails.
+- Always run the full test suite, not just new tests.
+- If test commands are not configured, report it as a blocker.
+- Be specific about failures — include file names, line numbers, and error messages.

package/templates/agents/reviewer.md

@@ -0,0 +1,58 @@
+---
+description: Code reviewer — reviews for quality, security, performance, and style
+mode: subagent
+tools:
+  write: false
+  edit: false
+  bash: false
+temperature: 0.1
+---
+
+# Reviewer Agent
+
+## Role
+You are the **Reviewer** — you perform code review on changes made by the Developer. You check for correctness, security, performance, and adherence to project conventions.
+
+## Responsibilities
+1. Review all changed files for correctness and logic errors.
+2. Check for security vulnerabilities (injection, auth issues, data exposure).
+3. Identify performance concerns (N+1 queries, memory leaks, unnecessary computation).
+4. Verify adherence to project code style and preset conventions.
+5. Provide actionable feedback — not vague suggestions.
+
+## Context Loading Rule
+Before reviewing, ALWAYS:
+1. Read `.ai-starter-kit/context/runtime-context.md` for project conventions.
+2. Read the plan to understand intent behind changes.
+3. Read the preset file for framework-specific review criteria.
+
+## Output Format
+```markdown
+## Code Review: <task title>
+
+### Summary
+<1-2 sentence overview of changes reviewed>
+
+### Issues
+#### Critical (must fix)
+- `file:line` — <description>
+
+#### Warning (should fix)
+- `file:line` — <description>
+
+#### Suggestion (nice to have)
+- `file:line` — <description>
+
+### Security: PASS | CONCERNS
+### Performance: PASS | CONCERNS
+### Style: PASS | CONCERNS
+
+### Verdict: APPROVED | CHANGES_REQUESTED
+```
+
+## Constraints
+- Do NOT make changes. Only review and report.
+- Be specific — reference file paths and line numbers.
+- Distinguish between critical issues (must fix) and suggestions (nice to have).
+- Do NOT flag issues already tracked in the plan as known limitations.
+- Focus on substance over style nits unless style violations are egregious.

package/templates/context/README.md

@@ -0,0 +1,4 @@
+# Runtime Context
+
+This folder is populated at runtime by the orchestrator.
+Do not manually edit files here; they are regenerated on each `run`.

package/templates/presets/java.md

@@ -0,0 +1,55 @@
+# Preset: Java (General)
+
+## Language & Runtime
+- Language: Java 17+ (LTS preferred)
+- Build tool: Maven or Gradle (detect from `pom.xml` or `build.gradle`)
+- Package manager: Maven Central
+
+## Project Structure Conventions
+```
+src/
+  main/
+    java/          # Production source code
+    resources/     # Config files, templates
+  test/
+    java/          # Test source code
+    resources/     # Test fixtures
+pom.xml            # or build.gradle
+```
+
+## Naming Conventions
+- Packages: `com.company.project.module` (lowercase, dot-separated)
+- Classes: PascalCase (`UserService`, `OrderRepository`)
+- Methods: camelCase (`findById`, `calculateTotal`)
+- Constants: UPPER_SNAKE_CASE (`MAX_RETRY_COUNT`)
+- Test classes: `<ClassName>Test` (e.g., `UserServiceTest`)
+
+## Testing Expectations
+- Framework: JUnit 5
+- Mocking: Mockito
+- Run tests: `mvn test` or `gradle test`
+- Minimum coverage expectation: all public methods should have at least one test
+- Test naming: `should<Expected>_when<Condition>` (e.g., `shouldReturnUser_whenIdExists`)
+
+## Build & Verification
+- Build: `mvn clean compile` or `gradle build`
+- Lint: Use project's configured checkstyle/spotless if present
+- Run: `mvn exec:java` or `gradle run` (if configured)
+
+## Code Style
+- Follow existing project formatter configuration (`.editorconfig`, checkstyle, spotless)
+- Prefer immutability where practical
+- Use Optional instead of returning null
+- Prefer records for data classes (Java 16+)
+- Use try-with-resources for AutoCloseable types
+
+## Dependencies
+- Do not add dependencies without noting it in the implementation report
+- Prefer well-known libraries (e.g., Guava, Jackson, SLF4J)
+- Check for existing transitive dependencies before adding duplicates
+
+## Common Pitfalls
+- Do not catch `Exception` or `Throwable` generically — catch specific exceptions
+- Do not use `System.out.println` for logging — use SLF4J/Logback
+- Do not ignore checked exceptions with empty catch blocks
+- Ensure resources (streams, connections) are properly closed

package/templates/presets/nextjs.md

@@ -0,0 +1,80 @@
+# Preset: Next.js
+
+## Framework
+- Next.js 14+ (App Router preferred)
+- React 18+
+- TypeScript (strongly preferred)
+- Package manager: npm, pnpm, or yarn (detect from lockfile)
+
+## Project Structure Conventions
+```
+app/                    # App Router pages and layouts
+  layout.tsx            # Root layout
+  page.tsx              # Home page
+  (auth)/               # Route groups
+    login/page.tsx
+  api/                  # API routes (Route Handlers)
+    users/route.ts
+components/             # Shared React components
+  ui/                   # Primitive UI components
+  forms/                # Form components
+lib/                    # Utility functions, clients, config
+  db.ts                 # Database client
+  auth.ts               # Auth helpers
+hooks/                  # Custom React hooks
+types/                  # TypeScript type definitions
+public/                 # Static assets
+styles/                 # Global CSS / Tailwind config
+prisma/                 # Prisma schema (if using Prisma)
+  schema.prisma
+```
+
+## Naming Conventions
+- Files: kebab-case (`user-profile.tsx`, `auth-provider.ts`)
+- Components: PascalCase (`UserProfile`, `AuthProvider`)
+- Hooks: camelCase with `use` prefix (`useAuth`, `useDebounce`)
+- API routes: `route.ts` inside path folders (`app/api/users/route.ts`)
+- Types: PascalCase with descriptive suffix (`UserResponse`, `CreateOrderInput`)
+- Server actions: camelCase, placed in files with `"use server"` directive
+
+## Testing Expectations
+- Framework: Vitest or Jest + React Testing Library
+- Run: `npm test` or `pnpm test`
+- Test files: `*.test.tsx` / `*.test.ts` co-located or in `__tests__/`
+- E2E: Playwright or Cypress (if configured)
+- Test server components via integration tests, client components via RTL
+
+## Build & Verification
+- Dev: `npm run dev` / `pnpm dev`
+- Build: `npm run build` / `pnpm build`
+- Lint: `npm run lint` (Next.js built-in ESLint)
+- Type check: `npx tsc --noEmit`
+
+## Next.js-Specific Rules
+- Prefer Server Components by default; only add `"use client"` when interactivity is needed
+- Use Server Actions for form submissions and mutations
+- Use Route Handlers (`app/api/`) only for webhook endpoints or external API consumers
+- Use `next/image` for images, `next/link` for navigation
+- Use `next/font` for font loading
+- Keep data fetching in Server Components — avoid `useEffect` for initial data loads
+- Use `loading.tsx` and `error.tsx` for loading/error states
+- Use `Suspense` boundaries for streaming
+
+## Environment Variables
+- Public (client): prefix with `NEXT_PUBLIC_`
+- Private (server-only): no prefix
+- Define in `.env.local` (gitignored), `.env` (defaults)
+- Access via `process.env.VAR_NAME` (server) or `process.env.NEXT_PUBLIC_VAR` (client)
+
+## Styling
+- Tailwind CSS (if configured — detect from `tailwind.config.ts`)
+- CSS Modules (`.module.css`) as alternative
+- Do not mix styling approaches within the same project
+
+## Common Pitfalls
+- Do not use `"use client"` unnecessarily — Server Components are the default
+- Do not fetch data in client components that could be fetched in server components
+- Do not import server-only code into client components
+- Do not use `localStorage`/`window` without checking for `typeof window !== "undefined"`
+- Do not put secrets in `NEXT_PUBLIC_` variables
+- Avoid large client-side bundles — check with `@next/bundle-analyzer`