workspace-agents

One command sets up your project to work with AI coding assistants.

npx workspace-agents init

The Problem

AI coding assistants (Claude, Copilot, Cursor, Gemini) each look for different config files:

| Tool | Looks for | |------|-----------| | Claude Code | CLAUDE.md | | Cursor | .cursor/rules/ | | GitHub Copilot | .github/copilot-instructions.md | | Gemini | GEMINI.md |

Without coordination, you end up duplicating instructions across 4+ files, and they get out of sync.

The Solution

workspace-agents creates a single source of truth (AGENTS.md) with vendor breadcrumbs:

your-project/
├── AGENTS.md                    # ← Your AI instructions live here
├── CLAUDE.md                    # → Points to AGENTS.md
├── GEMINI.md                    # → Points to AGENTS.md
├── .cursor/rules/project.mdc   # → Points to AGENTS.md
├── .github/copilot-instructions.md
└── agents/
    └── plans/                   # Track multi-session work
        └── local/               # Scratch work (gitignored)

Commands

npx workspace-agents init           # Create AGENTS.md + vendor breadcrumbs
npx workspace-agents init --with-skills  # Also add skills/ directory
npx workspace-agents init --full    # Everything (skills, READMEs, all vendors)
npx workspace-agents check          # Validate your AGENTS.md
npx workspace-agents status         # Show installation health
npx workspace-agents cleanup        # Remove broken symlinks, unused files

Options

# Init options
--vendors=claude,cursor   # Only create specific vendor files
--with-skills             # Include skills directory + bundled skills
--full                    # Create all files
--dry-run                 # Preview changes without applying
--force                   # Overwrite existing files
-y, --yes                 # Skip confirmation prompts

# Cleanup options
--vendors=cursor,gemini   # Remove specific vendor files

What You Get

Minimal (default):

• AGENTS.md - Pre-structured template
• agents/plans/ - Track work across sessions
• Vendor breadcrumbs for all 4 AI tools

With --with-skills:

• agents/skills/ directory
• Bundled skill-creator skill
• Claude Skills symlinks

After Setup

1. Run npx workspace-agents check to validate
2. Edit AGENTS.md with your project details
3. Start working with your AI assistant

How It Works

Each AI tool automatically loads its config file when you open a project:

| Tool | Auto-loads | Which contains | |------|------------|----------------| | Claude Code | CLAUDE.md | @AGENTS.md (include directive) | | Cursor | .cursor/rules/project.mdc | Link to AGENTS.md | | GitHub Copilot | .github/copilot-instructions.md | Link to AGENTS.md | | Gemini | GEMINI.md | Link to AGENTS.md |

Result: Your AI assistant reads AGENTS.md automatically. No copy-paste needed.

Recommended Workflow

1. Always Start with a Plan

Before implementing anything non-trivial, create a plan:

# agents/plans/add-user-search.md

## Objective
Add search functionality to the users API endpoint.

## Tasks
- [ ] Add query params to GET /users (name, email, role)
- [ ] Update user service with search filters
- [ ] Add input validation
- [ ] Write tests for search combinations
- [ ] Update OpenAPI spec

## Notes
- Use existing pagination pattern from /products
- Index considerations: check if we need DB indexes

Tell your agent: "Read the plan in agents/plans/add-user-search.md and let's work through it."

2. Work Through the Plan Iteratively

Your agent checks off tasks as you complete them. The plan becomes a living document:

## Tasks
- [x] Add query params to GET /users (name, email, role)
- [x] Update user service with search filters  
- [ ] Add input validation ← currently working
- [ ] Write tests for search combinations
- [ ] Update OpenAPI spec

## Notes
- Use existing pagination pattern from /products
- Index considerations: check if we need DB indexes
- **Decision:** Using LIKE for name search, exact match for email/role

3. Extract Reusable Patterns into Skills

When you discover a process you'll repeat, create a skill:

You: "We've done this database migration pattern three times now. 
     Let's document it as a skill."

Agent: Creates agents/skills/db-migration/SKILL.md with:
       - When to use this pattern
       - Step-by-step process
       - Common gotchas
       - Rollback procedures

Skills are for deterministic, repeatable processes like:

• Deployment workflows
• Database migrations
• Release procedures
• Code generation patterns

4. Add Reference Docs When AGENTS.md Gets Long

When a topic needs more detail than fits in AGENTS.md:

You: "The auth section is getting long. Let's move it to a reference doc."

Agent: Creates agents/reference/authentication.md with:
       - JWT token structure
       - Refresh token flow
       - Permission levels
       - Common auth errors

Update AGENTS.md to link to it:

## Authentication
See [agents/reference/authentication.md](agents/reference/authentication.md) for details.

5. Keep Plans for Major Changes

After completing a feature, keep the plan if it documents important decisions:

## Decisions Made
- Used LIKE for name search (case-insensitive)
- Added composite index on (role, created_at) for common query
- Chose 100 max results to prevent timeout on large datasets

## Future Considerations  
- Full-text search if LIKE becomes slow
- Elasticsearch integration for advanced search

These become valuable context for future sessions.

Example Session

You: "I need to add email notifications when users sign up"

Agent: "I'll create a plan first. Looking at AGENTS.md, I see:
       - I can edit code in src/
       - Email-related code needs review (under Forbidden)
       - You're using Express with the service pattern
       
       Let me create agents/plans/signup-notifications.md..."

[Agent creates plan with tasks]

You: "Looks good, let's start with task 1"

[Work through tasks, agent updates plan as you go]

Agent: "Done! I noticed we might want this notification pattern 
       for other events. Want me to create a skill for it?"

You: "Yes, create a notification skill"

[Agent creates agents/skills/notifications/SKILL.md]

Example AGENTS.md

# my-api

REST API for user management. Success = fast, tested, documented endpoints.

## Allowed Operations

- Edit code in `src/`
- Run tests
- Update OpenAPI spec

**Forbidden** (ask first):
- Database schema changes
- Auth/security code
- CI/CD configuration

## Setup

git clone <repo> && cd my-api
npm install
cp .env.example .env

## Run / Test

npm test              # Unit tests
npm run test:e2e      # Integration tests
npm run dev           # Dev server on :3000

## Repo Map

src/
├── routes/           # Express route handlers
├── services/         # Business logic
├── models/           # Database models
└── middleware/       # Auth, validation, etc.

Philosophy

"Give users a good AGENTS.md template and get out of the way."

• Minimal by default, extensible by opt-in
• No vocabulary to learn
• Skills are optional for repeatable processes

Requirements

• Node.js 14+
• macOS, Linux, Windows

License

MIT