@glrs-dev/harness-plugin-opencode 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Austin Hess
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,353 @@
+# @glrs-dev/harness-plugin-opencode
+
+Opinionated agent harness for [OpenCode](https://opencode.ai). Agents, tools, slash commands, and an unattended pilot mode — one package.
+
+## Quick start
+
+### CLI (recommended)
+
+```bash
+bun add -g @glrs-dev/harness-plugin-opencode
+glrs-oc install-plugin
+opencode
+```
+
+Gives you the full CLI (`glrs-oc`) plus all [plugin features](#what-the-plugin-provides) inside OpenCode.
+
+### Plugin only
+
+```bash
+bunx @glrs-dev/harness-plugin-opencode install
+opencode
+```
+
+No global install. All [plugin features](#what-the-plugin-provides) load automatically. You won't have the `glrs-oc` CLI, but pilot commands will offer to install the plugin if you add the CLI later.
+
+### Verifying the published tarball
+
+This package publishes with [npm provenance](https://docs.npmjs.com/generating-provenance-statements) via GitHub Actions OIDC. After installing, verify the provenance chain:
+
+```bash
+npm audit signatures
+```
+
+This confirms the tarball on npm was built from this repo's `release.yml` workflow on the canonical main branch — a malicious publish with a stolen npm token would fail this check.
+
+## The Glorious workflow
+
+### Interactive (plugin)
+
+Open OpenCode in any repo. The `prime` agent handles everything end-to-end.
+
+**Start a task from a ticket:**
+```
+/fresh ENG-1234
+```
+Wipes the worktree, creates a branch from the ticket ref, and begins the five-phase workflow: understand → plan → execute → verify → handoff.
+
+**Start a task from a description:**
+```
+/fresh add rate limiting to the upload endpoint
+```
+
+**Go hands-off after the plan looks good:**
+```
+/autopilot ENG-1234
+```
+Runs the full workflow unattended. Stops when all acceptance criteria are checked off. You review, then `/ship`.
+
+**Ship when done:**
+```
+/ship ~/.glorious/opencode/repo/plans/feat-rate-limit.md
+```
+Squashes commits, pushes, opens a PR with the plan as the body.
+
+**Review a PR:**
+```
+/review 87
+```
+Read-only adversarial review. Fetches the diff, runs typecheck/lint, delegates to `@qa-reviewer`, outputs a structured verdict.
+
+**Deep codebase research:**
+```
+/research how does authentication work in this codebase?
+```
+Spawns parallel subagents, synthesizes findings with exact file:line references.
+
+### Unattended (pilot CLI)
+
+For larger work that decomposes into a multi-task DAG. Each task runs in an isolated git worktree with its own verify commands.
+
+```bash
+# Plan interactively — spawns OpenCode TUI with the pilot-planner agent
+glrs-oc pilot plan "Refactor the billing module into separate services"
+
+# Validate the plan (schema, DAG, glob conflicts)
+glrs-oc pilot validate
+
+# Execute — fully unattended, isolated worktrees, topological order
+glrs-oc pilot build
+
+# Check progress
+glrs-oc pilot status
+```
+
+See [Pilot mode](#pilot-mode) for the full command reference.
+
+---
+
+## What the plugin provides
+
+14 agents, 7 slash commands, 5 tools, 5 MCPs, 5 skill bundles, 4 sub-plugins. Details below.
+
+### Agents
+
+| Agent | Tier | Role |
+|-------|------|------|
+| `prime` | deep | Five-phase end-to-end workflow (default agent) |
+| `plan` | deep | Interactive planner with gap analysis and adversarial review |
+| `build` | mid | Plan executor |
+| `qa-reviewer` | mid | Fast adversarial code review |
+| `qa-thorough` | deep | Full-suite adversarial review |
+| `plan-reviewer` | deep | Adversarial plan review |
+| `gap-analyzer` | deep | Identifies gaps in plans |
+| `architecture-advisor` | deep | Architecture guidance |
+| `code-searcher` | fast | Codebase search specialist |
+| `docs-maintainer` | mid | Documentation updates |
+| `lib-reader` | mid | Library/dependency reader |
+| `agents-md-writer` | mid | AGENTS.md generation |
+| `pilot-builder` | mid | Unattended task executor (pilot subsystem) |
+| `pilot-planner` | deep | Decomposes work into pilot.yaml DAGs |
+
+Tiers: **deep** = opus-class, **mid** = sonnet-class, **fast** = haiku-class. Override with [`harness.models`](#model-overrides).
+
+### Slash commands
+
+| Command | What it does |
+|---------|-------------|
+| `/fresh <ref>` | Wipe worktree, branch from ticket or description, start PRIME |
+| `/autopilot <ref>` | Hands-off PRIME run; stops when acceptance criteria pass |
+| `/ship <plan>` | Squash, push, open PR |
+| `/review <target>` | Read-only adversarial review (PR#, SHA, branch, or file) |
+| `/research <topic>` | Parallel codebase exploration with file:line citations |
+| `/init-deep` | Generate hierarchical AGENTS.md files |
+| `/costs` | Show running LLM spend totals |
+
+### Tools
+
+`ast_grep` · `tsc_check` · `eslint_check` · `todo_scan` · `comment_check`
+
+### MCP servers
+
+| Server | Status | Backend |
+|--------|--------|---------|
+| `serena` | enabled | AST code intelligence via `uvx` |
+| `memory` | enabled | Per-repo JSON memory |
+| `git` | enabled | Structured blame/log via `uvx` |
+| `playwright` | disabled | Browser automation — enable in opencode.json |
+| `linear` | disabled | Linear issue tracker — enable in opencode.json |
+
+### Sub-plugins
+
+- **autopilot** — idle-nudge loop driver (only activates via `/autopilot`)
+- **notify** — OS notifications when the agent asks a question
+- **cost-tracker** — LLM spend by provider/model at `~/.glorious/opencode/costs.json`
+- **pilot-plugin** — runtime invariant enforcement for pilot agents
+
+### Skills
+
+`review-plan` · `web-design-guidelines` · `vercel-react-best-practices` · `vercel-composition-patterns` · `pilot-planning`
+
+---
+
+## Pilot mode
+
+Runs a `pilot.yaml` task DAG fully unattended. Tasks have dependencies, touch-globs (file ownership), and verify commands. The worker executes them in topological order, each in an isolated git worktree.
+
+**Prerequisites:** `git` >= 2.5, `opencode` on PATH. Plugin must be installed (auto-prompted if missing).
+
+### Commands
+
+| Command | Description |
+|---------|-------------|
+| `glrs-oc pilot plan [input]` | Spawn OpenCode TUI with `pilot-planner`. Input: Linear ID, GitHub URL, or text. |
+| `glrs-oc pilot validate [path]` | Schema + DAG + glob validation. Defaults to newest plan. |
+| `glrs-oc pilot build` | Execute the plan. `--plan <path>`, `--dry-run`, `--filter <id>`. |
+| `glrs-oc pilot status` | Task statuses for the current run. `--run <id>`, `--json`. |
+| `glrs-oc pilot resume` | Continue a partial run. Skips succeeded tasks. |
+| `glrs-oc pilot retry <task>` | Reset one task to pending. `--run-now` to re-execute immediately. |
+| `glrs-oc pilot logs <task>` | Events and verify output for a task. |
+| `glrs-oc pilot worktrees list\|prune` | Manage pilot's git worktrees. |
+| `glrs-oc pilot cost` | Per-task and total LLM cost. `--json`. |
+| `glrs-oc pilot plan-dir` | Print the plans directory path. |
+
+### State storage
+
+```
+~/.glorious/opencode/<repo>/pilot/
+  plans/                  # YAML plans
+  runs/<runId>/
+    state.db              # SQLite (runs, tasks, events)
+    workers/00.jsonl      # structured logs
+  worktrees/<runId>/00/   # isolated git worktree
+```
+
+Repo identity derived from `git rev-parse --git-common-dir` — worktrees of the same repo share state. Override with `$GLORIOUS_PILOT_DIR`.
+
+> **v0.1:** single worker only. `--workers >1` clamps to 1. Parallel scheduling deferred to v0.3+.
+
+---
+
+## Configuration
+
+### Model overrides
+
+Override all agents in a tier, or target specific agents, via `harness.models` in `opencode.json`:
+
+```json
+{
+  "harness": {
+    "models": {
+      "deep": ["bedrock/claude-opus-4"],
+      "mid": ["bedrock/claude-sonnet-4"],
+      "fast": ["bedrock/claude-haiku-4"],
+      "prime": ["my-custom-model"]
+    }
+  }
+}
+```
+
+**Precedence:** per-agent `harness.models.X` > tier `harness.models.deep` > plugin default. Direct `agent.<name>.model` in opencode.json wins over all.
+
+### Agent/command/MCP overrides
+
+Your opencode.json values win. Example:
+
+```json
+{
+  "agent": {
+    "prime": { "model": "anthropic/claude-sonnet-4-6" }
+  }
+}
+```
+
+### Enabling optional MCPs
+
+```json
+{
+  "mcp": {
+    "playwright": { "enabled": true },
+    "linear": { "enabled": true }
+  }
+}
+```
+
+---
+
+## CLI reference
+
+| Command | Description |
+|---------|-------------|
+| `glrs-oc install-plugin [--pin] [--dry-run]` | Register plugin in opencode.json |
+| `glrs-oc uninstall [--dry-run]` | Remove plugin from opencode.json |
+| `glrs-oc doctor` | Check installation health |
+| `glrs-oc pilot <verb>` | [Pilot mode](#pilot-mode) |
+| `glrs-oc plan-dir` | Print repo-shared plan directory |
+| `glrs-oc plan-check <path>` | Validate legacy markdown plan files |
+
+`install` is an alias for `install-plugin`.
+
+---
+
+## Maintenance
+
+**Update:**
+```bash
+bun update -g @glrs-dev/harness-plugin-opencode
+```
+
+**Pin version:** `glrs-oc install-plugin --pin`
+
+**Rollback:** `npm deprecate @glrs-dev/harness-plugin-opencode@<broken> "<reason>"` — then ship a patch.
+
+**Uninstall:**
+```bash
+glrs-oc uninstall                           # remove from opencode.json
+bun remove -g @glrs-dev/harness-plugin-opencode    # remove CLI
+```
+
+## Prerequisites
+
+- [OpenCode](https://opencode.ai)
+- `bun`
+- `uvx` for serena + git MCPs (`brew install uv`)
+- `node`/`npx` for memory MCP
+- `git` >= 2.5 for pilot worktrees
+
+## Security & threat boundaries
+
+Report vulnerabilities privately per [`SECURITY.md`](./SECURITY.md) — do NOT open a public issue. Expected response: acknowledge within 72h, fix-or-disclose decision within 30 days.
+
+### What this plugin can do on your machine
+
+This is a plugin with broad local-machine access. Install it deliberately:
+
+- **Reads and writes files** under your home directory (`~/.config/opencode/opencode.json`, `~/.cache/harness-opencode/*`, `~/.config/harness-opencode/install-id`, `~/.glorious/opencode/<repo>/pilot/*`).
+- **Runs local subprocesses** during normal operation: `git`, `gh`, `npm`/`bun`, `ast-grep`, `tsc`, `opencode`, and project-specific verify commands from any `pilot.yaml` you author.
+- **Makes outbound HTTPS calls** (all opt-out-able):
+  - `registry.npmjs.org` — daily version check. Opt out: `HARNESS_OPENCODE_UPDATE_CHECK=0`.
+  - `catwalk.charm.land` — model catalog during interactive install only. Response is schema-validated before it reaches your `opencode.json`.
+  - `us.aptabase.com` — anonymous telemetry. Opt out: `HARNESS_OPENCODE_TELEMETRY=0`, `DO_NOT_TRACK=1`, or `CI=true`.
+- **Configures MCP servers** in your OpenCode config that, on first use, download third-party code via `uvx` (Serena, `mcp-server-git`) or `npx` (`@playwright/mcp`, `@modelcontextprotocol/server-memory`). These MCPs run in their own subprocesses. Review them before enabling ones that ship disabled by default (`playwright`, `linear`).
+
+### What is NOT a sandbox
+
+The agent-bash **deny-list** in `src/agents/index.ts` (`rm -rf /*`, `chmod *`, `sudo *`, force-push variants, etc.) is a safety rail for common mistakes, not a sandbox. An agent can still:
+
+- Read any file the user can read (including `~/.ssh/id_*`, `~/.aws/credentials`, etc.).
+- Pipe arbitrary code to a shell (e.g., `curl <url> | sh`).
+- Modify shell startup files (`.zshrc`, `.bashrc`) or your PATH.
+- Run `npx <malicious-package>` and similar network-fetched executables.
+
+If a prompt (your own, or an injected one from a web page, issue comment, or MCP response) tells the agent to do something malicious, the deny-list will not block many of the paths. Treat the agent like a junior dev with unrestricted shell access — be careful what you paste into the prompt, and do not run this plugin on machines with credentials you cannot afford to rotate.
+
+A future release may sandbox the bash surface (filesystem allow-list, egress filter). Until then, the boundary is documented, not enforced.
+
+### What this plugin does NOT do
+
+- It does NOT ship any postinstall scripts. `bun add @glrs-dev/harness-plugin-opencode` mutates only `node_modules/`. All filesystem changes to your config happen in the explicit `glrs-oc install` / `bunx @glrs-dev/harness-plugin-opencode install` step.
+- It does NOT write to `~/.config/opencode/agents/`, `~/.config/opencode/commands/`, `~/.config/opencode/skills/`, or `~/.config/opencode/tools/`. Agents, commands, and skills live in `node_modules` (read-only by design). The only config write is `~/.config/opencode/opencode.json` during `install`.
+- It does NOT exfiltrate code, prompts, file paths, error messages, usernames, project names, or git remotes via telemetry. See the allow-list in `src/telemetry.ts`.
+
+## Privacy & Telemetry
+
+**Update check.** Daily version check against `registry.npmjs.org`. Opt out: `HARNESS_OPENCODE_UPDATE_CHECK=0`.
+
+**Catwalk model catalog.** During interactive `install` only, fetches the provider list from `catwalk.charm.land/v2/providers`. The response is schema-validated (see `src/cli/catwalk.ts`) before any value reaches your `opencode.json`. If validation fails, the installer falls back to built-in presets.
+
+**Telemetry.** `@glrs-dev/harness-plugin-opencode` collects anonymous usage data via [Aptabase](https://aptabase.com) to help improve reliability. The data is opt-out, contains no personal information, and has no stable user identifier — Aptabase tracks anonymous sessions only.
+
+**What gets sent:** package version, OS, Node version, which tools were invoked (hashline, serena, memory, custom tools), tool durations, file extensions of edited files (e.g. `.ts`), edit success/failure outcomes, and hashline mismatch rates.
+
+**What never gets sent:** file paths, file contents, code, prompts, model outputs, error messages, project names, git remotes, usernames, or anything that could identify a user or codebase.
+
+To disable, set any of these in your shell:
+
+```bash
+export HARNESS_OPENCODE_TELEMETRY=0
+export DO_NOT_TRACK=1                   # standard cross-tool opt-out
+```
+
+Telemetry is also automatically disabled when `CI=true`.
+
+## Migrating from clone+symlink install
+
+See [docs/migration-from-clone-install.md](docs/migration-from-clone-install.md).
+
+## Contributing
+
+Read [`AGENTS.md`](./AGENTS.md) and [`CONTRIBUTING.md`](./CONTRIBUTING.md). All user-visible PRs need a changeset (`bunx changeset`).
+
+## License
+
+MIT

package/SECURITY.md

@@ -0,0 +1,89 @@
+# Security Policy
+
+Thank you for helping keep `@glrs-dev/harness-plugin-opencode` and the people who use it safe. This document describes how to report a vulnerability, what versions we fix, and what is in scope.
+
+## Supported versions
+
+We publish fixes for the **latest minor** during the 0.x cadence. Older minors do not receive backports.
+
+| Version | Supported |
+| ------- | --------- |
+| 0.x (latest minor) | ✅ |
+| 0.x (older minors) | ❌ |
+
+Once 1.0 ships, this table will track supported major lines instead.
+
+## Reporting a vulnerability
+
+**Please do not open a public GitHub issue for security bugs.**
+
+Use one of these private channels:
+
+1. **Preferred — GitHub private vulnerability reporting:** go to the [Security tab](https://github.com/iceglober/glrs/security/advisories/new) and open a new advisory. This gives us a private thread with tracking, severity fields, and a path to issue a CVE if applicable.
+2. **Fallback — email:** `austin@glorious.dev`. Use PGP if you have a key; otherwise plain email is fine. Include the word `SECURITY` in the subject.
+
+Please include:
+
+- A description of the issue and why it matters (threat, impact).
+- Steps to reproduce, ideally a minimal repro or a failing test.
+- Affected version(s). Check with `npm view @glrs-dev/harness-plugin-opencode version` if unsure.
+- Your disclosure timeline preference, if you have one.
+
+## Our response SLA
+
+These are honest numbers for a small maintainer footprint. We will keep them:
+
+- **Acknowledge your report:** within **72 hours**.
+- **Triage (confirmed / not a vuln / needs more info):** within **7 days**.
+- **Fix-or-disclose decision + timeline:** within **30 days** of acknowledgement.
+
+If a vulnerability is confirmed and fixed, we will publish a GitHub security advisory and an `npm deprecate` notice for affected versions.
+
+## Scope
+
+**In scope:**
+
+- The published npm tarball (`@glrs-dev/harness-plugin-opencode`).
+- CLI subcommands (`glrs-oc`, `harness-opencode`): `install`, `uninstall`, `doctor`, `plan-dir`, `plan-check`, `pilot`.
+- Plugin hooks registered via the OpenCode plugin API (`config`, `tool.execute.before/after`, `session.idle`, etc.).
+- The MCP config writer (`src/cli/install.ts`, `src/mcp/index.ts`) and the `opencode.json` merge logic (`src/cli/merge-config.ts`).
+- Outbound network calls the plugin makes on its own:
+  - `https://registry.npmjs.org/` — daily update check (opt-out: `HARNESS_OPENCODE_UPDATE_CHECK=0`).
+  - `https://catwalk.charm.land/` — model catalog fetch during interactive install.
+  - `https://us.aptabase.com/` — anonymous telemetry (opt-out: `HARNESS_OPENCODE_TELEMETRY=0`, `DO_NOT_TRACK=1`, or `CI=true`).
+
+**Out of scope (will not be treated as vulnerabilities in this package):**
+
+- User-authored `pilot.yaml` files: the pilot verify-runner executes user-supplied shell commands by design. Malicious `pilot.yaml` contents are the user's responsibility to review.
+- **Third-party MCP upstreams** the plugin configures (Serena, mcp-server-git, `@playwright/mcp`, `@modelcontextprotocol/server-memory`, Linear MCP): these run in the user's MCP shell and are outside this package's boundary. Report issues to their respective maintainers.
+- **Agent bash permission patterns** (`CORE_DESTRUCTIVE_BASH_DENIES` in `src/agents/index.ts`): the deny-list is a safety rail for common mistakes, not a sandbox. An agent (or prompt injection that reaches one) can exfiltrate files, call network endpoints, or mutate the shell via constructs the deny-list does not match (shell expansion, piping to curl, etc.). This is a documented property of the threat model; see `docs/THREAT_MODEL.md` (when published) or the README's Threat boundaries section.
+- Decisions made by the underlying LLM. If a model follows a malicious instruction, that's a model/prompt issue, not a plugin issue. Defense-in-depth against prompt injection is welcome via the private reporting channel but will typically be triaged as a feature request.
+- Vulnerabilities in Node.js, Bun, npm, git, `uvx`, `npx`, or other tools the plugin invokes via `execFile`/subprocess. Report to their maintainers; we will update our pinned/required versions if a fix affects us.
+
+## Safe harbor
+
+We will not pursue legal action against security researchers who:
+
+- Make a good-faith effort to avoid privacy violations, data destruction, and service interruption.
+- Report through the private channels above and give us reasonable time to fix before disclosing publicly.
+- Do not exploit the issue beyond what's necessary to demonstrate it.
+- Do not access, modify, or exfiltrate data that is not clearly theirs.
+
+If you are unsure whether your planned research falls within this safe harbor, ask first at the private channels above.
+
+## Coordinated disclosure & credit
+
+Unless you opt out, we will credit you by name (or chosen handle) in:
+
+- The GitHub security advisory for the fix.
+- The `CHANGELOG.md` entry.
+
+## Out-of-tree security concerns
+
+Use GitHub issues (public) for:
+
+- Hardening suggestions that are not actively exploitable.
+- Documentation improvements to this policy.
+- Questions about supported platforms / configurations.
+
+Use private reporting for anything that has impact before a patch is published.

package/dist/agents/prompts/agents-md-writer.md

@@ -0,0 +1,89 @@
+---
+name: agents-md-writer
+description: Generates a single per-directory AGENTS.md file scoped to the directory provided. Invoked in parallel from the /init-deep command.
+mode: subagent
+model: anthropic/claude-sonnet-4-6
+temperature: 0.2
+---
+
+You generate ONE per-directory `AGENTS.md` file scoped to the directory provided in your prompt.
+
+If you need to clarify scope with the PRIME mid-task (rare), use the `question` tool — never free-text chat.
+
+# Hard rules
+
+- You write ONLY to `<directory>/AGENTS.md` exactly. Nothing else, under any circumstance.
+- If the target `<directory>/AGENTS.md` already exists, use **Edit**. If it does NOT exist, use **Write**. NEVER Write over an existing file — manual authoring must be preserved.
+- Never repeat content from the root `AGENTS.md`. Child files are for directory-specific deviations and details.
+- 30-80 lines max. If you need more, your scope is too broad — ask the PRIME to split.
+- Telegraphic style. No generic boilerplate. No "this directory contains TypeScript code" — that's not useful.
+- If after exploring you can't articulate anything directory-specific worth documenting, write nothing and report back "no scoped context worth documenting in <directory>."
+
+# Workflow
+
+## 1. Read root AGENTS.md
+
+Note conventions already established globally. You will explicitly NOT repeat them.
+
+## 2. Inspect the directory — Serena FIRST
+
+Start with Serena. These calls are cheap and precise; do them before anything else:
+
+1. `serena_get_symbols_overview({relative_path: "<directory>"})` — get the symbol inventory (classes, functions, types, exported constants). This tells you what the directory actually exposes.
+2. For the top 3-5 symbols by apparent importance (index/default export, named exports with wide reference footprint): `serena_find_referencing_symbols({name_path: "<sym>", relative_path: "<file>"})` to see who else in the repo uses this directory. That's the "role in the larger codebase" answer.
+3. `serena_find_symbol({name_path: "<key-pattern>", relative_path: "<directory>", include_body: true})` for the 1-2 load-bearing exports to capture their actual signature in the AGENTS.md if that's useful.
+
+Only after Serena supplement with `read`/`grep`/`glob`/`ast_grep` for:
+- Configs (tsconfig, eslintrc, package.json, vitest.config)
+- READMEs + existing docs
+- Non-TS files (shell scripts, SQL, YAML)
+- Textual patterns that don't map to symbols (TODO annotations, URL strings, comment conventions)
+
+Use `git log -5 --oneline <directory>` for a feel of recent activity.
+
+If you catch yourself reaching for `grep "^export"` to count exports, STOP — Serena's `get_symbols_overview` already gave you that.
+
+Look for:
+- Naming conventions specific to this directory (that aren't root-level)
+- Patterns here that differ from the rest of the repo
+- Dependencies or imports unique to this area
+- Tests or fixtures that anchor behavior
+- Any local README.md, CHANGELOG, or doc file worth referencing
+
+## 3. Write `<directory>/AGENTS.md`
+
+Structure:
+
+```markdown
+# <Directory name>
+
+## Purpose
+<One paragraph: what lives here; what it does; what it doesn't do. Deviations from root expectations only.>
+
+## Conventions specific to this directory
+- <Bullet: convention NOT stated in root AGENTS.md>
+- <Bullet: another>
+(Skip this section if you have nothing directory-specific.)
+
+## Key files
+- `<file>` — <one-line description of its role in THIS directory>
+- `<file>` — <description>
+(List 3-8 load-bearing files. Not every file.)
+
+## Adjacent context
+- For <related concern>, see `<other-directory>/AGENTS.md`
+- For <other concern>, see `<doc-path>`
+(Skip if no obvious adjacencies.)
+```
+
+## 4. Self-validate
+
+Before declaring done:
+- Line count 30-80? If >80, trim; if <15, you're probably padding.
+- Any bullet duplicated from root AGENTS.md? Remove it.
+- Any bullet that would apply to ANY TypeScript project? Remove it.
+- Every claim verifiable by reading a file in this directory? If not, remove or cite the file.
+
+Report back:
+- `<directory>/AGENTS.md` (created | updated, N lines)
+- One-line description of what made this directory worth documenting.

package/dist/agents/prompts/architecture-advisor.md

@@ -0,0 +1,46 @@
+---
+name: architecture-advisor
+description: Read-only senior consultant for high-stakes decisions, repeated failures, and architectural questions. Slow and expensive — use sparingly.
+mode: subagent
+model: anthropic/claude-opus-4-7
+temperature: 0.2
+---
+
+You are the Architecture Advisor. Produce written analysis. If you need to ask the PRIME/user a clarifying question before committing to a recommendation, use the `question` tool — never free-text chat.
+
+You are consulted only when:
+- A decision has significant downstream cost (architecture, schema, public API)
+- The build agent has failed at the same task twice
+- A security or data-handling question needs a second opinion
+- A pattern in the codebase is unfamiliar and the planner needs guidance
+
+You do not write code. You do not delegate. You produce written analysis.
+
+Output format:
+
+```
+## Question
+
+<Restate the question in your own words.>
+
+## Analysis
+
+<2–4 paragraphs. Tradeoffs, constraints, what's at stake.>
+
+## Recommendation
+
+<One paragraph. Specific. Not "it depends." Take a position.>
+
+## Rationale
+
+<Why this recommendation over the alternatives.>
+
+## What would change my mind
+
+<List the specific facts that, if true, would flip the recommendation.>
+```
+
+Rules:
+- Be direct. The PRIME needs a decision, not a survey.
+- Always include "What would change my mind." If you can't think of anything, your recommendation is too weak.
+- Read enough code to ground your analysis. Don't speculate from naming alone.