GoingNinja Overview
GoingNinja is a three-repo starter system for web MVPs with four traits: durable server state, an auth or access boundary, a review boundary before merge, and provider-backed deployment wiring.
It does not assume one tool can plan, build, review, and approve by itself. Its value is the repo contract: file ownership, startup files, branch rules, credential boundaries, and proof steps live in the repo instead of in chat state.
If you are new here, use Ask the wiki in the header.
It explains wiki terms and repo concepts such as GitHub branches, previews, pipelines, Vercel, and launch readiness from the approved GoingNinja sources.
1. Start Here
Read these in order if you are new to the system:
- Before You Start for the minimum accounts, provider access, domains, and token model.
- Planning To Launch for the canonical path from global repos into one launchable product repo.
- Repo Structure for the exact file contract a generated project starts with.
- Tool Roles for builder, reviewer, and merge-owner boundaries.
- Credentials And Resumable Bootstrap for token loading, CLI sessions, and resumable setup.
- Deployment And Access for preview, live, and Cloudflare protection boundaries.
- Branches And Continuity for the local-to-branch-to-preview lifecycle.
- Vendor Sources for which parts come from vendor documentation and which parts are GoingNinja conventions.
- Workflow And Proof for what is already proven at the platform level and what is still pending.
Supporting context:
- Stack And Scope for the default stack and MVP fit.
- Chatbots And CLIs for the difference between discussion surfaces and execution surfaces.
- Lean Implementation for the code-shape rules that keep slices small, auditable, and globally fixable.
- Product Proof for the current Tagnova case that walks the system end to end.
2. What The System Is
The system is split into three repos:
| Repo | Purpose |
|---|---|
goingninja-os |
bootstrap script, starter template, invariants, renderers; GoingNinja OS is the orchestration and skeleton layer, not a device operating system |
goingninja-manual |
explanation, source citations, proof status, audit criteria |
goingninja-project-<slug> |
one generated MVP repo with runtime, state, and deployments |
3. How New Products Start
The normal GoingNinja path is:
- confirm the provider and domain prerequisites
- confirm the product brief
- start the active product repo from
goingninja-os - derive the concrete requirement set
- derive the architecture requirements from that requirement set
- pass the readiness gate
- continue implementation inside that generated project repo
- keep platform-wide rules and bootstrap logic in the global repos
The full planning-to-launch sequence is documented in Planning To Launch.
The important boundary is simple:
goingninja-osandgoingninja-manualdefine the systemgoingninja-project-<slug>is where one concrete product is built
If a pre-platform product already exists, it is an exception case and should be treated as reference only. It is not the main product-genesis model.
4. What It Fits
Good fit:
- authenticated operator consoles
- internal tools with durable server state
- review queues and approval workflows
- gated portals or manual surfaces that should not start from an empty repo
Not a good default fit:
- native mobile apps
- purely static marketing sites
- highly custom frontends with little workflow logic
- products that do not need state, access boundaries, or review-before-merge
See Stack And Scope for the default stack and setup assumptions.
5. What Breaks Without It
| Failure mode | How GoingNinja addresses it |
|---|---|
| state lives in chat instead of files | STATE.json, DELTA.json, and RISKS.json hold machine truth; Markdown files are rendered views |
| one tool builds, reviews, or approves its own work | the builder lane builds; Claude Code and Gemini CLI sit on the review side by contract today and by CI later; the human remains merge owner |
| repo instructions drift across tools | AGENTS.md is the shared contract; CLAUDE.md and GEMINI.md stay thin adapters |
| review is implicit, late, or left to the builder | a pre-merge check on required JSON files and keys runs on every pull_request; rendered Markdown state is maintained by CI on main after merge |
| each new MVP reconstructs auth, CI, state, and provider wiring from scratch | goingninja-os/scripts/bootstrap-project.sh generates the initial file contract, CI workflows, and provider wiring in one resumable run |
6. Where Proof Lives
The authoritative proof surface lives in Workflow And Proof.
The current product-case proof lives in Product Proof.
Today that proof surface shows:
- local deterministic bootstrap is reproducible
- generated repos contain the deterministic file contract
- JSON is machine truth and Markdown is rendered view
- post-merge rendering is encoded into the generated workflow
- open proof items remain explicit instead of being hidden in prose
If you need the provider and token prerequisites before that proof path starts, read Before You Start.
Notes
- Source. Repository family and the generated project contract documented in Repo Structure.