wtf-p 0.3.0 → 0.5.0

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

@@ -0,0 +1,266 @@
+---
+name: wtfp:contribute
+description: Walk through contributing code to WTF-P via pull request
+---
+
+<objective>
+Guide the user through the complete process of contributing code to WTF-P, from fork to Pull Request.
+</objective>
+
+<context>
+@~/.opencode/write-the-f-paper/references/github-contrib.md
+@~/.opencode/CONTRIBUTING.md
+</context>
+
+<process>
+
+## Step 1: Verify Prerequisites
+
+Check tools are available:
+```bash
+gh auth status 2>&1
+git --version
+node --version
+```
+
+If `gh` not authenticated:
+> Run `gh auth login` to authenticate with GitHub.
+
+## Step 2: Understand Contribution Type
+
+Use the question tool:
+
+**Question 1: What are you contributing?**
+- Header: "Type"
+- Options:
+  - "New command" - Add a /wtfp:* slash command
+  - "Bug fix" - Fix an existing issue
+  - "Workflow improvement" - Enhance a writing workflow
+  - "Documentation" - Improve docs or add examples
+  - "Other" - Something else
+
+**Question 2: Do you have an existing issue?**
+- Header: "Issue"
+- Options:
+  - "Yes, issue #___" - Link to existing issue
+  - "No, creating fresh" - New contribution without issue
+  - "I'll create one first" - Redirect to /wtfp:request-feature
+
+## Step 3: Setup Repository
+
+Check current state:
+```bash
+git remote -v
+```
+
+**If in wtf-p repo (maintainer):**
+```bash
+git checkout main
+git pull origin main
+git checkout -b [BRANCH_TYPE]/[SHORT_NAME]
+```
+
+**If not in wtf-p repo (external contributor):**
+```bash
+# Fork and clone
+gh repo fork akougkas/wtf-p --clone
+cd wtf-p
+
+# Create branch
+git checkout -b [BRANCH_TYPE]/[SHORT_NAME]
+```
+
+Branch naming:
+- `feat/add-citation-check` for features
+- `fix/install-path-spaces` for bugs
+- `docs/improve-readme` for documentation
+
+## Step 4: Guide Implementation
+
+Based on contribution type:
+
+### For New Command
+
+1. Show command template:
+```markdown
+---
+name: wtfp:command-name
+description: Brief description
+---
+
+<objective>
+What this command accomplishes.
+</objective>
+
+<context>
+@~/.opencode/write-the-f-paper/references/[relevant].md
+</context>
+
+<process>
+## Step 1: ...
+## Step 2: ...
+</process>
+```
+
+2. Create file in `commands/wtfp/[name].md`
+
+3. Follow naming conventions:
+   - `new-*` for creation
+   - `create-*` for generation
+   - `plan-*` for planning
+   - `write-*` for execution
+   - `review-*` for review
+   - `check-*` for validation
+   - `export-*` for output
+
+### For Bug Fix
+
+1. Identify the file(s) to modify
+2. Make minimal, focused changes
+3. Add test coverage if applicable
+
+### For Workflow Improvement
+
+1. Edit file in `write-the-f-paper/workflows/`
+2. If WCN version exists, update both `.md` and `.wcn.md`
+
+## Step 5: Test Changes
+
+```bash
+# Run existing tests
+npm test
+
+# Install locally for manual testing
+node bin/install.js --local --force
+
+# Test in Claude Code
+# /wtfp:your-new-command
+```
+
+Ask user to verify:
+- Does the feature work as expected?
+- Any edge cases to handle?
+- Error messages clear?
+
+## Step 6: Commit Changes
+
+Stage files:
+```bash
+git add [FILES]
+git status
+```
+
+Commit with conventional message:
+```bash
+git commit -m "[TYPE]([SCOPE]): [DESCRIPTION]
+
+[Optional body explaining why]
+
+[Closes #XX if applicable]"
+```
+
+Examples:
+- `feat(commands): add citation-check command`
+- `fix(cli): handle paths with spaces`
+- `docs(readme): clarify installation steps`
+
+## Step 7: Push and Create PR
+
+Push branch:
+```bash
+git push -u origin [BRANCH_NAME]
+```
+
+Create PR:
+```bash
+gh pr create \
+  --repo akougkas/wtf-p \
+  --title "[TYPE]([SCOPE]): [DESCRIPTION]" \
+  --body "$(cat <<'EOF'
+## Summary
+[What this PR does]
+
+## Changes
+- [Change 1]
+- [Change 2]
+
+## Testing
+- [ ] `npm test` passes
+- [ ] Manually tested in Claude Code
+- [ ] [Specific test scenario]
+
+## Related Issues
+[Closes #XX or References #XX]
+EOF
+)"
+```
+
+## Step 8: Post-PR Guidance
+
+After PR is created:
+
+1. **Show PR URL** to user
+2. **Explain review process:**
+   - Maintainer will review within a few days
+   - May request changes or ask questions
+   - Once approved, will be merged to main
+
+3. **Next steps:**
+   - Watch for review comments
+   - Respond to feedback
+   - Update PR if changes requested
+
+</process>
+
+<templates>
+
+## PR Title Format
+```
+<type>(<scope>): <description>
+```
+
+Types: feat, fix, docs, refactor, test, chore
+Scopes: commands, workflows, cli, templates
+
+## PR Body Template
+```markdown
+## Summary
+Brief description of what this PR accomplishes.
+
+## Changes
+- Added/Modified/Removed X
+- Updated Y to do Z
+
+## Testing
+How to verify this works:
+1. Install locally: `node bin/install.js --local`
+2. Run: `/wtfp:command`
+3. Expected: [outcome]
+
+## Screenshots (if UI changes)
+[Paste screenshots here]
+
+## Related Issues
+Closes #XX
+```
+
+</templates>
+
+<error-handling>
+
+**Fork already exists:** Use existing fork
+```bash
+gh repo sync [USERNAME]/wtf-p
+```
+
+**Branch already exists:**
+```bash
+git checkout [BRANCH]
+git pull origin main
+```
+
+**Push rejected:** Need to pull first or force push (with caution)
+
+**PR creation fails:** Check if branch was pushed, verify gh auth
+
+</error-handling>

