Engineering Workflow

Engineering Workflow — Micro-Agent Orchestration System

A 3-tier micro-agent system that routes engineering architecture queries to specialized domain agents, resolves cross-domain constraints, and synthesizes unified recommendations.

Role

A 3-tier micro-agent orchestration system for engineering architecture decisions spanning four major systems: DB (Database), BE (Backend), IF (Infrastructure), and SE (Security).

Architecture Overview

                         Tier 1: Gateway Router (this SKILL.md)
                                    |
                    ┌───────────────┼───────────────┐
                    |               |               |
               Tier 2: System Orchestrators
               ┌────┐  ┌────┐  ┌────┐  ┌────┐
               │ DB │  │ BE │  │ IF │  │ SE │
               └──┬─┘  └──┬─┘  └──┬─┘  └──┬─┘
                  |        |        |        |
               Tier 3: Micro Agents (domain-specific)
               ┌─────────────────────────────┐
               │ A: Storage  D: API Design   │
               │ B: Query    E: Concurrency  │
               │ C: Schema   F: Networking   │
               │ ...         ...             │
               └─────────────────────────────┘

Core Principles

1. Constraint-first synthesis: Agents declare constraints; conflicts are detected and resolved before output
2. Deterministic fast-path: Use classify-query.sh for unambiguous queries; reserve LLM classification for edge cases
3. Graceful degradation: If an agent fails or times out, return partial results with clear warnings

Routing Table

System Detection

SE Sub-Domain Detection (6 Clusters: A/Z/E/N/C/V)

DB Sub-Domain Detection (A-F)

BE Sub-Domain Detection (4 Clusters: S/B/R/T)

Execution Patterns

Four execution patterns exist: None (0 systems matched — falls through to LLM classification), Single-Domain (1 agent), Multi-Domain (2-3 agents, parallel dispatch), and Cross-System (multiple orchestrators + synthesizer).

For detailed flow diagrams and examples, see resources/orchestration-protocol.md § Pattern Examples.

Phase Flow

Pre-Flight Check (before Phase 0)

Run before any phase execution to ensure clean session state and detect reusable context.

1. Dependency check: Verify jq is available (command -v jq)
2. Interrupted session detection: Read ~/.claude/cache/engineering-workflow/progress.json
   • If status == "in_progress": previous session was interrupted
   • Archive the interrupted progress file and notify: "Previous session interrupted at phase {phase}. Starting fresh."
3. Session summary reuse: Read ~/.claude/cache/engineering-workflow/session-summary.json
   • If recent (< 30 min) and query is similar: display "Recent analysis available for reuse" with summary
   • Skip re-classification if the same query signature matches
4. Initialize progress: Write progress.json with {phase: "pre-flight", status: "in_progress"}
5. Run cleanup: Execute session cleanup (trim history, evict stale cache)

[engineering-workflow] Pre-Flight: deps=OK | prev_session={none|interrupted} | summary={available|none}

Phase 0: Query Classification

Resource: Read resources/routing-protocol.md when entering this phase.

1. Parse user input for explicit flags (--domain, --depth)
2. Run scripts/classify-query.sh "$QUERY" for keyword-based fast-path classification (2-phase: binary keywords → cross-keyword weighted scoring)
3. Progressive Classification: If session history exists within 30-minute window, augment confidence with prior_boost and suggest domain expansions based on transition patterns (see routing-protocol.md § Step 5.5)
4. Archetype Matching: If query matches a known archetype (e.g., multi-tenant-saas, event-driven-microservice), inject preset constraints from resources/constraints-archetypes.json
5. If confidence >= 0.85: proceed with fast-path result
6. LLM Verification (if needs_llm_verification == true, i.e., confidence > 0.0 AND < 0.85): Execute the lightweight LLM verification protocol defined in routing-protocol.md § Step 4.5:
   • Use the provided verification_prompt as-is (it is context-specific to system count)
   • Compare LLM answer against the keyword classification
   • If LLM agrees: boost confidence by +0.10 (capped at 0.85) and proceed
   • If LLM disagrees: adopt LLM classification, set classifier: "llm-verified", recalculate domains
   • Token cost: ~0.2K per verification (single-turn, no reference loading)
