archon/archon-example-workflow/README.md

Archon AI Coding Workflow Template

A simple yet reliable template for systematic AI-assisted development using create-plan and execute-plan workflows, powered by Archon - the open-source AI coding command center. Build on top of this and create your own AI coding workflows!

What is This?

This is a reusable workflow template that brings structure and reliability to AI coding assistants. Instead of ad-hoc prompting, you get:

• Systematic planning from requirements to implementation
• Knowledge-augmented development via Archon's RAG capabilities
• Task management integration for progress tracking
• Specialized subagents for analysis and validation
• Codebase consistency through pattern analysis

Works with Claude Code, Cursor, Windsurf, Codex, and any AI coding assistant that supports custom commands or prompt templates.

Core Workflows

1. Create Plan (/create-plan)

Transform requirements into actionable implementation plans through systematic research and analysis.

What it does:

• Reads your requirements document
• Searches Archon's knowledge base for best practices and patterns
• Analyzes your codebase using the codebase-analyst subagent
• Produces a comprehensive implementation plan (PRP) with:
  • Task breakdown with dependencies and effort estimates
  • Technical architecture and integration points
  • Code references and patterns to follow
  • Testing strategy and success criteria

Usage:

/create-plan requirements/my-feature.md

2. Execute Plan (/execute-plan)

Execute implementation plans with integrated Archon task management and validation.

What it does:

• Reads your implementation plan
• Creates an Archon project and tasks automatically
• Implements each task systematically (todo → doing → review → done)
• Validates with the validator subagent to create unit tests
• Tracks progress throughout with full visibility

Usage:

/execute-plan PRPs/my-feature.md

Why Archon?

Archon is an open-source AI coding OS that provides:

• Knowledge Base: RAG-powered search across documentation, PDFs, and crawled websites
• Task Management: Hierarchical projects with AI-assisted task creation and tracking
• Smart Search: Hybrid search with contextual embeddings and reranking
• Multi-Agent Support: Connect multiple AI assistants to shared context
• Model Context Protocol: Standard MCP server for seamless integration

Think of it as the command center that keeps your AI coding assistant informed and organized.

What's Included

.claude/
├── commands/
│   ├── create-plan.md      # Requirements → Implementation plan
│   ├── execute-plan.md     # Plan → Tracked implementation
│   └── primer.md           # Project context loader
├── agents/
│   ├── codebase-analyst.md # Pattern analysis specialist
│   └── validator.md        # Testing specialist
└── CLAUDE.md               # Archon-first workflow rules

Setup Instructions

For Claude Code

1. Copy the template to your project:

   cp -r use-cases/archon-example-workflow/.claude /path/to/your-project/
   

2. Install Archon MCP server (if not already installed):

   • Follow instructions at github.com/coleam00/Archon
   • Configure in your Claude Code settings

3. Start using workflows:

   # In Claude Code
   /create-plan requirements/your-feature.md
   # Review the generated plan, then:
   /execute-plan PRPs/your-feature.md
   

For Other AI Assistants

The workflows are just markdown prompt templates - adapt them to your tool - examples:

Cursor / Windsurf

• Copy files to .cursor/ or .windsurf/ directory
• Use as custom commands or rules files
• Manually invoke workflows by copying prompt content

Cline / Aider / Continue.dev

• Save workflows as prompt templates
• Reference them in your session context
• Adapt the MCP tool calls to your tool's API

Generic Usage

Even without tool-specific integrations:

1. Read create-plan.md and follow its steps manually
2. Use Archon's web UI for task management if MCP isn't available
3. Adapt the workflow structure to your assistant's capabilities

Workflow in Action

New Project Example

# 1. Write requirements
echo "Build a REST API for user authentication" > requirements/auth-api.md

# 2. Create plan
/create-plan requirements/auth-api.md
# → AI searches Archon knowledge base for JWT best practices
# → AI analyzes your codebase patterns
# → Generates PRPs/auth-api.md with 12 tasks

# 3. Execute plan
/execute-plan PRPs/auth-api.md
# → Creates Archon project "Authentication API"
# → Creates 12 tasks in Archon
# → Implements task-by-task with status tracking
# → Runs validator subagent for unit tests
# → Marks tasks done as they complete

Existing Project Example

# 1. Create feature requirements
# 2. Run create-plan (it analyzes existing codebase)
/create-plan requirements/new-feature.md
# → Discovers existing patterns from your code
# → Suggests integration points
# → Follows your project's conventions

# 3. Execute with existing Archon project
# Edit execute-plan.md to reference project ID or let it create new one
/execute-plan PRPs/new-feature.md

Key Benefits

For New Projects

• Pattern establishment: AI learns and documents your conventions
• Structured foundation: Plans prevent scope creep and missed requirements
• Knowledge integration: Leverage best practices from day one

For Existing Projects

• Convention adherence: Codebase analysis ensures consistency
• Incremental enhancement: Add features that fit naturally
• Context retention: Archon keeps project history and patterns

Customization

Adapt the Workflows

Edit the markdown files to match your needs - examples:

• Change task granularity in create-plan.md (Step 3.1)
• Add custom validation in execute-plan.md (Step 6)
• Modify report format in either workflow
• Add your own subagents for specialized tasks

Extend with Subagents

Create new specialized agents in .claude/agents/:

---
name: "security-auditor"
description: "Reviews code for security vulnerabilities"
tools: Read, Grep, Bash
---

You are a security specialist who reviews code for...

Then reference in your workflows.