claude-code-arcane 1.0.0

package/skills/agent-protocol/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: agent-protocol
+description: "Inter-agent communication protocol for C-suite agent teams. Defines invocation syntax, loop prevention, isolation rules, response formats, and quality loops."
+argument-hint: ""
+category: "clevel-operations"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Bash
+---
+
+# Inter-Agent Protocol
+
+How C-suite agents talk to each other. Rules that prevent chaos, loops, and circular reasoning.
+
+## Invocation Syntax
+
+Any agent can query another using:
+```
+[INVOKE:role|question]
+```
+
+**Valid roles:** `ceo`, `cfo`, `cro`, `cmo`, `cpo`, `cto`, `chro`, `coo`, `ciso`
+
+## Response Format
+
+```
+[RESPONSE:role]
+Key finding: [one line — the actual answer]
+Supporting data:
+  - [data point 1]
+  - [data point 2]
+Confidence: [high | medium | low]
+Caveat: [one line — what could make this wrong]
+[/RESPONSE]
+```
+
+## Loop Prevention (Hard Rules)
+
+1. **No Self-Invocation** — An agent cannot invoke itself.
+2. **Maximum Depth = 2** — Chains can go A→B→C. Third hop is blocked.
+3. **No Circular Calls** — If A called B, B cannot call A in the same chain.
+4. **Chain Tracking** — Each invocation carries `[CHAIN: cro → cfo → coo]`.
+
+**When blocked:** Return assumption instead of invoking:
+```
+[BLOCKED: cannot invoke cfo — circular call detected]
+State assumption used instead: [explicit assumption]
+```
+
+## Isolation Rules
+
+### Board Meeting Phase 2 (Independent Analysis)
+**NO invocations allowed.** Each role forms independent views before cross-pollination. If data is needed: `[ASSUMPTION: ...]`
+
+### Board Meeting Phase 3 (Critic Role)
+Executive Mentor can **reference** other roles' outputs but **cannot invoke** them.
+
+### Outside Board Meetings
+Invocations allowed freely, subject to loop prevention rules.
+
+## When to Invoke vs When to Assume
+
+**Invoke when:** question requires domain-specific data, error would materially change the recommendation, question is cross-functional.
+
+**Assume when:** data is directionally clear, you're in Phase 2 isolation, chain is at depth 2, question is minor.
+
+## Conflict Resolution
+
+When two invoked agents give conflicting answers: flag explicitly, state resolution approach (conservative / probabilistic / escalate), never silently pick one.
+
+## Quick Reference
+
+| Rule | Behavior |
+|------|----------|
+| Self-invoke | Always blocked |
+| Depth > 2 | Blocked, state assumption |
+| Circular | Blocked, state assumption |
+| Phase 2 isolation | No invocations |
+| Phase 3 critique | Reference only, no invoke |
+| Conflict | Surface it, don't hide it |
+
+## Internal Quality Loop
+
+No role presents to the founder without passing through the verification loop. See `references/quality-loop.md` for the full 4-step process: Self-Verification, Peer Verification, Critic Pre-Screen, Course Correction.
+
+## User Communication Standard
+
+All C-suite output follows ONE format. See `references/communication-standard.md` for Standard Output, Proactive Alert, and Board Meeting Output templates.
+
+### Communication Rules (non-negotiable)
+
+1. **Bottom line first.** The founder's time is the scarcest resource.
+2. **Results and decisions only.** No process narration.
+3. **Max 5 bullets per section.** Longer = reference doc.
+4. **Actions have owners and deadlines.** "We should consider" is banned.
+5. **Decisions framed as options** with trade-offs and recommendation.
+6. **Risks are concrete.** "If X happens, Y breaks, costing $Z."
+7. **Silence is an option.** Don't fabricate updates.
+
+## Resources
+- `references/invocation-patterns.md` — common cross-functional patterns with examples
+- `references/quality-loop.md` — self-verify, peer-verify, critic pre-screen, course correction
+- `references/communication-standard.md` — output templates for standard, proactive alert, board meeting

package/skills/agent-protocol/references/communication-standard.md

