DevAgent coordinates a roster of specialized workflows that carry product ideas from mission alignment through research, specs, planning, and execution. The repo stores shared context, workflow briefs, and task hubs so every hand-off stays traceable.
DevAgent separates portable tools (core) from project-specific artifacts (workspace):
.devagent/core/- PORTABLE workflow kit with instruction sheets and templates. Copy to any project for 5-minute setup. See core/README.md for setup guide..devagent/workspace/- PROJECT-SPECIFIC mission, tasks, research, and decisions that evolve with your product.
This separation means you can reuse the workflow system across projects while keeping each product's context isolated.
- The update-product-mission workflow curates product direction inside
.devagent/workspace/product/while referencing long-term guardrails in.devagent/workspace/memory/overview.mdandconstitution.md. - The research and create-plan workflows work out of
.devagent/workspace/tasks/{status}/YYYY-MM-DD_task-slug/to keep discovery packets and plans co-located (where {status} is active, planned, or completed). - The create-plan workflow produces comprehensive plans combining product context and implementation tasks under
.devagent/workspace/tasks/{status}/YYYY-MM-DD_task-slug/plan/; all execution tracking happens via git commits and PR descriptions. - The parent
README.mdacts as the quick orientation surface; individual workflow briefs in.devagent/core/workflows/capture detailed workflows and filing rules.
.devagent/core/workflows/- Instruction sheets for each workflow (research.md,create-plan.md,update-product-mission.md, etc.)..devagent/core/templates/- Reusable document templates for research packets, specs, task plans, and task hubs..devagent/core/AGENTS.md- Quick reference roster showing when to invoke each workflow..devagent/core/README.md- Setup guide for initializing DevAgent in new projects..devagent/core/PLUGINS.md- Plugin system documentation.
.devagent/workspace/product/- Mission, roadmap, guiding questions, and other top-of-funnel product context..devagent/workspace/memory/- Long-lived principles (constitution.md), decision journal, tech stack, and extended overview (overview.md)..devagent/workspace/tasks/- Task hubs organized by status (active, planned, completed); copy.devagent/core/templates/task-hub-template/into the appropriate status directory with a dated slug (e.g.active/2025-09-30_task-slug) to start a new initiative and file research/spec artifacts with ISO dates..devagent/workspace/tasks/{status}/YYYY-MM-DD_task-slug/plan/- Plan documents combining product context and implementation tasks, stored alongside the research hub..devagent/workspace/research/- Cross-cutting research that spans multiple tasks.
.devagent/plugins/- Optional plugins that extend DevAgent functionality (e.g.,ralph/for autonomous execution).
- New to DevAgent? See .devagent/core/README.md for 5-minute setup instructions.
- First time using workflows? Read .devagent/DEVELOPER-GUIDE.md for step-by-step examples and best practices.
- Want to learn from experience? Check .devagent/learned-lessons.md for real-world usage patterns and common questions.
- Review relevant workflow brief(s) in
.devagent/core/workflows/before kicking off work. - For a new task or feature, use
devagent new-taskto scaffold a task hub, then follow the workflow sequence:devagent research→devagent clarify-task→devagent create-plan→devagent implement-plan. - Keep artifacts date-prefixed and cross-link research, plans, and exencution notes so downstream workflows have the full story.
- When mission or guardrails change, update
.devagent/workspace/product/and.devagent/workspace/memory/first, then notify affected task hubs.
The apps/ralph-monitoring app is a React Router 7 app. react-router build outputs:
apps/ralph-monitoring/build/client/(static assets +index.html)apps/ralph-monitoring/build/server/(SSR server bundle)
This repo adds a small Bun static server for the client build (SPA-style routing) so you can do a production-like build + serve locally.
From the repo root:
bun run build
bun run serve
# open http://localhost:3000You can change the port:
PORT=4000 bun run serveFor the dev server (hot reload), run:
bun run --cwd apps/ralph-monitoring dev
# open http://localhost:5173If you need SSR behavior, use the existing start script instead:
bun run --cwd apps/ralph-monitoring startPrereqs: tailscale installed + authenticated, and Funnel enabled for your tailnet.
- Start the local server (in one terminal):
# Static server for the production build (defaults to PORT=3000)
bun run serve- Expose it publicly (in another terminal):
# By default this targets PORT=3000 (matches `bun run serve`)
bun run preview:funnel
# If you want to funnel the dev server instead (react-router dev runs on 5173)
PORT=5173 bun run preview:funnelTailscale will print a public https://... URL.
To shut it down:
tailscale funnel off
# (you can keep the local server running, or Ctrl+C it)Security note: Funnel exposes your local preview to the public internet. Treat the URL as sensitive, and avoid funneling environments with secrets or admin-only features.
Use this map to select the right workflow chain based on your goal. Update this table when workflows change.
| Goal | Recommended Chain | Notes |
|---|---|---|
| Explore new feature ideas | brainstorm → research → create-plan |
Use exploratory mode for broad ideation. |
| Validate a fuzzy requirement | clarify-task → research → create-plan |
Use for requirement completeness checks. |
| Setup unified AI rules | setup-ai-rules |
Initializes ai-rules source hub. |
| Execute a full task end-to-end | execute-full-task |
Runs new-task through implement-plan. |
| Implement from an approved plan | implement-plan |
Requires a plan document path. |
| Archive a finished task hub | mark-task-complete |
Moves task from active to completed. |
The update-core.sh script works for both fresh installations and updates to existing installations:
For new installations:
# Download and run the install script from your project root
curl -fsSL https://raw.githubusercontent.com/lambda-curry/devagent/main/.devagent/core/scripts/update-core.sh | bashFor existing installations:
# Run the update script (if you already have DevAgent installed)
.devagent/core/scripts/update-core.shThis script:
- Automatically detects whether this is a fresh install or an update
- Performs a Git sparse checkout to fetch only the
.devagent/core/directory (and related files) - Creates a timestamped backup of your existing core before updating (for updates only)
- Replaces the local core with the latest version from the repository
- Provides clear feedback on the install/update process and next steps
To make DevAgent commands available in Cursor's command palette, paste this prompt into Cursor's chat:
Create the
.cursor/commands/directory if it doesn't exist, then create symlinks from.cursor/commands/to all files in.agents/commands/so that DevAgent workflows are accessible through Cursor's command palette. Use relative symlinks (e.g.,ln -sf ../.agents/commands/* .cursor/commands/).
After running this prompt, all DevAgent workflows will be accessible through Cursor's command palette. For more details, see .agents/commands/README.md.
For new installations: The script will install core files and provide setup instructions for creating your workspace.
For existing installations: Run this periodically to get the latest workflow improvements, workflow updates, and bug fixes.
DevAgent supports plugins that extend core functionality with optional features. Plugins can add workflows, commands, tools, and skills while keeping the core system lightweight.
The Ralph plugin enables autonomous execution of DevAgent plans using Beads-backed task management. It converts implementation plans into Beads task structures and orchestrates AI agents to execute tasks autonomously with quality gates and progress tracking.
Key Features:
- Converts DevAgent plans to Beads task hierarchies
- Autonomous execution loop with quality gate verification
- Task status tracking and progress synchronization
- Revision learning and improvement reporting
Documentation:
- Plugin instructions: .devagent/plugins/ralph/AGENTS.md
- Plugin system overview: .devagent/core/PLUGINS.md
For details on installing, configuring, and using plugins, see the plugin system documentation.
This project uses ai-rules to maintain consistent AI coding rules across all AI assistants (Cursor, Claude Code, GitHub Copilot, Opencode, etc.). The ai-rules/ directory serves as the source of truth for all AI coding guidelines.
To update AI rules:
- Edit source files in the
ai-rules/directory (e.g.,ai-rules/react-router-7.md,ai-rules/testing-best-practices.md) - Generate platform-specific files by running:
ai-rules generate
This command automatically generates the following files from the source rules:
CLAUDE.md- Rules for Claude CodeAGENTS.md- Rules for Opencode and other agents (copilot, codex, opencode, gemini).cursor/rules/*.mdc- Rules for Cursor.github/copilot-instructions.md- Symlink to AGENTS.md for GitHub Copilot
To verify that generated files are in sync with source files, run:
ai-rules statusThis will show the sync status for all configured agents:
- ✅
in sync- Generated files match source files ⚠️ out of sync- Source files have been modified and need regeneration
You can also check status for specific agents:
ai-rules status --agents claude,cursorThe ai-rules/ai-rules-config.yaml file configures which agents to generate rules for. The default configuration generates rules for all supported agents: claude, cursor, copilot, codex, opencode, and gemini.
- Never edit generated files directly (e.g.,
CLAUDE.md,.cursor/rules/*.mdc,AGENTS.md). These are build artifacts that will be overwritten when you runai-rules generate. - Always edit source files in
ai-rules/and then runai-rules generateto sync changes to all platforms. - Commit both source and generated files to ensure all team members have consistent AI rules across their tools.
DevAgent generates files in the .devagent/workspace/ directory that can be quite long (research packets, plans, task hubs, etc.). You have two options for managing these files in your repository:
If you're committing DevAgent files to your repository (useful for team collaboration and traceability), you can hide them from GitHub diffs by marking them as generated files. This keeps PR reviews clean while still preserving the files in version control.
Create or edit a .gitattributes file in your repository root:
# Mark DevAgent workspace files as generated to hide them in GitHub diffs
.devagent/workspace/** linguist-generatedThis uses GitHub's linguist-generated attribute to collapse these files by default in pull request diffs, making reviews more focused on code changes while still keeping the DevAgent artifacts available in the repository.
If you're working solo or prefer to keep DevAgent files local, add .devagent/workspace/ to your .gitignore:
# DevAgent workspace files (project-specific artifacts)
.devagent/workspace/Note: Only exclude .devagent/workspace/ (project-specific artifacts), not .devagent/core/ (the portable workflow kit that should be committed).
- .devagent/DEVELOPER-GUIDE.md – Comprehensive step-by-step guide with examples for implementing tasks using DevAgent workflows. Start here for your first task.
- .devagent/learned-lessons.md – Real-world lessons learned from first-time usage, including common questions, workflow patterns, and best practices.
.devagent/core/README.md– Setup guide for initializing DevAgent in new projects (< 5 minutes)..devagent/core/AGENTS.md– Workflow roster showing when to invoke each workflow..devagent/workspace/memory/overview.md– Explains the memory layering model and shared working agreements..devagent/core/templates/– Reusable shells for research packets, plans, and more.- Workflow instructions in
.devagent/core/workflows/explain when to invokedevagent update-product-mission,devagent research,devagent create-plan,devagent implement-plan, and other workflows.