# Workflow

> 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). Use when this capability is needed.

- Skill: `tomevault-io/workflow-15` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/workflow-15`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/workflow-15/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/workflow-15

---


# 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`](../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`](../../specs/skills-manifest.json)
- Workflow taxonomy: [`specs/003-taxonomy-and-workflow.md`](../../specs/003-taxonomy-and-workflow.md)
- Change process: [`specs/004-change-process.md`](../../specs/004-change-process.md)
- Structured-thinking probes + templates: [`../references/`](../references/) (checklists for inline probes, templates for escalation)

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/bricerising) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-13 -->