🤖 Agent Resources

Shared commands for AI coding agents (Cursor, Claude, and more)

Generic AI Coding Agent commands for research, planning, implementation, and commits

Installation • Commands • Workflow • Troubleshooting • Contributing

📋 Table of Contents

Features
Quick Start
Installation
Workflow
Commands
Post-Installation
Requirements
Troubleshooting
Contributing
License

✨ Features

🔍 Smart Research Understand codebase structure and patterns instantly with AI-powered analysis	📝 Plan Generation Create detailed implementation plans following best practices
🚀 Auto Implementation Execute plans with automatic migrations, tests, and validation	📦 Conventional Commits Generate semantic commits that follow conventional commit standards

✅ Multi-Agent Support - Works with Cursor, Claude, and more
✅ Zero Configuration - Interactive installer handles everything
✅ Project-Aware - Respects your project's rules and architecture
✅ Workflow Integration - Commands designed to work together seamlessly
✅ MIT Licensed - Free for personal and commercial use

🚀 Quick Start

Install commands with a single command:

npx @integral-de/agent-resources install

The installer will:

✓ Detect which AI agents you have installed (Cursor, Claude)
✓ Let you choose which agents to install for
✓ Automatically copy commands to the correct locations
✓ Create a configuration file to track your installation

📦 Installation

Prerequisites

Node.js 18 or higher
At least one supported AI agent installed:
- Cursor (installs to ~/.cursor/)
- Claude (installs to ~/.claude/)

Install

Simply run:

npx @integral-de/agent-resources install

The interactive installer will guide you through the process.

Verify Installation

After installation, verify commands are available:

For Cursor Users:

Commands appear as custom rules in your workspace

For Claude Users:

Type /integral: to see available commands

🔄 Workflow

These commands work together in a natural development cycle:

graph LR
    A[🔍 Research] --> B[📝 Plan]
    B --> C[🚀 Implement]
    C --> D[📦 Commit]
    D --> A
    
    style A fill:#e1f5ff
    style B fill:#fff4e1
    style C fill:#e8f5e9
    style D fill:#f3e5f5

1. Research → Understand the Codebase

/integral:research-codebase

Analyzes your codebase to understand domain architecture, business logic, and implementation patterns.

2. Plan → Create Implementation Strategy

/integral:generate-plan TICKET-123 add user notifications

Generates a detailed implementation plan with requirements, architecture decisions, and file changes.

3. Implement → Execute with Confidence

/integral:implement-plan @docs/plans/TICKET-123-user-notifications.plan.md

Executes the plan following project rules, generating migrations, tests, and validation automatically.

4. Commit → Ship It

/integral:commit-and-push

Creates a conventional commit and pushes to remote with semantic versioning support.

📚 Commands

`integral:research-codebase`

Purpose: Research codebase structure and patterns to understand domain architecture, business logic, and implementation patterns.

Usage:

/integral:research-codebase

What It Does:

🔍 Analyzes project structure and architecture
📊 Identifies domain patterns and business logic
🏗️ Maps dependencies and relationships
📝 Generates synthesized findings with file references

Output:

docs/research/{topic}.research.md

Best For:

New team members onboarding
Understanding legacy code
Planning large refactors
Documenting system architecture

`integral:generate-plan`

Purpose: Generate software implementation plans through structured requirement gathering.

Usage:

# Basic usage
/integral:generate-plan implement user authentication

# With ticket reference
/integral:generate-plan TICKET-456 add payment processing

# Complex feature
/integral:generate-plan TASK-789 multi-tenant support with data isolation

What It Does:

📝 Gathers requirements interactively
🎯 Defines clear objectives and success criteria
🏗️ Plans architecture and file changes
⚠️ Identifies risks and considerations
✅ Creates validation checklist

Output:

docs/plans/{ticket-id}-{feature-name}.plan.md

Plan Sections:

Overview & Requirements
Architecture Decisions
Implementation Steps
File Changes
Testing Strategy
Validation Checklist

`integral:implement-plan`

Purpose: Execute implementation plans following project rules and guidelines.

Usage:

# Implement a plan
/integral:implement-plan @docs/plans/user-authentication.plan.md

# With optional research context
/integral:implement-plan @docs/plans/user-auth.plan.md @docs/research/auth-patterns.research.md

What It Does:

📖 Reads plan and optional research files
🏗️ Follows project architecture rules
🗄️ Generates database migrations automatically
🧪 Runs tests and linting
✅ Validates implementation against plan
📊 Reports progress and completion

Features:

Smart Implementation - Follows your project's rules and patterns
Auto Migrations - Generates Liquibase/Flyway migrations
Test Integration - Runs relevant tests after changes
Validation - Ensures all plan requirements are met
Rollback Support - Guides you if issues occur

Best Practices:

Run research before complex implementations
Review generated migrations before applying
Check validation report before committing

`integral:commit-and-push`

Purpose: Create a conventional commit for staged changes and push to the remote repository.

Usage:

/integral:commit-and-push

What It Does:

📊 Analyzes staged changes with git diff
📝 Generates conventional commit message
🎯 Determines commit type (feat, fix, chore, etc.)
💬 Creates meaningful commit description
✅ Asks for approval before pushing
🚀 Pushes to remote repository

Commit Types:

feat: New features
fix: Bug fixes
chore: Maintenance tasks
docs: Documentation changes
refactor: Code refactoring
test: Test additions/changes
style: Code style changes

Example Output:

feat(auth): add user authentication with JWT tokens

