This project uses a multi-agent AI workflow so different tools can contribute where they are strongest instead of forcing one model to do everything.
Our current stack:
- Aider (ChatGPT) in terminal
- Claude in terminal
- Cursor IDE
- Markdown files for persistent instruction and context
- TODO files for task passing and state tracking
- Planned email-based prompting for asynchronous cross-agent handoff
The goal is to create a repeatable workflow where AI tools can:
- understand the project
- pick up where another tool left off
- leave clean instructions for the next tool
- stay aligned on architecture, priorities, and constraints
- reduce repeated explanation from the human operator
Each AI is treated like a specialized contributor.
Instead of asking one AI to do everything, we give each tool a role and let Markdown files act as the shared memory and coordination layer.
This makes the workflow feel less like isolated chat sessions and more like a lightweight AI team.
Primary use:
- code changes
- refactors
- debugging
- implementation help
- repository-aware editing
Strengths:
- practical coding help
- fast iteration
- direct file edits
- good at turning structured instructions into implementation steps
Best used for:
- applying scoped changes
- handling bugfixes
- implementing features from a written plan
- updating files based on TODO instructions
Primary use:
- architecture thinking
- system design
- product thinking
- UI/UX planning
- large feature decomposition
- technical writing and agent plans
Strengths:
- understanding bigger picture
- writing high-quality planning documents
- organizing messy ideas into systems
- outlining refactors and feature roadmaps
Best used for:
- drafting implementation plans
- writing design briefs
- generating agent instructions
- creating handoff docs for Aider or Cursor
Primary use:
- project-aware development
- fast code navigation
- inline AI edits
- file-by-file implementation
- human-in-the-loop coding
Strengths:
- best environment for editing and reviewing code visually
- easier to inspect project structure
- ideal for targeted implementation after planning is done
Best used for:
- executing plans written by Claude
- refining code generated by Aider
- reviewing diffs
- making UI changes
- working from TODOs and agent briefs
The system works because all tools communicate through files.
Instead of relying on memory from one terminal session, we store context in project documents.
Contains:
- what the app is
- current project goals
- stack overview
- important architecture decisions
- constraints
- coding standards
- business context
Purpose:
Gives every AI a baseline understanding of the project.
Contains:
- what is actively being worked on right now
- highest-priority feature or bug
- known blockers
- current decisions in progress
Purpose:
Prevents agents from drifting into unrelated work.
Contains:
- task backlog
- next steps
- task status
- ownership or suggested agent
- dependencies
Purpose:
Acts as the central work queue for humans and AIs.
Example structure:
# TODO
## In Progress
- [ ] Redesign quote detail page layout
- [ ] Add hide-from-quote toggle on quote items
## Ready for Aider
- [ ] Implement client info card white background
- [ ] Move logistics section toward bottom
## Ready for Claude
- [ ] Outline pull sheet system architecture
- [ ] Review quote page UX flow
## Ready for Cursor
- [ ] Refactor QuoteDetailPage layout
- [ ] Polish spacing for half-width screens
## Done
- [x] Add public quote route
- [x] Add OpenAPI interface support
AI/HANDOFF.md
Contains:
summary of what was just done
files changed
what still needs attention
warnings
suggested next AI/tool
Purpose:
This is the baton-pass file.
Whenever one AI finishes a meaningful chunk of work, it should leave a clean handoff for the next one.
AI/ARCHITECTURE.md
Contains:
system structure
module responsibilities
data flow
backend/frontend boundaries
important implementation rules
Purpose:
Helps prevent contradictory changes from different AIs.
AI/UX_GUIDES/...
Contains:
UX direction
visual priorities
page-specific design briefs
interaction rules
layout authority
Purpose:
Lets Claude define the design system and Cursor/Aider implement it consistently.
How the AIs Communicate
They do not communicate directly in real time.
They communicate by reading and writing structured project files.
That means:
Claude can write a feature plan into an .md file
Aider can read that plan and implement it
Cursor can review and refine the implementation
each tool can update TODOs and handoff notes for the next tool
This creates indirect but persistent communication.
Communication pattern
Claude -> Aider
Claude writes:
feature outline
implementation brief
acceptance criteria
risks
Aider reads that file and performs the code changes.
Aider -> Cursor
Aider updates:
what it changed
what failed
what needs visual cleanup
what should be reviewed manually
Cursor then opens the changed files and finishes or refines.
Cursor -> Claude
Cursor or the human updates:
pain points
unresolved architectural questions
UI inconsistencies
places needing redesign
Claude then creates the next planning doc.
Why Markdown Files Matter
Markdown files are the backbone of the system because they are:
readable by humans
readable by AIs
version-controlled
easy to diff
easy to organize by topic
persistent across sessions
Instead of repeating project context in every prompt, the AI can be told:
Read AI/PROJECT_CONTEXT.md, AI/CURRENT_FOCUS.md, and AI/TODO.md before acting.
That keeps prompts shorter and results more consistent.
TODO Files as Inter-Agent Memory
TODO files are not just reminders. They are active routing tools.
A good TODO file should answer:
what needs doing
why it matters
who should do it next
what files are involved
what blockers exist
This turns TODOs into operational instructions instead of vague notes.
Good TODO example
- [ ] Implement hide-from-quote toggle
- Route/component: `QuoteDetailPage.jsx`
- Behavior: eyeball icon beside product image
- State: toggle visible/hidden on public quote output
- Next tool: Aider
- Follow-up: Cursor to polish alignment and hover state
That is much more useful than:
- [ ] add quote toggle
Recommended Folder Structure
AI/
├── PROJECT_CONTEXT.md
├── CURRENT_FOCUS.md
├── TODO.md
├── HANDOFF.md
├── ARCHITECTURE.md
├── WORKFLOW.md
├── PROMPT_TEMPLATES.md
├── DECISIONS.md
├── FEATURES/
│ ├── PULL_SHEETS.md
│ ├── PUBLIC_QUOTE_VIEW.md
│ ├── GOODSHUFFLE_SYNC.md
│ └── API_ROADMAP.md
├── UXDesign/
│ ├── CLIENT_QUOTE_VIEW_UX_GUIDE.md
│ ├── QUOTE_DETAIL_REFACTOR.md
│ └── MOBILE_LAYOUT_GUIDE.md
└── HANDOFFS/
├── 2026-03-06-quote-layout.md
├── 2026-03-06-pull-sheets.md
└── 2026-03-07-api-plan.md
This keeps the AI system organized and prevents important context from being buried in chat history.
Human Operator Role
The human is still the orchestrator.
The human decides:
which AI gets the next task
when to promote a plan into implementation
when to reject low-quality output
when to update project direction
which file becomes the current source of truth
The system works best when the human keeps Markdown docs clean and current.
Planned Email-Based Prompting System
Goal
Use email as an asynchronous relay layer so one AI can effectively leave prompts or instructions for another AI outside the immediate coding session.
This is especially useful when:
switching machines
switching tools
preserving prompts cleanly
queueing work for later
separating planning from execution
Basic Concept
Each AI does not literally email another AI by itself in an autonomous closed loop.
Instead, email acts as a structured message transport and archival system.
A human or automation layer can send formatted prompts like:
feature requests
implementation briefs
review requests
handoff summaries
bug triage notes
These emails can then be copied into:
Claude terminal session
Aider terminal session
Cursor chat
issue tracker
local prompt files
Example email flow
1. Claude creates a planning brief
Subject:
[BADSHUFFLE][PLAN] Pull Sheets Feature Outline
Body:
purpose
problem statement
proposed UX
data model concerns
implementation phases
acceptance criteria
2. Human forwards or copies brief into Aider
Aider receives a very structured implementation task.
3. Aider performs code changes
Then a summary email is generated:
Subject:
[BADSHUFFLE][HANDOFF] Pull Sheets Backend Scaffolding Complete
Body:
files changed
what is working
what remains
known issues
next recommendation for Cursor
4. Cursor receives follow-up task
Cursor uses that summary to continue UI work.
Why Email Helps
Email adds:
timestamped history
searchable handoffs
async work queue
easy multi-device access
separation between planning and execution
possible future automation hooks
If structured correctly, email becomes a lightweight task bus.
Suggested Email Format
Subject pattern
[PROJECT][TYPE] Short description
Examples:
[BADSHUFFLE][PLAN] Client Quote UX Redesign
[BADSHUFFLE][TODO] Implement Hide From Quote Toggle
[BADSHUFFLE][HANDOFF] Public Quote API Completed
[BADSHUFFLE][REVIEW] QuoteDetailPage Layout Pass Needed
Body pattern
# Summary
Short explanation of purpose.
# Context
Relevant project or feature background.
# Objective
What needs to be done.
# Constraints
Important rules or things that must not change.
# Files
Relevant files or directories.
# Acceptance Criteria
What counts as done.
# Next Recommended Tool
Claude / Aider / Cursor
This format makes emails readable by both humans and AI tools.
Future Automation Vision
In a more advanced version of the system, email could be semi-automated.
Possible flow:
Claude writes a plan file
a script converts it into an email template
email is sent to a project inbox
another script sorts emails by tag
prompts are injected into the appropriate tool workflow
results are summarized back into Markdown files
This would turn the AI workflow into a semi-automated production pipeline.
Potential future components:
prompt inbox
email-to-markdown parser
markdown-to-email formatter
agent queue files
per-agent task folders
automatic handoff generation
daily status digest
Recommended Workflow
Planning phase
Use Claude to:
understand the feature
create an implementation brief
write architecture notes
define acceptance criteria
Outputs:
feature spec .md
TODO entries
handoff notes
Implementation phase
Use Aider to:
read the relevant .md files
modify the codebase
complete scoped tasks
update status and handoff docs
Outputs:
code changes
updated TODO state
implementation summary
Refinement phase
Use Cursor to:
inspect the code visually
clean up UI/UX
make final edits
run human-guided polish
Outputs:
refined code
reviewed diffs
better usability
Best Practices
1. Keep one source of truth
Do not scatter important context across random files. Put architecture in one place, current work in one place, and handoffs in one place.
2. Write for the next AI
Every note should assume another AI or human will read it later.
3. Prefer structured docs over huge prompts
A reusable Markdown file is better than rewriting the same context every session.
4. Separate planning from implementation
Claude should usually plan first. Aider and Cursor should usually execute second.
5. Update TODOs aggressively
If the TODO file is stale, the whole multi-agent system becomes unreliable.
6. Log decisions
If a decision is made once, write it into DECISIONS.md so future AIs do not revisit it blindly.
Example Real-World Flow
Feature: Pull Sheets
Claude
Writes:
AI/FEATURES/PULL_SHEETS.md
Includes:
problem definition
operational purpose
data requirements
workflow proposal
TODO updated
AI/TODO.md
- [ ] Implement pull sheets backend model
- Next tool: Aider
- [ ] Design pull sheet UI for warehouse crews
- Next tool: Claude
- [ ] Refine print layout and mobile readability
- Next tool: Cursor
Aider
Implements backend scaffolding and updates:
AI/HANDOFF.md
Implemented initial pull sheet model and order linkage.
Changed:
- server/routes/pullSheets.js
- server/models/PullSheet.js
Still needed:
- printable UI
- inventory grouping rules
- internal notes display
Next recommended tool:
Cursor
Cursor
Builds and polishes the interface.
That is the system working correctly.
Bottom Line
This AI system works by treating:
Claude as planner
Aider as implementer
Cursor as builder/refiner
Markdown as shared memory
TODO files as routing/state
Email as future asynchronous handoff transport
It is not about making the AIs magically talk to each other directly.
It is about building a repeatable structure where each one can inherit context, leave instructions, and continue the work of the others with minimal friction.
If you want, I can turn this into a tighter, more polished `WORKFLOW.md` plus separate `PROMPT_TEMPLATES.md` and `TODO_TEMPLATE.md` files.