deck_orchestrator_executor_workflow

Question 1

AI Coding Agent

Answer 1

A tool where you describe what you want in plain English and an AI writes, runs, and debugs the code for you. Examples include Cursor, Claude Code, and GitHub Copilot.

Question 2

Cursor

Answer 2

An AI-powered code editor based on VS Code. You type instructions in plain English and it writes code, runs CLI commands, and deploys resources directly in your project.

Question 3

Claude Code

Answer 3

Anthropic’s command-line AI coding tool. You type instructions in your terminal and Claude writes and edits files directly. Supports a CLAUDE.md file for persistent project rules.

Question 4

Orchestrator

Answer 4

The AI that plans, tracks progress, generates instructions, and maintains documentation. It is the brain of the workflow. In this system Claude plays the orchestrator role.

Question 5

Executor

Answer 5

The AI that writes code, runs commands, and deploys resources. It is the hands of the workflow. It has no memory between sessions and relies entirely on instructions given to it each time. In this system Cursor plays the executor role.

Question 6

Operator

Answer 6

The human in the middle who copies instructions from the orchestrator to the executor and pastes results back. Makes architectural decisions, reviews changes, and manages communication.

Question 7

Orchestrator-Executor Pattern

Answer 7

A two-AI workflow where one AI plans and tracks (orchestrator) and another AI builds and deploys (executor). The human operator bridges them by copying instructions and results back and forth.

Question 8

Round-Trip

Answer 8

One complete cycle of the workflow: orchestrator generates instructions, operator pastes them into executor, executor runs them, operator pastes results back, orchestrator updates the playbook. Every unit of work follows this loop.

Question 9

Playbook

Answer 9

A living markdown document that serves as the single source of truth for a project. Contains environment details, task queue, deployed inventory, architecture notes, and lessons learned. Updated after every round-trip.

Question 10

Playbook Template

Answer 10

A blank standardized structure that the orchestrator fills in when a new project starts. Ensures every project has the same sections and nothing gets missed. Like an SOP template you reuse across projects.

Question 11

Environment Reference

Answer 11

Section of the playbook that lists every AWS resource ID, ARN, region, account ID, table name, and endpoint needed for the project. Critical because the executor has no memory and cannot look these up on its own.

Question 12

Current Queue

Answer 12

Section of the playbook that lists tasks in priority order. When the operator says next step the orchestrator reads this section, finds the first incomplete item, and generates instructions for it.

Question 13

Queue Item

Answer 13

A single task in the current queue with a status, description, dependencies, and estimated round-trips. Statuses are Not Started, In Progress, or Complete.

Question 14

Deployed Component Inventory

Answer 14

Section of the playbook tracking every resource that has been built, organized by project phase. Each component shows its type, status, and any relevant notes like resource IDs or error history.

Question 15

Deployed Items by Path

Answer 15

Section of the playbook grouping all deployed resources by the feature or data path they belong to. Gives a quick visual of what exists for each logical piece of the system.

Question 16

Architecture Notes

Answer 16

Section of the playbook describing how all components wire together. Often includes ASCII diagrams showing data flow, key design decisions, and integration points.

Question 17

Cursor Instruction Set

Answer 17

A fully self-contained markdown document generated by the orchestrator and given to the executor. Contains everything the executor needs: overview, environment IDs, step-by-step commands, verification steps, and relevant lessons learned.

Question 18

Self-Contained Instructions

Answer 18

Every instruction set must include ALL resource IDs, ARNs, account numbers, and context because the executor has zero memory between sessions. If it is not in the instructions the executor does not know it.

Question 19

Verification Step

Answer 19

A required step at the end of every instruction set where the executor confirms its own work. Examples include running a test invocation, checking a deployment status, or verifying a resource exists.

Question 20

Lessons Learned

Answer 20

A running list of mistakes and gotchas discovered during projects. Each entry documents what went wrong and the rule to prevent it next time. The most important concept in this workflow because it creates compounding improvement.

Question 21

Lessons Learned Master Document

Answer 21

A file that accumulates lessons from ALL past projects. Split into two parts: Part 1 for architecture and design lessons (orchestrator only) and Part 2 for deployment lessons (sent to executor). Grows with every project.

Question 22

Part 1: Architecture and Design Lessons

Answer 22

Strategic and design-level findings that inform the orchestrator’s planning decisions. Examples include latency comparisons between Bedrock patterns or voice vs chat attribute differences. Never sent to the executor.

Question 23

Part 2: Cursor Deployment Lessons

Answer 23

Tactical deployment gotchas that prevent the executor from repeating known mistakes. Examples include Git Bash path issues, Lambda environment variable replacement behavior, or CloudFront cache invalidation requirements. Sent to executor in first instruction set.

Question 24

First Instruction Set Rule

Answer 24

The very first instruction set sent to the executor in any new session must include the FULL Part 2 deployment lessons from the master document. This ensures the executor starts every project fully informed of all known gotchas.

