GYO-AGENTS

Generate instructions for your coding agent, share project knowledge, enforce team conventions, and hand unfinished work from one agent to another with verification evidence tied to the code.

Use the standalone AGENTS.md prompt in any coding agent, or connect the MCP server for shared memory, Guardrails, local task handoffs, and the full library of 11 client-specific templates.

Quick start

Build the MCP server from a checkout with Git and Node.js 18 or newer.

git clone https://github.com/youssef-jad/GYO-AGENTS.git
cd GYO-AGENTS/mcp-server
npm ci
npm run build

Set gyo_entry to the built server's absolute path. Run the registration command for your client from the repository you want to work in.

gyo_entry="/absolute/path/to/GYO-AGENTS/mcp-server/dist/index.js"

# Claude Code
claude mcp add --scope local gyo-agents -- node "$gyo_entry"

# Codex
codex mcp add gyo-agents -- node "$gyo_entry"

Start a new session and ask for the client-specific setup prompt. Use get_prompt_claudecode in Claude Code or get_prompt_codexcli in Codex. For Cursor, Kiro, and other clients, see the MCP setup guide.

GYO Guardrails

Teach a convention in one agent, approve it once, and have another agent check its changes against the same rule. For example, ask Claude Code:

In this repo, use the App\Support\CacheStore wrapper in PHP services. Record that correction for this repository and propose a GYO Guardrail for app/Services/**/*.php that flags newly added lines containing use Illuminate\Support\Facades\Cache;. Leave the rule pending.

From the target repository, review the proposed rule and approve its ID.

node "$gyo_entry" guardrail list
node "$gyo_entry" guardrail approve RULE_ID

To run checks automatically, merge the Stop hook example into .claude/settings.local.json for Claude Code or .codex/hooks.json for Codex. If you built from a checkout, point the hook command to node "/absolute/path/to/GYO-AGENTS/mcp-server/dist/index.js" guardrail hook. In Codex, use /hooks to review and trust the hook.

When the agent tries to finish, the hook checks staged and unstaged changes against HEAD, plus new, non-ignored files. A violation gives the agent one repair pass, followed by a recheck. Each rule checks for exact, case-sensitive text on added lines in matching files.

Team Guardrails

Export approved rules to .gyo/guardrails.json and review them in a PR. After merge, the hook and CLI load the committed rules in every checkout. CI can check a PR against the rules from its trusted base commit. Team setup and CI example

To run the same local check as the hook, use node "$gyo_entry" guardrail check --working-tree from the target repo.

Verified in Claude Code and Codex. In separate fresh clones with empty local rule stores, both agents received a prompt to run a PHP smoke test. Their Stop hooks read the team policy, caught the forbidden Cache facade import in an untracked service, and sent the agents back to fix it. Both checks then reported zero violations and both smoke tests passed. The file stayed untracked throughout.

GYO Relay (local preview)

Let one agent checkpoint unfinished work and another continue it through GYO and the same local profile. Relay saves the objective, acceptance criteria, progress, next steps, and uncertainty. A temporary claim prevents two cooperating clients from owning the same handoff; after expiry, another client can reclaim it and the previous token can no longer submit.

Verification runs checks defined in the project's committed .gyo/relay.json, plus GYO Guardrails. Evidence is tied to the commit, staged content, tracked and non-ignored untracked files, and policy. When these change, get_handoff and claim_handoff report stale evidence and the changed paths. An agent's summary alone never counts as verification.

Start by reviewing and committing the project's allowed check commands, then ask an agent to create and claim a handoff. Both clients must use the same GYO_AGENTS_DATA_DIR and checkout. Setup, tool workflow, limits, and live validation

For example, ask the first agent:

Use GYO Relay to create and claim this task. Before stopping, verify the current work and checkpoint what is complete, what remains, and what is uncertain. Release the claim for the next agent.

In a new session with the second agent:

Find and claim the unfinished GYO Relay handoff in this checkout. Inspect its checkpoint and evidence freshness, complete the remaining work, run verification, and submit the result. Keep changes local.

The workflow uses create_handoff, claim_handoff, checkpoint_handoff, verify_result, and submit_result; list_handoffs and get_handoff let clients discover tasks and inspect their current state. Relay coordinates participating clients on one machine; it does not launch agents or transfer work between remote checkouts.

Verified with real Claude Code and Codex sessions. Claude implemented part of a synthetic billing task, recorded passing tests and checkpointed before stopping. After deliberate changes to the code and an untracked file, a new Codex session reclaimed the expired handoff, identified stale evidence, repaired the regression, completed the remaining work and submitted fresh passing verification. The old claim token was rejected.

