toir-automatization/.claude/GETTING_STARTED.md

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