Agentic Framework - Universal Project Builder

AI-powered development framework for building any project type with Claude Code assistance.

Overview

The Agentic Framework creates a simple but powerful workflow for building any project with AI assistance. Works with:

• ✅ WordPress Plugins - OOP architecture, PHPUnit, Composer
• ✅ React WebApps - React + TypeScript + Vite + modern state management
• ✅ Next.js Apps - App Router, Server Components, auth, database
• ✅ Node.js APIs - Express/Fastify REST APIs with TypeScript
• ✅ Python FastAPI - Async Python APIs with SQLAlchemy

Instead of complex orchestration loops, it uses:

• State files (.agentic/) that Claude reads and writes
• Intelligent slash commands (.claude/commands/) that guide Claude's behavior
• Simple CLI (afw) for running tests, verifying changes, and checking status

Philosophy

No API calls, no orchestration loops, no complex logic. Claude in Cursor IDE is the orchestrator. The framework provides:

1. Universal template system - 5+ project types out of the box
2. State structure - Files that track project, tasks, and progress
3. Slash commands - AI prompts that adapt to your project type
4. CLI helpers - Simple commands to verify work and run tests
5. Quality gates - Blocks skipping important steps (verify/test/review)
6. Proactive guidance - Claude tells you when to run CLI commands

Installation

npm install -g @mattsoave/agentic-framework-wordpress

Or use directly with npx:

npx @mattsoave/agentic-framework-wordpress init

Quick Start

1. Initialize a New Project

cd my-project
afw init

# Select template
📋 Available project templates:
   1. WordPress Plugin - WordPress plugin with OOP architecture
   2. React WebApp - React + TypeScript + Vite application
   3. Next.js App - Next.js 14+ with App Router
   4. Node.js API - Express/Fastify REST API with TypeScript
   5. Python FastAPI - FastAPI REST API with SQLAlchemy

Select template (1-5): 2

# Answer prompts
App name: My Dashboard
Package name: my-dashboard
Description: Admin dashboard for analytics
Author name: Your Name
State management (zustand/redux/context): zustand
Styling (tailwind/css-modules/styled-components): tailwind

✅ Initialization complete!

This creates:

• .agentic/ - State files (project.json, tasks.json, etc.)
• .claude/commands/ - Slash commands adapted to your project type
• Project structure (based on selected template)

2. Open in Cursor IDE

cursor .

3. Start Brainstorming

In Claude, run:

/brainstorm

Claude becomes an expert consultant for your stack:

• React WebApp: Asks about state, routing, auth, forms, styling, performance
• Next.js App: Covers App Router, Server Components, database, auth, caching
• Node.js API: Discusses endpoints, auth, validation, database, API docs
• WordPress Plugin: Probes hooks, CPTs, security, performance, admin UI
• Python FastAPI: Covers async, Pydantic, SQLAlchemy, auth, deployment

Claude will:

• Ask strategic architectural questions
• Challenge assumptions
• Spot knowledge gaps (API costs, security, performance)
• Warn about common mistakes
• Suggest framework-specific best practices

After conversation, Claude writes:

• .agentic/requirements.md - Detailed requirements with edge cases
• .agentic/architecture.md - Technical decisions and patterns
• .agentic/schema.md - WordPress code examples

4. Plan the Work

/plan

Claude breaks down requirements into 30-80 granular tasks:

• Each task: 1-3 hours
• Specific files to modify
• Testable acceptance criteria
• WordPress APIs to use
• Security considerations
• Dependencies mapped

Result: .agentic/tasks.json with complete task breakdown

5. Execute Tasks

Pick next task:

/next

Get guidance before coding:

/review-approach

Generate code (or write manually):

/implement

6. Verify and Test

Check file scope:

afw verify

Run tests:

afw test

Code review:

/review

Mark complete:

/done

7. Check Progress

afw status

Shows:

• Overall progress (tasks done/total)
• Current task
• Next tasks
• Time estimates
• Phase breakdown

Workflow

/brainstorm → /plan → /next → /review-approach → /implement → afw verify → afw test → /review → /done → /next

