# WP Agentic Writer - Development Brief

**Product Name:** WP Agentic Writer  
**Tagline:** Plan-first AI writing workflow for WordPress  
**Target Users:** Developers, Technical Writers, Content Creators who struggle with blogging  
**Status:** MVP Development  
**Date Created:** January 17, 2026

---

## 🎯 Product Overview

**WP Agentic Writer** is a WordPress plugin that transforms how developers and technical writers create blog posts. Instead of the traditional "blank page → write → edit" workflow, it implements a **multi-phase agentic AI workflow**:

```
Scribble (Ideas) → Research → Plan (Outline) → Execute (Write) → Discussion/Revise
```

**Key Insight:** Most developers never write articles because writing feels separate from coding. This plugin makes the workflow feel like coding—iterative, phase-based, with revision at every step.

---

## 📋 Core Features (MVP)

### Phase 1: Brainstorm & Scribble
- **User inputs:** Raw notes, code snippets, PR description, or vague idea
- **AI does:** Clarifies the angle, suggests what problem this solves
- **Output:** Structured brainstorm notes

### Phase 2: Research
- **User inputs:** Confirms the angle or edits AI suggestions
- **AI does:** Generates research queries, pulls relevant information (optional web search)
- **Output:** Research notes, citations, key points
- **Display:** Real-time cost tracking
- **Web Search:** Optional toggle using OpenRouter's built-in web search (:online models)

### Phase 3: Plan (Outline)
- **User inputs:** Reviews outline, suggests sections to add/remove/reorganize
- **AI does:** Structures as JSON with H2 sections, suggests code examples
- **Output:** Plan JSON (see structure below)
- **Cost:** Minimal (using fast, cheap model like Gemini Flash)

### Phase 4: Execute (Auto-Write)
- **User inputs:** Approves plan, clicks "Execute"
- **AI does:** Generates final article with:
  - Paragraph blocks
  - Code blocks (with language detection)
  - Optional image prompts
- **Output:** Gutenberg blocks inserted into editor canvas
- **Cost:** Higher quality model (Claude Opus) for best output

### Phase 5: Discuss & Revise
- **User inputs:** Click "Regenerate Section" on any block
- **AI does:** Re-generates just that block based on selected text context
- **Features:**
  - Section-level chat
  - Line-by-line refinement
  - Change entire paragraphs or code blocks

---

## 💰 Cost Architecture

### Models Strategy

**Planning Model:** `google/gemini-3-flash` (Free on OpenRouter)
- Cost: ~$0.0007 per planning session
- Speed: Very fast
- Quality: Good enough for outlining

**Execution Model:** `anthropic/claude-4-opus` (Paid on OpenRouter)
- Cost: ~$0.633 per full article write
- Speed: Medium
- Quality: Excellent prose, code understanding

**Image Generation Model:** `black-forest-labs/flux-schnell` (via fal.ai free tier or OpenRouter)
- Cost: ~$0.04 per image (paid option)
- Cost: $0.00 (free tier fal.ai with 100 credits/month = 25-50 images)
- Speed: <2 seconds
- Quality: Excellent for developer blogs

### Cost Breakdown Per Article (2,500 words)

```
Planning (Gemini Flash):    $0.0007 (free tier alternative: $0.00)
Research (Web Search):      $0.02 (optional, Exa search)
Writing (Claude Opus):      $0.633
Image (Flux Schnell):       $0.04 (free tier alternative: $0.00)
OpenRouter platform fee:    ~$0.034
─────────────────────────────────────
TOTAL:                      ~$0.72 per article (paid tier with research)
TOTAL (No research):        ~$0.70 per article (paid tier)
TOTAL (Free tier):          ~$0.00 per article
```

### User Cost Scenarios

| User Type | Articles/Month | Paid Cost | Free Tier |
|-----------|---|---|---|
| **Solo Dev Blogger** | 10 | $7.00 | Free (limited) |
| **Agency Content** | 50 | $35.00 | Free (limited) |
| **Company Blog** | 200 | $140.00 | Free (limited) |

---

## 🔌 Integration: OpenRouter

### Why OpenRouter?