@@ -0,0 +1,115 @@
+# User Communication Standard
+
+All C-suite output to the founder follows ONE format. No exceptions. The founder is the decision-maker — give them results, not process.
+
+## Standard Output (single-role response)
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📊 [ROLE] — [Topic]
+
+BOTTOM LINE
+[One sentence. The answer. No preamble.]
+
+WHAT
+• [Finding 1 — most critical]
+• [Finding 2]
+• [Finding 3]
+(Max 5 bullets. If more needed → reference doc.)
+
+WHY THIS MATTERS
+[1-2 sentences. Business impact. Not theory — consequence.]
+
+HOW TO ACT
+1. [Action] → [Owner] → [Deadline]
+2. [Action] → [Owner] → [Deadline]
+3. [Action] → [Owner] → [Deadline]
+
+⚠️ RISKS (if any)
+• [Risk + what triggers it]
+
+🔑 YOUR DECISION (if needed)
+Option A: [Description] — [Trade-off]
+Option B: [Description] — [Trade-off]
+Recommendation: [Which and why, in one line]
+
+📎 DETAIL: [reference doc or script output for deep-dive]
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+## Proactive Alert (unsolicited — triggered by context)
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+🚩 [ROLE] — Proactive Alert
+
+WHAT I NOTICED
+[What triggered this — specific, not vague]
+
+WHY IT MATTERS
+[Business consequence if ignored — in dollars, time, or risk]
+
+RECOMMENDED ACTION
+[Exactly what to do, who does it, by when]
+
+URGENCY: 🔴 Act today | 🟡 This week | ⚪ Next review
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+## Board Meeting Output (multi-role synthesis)
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📋 BOARD MEETING — [Date] — [Agenda Topic]
+
+DECISION REQUIRED
+[Frame the decision in one sentence]
+
+PERSPECTIVES
+  CEO: [one-line position]
+  CFO: [one-line position]
+  CRO: [one-line position]
+  [... only roles that contributed]
+
+WHERE THEY AGREE
+• [Consensus point 1]
+• [Consensus point 2]
+
+WHERE THEY DISAGREE
+• [Conflict] — CEO says X, CFO says Y
+• [Conflict] — CRO says X, CPO says Y
+
+CRITIC'S VIEW (Executive Mentor)
+[The uncomfortable truth nobody else said]
+
+RECOMMENDED DECISION
+[Clear recommendation with rationale]
+
+ACTION ITEMS
+1. [Action] → [Owner] → [Deadline]
+2. [Action] → [Owner] → [Deadline]
+3. [Action] → [Owner] → [Deadline]
+
+🔑 YOUR CALL
+[Options if you disagree with the recommendation]
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+## Communication Rules (non-negotiable)
+
+1. **Bottom line first.** Always. The founder's time is the scarcest resource.
+2. **Results and decisions only.** No process narration ("First I analyzed..."). No thinking out loud.
+3. **What + Why + How.** Every finding explains WHAT it is, WHY it matters (business impact), and HOW to act on it.
+4. **Max 5 bullets per section.** Longer = reference doc.
+5. **Actions have owners and deadlines.** "We should consider" is banned. Who does what by when.
+6. **Decisions framed as options.** Not "what do you think?" — "Option A or B, here's the trade-off, here's my recommendation."
+7. **The founder decides.** Roles recommend. The founder approves, modifies, or rejects. Every output respects this hierarchy.
+8. **Risks are concrete.** Not "there might be risks" — "if X happens, Y breaks, costing $Z."
+9. **No jargon without explanation.** If you use a term, explain it on first use.
+10. **Silence is an option.** If there's nothing to report, don't fabricate updates.

package/skills/agent-protocol/references/invocation-patterns.md

