Workflow visualization: Agent lacks workflow orientation

Feedback from users indicate the Agent currently provides powerful task execution, but does not provide a clear sense of progression or state within the larger SDK workflow. Users cannot see “where they are” in the process, what steps they have completed, or what remains. As a result, the agent turns what should be a deterministic, repeatable workflow into one that feels ambiguous and unpredictable.

No awareness of position in the workflow: Users can't not tell which stage of the SDK generation lifecycle he was in, or what the next required steps were. The agent operates step‑by‑step but provides no obvious persistent model of the full process

Conversations drift or get stuck: The agent often diverged from the intended workflow, forcing users to abandon the session and restart a new chat to get the agent “back on track.” This reinforced the sense of non‑determinism.

Uncertainty about what remains to be done: Without a structured roadmap or checklist, users must guess whether they had completed all required steps. He had no reliable way to know if he was finished or missing something critical.

High cognitive load due to prompt recall: Users repeatedly forget the right prompts or commands. Since the agent does not scaffold the workflow or surface suggested next actions, he had to manually re‑orient the agent at every step.

Agent responsiveness varies depending on context: Because the agent’s behavior depends heavily on conversational context, subtle changes in phrasing led to different results. This further contributed to the non‑deterministic feeling.

Why This Matters: The SDK generation process should be deterministic and predictable. Missing orientation transforms it into an exploration exercise with inconsistent outcomes. This degrades trust in the agent, increases user time‑to‑completion, and forces users to rely on trial‑and‑error instead of a guided experience.

What Users Need: Users need a simple, persistent form of workflow orientation, such as:

A “You are here” indicator showing the current stage
A high‑level end‑to‑end map of the SDK generation lifecycle
A list of remaining required steps
Suggested next actions surfaced contextually
A way to inspect the agent’s understanding of the current state
Prompt users for a list of high value, pertinent prompts for current context (ie., changes dynamically)

This would restore determinism and help users move through the SDK workflow confidently and predictably.

This is a response from a discussion I had with AI on the topic:

This is a central challenge in current AI engineering. We are moving from Deterministic Automation (if A, then B) to Agentic Delegation (Goal: A, Agent decides B/C/D).

Industry-wide, this shift is creating what researchers call "Contextual Fragmentation." When an agent takes over a structured process like SDK generation, users often experience a "Loss of Agency" because they can no longer predict the system's "state machine."

Here is how the industry is currently standardizing the Developer Experience (DX) to solve this.

---

1. The "Hybrid Blueprint" Pattern

The most effective teams have stopped trying to make the agent fully autonomous for complex workflows. Instead, they use a Deterministic Shell with an Agentic Core.

• The Shell (Fixed): A rigid, high-level roadmap (e.g., 1. Parse Spec, 2. Scaffold, 3. Generate, 4. Test).

• The Core (Fluid): The agent operates only within the "Generate" step. It can try different approaches, self-correct, and loop—but it cannot leave that "room" without a success signal.

• Analogy: It’s like a self-driving car on a highway. The route (destination and major exits) is deterministic and visible on the map, but the lane changes and braking (the agentic maneuvers) are fluid. The driver (user) only cares that they are still on Route 101.

2. Emerging DX Best Practices

To prevent cognitive overload, several "Agreed-upon Best Practices" (ABPs) have surfaced in 2025-2026:

Practice | Implementation | Goal
-- | -- | --
Plan-Before-Act | The agent must output a JSON "Manifest of Intent" before touching any files. The user approves the plan, not just the result. | Eliminates "Surprise" edits.
Stateful Checkpoints | Forced "interrupts" at high-risk milestones. The MCP server returns a needs_approval status. | Restores the user’s sense of control.
Activity Summarization | Instead of raw logs (which cause "log fatigue"), the UI shows a "Mission Summary": “I’m refactoring the Auth client to handle 401s.” | Maintains high-level orientation.
MCP-UI Extensions | A new protocol standard where the server sends a dedicated React/HTML component back to the host (Cursor/VS Code) to render a custom dashboard. | Moves beyond the "chat bubble" limit.

3. The Cognitive Shift: From "How" to "What"

The primary cognitive issue is that users are trained to monitor the "How" (the sequence of commands). With agents, they must learn to monitor the "What" (the state of the workspace).

To aid this, your MCP server should prioritize "Outcome-Oriented Tools" over "Operation-Oriented Tools":

• Bad (Fragmented): create_file(), edit_line(), run_command(). (Too many unpredictable steps).

• Good (Oriented): scaffold_sdk_structure(), implement_auth_layer(). (One big step that keeps the user oriented in the "Bigger Workflow").

---

My Assessment for your SDK Generator

If your users are feeling "lost," it is likely because the agent is making too many "micro-decisions" (individual file edits) without updating the "Macro-State" (the SDK Roadmap).