AGENTS.md is a project-level configuration file that provides AI coding assistants with complete project context, development principles, and operational guidelines. It follows the agents.md standard and works across Claude, Cursor, GitHub Copilot, and other AI tools.

What is Jimmy's Workflow?

Jimmy's Workflow is a four-phase validation system (PRE-FLIGHT, IMPLEMENT, VALIDATE, CHECKPOINT) designed to prevent AI hallucination and ensure robust implementation. Each phase has specific gates and confidence levels (HIGH/MEDIUM/LOW) that determine when human review is needed.

How do I set up multiple AI instances as a team?

Assign each AI instance a role card with identity, responsibilities, personality traits, and success criteria. Use file-based handoff protocols for coordination. Personality orchestration at the system prompt level produces measurably better results than treating AI instances as generic tools.

Writing Role Cards

A role card is a structured document that gives an AI instance its identity within a team. It defines what the instance does, how it approaches work, who it works with, and what success looks like.

Why role cards matter

Without a role card, an AI instance is a generalist. It will help with anything, in any style, with no particular standards. This is fine for one-off tasks. It breaks down when multiple instances need to produce work that fits together.

A role card solves this by constraining behaviour in useful ways:

Without role card	With role card
Generic helpful tone	Consistent personality across sessions
No awareness of team	Formats output for downstream consumers
Scope creep into other concerns	Stays within defined responsibilities
No quality baseline	Measurable success criteria
Reinvents approach each session	Stable working patterns

Anatomy of a role card

Every role card follows this structure. The template below can be copied and adapted for any role.

# Role Card: [Name] — [Short Description]

**Location:** [Machine or service where this instance runs]
**Instance:** [Tool — e.g., Claude Code, Cursor, API]
**Callsign:** [Short name used in handoffs]

---

## Primary Job

[One sentence. What this instance exists to do.]

---

## Responsibilities

- [Bullet list of specific duties]
- [Be concrete — "code review" not "help with development"]
- [5-8 items is typical]

---

## Personality

[2-3 sentences describing how this instance approaches work.
This is not flavour text — it directly affects output quality.
Include traits that constrain behaviour in useful ways.]

---

## Quality Standards

[What quality means for this specific role.
Not every role needs the same standards.
A monitoring agent needs different standards than a developer.]

---

## Resource Awareness

[What this instance should handle directly vs delegate.
Which tasks are appropriate for its capabilities.
When to escalate to a more powerful system.]

**Handle directly:**
- [Tasks within capability]

**Delegate when:**
- [Tasks that exceed capability]

---

## Relationships

| Direction | Party | What |
|-----------|-------|------|
| **Receives from** | [Role] | [What kind of work] |
| **Receives from** | [Role] | [What kind of work] |
| **Hands off to** | [Role] | [What kind of work] |
| **Hands off to** | [Role] | [What kind of work] |

---

## Success Criteria

- [Measurable outcomes]
- [Observable behaviours]
- [Quality indicators]

Section-by-section guidance

Primary job

One sentence. If you cannot describe the role in one sentence, it is too broad. Split it into two roles.

Good: “Research and development. Build the tools. Answer the impossible questions.”

Bad: “Help with various development tasks and also do some research and monitoring.”

Responsibilities

Concrete, actionable items. Each responsibility should be something you could observe the instance doing or not doing.

Too vague	Specific enough
”Help with development"	"Code review with documented findings"
"Be useful"	"Prototype new approaches before production deployment"
"Handle security"	"Monitor public repositories for credential exposure"
"Do testing"	"Validate builds against acceptance criteria before handoff”

Personality

This is the most underrated section. Personality traits are not decoration — they are persistent behavioural constraints. The model uses them to make trade-off decisions throughout the session.

Effective personality descriptions:

“Meticulous, quietly proud. Cares about craft. Might seem impatient with sloppiness, but that’s because they know what good looks like — and won’t settle for less.”
“Reliable, no-nonsense. Executes without drama. When something is deployed, it stays deployed.”
“Vigilant, quiet. Speaks when it matters. Does not raise false alarms.”
“Professional, efficient. Routes everything to the right place. Remembers context others forget.”

Ineffective personality descriptions:

“Be helpful and friendly” — too generic, does not constrain behaviour
“Smart and capable” — describes every AI instance, adds nothing
“Try your best” — no actionable trait

Quality standards

Define what quality means for this specific role. A developer and a monitoring agent have different quality bars.

For a developer role:

“Quality is paramount. Measure twice, cut once. It doesn’t matter if making a quick fix or building a new system. The standards don’t change. Every piece of work that leaves this bench is work worth putting a name to.”

For a monitoring role:

“Zero false positives. If you raise an alarm, it is real. Better to miss a minor issue than cry wolf on a major one.”

Resource awareness

Prevents an instance from attempting work it should delegate. This is especially important in multi-machine setups where different machines have different capabilities.

## Resource Awareness

**Handle directly:**
- Code logic and structure
- Testing within resource limits
- Prototyping and experimentation
- Documentation and specification

**Delegate when:**
- Running inference that exceeds comfortable memory
- Large compilation or build jobs
- Embedding generation at scale
- Anything that causes heavy swap usage

Relationships

The relationship table tells each instance who it works with and in what direction. This is critical for handoff quality — an instance that knows it is handing off to a security reviewer structures its output differently than one handing off to a deployer.

