117 lines
5.4 KiB
Markdown
117 lines
5.4 KiB
Markdown
# 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*
|