package/vendors/opencode/commands/wtfp/create-outline.md

@@ -0,0 +1,181 @@
+---
+name: wtfp:create-outline
+description: Build section outline, argument map, and word budgets
+---
+
+<execution_context>
+@~/.opencode/write-the-f-paper/workflows/create-outline.md
+@~/.opencode/write-the-f-paper/templates/roadmap.md
+@~/.opencode/write-the-f-paper/templates/state.md
+@~/.opencode/write-the-f-paper/references/imrad-structure.md
+</execution_context>
+
+<objective>
+Create the document outline and section roadmap for an initialized paper.
+
+**Orchestrator role:** Validate environment, load project context, resolve model profile, spawn outliner agent to produce structure artifacts, create STATE.md, create section directories, commit, present results.
+
+**Why subagent:** Outlining requires significant reasoning about document structure, argument decomposition, and wave assignment. A fresh outliner agent gets peak quality for these creative decisions.
+</objective>
+
+<context>
+No arguments. Requires `.planning/PROJECT.md` to exist.
+</context>
+
+<process>
+
+## 1. Validate Environment and Resolve Model Profile
+
+```bash
+[ ! -f .planning/PROJECT.md ] && echo "ERROR: No project. Run /wtfp:new-paper" && exit 1
+[ -f .planning/ROADMAP.md ] && echo "ERROR: Outline exists. Use /wtfp:progress" && exit 1
+ls .planning/ 2>/dev/null
+```
+
+**Resolve model profile:**
+
+```bash
+MODEL_PROFILE=$(cat .planning/config.json 2>/dev/null | grep -o '"model_profile"[[:space:]]*:[[:space:]]*"[^"]*"' | grep -o '"[^"]*"$' | tr -d '"' || echo "balanced")
+```
+
+**Model lookup table:**
+
+| Agent | quality | balanced | budget |
+|-------|---------|----------|--------|
+| outliner | opus | sonnet | sonnet |
+
+**Resolve gate flag:**
+```bash
+GATE_CONFIRM_OUTLINE=$(cat .planning/config.json 2>/dev/null | grep -o '"confirm_outline"[[:space:]]*:[[:space:]]*[^,}]*' | grep -o 'true\|false' || echo "true")
+```
+
+## 2. Read Context Files
+
+```bash
+PROJECT_CONTENT=$(cat .planning/PROJECT.md)
+CONFIG_CONTENT=$(cat .planning/config.json 2>/dev/null)
+EXISTING_STRUCTURE=$(cat .planning/structure/*.md 2>/dev/null)
+```
+
+## 3. Ensure Structure Directory
+
+```bash
+mkdir -p .planning/structure
+mkdir -p .planning/sections
+```
+
+## 4. Gate Check: Confirm Before Outlining
+
+**If GATE_CONFIRM_OUTLINE is "true" (default):**
+Present project summary to user via the question tool and wait for confirmation before proceeding.
+
+**If GATE_CONFIRM_OUTLINE is "false":**
+Skip confirmation and proceed directly to outlining.
+
+## 5. Spawn wtfp-outliner Agent
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ WTF-P ► OUTLINING DOCUMENT
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Fill prompt with inlined content and spawn:
+
+```
+Task(
+  prompt="First, read ~/.opencode/agents/wtfp/outliner.md for your role and instructions.\n\n" + filled_outlining_prompt,
+  subagent_type="general-purpose",
+  model="{outliner_model}",
+  description="Create Document Outline"
+)
+```
+
+Outlining prompt includes: `<project_context>` with PROJECT.md content, config.json settings, any existing structure files.
+
+## 6. Handle Outliner Return
+
+**`## OUTLINING COMPLETE`:** Proceed to STATE.md creation and directory setup.
+
+**`## CHECKPOINT REACHED`:** Present to user, get response, re-spawn outliner with decision.
+
+**`## OUTLINING BLOCKED`:** Show blocker, offer options.
+
+## 7. Post-Outliner Setup
+
+After successful outlining, the orchestrator handles:
+
+**Create STATE.md** using template from `~/.opencode/write-the-f-paper/templates/state.md`:
+- Initialize position (section 1 of N), word count (0)
+- Set argument strength from outliner's argument-map
+- Set open questions from PROJECT.md
+
+**Create section directories** from ROADMAP.md sections:
+```bash
+mkdir -p .planning/sections/01-[section-slug]
+mkdir -p .planning/sections/02-[section-slug]
+# ... for all sections listed in ROADMAP.md
+```
+
+## 8. Commit (with commit_docs Guard)
+
+```bash
+COMMIT_DOCS=$(cat .planning/config.json 2>/dev/null | grep -o '"commit_docs"[[:space:]]*:[[:space:]]*[^,}]*' | grep -o 'true\|false' || echo "true")
+```
+
+**If commit_docs = "true" (default):**
+```bash
+git add .planning/ROADMAP.md .planning/STATE.md .planning/sections/ .planning/structure/
+git commit -m "docs: create document outline -- [N] sections, [X] words target"
+```
+
+**If commit_docs = "false":**
+Skip git add and commit for planning docs. Log: "Skipping planning docs commit (commit_docs: false)"
+
+## 9. Present Final Status
+
+</process>
+
+<offer_next>
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ WTF-P ► OUTLINE CREATED ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+- Roadmap: .planning/ROADMAP.md ([N] sections, [X] words)
+- State: .planning/STATE.md
+- Structure: .planning/structure/ (outline, argument-map, narrative-arc)
+- Sections: .planning/sections/ ([N] directories)
+
+| # | Section | Words | Wave |
+|---|---------|-------|------|
+[table from ROADMAP.md]
+
+───────────────────────────────────────────
+
+## ▶ Next Up
+
+**Section 1: [Name]** — [goal]
+
+`/wtfp:plan-section 1`
+
+<sub>`/clear` first → fresh context window</sub>
+
+───────────────────────────────────────────
+
+**Also available:**
+- `/wtfp:discuss-section 1` — gather context first
+- `/wtfp:research-gap 1` — investigate literature needs
+- `/wtfp:execute-outline` — write all sections in wave-based parallel execution
+
+</offer_next>
+
+<success_criteria>
+- [ ] Outliner agent spawned with full project context
+- [ ] 4 artifacts created (outline.md, argument-map.md, narrative-arc.md, ROADMAP.md)
+- [ ] STATE.md initialized with correct position
+- [ ] Section directories created
+- [ ] Word budget totals match target
+- [ ] All committed to git
+- [ ] User knows next steps
+</success_criteria>

