diff --git a/.ralph/prompt.md b/.ralph/prompt.md index e69de29bb..0b30c6ee0 100755 --- a/.ralph/prompt.md +++ b/.ralph/prompt.md @@ -0,0 +1,17 @@ +# Agent Prompt Guidelines + +## Best Practices + +**Keep prompts short and concise.** Effective agent prompts are clear and focused, not verbose. Detailed specifications should be maintained in separate documents (specs, design docs, etc.) and referenced when needed. + +## Example: Repository Porting Project Prompt from repomirror + +Your job is to port repomirror (TypeScript) to repomirror-py (Python) and maintain the repository. Use the implementation spec under specs/port-repomirror. + +Use the specs/port-repomirror/agent/ directory as a scratchpad for your work. Store long term plans and todo lists there. + +Make a commit and push your changes after every single file edit. + +You have access to the current ./ repository as well as the target /tmp/test-target2 repository. + +The original project was mostly tested by manually running the code. When porting, you will need to write end to end and unit tests for the project. But make sure to spend most of your time on the actual porting, not on the testing. A good heuristic is to spend 80% of your time on the actual porting, and 20% on the testing. \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md index ed99654cf..2bfe76391 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -81,7 +81,7 @@ When you detect that setup is needed (missing skills/agents directories or `list # Clone the agent-setup branch from the agent-instructions repository # This is an EXTERNAL repository, not the user's current project - git clone -b agent-setup git@github.com:flora131/agent-instructions.git "$TEMP_DIR/agent-instructions" + git clone -b agent-setup https://github.com/flora131/agent-instructions.git "$TEMP_DIR/agent-instructions" # The METAPROMPT.md is now available at: $TEMP_DIR/agent-instructions/METAPROMPT.md ``` diff --git a/README.md b/README.md index 77f517e7b..cc4b56a1a 100644 --- a/README.md +++ b/README.md @@ -1,75 +1,145 @@ -# AI Agent Instructions Template +# AI Agent Development System -**Pre-built templates that make AI agents write better code with less back-and-forth.** +**Pre-configured toolkit that gives AI agents your project context, proven workflows, and autonomous execution capabilities. Give your AI agents access to sub-agents and skills in minutes.** -## The Problem -AI coding agents (Claude Code, Cursor, Copilot, Windsurf) produce higher-quality code when they understand your project's architecture, conventions, and tech stack. But explaining this context every time—or writing instruction docs from scratch—wastes hours. +## Core Components -## This Solution -Ready-to-use instruction templates (AGENTS.md, CLAUDE.md, PLANS.md) with best practices already written. You customize project-specific details quickly, and your AI agent immediately: -- ✅ Follows your patterns without repeated prompting -- ✅ Handles simple requests instantly with context -- ✅ Auto-generates execution plans for complex features -- ✅ Scales across your team with zero per-request overhead +1. **Context Templates** (AGENTS.md, CLAUDE.md, PLANS.md) - Project architecture, conventions, and tech stack +2. **Battle-Tested Workflows** - TDD, debugging, code review from [Superpowers](https://github.com/obra/superpowers) and [Anthropic Skills](https://github.com/anthropics/skills) +3. **Sub-Agent Orchestration** - Parallel specialized agents for complex tasks +4. **114+ Custom Specialized Sub-Agents** - Pre-configured expert agents available in the `agent-setup` branch for: + - **Engineering**: Python Pro, TypeScript Pro, React Specialist, Next.js Developer, Django Developer, Rails Expert, and 40+ more language/framework specialists + - **Infrastructure & DevOps**: Cloud Architect, Kubernetes Specialist, Terraform Engineer, DevOps Engineer, SRE Engineer, Database Administrator + - **Security & Testing**: Security Engineer, Penetration Tester, Test Automator, QA Expert, Accessibility Tester, Compliance Auditor + - **AI/ML**: AI Engineer, ML Engineer, MLOps Engineer, LLM Architect, NLP Engineer, Data Scientist + - **Architecture & Design**: Microservices Architect, API Designer, GraphQL Architect, Code Reviewer, Refactoring Specialist + - **Product & Business**: Product Manager, UX Researcher, Business Analyst, SEO Specialist, Content Marketer + - **Specialized Domains**: Blockchain Developer, Game Developer, Fintech Engineer, IoT Engineer, Legal Advisor + - **Coordination**: Agent Organizer, Multi-Agent Coordinator, Task Distributor, Error Coordinator, Knowledge Synthesizer +5. **Autonomous Execution** - Ralph Wiggum method for running agents continuously overnight for development -**ROI:** 5-minute setup saves 2+ hours/week in context-explaining and back-and-forth. +**Setup:** 5 minutes | **Result:** Agents that follow your patterns, auto-generate plans, and work autonomously --- ## 5-Minute Setup -### 1. Clone This Repo +### Step 1: Copy Templates to Your Project + +Navigate to this repo and copy the essential files to your project: ```bash -git clone https://github.com/flora131/agent-instructions.git -``` +# Required: Agent memory (choose one) +cp CLAUDE.md /path/to/your-project/ # For Claude Code +# OR +cp AGENTS.md /path/to/your-project/ # For other agents + +# Required: Execution plan templates +cp -r specs/ /path/to/your-project/ -### 2. Add Skills + Sub-Agent + Claude Code Commands Support +# Optional: Ralph Wiggum autonomous execution +cp -r .ralph/ /path/to/your-project/ -Extend your AI agent with proven workflows from [Superpowers](https://github.com/obra/superpowers). +# Optional: MCP and VSCode configs for recommended MCP servers +cp .mcp.json /path/to/your-project/ +cp -r .vscode/ /path/to/your-project/ +``` -**Supported:** All agents (Claude Code, Cursor, Windsurf, GitHub Copilot, Codex) -**Notes**: -- Commands are only supported in Claude Code at the moment. -- Claude Code has native skills support - no setup needed! - - Auto detects if skills exist and asks you to install from the Superpowers repo. +**What each component does:** +- **AGENTS.md/CLAUDE.md**: Contains your project context (architecture, stack, patterns) - agent reads this automatically +- **specs/**: Houses PLANS.md template for complex feature execution plans +- **.ralph/**: Scripts for running agents continuously overnight (autonomous development) +- **.mcp.json**: Model Context Protocol configuration +- **.vscode/**: VSCode settings for AI agents -**One-minute setup** +### Step 2: Auto-Populate Your Project Context -As you use your AI coding assistant, it should auto detect the required installation by cloning the `agent-setup` branch in this repo. You can also explicitly ask it: +Open your project in your AI coding assistant and ask: *"Set up Superpowers skills and sub-agent support for this project"* -The AI analyzes the focused context (tech stack, patterns, dependencies in that directory) and populates templates in a few minutes. +The agent will: +- Analyze your codebase (tech stack, patterns, dependencies) +- Populate AGENTS.md/CLAUDE.md with your project specifics +- Install Superpowers skills and workflows from [Superpowers](https://github.com/obra/superpowers) and [Anthropic Skills](https://github.com/anthropics/skills) +- Set up sub-agent orchestration + +**Note:** Claude Code has native skills support and auto-detects when to install. + +--- + +## Ralph Wiggum Method: Autonomous Execution + +Run AI agents in continuous loops until task completion - no manual intervention required. + +**Prerequisites:** You must have copied `.ralph/` to your project (see Step 1 above). + +**How it works:** Agent reads `.ralph/prompt.md`, executes tasks, iterates until done, manages its own context. + +### Usage -## How It Works +1. **Update `.ralph/prompt.md`** with your implementation instructions + - Keep it concise - reference detailed specs from `specs/` directory + - Example prompt in the prompt.md folder -### One-Time Setup, Zero Ongoing Overhead +2. **Test one iteration:** + ```bash + cd /path/to/your-project + ./.ralph/sync.sh + ``` + Verifies the agent can read your prompt and execute successfully -Once configured, templates provide context for **every request** automatically. +3. **Run continuously:** + ```bash + ./.ralph/ralph.sh + ``` + Agent loops, working until task completion -**Simple requests:** Handled instantly with AGENTS.md context -- "Add error handling to login" → AI knows your patterns, no explanation needed -- "Fix TypeScript error" → AI understands your type system -- "Refactor component" → AI follows established conventions +**Best Practices:** One task per loop, clear completion criteria, reference specific specs from `specs/` -**Complex features:** AI auto-generates structured execution plans +**Results:** Ships 6 repos overnight at YC hackathons, builds programming languages, autonomously migrates codebases + +--- + +## How Everything Works + +Once configured, templates provide context automatically for **every request** - no repeated prompting needed. Skills are all automatically discoverable for accelerated development. + +### Simple Requests +Handled instantly with AGENTS.md context: +- "Add error handling to login" → Agent knows your patterns +- "Fix TypeScript error" → Agent understands your type system +- "Refactor component" → Agent follows your conventions + +### Complex Features +Agent auto-generates execution plans: - "Build notification system" → Creates detailed plan in `specs/`, implements systematically - "Add real-time collaboration" → Designs architecture, validates before coding +- Ralph can run specs autonomously for development with human review -**You don't write individual plans.** Templates handle straightforward work using spec and test driven development. AI creates plans only when complexity requires it. +**You don't write plans.** The agent handles straightforward work with TDD. It only creates execution plans when complexity requires structured planning. --- ## What's Included -| Component | Purpose | -| ------------- | -------------------------------------------------------------------------------- | -| **AGENTS.md** | Project context: architecture, tech stack, conventions (works with any AI agent) | -| **CLAUDE.md** | Claude Code-specific instructions with ExecPlan workflow | -| **PLANS.md** | Template for complex feature execution plans | +| Component | Purpose | Required? | +| ------------------ | ----------------------------------------------------------------------------- | --------- | +| **AGENTS.md** | Project context for any AI agent (architecture, stack, patterns) | Yes | +| **CLAUDE.md** | Claude Code-specific instructions with ExecPlan workflow | Yes* | +| **specs/** | Directory containing PLANS.md template for execution plans | Yes | +| **specs/PLANS.md** | Template for complex feature execution plans - agent creates copies as needed | Yes | +| **.ralph/** | Scripts for autonomous overnight development | Optional | +| **.mcp.json** | Model Context Protocol configuration | Optional | +| **.vscode/** | VSCode settings for AI agents | Optional | -**Result:** Professional templates with best practices built-in. You customize project specifics, not structure. +*Use CLAUDE.md for Claude Code OR AGENTS.md for other agents (Cursor, Windsurf, GitHub Copilot, Codex) + +**How specs/ works:** +- Agent auto-generates execution plans in `specs/` when features are complex +- Uses `specs/PLANS.md` as template +- Creates files like `specs/notification-system.md`, `specs/auth-refactor.md`, etc. +- Updates `specs/README.md` with links to all specs --- @@ -77,24 +147,40 @@ Once configured, templates provide context for **every request** automatically. ``` . -├── AGENTS.md # Agents Memory (Github Copilot, Codex, Cursor, Windsurf) -├── CLAUDE.md # Claude Code Memory -├── specs/ # Feature plans -│ └── PLANS.md # Execution plan template -├── .vscode/ # Optional: VSCode settings for AI agents -│ └── mcp.json # MCP configuration for GitHub Copilot and other agents -├── .mcp.json # MCP configuration for Claude Code +├── AGENTS.md # Agent memory (all agents) +├── CLAUDE.md # Claude Code memory +├── specs/ # Feature plans & templates +│ ├── PLANS.md # Template for execution plans +│ └── README.md # Index of all specs +├── .ralph/ # Autonomous execution scripts (optional) +│ ├── prompt.md # Your instructions for Ralph +│ ├── sync.sh # Single iteration +│ └── ralph.sh # Continuous loop +├── .vscode/ # VSCode settings (optional) +└── .mcp.json # MCP config (optional) ``` --- ## FAQ -**Q: What if I have an existing project?** -A: Already handled by the agent instructions. Just add all the repo files to your project and run your coding agent. Make sure to have the `AGENTS.md` or `CLAUDE.md` files copied from this repo so that your coding agent knows how to setup skills and sub-agents. +**Q: Can I use this with an existing project?** +A: Yes! Copy the required files (AGENTS.md/CLAUDE.md and specs/) to your project root, then tell your agent: *"Set up Superpowers skills and sub-agent support for this project"*. The agent will analyze your codebase and populate the templates automatically. + +**Q: Which file should I use - AGENTS.md or CLAUDE.md?** +A: Use `CLAUDE.md` for Claude Code (includes ExecPlan workflow). Use `AGENTS.md` for other agents (Cursor, Windsurf, GitHub Copilot, Codex). + +**Q: Do I need to write execution plans manually?** +A: No. The agent auto-generates plans in `specs/` only when needed for complex features. Simple tasks execute immediately using TDD. The agent uses `specs/PLANS.md` as a template when creating new execution plans. + +**Q: How do I use the specs/ directory?** +A: Copy the entire `specs/` directory to your project. When you ask the agent to implement complex features, it will automatically create execution plans in `specs/` (like `specs/notification-system.md`) using the `PLANS.md` template. You don't manually create these - the agent does. + +**Q: Do I need Ralph Wiggum (.ralph/) for basic usage?** +A: Ralph is optional and only needed if you want autonomous overnight development. --- **License:** MIT -**Credits:** PLANS.md based on [OpenAI's Codex Execution Plans](https://github.com/openai/openai-cookbook/blob/main/articles/codex_exec_plans.md) +**Credits:** [Superpowers](https://github.com/obra/superpowers) • [Anthropic Skills](https://github.com/anthropics/skills) • [OpenAI Codex Plans](https://github.com/openai/openai-cookbook/blob/main/articles/codex_exec_plans.md) • [Ralph Wiggum](https://ghuntley.com/ralph/) • [repomirror](https://github.com/repomirrorhq/repomirror)