✅ **Single API Key** - No juggling Claude + Gemini + GPT
✅ **Model Flexibility** - Switch models in settings, no code changes
✅ **Unified Cost Tracking** - OpenRouter returns exact token costs per request
✅ **25+ Free Models** - Full plugin works without credit card
✅ **Built-in Web Search** - Add `:online` to any model for real-time research
✅ **Transparent Pricing** - 5.5% platform fee on all models

### Settings Page (One Simple Input)

```
WP Agentic Writer Settings
├─ OpenRouter API Key: [___________________]
├─ Planning Model: google/gemini-3-flash ▼
├─ Execution Model: anthropic/claude-4-opus ▼
├─ Image Model: black-forest-labs/flux-schnell ▼
├─ Research Phase:
│  ◉ Enable Web Search (~$0.02 per search)
│  ○ Disabled (use LLM knowledge only)
│  └─ Search Engine: [Auto ▼] (Native or Exa fallback)
│  └─ Search Depth: [Medium ▼] (Low/Medium/High)
└─ Cost Tracking: ON ✓
```

---

## 🎨 Gutenberg Integration

### Sidebar Chat Interface

**During Planning:**
```
Sidebar shows:
┌─────────────────────────────┐
│ WP Agentic Writer            │
├─────────────────────────────┤
│                             │
│ > I built a PHP plugin      │
│   that handles OAuth...     │
│                             │
│ < Agentic AI (Gemini)       │
│   Planning $0.0007          │
│   This is really about      │
│   "Auth abstraction for     │
│   WordPress", correct?      │
│                             │
│ > Yes, exactly!             │
│                             │
│ [Regenerate Plan] [Execute] │
└─────────────────────────────┘
```

**During Execution:**
```
Canvas shows:
[Paragraph block] ← Regenerate This
"Here's how OAuth works in WordPress..."

[Code block] ← Regenerate This
function auth_provider() { ... }

[Paragraph block] ← Regenerate This
"Notice the abstraction layer..."

Sidebar: "Article generated in 3.5s | Cost: $0.633"
```

### Block Operations

**Each Gutenberg block gets:**
- "Regenerate" button (re-runs AI for that section only)
- "Refine" button (opens sidebar chat for that block)
- Visual cost indicator per block

---

## 📊 Plan JSON Structure

```json
{
  "title": "OAuth Plugin Architecture for WordPress",
  "meta": {
    "reading_time": "5 min",
    "difficulty": "intermediate",
    "cost_estimate": 0.70
  },
  "sections": [
    {
      "id": "intro",
      "type": "section",
      "heading": "The Problem: Auth Abstraction",
      "content": [
        {
          "type": "paragraph",
          "content": "Building flexible auth systems..."
        },
        {
          "type": "code",
          "language": "php",
          "content": "interface AuthProvider { ... }",
          "caption": "Provider interface pattern"
        },
        {
          "type": "paragraph",
          "content": "This pattern allows switching..."
        }
      ]
    },
    {
      "id": "implementation",
      "type": "section",
      "heading": "Step-by-Step Implementation",
      "content": [
        {
          "type": "ordered_list",
          "items": [
            "Define provider interface",
            "Implement concrete providers",
            "Create abstraction layer"
          ]
        }
      ]
    },
    {
      "id": "image_section",
      "type": "section",
      "image_prompt": "WordPress OAuth architecture diagram with abstraction layers, clean technical aesthetic, light colors",
      "image_alt": "OAuth architecture flowchart"
    }
  ],
  "citations": [
    {
      "id": 1,
      "text": "OAuth 2.0 specification",
      "url": "https://..."
    }
  ]
}
```

---

## 💾 Cost Tracking Display

### Real-Time Sidebar

```
Today's Usage:
──────────────────────────
Planning:      4,700 tokens  $0.0007
Writing:       7,500 tokens  $0.633
Images:        1 @ Flux      $0.04
──────────────────────────
Session Total:               $0.6737

Monthly Budget:
Used: $6.74 / $600 (1.1%)
Remaining: $593.26
```

### Per-Request Cost

Each API call logs:
- Model used
- Tokens in/out
- Cost (in real-time)
- Cumulative session cost

---

## 🔍 Web Search Strategy

### OpenRouter Built-in Web Search

