@opengroundplan/core 0.1.1

package/templates/agent-kits/core/files/.agent/delegate.mjs

@@ -0,0 +1,352 @@
+#!/usr/bin/env node
+/**
+ * Hands a task to another AI coding agent by running its CLI headlessly.
+ *
+ *   node .agent/delegate.mjs <task> "<prompt>"
+ *   node .agent/delegate.mjs bulk-edit "rename useAuth to useSession everywhere" --write
+ *   node .agent/delegate.mjs --list
+ *
+ * Routing comes from .agent/delegation.yaml. The first preferred tool that is actually
+ * installed wins, so a repo works on a machine that has only some of them.
+ *
+ * Zero dependencies on purpose: this must run in a freshly cloned repo before any install.
+ */
+import { execFile, execFileSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import process from 'node:process';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+/** Every tunable, in one place. */
+const config = {
+  routes: join(HERE, 'delegation.yaml'),
+  timeoutMs: Number(process.env.DELEGATE_TIMEOUT_MS ?? 900_000),
+  maxDepth: Number(process.env.DELEGATE_MAX_DEPTH ?? 2),
+  depthVar: 'DELEGATE_DEPTH',
+};
+
+/* ── guardrails ───────────────────────────────────────────────────────────── */
+
+/**
+ * A delegating to B delegating back to A burns budget until something dies. Depth travels
+ * in the environment, so it survives across process boundaries and tool vendors.
+ */
+function assertDepthAvailable() {
+  const depth = Number(process.env[config.depthVar] ?? 0);
+  if (depth >= config.maxDepth) {
+    fail(
+      `Delegation depth ${depth} reached the limit of ${config.maxDepth}.\n` +
+        `Something is delegating in a loop. Raise ${config.depthVar} deliberately if this is intended.`,
+    );
+  }
+  return depth;
+}
+
+/** Secrets in the parent environment must not ride along into another vendor's process. */
+const SECRET_PATTERN = /(_KEY|_TOKEN|_SECRET|PASSWORD|CREDENTIAL)/i;
+
+function childEnvironment(depth) {
+  const clean = {};
+  for (const [key, value] of Object.entries(process.env)) {
+    if (SECRET_PATTERN.test(key)) continue;
+    clean[key] = value;
+  }
+  // The delegated tool authenticates itself; it does not need ours.
+  clean[config.depthVar] = String(depth + 1);
+  return clean;
+}
+
+/* ── routing ──────────────────────────────────────────────────────────────── */
+
+/** Minimal YAML reader for the flat shape this file is generated in. */
+function readRoutes(file) {
+  const text = readFileSync(file, 'utf8');
+  const routes = [];
+  let current = null;
+
+  for (const raw of text.split(/\r?\n/)) {
+    const line = raw.replace(/#.*$/, '').trimEnd();
+    if (!line.trim()) continue;
+
+    const start = line.match(/^\s*-\s+task:\s*(.+)$/);
+    if (start) {
+      current = { task: unquote(start[1]), prefer: [], invoke: {} };
+      routes.push(current);
+      continue;
+    }
+    if (!current) continue;
+
+    const field = line.match(/^\s+(\w+):\s*(.*)$/);
+    if (!field) continue;
+    const [, key, value] = field;
+
+    if (key === 'prefer') current.prefer = parseList(value);
+    else if (key === 'why') current.why = unquote(value);
+  }
+  return routes;
+}
+
+function parseList(value) {
+  const inner = value.trim().replace(/^\[|\]$/g, '');
+  return inner ? inner.split(',').map((v) => unquote(v.trim())).filter(Boolean) : [];
+}
+
+function unquote(value) {
+  return value.trim().replace(/^['"]|['"]$/g, '');
+}
+
+/** Tool specs are inlined at generation time from each adapter's verified invoke block. */
+const TOOLS = JSON.parse(readFileSync(join(HERE, 'delegation-tools.json'), 'utf8'));
+
+/**
+ * Resolves a binary to an absolute path so it can be spawned WITHOUT a shell.
+ *
+ * Spawning through a shell would splice the prompt into a command line, and a prompt
+ * containing `&& …` would execute. Windows needs this resolution because npm installs
+ * globals as `.cmd` shims that `execFile` cannot launch directly.
+ */
+function resolveBinary(name) {
+  if (name.includes('/') || name.includes('\\')) return existsSync(name) ? name : null;
+
+  const isWindows = process.platform === 'win32';
+  // Real executables first. Node refuses to spawn a .cmd or .bat without a shell since the
+  // CVE-2024-27980 hardening, so a tool that ships both must be reached through the .exe;
+  // taking PATHEXT's own order would find the shim and report the tool as unusable.
+  const extensions = isWindows
+    ? ['.EXE', '.COM', ...(process.env.PATHEXT ?? '.COM;.EXE;.BAT;.CMD').split(';').filter(Boolean)]
+    : [''];
+
+  for (const dir of (process.env.PATH ?? '').split(isWindows ? ';' : ':')) {
+    if (!dir) continue;
+    for (const extension of extensions) {
+      const candidate = join(dir, name + extension);
+      if (existsSync(candidate)) return candidate;
+    }
+  }
+  return null;
+}
+
+/**
+ * npm and pnpm install global CLIs as `.cmd` shims, and Node will not spawn one with
+ * `shell: false`. Running it through `cmd.exe` would put the prompt on a command line that
+ * cmd re-parses, which is the injection this dispatcher exists to avoid — so the shim is
+ * reported as unusable, with the reason, rather than silently treated as absent.
+ *
+ * The prompt never reaches a command interpreter on any platform.
+ */
+function isBatchShim(path) {
+  return process.platform === 'win32' && /\.(cmd|bat)$/i.test(path);
+}
+
+/** Split on either line ending; several CLIs print a banner under the version. */
+const NEWLINE = new RegExp('\r?\n');
+
+const resolved = new Map();
+
+function binaryPath(id, tool) {
+  if (!resolved.has(id)) resolved.set(id, resolveBinary(tool.binary));
+  return resolved.get(id);
+}
+
+/**
+ * Probes the tool and keeps what it said.
+ *
+ * Deliberately not cached across runs and not persisted: a tool that was present an hour ago
+ * may be uninstalled, downgraded, or replaced by a shim that no longer starts. Every dispatch
+ * re-probes and reports what it found this time. The probe's own output is the version, so
+ * the record says which build actually ran rather than which one the adapter was verified
+ * against.
+ */
+function validate(id, tool) {
+  const at = new Date().toISOString();
+  const path = binaryPath(id, tool);
+  if (!path) {
+    return { tool: id, status: 'absent', binary: tool.binary, at, install: tool.install };
+  }
+
+  if (isBatchShim(path)) {
+    return {
+      tool: id,
+      status: 'unusable',
+      binary: path,
+      probe: [tool.binary, ...tool.detect].join(' '),
+      reason:
+        'installed as a .cmd shim, which Node cannot spawn without a shell — and a shell would ' +
+        'reparse the prompt. Install the native build, or run this tool directly.',
+      at,
+      install: tool.install,
+    };
+  }
+
+  try {
+    const output = execFileSync(path, tool.detect, {
+      encoding: 'utf8',
+      timeout: 10_000,
+      shell: false,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    return {
+      tool: id,
+      status: 'ok',
+      binary: path,
+      // First line only: several CLIs print a banner under the version.
+      version: (output ?? '').trim().split(NEWLINE)[0] || 'unreported',
+      probe: [tool.binary, ...tool.detect].join(' '),
+      at,
+    };
+  } catch (error) {
+    return {
+      tool: id,
+      status: 'unusable',
+      binary: path,
+      probe: [tool.binary, ...tool.detect].join(' '),
+      reason: error.code === 'EINVAL' && process.platform === 'win32'
+        ? 'EINVAL — Node refuses to spawn a .cmd/.bat shim directly (CVE-2024-27980 hardening)'
+        : String(error.code ?? error.message).split(NEWLINE)[0],
+      at,
+    };
+  }
+}
+
+function isInstalled(id, tool) {
+  return validate(id, tool).status === 'ok';
+}
+
+/* ── dispatch ─────────────────────────────────────────────────────────────── */
+
+function buildArgv(tool, prompt, { write, model }) {
+  const argv = tool.args.map((arg) => arg.replace('{prompt}', prompt));
+  if (write && tool.autoApprove.length) argv.push(...tool.autoApprove);
+  if (model && tool.modelFlag.length) {
+    argv.push(...tool.modelFlag.map((arg) => arg.replace('{model}', model)));
+  }
+  return argv;
+}
+
+async function run(tool, argv, depth) {
+  return new Promise((resolve) => {
+    const child = execFile(
+      binaryPath(chosen.tool, tool),
+      argv,
+      {
+        timeout: config.timeoutMs,
+        env: childEnvironment(depth),
+        maxBuffer: 32 * 1024 * 1024,
+        // Never true. The prompt is attacker-influenced text; a shell would execute it.
+        shell: false,
+      },
+      (error, stdout, stderr) => resolve({ error, stdout, stderr }),
+    );
+    child.stdout?.pipe(process.stdout);
+    child.stderr?.pipe(process.stderr);
+  });
+}
+
+/** The prompt carries source and file contents; the record reports its size, never its text. */
+function redactPrompt(argv) {
+  return argv.map((arg) =>
+    arg === prompt ? `<prompt:${prompt.length}chars>` : arg.split(prompt).join('<prompt>'),
+  );
+}
+
+function fail(message) {
+  console.error(`\n✖ ${message}`);
+  process.exit(1);
+}
+
+/* ── entry ────────────────────────────────────────────────────────────────── */
+
+const args = process.argv.slice(2);
+const flags = new Set(args.filter((a) => a.startsWith('--')));
+const positional = args.filter((a) => !a.startsWith('--'));
+const modelIndex = args.indexOf('--model');
+const model = modelIndex === -1 ? undefined : args[modelIndex + 1];
+
+const routes = readRoutes(config.routes);
+
+if (flags.has('--list') || positional.length === 0) {
+  console.log('\nRoutes (first installed tool wins):\n');
+  for (const route of routes) {
+    const available = route.prefer.filter((id) => TOOLS[id] && isInstalled(id, TOOLS[id]));
+    const status = available.length ? `→ ${available[0]}` : '→ none installed';
+    console.log(`  ${route.task.padEnd(24)} ${status.padEnd(20)} ${route.why ?? ''}`);
+  }
+  console.log('\nUsage: node .agent/delegate.mjs <task> "<prompt>" [--write] [--model <id>]\n');
+  process.exit(0);
+}
+
+const [task, ...promptParts] = positional;
+const prompt = promptParts.join(' ');
+if (!prompt) fail('No prompt given.\nUsage: node .agent/delegate.mjs <task> "<prompt>"');
+
+const route = routes.find((r) => r.task === task);
+if (!route) {
+  fail(`Unknown task "${task}". Known tasks:\n  ${routes.map((r) => r.task).join('\n  ')}`);
+}
+
+const depth = assertDepthAvailable();
+
+// Probe every candidate in preference order, now. Nothing carries over from a previous
+// dispatch: an earlier success is evidence about an earlier moment, not about this one.
+const checks = route.prefer.filter((id) => TOOLS[id]).map((id) => validate(id, TOOLS[id]));
+const chosen = checks.find((check) => check.status === 'ok');
+
+if (!chosen) {
+  const options = checks
+    .map((check) =>
+      check.status === 'absent'
+        ? `  ${check.tool.padEnd(18)} not on PATH — ${check.install ?? 'no install command recorded'}`
+        : `  ${check.tool.padEnd(18)} found at ${check.binary} but would not run: ${check.reason}`,
+    )
+    .join('\n');
+  fail(`No tool for "${task}" is usable. Preferred, in order:\n${options}`);
+}
+
+const candidate = TOOLS[chosen.tool];
+const write = flags.has('--write');
+const argv = buildArgv(candidate, prompt, { write, model });
+
+/**
+ * What ran, which build of it, how that was established, and when. stderr because ADR 0007
+ * reserves stdout for the tool's own output, and without the prompt, which routinely carries
+ * source and file contents.
+ */
+console.error(
+  `→ delegate ${JSON.stringify({
+    task,
+    tool: chosen.tool,
+    command: [candidate.binary, ...redactPrompt(argv)].join(' '),
+    binary: chosen.binary,
+    version: chosen.version,
+    validation: { status: chosen.status, probe: chosen.probe, at: chosen.at },
+    write,
+    autoApprove: write ? candidate.autoApprove : [],
+    model: model ?? null,
+    depth,
+  })}`,
+);
+
+for (const check of checks.filter((c) => c.status !== 'ok')) {
+  console.error(`  skipped ${check.tool}: ${check.status}${check.reason ? ` — ${check.reason}` : ''}`);
+}
+
+const startedAt = Date.now();
+const { error } = await run(candidate, argv, depth);
+
+console.error(
+  `← delegate ${JSON.stringify({
+    tool: chosen.tool,
+    status: error ? 'failed' : 'ok',
+    exitCode: error?.code ?? 0,
+    timedOut: Boolean(error?.killed),
+    durationMs: Date.now() - startedAt,
+    finishedAt: new Date().toISOString(),
+  })}`,
+);
+
+if (error) {
+  // Only Gemini and Qwen document exit-code meanings; for the rest, non-zero is all we get.
+  fail(`${chosen.tool} exited ${error.code ?? 'abnormally'}${error.killed ? ' (timed out)' : ''}`);
+}

package/templates/agent-kits/core/files/.agent/delegation-tools.json

@@ -0,0 +1 @@
+{{ delegationToolsJson }}

package/templates/agent-kits/core/files/.agent/delegation.yaml

@@ -0,0 +1,33 @@
+# Which AI tool gets which kind of task. Read by .agent/delegate.mjs, which runs the first
+# preferred tool that is actually installed — so this file works on any machine.
+#
+# Edit freely. The routing is a judgement call about cost and capability, not a fact.
+
+routes:
+  - task: bulk-edit
+    prefer: [codex, aider, cursor]
+    why: cheapest per token for deterministic transforms across many files
+
+  - task: refactor
+    prefer: [claude-code, codex, cursor]
+    why: multi-file planning with a review loop
+
+  - task: explain
+    prefer: [claude-code, amp, antigravity-cli, gemini-cli]
+    why: broad search and synthesis across the repo
+
+  - task: review
+    prefer: [claude-code, github-copilot]
+    why: diff-scoped review
+
+  - task: test-fix
+    prefer: [codex, claude-code, aider]
+    why: a failing test is ground truth, so a cheap tool with a real signal is enough
+
+  - task: docs
+    prefer: [antigravity-cli, gemini-cli, aider, continue]
+    why: low-stakes prose; use the cheapest tool that is installed
+
+  - task: security-review
+    prefer: [claude-code, github-copilot]
+    why: false negatives are expensive here; prefer the strongest reader available

package/templates/agent-kits/core/files/AGENTS.md

@@ -0,0 +1,107 @@
+# AGENTS.md
+
+Operational instructions for AI coding agents working in this repository.
+
+> **This file is the single source of truth.** Every other agent instruction file
+> (`CLAUDE.md`, `.cursor/rules/`, `.github/instructions/`, …) is a thin pointer to this one.
+> Edit here, then run `groundplan sync-agents` to propagate. Never duplicate content outward —
+> duplicated instructions drift, and drifted instructions are worse than none.
+
+## Project
+
+{{ solutionName | title }} — see [README.md](README.md).
+
+- **Stack:** {{ stack }}
+- **Architecture:** {{ architecture }} — layout and rules in [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
+
+## Commands
+
+Run these verbatim.
+
+| Task | Command |
+|---|---|
+| Build | `{{ buildCommand }}` |
+| Test | `{{ testCommand }}` |
+| Lint | `{{ lintCommand }}` |
+
+## Conventions
+
+Only what differs from language defaults is listed. Everything else follows the ecosystem norm.
+
+- Comments are short and explain **why**. Never narrate what the code already shows.
+- No hardcoded configuration in business logic — URLs, ports, keys, model ids, paths, and
+  limits resolve through the config layer with one typed default.
+- Match the surrounding file's style over any general convention.
+- Prefer editing an existing file to creating a new one.
+
+## Boundaries
+
+- Respect the {{ architecture }} layout. A change that crosses a boundary needs a reason
+  stated in the PR, not a workaround.
+- Import across modules only through a module's public surface.
+
+## Security
+
+- Never commit secrets. Configuration comes from the environment, not from source.
+- Validate and encode external input at the boundary.
+- Do not weaken auth, CORS, or CSP to make a test pass.
+
+## Protected paths
+
+Ask before editing. Where the tool supports hooks, this is enforced mechanically.
+
+```
+.env
+.env.*
+**/migrations/**
+.github/workflows/**
+```
+
+## Working with other agents
+
+This repo is worked on by more than one AI tool. State lives in `.agent/`, in plain markdown
+at fixed paths, so any tool can read and write it.
+
+| File | Read it when | Write it when |
+|---|---|---|
+| [.agent/ACTIVE.md](.agent/ACTIVE.md) | starting any task | you begin or finish a task |
+| [.agent/HANDOFF.md](.agent/HANDOFF.md) | resuming someone else's work | you stop mid-task |
+| [.agent/DECISIONS.md](.agent/DECISIONS.md) | a choice looks arbitrary | you make a non-obvious call |
+| [.agent/DONE.md](.agent/DONE.md) | you need recent history | you complete a task (append only) |
+
+**Before starting:** read `.agent/ACTIVE.md`. If it names work in flight, either continue it
+or say why you are doing something else.
+
+**Before stopping mid-task:** write `.agent/HANDOFF.md` with enough state that a *different*
+tool can resume without re-deriving anything.
+
+### Delegation
+
+Work can be handed to another AI tool by running its CLI. Routing lives in
+[.agent/delegation.yaml](.agent/delegation.yaml); the dispatcher picks the first preferred
+tool that is actually installed.
+
+```bash
+node .agent/delegate.mjs --list                          # what routes exist, what is installed
+node .agent/delegate.mjs explain "how does auth work"    # read-only
+node .agent/delegate.mjs bulk-edit "rename X to Y" --write   # allows unattended edits
+```
+
+`--write` passes the tool's auto-approve flag. Every one of those flags means "edit files
+without asking", so it is opt-in and printed before the run.
+
+{{ delegationTable }}
+
+## Specs
+
+Feature work is spec-driven. Each feature lives in `specs/NNN-slug/`:
+
+```
+specs/001-example/
+├── spec.md      what and why — deliberately no tech stack
+├── plan.md      technical strategy
+└── tasks.md     actionable breakdown
+```
+
+Write `spec.md` before `plan.md`, and `plan.md` before code. For a one-line fix, skip this —
+ceremony on a trivial change is waste.

package/templates/agent-kits/core/files/docs/ARCHITECTURE.md

@@ -0,0 +1,26 @@
+# Architecture
+
+**Style:** {{ architecture }}
+**Stack:** {{ stack }}
+
+<!-- The architecture overlay blueprint appends the canonical layout and its enforcement
+     rules below. Keep this file current — agents read it to decide where code goes. -->
+
+## The rule that matters most
+
+<!-- Filled in by the architecture overlay. If this section is empty, the repo has no
+     enforced boundary and the layout will drift. -->
+
+## Layout
+
+See the folder structure in the repository root.
+
+## Decisions
+
+Architecturally significant decisions are recorded as ADRs in [adr/](adr/).
+
+## Changing the architecture
+
+Changing the style is not a refactor — it is a migration. Write an ADR first, then a spec
+under `specs/`, and expect it to touch every module. If the current style is causing pain,
+record *which* pain in the ADR; "it felt wrong" does not survive review.

package/templates/agent-kits/core/files/docs/adr/0001-record-architecture-decisions.md

@@ -0,0 +1,27 @@
+# 1. Record architecture decisions
+
+**Status:** accepted
+**Date:** {{ today }}
+
+## Context
+
+Architectural decisions get made, then the reasoning evaporates. Six months later someone —
+human or agent — sees an odd-looking choice, assumes it was accidental, and "fixes" it back
+into the problem it was solving.
+
+## Decision
+
+We record architecturally significant decisions as ADRs in `docs/adr/`, using Nygard's format:
+context, decision, consequences. Files are numbered sequentially and never deleted — a
+superseded ADR gets its status changed and a pointer to its replacement.
+
+Write one when a choice is expensive to reverse, constrains future work, or would make a
+reader ask "why is it like this?"
+
+## Consequences
+
+Reviewers get a place to point when a PR contradicts a prior decision. Agents get the
+reasoning instead of re-deriving it, or worse, silently reversing it.
+
+The cost is a short document per significant decision. Skip it for reversible, local choices —
+an ADR for every library bump makes the directory useless.

package/templates/agent-kits/core/files/specs/000-template/plan.md

@@ -0,0 +1,48 @@
+# Plan: <feature name>
+
+**Spec:** [spec.md](spec.md)
+**Created:** {{ today }}
+
+## Approach
+
+How, in a paragraph. Name the shape of the solution before the details.
+
+## Architecture fit
+
+Where this lands in the {{ architecture }} layout, and which boundaries it touches.
+
+- 
+
+## Changes
+
+| Area | Change | Risk |
+|---|---|---|
+|  |  |  |
+
+## Data
+
+Schema changes, migrations, and whether they are backward compatible. A migration that cannot
+be rolled back needs to say so here.
+
+- 
+
+## Alternatives considered
+
+What else was on the table and why it lost. This is the section future readers actually need.
+
+| Option | Why not |
+|---|---|
+|  |  |
+
+## Testing
+
+What proves this works. Name the level — unit, integration, e2e — and what specifically each
+one covers.
+
+- 
+
+## Rollout
+
+Feature flag, migration order, and how to reverse it if it goes wrong.
+
+- 

package/templates/agent-kits/core/files/specs/000-template/spec.md

@@ -0,0 +1,45 @@
+# Spec: <feature name>
+
+**Status:** draft | approved | implemented
+**Owner:**
+**Created:** {{ today }}
+
+<!-- No tech stack in this file. If you find yourself naming a library, it belongs in plan.md. -->
+
+## Problem
+
+What is wrong today, for whom, and what it costs them.
+
+## Goal
+
+What is true after this ships. One paragraph.
+
+## Non-goals
+
+What this deliberately does not do. This section prevents scope creep more reliably than any
+other; be specific.
+
+- 
+
+## User stories
+
+- As a **<role>**, I want **<capability>**, so that **<outcome>**.
+
+## Acceptance criteria
+
+Testable statements. If a criterion cannot fail, it is not a criterion.
+
+- [ ] 
+- [ ] 
+
+## Constraints
+
+Regulatory, performance, compatibility, or deadline constraints that limit the solution space.
+
+- 
+
+## Open questions
+
+Anything unresolved. An agent should stop and ask rather than guess at these.
+
+- 

package/templates/agent-kits/core/files/specs/000-template/tasks.md

@@ -0,0 +1,21 @@
+# Tasks: <feature name>
+
+**Spec:** [spec.md](spec.md) · **Plan:** [plan.md](plan.md)
+
+<!-- Each task should be completable and verifiable on its own. If a task cannot be verified,
+     split it until it can. -->
+
+## Tasks
+
+- [ ] **T1** — <what>
+  - Verify: <command or observable behavior>
+- [ ] **T2** — <what>
+  - Verify: 
+
+## Definition of done
+
+- [ ] All acceptance criteria in `spec.md` pass
+- [ ] `{{ testCommand }}` passes
+- [ ] `{{ lintCommand }}` passes
+- [ ] Non-obvious decisions recorded in `.agent/DECISIONS.md`
+- [ ] `.agent/DONE.md` appended