7. If confidence == 0.0 (no keywords matched): use full LLM classification (read routing-protocol.md for detailed algorithm)
8. Output: { systems: [...], domains: [...], pattern: "...", confidence: float, classifier: "...", prior_boost: float, suggested_expansions: [...], archetype_matched: [...], needs_llm_verification: bool, verification_prompt: string|null }

Progressive Classification rollback: Set EW_PROGRESSIVE_CLASSIFICATION=0 to disable.

Status Display:

[engineering-workflow] Phase: Classification | Pattern: {single|multi|cross} | Systems: {DB,BE,...}

Phase 1: Orchestrator Dispatch

Resource: Read resources/orchestration-protocol.md when entering this phase.

1. Based on classification result, identify required orchestrator(s)
2. Read the orchestrator .md file(s) from agents/
3. Construct Task prompt per orchestration-protocol.md template
4. For single-system: invoke one orchestrator Task
5. For cross-system: invoke multiple orchestrator Tasks in parallel
6. Run scripts/enforce-budget.sh <pattern> orchestrator-dispatch <output> to verify token budget before proceeding

Orchestrator Task prompt template:

You are the {system} System Orchestrator.

## Classification
{classification result from Phase 0}

## User Query
{original user query}

## Instructions
Read the relevant agent definition(s) from agents/{system}/ and dispatch sub-tasks.
Collect agent outputs and resolve intra-system constraints.
Return your analysis in the structured format defined in your orchestrator definition.

Phase 2: Agent Execution

BE Test Pipeline Status Display (when T2-T3-T4 loop is active):

[engineering-workflow] Phase: Test Pipeline | Loop: {n}/{max} | Coverage: {pct}% (target: {target}%)

Orchestrators handle this phase internally. Each orchestrator:

1. Reads the required agent .md file(s) from agents/{system}/
2. Constructs focused Task prompts for each agent
3. For multi-domain: dispatches agents in parallel via concurrent Task calls
4. Collects results and performs intra-system constraint merge
5. Returns structured output with constraints declared

Each agent determines its confidence score using the calibration rubric in resources/confidence-calibration.md (5-factor model: input completeness, specificity, evidence grounding, trade-off coverage, assumption count).

Agent Task prompt template:

You are the {domain} Micro Agent.

## Query Context
{focused sub-question extracted by orchestrator}

## Reference Material
{relevant excerpts loaded by orchestrator via Read with offset/limit}

## Output Requirements
1. Analysis: detailed technical analysis
2. Recommendation: concrete actionable recommendation
3. Constraints: declare any constraints your recommendation imposes on other domains
4. Trade-offs: explicit trade-off documentation
5. Confidence: score between 0.0–1.0 per `resources/confidence-calibration.md` rubric

Phase 2.5: Analysis Quality Gate

Resource: Read resources/analysis-audit-protocol.md when entering this phase.

This phase validates agent output quality before constraint resolution.

Steps: 0. Tier Determination: Run scripts/audit-analysis.sh tier <classification> <agent-count> — auto-selects LIGHT / STANDARD / THOROUGH based on system count, agent count, depth, and security keywords. Escalation is upward only (see auto-escalation rules below).

1. Budget Check: Run scripts/enforce-budget.sh <pattern> quality-gate <output> to verify token budget before audit
2. Confidence Gating (all tiers): Run scripts/audit-analysis.sh confidence per agent result

   • = 0.70: PASS

   • 0.50-0.69: PASS + warning
   • 0.30-0.49: Simplified re-dispatch (1 attempt)
   • < 0.30: Reject, orchestrator fallback
3. Completeness Audit (STANDARD+): 6-point checklist — split into deterministic (jq) and semantic (LLM):
   • Deterministic (jq via validate-agent-output.sh): automatically checked, no LLM cost
     • Point 2: 정량적 데이터 — validate-agent-output.sh detects number+unit patterns (ms, GB, %, TPS, etc.)
     • Point 3: Trade-off 문서화 — existing trade_offs array length check (>= 2 options)
     • Point 4: Constraint 선언 — existing constraints field presence check
   • Semantic (LLM evaluation, STANDARD+ only): evaluate each agent output against these 3 criteria:
     • Point 1: 맥락 반영 — Does the analysis address the user's specific context, not generic advice?
     • Point 5: Actionable 추천 — Is the recommendation concrete and implementable, not vague?
     • Point 6: 컨텍스트 인용 — Does the analysis reference key terms from the user's query?
   • LLM evaluation output: for each point, PASS or FAIL with one-line reason. If any FAIL: add warning to output