package/vendors/opencode/commands/wtfp/create-poster.md

@@ -0,0 +1,37 @@
+---
+name: wtfp:create-poster
+description: Generate academic poster from paper content
+---
+
+<objective>
+Generate an academic poster based on the current project's PROJECT.md and findings.
+Uses the wtfp-marp skill to compile to HTML.
+</objective>
+
+<context>
+@~/.opencode/write-the-f-paper/references/principles.md
+@~/.opencode/write-the-f-paper/templates/posters/basic.md
+</context>
+
+<process>
+## Step 1: Content Synthesis
+- Read `.planning/PROJECT.md` and any drafted sections.
+- Identify key findings, methodology, and conclusion.
+
+## Step 2: User Interview
+the question tool to determine:
+- Poster title (default to project title)
+- Authors
+- Key visuals/charts needed
+- Target audience
+
+## Step 3: Markdown Generation
+- Create `poster.md` using Marp format.
+- Integrate synthesized content.
+
+## Step 4: Compilation
+- Use `wtfp-marp` skill: `npx @marp-team/marp-cli poster.md -o poster.html`
+
+## Step 5: Review
+- Present the generated poster.html path to the user.
+</process>

package/vendors/opencode/commands/wtfp/create-slides.md

@@ -0,0 +1,36 @@
+---
+name: wtfp:create-slides
+description: Generate presentation slides from paper content
+---
+
+<objective>
+Generate presentation slides based on the current project's PROJECT.md and findings.
+Uses the wtfp-marp skill to compile to PDF.
+</objective>
+
+<context>
+@~/.opencode/write-the-f-paper/references/principles.md
+@~/.opencode/write-the-f-paper/templates/slides/
+</context>
+
+<process>
+## Step 1: Content Synthesis
+- Read `.planning/PROJECT.md` and any drafted sections.
+- Identify the core narrative and supporting claims.
+
+## Step 2: User Interview
+the question tool to determine:
+- Presentation duration/target number of slides
+- Specific focus areas
+- Audience background
+
+## Step 3: Markdown Generation
+- Create `slides.md` using Marp format.
+- Separate slides with `---`.
+
+## Step 4: Compilation
+- Use `wtfp-marp` skill: `npx @marp-team/marp-cli slides.md -o slides.pdf`
+
+## Step 5: Review
+- Present the generated slides.pdf path to the user.
+</process>

