OpenCode MiniAppBuilder — an opencode app-builder template

AppBuilder is a project template for building apps with a small opencode AI engineering squad. It bundles the method, the tooling defaults, the agents, the autonomous build loop, and the repo conventions — so every new project starts from the same proven operating system instead of from zero.

This template is stack-opinionated by default (Expo React Native client + InsForge/Postgres backend) but every role, scope rule, and tool is a placeholder you make your own.

What's inside

• Docs layer — Framework.md (the squad → skills philosophy), AGENTS.md (the project operating manual), V1_TEMPLATE.md (the MVP spec skeleton), VISION.md (forward-looking design/arch), DECISIONS.md (light ADR log).
• opencode config — opencode.json (model, default agent, instructions, skills paths, references, permissions, per-agent models, MCP servers) + .opencode/ (agents, skills, plugins, command).
• Five tooling defaults — graphify (code intelligence), ruflo (vector memory), InsForge (backend MCP), genjutsu (motion/design), best-practice reference repo.
• Autonomous loop — loop.sh (gap-driven: ask → generate → verify → repeat) + .loop/ state.
• Repo conventions — npm workspaces, typecheck/lint/e2e scripts, committed graphify-out/ with a merge driver, CI, .maestro/ + e2e/problem-cases/, data/ single source of truth.

Quick start

Option A — one command (recommended)

./scripts/init.sh MyProject "a user confidently <does the core job>"

This runs find/replace over every {{...}} placeholder, renames V1_TEMPLATE.md → V1_MyProject.md, and inits git.

Option B — manual

1. Copy this repo somewhere new (or gh repo create --template <this-repo>).
2. Find/replace the placeholders listed below across the repo.
3. Rename V1_TEMPLATE.md → V1_<Project>.md.
4. Fill in the MoSCoW table, the Problem Cases, the screens, the NFRs, and the one-sentence decision criterion.
5. git init && git add -A && git commit -m "init".

Placeholders to replace

Search for these tokens across the repo and replace them:

Token	Meaning	Example
{{PROJECT}}	Project name (used in filenames, headings, agent descriptions)	MyApp
{{CORE_JOB}}	The one-sentence core job the V1 app must enable	a user confidently <does the core job>
{{STACK}}	The stack summary line	Expo React Native + InsForge Postgres
{{FROZEN_CONTRACT}}	The interface every backend change must preserve (paths + shapes)	GET /api/items, GET /api/items/:id, ...
{{REJECT_LIST}}	Comma-separated scope-reject list the lead agent blocks on sight	login, push notifications, background tracking
{{PROJECT_DIR}}	Absolute repo path (used in opencode.json permissions + loop.sh)	~/MyApp
{{PACKAGE_ID}}	The app's native package id (Maestro flows)	com.mycompany.myapp

scripts/init.sh replaces {{PROJECT}}, {{CORE_JOB}}, {{REJECT_LIST}}, and {{PACKAGE_ID}} automatically; {{FROZEN_CONTRACT}}, {{STACK}}, and {{PROJECT_DIR}} you fill in by hand (they need real content/paths).

Philosophy (one page)

1. The lead orchestrates, never codes. The lead enforces scope and delegates to specialists. Subagents own their surface and escalate cross-cutting changes to the owner.
2. Frozen invariants are preserved by every change. The contract the client depends on (e.g. {{FROZEN_CONTRACT}}) is inviolable; every backend/design change must keep it.
3. MoSCoW reject-on-sight. The lead rejects anything in the "Won't" rows on sight with a quoted MoSCoW reference. Scope creep is the default failure mode; reject it explicitly.
4. One decision criterion ends every plan. A single sentence from V1_{{PROJECT}}.md decides whether to ship V1 or sharpen the core. End every plan with it.
5. Skills are deep system prompts. Each Ultimate Skill is a SKILL.md that forces the LLM to match a real engineering team's standards instead of falling back on "default AI behavior."
6. Query the graph first. For any code question, query the graphify knowledge graph before grep/glob/Read/Explore. It cuts retrieval tokens and returns instant structured answers.
7. Persist + recall before re-deciding. Store ADRs in ruflo memory; search before re-deciding something already ruled on.

Layout

AppBuilder/
  README.md                # this file
  Framework.md             # the squad → skills philosophy
  AGENTS.md                # the operating manual (5 tooling defaults, roster, layout, scope, run)
  V1_TEMPLATE.md           # the MVP spec skeleton (rename to V1_<Project>.md)
  VISION.md                # forward-looking design/architecture (optional)
  DECISIONS.md             # light ADR log (complements ruflo memory)
  opencode.json            # squad config (model, agents, permissions, MCP)
  package.json             # npm workspaces + scripts
  tsconfig.json
  .gitignore, .gitattributes
  .opencode/
    opencode.json          # plugin registration
    package.json           # @opencode-ai/plugin dep
    agents/                # lead, mobile, design, backend, content, qa
    skills/                # Ultimate Skills + graphify + genjutsu
    plugins/graphify.js    # tool.execute.before hook (query-first)
    command/               # slash-command slot
  loop.sh                  # autonomous gap-driven build loop
  .loop/                   # loop state (gaps.json, logs, answers)
  scripts/init.sh          # one-command scaffolder
  .github/workflows/ci.yml # typecheck + build per workspace
  app/                     # client workspace (Expo React Native by default)
  backend/                 # backend workspace (InsForge by default)
  data/                    # single source of truth for content/templates
  e2e/problem-cases/       # Cypress specs for the Problem Cases
  .maestro/                # Maestro RN e2e flows
  graphify-out/            # knowledge graph (committed; merge-driver)

Credits

Thank you!

Github Repos:

https://github.com/ruvnet/ruflo.git

https://github.com/AThevon/genjutsu.git

https://github.com/shanraisshan/claude-code-best-practice.git

https://github.com/InsForge/InsForge.git

https://github.com/Graphify-Labs/graphify.git

License

Yours. This is a template — use it however you want.