4. Feasibility Check (STANDARD+): Verify recommendations against constraints_used environment
5. Dynamic Expansion (THOROUGH only): Dispatch audit-reviewer agent for gap detection and expansion

Auto-escalation (upward only):

• 2+ agents with confidence < 0.50 → LIGHT→STANDARD
• Unexpected cross-system constraint → STANDARD→THOROUGH
• Security keywords in agent output → immediate THOROUGH

Phase 3: Constraint Resolution

Resource: Read resources/constraint-propagation.md when entering this phase.

1. Collect all constraint declarations from agents (including archetype-injected constraints)
2. Run scripts/resolve-constraints.sh to detect conflicts:
   • Tier 1 (Structural): Same target, different values — existing detection
   • Tier 2 (Semantic): Known incompatible pairs (e.g., LSM + low read latency) — detected via KNOWN_CONFLICT_PAIRS in _common.sh
3. If no conflicts: merge constraints into unified set
4. If conflicts detected:
   • For intra-system conflicts: orchestrator resolves using domain priority rules
   • For cross-system conflicts: escalate to synthesizer (Phase 4)
5. Orchestrators include all_declared_constraints (pre-resolution snapshot) for synthesizer transparency
6. Store resolved constraints in ~/.claude/cache/engineering-workflow/constraints.json

Phase 3.5: Contract Enforcement Gate

Resource: Reuse resources/analysis-audit-protocol.md (already loaded at Phase 2.5).

STANDARD+ tier only. Validates orchestrator output contracts before synthesis.

Steps:

1. Schema Contract Validation (STANDARD+): Run scripts/audit-analysis.sh orchestrator per orchestrator output
   • Validates required fields (system, status, guidance, recommendations, etc.)
   • Auto-fills defaults for non-critical missing fields with warnings
2. Priority Consistency Check (THOROUGH only): Verify intra-system conflict resolutions follow priority-matrix.md
3. Constraint Forwarding Completeness (THOROUGH only): Verify cross-system impacts are forwarded to unresolved_constraints

Phase 4: Synthesis (Cross-System Only)

Only activated for Pattern "cross" (cross-system) queries.

1. Run scripts/enforce-budget.sh <pattern> synthesis <output> to verify token budget before synthesis
2. Read agents/synthesizer.md
3. Pass all orchestrator outputs + resolved/conflicting constraints
4. Synthesizer produces:
   • Unified recommendation that respects all system constraints
   • Explicit documentation of cross-system trade-offs
   • Implementation priority ordering
   • Risk assessment for constraint violations

Phase 4.5: Synthesis Validation Gate

Resource: Reuse resources/analysis-audit-protocol.md (already loaded at Phase 2.5).

THOROUGH tier, cross-system pattern only. Validates synthesis output integrity.

Steps:

1. Coverage Check: Run scripts/audit-analysis.sh synthesis — verify all systems_analyzed are reflected in unified_recommendation
2. Ordering Validation: Verify implementation_order.depends_on references valid phases (topological sort consistency)
3. Risk-Rollback Completeness: Verify risk: "high" phases have rollback strategies defined
4. Confidence Floor: If confidence_assessment.overall is "low", add explicit caveat to output

Phase 5: Output Formatting

1. Run scripts/format-output.sh to structure the final output
2. Output format:

## Engineering Analysis: {query summary}

### Classification
- Pattern: {single|multi|cross}
- Systems: {DB, BE, ...}
- Domains: {A, C, ...}
- Depth: {shallow|deep}

### Analysis
{per-domain analysis sections}

### Recommendation
{unified recommendation}

### Constraints
{resolved constraint set}

### Trade-offs
| Option | Pros | Cons | Recommended When |
|--------|------|------|-----------------|

### Implementation Priority
1. {highest priority action}
2. {next action}
...