package/vendors/opencode/commands/wtfp/discuss-section.md

@@ -0,0 +1,63 @@
+---
+name: wtfp:discuss-section
+description: Discuss your vision for a section before planning it
+---
+
+<objective>
+Gather section context through collaborative thinking before planning.
+
+Purpose: Help the user articulate their vision for how a section should read, what it needs to accomplish, and what makes it effective.
+Output: CONTEXT.md file in the section directory capturing vision, essential content, and boundaries.
+</objective>
+
+<execution_context>
+@~/.opencode/write-the-f-paper/workflows/discuss-section.md
+@~/.opencode/write-the-f-paper/templates/context.md
+</execution_context>
+
+<context>
+Section number: $ARGUMENTS (required)
+
+**Load project state first:**
+@.planning/STATE.md
+
+**Load roadmap:**
+@.planning/ROADMAP.md
+
+**Load structure documents:**
+@.planning/structure/argument-map.md
+@.planning/structure/outline.md
+</context>
+
+<process>
+
+<step name="verify">
+1. Check .planning/ directory exists (error if not - user should run /wtfp:new-paper)
+2. Validate section number provided via $ARGUMENTS
+3. Validate section exists in roadmap
+</step>
+
+<step name="execute_workflow">
+Execute the discuss-section workflow from execution_context.
+
+The workflow will:
+- Validate section against roadmap
+- Check for existing CONTEXT.md
+- Gather vision through the question tool (not interrogation)
+- Write CONTEXT.md capturing user's vision
+- Commit to git
+</step>
+
+<step name="done">
+Workflow outputs next steps to user (typically: research or plan the section).
+</step>
+
+</process>
+
+<success_criteria>
+- Section validated against roadmap
+- Vision gathered through collaborative thinking
+- CONTEXT.md created in section directory
+- CONTEXT.md committed to git
+- User knows next steps
+</success_criteria>