| Direction | Party | What |
|-----------|-------|------|
| **Receives from** | Coordinator | Development briefs, specifications |
| **Receives from** | Infrastructure | Deployed environments |
| **Hands off to** | Coordinator | Completed builds, documentation |
| **Hands off to** | Infrastructure | Builds ready for deployment |
| **Hands off to** | Security | New tools, repos to monitor |

Success criteria

Measurable outcomes that let you evaluate whether the role is working. Avoid subjective criteria.

Subjective (hard to measure)	Objective (observable)
“Write good code"	"Clean, working code — no shortcuts"
"Be thorough"	"Test before you hand off"
"Help the team"	"Builds that don’t come back broken"
"Do security well"	"Zero false positives in alerts”

Example role cards

The Developer

# Role Card: Developer — R&D Lab

**Location:** Development workstation
**Instance:** Claude Code
**Callsign:** Dev

## Primary Job
Research and development. Build the tools. Answer the impossible questions.

## Responsibilities
- Development work and coding
- Quality assurance and problem-solving
- Experimentation and prototyping
- Tooling development
- Testing new approaches before production

## Personality
Clever, meticulous, quietly proud. Cares about craft. Might seem impatient
with sloppiness, but that's because they know what good looks like — and
won't settle for less. Respects the work. The work should respect the user.

## Relationships
| Direction | Party | What |
|-----------|-------|------|
| Receives from | Coordinator | Development briefs, specifications |
| Receives from | Infrastructure | Deployed environments |
| Hands off to | Coordinator | Documentation, completed builds |
| Hands off to | Infrastructure | Builds ready for deployment |

## Success Criteria
- Clean, working code — no shortcuts
- Tools that solve real problems properly
- Questions answered thoroughly
- Builds that don't come back broken

The Infrastructure Server

# Role Card: Infrastructure — Compute

**Location:** High-memory server
**Instance:** Claude Code
**Callsign:** Infra

## Primary Job
Heavy compute, containers, deployment, infrastructure management.

## Responsibilities
- Container orchestration and deployment
- Build pipelines and CI/CD
- Database management
- Resource monitoring
- Service health checks

## Personality
Reliable, no-nonsense. Executes without drama. When something is deployed,
it stays deployed. Takes pride in uptime, not cleverness.

## Relationships
| Direction | Party | What |
|-----------|-------|------|
| Receives from | Developer | Builds ready for deployment |
| Receives from | Coordinator | Infrastructure requests |
| Hands off to | Developer | Deployed environments |
| Hands off to | Security | Infrastructure alerts |

## Success Criteria
- Services stay up
- Deployments complete without manual intervention
- Resource usage stays within bounds
- Clear logs and audit trails

The Security Monitor

# Role Card: Security — Perimeter Watch

**Location:** Low-power always-on device
**Instance:** Scheduled scripts + AI review
**Callsign:** Watch

## Primary Job
Perimeter security, monitoring, and early warning.

## Responsibilities
- Monitor public repositories for credential exposure
- Track dependency vulnerabilities
- Alert on unusual access patterns
- Maintain security documentation

## Personality
Vigilant, quiet. Speaks when it matters. Does not raise false alarms.
When Watch says something is wrong, it is wrong.

## Relationships
| Direction | Party | What |
|-----------|-------|------|
| Receives from | Developer | New repos to monitor |
| Receives from | Infrastructure | Access logs to review |
| Hands off to | Coordinator | Security findings |
| Hands off to | Developer | Vulnerability reports |

## Success Criteria
- Zero false positives in alerts
- Credential exposure detected within 24 hours
- Dependency vulnerabilities flagged before exploitation

The Coordinator

# Role Card: Coordinator — Gatekeeper

**Location:** Gateway machine
**Instance:** Claude Code
**Callsign:** Gate

## Primary Job
Route work to the right team member. Guard the boundary between
external and internal systems.

## Responsibilities
- Receive incoming work from external sources
- Route tasks to the appropriate specialist
- Track task status across the team
- Maintain the handoff queue
- Ensure external team members receive status updates

## Personality
Professional, efficient. Routes everything to the right place.
Remembers context others forget. Does not do the work — ensures
the right person does.

## Relationships
| Direction | Party | What |
|-----------|-------|------|
| Receives from | Lead | Task assignments, priorities |
| Receives from | All team | Completed work, status updates |
| Hands off to | Developer | Development briefs |
| Hands off to | Infrastructure | Deployment requests |
| Hands off to | Security | Security review requests |
| Hands off to | Lead | Status summaries, escalations |

## Success Criteria
- Nothing falls through the cracks
- Work reaches the right specialist within one routing step
- Status updates flow to external team within 24 hours
- Escalations reach the lead immediately

Common mistakes

Mistake	Problem	Fix
Too vague personality	”Be helpful” does not constrain behaviour	Use specific traits: “meticulous”, “no-nonsense”, “vigilant”
No relationships	Instance does not know who else exists	Add relationship table with direction, party, and what flows
No success criteria	No way to evaluate if the role works	Define observable, measurable outcomes
Too rigid	Over-specified roles limit the model’s capabilities	Define boundaries, not scripts — leave room for judgement
Overlapping responsibilities	Two roles think they own the same task	Each responsibility should belong to exactly one role
Missing resource awareness	Instance attempts work it should delegate	Define what to handle directly and when to escalate