wtf-p 0.3.0 → 0.5.0

package/vendors/claude/commands/wtfp/check-refs.md

@@ -1,6 +1,6 @@
 ---
 name: wtfp:check-refs
-description: BibTeX audit - verify citations are complete and consistent
+description: Audit BibTeX for missing, duplicate, or broken references
 argument-hint: "[bib-file]"
 allowed-tools:
   - Read
@@ -9,179 +9,111 @@ allowed-tools:
   - Edit
   - Glob
   - Grep
+  - Task
+  - AskUserQuestion
 ---
 
 <objective>
 Audit citations for completeness and consistency.
 
-Purpose: Ensure all in-text citations have BibTeX entries, all BibTeX entries are cited, and references are properly formatted.
-Output: Report of citation issues with fixes applied or flagged for user action.
-</objective>
+**Orchestrator role:** Locate bib and draft files, run deterministic indexer, resolve model profile, spawn citation-formatter agent for cross-referencing, present results, apply fixes.
 
-<execution_context>
-@~/.claude/write-the-f-paper/references/citation-formats.md
-</execution_context>
+Ensures all in-text citations have BibTeX entries, all entries are cited, and references are properly formatted.
+</objective>
 
 <context>
-BibTeX file: $ARGUMENTS (optional - auto-detects .bib files if not provided)
+BibTeX file: $ARGUMENTS (optional — auto-detects .bib files)
 
 **Load project state:**
 @.planning/STATE.md
-
-**Scan for:**
-- .bib files in project root and common locations
-- Draft files with citations (\cite{}, [@...], etc.)
 </context>
 
 <process>
 
-<step name="locate_files">
-1. Find BibTeX file(s):
-```bash
-find . -name "*.bib" -type f 2>/dev/null | head -20
-```
+## 1. Validate Environment and Resolve Model Profile
 
-2. Find files with citations:
 ```bash
+find . -name "*.bib" -type f 2>/dev/null | head -20
 grep -rl "\\\\cite\|\\[@\|\\[.*\\]" --include="*.tex" --include="*.md" . 2>/dev/null
 ```
 
-3. If no .bib found, error:
+```bash
+MODEL_PROFILE=$(cat .planning/config.json 2>/dev/null | grep -o '"model_profile"[[:space:]]*:[[:space:]]*"[^"]*"' | grep -o '"[^"]*"$' | tr -d '"' || echo "balanced")
 ```
-No .bib file found.
 
-Create one or specify path: /wtfp:check-refs path/to/refs.bib
-```
-</step>
+| Agent | quality | balanced | budget |
+|-------|---------|----------|--------|
+| citation-formatter | sonnet | sonnet | haiku |
 
-<step name="parse_bib">
-**Extract all BibTeX keys:**
+## 2. Run Deterministic Indexer
 
 ```bash
-grep -E "^@[a-zA-Z]+\{" *.bib | sed 's/.*{\([^,]*\),.*/\1/'
+node ~/.claude/bin/bib-index.js index "$BIB_FILE"
 ```
 
-Build inventory:
-- Entry key
-- Entry type (@article, @inproceedings, etc.)
-- Required fields present/missing
-- Year
-</step>
+## 3. Spawn citation-formatter Agent
 
-<step name="parse_citations">
-**Extract all in-text citations:**
-
-LaTeX style: `\cite{key}`, `\citep{key}`, `\citet{key}`, `\cite{key1,key2}`
-Markdown style: `[@key]`, `[@key1; @key2]`
-
-Build list of all citation keys used in text.
-</step>
-
-<step name="cross_reference">
-**Compare citations vs BibTeX:**
-
-| Check | Status |
-|-------|--------|
-| Cited but no BibTeX entry | ❌ MISSING |
-| BibTeX entry but never cited | ⚠️ UNUSED |
-| Entry missing required fields | ⚠️ INCOMPLETE |
-| Duplicate keys | ❌ DUPLICATE |
-| Year out of range (< 1900 or > current) | ⚠️ SUSPICIOUS |
-
-**Required fields by type:**
-
-| Type | Required |
-|------|----------|
-| @article | author, title, journal, year |
-| @inproceedings | author, title, booktitle, year |
-| @book | author/editor, title, publisher, year |
-| @phdthesis | author, title, school, year |
-| @misc | author, title, year, howpublished/url |
-</step>
-
-<step name="report">
-**Present findings:**
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ WTF-P ► AUDITING CITATIONS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
 
 ```
