diff --git a/.agents/skills/meta/agentic-workflow-design/SKILL.md b/.agents/skills/meta/agentic-workflow-design/SKILL.md new file mode 100644 index 00000000..f238b98d --- /dev/null +++ b/.agents/skills/meta/agentic-workflow-design/SKILL.md @@ -0,0 +1,358 @@ +--- +name: agentic-workflow-design +id: agentic-workflow-design +version: "1.0.0" +title: "Agentic Workflow Design" +description: "Design or review a multi-step agent workflow with explicit data contracts, gates, verification, and run-record requirements." +type: skill +status: experimental +owners: + - "@GSA-TTS/agentic-coding-team" +primary_personas: + - agents + - developers + - technical-writers +requires: + anchors: [] + skills: [] +output: + format: markdown + contract: + required_sections: + - "Summary" + - "Workflow Design Brief" + - "Data Contracts" + - "Step Graph" + - "Step Specifications" + - "Verification Plan" + - "Readiness Review" + prohibited_content: + - "Secrets" + - "Real PII" + - "Real CUI" + - "Internal URLs" +quality_gates: + readability_max_grade: 10 + citations_required: false +categories: + - development + - testing + - documentation +collection: meta +triggers: + - "design agent workflow" + - "multi-agent workflow" + - "orchestration design" + - "workflow data contract" + - "agent run record" +tags: + - "agentic" + - "workflow" + - "orchestration" + - "data-contracts" + - "verification" +routing: + task_types: + - plan + - analyze + - review + - orchestrate + input_artifacts: + - documentation + output_artifacts: + - documentation + aliases: + - "agent workflow architecture" + - "multi-agent pipeline design" + - "orchestration plan" + prefer_when: + - "A multi-step agent process needs explicit state, gates, verification, and execution controls." + avoid_when: + - "The request is to execute an already-designed workflow rather than design or review it." + priority: 70 +portability: + opencode: true + cursor: true + claude_projects: true + chatgpt: true + generic_llm: true +scope: + intended_use: + - "Designing or reviewing orchestrated workflows that may use agents, tools, external services, and operator decisions." + exclusions: + - "Replacing an implementation-specific scheduler, permissions system, or observability service." + - "Authorizing actions beyond the operator's stated permissions." +--- + +# Skill: Agentic Workflow Design + +## Summary + +Design or review an agent-run workflow as a typed, verifiable system rather +than a sequence of prompts. Use it for multi-step work that may involve +sub-agents, external services, operator decisions, shared state, or a durable +run record. + +The outcome is a design package that an implementation team can review before +building or running the workflow. This skill does not execute the workflow, +grant permissions, or replace the controls of the target platform. + +## When to Use + +- A team asks to design or revise a multi-step workflow run by an orchestrator. +- A workflow needs explicit item states, handoffs, gates, or failure handling. +- A review finds that agents share files, call services, or wait without clear + ownership and evidence. +- A workflow needs measurable acceptance criteria, replayable records, or a + design readiness review. + +## When Not to Use + +- The task is to execute an existing workflow. +- The task is a single, independent agent operation with no handoff or state. +- The requester needs a platform-specific deployment, scheduler, or access + control implementation. Design the controls here, then use the platform's + implementation guidance. + +## Inputs and Preconditions + +Collect the following before finalizing a design. Ask concise questions for +missing information; do not invent authority, classification, or permissions. + +- Objective, deliverables, and success criteria. +- Expected input routes, scale, and source formats. +- Data classification, retention rules, and permitted environments. +- External-service, network, rate-limit, and budget constraints. +- Operator availability, approval authority, and standing rules. +- Existing tools, orchestration harness constraints, and shared storage model. + +If the workflow will make network calls, change files, spend a material budget, +or act without immediate supervision, require an explicit approval model before +declaring the design ready. + +## Required Output Package + +Produce all of the following sections: + +1. **Workflow Design Brief**: objective, scope, deliverables, constraints, + success metrics, operator authority, and assumptions. +2. **Data Contracts**: item IDs, states, terminal outcomes, required fields, + source locators, canonical configuration, and writer ownership. +3. **Step Graph**: typed nodes, dependencies, reads, produces, gates, and + failure or recovery routes. +4. **Step Specifications**: one specification for every node in the graph. +5. **Verification Plan**: deterministic acceptance checks, fixtures, dry runs, + reconciliations, and readiness checks. +6. **Readiness Review**: unresolved decisions, risks, and a PASS, BLOCKED, or + NEEDS-REVISION verdict. + +## Procedure + +### 1. Establish Scope and Authority + +Classify the request as design, revision, or review. State whether the proposed +workflow is attended, unattended-capable, or not yet authorized to run. + +For unattended-capable work, identify: + +- The exact actions that may proceed without an operator. +- Conditions that force a stop or decision gate. +- Command, tool, write, and network restrictions. +- Timeout, escalation, and recovery rules for background work. + +Express standing authority as a rule over conditions, not a list of hoped-for +steps. For example: continue until a quality check fails, a budget cap is met, +or a blocking gate is due. + +### 2. Define the Success Contract + +Write the outcome before writing the process. Each success metric must be +operational: name the stage, numerator, denominator, data source, and check +that computes it. + +| Metric | Stage | Numerator | Denominator | Evidence and check | +|---|---|---|---|---| +| Accepted-item rate | quality gate | accepted items | evaluated items | state ledger; `verify-states` | + +Do not use a metric that cannot be calculated from planned records. Define +known limits and assumptions separately from acceptance criteria. + +### 3. Model Items and Data Contracts + +For every way an item enters the workflow, define an ID grammar, source locator, +initial state, and owner. Keep processing-request state separate from the state +of the underlying item. + +Define a single state machine with ordered states and explicit terminal states. +Include every exit route, including rejected, deferred by budget, deferred by +operator, unavailable, and failed. Never reuse a cancelled ID. + +For each machine-read field, specify allowed values or an explicit `not_stated` +sentinel. Name one authoritative source for each fact and one writer for every +shared file or column. + +| Contract | Required design decision | +|---|---| +| IDs | Grammar and minting rule for each entry route | +| States | Allowed transitions, terminal states, and failure codes | +| Locators | Deterministic source reference for each source format | +| Configuration | One canonical file for caps, thresholds, and vocabularies | +| Events | Required fields for each event type, validated when emitted | +| Ownership | Named writer, reader, and lock or atomic-write strategy | + +### 4. Draw the Typed Step Graph + +Represent the workflow as nodes and edges before drafting detailed prose. Each +node lists its reads, produces, required decisions, and deterministic closure +check. Each edge names the produced artifact or decision it carries. + +```text +intake -> normalize -> quality_gate -> operator_gate -> deliver -> close_out +``` + +Check the graph for: + +- A producer for every value a step reads. +- A terminal route for every item. +- No work that depends on a gate decision running before the gate. +- No concurrent writers to the same output. +- A recovery or stop route for each external dependency. + +### 5. Specify Each Step + +Use this template for every node, including gates and close-out: + +```markdown +### Step: - + +**Goal:** +**Reads:** +**Produces:** +**Consumes decisions:** +**Volume:** +**Agents:** +**Network:** +**Sub-steps:** +**Failure rule:** +**Evidence location:** +**Time estimate:** +**Done when:** `` +``` + +Keep each rule in one canonical location. Generate restated briefs or kickoff +materials from that source instead of manually copying requirements. + +### 6. Design Agents, External Calls, and Gates + +Add execution controls only when the workflow needs them. + +For sub-agents, define a bounded work unit, model, deadline, concurrency cap, +one owner per item, and one writer per output. Use a dispatch ledger with a +separate record for prepared, launched, and completed work. Count active agents +from the ledger, not from chat history. + +For external services, use one queue-owning client per service. It must own +ordering, rate limits, retries, budget enforcement, raw-response retention, and +event logging. Record refusal and wait events as well as successful sends. + +For each operator gate, present two to four genuine options, consequences for +cost, time, coverage, and quality, one recommendation, a blocking flag, and an +evidence path. Record the question, decision, and resulting configuration. + +### 7. Define Verification and Readiness Checks + +Prefer deterministic checks over judgment-only review. Give workers the same +verifier that the orchestrator will apply, and rerun it after every repair. + +Plan tests for: + +- State transitions, terminal statuses, and numeric caps. +- External vocabulary mappings and source-locator rules. +- Concurrent writes, locks, timeouts, and recovery paths. +- Failure policies, retry boundaries, and budget stops. +- Known-good and known-bad fixtures for each gate. +- Reconciliation of expected items, disk artifacts, state records, and events. + +Dry-run each step on a small representative slice before a live run. Freeze the +specification and configuration versions or hashes at run start; record later +changes as amendments with affected artifacts and rechecks. + +### 8. Design the Run Record and Close-Out + +Define event types before choosing time or cost metrics. At minimum, distinguish +active work, operator wait, permission wait, rate-limit wait, session pause, and +agent activity. Validate events when written, not after an append-only record +has accumulated invalid data. + +Classify every artifact as `record` or `scratch`. Before cleanup, promote every +cited brief, gate decision, exception, repair note, and evidence artifact into +the record area. Produce one machine-readable carry-forward list with item, +owner, and durable evidence path. + +## Review Mode + +When reviewing an existing design, report findings before proposing a redesign. +For each finding, state the affected step or contract, evidence, impact, and +smallest corrective change. Flag at least these defects when present: + +- A value is read but has no producer. +- An item route has no ID, locator, terminal status, or owner. +- A gate is bypassed by downstream work. +- A shared file has multiple writers or no atomic-write strategy. +- A metric lacks a numerator, denominator, or evidence source. +- A failure policy relies on an agent guessing what to do. +- A cited artifact can be deleted as scratch. + +## Verification + +Before returning the design package, confirm: + +- [ ] Every item route has an ID form, source locator, and terminal status. +- [ ] The state machine and failure codes are declared once. +- [ ] Every graph read has a named producer and every gate dependency is valid. +- [ ] Each step has bounded inputs, outputs, owner, failure rule, and done-when check. +- [ ] Network, write, budget, and operator authority rules are explicit where needed. +- [ ] Verification includes fixtures, reconciliation, and a small-slice dry run. +- [ ] Record artifacts are protected from scratch cleanup. +- [ ] Missing authority or material assumptions produce BLOCKED or NEEDS-REVISION, not an invented approval. + +## Output Template + +```markdown +## Summary + + +## Workflow Design Brief + + +## Data Contracts + + +## Step Graph + + +## Step Specifications + + +## Verification Plan + + +## Readiness Review + +``` + +## Common Failure Modes + +| Failure | Smallest corrective change | +|---|---| +| Agents infer missing fields | Add an allowed-value set and `not_stated` sentinel. | +| Work starts before approval | Make the gate decision a required graph input. | +| Shared records diverge | Assign one writer and add atomic writes plus reconciliation. | +| Budget or rate limit is exceeded | Put the cap and wait behavior in the queue-owning client. | +| A repair invalidates downstream work | List consumers and regenerate each affected artifact. | +| A workflow cannot explain a delay | Emit start and end events for work, waits, pauses, and agents. | + +## Related Patterns + +- [pattern-router](../pattern-router/SKILL.md) - Select this skill when a request needs workflow design or review. +- [test-generation](../../test-generation/SKILL.md) - Add implementation tests after the workflow design is accepted. diff --git a/.agents/skills/meta/agentic-workflow-design/tests/test-cases.yml b/.agents/skills/meta/agentic-workflow-design/tests/test-cases.yml new file mode 100644 index 00000000..42d85292 --- /dev/null +++ b/.agents/skills/meta/agentic-workflow-design/tests/test-cases.yml @@ -0,0 +1,90 @@ +suite: + pattern_id: agentic-workflow-design + pattern_version: "1.0.0" + description: Expected design-package behaviors for agentic workflow design. + +test_cases: + - id: missing-terminal-route + name: Flags items without a terminal route + description: A workflow design must identify the absent terminal status instead of treating all work as successful. + input: + type: literal + content: | + ## Summary + NEEDS-REVISION + + ## Readiness Review + Finding: the intake route has no terminal status for items deferred when the budget is exhausted. + Corrective action: add a `deferred_by_budget` terminal state and reconciliation check. + assertions: + - type: contains + pattern: "NEEDS-REVISION" + - type: contains + pattern: "deferred_by_budget" + - type: contains + pattern: "terminal state" + + - id: gate-dependency + name: Prevents work from bypassing an operator gate + description: A downstream step cannot run until the required decision is present. + input: + type: literal + content: | + ## Summary + BLOCKED pending scope approval. + + ## Step Graph + `dispatch` consumes `scope_approval`, produced by `scope_gate`. + `dispatch` must not run before `scope_gate` records the decision. + + ## Readiness Review + Add `scope_approval` as a required graph input to `dispatch`. + assertions: + - type: contains + pattern: "BLOCKED" + - type: contains + pattern: "must not run before" + - type: contains + pattern: "required graph input" + + - id: measurable-success-contract + name: Requires operational success metrics + description: The design names a numerator, denominator, evidence source, and deterministic check. + input: + type: literal + content: | + ## Workflow Design Brief + | Metric | Stage | Numerator | Denominator | Evidence and check | + |---|---|---|---|---| + | Accepted-item rate | quality gate | accepted items | evaluated items | state ledger; `verify-states` | + + ## Verification Plan + Run `verify-states` and fail when an evaluated item lacks a terminal status. + assertions: + - type: contains + pattern: "Numerator" + - type: contains + pattern: "Denominator" + - type: contains + pattern: "state ledger" + - type: contains + pattern: "verify-states" + + - id: no-invented-authority + name: Blocks missing execution authority + description: The skill must not invent permissions for unattended network or write operations. + input: + type: literal + content: | + ## Summary + BLOCKED: unattended execution authority is not defined. + + ## Readiness Review + Obtain an approved network and write policy before permitting the workflow to run without an operator. + assertions: + - type: contains + pattern: "BLOCKED" + - type: contains + pattern: "network and write policy" + - type: not_contains + pattern: "approval assumed" diff --git a/CATALOG.md b/CATALOG.md index dcc3e19f..0dfb4982 100644 --- a/CATALOG.md +++ b/CATALOG.md @@ -2,7 +2,7 @@ > **Generated file — do not edit by hand.** Run `make generate` (regenerates INDEX.yaml + CATALOG.md). Source of truth is each pattern's `SKILL.md`/`AGENTS.md` frontmatter. -41 patterns — 30 skills, 3 prompts, 3 agents, 4 workflows, 1 lessons. +42 patterns — 31 skills, 3 prompts, 3 agents, 4 workflows, 1 lessons. For machine routing use the [`pattern-router`](.agents/skills/meta/pattern-router/SKILL.md) skill + `scripts/route_patterns.py`; this catalog is the human view. @@ -10,6 +10,7 @@ For machine routing use the [`pattern-router`](.agents/skills/meta/pattern-route | Pattern | Type | Status | Tasks | Consumes | Produces | |---------|------|--------|-------|----------|----------| +| [`agentic-workflow-design`](skills/meta/agentic-workflow-design/SKILL.md) | skill | experimental | analyze, orchestrate, plan, review | documentation | documentation | | [`example-agentic-session`](lessons-learned/example-agentic-session/SKILL.md) | lesson | experimental | analyze | documentation | documentation | | [`pattern-router`](skills/meta/pattern-router/SKILL.md) | skill | experimental | discover, orchestrate | — | — | diff --git a/INDEX.yaml b/INDEX.yaml index b6c47451..439bed58 100644 --- a/INDEX.yaml +++ b/INDEX.yaml @@ -69,6 +69,31 @@ patterns: - ROI framing without hype - value framing priority: 55 + - path: skills/meta/agentic-workflow-design/SKILL.md + id: agentic-workflow-design + title: Agentic Workflow Design + type: skill + status: experimental + categories: + - development + - testing + - documentation + collection: meta + routing: + task_types: + - analyze + - orchestrate + - plan + - review + input_artifacts: + - documentation + output_artifacts: + - documentation + aliases: + - agent workflow architecture + - multi-agent pipeline design + - orchestration plan + priority: 70 - path: skills/communications/artifact-brief/SKILL.md id: artifact-brief title: Artifact Brief @@ -898,6 +923,7 @@ categories: - security-scan-review - untrusted-input-boundary-review development: + - agentic-workflow-design - general-agent - implementation-plan - issue-to-merge-request @@ -921,11 +947,13 @@ categories: - security-scan-review - untrusted-input-boundary-review testing: + - agentic-workflow-design - issue-to-merge-request - qa-round - qa-workflow - test-generation documentation: + - agentic-workflow-design - compliance-claim-checker - documentation-agent - documentation-review @@ -988,6 +1016,7 @@ collections: - safe-shell-script-author - test-generation meta: + - agentic-workflow-design - example-agentic-session - pattern-router security: @@ -1007,6 +1036,7 @@ task_types: - accessibility-review - agentic-actions-auditor - agentic-value-analyst + - agentic-workflow-design - backdoor-review - compliance-claim-checker - dependency-analysis @@ -1042,12 +1072,14 @@ task_types: - federal-service-blueprint - pattern-router orchestrate: + - agentic-workflow-design - design-artifact - issue-to-merge-request - pattern-router - qa-workflow - security-scan-review plan: + - agentic-workflow-design - artifact-brief - federal-service-blueprint - general-agent @@ -1065,6 +1097,7 @@ task_types: review: - accessibility-review - agentic-actions-auditor + - agentic-workflow-design - artifact-qa - backdoor-review - compliance-claim-checker @@ -1101,6 +1134,7 @@ output_artifacts: - artifact-brief documentation: - agentic-value-analyst + - agentic-workflow-design - documentation-agent - example-agentic-session - federal-service-blueprint @@ -1168,8 +1202,8 @@ output_artifacts: web-prototype: - uswds-prototype stats: - total_patterns: 41 - skills: 30 + total_patterns: 42 + skills: 31 prompts: 3 agents: 3 workflows: 4