workflow

name	workflow
description	Auto-select and orchestrate playbook skills end-to-end for feature, bug-fix, or refactor work. Use when the user gives a general request without naming a specific skill — workflow picks the right skills, sequences them, and keeps overhead proportional to the change size. NOT for creating a standalone task breakdown (use plan) or writing spec artifacts (use spec).
metadata	{"stage":"Define","tags":["workflow","auto-routing","skill-orchestration","delivery-loop","taxonomy","orchestrator","router"],"aliases":["orchestrate","route","auto-select","delivery-loop","end-to-end"]}

Workflow (Auto Router)

Overview

This skill is a workflow orchestrator: it routes work across the other skills in this repo so you can deliver cohesive enterprise web app changes without the user needing to micromanage “which skill to use”.

Default loop: Define → Standardize → Harden → Verify.

Chooser

• Use workflow when: the user gives a general request ("add feature X", "fix this bug", "refactor module Y") without naming a specific skill. Workflow picks the right skills and sequences them.
• Do NOT use workflow when: the user names a specific skill ("run plan", "write a spec", "do a review") — invoke that skill directly.
• Do NOT use workflow for: one-shot questions about code, explanations, or small edits that don't need multi-skill orchestration.

Inputs / Outputs

Inputs: User request (unstructured), codebase. Outputs: Completed work via orchestrated skill chain; final output from the last skill (typically finish for non-trivial changes).

Workflow

0) Calibrate scope (keep overhead proportional)

Classify the request:

• Tiny change: small UI copy tweaks, rename a local variable, fix a typo. No behavior/contract change.
• Normal change: touches behavior, boundary semantics, or adds a feature.
• Big change: cross-service work, migrations, or changes that affect multiple boundaries/teams.

For this repo, non-trivial = normal or big.

Rule: only create/expand specs and platform primitives when they reduce future drift for the expected scope.

Proportionality guide (what to skip per scope):

Scope	Skip	Always apply	Use if relevant
Tiny	plan, spec, architecture, design, platform, review, finish	typescript (if TS)	testing (if behavior changed)
Normal	architecture (unless cross-service), platform (unless 2+ services)	plan, archobs, testing, finish	spec (if contracts change), resilience/security/observability (if I/O touched)
Big	nothing	plan, archobs, spec, testing, finish	all Harden + Standardize skills

Boundary cases (scope is about impact, not diff size):

Example change	Scope	Why
Changing a default timeout from 5s to 30s	Normal	Behavior change — affects consumer-visible latency and failure semantics
Adding a new field to a response payload	Normal	Contract change — consumers must handle the new shape
Renaming a variable across 30 files	Tiny	No behavior change — diff is large but purely cosmetic
Adding rate limiting to a public endpoint	Normal	Consumers may start seeing 429s — behavior and error semantics change
Extracting shared auth middleware to packages/shared	Big	Cross-service change — affects deployment and ownership boundaries

GATE: After classifying scope, verify the classification against these boundary cases. If the change touches consumer-visible behavior or contract semantics, it is at least Normal regardless of diff size.

0.5) Externalize the system model (for non-trivial changes)

Before pattern/tool selection, write a compact model:

• Objective function: goal, constraints, and anti-goals.
• System sketch: boundary (in/out), time horizon, actors/incentives, key flows, top bottlenecks.
• Reversibility signal: what evidence would make you change direction.

Then, if the work involves choosing between 2+ viable approaches, the first Define-stage skill stress-tests the model with probes (later skills refine, never re-run). If the path is obvious, note probes: skipped — single viable approach and move on.

• Normal scope: run Assumptions (facts vs assumptions, which to validate first), Second-Order Effects (what changes next week/quarter/year, new load/toil/coupling/failure modes, pre-mortem), and Opportunity Cost / Bias (what we're saying "no" to, sunk cost/familiarity/novelty check). Attach outputs to the decision table.
• Big scope or high ambiguity: also run Feedback Loops (reinforcing/balancing loops, delays, accumulations — attach to system sketch).
• Escalate to one template from ../references/structured-thinking-templates.md when: 3+ options with no clear winner, multiple stakeholders must align, rollback/incident needs formal learning capture, or big-scope probes surfaced unresolved ambiguity.

1) Define (what are we building?)

Pick the minimal “definition artifacts” needed:

