.md` and merges global and project-level rules. This layer does not contain workflow logic; it only defines how the AI should behave across all interactions.

# SYSTEM IDENTITY
- **Role:** Technical Execution Partner
- **Communication:** Direct, code-first, zero filler
- **Constraints:** 
  - Never explain unless explicitly requested
  - Always verify file existence before modification
  - Abort on destructive operations without confirmation
- **Output Contract:** Return structured JSON or markdown tables for all automated tasks

Why this works: Separating identity from execution prevents behavioral drift. Agents inherit these rules automatically, ensuring consistent tone and safety checks without duplicating instructions across workflow files.

Step 2: Build Trigger Files

Triggers are user-facing entry points. They reside in .claude/commands/ and accept arguments. They contain zero orchestration logic. Their sole purpose is to capture intent and pass parameters downstream.

---
name: /build-pipeline
description: Execute the CI build sequence with optional scope filtering
arguments:
  - target: "env"
    type: "string"
    required: false
    default: "staging"
---

Initiate build pipeline for environment: $ARGUMENTS.target

Why this works: Triggers remain declarative. By stripping logic from this layer, you enable rapid iteration on user experience without touching execution code. The slash-command interface matches native editor behavior, reducing cognitive load.

Step 3: Create Orchestration Rules

Orchestrators live in .claude/skills/. They read trigger arguments, instantiate execution workers, manage retries, and format final outputs. This layer handles composition, error boundaries, and result transformation.

# ORCHESTRATOR: CI_BUILD
## Worker Template
Load: `.claude/agents/build-runner.md`

## Execution Protocol
1. Validate environment argument against allowed list
2. Spawn worker with payload: { env: $ARGUMENTS.target, retry_limit: 2 }
3. Monitor worker exit code
4. If exit code != 0, retry once with verbose logging
5. Transform raw output into markdown summary table

## Output Contract
Return:
- Status: PASS/FAIL
- Duration: seconds
- Artifacts: list of generated files
- Errors: array of { code, message, file }

Why this works: Orchestration centralizes cross-cutting concerns. Retry logic, output formatting, and argument validation live here, keeping workers focused on domain execution. This layer also enables parallel spawning and result aggregation without polluting the main conversation.

Step 4: Deploy Execution Workers

Workers reside in .claude/agents/. They are autonomous, stateless, and bounded. Each worker receives a context payload, executes a defined sequence, and returns a structured result. They run in isolated contexts to preserve the main conversation window.

# WORKER: BUILD_RUNNER
## Scope
Execute environment-specific build commands and capture diagnostics.

## Execution Sequence
1. Read project config to locate build script
2. Run: `npm run build -- --env=${payload.env}`
3. Capture stdout, stderr, and exit code
4. Parse build artifacts from output directory
5. Return structured payload matching orchestrator contract

## Error Boundaries
- Timeout: 120s → abort and return timeout flag
- Missing config: return config_not_found error
- Syntax failure: return first compilation error only

Why this works: Isolated execution prevents context bloat. Workers do not maintain state between runs, ensuring predictable behavior. Bounded execution guarantees token limits are respected. The strict output contract enables downstream parsing by external tooling.

Architecture Rationale

The separation of concerns follows a strict data flow: Intent → Routing → Orchestration → Execution → Contract. Each layer communicates through explicit payloads, not implicit conversation state. This design enables:

• Context budgeting: Main thread remains reserved for user interaction
• Deterministic routing: Triggers map directly to orchestrators
• Testable workflows: Workers can be validated in isolation
• Token optimization: Redundant reads and verbose outputs are eliminated at the orchestration layer

Pitfall Guide

1. Identity Leakage into Execution

Explanation: Developers embed persona rules directly into worker templates, causing behavioral duplication and context bloat. Fix: Keep CLAUDE.md as the single source of truth. Reference it implicitly; never copy rules into .claude/agents/.

2. Orchestration Bypass

Explanation: Skipping the skill layer to save tokens, causing commands to spawn workers directly. This eliminates error handling, retry logic, and output formatting. Fix: Always route through .claude/skills/. The token overhead is negligible compared to the debugging cost of unstructured outputs.

3. Stateful Worker Design

Explanation: Workers expecting memory across invocations or relying on conversation history. This breaks isolation and causes unpredictable behavior. Fix: Design workers as pure functions. Pass all required context in the payload. Never reference previous runs.

4. Unbounded Execution Windows

Explanation: Workers running indefinitely or scanning entire repositories without scope limits. This exhausts context windows and increases latency. Fix: Enforce explicit timeouts, file glob limits, and directory scoping in worker templates. Validate scope before execution.

5. Inconsistent Output Contracts

Explanation: Workers returning freeform text instead of structured data. This breaks downstream parsing and automation pipelines. Fix: Define strict return schemas in orchestrator templates. Validate worker outputs against the contract before forwarding.

6. Global/Project Scope Conflicts

Explanation: Merging global and project CLAUDE.md files without precedence rules, causing contradictory instructions. Fix: Establish a clear override hierarchy. Project-level rules should extend, not contradict, global identity constraints. Document precedence explicitly.

7. Trigger Overengineering

Explanation: Embedding conditional logic, loops, or complex argument parsing into command files. This violates the single-responsibility principle. Fix: Keep triggers declarative. Move all logic to orchestrators. Use simple argument substitution only.

Production Bundle

Action Checklist

• Audit existing prompts: Extract identity rules into CLAUDE.md and remove duplicates
• Map workflows to triggers: Create .claude/commands/ files for each user-facing action
• Implement orchestrators: Build .claude/skills/ files with retry logic and output contracts
• Deploy bounded workers: Write .claude/agents/ templates with explicit timeouts and scope limits
• Enforce output schemas: Validate all worker returns against orchestrator contracts
• Test isolation: Run workers independently to verify stateless behavior
• Monitor token consumption: Track context window usage before and after layering
• Version control: Commit all .claude/ directories to repository for team consistency

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Ad-hoc code exploration	Direct prompting	Low overhead, flexible iteration	Baseline token usage
Repetitive CI tasks	Layered architecture	Deterministic, reusable, testable	30-40% token reduction
Multi-step deployments	Orchestrator + Worker	Error handling, parallel execution, structured output	Higher initial setup, lower long-term cost
Team-wide standards	Global CLAUDE.md + Project overrides	Consistent identity, scalable governance	Zero marginal cost
High-frequency linting	Bounded worker with strict timeout	Prevents context bloat, ensures fast feedback	Predictable token budget

Configuration Template

project-root/
├── CLAUDE.md                  # Identity layer (global/project merge)
├── .claude/
│   ├── commands/
│   │   └── deploy.md          # Trigger: captures intent
│   ├── skills/
│   │   └── deploy-orchestrator.md  # Orchestration: routing, retries, formatting
│   └── agents/
│       └── deploy-worker.md   # Execution: bounded, stateless, contract-bound

CLAUDE.md

# IDENTITY
- Role: Technical Execution Partner
- Style: Direct, code-first, zero filler
- Safety: Abort on destructive actions without confirmation
- Output: Structured JSON/Markdown for all automated tasks

.claude/commands/deploy.md

---
name: /deploy
description: Trigger production deployment sequence
arguments:
  - target: "region"
    type: "string"
    required: true
---

Deploy to region: $ARGUMENTS.region

.claude/skills/deploy-orchestrator.md

# ORCHESTRATOR: DEPLOY
## Worker Template
Load: `.claude/agents/deploy-worker.md`

## Execution Protocol
1. Validate region against allowed list
2. Spawn worker with payload: { region: $ARGUMENTS.region, max_retries: 1 }
3. Monitor exit code; retry once on network timeout
4. Format result as markdown table

## Output Contract
- Status: SUCCESS/FAILURE
- Region: string
- Duration: seconds
- Logs: array of { timestamp, level, message }

.claude/agents/deploy-worker.md

# WORKER: DEPLOY
## Scope
Execute deployment script for specified region.

## Execution Sequence
1. Read deployment config
2. Run: `./scripts/deploy.sh --region=${payload.region}`
3. Capture stdout/stderr
4. Return structured payload matching orchestrator contract

## Error Boundaries
- Timeout: 180s
- Missing config: return config_not_found
- Auth failure: return auth_error with hint

Quick Start Guide

1. Initialize directory structure: Create .claude/commands/, .claude/skills/, and .claude/agents/ in your project root.
2. Define identity: Add CLAUDE.md with role, style, and output contract rules. Commit to version control.
3. Create first trigger: Write a simple .claude/commands/ file with YAML frontmatter and argument substitution.
4. Build orchestrator: Add a .claude/skills/ file that references a worker, defines retry logic, and specifies an output schema.
5. Deploy worker: Write a .claude/agents/ template with explicit scope, timeout, and error boundaries. Test in isolation before integration.

This architecture transforms AI coding assistants from conversational tools into deterministic workflow engines. By enforcing separation of concerns, bounded execution, and contract-driven outputs, teams achieve predictable performance, reduced token costs, and scalable automation. Implement the layers, validate the contracts, and monitor context usage. The runtime will reward discipline with reliability.