**How it works:**
- Append `:online` to any model slug: `google/gemini-3-flash:online`
- OpenRouter automatically adds real-time web search results
- Supports native search (OpenAI, Anthropic, Perplexity, xAI) or Exa fallback
- Standardized citation format across all providers

### Cost Structure

| Search Type | Cost | Best For |
|-------------|------|----------|
| **No Search** | $0.00 | Evergreen topics, general knowledge |
| **Native Search** | Provider pricing | Premium research (OpenAI, Anthropic models) |
| **Exa Search** | $4 per 1,000 results = ~$0.02 per search | Most models, cost-effective research |

### Research Provider Options (Via OpenRouter)

| Option | Model | Cost | Quality | Best For |
|--------|-------|------|---------|----------|
| **Web Search ON** | `google/gemini-3-flash:online` | ~$0.02 + model cost | Real-time sources | Technical tutorials, recent topics |
| **Web Search OFF** | `google/gemini-3-flash` | Model cost only | Training data | Evergreen topics |
| **Premium Search** | `anthropic/claude-4-opus:online` | ~$0.05 + model cost | Best research | Professional articles |

### Implementation

```php
// Research with web search toggle
class OpenRouterProvider {
    private $web_search_enabled;
    private $search_engine = 'auto'; // native, exa, auto
    private $search_depth = 'medium'; // low, medium, high

    public function research($query) {
        $model = $this->planning_model;

        // Add :online suffix if web search enabled
        if ($this->web_search_enabled) {
            $model .= ':online';
        }

        $response = $this->chat([
            ['role' => 'user', 'content' => "Research this topic: {$query}"]
        ], [
            'model' => $model,
            'web_search_options' => [
                'search_context_size' => $this->search_depth,
                'max_results' => 5,
                'engine' => $this->search_engine
            ]
        ]);

        // Parse web search results from response
        $citations = $this->extractWebSearchResults($response);

        return [
            'content' => $response['content'],
            'citations' => $citations,
            'cost' => $response['cost']
        ];
    }
}
```

### User Workflow

**Scenario 1: Evergreen Topic**
```
User: "Write about basic OOP principles"
Research: Web Search OFF
→ Uses LLM's training data
Cost: $0.00 (no extra cost)
Time: ~2 seconds
```

**Scenario 2: Recent Tech Topic**
```
User: "Write about WordPress 6.7 new features"
Research: Web Search ON
→ Searches: "WordPress 6.7 new features 2025"
→ Returns: 5 relevant articles with citations
Cost: ~$0.02 (Exa search) + $0.0007 (model)
Time: ~5 seconds
```

### Settings Configuration

**Research Provider Selection:**
- **Enable Web Search** - Toggle on/off
- **Search Engine:**
  - `Auto` - Native if available, Exa fallback (recommended)
  - `Native` - Force provider's native search
  - `Exa` - Force Exa search
- **Search Depth:**
  - `Low` - Minimal context, basic queries
  - `Medium` - Moderate context, general queries (default)
  - `High` - Extensive context, detailed research

---

## 🖼️ Image Generation Strategy

### Recommendation: Multi-Tier Approach

#### **Tier 1: Free for Most Users**
**Provider:** fal.ai (via Replicate)  
**Model:** FLUX.1 Schnell (free tier)
- **Free Credits:** 100 credits/month (= ~25-50 images)
- **Generation Time:** <2 seconds
- **Quality:** Excellent for dev blogs
- **Setup:** Simple API integration
- **Cost:** $0.00

**When to use:**
- If user hasn't added OpenRouter key
- For quick placeholder images
- Personal/hobby blogs

#### **Tier 2: Premium via OpenRouter**
**Provider:** OpenRouter  
**Model:** `black-forest-labs/flux-schnell` or `flux-pro`
- **Cost:** ~$0.04 per image (schnell), ~$0.25 (pro)
- **Quality:** Highest quality
- **Integration:** Same API key as text models
- **User Control:** Settings dropdown to pick Schnell vs Pro

**When to use:**
- User has OpenRouter API key
- Premium blogs/companies
- High-quality images needed

### Implementation