@@ -0,0 +1,247 @@
+# Invocation Patterns — Inter-Agent Protocol
+
+Common cross-functional patterns, with examples and guidance on when to invoke vs assume.
+
+---
+
+## Pattern 1: Revenue Planning Chain
+**CRO → CFO → CMO**
+
+Used when: setting revenue targets, allocating growth budget, modeling pipeline scenarios.
+
+```
+CRO initiates:
+"Planning Q3 revenue targets. Need financial constraints and marketing input."
+
+CRO → [INVOKE:cfo|What's our Q3 revenue target given current runway and burn?]
+
+CFO responds:
+[RESPONSE:cfo]
+Key finding: To maintain 12-month runway without new raise, Q3 ARR target ≥ $2.4M (+20% QoQ)
+Supporting data:
+  - Current ARR: $2.0M, burn: $180K/month, runway: 14 months
+  - 20% QoQ growth maintains runway; <15% triggers bridge discussion
+  - Board expectation communicated as 25% QoQ
+Confidence: high
+Caveat: Assumes no new hires or major infrastructure spend in Q3.
+[/RESPONSE]
+
+CRO → [INVOKE:cmo|Given a $2.4M Q3 ARR target, what pipeline coverage and CAC should we plan for?]
+[CHAIN: cro → cfo → cmo]
+
+CMO responds:
+[RESPONSE:cmo]
+Key finding: Need 3x pipeline ($7.2M) and CAC ≤ $8,400 to hit $2.4M ARR target.
+Supporting data:
+  - Historical close rate: 33% → 3x coverage required
+  - Current CAC: $9,100 → 8% efficiency improvement needed
+  - Recommended channel mix: 60% outbound, 30% inbound, 10% partner
+Confidence: medium
+Caveat: Close rate assumes no sales team changes; any rep turnover drops it to 25%.
+[/RESPONSE]
+```
+
+**What CRO does with this:** Synthesizes CFO constraint (target) + CMO playbook (how to hit it) into a revenue plan. Does not invoke further (depth limit reached).
+
+---
+
+## Pattern 2: Hiring Decision Chain
+**CHRO → CFO → COO**
+
+Used when: headcount planning, role approval, capacity vs budget tradeoffs.
+
+```
+CHRO initiates:
+"Engineering wants to hire 3 senior engineers. Need budget clearance and capacity validation."
+
+CHRO → [INVOKE:cfo|Can we afford 3 senior engineers in H2? Fully loaded ~$180K each.]
+
+[RESPONSE:cfo]
+Key finding: Budget supports 2 hires now; 3rd is contingent on Q2 ARR closing above $2.1M.
+Supporting data:
+  - Current H2 headcount budget: $340K remaining
+  - 2 hires = $270K fully loaded → $70K buffer
+  - 3 hires = $405K → $65K over; triggers board approval
+Confidence: high
+Caveat: Based on current runway projection — fundraise close changes this completely.
+[/RESPONSE]
+
+CHRO → [INVOKE:coo|Do operations support onboarding 2-3 engineers in H2? Any capacity constraints?]
+[CHAIN: chro → cfo → coo]
+
+[RESPONSE:coo]
+Key finding: Can absorb 2 comfortably; 3rd requires dedicated onboarding lead or delays velocity 6 weeks.
+Supporting data:
+  - Current eng team: 8 → adding 2 is 25% growth (manageable)
+  - Onboarding bottleneck: 1 senior eng mentor per 1-2 new hires, currently at capacity
+  - Dev environment setup: 3-week lead time per hire
+Confidence: medium
+Caveat: Assumes no concurrent product launches requiring full team focus.
+[/RESPONSE]
+
+CHRO synthesis: Recommends 2 hires now, pipeline 3rd for Q3 contingent on ARR milestone.
+```
+
+---
+
+## Pattern 3: Product Launch Chain
+**CPO → CTO → CMO**
+
+Used when: planning feature launches, assessing readiness, aligning go-to-market.
+
+```
+CPO initiates:
+"Planning Q3 launch of [Feature X]. Need technical readiness and GTM input."
+
+CPO → [INVOKE:cto|Is Feature X technically ready for Q3 launch? Key risks?]
+
+[RESPONSE:cto]
+Key finding: 70% complete; Q3 launch is achievable with scope cut — 2 items must move to Q4.
+Supporting data:
+  - Core feature: complete; performance optimization: 3 weeks remaining
+  - Infrastructure scaling: needs load testing at 10x current volume
+  - Scope cuts needed: advanced analytics dashboard, third-party integrations
+Confidence: medium
+Caveat: Assumes no critical bugs found in load testing; historical rate suggests 1-2 found.
+[/RESPONSE]
+
+CPO → [INVOKE:cmo|Given Q3 launch of Feature X (core only, no analytics/integrations), what's the GTM plan?]
+[CHAIN: cpo → cto → cmo]
+
+[RESPONSE:cmo]
+Key finding: Core-only launch works for existing customers; new logo acquisition needs integrations — recommend phased announcement.
+Supporting data:
+  - Phase 1: Early access for top 20 accounts → testimonials and case studies
+  - Phase 2: Full launch with integration partners in Q4
+  - CAC impact: core-only launch reduces new logo conversion rate 15%
+Confidence: medium
+Caveat: Competitor launched similar feature last month — window for differentiation is narrow.
+[/RESPONSE]
+```
+
+---
+
+## Pattern 4: Crisis Broadcast
+**CEO → All Roles**
+
+Used when: major adverse event, fundraise miss, key customer loss, market disruption.
+
+```
+CEO broadcasts:
+[BROADCAST:all|Scenario: largest customer (28% of ARR) gives 60-day termination notice. 
+Each role: what's the immediate impact on your domain and your top recommended action?]
+
+Roles respond INDEPENDENTLY (no agent sees others' responses first):
+
+[RESPONSE:cfo]
+Key finding: 28% ARR loss drops runway from 14 to 8 months at current burn.
+Supporting data:
+  - Lost ARR: ~$560K → burn multiple increases from 1.8x to 3.2x
+  - Bridge options: $500K credit line (pre-approved), defer 2 planned hires
+  - Fundraise timeline must compress: target term sheet within 60 days
+Confidence: high
+Caveat: Assumes no secondary customer churn triggered by news.
+[/RESPONSE]
+
+[RESPONSE:cro]
+Key finding: Pipeline must replace $560K ARR within 6 months to avoid emergency measures.
+Supporting data:
+  - Current qualified pipeline: $1.8M → need 31% close rate (currently 28%)
+  - 3 deals in late stage can cover 70% of gap if closed this quarter
+  - Churn risk: 2 other accounts had similar usage patterns — immediate EBR required
+Confidence: medium
+Caveat: Close rate may drop if word spreads; manage communication carefully.
+[/RESPONSE]
+
+[RESPONSE:chro]
+Key finding: Hiring freeze recommended immediately; retain all current staff.
+Supporting data:
+  - 4 open reqs should pause pending CFO guidance
+  - At-risk of counter-poaching: 2 senior engineers, 1 product lead
+  - Retention bonuses for key staff: ~$80K to secure 12-month commitments
+Confidence: high
+Caveat: Morale impact of freeze can accelerate attrition if not communicated well.
+[/RESPONSE]
+
+[RESPONSE:cpo]
+Key finding: Accelerate features that differentiate with remaining accounts; reduce scope to core.
+Supporting data:
+  - Lost customer's feature requests: deprioritize (no longer strategic)
+  - Features most valued by remaining top 5 accounts: [list from account data]
+  - Reduce Q3 scope by 30% to free engineering capacity for retention work
+Confidence: medium
+Caveat: Need sales input on which features are blocking new logo deals.
+[/RESPONSE]
+
+[RESPONSE:cmo]
+Key finding: Control the narrative; proactive communication to market reduces churn cascade risk.
+Supporting data:
+  - Draft customer communication within 48 hours (frame as strategic pivot, not loss)
+  - Press: no comment strategy unless proactively asked
+  - Replace pipeline: double down on ICP segments where we're strongest
+Confidence: medium
+Caveat: If customer goes public with criticism, narrative control becomes much harder.
+[/RESPONSE]
+
+CEO synthesis: [Aggregates all 9 responses, identifies conflicts, sets priorities]
+```
+
+---
+
+## When to Invoke vs When to Assume
+
+### Invoke when:
+- Cross-functional data is material to the decision
+- Getting it wrong changes the recommendation significantly
+- The other role has data you genuinely don't have
+- Time allows (not in Phase 2 isolation)
+
+### Assume when:
+- You're in Phase 2 (always — no exceptions)
+- The chain is at depth 2 (you cannot invoke further)
+- The answer is directionally obvious (e.g., "CFO will care about runway")
+- The precision doesn't change the recommendation
+
+### State assumptions explicitly:
+```
+[ASSUMPTION: runway ~12 months — not verified with CFO; actual may vary ±20%]
+[ASSUMPTION: CAC ~$8K based on industry benchmark — CMO has actual figures]
+[ASSUMPTION: engineering capacity at ~70% — not verified with CTO]
+```
+
+---
+
+## Handling Conflicting Responses
+
+When two agents give incompatible answers, surface it:
+
+```
+[CONFLICT DETECTED]
+CFO says: runway extends to 18 months if Q3 targets hit
+CRO says: only 45% confidence Q3 targets will be hit
+Resolution: use probabilistic blend
+  - 45% probability: 18-month runway (optimistic case)
+  - 55% probability: 11-month runway (current trajectory)
+Expected value: ~14 months
+Recommendation: plan for 12 months, trigger bridge at 10.
+[/CONFLICT]
+```
+
+**Resolution options:**
+1. **Conservative:** Use worse case — appropriate for cash/runway decisions
+2. **Probabilistic:** Weight by confidence scores — appropriate for planning
+3. **Escalate:** Flag for human decision — appropriate for high-stakes irreversible choices
+4. **Time-box:** Gather more data within 48 hours — appropriate when data gap is closeable
+
+---
+
+## Anti-Patterns to Avoid
+
+| Anti-pattern | Problem | Fix |
+|---|---|---|
+| Invoke to validate your own conclusion | Confirmation bias loop | Ask open-ended questions |
+| Invoke when assuming works | Unnecessary latency | State assumption clearly |
+| Hide conflicts between responses | Bad synthesis | Always surface conflicts |
+| Invoke across depth > 2 | Loop risk | State assumption at depth 2 |
+| Invoke during Phase 2 | Groupthink contamination | Flag with [ASSUMPTION:] |
+| Vague questions | Poor responses | Specific, scoped questions only |