### Risk Assessment
| Risk | Impact | Likelihood | Mitigation |
|------|--------|------------|------------|

Execution Modes

Depth flag: --depth shallow (1 agent, ~3K) or --depth deep (all relevant agents, ~6-14K, default).

Resource Loading Instructions

Resources are loaded on-demand per phase. MUST NOT pre-load all resources.

Agent definitions (loaded by orchestrators during Phase 2):

• Orchestrator .md files: loaded by Gateway Router in Phase 1
• Micro agent .md files: loaded by orchestrators in Phase 2
• agents/synthesizer.md: loaded by Gateway Router in Phase 4 (cross-system only)

Reference excerpts (loaded by agents during Phase 2):

• Agents may use Read with offset/limit to load relevant sections from large reference files
• Follow the large file loading rules: <=200 lines full read, 201-500 lines offset/limit, >500 lines Grep then Read

Constraint Propagation

Agents declare constraints (requires | recommends | prohibits | conflicts_with) in their output. Constraints flow upward through orchestrators → synthesizer for resolution. Hard constraints MUST be respected; soft constraints may be overridden with justification.

Schema, flow diagrams, and storage: resources/constraint-propagation.md

Token Budget Guidelines

Token budgets are guidelines, not hard limits. Exceeding the budget triggers reference excerpt truncation, not query failure.

Note: Budgets include ~20% contingency for complex queries requiring additional reference loading. Actual token usage is typically 10-20% below budget for standard queries.

Budget enforcement: Run scripts/enforce-budget.sh <pattern> <phase> <output> at phase transitions. Exits non-zero if estimated tokens exceed 120% of budget. Patterns: shallow, analysis, implementation, test, full, cross-system, cross-pruning.

Budget guidelines:

1. Orchestrators MUST use offset/limit reference loading over full-file reads
2. At high context pressure (>80%): truncate reference excerpts to essential sections only
3. At critical context pressure (>90%): skip remaining low-priority reference loading
4. MUST NOT sacrifice constraint resolution for token savings

Error Handling

Resource: Read resources/error-playbook.md on error occurrence.

Error Categories

Escalation Protocol

1. Agent fails       → Orchestrator provides fallback analysis
2. Orchestrator fails → Gateway Router provides high-level guidance
3. Multiple failures  → Report partial results + clear error summary to user
4. Total failure      → Return classification result + suggest manual domain selection

Context Health Protocol

Long sessions with multiple queries accumulate context. Monitor and manage proactively.

Thresholds

Recovery After /compact

1. /compact executed → context summarized
2. Check for classification result in context
3. IF not found AND mid-query:
   - Re-run classify-query.sh (fast, deterministic)
   - Re-read only the orchestrator .md needed for current phase
4. Resume from current phase

Status Display Protocol

Display current state at each phase entry.

Format

[engineering-workflow] Phase: {phase} | Pattern: {pattern} | Systems: {systems} | Budget: {used}/{total}K

Examples

[engineering-workflow] Phase: Classification | Pattern: pending | Systems: pending
[engineering-workflow] Phase: Agent Execution | Pattern: cross-system | Systems: DB,BE,SE | Budget: 5.8/14K

Session pattern caching: ~/.claude/cache/engineering-workflow/ (details in constraint-propagation.md)

Agents

Orchestrators (Tier 2)

Micro Agents (Tier 3)

• DB: 6 domains (A-F), 18 agents — see db-orchestrator.md § Agent Selection Matrix
• BE: 4 clusters (S/B/R/T), 18 agents — see be-orchestrator.md § Agent Selection Matrix
• SE: 6 clusters (A/Z/E/N/C/V), 24 agents — see se-orchestrator.md § Agent Selection Matrix

Resources (On-demand)

Scripts

References (Static)

• DB: references/db/ — 18 files covering domains A-F (mapped in db-orchestrator.md § Load Reference Excerpts)
• BE: references/be/ — 11 files covering clusters S/B/R/T (mapped in be-orchestrator.md § Load Reference Excerpts)
• SE: references/se/ — 7 files covering clusters A/Z/E/N/C/V + best practices (mapped in se-orchestrator.md § Load Reference Excerpts)