What else you can do

• Generate agent instructions. Use the 11 client templates to build instructions from your repo structure, commands, and conventions.
• Share local memory. Save preferences, corrections, and decisions for clients on the same machine. Use project scope for repo-specific knowledge and global scope for conventions you want across repos. Memory setup
• Keep instructions current. Use snapshot_config and sync_agent_config to detect repo changes and see which instructions need updating. Config freshness guide

---

Prompt: Generate Your Own AGENTS.md

Copy this entire prompt into any AI coding agent (Kiro, Claude Code, Cursor, Copilot, Codex, etc.) while inside your project workspace. It will analyze your codebase and git history to generate a powerful, project-specific AGENTS.md file.

(Note: If the agent truncates its response, run Steps 1-2 first, then ask it to complete Steps 3-4 in a follow-up).

I need you to generate a comprehensive AGENTS.md file for this project. This file will instruct AI coding agents on how to work in this codebase correctly. Follow these steps:

## Step 1: Analyze the Project

Explore the codebase and gather:
- Language, framework, and major dependency versions (from package.json, composer.json, Gemfile, go.mod, requirements.txt, Cargo.toml, etc.)
- Directory structure and code organization patterns (where do models, controllers, services, tests live?)
- **Architectural Observations**: Describe what you directly observe (directory names, file names, import patterns). Do NOT guess architectural labels (like "CQRS" or "DDD") unless there is explicit evidence (e.g., a file named `CommandHandler` inside a `Commands/` directory). If uncertain, describe the structure instead of labeling it.
- Module/package count and naming conventions
- How tests are organized, base classes/traits, test runner, and testing philosophy (unit vs integration ratio, what gets mocked, what uses real DB)
- Error handling patterns (custom exception classes, error middleware, global handlers)
- Security patterns (auth middleware location, permission checks, input sanitization, CSRF)
- Logging setup (library used, what gets logged, standard log levels)
- Environment/Config loading (.env patterns, per-environment overrides, secrets management)
- Type system strictness (strict types enabled? generics usage? type narrowing?)
- Dependency injection patterns (container, manual wiring, constructor injection?)
- Generated code (migrations, proto stubs, OpenAPI clients, IDE helpers) — note what should NEVER be edited manually
- CI/CD configuration (what checks run on PR? what blocks merge?)
- Docker/container setup (compose files, Makefiles, scripts)
- Linting/formatting tools and their configs
- Database setup (connections, migrations location, ORM patterns, read/write split)
- API response patterns (how are responses serialized? presenters, transformers, resources?)
- Caching patterns (driver, TTL conventions, key naming, invalidation strategy)
- Event/messaging patterns (event bus, queues, Kafka, pub/sub)

*Important: If a data source for any of the above doesn't exist (e.g., no Docker, no CI), note "No [X] detected" and skip that item. Do not guess or fill with generic advice.*

## Step 2: Analyze Git History for Style

Run these git commands to study the coding style:

1. `git config user.name` and `git config user.email` — identify the developer
2. `git log --oneline | wc -l` — check total commit count. If total commits < 50, skip this step entirely and write "Insufficient commit history for style analysis."
3. Filter out bot authors (dependabot, renovate, github-actions, ci, automation) and use `--no-merges`. If this is a forked repo, use `--first-parent` to exclude upstream history.
4. Fetch up to 1000 valid commit messages. *(If output exceeds your context window, sample the 500 most recent and 500 oldest, and note the gap.)*
5. Analyze the messages. **To get accurate counts, use shell tools (`grep`, `awk`, `sort`, `uniq`) if you have execution access. If you do not have shell execution access, parse the text but you MUST append `[verify: count]` to any numbers you derive.** Calculate:
   - Commit message format (conventional commits? ticket prefixes? terse vs descriptive?)
   - Most common action verbs with exact counts (e.g., "fix: 45, add: 30")
   - Domain keywords frequency — what parts of the codebase are touched most?
   - Style evolution over time (compare the first 20% of commits to the last 20% of commits)
   - Ticket/issue prefix patterns (Jira, Linear, GitHub issues?)
   - Date range of contributions
6. If I provide a GitHub/GitLab profile URL, fetch it and extract: title/role, technical skills, and notable achievements or metrics.

## Step 3: Analyze Performance Patterns