package/skills/agent-protocol/references/quality-loop.md

@@ -0,0 +1,123 @@
+# Internal Quality Loop
+
+No role presents to the founder without passing through this verification loop. The founder sees polished, verified output — not first drafts.
+
+## Step 1: Self-Verification (every role, every time)
+
+Before presenting, every role runs this internal checklist:
+
+```
+SELF-VERIFY CHECKLIST:
+□ Source Attribution — Where did each data point come from?
+  ✅ "ARR is $2.1M (from CRO pipeline report, Q4 actuals)"
+  ❌ "ARR is around $2M" (no source, vague)
+
+□ Assumption Audit — What am I assuming vs what I verified?
+  Tag every assumption: [VERIFIED: checked against data] or [ASSUMED: not verified]
+  If >50% of findings are ASSUMED → flag low confidence
+
+□ Confidence Score — How sure am I on each finding?
+  🟢 High: verified data, established pattern, multiple sources
+  🟡 Medium: single source, reasonable inference, some uncertainty
+  🔴 Low: assumption-based, limited data, first-time analysis
+
+□ Contradiction Check — Does this conflict with known context?
+  Check against company-context.md and recent decisions in decision-log
+  If it contradicts a past decision → flag explicitly
+
+□ "So What?" Test — Does every finding have a business consequence?
+  If you can't answer "so what?" in one sentence → cut it
+```
+
+## Step 2: Peer Verification (cross-functional validation)
+
+When a recommendation impacts another role's domain, that role validates BEFORE presenting.
+
+| If your recommendation involves... | Validate with... | They check... |
+|-------------------------------------|-------------------|---------------|
+| Financial numbers or budget | CFO | Math, runway impact, budget reality |
+| Revenue projections | CRO | Pipeline backing, historical accuracy |
+| Headcount or hiring | CHRO | Market reality, comp feasibility, timeline |
+| Technical feasibility or timeline | CTO | Engineering capacity, technical debt load |
+| Operational process changes | COO | Capacity, dependencies, scaling impact |
+| Customer-facing changes | CRO + CPO | Churn risk, product roadmap conflict |
+| Security or compliance claims | CISO | Actual posture, regulation requirements |
+| Market or positioning claims | CMO | Data backing, competitive reality |
+
+**Peer validation format:**
+```
+[PEER-VERIFY:cfo]
+Validated: ✅ Burn rate calculation correct
+Adjusted: ⚠️ Hiring timeline should be Q3 not Q2 (budget constraint)
+Flagged: 🔴 Missing equity cost in total comp projection
+[/PEER-VERIFY]
+```
+
+**Skip peer verification when:**
+- Single-domain question with no cross-functional impact
+- Time-sensitive proactive alert (send alert, verify after)
+- Founder explicitly asked for a quick take
+
+## Step 3: Critic Pre-Screen (high-stakes decisions only)
+
+For decisions that are **irreversible, high-cost, or bet-the-company**, the Executive Mentor pre-screens before the founder sees it.
+
+**Triggers for pre-screen:**
+- Involves spending > 20% of remaining runway
+- Affects >30% of the team (layoffs, reorg)
+- Changes company strategy or direction
+- Involves external commitments (fundraising terms, partnerships, M&A)
+- Any recommendation where all roles agree (suspicious consensus)
+
+**Pre-screen output:**
+```
+[CRITIC-SCREEN]
+Weakest point: [The single biggest vulnerability in this recommendation]
+Missing perspective: [What nobody considered]
+If wrong, the cost is: [Quantified downside]
+Proceed: ✅ With noted risks | ⚠️ After addressing [specific gap] | 🔴 Rethink
+[/CRITIC-SCREEN]
+```
+
+## Step 4: Course Correction (after founder feedback)
+
+The loop doesn't end at delivery. After the founder responds:
+
+```
+FOUNDER FEEDBACK LOOP:
+1. Founder approves → log decision (Layer 2), assign actions
+2. Founder modifies → update analysis with corrections, re-verify changed parts
+3. Founder rejects → log rejection with DO_NOT_RESURFACE, understand WHY
+4. Founder asks follow-up → deepen analysis on specific point, re-verify
+
+POST-DECISION REVIEW (30/60/90 days):
+- Was the recommendation correct?
+- What did we miss?
+- Update company-context.md with what we learned
+- If wrong → document the lesson, adjust future analysis
+```
+
+## Verification Level by Stakes
+
+| Stakes | Self-Verify | Peer-Verify | Critic Pre-Screen |
+|--------|-------------|-------------|-------------------|
+| Low (informational) | ✅ Required | ❌ Skip | ❌ Skip |
+| Medium (operational) | ✅ Required | ✅ Required | ❌ Skip |
+| High (strategic) | ✅ Required | ✅ Required | ✅ Required |
+| Critical (irreversible) | ✅ Required | ✅ Required | ✅ Required + board meeting |
+
+## Verified Output Format
+
+The verified output adds confidence and source information:
+
+```
+BOTTOM LINE
+[Answer] — Confidence: 🟢 High
+
+WHAT
+• [Finding 1] [VERIFIED: Q4 actuals] 🟢
+• [Finding 2] [VERIFIED: CRO pipeline data] 🟢  
+• [Finding 3] [ASSUMED: based on industry benchmarks] 🟡
+
+PEER-VERIFIED BY: CFO (math ✅), CTO (timeline ⚠️ adjusted to Q3)
+```

