Files

dwindown 97426d5ab1 first commit all files

2026-01-28 00:26:00 +07:00

20 KiB

Raw Blame History

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

{
  "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

// 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

// 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

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

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

CostTracker

- 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.

20 KiB Raw Blame History

WP Agentic Writer - Development Brief

🎯 Product Overview

📋 Core Features (MVP)

Phase 1: Brainstorm & Scribble

Phase 2: Research

Phase 3: Plan (Outline)

Phase 4: Execute (Auto-Write)

Phase 5: Discuss & Revise

💰 Cost Architecture

Models Strategy

Cost Breakdown Per Article (2,500 words)

User Cost Scenarios

🔌 Integration: OpenRouter

Why OpenRouter?

Settings Page (One Simple Input)

🎨 Gutenberg Integration

Sidebar Chat Interface

Block Operations

📊 Plan JSON Structure

💾 Cost Tracking Display

Real-Time Sidebar

Per-Request Cost

🔍 Web Search Strategy

OpenRouter Built-in Web Search

Cost Structure

Research Provider Options (Via OpenRouter)

Implementation

User Workflow

Settings Configuration

🖼️ Image Generation Strategy

Recommendation: Multi-Tier Approach

Tier 1: Free for Most Users

Tier 2: Premium via OpenRouter

Implementation

🆓 Free Tier Strategy

What Works for Free (No Credit Card)

Free Tier Limitations

Upsell Path

🏗️ Technical Architecture

WordPress Plugin Structure

Key Classes

📅 Development Roadmap (4 Weeks)

Week 1: Core Setup

Week 2: Planning & Execution

Week 3: Refinement & Images

Week 4: Polish & Launch

🚀 Launch Checklist

Plugin Preparation

Documentation

Distribution

📝 User Workflow Example

Scenario: Dev Writes OAuth Article

🎯 Success Metrics

MVP Success Criteria

Post-Launch Goals

🔐 Security & Privacy Notes

OpenRouter API Key Storage

User Data

Compliance

💡 Future Roadmap (Post-MVP)

Phase 2 Features

Phase 3 Integration

📚 Resources & References

20 KiB

Raw Blame History