Designing agentic workflows: supplementary commands and pressure valves

Source: Dev.to

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:
  • Automatic compaction occurs,
  • Corrections begin looping, or
  • 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 handover 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 handover document. The new session reconstructs state from artifacts and the handover. Once alignment is confirmed, discard the handover.

---

Typical Session States

/wf-summarise is a pressure valve for context. It makes resets controlled instead of 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

Use when:

• The issue description is vague.
• You are debugging unfamiliar code.
• You need to explore before defining “fixed.”

Not needed for:

• Clear bug‑fixes with known root cause.
• Features in familiar code with an obvious implementation path.
• Changes where you can immediately define “done.”

Example:

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

Investigation might reveal:

• Failure occurs when token expiry falls within a 5‑second race window and only affects a specific middleware branch.

Now you can define concrete gates:

• expired_token_within_grace_period_rejected
• valid_token_within_window_accepted

If you cannot define “done,” you do not understand the problem well enough.

/wf-investigate

---

/wf-design

Use when:

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

Not needed for:

• 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 – human review happens before code.

Example:

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

Design answers:

• What are we building for this issue?

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

/wf-design

---

/wf-adr

Use when:

• The decision introduces or rejects a dependency, 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 makes the decision, documents it as an ADR (Architecture Decision Record), and the documented ADR becomes 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:

• Maintenance cost
• Upgrade surface area
• Operational risk

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

---

ADR Answers

• Clear behavioural adjustment with no structural impact → skip design.
• Implementation detail that does not affect boundaries → no ADR. |

---

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.