• For non-trivial changes, use plan early to produce an executable task list, trade-off table, and measurement ladder.
• If work changes externally visible behavior (API/WS/event schema, boundary error semantics, auth rules), use spec first:
  • update the relevant specs/*.md and/or apps/<service>/spec/ bundle
  • update contracts (contracts/: OpenAPI/proto/WS docs)
  • write acceptance scenarios and failure-mode expectations
• If the primary pressure is cross-service (partial failures, sagas, event-driven, domain boundaries), use architecture.
• If the primary pressure is in-process design (construction/structure/behavior), use design.
• For non-trivial changes, run archobs and wait for its report to complete before proceeding to architecture or design. Downstream skills depend on archobs output (risk scores, boundary leakage, cluster assignments) to make evidence-based decisions — do not continue until the report is available.

2) Standardize (make it consistent)

Prevent copy/paste drift:

• If the same boundary behavior repeats across services (timeouts, retries, error mapping, telemetry fields), use platform and extract a small “golden path” primitive.
• If editing TypeScript, apply typescript while implementing (typed boundaries, explicit lifetimes, safe module structure).

3) Harden (make it survive reality)

If the change touches I/O boundaries (HTTP/gRPC/DB/cache/queues/events/WS), apply these:

• resilience: timeouts + cancellation, bounded retries (only when safe), idempotency/dedupe, breakers/bulkheads when needed.
• security: authn/authz checks, strict input validation, secrets/PII safety, and SSRF/injection guardrails where applicable.
• observability: log/trace/metric correlation, stable field contract, and local verification steps (log → trace → metrics).

4) Verify (prove behavior)

• Use testing for non-trivial changes:
  • characterization tests before refactors
  • consumer-visible tests for new behavior and failure semantics
  • avoid asserting implementation details

Minimum viable execution

When context or time is constrained, these are the load-bearing steps:

1. Classify scope (step 0) — everything else depends on this.
2. Select skill sequence from proportionality guide — skip skills the table says to skip.
3. Execute skills in order — respect sequential dependencies (e.g., spec before testing for contract changes).
4. Run finish for non-trivial changes — verification + summary.

Steps that can be cut under pressure: system model externalization (0.5), structured-thinking probes, recipe lookup.

Common Compositions (Recipes)

These are typical skill sequences for common work types. Adapt based on scope.

New endpoint / handler: spec → typescript → security → resilience → observability → testing → finish

Bug fix (production issue): debug → (fix) → testing → finish

Refactor (in-process): archobs → design → testing → review → finish

New service: spec → architecture → platform → typescript → resilience → security → observability → testing → finish

Cross-service feature: archobs → plan → spec → architecture → platform → typescript → resilience → security → observability → testing → review → finish

Feature roadmap: archobs → forecast (internal) → plan

Full situational awareness: archobs → forecast (combined) → plan

Technology adoption assessment (outside-in): intel → forecast (external) → archobs → architecture → plan Start with ecosystem signals, then check internal readiness. Use when the question is "should we adopt X?" rather than "what should we build next?"

Conditional composition: When archobs reveals high coupling to external dependencies (files with high xnbr bridging to third-party code, or clusters labeled with external technology names), invoke forecast in combined mode (not just internal). Topics for the external engine are derived from archobs cluster labels and high-xnbr file paths.

Architecture health pass: archobs → plan (from suggestions) → design → testing → finish

Security hardening pass: security → testing → review (type: security) → finish

Clarifying Questions

• What is the scope of the change (tiny/normal/big)?
• Are there existing specs, plans, or ADRs that constrain the approach?
• Which services, boundaries, or contracts are affected?
• Are there deployment constraints (freeze windows, feature flags, rollback requirements)?
• Is this greenfield or modifying existing behavior?

Guardrails

• Don’t create “spec theater”: if the change is tiny, keep docs minimal and move on.
• Don’t choose architecture/patterns before writing objective function + constraints + anti-goals.
• Don’t skip specs for boundary/contract changes: pin behavior with contracts + tests.
• Don’t introduce retries without idempotency.
• Don’t add telemetry labels with unbounded/high-cardinality values.
• Don’t define metrics without a named decision, owner, and review ritual.
• Don’t “helpfully” change response shapes or error semantics unless the spec says so.

Common failure modes

• Applies big-scope overhead to tiny changes ("spec theater") — a typo fix does not need a decision table.
• Skips archobs for non-trivial changes because the change "seems simple" — archobs data is required for normal/big scope.
• Runs skills with sequential dependencies in parallel (e.g., running testing before spec is updated for a contract change).
• Does not re-check scope classification after discovering the change is bigger than initially expected.
• Defaults to the longest recipe instead of the proportionality guide.

Output Template

When you finish work, report:

• For non-trivial changes, run finish before reporting.
• Skills applied: which ones you used and why (1 line each).
• System model (non-trivial only): objective function + system sketch + reversal signal.
• What changed: behavior + contract impacts + key files touched.
• Decision + measurement (non-trivial only): chosen option, trade-offs, kill criteria, leading/lagging indicators, and review cadence/owner.
• Verification: commands run and results (or why they couldn’t be run).
• Follow-ups: optional next tasks (if any).

References

• Machine-readable skill index (triggers, tags, related, overhead): specs/skills-manifest.json
• Workflow taxonomy: specs/003-taxonomy-and-workflow.md
• Change process: specs/004-change-process.md
• Structured-thinking probes + templates: ../references/ (checklists for inline probes, templates for escalation)