Designing agentic workflows: supplementary commands and pressure valves

Source: Dev.to

Sure thing! To give you the best possible cleanup, could you please paste the markdown text you’d like me to tidy up? Once I have the actual content, I can format headings, lists, code blocks, links, and any other elements so everything looks clean and consistent.

## Designing Agentic Workflows

### Topics Covered
- **Designing agentic workflows: where agents fail and where we fail**
- **Designing agentic workflows: a practical example**
- **Designing agentic workflows: the core loop**

---

The Core Execution Loop

1. Define gates
2. Plan one bounded task
3. Implement exactly one task
4. Repeat until all gates pass
5. Run cleanup

This loop is the default path. Most issues go straight into it.

The supplementary commands do not replace the loop; they address two pressures:

• Context degradation
• Intent drift

If neither pressure is present, skip them. If either appears, use them deliberately.

/wf-summarise

Context Degradation & the “50 % Rule”

• Long sessions degrade gradually: repeated corrections appear, previously rejected approaches re‑appear, architectural decisions get lost, and small logic mistakes creep in.
• The core loop assumes sessions are disposable.

The “50 % Rule”

• A heuristic, not a hard stop.
• Finish the current bounded unit of work and exit before:
  1. Automatic compaction occurs,
  2. Corrections begin looping, or
  3. State reconstruction becomes unreliable.

Compaction compresses earlier reasoning; each compression step discards detail, and after several rounds subtle constraints disappear.

/wf-summarise   # prevents that erosion

What /wf-summarise does

When you decide to reset:

1. Finish the current task or step.
2. Run /wf-summarise.

It generates:

• A structured temporary hand‑over document
• A phase‑aware continuation prompt for the next session

Handover captures

• Issue objective and scope
• Gate status
• Completed tasks
• Remaining work
• Key architectural decisions
• Relevant constraints
• Important discoveries

Handover documents are temporary – they bridge sessions, not commits.

Example continuation block

---
You are resuming work on `issue-47-user-validation`.

Before proceeding:
1. Read `.agents/issues/issue-47-user-validation/handover.md`
2. Confirm gate status
3. Identify next task

Current phase: Implementation  
Tasks completed: task‑1, task‑2  
Tasks remaining: task‑3, task‑4
---

Paste the block into a fresh session together with the hand‑over document. The new session reconstructs state from the artifacts and the hand‑over. Once alignment is confirmed, discard the hand‑over.

Typical Session States

/wf-summarise is a pressure valve for context. It makes resets controlled rather than lossy.

Preparing to Enter the Core Loop

1. Start with an issue that has verifiable success criteria.

   • Most teams already have issues from GitHub, JIRA, product specs, or bug reports.

2. If the issue lacks clear criteria, enrich it first using \wf-issue-plan.

   • This command checks for investigation, design, or ADR gaps and suggests the appropriate on‑demand command before proceeding.

Litmus Test

Can I define verification gates for this right now?

These commands make intent explicit before implementation begins.

/wf-investigate

When to use

• The issue description is vague.
• You are debugging unfamiliar code.
• You need to explore the problem before you can define “fixed.”

When it’s not needed

• The bug‑fix is clear and the root cause is known.
• You are working on a familiar codebase with an obvious implementation path.
• You can immediately define what “done” looks like.

Example

A bug report says, “Authentication sometimes fails.”
“Sometimes” is not verifiable.

Investigation might reveal:

• The failure occurs when a token expires within a 5‑second race window and only affects a specific middleware branch.

From that you can define concrete acceptance criteria, e.g.:

• expired_token_within_grace_period_rejected
• valid_token_within_window_accepted

If you cannot define “done,” you don’t yet understand the problem well enough.

/wf-investigate

/wf-design

When to use

• Introducing new interfaces, changing public contracts, or adding cross‑cutting abstractions.

When it’s not needed

• Internal implementation details that don’t affect contracts.
• Small behavioral changes in existing functions.
• Refactoring that preserves existing interfaces.

What it produces

• Proposed interfaces, data shapes, interaction patterns, and trade‑offs.
• No implementation – a human review occurs before any code is written.

Example

• Adding a new API endpoint → define request/response schema, error contract, and versioning expectations.

Design questions answered

• What are we building for this issue?

It prevents structural drift during implementation. Design is issue‑scoped.

/wf-design

/wf-adr

Use when:

• The decision introduces or rejects a dependency.
• The decision changes architectural direction, constrains future work, or is likely to be revisited if undocumented.

Not needed for:

• Implementation choices (e.g., sort algorithm, loop structure, data structure).
• Local design patterns within a module.
• Tooling or developer‑experience improvements.
• Style or convention decisions.

Reserved for:

• Introducing or rejecting dependencies (libraries, services, infrastructure).
• Choosing system‑wide patterns (API style, auth approach, data flow).
• Organizational architecture (monorepo structure, deployment strategy).

The purpose of /wf-adr is not to let the model decide; it records human‑made architectural decisions for future reference.

/wf-adr

Decision‑Space Workflow Overview

The command produces:

• Context
• Explicit options
• Trade‑offs
• Consequences of each option

It does not select the final approach. The output is presented to the human, who reviews it with their team. The team then:

1. Makes the decision.
2. Documents it as an ADR (Architecture Decision Record).
3. Treats the documented ADR as a durable constraint that future planning must respect.

Example: Choosing a JWT Implementation

When deciding between native crypto APIs or a third‑party JWT library, the agent can enumerate:

The agent does not choose; the team decides, and the ADR records that decision.

ADR Answers

Core Loop (Default Process)

Define gates
Plan bounded task
Implement exactly one task
Repeat
Cleanup

The core loop enforces bounded implementation.

Supplementary Commands (Situational)

These commands intervene before or during the core loop when pressure appears. They do not replace the loop; they keep it viable under complexity.

• If no pressure exists, skip them.
• If pressure appears, activate them deliberately.

The structure stays lean by default and expands only when necessary.