# Getting Started: Claude Code Full-Generation Workflow

You're launching a full-generation task in Claude Code. **Read in this order:**

## Step 1: Root Governance (CRITICAL)
Read **AGENTS.md** (all 477 lines, ~10 minutes)
- Why: Defines the source-of-truth hierarchy, mutation boundaries, tier structure, version policy, and success criteria
- Key sections:
  - Lines 1-77: Source-of-truth hierarchy (Tier 1-4, what's hand-authored vs. generated)
  - Lines 78-117: Approved stack versions (Node.js, NestJS, Prisma, React, etc.)
  - Lines 298-328: Generation workflow (13 mandatory steps)
  - Lines 493-507: Success criteria (what done actually looks like)

## Step 2: Master Task Definition (CRITICAL)
Read **prompts/general-prompt.md** (all 535 lines, ~10 minutes)
- Why: Defines your mission as orchestrator, the 8-stage roadmap, parent vs. generator responsibilities, and contract freeze protocol
- Key sections:
  - Lines 1-56: Your role and mission
  - Lines 212-492: Stage-by-stage roadmap (Discovery → Final Review)
  - Lines 493-507: Success criteria (must pass all)

## Step 3: Claude Code Entry Points (FOR YOU)
Read **.claude/CLAUDE.md** (all 242 lines, ~5 minutes)
- Why: Claude Code-specific entry points and MCP tools
- Key sections:
  - Lines 26-59: How to invoke orchestrator (CLI, programmatic, via Agent SDK)
  - Lines 199-217: Available MCP servers (Context7, exa, memory, etc.)
  - **Skip lines 10-88**: These duplicate AGENTS.md; use as reference only

## Step 4: Subagent Delegation Protocol (FOR YOU)
Read **prompts/claude-orchestration-rules.md** (all 389 lines, ~8 minutes)
- Why: Defines how to delegate to subagents, contract freeze, acceptance protocol, and failure handling
- Key sections:
  - Lines 70-173: Mandatory delegation workflow (5 phases)
  - Lines 196-213: Write-zone enforcement (what each agent is allowed to touch)
  - Lines 216-237: Failure handling (how to handle rejected outputs)
  - Lines 279-356: Example full delegation cycle (read this if unsure)
- **Skip lines 1-68**: These duplicate general-prompt.md; use as reference only

## Before Delegating to a Generator

Load the stage-specific rule file that matches your current work:

**Stage D (Shared Platform Scaffold):**
- prompts/auth-rules.md (auth/realm generation)
- prompts/runtime-rules.md (docker, env, deploy)

**Stage E (Parallel Specialized Generation):**
- prompts/prisma-rules.md (before delegating to generator_prisma)
- prompts/backend-rules.md (before delegating to generator_nest_resources)
- prompts/frontend-rules.md (before delegating to generator_react_admin_resources)

**Stage G (Validation):**
- prompts/validation-rules.md (interpreting validation gate output)

## Reference Documents (Consult as Needed)

- **docs/completion-contract.md**: Definition of done, failure modes, recovery procedures
- **domain/dsl-spec.md**: DSL syntax reference (only if DSL is ambiguous)
- **docs/generation-playbook.md**: Step-by-step workflow (optional deep-dive)

## Key Decisions to Make Before Starting

1. **Am I doing a full-generation run or a repair run?**
   - Full-generation: Start from clean Tier 1/2 (DSL only); recreate server/ and client/ from scratch
   - Repair: Start with existing Tier 3; fix specific issues

2. **Which subagents do I need?**
   - Always: explorer (discovery), docs_researcher (verification)
   - Usually: generator_prisma, generator_nest_resources, generator_react_admin_resources
   - Maybe: generator_data_access (only if dataProvider needs repair)
   - Always last: reviewer (final quality check)

3. **What's my acceptance threshold for delegated outputs?**
   - Review against: write-zones, contract adherence, integration readiness
   - Allow one bounded repair if rejected
   - Reject explicitly if repair fails
   - Don't silently continue with partial work

## Quick Checklist

- [ ] Read AGENTS.md
- [ ] Read prompts/general-prompt.md
- [ ] Read .claude/CLAUDE.md
- [ ] Read prompts/claude-orchestration-rules.md
- [ ] Understand the 8-stage roadmap (general-prompt.md)
- [ ] Know when to load stage-specific prompts
- [ ] Know your write-zones (prompts/claude-orchestration-rules.md lines 196-213)
- [ ] Know your acceptance protocol (prompts/claude-orchestration-rules.md lines 138-155)
- [ ] Ready to delegate? Start with explorer, then docs_researcher, then contract freeze

## Common Questions

**Q: Do I read .codex/AGENTS.md?**
A: Only if using Codex runtime (a different Claude product). For Claude Code, read `.claude/CLAUDE.md` instead. Root `AGENTS.md` applies to all runtimes.

**Q: Do I read agents/definitions.ts?**
A: No, it's loaded automatically by the orchestrator. It's for implementation, not user reading.

**Q: Do I read the .toml files?**
A: No, they're loaded automatically by agents. They're not for manual reading.

**Q: What if I disagree with the version policy?**
A: Don't. It's Tier 1 source of truth (AGENTS.md lines 78-117). If you need to upgrade, make that a separate explicit task, not part of routine generation.

**Q: What if a subagent output violates write-zones?**
A: Reject it explicitly. Quote the specific violation and the allowed write-zone from prompts/claude-orchestration-rules.md. Allow one bounded repair. If it still violates, manual fallback.

**Q: What if validation gates fail?**
A: See prompts/claude-orchestration-rules.md Phase 5 (Validation & Final Review). Run the gates, surface failures explicitly, allow one bounded repair, or flag for manual review.

---

**Ready? Start with AGENTS.md.**

*Last Updated: 2026-04-07*