Search the codebase for:
- Eager loading patterns (e.g., `->with()`, `include`, `preload`, joins)
- Pagination patterns
- Caching usage (e.g., `Cache::remember`, Redis patterns, memoization, HTTP caching headers)
- Batch processing (e.g., `chunk`, `cursor`, `batch`, streaming)
- Query optimization (select specific columns, `exists` checks, indexed queries)
- Response shaping (presenters, serializers, transformers, DTOs)
- **Potential N+1 indicators**: Search for relationship access in loops or serializers without eager loading. ONLY flag cases where you can see the full call chain (query → loop → access). If you cannot verify whether it's eager-loaded upstream, omit it rather than guessing.

## Step 4: Generate the AGENTS.md

Structure the file with these exact sections. Target 250-400 total lines.

### 1. Header (2 lines)
One-line project description with language, framework, version, and scale (module/package count).

### 2. Architecture at a Glance (30–50 lines)
- ASCII tree of top-level directories with purpose annotations
- Note any generated code directories that must not be manually edited
- Describe the anatomy of a typical module/package based on direct observation. If you include subdirectory counts, append `[verify: count]` if you cannot verify via shell commands.

### 3. Docker / Dev Environment (15–25 lines)
- How to run commands (container exec, Makefile shortcuts, scripts)
- Services table with ports and stack info
- Keep Makefile shortcuts as the preferred method if one exists
- If no Docker detected, write "No Docker setup detected" and skip

### 4. Essential Commands (15–25 lines)
- Table of common tasks (test, lint, format, analyze, migrate)
- Note important flags (disable debugger, memory limits, config clearing)
- CI info (how many test suites, parallel groups, which branches trigger checks)

### 5. Guardrails — ALWAYS / NEVER / WATCH OUT (40–60 lines)
This is the highest-impact section. Give it room.

**ALWAYS**: Things the agent must do on every change. Derived from the dominant patterns in the codebase.
*Crucial: Before writing an ALWAYS rule, verify the dominant pattern is actually a good practice. If the codebase predominantly does something that contradicts the framework's recommended approach, put it in WATCH OUT instead ("Legacy code does X, but for new code prefer Y").*

**NEVER**: Things that will break the build or violate project conventions. Be specific and actionable (e.g., "Don't use pattern X — we use Y instead", "Don't manually edit files in /generated/").

**WATCH OUT**: Gotchas and edge cases unique to this project — inconsistent naming conventions that coexist, feature flags that gate functionality, database split configurations, modules with non-standard structure.

### 6. Decision Trees (30–50 lines)
Write 3 decision trees as indented code blocks:
- "Where does this code go?" — routing new code to the right directory
- "How do I add a new endpoint/feature?" — step-by-step checklist
- "How do I write a test?" — which base class, traits, naming convention

### 7. Performance & Query Standards (20–30 lines)
Based ONLY on actual patterns found in the codebase:
- N+1 prevention rules with specific examples from the project
- Caching strategy with real TTL values and key formats extracted from the code
- Batch operation conventions (chunk sizes, cursor vs chunk)
- If no performance patterns detected, write "No established performance patterns detected" and skip

### 8. Error Handling, Logging & Security (15–25 lines)
- How errors are thrown and handled (custom exception classes, middleware, response format)
- What gets logged and at what level
- How auth/permissions work for new endpoints
- If any of these are not established, note it

### 9. Rules References (5–10 lines)
Link to any existing rule files, style guides, or documentation in the repo (e.g., `.cursorrules`, `.claude/rules/`, `CONTRIBUTING.md`, `.editorconfig`). If none exist, write "No existing rule files detected."

### 10. Developer Style Guide (30–50 lines)
Write in second-person imperative ("Match this format...", "Follow this pattern..."). Include:
- **Commit Format**: The exact format to use, with 3 real examples extracted from the git history. If style evolved, show the current style and note it explicitly.
- **Code Style**: Specific patterns to follow (null safety, typing, naming, import organization) derived from the most recent commits.
- **Domain Focus**: Table of areas the developer works on most, based on commit keyword frequency.
- **Key Features**: Attempt to identify ticket prefixes and list top 5 tickets by commit count. If the ticket prefix format is too inconsistent or difficult to parse reliably, write "Ticket prefix format too varied to aggregate reliably" instead of guessing.

## Formatting & Verification Rules

- Use tables for structured data (services, commands, domain expertise)
- Use code blocks for decision trees and directory structures
- Use bullet points for rules and guidelines
- Keep it scannable — an agent should find any answer in under 5 seconds
- **NO HALLUCINATED NUMBERS**: When stating counts or values, you must either cite the exact command or file that produced the number, or write "[verify: X]". Never estimate.
- Every rule must be grounded in actual codebase evidence. If you didn't see it, don't write it.
- If a section lacks data, write "No [X] detected" — do not fill space with generic advice.
- Total file should be 250–400 lines — comprehensive but not bloated.