Question 25

Subsequent Instruction Sets

Answer 25

After the first instruction set, only lessons relevant to the current task are included. No need to repeat the full list every time.

Question 26

Compounding Improvement Loop

Answer 26

The core concept that makes this workflow powerful. Every mistake is documented as a lesson learned, fed back into future instructions, and never repeated. Over many projects the AI makes fewer and fewer errors.

Question 27

Commit and Push Step

Answer 27

A required step at the end of every successful round-trip where the executor commits code to Git with a standardized message format: ProjectName followed by a brief task description.

Question 28

Rollback Instructions

Answer 28

For risky changes, the instruction set includes steps to undo the change if something goes wrong. Part of the risk-averse implementation principle.

Question 29

Stakeholder Documentation

Answer 29

Polished Word or Excel documents generated by the orchestrator for bosses or clients. Professional tone, focused on outcomes not implementation details. Separate from the technical playbook.

Question 30

Technical Documentation

Answer 30

Markdown documents like the playbook, cursor instructions, and architecture notes. Casual and direct tone meant for the engineering team.

Question 31

Session

Answer 31

A single chat conversation with the orchestrator. Each new chat is a new session. The playbook carries state across sessions by being pasted in at the start.

Question 32

Context Window

Answer 32

The amount of text an AI can see and process at once. The playbook must fit within this window. This is why it must stay organized and concise rather than growing endlessly.

Question 33

No Memory Between Sessions

Answer 33

A critical constraint of AI coding agents. The executor forgets everything after each session ends. The playbook and self-contained instructions solve this problem by providing all necessary context fresh each time.

Question 34

CLAUDE.md

Answer 34

A special file in Claude Code projects that acts as a persistent rules and lessons learned file. Claude reads it automatically at the start of every session. The Claude Code equivalent of pasting a playbook.

Question 35

Prompt Engineering (Agent Context)

Answer 35

The practice of writing structured instructions that tell an AI agent how to behave, what rules to follow, and what patterns to use. In this workflow the playbook and instruction format are the prompt.

Question 36

System Prompt vs User Prompt

Answer 36

System prompt sets the AI's role and rules for the entire session. User prompt is the specific task or question. The playbook acts as a system prompt and each next step request is a user prompt.

Question 37

Naming Convention

Answer 37

A standardized pattern for naming resources. In this workflow it is typically project-environment-component. Example: demo-profile-manager-dev-get-profiles. Keeps resources organized and identifiable.

Question 38

Phased Deployment

Answer 38

Breaking a project into sequential phases where each phase builds on the last. Example: Phase 1 is infrastructure and backend, Phase 2 is frontend, Phase 3 is integration. Reduces risk and keeps work manageable.

Question 39

Copy-Paste Ready

Answer 39

A requirement that every command in a Cursor instruction set can be copied and pasted directly into a terminal or editor without modification. No fill-in-the-blank placeholders unless absolutely unavoidable.

Question 40

Risk-Averse Implementation

Answer 40

A core principle of the workflow: backup before changes, include rollback instructions, deploy one step at a time, and verify after each step. Mistakes in production are expensive.

Question 41

Deferred Items

Answer 41

Tasks intentionally pushed to later in the project. Documented in the playbook with what is blocking them and what needs to be built so an engineer can pick them up when ready.

Question 42

Still Needed Section

Answer 42

Section of the playbook tracking blockers and missing information from the client or team. Keeps everyone aware of what is holding up progress.

Question 43

API and Integration Inventory

Answer 43

Section of the playbook documenting every external API the project integrates with, its format, whether sample data is available, and its current status like mocked, live, or blocked.

Question 44

VUI and Requirements Document Inventory

Answer 44

Section of the playbook tracking source documents like voice user interface specs, requirements docs, and architecture diagrams with their version and analysis status.

Question 45

Structured Response from Executor

Answer 45

When the executor finishes a task it reports back with a standardized format: status, summary of what was done, any lessons learned, resource IDs created, and errors encountered. Makes it easy for the orchestrator to parse and update the playbook.

Question 46

Documentation as First-Class Deliverable

Answer 46

A core principle that documentation is not an afterthought. The playbook is maintained in real time, stakeholder docs are generated at milestones, and every deployed resource is tracked.

Question 47

Orchestrator Internal Use Only

Answer 47

Some information is only for the orchestrator's planning and decision-making. Part 1 architecture lessons fall into this category. The executor never sees them because they are strategic not tactical.

Question 48

Adapting the Workflow Without CLI

Answer 48

If you do not have direct CLI access you replace the executor step with however you normally deploy. The orchestrator still generates the code and config, you just deploy through console, pipeline, or DevOps handoff instead of CLI commands.

Question 49

Three Layers of the Workflow

Answer 49

Layer 1 is planning and orchestration which needs no CLI. Layer 2 is code and config generation which needs no CLI. Layer 3 is execution which needs CLI or an equivalent deployment method. Only Layer 3 changes based on your access.