-## Citation Audit
+Task(
+  prompt="First, read ~/.claude/agents/wtfp/citation-formatter.md for your role.\n\n" + audit_prompt,
+  subagent_type="general-purpose",
+  model="{formatter_model}",
+  description="Audit citations"
+)
+```
 
-### ❌ Missing BibTeX Entries (cited but not in .bib)
-- `smith2023` — cited in intro.tex:45
-- `jones2022deep` — cited in methods.md:112
+Audit prompt includes: `<bib_index>` with parsed entries, `<draft_files>` with paths to files containing citations, `<state>` with STATE.md.
 
-### ⚠️ Unused References (in .bib but never cited)
-- `oldpaper1999` — consider removing or citing
-- `tangential2020` — consider removing or citing
+Agent performs: extract in-text citations, cross-reference vs BibTeX keys, check required fields by entry type, identify duplicates, flag suspicious years.
 
-### ⚠️ Incomplete Entries (missing required fields)
-- `chen2021` — missing: journal
-- `kumar2022` — missing: booktitle
+## 4. Handle Formatter Return
 
-### ✓ Valid Citations: [N]
-### ✓ Valid BibTeX Entries: [N]
-```
-</step>
+Present findings:
+- Missing BibTeX entries (cited but not in .bib)
+- Unused references (in .bib but never cited)
+- Incomplete entries (missing required fields)
+- Valid citation count
+
+**`## AUDIT BLOCKED`:** Present blocker (no .bib found, no .tex/.md to scan), ask user to provide file paths.
 
-<step name="offer_fixes">
-**For fixable issues:**
+## 5. Offer Fixes
 
-Use AskUserQuestion:
+Ask via AskUserQuestion:
 - header: "Fixes"
 - question: "How should I handle unused references?"
-- options:
-  - "Remove unused" — Delete entries not cited in text
-  - "Keep all" — Leave .bib unchanged
-  - "Comment out" — Keep but mark as unused
+- options: "Remove unused" | "Keep all" | "Comment out"
 
-For missing entries, offer to:
-- Search for DOI/metadata (if WebFetch available)
-- Create skeleton entry for user to complete
-- Flag for manual resolution
-</step>
+For missing entries, search using `node ~/.claude/bin/citation-fetcher.js "title"`.
 
-<step name="apply_fixes">
-Apply approved fixes to .bib file.
+## 6. Apply Fixes and Commit
 
-If removing unused:
 ```bash
-# Backup first
 cp references.bib references.bib.backup
+# Apply approved edits
+git add *.bib
+git commit -m "refs: audit and clean bibliography"
 ```
 
-Apply edits.
-</step>
+</process>
 
-<step name="commit">
-```bash
-git add *.bib
-git commit -m "$(cat <<'EOF'
-refs: audit and clean bibliography
-
-- Verified [N] citations against BibTeX
-- Removed [N] unused entries (if applicable)
-- Fixed [N] incomplete entries (if applicable)
-- [N] issues flagged for manual review
-EOF
-)"
-```
-</step>
+<offer_next>
 
-<step name="done">
-```
-Citation audit complete:
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ WTF-P ► CITATION AUDIT COMPLETE ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 - Citations in text: [N]
 - BibTeX entries: [N]
 - Issues fixed: [N]
 - Issues flagged: [N]
 
----
-
-## Manual Action Required (if any)
-
-[List of issues requiring user intervention]
-
----
+───────────────────────────────────────────
 
 ## Next Up
 
@@ -189,17 +121,14 @@ Citation audit complete:
 - `/wtfp:export-latex` — Generate LaTeX
 - `/wtfp:review-section` — Get reviewer feedback
 
----
-```
-</step>
+───────────────────────────────────────────
 
-</process>
+</offer_next>
 
 <success_criteria>
-- All in-text citations have corresponding BibTeX entries
-- All BibTeX entries have required fields
-- Unused references identified (removed or flagged)
-- No duplicate keys
-- Changes committed to git
-- User knows what manual fixes remain
+- [ ] All in-text citations cross-referenced
+- [ ] Missing entries identified and searched
+- [ ] Incomplete entries flagged
+- [ ] Unused references handled per user choice
+- [ ] Changes committed to git
 </success_criteria>

package/vendors/claude/commands/wtfp/check-todos.md