Slash Commands (in Claude)

| Command | Purpose | |---------|---------| | /brainstorm | Expert WordPress consultation to define requirements | | /plan | Break down requirements into 30-80 tasks | | /next | Pick next actionable task | | /review-approach | Get WordPress-specific coding guidance | | /implement | Generate production-ready code | | /review | Code quality and security review | | /done | Mark task complete and update state |

CLI Commands (in terminal)

| Command | Purpose | |---------|---------| | afw init | Initialize new WordPress plugin project | | afw verify | Check modified files match current task | | afw test | Run PHPUnit test suite | | afw status | Show project progress dashboard |

How It Works

State Files (.agentic/)

project.json - Project metadata:

{
  "name": "My Plugin",
  "type": "wordpress-plugin",
  "textDomain": "my-plugin",
  "description": "...",
  "stack": {"php": "^8.0", "wordpress": "6.4"},
  "testCommand": "composer test"
}

tasks.json - Task breakdown:

{
  "tasks": [
    {
      "id": "001",
      "title": "Setup plugin structure",
      "status": "todo",
      "estimateHours": 2,
      "files": ["my-plugin.php", "includes/class-loader.php"],
      "acceptanceCriteria": ["Plugin activates", "Tests pass"],
      "dependencies": [],
      "wordpressAPIs": ["register_activation_hook"]
    }
  ],
  "stats": {"total": 42, "done": 0, "todo": 42}
}

current-task.json - Active task (or null)

requirements.md - Detailed requirements from brainstorming

architecture.md - Technical decisions

schema.md - WordPress code patterns

Slash Commands (.claude/commands/)

Each slash command is a markdown file with instructions for Claude:

brainstorm.md - Become WordPress expert consultant

• Probe for missing details
• Challenge assumptions
• Warn about pitfalls
• Suggest better approaches

plan.md - Task architect

• Break into 30-80 tasks
• Sequence dependencies
• Estimate complexity
• Define acceptance criteria

review-approach.md - Pre-coding advisor

• Show correct WordPress patterns
• Warn about anti-patterns
• Security checklist
• Performance considerations

implement.md - Code generator

• Generate production-ready code
• WordPress coding standards
• Security built-in
• Comprehensive tests

review.md - Code quality inspector

• Security scan (XSS, SQL injection, CSRF)
• WordPress best practices
• Performance issues
• Acceptance criteria check

done.md - Completion manager

• Quality gates (tests, review, scope)
• Update state
• Suggest commit message
• Show progress

Example: AI Content Plugin

# Initialize
afw init

# In Claude
/brainstorm

Claude asks:

• "AI content generation costs $0.002/1K tokens. Budget?"
• "What if OpenAI is down? Fallback?"
• "Real-time or on-demand?"
• "Where's the undo/version history?"

Claude writes requirements.md with cost estimates, error handling, UX flows.

/plan

Claude creates 45 tasks:

1. Setup plugin structure (2h)
2. Register AI content CPT (2h)
3. Create OpenAI API client (3h)
4. Add rate limiting (2h)
5. Build rewrite block (4h) ...

/next

Shows Task 001: Setup plugin structure

/review-approach

Claude shows:

• Correct plugin header format
• PSR-4 autoloading pattern
• Activation hook usage
• Test structure

/implement

Generates:

• my-plugin.php with proper header
• includes/class-loader.php with autoloader
• tests/test-autoloading.php with tests

afw verify  # ✅ All files in scope
afw test    # ✅ 3/3 tests pass

/review

Claude checks:

• ✅ WordPress coding standards
• ✅ Security checks
• ✅ Acceptance criteria met

/done

Task marked complete. Suggests commit message.

/next

Task 002: Register AI content CPT...

Architecture

Simple CLI (afw)

The CLI is just a thin wrapper around agents:

// src/core/Supervisor.ts
const agents = [
  new InitAgent(),
  new VerifyAgent(),
  new TestAgent(),
  new StatusAgent()
];

const agent = agents.find(a => a.meta.commands.includes(cmd));
await agent.run(context);

