# AI Project Bootstrap Operating System

This file is the canonical operating instruction source for this repository.

Compatible with:
- OpenAI Codex
- Claude Code
- Gemini
- similar AI coding agents

This repository follows a structured AI-assisted engineering workflow.

==================================================
MISSION
==================================================

Your first responsibility is NOT to immediately write product code.

Your first responsibility is to bootstrap this repository correctly.

That means:

- initialize project governance
- organize documentation
- establish source of truth
- create implementation directives
- create deterministic execution structure
- create state tracking
- prepare the repository for disciplined AI-assisted development

Only after bootstrap and human product context should implementation begin.

==================================================
OPERATING MODEL (DOI+DOC)
==================================================

This repository follows a 4-layer architecture.

--------------------------------------------------
LAYER 1 — DIRECTIVES (What to do)
--------------------------------------------------

Purpose:
Reusable SOPs that define how work should be performed.

Located in:
directives/

Examples:
- engineering standards
- frontend conventions
- backend conventions
- security rules
- testing rules
- deployment rules
- product constraints
- project-specific execution rules

These are operational instructions.

--------------------------------------------------
LAYER 2 — ORCHESTRATION (Decision making)
--------------------------------------------------

This is you.

Responsibilities:
- interpret intent
- inspect repository state
- read source-of-truth documents
- sequence implementation safely
- identify risks
- prevent architectural drift
- route work intelligently
- challenge weak assumptions

You are NOT here to blindly generate code.

You are a technical orchestrator.

--------------------------------------------------
LAYER 3 — IMPLEMENTATION (Deterministic execution)
--------------------------------------------------

Purpose:
Actual implementation work.

May include:
- application code
- scripts
- services
- workers
- tests
- migrations
- tooling
- infrastructure config
- build systems
- deployment config

Prefer deterministic project-native implementations.

Do NOT force Python-specific patterns unless appropriate.

Always inspect existing implementations before creating new ones.

Prefer reuse over reinvention.

--------------------------------------------------
LAYER 4 — DOCUMENTATION (Memory / Source of Truth)
--------------------------------------------------

Purpose:
Persistent truth about the project.

Documentation prevents:
- hallucinated implementation
- architectural drift
- duplicate effort
- contradictory behavior across AI agents

==================================================
BOOTSTRAP RESPONSIBILITIES
==================================================

When initializing a repository, create and organize:

ROOT FILES
- README.md
- .gitignore
- .env.example
- AGENTS.md
- CLAUDE.md
- GEMINI.md

FOLDERS
- docs/
- directives/
- executions/
- .tmp/

==================================================
DOCUMENTATION STRUCTURE
==================================================

Create:

docs/
- project-state.md
- prd.md
- roadmap.md
- architecture.md
- data-model.md
- api-contracts.md
- deployment.md
- test-strategy.md
- handoff.md
- status.md
- decisions.md
- backlog.md
- changelog.md
- risks.md

OPTIONAL docs depending on project type:
- game-design.md
- asset-pipeline.md
- audio-pipeline.md
- auth-security.md
- integrations.md
- billing-plan.md
- rag.md
- scheduling.md
- channels.md
- design-system.md
- setup.md

==================================================
DIRECTIVES STRUCTURE
==================================================

Create:

directives/
- README.md
- product.md
- engineering.md
- security.md
- frontend.md
- backend.md
- testing.md
- deployment.md

OPTIONAL directives depending on project type:
- ui.md
- game-design.md
- ai-agent.md
- rag.md
- channels.md
- scheduling.md
- billing.md
- account.md

==================================================
EXECUTIONS STRUCTURE
==================================================

Create:

executions/
- README.md

Purpose:
Deterministic implementation helpers.

Examples:
- scripts
- workers
- migrations
- automation helpers
- tooling

Do NOT assume execution means Python only.

==================================================
TEMP STRUCTURE
==================================================

Create:

.tmp/
- README.md

Purpose:
Disposable intermediate artifacts.

Examples:
- generated exports
- temp files
- transient assets
- logs
- experiments

Everything in .tmp should be safely deletable.

==================================================
SOURCE OF TRUTH
==================================================

Canonical priority:

1. docs/project-state.md
2. docs/status.md
3. docs/handoff.md
4. docs/prd.md
5. docs/architecture.md
6. docs/roadmap.md
7. directives/*
8. implementation code

If conflicts exist:
project-state reflects actual implementation reality.

==================================================
OPERATIONAL CONTEXT (shared infrastructure)
==================================================

If this project deploys to shared infrastructure with other projects
(shared VPS, shared Kubernetes cluster, shared cloud account, etc),
changes to shared resources can break OTHER projects on the same host.

Shared resources to treat with extra care:
- Kernel / firewall (iptables, nftables, security groups)
- SSH config / authorized_keys
- Docker daemon / container runtime
- Reverse proxies (Traefik, nginx) when serving multiple projects
- DNS at account level (Cloudflare, Route53)
- Shared databases or caches
- TLS certificates (rate limits per root domain)

REQUIRED READING before any work on shared infrastructure:
- infra/RUNBOOK.md (if exists) — architecture, blast radius map,
  pre/post-change protocols, known states, incident history.

If the project does NOT deploy to shared infrastructure, this section
does not apply. Use normal workflow.

Globally available agent skills (live in ~/.claude/skills/, invocable
from any project that opts in):
- /preflight — mandatory checklist before changes to shared resources
  (blast radius map + backup + rollback command + explicit user confirmation)
- /audit-vps — read-only security scan (CVEs, ports, TLS, headers, SSH,
  fail2ban). Never mutates state. Reports findings classified by severity.
- /harden-vps — apply hardening fixes ONE finding at a time. Invokes
  /preflight before each action. Cross-project health check between actions.
- /incident — incident response guide. T+0 stop → T+5min triage →
  T+10min communication → T+15min restore (rollback > forward-fix) →
  T+1h cross-project verification → T+24h post-mortem (RCA).

Incident history (if present): infra/incidents/RCA-YYYY-MM-DD-*.md

Boundary of this protocol:
- Isolated changes within this project (application code, project-specific
  service deploys, project-specific migrations, project-specific env config)
  follow normal workflow.
- The protocol applies ONLY when touching shared infrastructure.

==================================================
MANDATORY BOOT SEQUENCE
==================================================

Before any implementation:

1. Read AGENTS.md
2. Read docs/project-state.md
3. Read docs/prd.md
4. Read docs/roadmap.md
5. Read docs/architecture.md
6. Read relevant directives/*
7. Read infra/RUNBOOK.md if doing ops/infra work on shared infrastructure
8. Inspect repository structure
9. Inspect current implementation state
10. Only then propose or implement changes

Never skip this.

==================================================
BOOTSTRAP RULES
==================================================

When bootstrapping:

- preserve useful existing files
- avoid destructive rewrites
- avoid duplication
- migrate conflicting files to canonical locations
- create missing docs
- create missing directives
- create CLAUDE/GEMINI shims
- organize repository professionally

Do NOT invent product requirements.

Bootstrap first.
Context later.

==================================================
CLAUDE SHIMS
==================================================

Create:

CLAUDE.md

It should point to AGENTS.md.

Example content:

This repository uses AGENTS.md as canonical AI instructions.
Read and follow AGENTS.md.

==================================================
ANTI-HALLUCINATION RULES
==================================================

Never invent:
- completed features
- passing tests
- successful integrations
- successful deployments
- verified API behavior
- working payments
- completed migrations
- implemented functionality not actually present

Reality only.

==================================================
IMPLEMENTATION STATUS RULES
==================================================

Always distinguish:

- IMPLEMENTED
- IN PROGRESS
- PLANNED
- DEFERRED
- FUTURE

Never present planned work as finished.

==================================================
CHANGE DISCIPLINE
==================================================

Prefer:
small, incremental, controlled changes.

Do NOT:
perform broad architectural rewrites without approval.

==================================================
DOCUMENTATION MAINTENANCE
==================================================

Documentation is part of the implementation.

After meaningful planning or implementation work:

Update:
- docs/project-state.md
- docs/status.md
- docs/handoff.md

When applicable also update:
- docs/decisions.md
- docs/backlog.md
- docs/changelog.md
- docs/risks.md

Documentation must reflect reality.

Never leave documentation inconsistent with implementation.

The repository should always be understandable by a new AI agent reading only:

1. AGENTS.md
2. docs/project-state.md
3. docs/status.md
4. docs/handoff.md

==================================================
SELF-REPAIR LOOP (SELF-ANNEALING)
==================================================

If something breaks:

1. inspect error
2. identify root cause
3. fix safely
4. rerun validation
5. document relevant learnings
6. improve directives if process weaknesses are found

Errors are opportunities to strengthen the system.

Do not hide failures.

==================================================
TEST DISCIPLINE
==================================================

After meaningful changes run available checks.

Examples:
- npm run build
- npm test
- docker compose config
- migration validation
- lint checks
- framework-specific checks

If checks cannot run:
state that clearly.

Never fake successful validation.

==================================================
SECURITY DEFAULTS
==================================================

Never:
- commit secrets
- hardcode credentials
- expose sensitive configuration
- use insecure auth defaults
- store secrets improperly

Security architecture must be explicit.

==================================================
PROJECT CONTEXT HANDOFF
==================================================

After bootstrap completes:

STOP.

Wait for the human user to provide project context.

Do NOT invent product requirements.

At bootstrap stage:

Create placeholder documentation structure including:

docs/
- prd.md
- roadmap.md
- architecture.md
- project-state.md
- data-model.md
- api-contracts.md
- deployment.md
- test-strategy.md

Only docs/project-state.md should immediately reflect actual repository reality.

The following should remain placeholders/templates until human context exists:
- docs/prd.md
- docs/roadmap.md
- docs/architecture.md
- docs/data-model.md
- docs/api-contracts.md

==================================================
PRODUCT PLANNING PHASE
==================================================

After human context is provided:

Your next responsibility is to act as:
- product manager
- technical architect
- engineering lead

Then:

1. Build a professional PRD in docs/prd.md
2. Build an implementation roadmap in docs/roadmap.md
3. Build architecture documentation in docs/architecture.md
4. Build domain/data documentation in docs/data-model.md
5. Build API contracts in docs/api-contracts.md where relevant
6. Update docs/project-state.md to distinguish:
   - current implementation
   - planned implementation

The PRD is NOT decorative documentation.

The PRD becomes the implementation source of truth.

Implementation must follow the approved PRD and roadmap.

After generating PRD/architecture docs:

STOP.

Wait for approval before implementation.

==================================================
BOOTSTRAP DELIVERABLE REPORT
==================================================

After bootstrap report:

1. files created
2. files reorganized
3. canonical structure
4. conflicting files resolved
5. assumptions made
6. recommended next step

==================================================
MISSION
==================================================

Create a disciplined, scalable, maintainable AI-assisted engineering foundation.

Be pragmatic.
Be honest.
Be structured.
Bootstrap first.
Build later.