```javascript
// Image generation in Execute phase

const imagePrompt = plan.sections
  .filter(s => s.image_prompt)
  .map(s => ({
    section: s.id,
    prompt: s.image_prompt,
    model: userSettings.imageModel // schnell or pro
  }));

// Generate images via OpenRouter or fal.ai
// Insert as Image blocks into Gutenberg
```

---

## 🆓 Free Tier Strategy

### What Works for Free (No Credit Card)

**25+ Free Models on OpenRouter:**

**Best for Planning:**
- `xiaomi/mimo-v2-flash` - Top #1 open-source, Claude Sonnet 4.5 quality
- `mistralai/mistral-devstral-2` - Excellent agentic coding
- `deepseek/r1t2-chimera` - Strong reasoning

**Best for Writing:**
- `meta-llama/llama-3.3-70b` - GPT-4 level quality
- `qwen/qwen3-coder-480b` - Technical writing excellence

**Best for Images:**
- fal.ai free tier: 100 credits/month
- Replicate: 50 free generations/month with FLUX.1

### Free Tier Limitations

```
✅ No credit card required
✅ 25+ models available  
✅ Full plugin functionality
✅ Rate limits: ~50 requests/day (= 5+ articles)
❌ Shared infrastructure (queue during peak)
❌ No premium models (Claude Opus, etc.)
```

### Upsell Path

**Sidebar messaging:**
```
"Using Free Tier (30 requests remaining today)"

"Upgrade to OpenRouter ($0.67/article with premium models)"
 [Add API Key] [Learn More]
```

**Settings page:**
```
Tier Selection:
○ Free Tier (25+ models, slow during peak)
◉ Pro Tier (300+ models, priority queue) - Add OpenRouter Key
```

---

## 🏗️ Technical Architecture

### WordPress Plugin Structure

```
wp-agentic-writer/
├── wp-agentic-writer.php (main plugin file)
├── includes/
│   ├── class-openrouter-provider.php (AI provider)
│   ├── class-gutenberg-sidebar.php (React sidebar)
│   ├── class-cost-tracker.php (cost display)
│   └── class-plan-generator.php (plan logic)
├── assets/
│   ├── js/
│   │   ├── sidebar.js (React component)
│   │   └── blocks.js (Gutenberg integration)
│   └── css/
│       └── sidebar.css
├── admin/
│   └── settings.php (Settings page with API key input)
└── tests/
    └── test-openrouter.php
```

### Key Classes

**OpenRouterProvider**
```php
class OpenRouterProvider {
  - setApiKey($key)
  - setModel($type, $model)  // type: "planning" or "execution"
  - enableWebSearch($enabled, $engine, $depth)
  - chat($messages, $options)  // returns response + cost
  - generateImage($prompt)
  - getModelList()
  - getCostBreakdown()
}
```

**GutenbergSidebar**
```js
- useChat()  // maintains conversation history
- usePlan()  // stores plan JSON
- useBlockRegen()  // regenerate specific block
- useCostTracker()  // real-time cost display
```

**CostTracker**
```php
- addRequest($model, $input_tokens, $output_tokens, $cost)
- getSessionTotal()
- getMonthlyTotal()
- formatDisplay()
```

---

## 📅 Development Roadmap (4 Weeks)

### **Week 1: Core Setup**
- [ ] OpenRouter integration + cost tracking
- [ ] Settings page (API key + model selection)
- [ ] Gutenberg sidebar UI (chat interface)
- [ ] Phase 1 & 2: Scribble → Research

**Deliverable:** User can chat in sidebar, see costs

### **Week 2: Planning & Execution**
- [ ] Plan JSON generation from research
- [ ] Plan editor in sidebar
- [ ] Execute phase: Convert plan → Gutenberg blocks
- [ ] Code block insertion with language detection

**Deliverable:** User can generate article blocks automatically

### **Week 3: Refinement & Images**
- [ ] Block-level regeneration
- [ ] Section-level chat refinement
- [ ] Image generation integration (fal.ai + OpenRouter)
- [ ] Image block insertion

**Deliverable:** Full 5-phase workflow functional

### **Week 4: Polish & Launch**
- [ ] Cost tracking display (sidebar + settings)
- [ ] Free tier messaging + upsell
- [ ] Documentation (README, setup guide)
- [ ] Testing + bug fixes