@@ -0,0 +1,152 @@
+---
+name: wtfp:check-todos
+description: Review pending todos and act on, defer, or dismiss each
+allowed-tools:
+  - Read
+  - Bash
+  - Write
+  - Glob
+  - AskUserQuestion
+---
+
+<objective>
+Review pending todos. For each, user decides: act on it, defer it, dismiss it, or mark done.
+</objective>
+
+<context>
+No arguments. Reads from .planning/todos/pending/.
+</context>
+
+<process>
+
+## 1. Validate Environment
+
+```bash
+ls .planning/ 2>/dev/null
+```
+
+If `.planning/` does not exist, output error and exit:
+```
+Error: No project found. Run /wtfp:new-paper first.
+```
+
+## 2. List Pending Todos
+
+```bash
+ls -1 .planning/todos/pending/*.md 2>/dev/null
+```
+
+If no files found:
+```
+No pending todos.
+```
+Exit.
+
+## 3. Display Banner
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ WTF-P ► PENDING TODOS ({N})
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+## 4. Process Each Todo
+
+Initialize counters:
+- acted = 0
+- deferred = 0
+- dismissed = 0
+- done = 0
+
+For each file in `.planning/todos/pending/`:
+
+1. Read the file. Parse frontmatter (created, context) and body (description).
+
+2. Present via AskUserQuestion:
+   - header: "Todo #{N}"
+   - question: "{todo description}\n\nCreated: {date} | Context: {context}"
+   - options:
+     - "Act on it now"
+     - "Defer"
+     - "Dismiss"
+     - "Done"
+     - "Skip rest"
+
+3. Handle response:
+
+   **"Act on it now":**
+   - Display the full todo content
+   - Output: "What would you like to do with this? (describe action or command)"
+   - Let user take action manually
+   - Increment acted counter
+   - Keep file in pending (user will mark done when complete)
+
+   **"Defer":**
+   - Keep file in pending
+   - Increment deferred counter
+   - Continue to next
+
+   **"Dismiss":**
+   ```bash
+   mkdir -p .planning/todos/dismissed
+   mv {file} .planning/todos/dismissed/
+   ```
+   - Increment dismissed counter
+   - Continue to next
+
+   **"Done":**
+   ```bash
+   mkdir -p .planning/todos/done
+   mv {file} .planning/todos/done/
+   ```
+   - Increment done counter
+   - Continue to next
+
+   **"Skip rest":**
+   - Break out of loop
+   - All remaining todos stay deferred
+
+## 5. Update STATE.md
+
+Count remaining pending todos:
+```bash
+ls -1 .planning/todos/pending/*.md 2>/dev/null | wc -l
+```
+
+Read STATE.md. Update "### Pending Todos" section with new count:
+```
+### Pending Todos
+
+{N} pending todo(s).
+```
+
+Or if N = 0:
+```
+### Pending Todos
+
+None.
+```
+
+## 6. Summary
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ WTF-P ► TODOS REVIEWED ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Acted on: {N}
+Deferred: {N}
+Dismissed: {N}
+Done: {N}
+Still pending: {N}
+```
+
+</process>
+
+<success_criteria>
+- [ ] Pending todos listed with count
+- [ ] Each todo presented with act/defer/dismiss/done/skip options
+- [ ] Files moved to dismissed/ or done/ subdirectories as appropriate
+- [ ] STATE.md pending count updated after review
+- [ ] Summary shows actions taken
+</success_criteria>

package/vendors/claude/commands/wtfp/checkpoint.md

@@ -0,0 +1,105 @@
+---
+name: wtfp:checkpoint
+description: Save, restore, or list paper state snapshots
+argument-hint: "[save|restore|list] [label]"
+allowed-tools:
+  - Read
+  - Bash
+  - Write
+  - Glob
+  - Grep
+  - AskUserQuestion
+---
+
+<objective>
+Save full paper state as a git-tagged checkpoint or restore from a previous one.
+
+**Orchestrator role:** Parse subcommand, execute checkpoint operation via bin/lib/checkpoint.js, report result.
+
+Enables session continuity — save state before `/clear`, restore in next session.
+</objective>
+
+<context>
+Subcommand: $ARGUMENTS
+- `save [label]` — Create checkpoint with label (e.g., "pre-discussion", "draft-1")
+- `restore [tag]` — Restore from a checkpoint tag
+- `list` — Show available checkpoints
+
+**Load project state:**
+@.planning/STATE.md
+</context>
+
+<process>
+
+## 1. Parse Subcommand
+
+Extract subcommand and arguments from $ARGUMENTS.
+
+Default: `save` if no subcommand provided, with auto-generated label from STATE.md position.
+
+## 2. Execute Operation
+
+### Save
+
+```bash
+node -e "
+const cp = require('$HOME/.claude/bin/lib/checkpoint.js');
+const result = cp.createCheckpoint({
+  planningDir: '.planning',
+  label: '[label]',
+  note: '[current position from STATE.md]'
+});
+console.log(JSON.stringify(result));
+"
+```
+
+### Restore
+
+If no tag provided, list checkpoints and ask via AskUserQuestion:
+- header: "Checkpoint"
+- question: "Which checkpoint to restore?"
+- options: [list of available checkpoints]
+
+```bash
+node -e "
+const cp = require('$HOME/.claude/bin/lib/checkpoint.js');
+cp.restoreCheckpoint('[tag]');
+"
+```
+
+### List
+
+```bash
+node -e "
+const cp = require('$HOME/.claude/bin/lib/checkpoint.js');
+const list = cp.listCheckpoints();
+list.forEach(c => console.log(c.tag + ' — ' + c.message));
+"
+```
+
+## 3. Present Result
+
+</process>
+
+<offer_next>
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ WTF-P ► CHECKPOINT [SAVED|RESTORED] ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Tag: [tag]
+Files: [N]
+
+───────────────────────────────────────────
+
+Resume with `/wtfp:progress` after restoring.
+
+───────────────────────────────────────────
+
+</offer_next>
+
+<success_criteria>
+- [ ] Checkpoint created/restored/listed successfully
+- [ ] Git tag created (for save)
+- [ ] State verified after restore
+</success_criteria>

package/vendors/claude/commands/wtfp/contribute.md

@@ -1,6 +1,6 @@
 ---
 name: wtfp:contribute
-description: Guide through contributing code to WTF-P via Pull Request
+description: Walk through contributing code to WTF-P via pull request
 allowed-tools:
   - Bash
   - Read