Each agent reads/writes state files. No complex logic.

Agents

InitAgent - Creates .agentic/, .claude/commands/, scaffolds plugin

VerifyAgent - Compares git status to current task files

TestAgent - Runs composer test (or project.testCommand)

StatusAgent - Reads tasks.json, displays progress

Slash Commands

Pure AI prompts. No code execution. Claude reads them and acts accordingly.

The intelligence is in the prompts, not the framework.

Example from review-approach.md:

You are Claude, preventing developers from building things the wrong way.

For REST API tasks, remind them:
- permission_callback is required (developers forget 90% of time)
- Sanitize all inputs
- Handle API timeouts

WordPress-Specific Features

Expert Knowledge

Claude slash commands encode WordPress expertise:

• Security patterns - Nonces, capability checks, sanitization, escaping
• Performance traps - N+1 queries, missing indexes, poor caching
• Common mistakes - Custom tables vs CPT, real-time vs polling
• API costs - OpenAI, image APIs, rate limits
• Testing patterns - PHPUnit with WordPress test environment

Code Generation

/implement generates production-ready WordPress code:

// Automatically includes:
- Nonce verification
- Capability checks
- Input sanitization
- Output escaping
- Error handling
- Translation ready
- PHPDoc comments
- Comprehensive tests

Quality Gates

/review catches issues before production:

• Unsanitized input (XSS vulnerability)
• Unescaped output (XSS vulnerability)
• Missing nonces (CSRF vulnerability)
• Missing capability checks (unauthorized access)
• SQL without $wpdb->prepare() (SQL injection)
• Missing permission_callback (public REST endpoint)

Advanced Usage

Custom Templates

Add your own in templates/my-template/:

templates/my-template/
  project.json
  architecture.md
  schema.md

Use with:

afw init --template my-template

Custom Slash Commands

Add to .claude/commands/:

# /my-command

You are Claude, doing X.

Read: .agentic/project.json
Do: Y
Write: .agentic/output.json

Custom Agents

import { Agent, Context } from '@mattsoave/agentic-framework-wordpress';

export class MyAgent extends Agent {
  meta = { name: 'my-agent', commands: ['my-command'] };

  async run(ctx: Context) {
    // Read state
    const project = ctx.state.loadProject();

    // Do work
    await ctx.exec('wp', ['cli', 'command']);

    // Return result
    return { success: true, message: 'Done' };
  }
}

Philosophy & Design

Why This Architecture?

Problem: Existing agentic frameworks are complex:

• API calls for every decision
• Orchestration loops with retries
• Complex state machines
• Hard to debug

Solution: Let Claude in Cursor IDE be the orchestrator:

• Claude reads state files
• Claude follows slash command instructions
• CLI just runs tests/verifications
• Simple, transparent, debuggable

Why No API Calls?

Claude in Cursor already has:

• File reading/writing
• Command execution
• Conversational memory
• Tool use

Why duplicate this? Just give Claude:

• State structure to read/write
• Instructions (slash commands)
• Helpers for verification

Why Slash Commands?

They're just markdown files with instructions. Anyone can:

• Read them
• Modify them
• Add new ones
• Share them

No code required. The intelligence is in the prompts.

Comparison

| Feature | Agentic Framework | Traditional | |---------|------------------|-------------| | Orchestration | Claude in Cursor | You write loops | | State | JSON files | Code/database | | Intelligence | Slash commands (prompts) | Hardcoded logic | | Customization | Edit markdown | Write code | | Debugging | Read state files | Debug code | | Setup | afw init | Hours of setup |

Contributing

Contributions welcome!

Areas for Contribution

• Slash commands - Improve WordPress expertise
• Templates - New project types (theme, block, etc.)
• Agents - New CLI helpers
• Documentation - Guides, examples, tutorials

Development

git clone https://github.com/mattsoave/agentic-framework-wordpress
cd agentic-framework-wordpress
npm install
npm run build
npm link  # Test locally

License

MIT

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

Credits

Built with ❤️ using Claude AI and Cursor IDE.

Inspired by the need for simpler, more transparent agentic workflows.