opencode-autopilot

🚀🤖 Autonomy-first (web-oriented) OpenCode starter for real autonomy — with MCP-first tooling, quality gates, and a pragmatic validation flow 🔒🧪

If you’ve ever tried agentic coding and ended up with:

• “DONE ✅” without running anything,
• random refactors you never asked for,
• UI regressions that only show up after deploy,
• or token-burning context dumps…

This repo is the missing scaffolding: a clean set of rules + memory + validation gates so OpenCode behaves like a solid teammate from day one.

---

Safety note (honest, not scary) 🔐

This template is designed to be as safe as reasonably possible while keeping the agent highly autonomous — in a setup where OpenCode runs directly on your host (no container/VM sandbox by default).

What that means in practice:

• ✅ You get tight workflow boundaries (rules + MCP-first policy + token budgets + validation gates).
• ✅ You reduce the chance of accidental “big mistakes” (by forcing real validation and avoiding huge data pulls).
• ✅ You can keep secrets out of the repo (via env-based config).

But also:

• ⚠️ OpenCode can still run with powerful capabilities. With broad permissions, mistakes can be destructive.
• ⚠️ There is always a small residual risk (tool quirks, edge cases, unexpected prompts, human error).
• ✅ The goal here is pragmatic safety (reduce risk a lot) while keeping the workflow fast and autonomous — not “perfect isolation”.

If you want near-zero blast radius: run in a container/VM. If you want maximum speed on your main machine: this repo helps you do it responsibly.

---

What you get ✨

Autonomy that stays honest

• ✅ TODO-driven loop: pick a task → implement → validate → retry → escalate when blocked
• 🧪 Quality gates: no “looks good” DONE — the agent must prove it works
• 🧰 MCP-first tool policy: filesystem / browser / DB / docker / API client before random bash/web hacks
• ✂️ Token-budget rules: DB + API context stays small and relevant

Web-first (web-oriented) defaults, still adaptable

Default assumptions (easy to swap):

• 🌐 UI exists and can be validated in a real browser
• 🗄️ DB is MariaDB/MySQL
• 🐳 Services may run in Docker
• 🔌 API smoke tests can be run via an HTTP client (Postmancer)

Non-web project? Different stack? Still usable — you’ll just adapt the MCP config + QUALITY gates.

---

Why MCP-first? 🧠🧰

MCP servers give the agent purpose-built tools with clearer boundaries than “do everything with bash”:

• filesystem MCP: safer, scoped file access (no wandering outside your project)
• chrome-devtools MCP: validates UI behavior where it actually matters (real browser, real console)
• mysql/mariadb MCP: schema-first + targeted reads (no table dumps)
• docker MCP: inspect logs/status/exec without ad-hoc scripts
• postmancer: quick, repeatable API smoke checks without reinventing curl flows

Net effect: fewer hallucinated validations, fewer accidental dumps, more reliable “DONE”.

---

Lara : OK, je te refais la section Project layout en incluant tes dossiers 01_generated, agent, command, memory, plugin, rules, skills, tools, et je marque clairement quand c’est optionnel / souvent vide avec un petit commentaire utile. 👌

Project layout 🧭

.
├─ AGENTS.md                          # agent behavior + language & tone policy (source of truth)
├─ TODO.md                            # task list (can be in any language)
└─ .opencode/
   ├─ 01_generated/                   # optional generated artifacts (templates, exports, snapshots) — safe to delete/rebuild
   │                                   (often empty; useful for reproducible outputs without polluting the repo)
   ├─ agent/                          # optional agent profiles / modes / persona presets
   │                                   (often empty; useful when you want multiple agent behaviors per repo)
   ├─ command/                        # optional command presets / shortcuts / repeatable workflows
   │                                   (often empty; useful to standardize common actions like "run checks" / "smoke test")
   ├─ memory/                         # project memory the agent should rely on (keep updated)
   │  ├─ STATE.md                     # project context: stack, ports, constraints, URLs
   │  ├─ DISCOVERY.md                 # entrypoints + useful pointers (where to start, key modules)
   │  ├─ QUALITY.md                   # validation commands + gates (incl. UI gate / Chrome MCP)
   │  └─ CHANGELOG_DEV.md             # optional structured dev notes (often empty)
   ├─ plugin/                         # optional custom extensions / integrations for your workflow
   │                                   (often empty; keep only if you maintain a plugin layer)
   ├─ rules/                          # hard rules the agent must follow (behavioral guardrails)
   │  ├─ 00-core.md                   # tool policy, conventions, defaults
   │  ├─ 10-safety-guard.md           # safety rails (no secrets, no destructive ops, etc.)
   │  ├─ 20-git-guard.md              # git policy (often “no git unless asked”)
   │  └─ ...                          # add more rules as your playbook grows
   ├─ skills/                         # optional playbooks for repeatable tasks (debugging, refactors, migrations)
   │                                   (often empty; useful when you want consistent “how to” procedures)
   └─ tools/                          # optional tool wrappers / helpers / small scripts used by the agent
                                       (often empty; useful if you standardize local tooling without bloating the main repo)

