npm - wtf-p - Versions diffs - 0.1.0 → 0.3.0 - Mend

wtf-p 0.1.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (110) hide show

package/README.md CHANGED Viewed

@@ -1,338 +1,323 @@
 <div align="center">
-# WRITE THE F***ING PAPER
+# WTF-P
-**The G.O.A.T. meta-prompting system for 10x researchers who need to submit papers/proposals YESTERDAY.**
+**Write The Freaking...**
+- **P**aper
+- **P**roposal
+- **P**resentation
+- **P**oster
+**Context engineering for academic writing with Claude Code.**
 ```bash
-npx wtfp
+npx wtf-p
 ```
-**Runs on everything. Mac, Windows, Linux. No excuses.**
-*(You need LaTeX and BibTeX or you're NGMI)*
-> "Bro, if you have the data, this ships the manuscript. Zero writer's block."
+</div>
-> "I tried Overleaf and Notion — weak sauce. This tool actually ships words."
+---
-> "Literally the most based addition to my stack. It just writes the f*ing paper."
+## What This Does
-**Used by absolute legends at Gnosis Research Center at Illinois Tech.**
+WTF-P turns Claude Code into a structured academic writing system. Instead of chatting with AI and hoping for the best, you get:
-[The Alpha](#the-alpha-why-i-built-this) · [The Stack](#the-stack) · [The Commands](#the-toolkit) · [The Logic](#the-logic)
+- **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
-</div>
+The philosophy: **context engineering beats prompt engineering**. The files you prepare matter more than what you type.
 ---
-## The Alpha (Why I Built This)
+## Quick Start
-Yo, I'm leading the Gnosis Research Center at Illinois Tech. I got grants to win, labs to run, and exactly zero time to stare at a blinking cursor like an NPC. My PhD students? Same story.
-Other tools? Garbage. **Jasper?** Hallucinates. **ChatGPT?** Sounds like a robot trying to pass a Turing test. They don't get structure. They don't respect the citations.
+```bash
+npx wtf-p
+```
-So I cooked up **WTF-P**. We're talking high-leverage context maxxing here. Under the hood? It's parsing BibTeX, mapping arguments, and enforcing that IMRaD structure so hard. You feed it data, it spits out submission-ready drafts.
+Then in Claude Code:
-I trust the system. It builds the frame so I can just come in and drop the knowledge.
+```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
+```
-**No more "writer's block" excuses. We are shipping papers before the deadline. Period.**
+Run `/wtfp:help` for the full command reference.
-— *akougkas (Nerd ^ academic+coder)*
+<details>
+<summary><strong>Installation Options</strong></summary>
-> Academic writing is usually chaotic evil. You ask AI for a lit review, it invents papers. Total beta move.
-> **WTF-P fixes that.** It's the grounding layer that makes Claude Code academic weapon grade. Describe the hypothesis, drop the .bib, and watch it cook.
+```bash
+# Global install (recommended)
+npx wtf-p --global
-### Who This Is For
-PhDs, Postdocs, and PIs who are done playing games and need to submit the damn proposal/paper/report **right now**.
+# Local to current project
+npx wtf-p --local
----
+# Custom Claude config directory
+npx wtf-p --global --config-dir ~/research/.claude
-## Let's Go
+# Check installation status
+npx wtf-p status
-```bash
-npx wtfp
+# Diagnose issues
+npx wtf-p doctor
 ```
-Boom. Done. Check `/wtfp:help` if you're lost.
+</details>
 <details>
-<summary><strong>Headless / CI / HPC (For the devops wizards)</strong></summary>
+<summary><strong>Upgrading</strong></summary>
 ```bash
-npx wtfp --global   # Install to ~/.claude/
-npx wtfp --local    # Install to ./.claude/
+# 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
 ```
 </details>
 <details>
-<summary><strong>Custom Location (For the organized)</strong></summary>
+<summary><strong>Uninstalling</strong></summary>
 ```bash
-# Install to a custom Claude config directory
-npx wtfp --global --config-dir ~/projects/my-paper/.claude
-# Or use environment variable
-CLAUDE_CONFIG_DIR=~/research/.claude npx wtfp --global
+npx wtf-p-uninstall --global
+npx wtf-p-uninstall --global --dry-run  # Preview first
 ```
+Only WTF-P files are removed. Your `CLAUDE.md` and other configs stay intact.
 </details>
-<details>
-<summary><strong>Upgrade / Reinstall (For the cautious)</strong></summary>
+---
-When upgrading, WTF-P respects your existing files:
+## Why AI Writing Tools Fail Researchers
-```bash
-# Interactive: prompts for each conflict (overwrite/skip/backup)
-npx wtfp --global
+Most researchers using AI for writing hit the same walls:
-# Force overwrite everything (yolo mode)
-npx wtfp --global --force
+| 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 |
-# Backup all existing files before overwriting
-npx wtfp --global --backup-all
-```
-</details>
+WTF-P solves these by treating academic writing as a **specification problem**, not a generation problem.
-<details>
-<summary><strong>Uninstall (For the tidy)</strong></summary>
+---
-```bash
-# Interactive uninstall
-npx wtf-p-uninstall --global
+## The Approach: Context Engineering
-# Preview what would be removed
-npx wtf-p-uninstall --global --dry-run
+The insight behind WTF-P: **what you prepare matters more than what you prompt**.
-# Backup before removing
-npx wtf-p-uninstall --global --backup
+### 1. Specification First
-# Also clean up backup files from prior installs
-npx wtf-p-uninstall --global --clean-backups
-```
+Before any writing, WTF-P interviews you to extract:
+- Research questions and hypotheses
+- Core argument structure
+- Evidence and data inventory
+- Target venue requirements
-Only WTF-P files are removed. Your `CLAUDE.md`, `settings.json`, and other configs stay intact.
-</details>
+This becomes your `PROJECT.md` — the grounding document that keeps every section aligned.
-<details>
-<summary><strong>Dev Mode (For the builders)</strong></summary>
+### 2. Hierarchical Planning
-Clone it, build it, break it:
+Papers aren't written in one shot. WTF-P breaks them down:
-```bash
-git clone https://github.com/akougkas/wtfp.git
-cd wtfp
-node bin/install.js --local
 ```
-</details>
+Paper Vision → Section Outline → Section Plan → Paragraph Execution
+```
-### Pro Move: God Mode
-WTF-P is designed for flow state. Don't let permissions slow you down.
+Each level has its own document. Each document is version-controlled. You always know where you are.
-```bash
-claude --dangerously-skip-permissions
-```
+### 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?)
-> [!TIP]
-> This is the way. Stopping to approve `cat research_notes.txt` 50 times is strictly for amateurs.
+The system flags issues. You fix them. Iterate until solid.
 ---
 ## The Workflow
-### 1. The Setup
+### Starting Fresh
 ```bash
-/wtfp:new-paper
+/wtfp:new-paper         # Deep interview about your research
+/wtfp:create-outline    # Generate section structure + word budgets
 ```
-It grills you until it gets the alpha—your research questions, methods, findings. Creates `MANUSCRIPT.md`.
-### 2. The Skeleton
+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
 ```bash
-/wtfp:create-outline
+/wtfp:plan-section 1    # Create detailed plan for section 1
+/wtfp:write-section     # Execute the plan
+/wtfp:progress          # Check status, get next action
 ```
-Generates:
-- `OUTLINE.md` — The IMRaD backbone.
-- `ARGUMENT.md` — The logic flow.
-- `REFS.md` — Citations mapped to sections. **No hallucinations allowed.**
-### 3. The Grind
+Each section gets its own planning documents. Plans are explicit — you see exactly what Claude intends before it writes.
+### Review and Polish
 ```bash
-/wtfp:plan-section 1      # Atomic planning
-/wtfp:write-section       # Agent swarm execution
+/wtfp:review-section 1  # Three-layer verification
+/wtfp:polish-prose      # Remove AI-speak, improve flow
+/wtfp:check-refs        # BibTeX audit
 ```
-Each section runs in a fresh subagent context. 200k tokens of pure synthesis. No degradation. It reads only what it needs. Surgical precision.
-### 4. The Finish
+### Export
 ```bash
-/wtfp:polish-prose        # De-robotize the text
-/wtfp:check-refs          # BibTeX audit
-/wtfp:export-latex        # LaTeX injection
+/wtfp:export-latex      # Generate .tex with proper formatting
 ```
-Ship the draft to your advisor. Get roasted. Iterate. The system is modular—you never get stuck in a monolithic doc.
 ---
-## Resurrecting Dead Papers
+## Reviving Stalled Projects
-Got a paper rotting in a drawer? We're bringing it back to life.
+Got a half-finished paper? WTF-P can work with existing material.
-### 1. Context Maxxing
 ```bash
-/wtfp:map-project
+/wtfp:map-project       # Index your existing files
+/wtfp:new-paper         # Initialize with awareness of prior work
 ```
-Spawns agents to raid your directory. Creates `.planning/context/`:
-| Document | The Vibe |
-| :--- | :--- |
-| `LIT_REVIEW.md` | Your .bib analysis. |
-| `CURRENT_DRAFT.md` | The half-baked stuff you wrote 6 months ago. |
-| `DATA_SUMMARY.md` | Your results/figures decoded. |
-| `STYLE_GUIDE.md` | Nature/IEEE specs. |
-| `GAPS.md` | Where you messed up. |
+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
-### 2. Re-Init
-```bash
-/wtfp:new-paper
-```
-Same as fresh, but now it knows your history.
+---
-### 3. Grind
-`/wtfp:create-outline` → `/wtfp:plan-section` → `/wtfp:write-section`
+## 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 |
+### 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 |
+### 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 |
+### 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 |
+### Export
+| Command | Purpose |
+|---------|---------|
+| `/wtfp:export-latex` | Generate .tex output |
+| `/wtfp:submit-milestone` | Archive submission version |
+### Contributing
+| Command | Purpose |
+|---------|---------|
+| `/wtfp:report-bug` | File a GitHub issue |
+| `/wtfp:request-feature` | Request new functionality |
+| `/wtfp:contribute` | Submit a pull request |
 ---
-## Why It Crushes
-### Context Maxxing
-Claude Code is cracked if you give it the right juice. Most profs just dump a PDF and pray.
-WTF-P handles the prompt engineering:
-| File | Function |
-| :--- | :--- |
-| `MANUSCRIPT.md` | The Vision. Always active. |
-| `OUTLINE.md` | The Backbone. |
-| `FLOW.md` | The Rhetoric. |
-| `DRAFT_PLAN.md` | The Battle Plan. |
-| `CRITIQUE.md` | Reviewer #2 Simulator. |
-### XML Prompts (The Secret Sauce)
-We use structured XML so Claude doesn't go off the rails:
-```xml
-<section type="synthesis">
-  <title>3.2 Neural Architecture Search</title>
-  <inputs>
-    <file>data/results_table_3.csv</file>
-  </inputs>
-  <citations>
-    <cite>vaswani2017attention</cite>
-  </citations>
-  <instruction>
-    Describe the modified ResNet block.
-    Tone: Objective, technical, gigabrain.
-  </instruction>
-</section>
-```
-Precise. No hallucinations. Pure signal.
+## Venue Templates
+| Template | Structure |
+|----------|-----------|
+| `acm-cs` | Intro → Background → Approach → Evaluation → Related Work → Conclusion |
+| `ieee-cs` | Intro → Background → Design → Implementation → Evaluation → Conclusion |
+| `arxiv-ml` | Intro → Related Work → Preliminaries → Method → Experiments → Conclusion |
+| `nature` | Intro → Methods → Results → Discussion |
+| `thesis` | Flexible chapter structure |
-### Subagent Swarm
-Writing 10k words? Context windows get full. The AI gets dumb.
-WTF-P prevents this. Every section = Fresh Agent.
+---
-| Section | Context | Quality |
-| :--- | :--- | :--- |
-| Intro | Fresh | 🔥 |
-| Methods | Fresh | 🔥 |
-| Discussion | Fresh | 🔥 |
+## WCN Mode (Reduced Tokens)
-No degradation. Walk away, come back to a finished Methods section.
+For smaller models or limited context windows, WTF-P includes compressed workflows:
-### Atomic Commits
-Every draft gets a git commit instantly:
-```text
-abc123f text(intro): complete problem statement
-def456g text(methods): draft experimental setup
+```bash
+./tools/wcn/swap-workflows.sh wcn      # Switch to compressed
+./tools/wcn/swap-workflows.sh verbose  # Switch back
 ```
-> [!NOTE]
-> **Benefits:** Version control for your thesis. If a draft is mid, `git revert`.
+35-50% token reduction with equivalent output quality. Verified on Claude Haiku and Sonnet.
-### WCN Mode (Lite Context)
-Running on smaller models? Limited context window? Free-tier Claude?
+---
-WCN (Workflow Compression Notation) cuts workflow tokens by **35-50%** with zero quality loss. Verified on Haiku and Sonnet.
+## Origin
-```bash
-# Switch to compressed workflows
-./tools/wcn/swap-workflows.sh wcn
+WTF-P was built at the [Gnosis Research Center](https://www.intelli-gnosis.com/) at Illinois Tech.
-# Switch back to verbose
-./tools/wcn/swap-workflows.sh verbose
-```
+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.
-| Mode | create-outline | plan-section | Best For |
-| :--- | :--- | :--- | :--- |
-| Verbose | 13,029 chars | 13,655 chars | Opus, unlimited plans |
-| WCN | 6,676 chars | 8,863 chars | Haiku, Sonnet, free tiers |
+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.
-> [!TIP]
-> WCN uses structured notation (`[step:]`, `IF→`, `RUN:`) that smaller models parse just as well. You lose nothing but tokens.
+The result: papers that ship.
 ---
-## The Toolkit
-### Setup & Planning
-| Command | Payload |
-| :--- | :--- |
-| `/wtfp:new-paper` | Start the grind. Picks venue template (ACM/IEEE/ML/Nature). |
-| `/wtfp:create-outline` | Build the skeleton from venue structure. |
-| `/wtfp:map-project` | Analyze the ruins of old drafts. |
-| `/wtfp:analyze-bib` | BibTeX intelligence. Cluster topics, find seminal works, map citations to sections. |
-| `/wtfp:discuss-section [N]` | Gather section context before planning. |
-### Writing & Execution
-| Command | Payload |
-| :--- | :--- |
-| `/wtfp:plan-section [N]` | Tactical planning. |
-| `/wtfp:write-section` | Execute the draft. |
-| `/wtfp:progress` | Stats check. |
-| `/wtfp:insert-section [N]` | Add missing sauce. |
-| `/wtfp:remove-section [N]` | Kill your darlings. |
-| `/wtfp:research-gap` | Find the holes in literature. |
-| `/wtfp:list-assumptions` | Logic check. |
-### Review & Polish
-| Command | Payload |
-| :--- | :--- |
-| `/wtfp:review-section [N]` | Reviewer personas: Hostile, Area Chair, Editor, Mentor. |
-| `/wtfp:plan-revision [N]` | Fix the damage. |
-| `/wtfp:polish-prose` | De-robotize the text. Kill AI-speak. |
-| `/wtfp:check-refs` | BibTeX audit. Find missing/unused citations. |
-### Export & State
-| Command | Payload |
-| :--- | :--- |
-| `/wtfp:export-latex` | Generate .tex (The final boss). |
-| `/wtfp:submit-milestone` | Version lock. |
-| `/wtfp:pause-writing` | Save state. |
-| `/wtfp:resume-writing` | Load state. |
-| `/wtfp:help` | RTFM. |
-### Venue Templates
-| Template | Structure |
-| :--- | :--- |
-| `acm-cs` | Intro → Background → Approach → Eval → Related → Conclusion |
-| `ieee-cs` | Intro → Background/Related → Design → Impl → Eval → Conclusion |
-| `arxiv-ml` | Intro → Related → Prelim → Method → Experiments → Conclusion |
-| `nature` | Intro → Methods → Results → Discussion (classic IMRaD) |
-| `thesis` | Flexible chapter structure for dissertations |
+## Contributing
+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).
 ---
 ## License
 MIT License. Open source, open science.
 <div align="center">
-  <br>
-  <strong>Claude Code is powerful. WTF-P makes it tenured.</strong>
+<br>
+<strong>Stop staring at the cursor. Start shipping papers.</strong>
 </div>

package/bin/commands/doctor.js ADDED Viewed

@@ -0,0 +1,100 @@
+const fs = require('fs');
+const path = require('path');
+const { getClaudeDir, normalizePath, getPathLabel, detectInstallation } = require('../lib/utils');
+async function runDoctor(options) {
+  const { out, explicitConfigDir } = options;
+  const c = out.colors;
+  out.log(`  ${c.yellow('WTF-P Installation Doctor')}\n`);
+  const issues = [];
+  const checks = [];
+  // Check 1: Node.js version
+  const nodeVersion = process.version;
+  const nodeMajor = parseInt(nodeVersion.slice(1).split('.')[0], 10);
+  if (nodeMajor < 16) {
+    issues.push(`Node.js ${nodeVersion} is below minimum (16.7.0)`);
+    checks.push({ name: 'Node.js version', status: 'fail', detail: nodeVersion });
+  } else {
+    checks.push({ name: 'Node.js version', status: 'pass', detail: nodeVersion });
+  }
+  // Check 2: Claude directory exists
+  const globalDir = getClaudeDir(explicitConfigDir, true);
+  if (fs.existsSync(globalDir)) {
+    checks.push({ name: 'Claude config directory', status: 'pass', detail: getPathLabel(globalDir, true) });
+  } else {
+    checks.push({ name: 'Claude config directory', status: 'warn', detail: 'Does not exist (will be created on install)' });
+  }
+  // Check 3: Write permissions
+  const testDir = globalDir.replace(/\.claude$/, '.claude-test-' + Date.now());
+  try {
+    fs.mkdirSync(testDir, { recursive: true });
+    fs.writeFileSync(path.join(testDir, 'test'), 'test');
+    fs.rmSync(testDir, { recursive: true });
+    checks.push({ name: 'Write permissions', status: 'pass', detail: 'Can write to config directory' });
+  } catch (err) {
+    issues.push(`Cannot write to ${getPathLabel(globalDir, true)}: ${err.message}`);
+    checks.push({ name: 'Write permissions', status: 'fail', detail: err.message });
+  }
+  // Check 4: Installation state
+  const detection = detectInstallation(globalDir);
+  if (detection.hasCommands || detection.hasWorkflows || detection.hasSkills) {
+    if (detection.partial) {
+      issues.push('Partial installation detected - some files are missing');
+      checks.push({ name: 'Installation integrity', status: 'warn', detail: 'Partial install' });
+    } else if (detection.corrupt) {
+      issues.push('Version file is corrupt - reinstall recommended');
+      checks.push({ name: 'Installation integrity', status: 'warn', detail: 'Corrupt version file' });
+    } else {
+      checks.push({ name: 'Installation integrity', status: 'pass', detail: `v${detection.version}` });
+    }
+  } else {
+    checks.push({ name: 'Installation integrity', status: 'info', detail: 'Not installed' });
+  }
+  // Check 5: CLAUDE_CONFIG_DIR env var
+  const configDirEnv = process.env.CLAUDE_CONFIG_DIR;
+  if (configDirEnv) {
+    const expanded = normalizePath(configDirEnv);
+    if (fs.existsSync(expanded)) {
+      checks.push({ name: 'CLAUDE_CONFIG_DIR', status: 'pass', detail: expanded });
+    } else {
+      issues.push(`CLAUDE_CONFIG_DIR points to non-existent path: ${configDirEnv}`);
+      checks.push({ name: 'CLAUDE_CONFIG_DIR', status: 'warn', detail: `${configDirEnv} (does not exist)` });
+    }
+  } else {
+    checks.push({ name: 'CLAUDE_CONFIG_DIR', status: 'info', detail: 'Not set (using default)' });
+  }
+  // Output results
+  for (const check of checks) {
+    let icon, color;
+    switch (check.status) {
+      case 'pass': icon = '✓'; color = c.green; break;
+      case 'fail': icon = '✗'; color = c.red; break;
+      case 'warn': icon = '⚠'; color = c.yellow; break;
+      default: icon = 'ℹ'; color = c.cyan;
+    }
+    out.log(`  ${color(icon)} ${check.name}: ${c.dim(check.detail)}`);
+  }
+  out.log('');
+  if (issues.length > 0) {
+    out.log(`  ${c.yellow('Issues found:')}`);
+    for (const issue of issues) {
+      out.log(`    ${c.yellow('•')} ${issue}`);
+    }
+    out.log('');
+    out.log(`  ${c.dim('Run')} ${c.cyan('npx wtf-p --global --force')} ${c.dim('to reinstall')}\n`);
+  } else {
+    out.log(`  ${c.green('No issues found!')}\n`);
+  }
+}
+module.exports = runDoctor;