- Implement JWT token generation and validation
- Add login and logout endpoints
- Create authentication middleware
- Add user session management

🎯 Post-Installation

After installation, commands are immediately available in your selected agents.

For Cursor Users

Commands are available as custom rules in your workspace. Simply start typing /integral: to see available commands.

Available Commands:

/integral:research-codebase - Research codebase structure and patterns
/integral:generate-plan - Create implementation plans
/integral:implement-plan - Execute implementation plans
/integral:commit-and-push - Generate conventional commits and push

For Claude Users

Use commands with the / prefix in any conversation:

/integral:research-codebase
/integral:generate-plan TICKET-123 feature description
/integral:implement-plan @docs/plans/plan-file.plan.md
/integral:commit-and-push

📋 Requirements

Requirement	Version	Purpose
Node.js	≥ 18.0.0	Runtime environment
npm	Latest	Package installation
AI Agent	Any	Cursor, Claude, etc.

Supported AI Agents:

✅ Cursor (Desktop app)
✅ Claude (CLI or Desktop)
🔜 More agents coming soon

🔧 Troubleshooting

No agents detected

Symptom: Installer says "No supported agents found"

Solutions:

Ensure you have Cursor or Claude installed
Check that the agent's directory exists:
- Cursor: ~/.cursor/
- Claude: ~/.claude/
Run the agent at least once to create its configuration directory

Try running installer with verbose output:

DEBUG=* npx @integral-de/agent-resources install

Installation fails

Symptom: Installation script exits with error

Solutions:

Check write permissions to your home directory:
```
ls -la ~/.cursor/
ls -la ~/.claude/
```
Try running with elevated permissions (macOS/Linux):
```
sudo npx @integral-de/agent-resources install
```
Check the error message for specific issues

Clear npm cache and retry:

npm cache clean --force
npx @integral-de/agent-resources install

Commands not working

Symptom: Commands don't appear after installation

Solutions:

Restart your AI agent - Most agents require restart to load new commands
Check that files were copied correctly:
- Cursor: ~/.cursor/commands/integral/
- Claude: ~/.claude/commands/integral/

Verify file contents are not corrupted:

cat ~/.cursor/commands/integral/research-codebase.md

Reinstall commands:

npx @integral-de/agent-resources install

Commands execute but produce errors

Symptom: Commands run but fail during execution

Solutions:

Ensure you're in a git repository (for commit-and-push)
Check that plan files exist (for implement-plan)
Verify your project has a docs/ directory
Check agent logs for detailed error messages
Try running in a fresh terminal session

Need More Help?

📖 Check the GitHub Issues
💬 Open a new issue with detailed error information
📧 Contact maintainers for support

🤝 Contributing

We welcome contributions! Here's how you can help:

Ways to Contribute

🐛 Report Bugs - Open an issue with detailed reproduction steps
💡 Suggest Features - Share ideas for new commands or improvements
📝 Improve Documentation - Fix typos, add examples, clarify instructions
🔧 Submit Pull Requests - Add features or fix bugs

Development Setup

Clone the repository:

git clone https://github.com/Integral-de/agent-resources.git
cd agent-resources

Install dependencies:
```
npm install
```

Test locally:

npm link
integral-agent-resources install

Make your changes:
- Commands: integral/commands/
- Installers: src/installers/
- CLI: bin/cli.js
Test your changes:
```
npm test
```
Submit a pull request

Coding Standards

✅ Use ES modules (import/export)
✅ Follow existing code style
✅ Add comments for complex logic
✅ Test with both Cursor and Claude
✅ Update README if adding features

Adding New Commands

Create command file in integral/commands/{command-name}.md
Follow existing command structure
Add command to installer in src/installers/
Update README with command documentation
Test with target AI agents

Pull Request Process

Fork the repository
Create a feature branch (feat/amazing-feature)
Commit your changes (use conventional commits)
Push to your branch
Open a pull request with detailed description

Code Review

All contributions go through code review. We look for:

✅ Code quality and readability
✅ Test coverage
✅ Documentation updates
✅ Compatibility with supported agents

📄 License

MIT License - see the LICENSE file for details.

Made with ❤️ by Integral

If you find this project useful, please consider giving it a star ⭐

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
.github/workflows		.github/workflows
bin		bin
integral/commands		integral/commands
src		src
.gitignore		.gitignore
.npmignore		.npmignore
LICENSE		LICENSE
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json

License

Integral-de/agent-resources

Folders and files

Latest commit

History

Repository files navigation

🤖 Agent Resources

📋 Table of Contents

✨ Features

🔍 Smart Research

📝 Plan Generation

🚀 Auto Implementation

📦 Conventional Commits

🚀 Quick Start

📦 Installation

Prerequisites

Install

Verify Installation

🔄 Workflow

1. Research → Understand the Codebase

2. Plan → Create Implementation Strategy

3. Implement → Execute with Confidence

4. Commit → Ship It

📚 Commands

integral:research-codebase

integral:generate-plan

integral:implement-plan

integral:commit-and-push

🎯 Post-Installation

For Cursor Users

For Claude Users

📋 Requirements

🔧 Troubleshooting

No agents detected

Installation fails

Commands not working

Commands execute but produce errors

Need More Help?

🤝 Contributing

Ways to Contribute

Development Setup

Coding Standards

Adding New Commands

Pull Request Process

Code Review

📄 License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 1

Languages

`integral:research-codebase`

`integral:generate-plan`

`integral:implement-plan`

`integral:commit-and-push`