wtf-p 0.4.0 → 0.5.0

package/README.md

@@ -1,282 +1,209 @@
 <div align="center">
 
+<img src="https://raw.githubusercontent.com/akougkas/wtf-p/main/assets/wtfp-banner.jpg" alt="WTF-P Banner" width="600">
+
 # WTF-P
 
-**Write The Freaking...**
-- **P**aper
-- **P**roposal
-- **P**resentation
-- **P**oster
+**Write The F\*\*\*ing Paper.**
 
-**Context engineering for academic writing with Claude Code.**
+Also: Proposal. Presentation. Poster.
 
 ```bash
 npx wtf-p
 ```
 
+*Academic writing commands for [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Gemini CLI](https://github.com/google-gemini/gemini-cli), and [OpenCode](https://github.com/opencode-ai/opencode).*
+
 </div>
 
 ---
 
 ## What This Does
 
-WTF-P turns Claude Code into a structured academic writing system. Instead of chatting with AI and hoping for the best, you get:
-
-- **Spec-driven writing** — Define your paper's vision, then execute section by section
-- **Grounded output** — BibTeX integration, citation mapping, no hallucinated references
-- **State management** — Pause, resume, track progress across sessions
-- **Venue templates** — ACM, IEEE, Nature, arXiv-ML structures built in
-
-The philosophy: **context engineering beats prompt engineering**. The files you prepare matter more than what you type.
+WTF-P installs structured commands into your AI coding assistant that turn it into an academic writing system. You get spec-driven workflows, citation grounding, section isolation, and quality verification — not just "write me a paper." Every section is planned before it's written, verified after, and grounded in your actual BibTeX sources.
 
 ---
 
 ## Quick Start
 
 ```bash
-npx wtf-p
-```
-
-Then in Claude Code:
-
-```bash
-/wtfp:new-paper        # Define your paper
-/wtfp:create-outline   # Build the structure
-/wtfp:plan-section 1   # Plan first section
-/wtfp:write-section    # Execute the plan
-```
-
-Run `/wtfp:help` for the full command reference.
-
-<details>
-<summary><strong>Installation Options</strong></summary>
-
-```bash
-# Global install (recommended)
-npx wtf-p --global
-
-# Local to current project
-npx wtf-p --local
-
-# Custom Claude config directory
-npx wtf-p --global --config-dir ~/research/.claude
-
-# Check installation status
-npx wtf-p status
-
-# Diagnose issues
-npx wtf-p doctor
-```
-</details>
-
-<details>
-<summary><strong>Upgrading</strong></summary>
-
-```bash
-# Update existing installation
-npx wtf-p update
-
-# Or reinstall with conflict handling
-npx wtf-p --global              # Interactive: prompts for conflicts
-npx wtf-p --global --force      # Overwrite everything
-npx wtf-p --global --backup-all # Backup before overwriting
+npx wtf-p                  # Install commands (Claude Code by default)
 ```
-</details>
 
-<details>
-<summary><strong>Uninstalling</strong></summary>
+Then in your AI assistant:
 
 ```bash
-npx wtf-p-uninstall --global
-npx wtf-p-uninstall --global --dry-run  # Preview first
+/wtfp:new-paper            # Guided interview about your research
+/wtfp:create-outline       # Build section structure + word budgets
+/wtfp:plan-section 1       # Plan first section
+/wtfp:write-section        # Write the section
 ```
 
-Only WTF-P files are removed. Your `CLAUDE.md` and other configs stay intact.
-</details>
-
----
-
-## Why AI Writing Tools Fail Researchers
-
-Most researchers using AI for writing hit the same walls:
-
-| Problem | What Happens |
-|---------|--------------|
-| **Dump and pray** | Paste a PDF, ask for a lit review, get hallucinated citations |
-| **No verification layer** | AI sounds confident, but claims aren't grounded in your actual sources |
-| **Monolithic approach** | Try to write 10k words at once, context window fills, quality degrades |
-| **No structure** | Generic AI doesn't know IMRaD from a blog post |
-
-WTF-P solves these by treating academic writing as a **specification problem**, not a generation problem.
+Run `/wtfp:help` for the full command list.
 
 ---
 
-## The Approach: Context Engineering
-
-The insight behind WTF-P: **what you prepare matters more than what you prompt**.
-
-### 1. Specification First
-
-Before any writing, WTF-P interviews you to extract:
-- Research questions and hypotheses
-- Core argument structure
-- Evidence and data inventory
-- Target venue requirements
-
-This becomes your `PROJECT.md` — the grounding document that keeps every section aligned.
-
-### 2. Hierarchical Planning
-
-Papers aren't written in one shot. WTF-P breaks them down:
-
-```
-Paper Vision → Section Outline → Section Plan → Paragraph Execution
-```
-
-Each level has its own document. Each document is version-controlled. You always know where you are.
-
-### 3. Isolated Execution
-
-When writing a section, WTF-P spawns a fresh context with only what's needed:
-- The paper vision
-- That section's plan
-- Relevant citations from your BibTeX
-- Prior sections for continuity
-
-No context pollution. No degradation over long documents.
-
-### 4. Human Verification
-
-AI drafts. Humans verify. Every section goes through:
-- Citation audit (are these real? are they relevant?)
-- Argument check (does this follow from the evidence?)
-- Rubric validation (does this meet venue requirements?)
-
-The system flags issues. You fix them. Iterate until solid.
-
----
+## Runtime Support
 
-## The Workflow
-
-### Starting Fresh
+| Runtime | Commands | Agents | Extras |
+|---------|----------|--------|--------|
+| **Claude Code** | 36 | 11 | Skills, MCP server, plugin manifest |
+| **Gemini CLI** | 36 | 11 | — |
+| **OpenCode** | 36 | 11 | — |
 
 ```bash
-/wtfp:new-paper         # Deep interview about your research
-/wtfp:create-outline    # Generate section structure + word budgets
+npx wtf-p --global              # Claude Code (default)
+npx wtf-p --global --gemini     # Gemini CLI
+npx wtf-p --global --opencode   # OpenCode
 ```
 
-Creates `.planning/` with your paper's specification:
-- `PROJECT.md` — Vision, requirements, constraints
-- `ROADMAP.md` — Section breakdown with status
-- `STATE.md` — Writing progress and context
+---
 
-### Writing Sections
+## Installation
 
 ```bash
-/wtfp:plan-section 1    # Create detailed plan for section 1
-/wtfp:write-section     # Execute the plan
-/wtfp:progress          # Check status, get next action
-```
+# Default: install to Claude Code
+npx wtf-p
 
-Each section gets its own planning documents. Plans are explicit — you see exactly what Claude intends before it writes.
+# Global install (recommended — persists across projects)
+npx wtf-p --global
 
-### Review and Polish
+# Local to current project only
+npx wtf-p --local
 
-```bash
-/wtfp:review-section 1  # Three-layer verification
-/wtfp:polish-prose      # Remove AI-speak, improve flow
-/wtfp:check-refs        # BibTeX audit
-```
+# Specify a custom config directory
+npx wtf-p --global --config-dir ~/research/.claude
 
-### Export
+# Check what's installed
+npx wtf-p status
 
-```bash
-/wtfp:export-latex      # Generate .tex with proper formatting
+# Diagnose issues
+npx wtf-p doctor
 ```
 
----
-
-## Reviving Stalled Projects
-
-Got a half-finished paper? WTF-P can work with existing material.
+### Upgrading
 
 ```bash
-/wtfp:map-project       # Index your existing files
-/wtfp:new-paper         # Initialize with awareness of prior work
+npx wtf-p update                    # Check for newer version
+npx wtf-p --global                  # Reinstall (prompts on conflicts)
+npx wtf-p --global --force          # Overwrite everything
+npx wtf-p --global --backup-all    # Backup before overwriting
 ```
 
-The mapping phase analyzes:
-- Existing drafts and their state
-- Your BibTeX and how citations are used
-- Data files and figures
-- What's missing vs. what's done
-
----
-
-## Citation Expert (v0.4.0)
-
-WTF-P includes a specialized tiered pipeline for bibliography management.
+### Uninstalling
 
 ```bash
-/wtfp:analyze-bib      # Deep analysis of impact (seminal vs rising)
-/wtfp:research-gap     # Intent-aware search (seminal/recent)
-/wtfp:check-refs       # Auto-suggest missing citations
+npx wtf-p-uninstall --global
+npx wtf-p-uninstall --global --dry-run   # Preview what would be removed
 ```
 
-Capabilities:
-- **Tiered Search:** Integrated Semantic Scholar, SerpAPI (Google Scholar), and CrossRef.
-- **Impact Ranking:** Automatically scores papers by citations, velocity, and venue prestige.
-- **Deduplication:** universal anchoring via DOI and Scholar Cluster IDs.
-- **Provenance:** Entries track their metadata source and verification status.
+Only WTF-P files are removed. Your config files and other tools stay intact.
 
 ---
 
 ## Command Reference
 
 ### Setup
+
 | Command | Purpose |
 |---------|---------|
-| `/wtfp:new-paper` | Initialize paper with deep context gathering |
-| `/wtfp:create-outline` | Generate section structure |
-| `/wtfp:map-project` | Index existing project materials |
-| `/wtfp:analyze-bib` | Deep analysis of your bibliography |
+| `/wtfp:new-paper` | Guided interview to define your paper's vision and requirements |
+| `/wtfp:create-outline` | Build section structure, argument map, and word budgets |
+| `/wtfp:map-project` | Index existing drafts, data, and references |
+| `/wtfp:analyze-bib` | Analyze bibliography and map citations to sections |
 
 ### Planning
+
 | Command | Purpose |
 |---------|---------|
-| `/wtfp:discuss-section [N]` | Articulate vision before planning |
-| `/wtfp:plan-section [N]` | Create execution plan |
-| `/wtfp:list-assumptions [N]` | See what Claude plans to write |
-| `/wtfp:research-gap [N]` | Literature analysis for a section |
+| `/wtfp:discuss-section [N]` | Discuss your vision for a section before planning |
+| `/wtfp:plan-section [N]` | Create detailed writing plan with quality validation |
+| `/wtfp:list-assumptions [N]` | Preview intended approach before writing |
+| `/wtfp:research-gap [N]` | Research literature for a section (tiered: Semantic Scholar, Google Scholar, CrossRef) |
 
 ### Writing
+
 | Command | Purpose |
 |---------|---------|
-| `/wtfp:write-section` | Execute a plan |
-| `/wtfp:progress` | Status + intelligent next action |
-| `/wtfp:pause-writing` | Save state for later |
-| `/wtfp:resume-writing` | Restore context and continue |
+| `/wtfp:write-section` | Execute a section plan with agent-based writing |
+| `/wtfp:execute-outline` | Write all sections in parallel, then check coherence |
+| `/wtfp:quick` | Minimal-ceremony writing for quick tasks |
+| `/wtfp:progress` | Show writing progress and suggest next step |
+| `/wtfp:pause-writing` | Save current progress for later |
+| `/wtfp:resume-writing` | Resume from a previous session |
 
 ### Review
+
 | Command | Purpose |
 |---------|---------|
-| `/wtfp:review-section [N]` | Three-layer verification |
-| `/wtfp:plan-revision [N]` | Create fix plan from issues |
-| `/wtfp:polish-prose` | Improve readability |
-| `/wtfp:check-refs` | Citation audit |
+| `/wtfp:review-section [N]` | Review for citations, coherence, and venue requirements |
+| `/wtfp:verify-work [N]` | Acceptance-test a section against its plan |
+| `/wtfp:plan-revision [N]` | Create revision plan from review issues |
+| `/wtfp:polish-prose` | Improve clarity, flow, and academic voice |
+| `/wtfp:check-refs` | Audit BibTeX for missing, duplicate, or broken references |
+
+### Structure
 
-### Export
 | Command | Purpose |
 |---------|---------|
-| `/wtfp:export-latex` | Generate .tex output |
-| `/wtfp:submit-milestone` | Archive submission version |
+| `/wtfp:create-poster` | Full poster creation workflow |
+| `/wtfp:create-slides` | Presentation deck workflow |
+| `/wtfp:insert-section` | Add a new section to the outline |
+| `/wtfp:remove-section` | Remove a section from the outline |
+
+### Export & Submission
 
-### Contributing
 | Command | Purpose |
 |---------|---------|
-| `/wtfp:report-bug` | File a GitHub issue |
-| `/wtfp:request-feature` | Request new functionality |
-| `/wtfp:contribute` | Submit a pull request |
+| `/wtfp:export-latex` | Export to LaTeX with bibliography and formatting |
+| `/wtfp:audit-milestone` | Pre-submission checks on sections, citations, and word counts |
+| `/wtfp:plan-milestone-gaps` | Create fix plans for gaps found by audit |
+| `/wtfp:submit-milestone` | Archive a completed draft or submission version |
+
+### Settings & Productivity
+
+| Command | Purpose |
+|---------|---------|
+| `/wtfp:settings` | View and edit project settings interactively |
+| `/wtfp:checkpoint` | Save, restore, and list paper state checkpoints |
+| `/wtfp:add-todo` | Capture a quick note or task without breaking flow |
+| `/wtfp:check-todos` | Review pending todos (act, defer, dismiss) |
+| `/wtfp:update` | Check for updates and install newer version |
+
+### Help & Contributing
+
+| Command | Purpose |
+|---------|---------|
+| `/wtfp:help` | Full command reference |
+| `/wtfp:report-bug` | Report a bug via GitHub issue |
+| `/wtfp:request-feature` | Request a new feature via GitHub issue |
+| `/wtfp:contribute` | Walk through contributing code via pull request |
+
+---
+
+## Configuration
+
+WTF-P uses a `config.json` in your `.planning/` directory. Key settings:
+
+```jsonc
+{
+  "model_profile": "balanced",        // "quality" | "balanced" | "budget"
+  "workflow": {
+    "research": true,                  // Enable research phase
+    "plan_check": true,                // Pre-write plan validation
+    "verifier": true                   // Post-write verification
+  },
+  "parallelization": {
+    "enabled": false,                  // Parallel section writing
+    "max_concurrent_agents": 3
+  }
+}
+```
+
+**Model profiles** route 11 specialized agents to appropriate models:
+- **quality** — best models for all agents (slower, higher cost)
+- **balanced** — strong models for writing, lighter for validation (default)
+- **budget** — fastest models everywhere (good for iteration)
 
 ---
 
@@ -292,50 +219,43 @@ Capabilities:
 
 ---
 
-## WCN Mode (Reduced Tokens)
+## How It Works
 
-For smaller models or limited context windows, WTF-P includes compressed workflows:
+WTF-P follows a **thin orchestrator → specialized agent → quality loop** architecture:
+
+1. **Specification first** — `/wtfp:new-paper` interviews you to extract research questions, argument structure, evidence inventory, and venue requirements into a `PROJECT.md`.
+2. **Hierarchical planning** — Papers break down: Paper Vision → Section Outline → Section Plan → Paragraph Execution. Each level has its own document.
+3. **Isolated execution** — Each section is written in a fresh context containing only the paper vision, that section's plan, relevant citations, and prior sections. No context pollution.
+4. **Quality loops** — Pre-write plan validation (7 dimensions, up to 3 revisions) and post-write goal-backward verification ensure claims match plans and evidence.
+
+### WCN Mode (Reduced Tokens)
+
+For smaller models or limited context windows, WTF-P includes compressed workflows with 35-50% token reduction:
 
 ```bash
 ./tools/wcn/swap-workflows.sh wcn      # Switch to compressed
-./tools/wcn/swap-workflows.sh verbose  # Switch back
+./tools/wcn/swap-workflows.sh verbose   # Switch back
 ```
 
-35-50% token reduction with equivalent output quality. Verified on Claude Haiku and Sonnet.
-
 ---
 
 ## Origin
 
-WTF-P was built at the [Gnosis Research Center](https://www.intelli-gnosis.com/) at Illinois Tech.
-
-The problem: research teams with grants to win, papers to publish, and no time to waste on writer's block. Existing AI tools either hallucinated citations or produced generic output that required complete rewrites.
-
-The solution: treat Claude Code as a **structured writing system**, not a chatbot. Give it proper context, explicit specifications, and verification layers. Let humans focus on ideas while AI handles the mechanical synthesis.
-
-The result: papers that ship.
+Built at the [Gnosis Research Center](https://www.intelli-gnosis.com/) at Illinois Tech. The problem: research teams with grants to win, papers to publish, and no time for writer's block. The solution: treat your AI coding assistant as a structured writing system — proper context, explicit specs, verification layers.
 
 ---
 
-## Contributing
+## Links
 
-Found a bug? Want a feature? WTF-P includes commands to help:
-
-```bash
-/wtfp:report-bug        # Creates a GitHub issue
-/wtfp:request-feature   # Submits a feature request
-/wtfp:contribute        # Guides you through a PR
-```
-
-Or visit [github.com/akougkas/wtf-p](https://github.com/akougkas/wtf-p).
+- [Changelog](CHANGELOG.md)
+- [Contributing](CONTRIBUTING.md)
+- [Roadmap](ROADMAP.md)
+- [License](LICENSE) (MIT)
+- [GitHub](https://github.com/akougkas/wtf-p)
 
 ---
 
-## License
-
-MIT License. Open source, open science.
-
 <div align="center">
 <br>
-<strong>Stop staring at the cursor. Start shipping papers.</strong>
+<strong>No more excuses. Ship the paper.</strong>
 </div>

package/bin/commands/doctor.js

@@ -6,7 +6,7 @@ async function runDoctor(options) {
   const { out, explicitConfigDir } = options;
   const c = out.colors;
 
-  out.log(`  ${c.yellow('WTF-P Installation Doctor')}\n`);
+  out.log(`  ${c.yellow('WTF-P Health Check')}\n`);
 
   const issues = [];
   const checks = [];
@@ -71,6 +71,92 @@ async function runDoctor(options) {
     checks.push({ name: 'CLAUDE_CONFIG_DIR', status: 'info', detail: 'Not set (using default)' });
   }
 
+  // Check 6: v0.5.0 components (agents, workflows, commands)
+  if (detection.hasCommands || detection.hasWorkflows) {
+    const v050Components = {
+      agents: [
+        'coherence-checker.md',
+        'section-writer.md',
+        'section-planner.md',
+        'argument-verifier.md'
+      ],
+      workflows: [
+        'verify-work.md',
+        'execute-outline.md'
+      ],
+      commands: [
+        'verify-work.md',
+        'execute-outline.md',
+        'settings.md',
+        'add-todo.md',
+        'check-todos.md',
+        'update.md',
+        'audit-milestone.md',
+        'plan-milestone-gaps.md'
+      ]
+    };
+
+    // Note: After install, agents/workflows/commands are all under globalDir
+    // The installer copies from vendors/ and core/ into the config directory
+    const agentsDir = path.join(globalDir, 'agents', 'wtfp');
+    const workflowsDir = path.join(globalDir, 'write-the-f-paper', 'workflows');
+    const commandsDir = path.join(globalDir, 'commands', 'wtfp');
+
+    let missingAgents = [];
+    let missingWorkflows = [];
+    let missingCommands = [];
+
+    if (fs.existsSync(agentsDir)) {
+      for (const agent of v050Components.agents) {
+        if (!fs.existsSync(path.join(agentsDir, agent))) {
+          missingAgents.push(agent);
+        }
+      }
+    }
+
+    if (fs.existsSync(workflowsDir)) {
+      for (const wf of v050Components.workflows) {
+        if (!fs.existsSync(path.join(workflowsDir, wf))) {
+          missingWorkflows.push(wf);
+        }
+      }
+    }
+
+    if (fs.existsSync(commandsDir)) {
+      for (const cmd of v050Components.commands) {
+        if (!fs.existsSync(path.join(commandsDir, cmd))) {
+          missingCommands.push(cmd);
+        }
+      }
+    }
+
+    const totalMissing = missingAgents.length + missingWorkflows.length + missingCommands.length;
+    const totalChecked = v050Components.agents.length + v050Components.workflows.length + v050Components.commands.length;
+
+    if (totalMissing === 0) {
+      checks.push({ name: 'v0.5.0 components', status: 'pass', detail: `${totalChecked} files verified` });
+    } else if (totalMissing === totalChecked) {
+      checks.push({ name: 'v0.5.0 components', status: 'info', detail: 'Pre-v0.5.0 installation' });
+    } else {
+      issues.push(`Missing v0.5.0 components: ${missingAgents.concat(missingWorkflows, missingCommands).join(', ')}`);
+      checks.push({ name: 'v0.5.0 components', status: 'warn', detail: `${totalMissing} missing` });
+    }
+  }
+
+  // Check 7: Dual-installation conflict (global + local both present)
+  const localDir = path.join(process.cwd(), '.claude');
+  if (localDir !== globalDir) {
+    const localDetection = detectInstallation(localDir);
+    if (localDetection.hasCommands && detection.hasCommands) {
+      issues.push('WTF-P is installed both globally and locally — commands will appear twice');
+      checks.push({
+        name: 'Dual installation',
+        status: 'warn',
+        detail: `Found in both ${getPathLabel(globalDir, true)} and ./.claude`
+      });
+    }
+  }
+
   // Output results
   for (const check of checks) {
     let icon, color;
@@ -91,7 +177,7 @@ async function runDoctor(options) {
       out.log(`    ${c.yellow('•')} ${issue}`);
     }
     out.log('');
-    out.log(`  ${c.dim('Run')} ${c.cyan('npx wtf-p --global --force')} ${c.dim('to reinstall')}\n`);
+    out.log(`  ${c.dim('To fix, reinstall:')} ${c.cyan('npx wtf-p --global --force')}\n`);
   } else {
     out.log(`  ${c.green('No issues found!')}\n`);
   }