package/skills/agent-workflow-designer/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: agent-workflow-designer
+description: "Design production-grade multi-agent workflows with pattern selection, handoff contracts, failure handling, and cost/context controls for sequential, parallel, router, orchestrator, and evaluator topologies."
+argument-hint: ""
+category: "backend"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Bash
+---
+
+# Agent Workflow Designer
+
+Design production-grade multi-agent workflows with clear pattern choice, handoff contracts, failure handling, and cost/context controls.
+
+## Core Capabilities
+
+- Workflow pattern selection for multi-step agent systems
+- Skeleton config generation for fast workflow bootstrapping
+- Context and cost discipline across long-running flows
+- Error recovery and retry strategy scaffolding
+- Documentation pointers for operational pattern tradeoffs
+
+## When to Use
+
+- A single prompt is insufficient for task complexity
+- You need specialist agents with explicit boundaries
+- You want deterministic workflow structure before implementation
+- You need validation loops for quality or safety gates
+
+## Pattern Map
+
+- `sequential`: strict step-by-step dependency chain
+- `parallel`: fan-out/fan-in for independent subtasks
+- `router`: dispatch by intent/type with fallback
+- `orchestrator`: planner coordinates specialists with dependencies
+- `evaluator`: generator + quality gate loop
+
+Detailed templates: `references/workflow-patterns.md`
+
+## Recommended Workflow
+
+1. Select pattern based on dependency shape and risk profile.
+2. Scaffold config via `scripts/workflow_scaffolder.py`.
+3. Define handoff contract fields for every edge.
+4. Add retry/timeouts and output validation gates.
+5. Dry-run with small context budgets before scaling.
+
+## Common Pitfalls
+
+- Over-orchestrating tasks solvable by one well-structured prompt
+- Missing timeout/retry policies for external-model calls
+- Passing full upstream context instead of targeted artifacts
+- Ignoring per-step cost accumulation
+
+## Best Practices
+
+1. Start with the smallest pattern that can satisfy requirements.
+2. Keep handoff payloads explicit and bounded.
+3. Validate intermediate outputs before fan-in synthesis.
+4. Enforce budget and timeout limits in every step.