---

UI validation via Chrome DevTools MCP (required by design) 🌐🧪

This template expects UI-impacting changes to be validated using Chrome DevTools MCP — not just API calls. That’s how you avoid false “DONE” on:

• routing/hydration issues
• auth flows
• layout regressions
• error rendering
• “works in API but breaks in UI”

Install & docs:

• https://github.com/ChromeDevTools/chrome-devtools-mcp

If your project has no UI, replace the UI gate in .opencode/memory/QUALITY.md with an equivalent (CLI integration tests, snapshots, etc.).

---

Quickstart (5–10 minutes) ⚡

1. Copy this starter into your project:

   • .opencode/
   • AGENTS.md
   • TODO.md

2. Configure MCP servers (paths/ports/hosts):

   • filesystem MCP root → your project directory
   • DB MCP → your DB (MariaDB/MySQL by default)
   • Docker MCP → your Docker daemon (if using containers)
   • Chrome DevTools MCP → installed + able to connect to Chrome
   • Postmancer → optional, but great for API smoke tests

3. Update memory:

   • .opencode/memory/STATE.md → architecture, ports, URLs, constraints or keep it "as-is".
   • .opencode/memory/QUALITY.md → real lint/test/build commands + UI flows or keep it "as-is".

4. Write a good TODO and run OpenCode.

---

MCP config: what to change for your project 🔧

This repo ships with a “known good” MCP toolbox. You’ll typically adapt:

1) filesystem MCP

• Change the root path to your project directory
• Keep it scoped to avoid accidental reads/writes outside the repo

2) DB MCP (MariaDB/MySQL by default)

• Update host/port/user/db name for your environment
• Prefer env vars (e.g. {env:OPENCODE_DB_PASS}) instead of hardcoding secrets

If you’re not on MariaDB/MySQL:

• Postgres → swap the MySQL MCP server for a Postgres MCP server
• SQLite → use a SQLite MCP server (or keep DB ops minimal)
• No DB → disable DB MCP and remove DB gates from QUALITY

3) chrome-devtools MCP

• Ensure Chrome is installed and reachable by the MCP server
• Keep this enabled if your changes can affect UI behavior

4) docker MCP (optional)

• Enable if your services run in containers (status/logs/exec)
• Disable if you don’t use Docker (and remove Docker references in QUALITY)

5) postmancer (optional)

• Useful for repeatable API smoke tests (especially when UI is not the best probe)

---

Writing “agent-proof” TODOs ✅

A TODO should be executable without guesswork.

A good TODO contains:

• expected behavior (observable)
• scope (files/areas)
• exact validation commands
• UI flow to validate (if UI impact)
• “DONE WHEN” criteria

Example:

- [ ] T42: Fix redirect after token refresh
  Expected: after refresh, user stays on original route
  Scope: frontend auth composable + backend refresh endpoint
  Validate:
    - npm run lint
    - npm test
    - npm run build
    - UI: open /account, refresh page, verify still on /account (Chrome MCP)
  DONE WHEN: all validations PASS and no console errors

---

MCP-first tool policy (high level) 🧰

• filesystem MCP: default for file ops
• chrome-devtools MCP: default for UI checks + console
• DB MCP: schema-first + small samples (LIMIT 4), never dump tables
• postmancer: default for API smoke tests
• docker MCP: default for status/logs/exec
• webfetch/websearch: external docs only (not for testing your app)

---

Token budget rules (DB/API) ✂️

• Never dump tables or giant JSON blobs.

• Prefer schema introspection first (tables, columns, constraints).

• For data shape, sample 3–4 rows max (LIMIT 4).

• For big API responses, keep only:

  • first ~450 chars or
  • first 3 objects whichever best represents structure.

---

Language policy 🌍

• All files (code, comments, docs) are written in English.
• User interaction (chat) follows the user’s language.
• TODO.md can be written in any language.

---

Recommended operating discipline 🧠

• Review diffs. Commit early. Commit often.
• Keep backups/snapshots.
• Start restrictive on permissions, loosen gradually.
• Don’t store secrets in the repo.

---

License

MIT