Manager and Worker Markdown Manual
Download# Manager And Worker Markdown Manual
## Purpose
This document explains a general way to structure markdown instructions for a team-style agent setup.
The pattern separates two kinds of roles:
- a manager, who decides what should happen next
- a worker, staff member, employee, or team member, who performs the assigned work
The goal is to keep each role clear, prevent duplicated responsibility, and make the markdown files easy to load only when needed.
## Core Idea
Use separate instruction entrypoints for each role.
The manager should not perform the worker's tasks. The manager should interpret state, choose the next step, and give one clear instruction.
The worker should not redefine the plan unless live information makes the assigned task impossible or unsafe. The worker should execute the assigned task, report the result, and surface blockers clearly.
This creates a loop:
1. Manager gives one task.
2. Worker performs the task.
3. Worker reports state, completion, or blocker.
4. Manager decides the next task.
## Recommended Folder Structure
Use a structure like this:
```text
workflow/
manager/
WORKFLOW.md
worker/
WORKFLOW.md
manager_guides/
manager_rules.md
manager_playbooks.md
manager_reference.md
task_list.md
history_log.md
workflows/
workflow.md
feature-one.md
feature-two.md
feature-three.md
integrations/
external-system-one.md
external-system-two.md
runbooks/
stop-and-escalate-rules.md
execution-runbook.md
```
The exact names can change, but keep the separation clear:
- role entrypoints live in role folders
- manager-only guidance lives in a manager-only area
- shared execution workflows live in a shared workflow area
- integrations describe external systems or cross-system behavior
- runbooks describe operational procedures and safety rules
## Manager Entrypoint
The manager should have its own `WORKFLOW.md`.
It should define:
- the manager's role
- what the manager is allowed to do
- what the manager is not allowed to do
- how to load supporting docs
- how to route worker tasks
- how to handle blockers
- how to format instructions
Example structure:
```markdown
# WORKFLOW.md
## Role
You are the manager for this workflow.
You decide the next step.
You do not execute worker tasks directly.
You do not operate inside the application or system unless explicitly instructed.
When assigning work, address the worker by their role name.
## Loading Discipline
- Keep context light.
- Do not preload every workflow doc.
- Read only the document needed for the current decision.
- Use manager-only docs for management decisions.
- Use shared workflow docs only when product, process, or system behavior matters.
## Core Loop
1. Read the latest worker output.
2. Identify the current state.
3. Load only the needed guidance.
4. Decide the next action.
5. Send one instruction.
## Rules
- Give one task at a time.
- Do not bundle multiple tasks into one instruction.
- Do not perform the worker's work.
- Do not guess missing state.
- If blocked, ask one targeted question or reroute to the next valid preparatory task.
## Output Style
- short
- direct
- actionable
- addressed to the worker
```
## Worker Entrypoint
The worker should also have its own `WORKFLOW.md`.
It should define:
- the worker's role
- what work the worker is allowed to perform
- what the worker must not decide independently
- which shared docs the worker may load
- how the worker should report back
- when the worker should stop or escalate
Example structure:
```markdown
# WORKFLOW.md
## Role
You are the worker for this workflow.
You perform assigned tasks.
You do not act as the manager.
The manager decides the next step and routes your work.
When replying to the manager, address the manager by their role name.
## Loading Discipline
- Read only the docs required for the assigned task.
- Do not read manager-only docs.
- Use shared workflow docs as the source of operational truth.
## Core Rules
- Work only on the assigned task.
- Do not invent missing routes, IDs, files, data, or assumptions.
- If live state conflicts with the manager's instruction, report the conflict.
- If a management decision is required, stop and report it.
- Return exact state, result, blocker, or completion.
## Required Prep Order
1. Resolve the exact object, project, record, file, or target.
2. Confirm prerequisites required for the task.
3. Load the relevant workflow doc.
4. Execute the assigned task.
5. Report the result to the manager.
## Report Shape
- task:
- target:
- result:
- blocker:
- next required decision:
```
## Manager-Only Guides
Manager-only files should help the manager make decisions without turning the manager into the worker.
Useful manager files include:
```text
manager_guides/
manager_rules.md
manager_playbooks.md
manager_reference.md
task_list.md
history_log.md
```
`manager_rules.md` should contain the non-negotiable rules:
- do not execute worker tasks
- one instruction at a time
- do not assume success
- always use latest worker output
- stop on ambiguity
- distinguish decisions from execution
`manager_playbooks.md` should map common situations to next actions:
- missing intake
- blocked worker
- invalid target
- prerequisite failure
- task completed
- validation failed
- unknown state
- repeated waiting
`manager_reference.md` should be a small durable packet:
```markdown
# manager_reference.md
## Current Packet
- active work:
- current target:
- current stage:
- assigned worker task:
- known blockers:
- next required decision:
## Notes
- assumptions:
- decisions:
- open questions:
```
`task_list.md` can track queue state:
```markdown
# task_list.md
## Queued
- none
## In Progress
- none
## Blocked
- none
## Completed
- none
```
`history_log.md` should only store durable outcomes:
```markdown
# history_log.md
## Entries
- date:
- work item:
- decision:
- outcome:
- follow-up:
```
## Shared Workflow Docs
Shared workflow docs describe how actual work is done.
They should not contain manager-only coordination rules. They should describe the system, process, feature, or task behavior that a worker needs to execute correctly.
Use a router file when there are many workflow docs:
```text
workflows/
workflow.md
research.md
audit.md
execution.md
validation.md
```
The router file should say which detailed doc to load:
```markdown
# Workflow Router
Use this file only to route to the correct detailed workflow.
- If the task is research, read `research.md`.
- If the task is audit, read `audit.md`.
- If the task is execution, read `execution.md`.
- If the task is validation, read `validation.md`.
```
Each detailed workflow doc should define:
- role of that workflow
- inputs
- outputs
- required prerequisites
- exact process
- stop conditions
- success criteria
- related files, routes, records, or artifacts
## Integrations
Use integration docs for cross-system behavior.
These are useful when the worker needs to resolve identity or state across multiple systems.
Examples:
- how to match a project between two systems
- how to map an external record to an internal record
- how to treat upstream data
- which system is authoritative for which field
Integration docs should answer:
- what system is the source of truth
- what lookup order to use
- what to do when records conflict
- what must be reported back to the manager
## Runbooks
Runbooks are operational procedures.
Use them for repeatable process rules such as:
- execution steps
- validation steps
- escalation rules
- stop conditions
- recovery procedures
Runbooks should be practical and direct. They should not describe broad strategy unless that strategy changes what the worker should do.
## Role Boundaries
Keep this boundary strict.
The manager:
- receives reports
- interprets state
- chooses the next step
- asks targeted questions
- updates manager reference notes
- assigns one task at a time
The manager does not:
- perform worker tasks
- call operational APIs
- edit operational records
- invent missing state
- skip over blocker reports
- send large bundles of instructions
The worker:
- executes assigned tasks
- reads shared workflow docs
- operates inside the relevant system
- checks live state
- reports exact results
- reports conflicts and blockers
The worker does not:
- take over planning
- read manager-only docs
- hide uncertainty
- force work through a bad prerequisite
- make management decisions without reporting them
## Instruction Design
Manager instructions should be short and specific.
Use this shape:
```markdown
@worker_role
Do this specific task.
Use this target or packet:
- target:
- known constraints:
- required source doc:
Report:
- result:
- blocker:
- next required decision:
```
Avoid instructions that contain many independent tasks. If the worker has to complete several phases, assign the first phase only and wait for the report.
## Worker Report Design
Worker reports should be structured enough for the manager to route the next step.
Use this shape:
```markdown
@manager_role
Task:
Target:
Result:
Current state:
Blocker:
Next required decision:
Artifacts created:
```
The worker should not bury the blocker in prose. If something is blocked, it should be obvious.
## Loading Discipline
Both roles should avoid loading everything.
The manager loads:
- manager rules when discipline or boundaries matter
- manager playbooks when choosing next action
- manager reference when durable context matters
- shared workflows only when a decision depends on system behavior
The worker loads:
- only the workflow docs needed for the assigned task
- integration docs only when cross-system identity or state matters
- runbooks only when executing a procedure or evaluating a stop condition
This keeps the active context small and reduces accidental mixing of responsibilities.
## Source Of Truth Rules
Every workflow should define source-of-truth rules.
For example:
- which file or record is authoritative
- which state field controls routing
- which artifact is downstream and not authoritative
- which live state overrides planned state
- which missing information blocks work
Without this, the manager and worker will eventually make different assumptions.
## Stop And Escalate Rules
Create a shared stop-and-escalate runbook.
It should define when the worker must stop instead of guessing:
- target cannot be resolved
- multiple targets are plausible
- required data is missing
- live state conflicts with assignment
- prerequisite failed
- validation failed
- task requires a manager decision
- source of truth is unclear
Escalation should be short:
```markdown
@manager_role
Blocked.
Reason:
Evidence:
Decision needed:
```
## Implementation Steps
To implement this pattern in a new project:
1. Create the top-level `workflow/` folder.
2. Create one folder for the manager role and one folder for the worker role.
3. Add a `WORKFLOW.md` entrypoint to each role folder.
4. Create a manager-only guidance folder.
5. Create shared workflow docs for the actual work.
6. Add integration docs if the work crosses systems.
7. Add runbooks for execution, validation, and escalation.
8. Define source-of-truth rules.
9. Define how manager instructions should look.
10. Define how worker reports should look.
11. Test the loop manually with a simple task.
12. Tighten the docs where the roles overlap or become ambiguous.
## Minimal Starting Version
If you want the smallest useful setup, start with this:
```text
workflow/
manager/
WORKFLOW.md
worker/
WORKFLOW.md
manager_guides/
manager_rules.md
manager_playbooks.md
workflows/
workflow.md
task-process.md
runbooks/
stop-and-escalate-rules.md
```
This is enough to establish role separation, route tasks, execute work, and handle blockers.
## Quality Checklist
Before using the setup, check that:
- the manager cannot accidentally become the worker
- the worker knows when to stop and report
- manager-only docs are clearly marked
- shared workflow docs contain operational truth
- every role has one obvious entrypoint
- task instructions are one step at a time
- worker reports include result and blocker fields
- source-of-truth rules are explicit
- there is a clear escalation path
The structure works best when the docs are short, role-specific, and loaded only when needed.