**Deliverable:** Production-ready MVP

---

## 🚀 Launch Checklist

### Plugin Preparation
- [ ] Prefix all functions/classes with `wp_agentic_writer_`
- [ ] Add proper nonces for security
- [ ] Sanitize all user inputs
- [ ] Add error handling + user feedback
- [ ] Include .pot file for translations
- [ ] Test on WordPress 6.6+
- [ ] Test with Gutenberg editor

### Documentation
- [ ] README.md with setup instructions
- [ ] Inline code comments
- [ ] Troubleshooting guide
- [ ] FAQ for developers

### Distribution
- [ ] WordPress.org plugin listing
- [ ] GitHub repository
- [ ] Demo video showing workflow

---

## 📝 User Workflow Example

### Scenario: Dev Writes OAuth Article

```
1. Opens WordPress editor
2. Clicks "Start Agentic Writing" in sidebar
3. Types: "I built an OAuth provider plugin for WordPress, want to write about it"

4. AI (Planning Model - Free): 
   "This is about flexible authentication abstraction, yes? 
    Key angles: Architecture pattern, Step-by-step implementation, 
    Comparison to built-in WP auth"

5. User confirms: "Yes, but add performance considerations too"

6. AI generates plan in 8 seconds (JSON outline)
   Cost shown: $0.0007

7. User reviews outline in sidebar
   - Sees H2 sections, estimated code blocks
   - Adds "Security Tips" section
   - Removes redundant section

8. Clicks [Execute Article]

9. AI (Execution Model - Claude):
   - Generates prose for each section
   - Pulls code examples
   - Generates tech blog image
   
   Takes 45 seconds, Cost: $0.634

10. Canvas fills with:
    - Paragraph blocks
    - Code blocks (highlighted)
    - Image block (auto-inserted)

11. User reviews in editor:
    - Reads through blocks
    - Clicks "Regenerate Section" on intro
    - Types refinement: "Make it more beginner-friendly"
    - AI re-writes just that section

12. User publishes

**Total time:** 3 minutes  
**Total cost:** ~$0.70  
**User satisfaction:** Very high (finally wrote the article!)
```

---

## 🎯 Success Metrics

### MVP Success Criteria
- [ ] Plugin installs without errors
- [ ] 5-phase workflow completes end-to-end
- [ ] Cost tracking accurate within 1%
- [ ] Free tier users can write 1+ articles/month
- [ ] Paid tier users save 2+ hours per article
- [ ] Block regeneration works on all content types

### Post-Launch Goals
- 100+ active installations
- 4.5+ star rating on WordPress.org
- Feature requests from real users
- Revenue from premium features (if applicable)

---

## 🔐 Security & Privacy Notes

### OpenRouter API Key Storage
- Store in WordPress options (prefixed)
- Encrypt sensitive data
- Add warning: "Never share your API key"

### User Data
- Plan JSON stored in post meta
- Cost history stored locally (not sent externally)
- Conversation history stored in post meta

### Compliance
- GDPR: User controls data, can delete anytime
- No tracking or analytics
- No external data collection

---

## 💡 Future Roadmap (Post-MVP)

### Phase 2 Features
- [ ] Multi-language support (generate in any language)
- [ ] SEO optimization (auto-generate meta descriptions, keywords)
- [ ] Social sharing templates
- [ ] Article scheduling
- [ ] Team collaboration (multiple editors)
- [ ] Template library (blog post templates, tutorials, case studies)

### Phase 3 Integration
- [ ] GitHub integration (auto-convert PR → blog post)
- [ ] Video script generation
- [ ] Podcast transcript → blog post
- [ ] Analytics dashboard

---

## 📚 Resources & References

- OpenRouter Docs: https://openrouter.ai/docs
- Gutenberg Handbook: https://developer.wordpress.org/block-editor/
- FLUX Image Generation: https://fal.ai/flux-2
- WordPress Plugin Development: https://developer.wordpress.org/plugins/

---

**Ready to build?** Start with Week 1 core setup. All tools are free for development with generous free tiers.

**Questions?** Refer to this brief as source of truth throughout development.