npm package: @hanyolo/agentic-framework
Description: Universal AI-powered development framework for building any project with Claude Code assistance
Author: Matt Soave
Latest version: 1.0.0

# 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

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

Or use directly with npx:

```bash
npx @mattsoave/agentic-framework-wordpress init
```

## Quick Start

### 1. Initialize a New Project

```bash
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

```bash
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:
```bash
afw verify
```

Run tests:
```bash
afw test
```

Code review:
```
/review
```

Mark complete:
```
/done
```

### 7. Check Progress

```bash
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:
```json
{
  "name": "My Plugin",
  "type": "wordpress-plugin",
  "textDomain": "my-plugin",
  "description": "...",
  "stack": {"php": "^8.0", "wordpress": "6.4"},
  "testCommand": "composer test"
}
```

**tasks.json** - Task breakdown:
```json
{
  "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

```bash
# 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

```bash
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:

```typescript
// 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`:
```markdown
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:

```php
// 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:
```bash
afw init --template my-template
```

### Custom Slash Commands

Add to `.claude/commands/`:

```markdown
# /my-command

You are Claude, doing X.

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

### Custom Agents

```typescript
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

```bash
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](https://github.com/mattsoave/agentic-framework-wordpress/issues)
- **Discussions:** [GitHub Discussions](https://github.com/mattsoave/agentic-framework-wordpress/discussions)

## Credits

Built with ❤️ using Claude AI and Cursor IDE.

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