Repo Structure

When goingninja-os/scripts/bootstrap-project.sh runs, it creates a goingninja-project-<slug> repo with the contract below.

This generated repo is the intended active baseline for a new product. The platform repos define the contract first, and the concrete product work continues from this generated starting point.

1. Generated Project Skeleton

The generated project starts with this minimum structure:

goingninja-project-<slug>/
├── README.md
├── PRODUCT_BRIEF.json
├── PRODUCT_BRIEF.md              # rendered once by bootstrap, then maintained by CI on `main`
├── REQUIREMENTS.json
├── REQUIREMENTS.md               # rendered once by bootstrap, then maintained by CI on `main`
├── ARCHITECTURE_REQUIREMENTS.json
├── ARCHITECTURE_REQUIREMENTS.md   # rendered once by bootstrap, then maintained by CI on `main`
├── READINESS_GATE.json
├── READINESS_GATE.md             # rendered once by bootstrap, then maintained by CI on `main`
├── AUDIT_STATE.json
├── AUDIT_STATE.md                # rendered once by bootstrap, then maintained by CI on `main`
├── AGENTS.md
├── CLAUDE.md
├── GEMINI.md
├── PLAN.md
├── INVARIANTS.md
├── DECISIONS.md
├── STATE.json
├── DELTA.json
├── RISKS.json
├── STATE.md                      # rendered once by bootstrap, then maintained by CI on `main`
├── DELTA.md                      # rendered once by bootstrap, then maintained by CI on `main`
├── RISKS.md                      # rendered once by bootstrap, then maintained by CI on `main`
├── .claude/settings.json
├── .gemini/settings.json
├── .execution/bootstrap.state.json
├── .execution/credential-registry.json
├── scripts/check-project-state.mjs
├── scripts/render-state-views.mjs
└── .github/workflows/
    ├── pr-audit.yml
    └── post-merge-state.yml

The contract is intentionally small:

• enough files to keep state and rules explicit
• not so many files that the template creates maintenance burden without adding real constraint clarity

2. What Each File Is For

Instruction adapter files and vendor settings surfaces are covered in Instruction Files.

Writer authority is defined in Tool Roles and Branches And Continuity. Local agents must not commit direct edits to rendered Markdown state views.

Minimal STATE.json shape today:

{
  "updated_at": "2026-04-16T05:10:00+02:00",
  "project": {
    "name": "<PROJECT_NAME>",
    "slug": "<PROJECT_SLUG>",
    "github_repo": "<GITHUB_REPO>"
  },
  "phase": "briefing",
  "status": "active",
  "default_branch": "main",
  "stack": {
    "app": "sveltekit",
    "deploy": "vercel",
    "database": "neon"
  },
  "linked_resources": {
    "vercel_project": "<VERCEL_PROJECT>",
    "neon_project": "<NEON_PROJECT>",
    "database_name": "<DATABASE_NAME>"
  },
  "deterministic_status": [
    "repo_bootstrapped",
    "instruction_contract_present",
    "initial_commit_created",
    "product_brief_pending",
    "requirements_pending",
    "architecture_requirements_pending",
    "readiness_gate_pending"
  ]
}

3. Briefing Before Planning

Bootstrap does not mean the product is already defined.

The generated repo starts in briefing phase. That phase exists to prevent one specific failure mode:

• filling product goal and scope from memory or from a historical repo instead of from an explicit brief

Only after PRODUCT_BRIEF.json is confirmed, REQUIREMENTS.json is confirmed, ARCHITECTURE_REQUIREMENTS.json is confirmed, and READINESS_GATE.json passes should the repo move into product-specific planning.

3a. Canonical Readiness Gate Inventory

The readiness gate IDs are fixed and shared:

4. Bootstrap Phases

The bootstrap script in goingninja-os/scripts/bootstrap-project.sh is resumable.

Current checkpoint shape:

{
  "template_copied": true,
  "placeholders_replaced": true,
  "state_rendered": true,
  "git_initialized": true,
  "initial_commit_created": true,
  "github_repo_created": false,
  "github_remote_configured": false,
  "vercel_project_created": false,
  "vercel_linked": false,
  "neon_project_created": false,
  "neon_database_created": false
}

5. Genesis Writer Vs Maintenance Writer

Two writing moments exist and they should not be confused.

• bootstrap is the genesis writer: it copies the template, renders the first Markdown state once, and records continuity in .execution/bootstrap.state.json
• branch work updates code, decisions, and JSON state
• CI on main is the maintenance writer for rendered Markdown state only

That means:

• bootstrap may create PRODUCT_BRIEF.md, STATE.md, DELTA.md, and RISKS.md once
• branch work should not hand-edit those files
• CI on main may rewrite those files after merge

The canonical branch and continuity model lives in Branches And Continuity. The current proof boundary lives in Workflow And Proof.

5a. Audit State After Verification

After a slice is verified, the repo does not enter audit by memory or chat alone.

The audit path becomes explicit in AUDIT_STATE.json:

• the lane is named
• the scope class is declared
• the frozen snapshot ref is recorded
• normal, closure, and confirm rounds are counted

That file is what lets the audit-exit path stay mechanical instead of rhetorical.

6. Sources

• GitHub Actions workflows