wtf-p 0.3.0 → 0.5.0

package/core/write-the-f-paper/workflows/execute-outline.md

@@ -0,0 +1,163 @@
+<purpose>
+Execute all document sections via wave-based parallel execution. Sections are grouped
+by wave number (from PLAN.md frontmatter). Each wave runs in parallel; waves execute
+sequentially. After the final wave, spawn coherence-checker for cross-section verification.
+</purpose>
+
+<process>
+
+<step name="load_state" priority="first">
+Before any operation, read project state:
+
+```bash
+cat .planning/STATE.md 2>/dev/null
+cat .planning/config.json 2>/dev/null
+```
+
+Parse current position, accumulated decisions. Load planning config.
+
+```bash
+MODEL_PROFILE=$(cat .planning/config.json 2>/dev/null | grep -o '"model_profile"[[:space:]]*:[[:space:]]*"[^"]*"' | grep -o '"[^"]*"$' | tr -d '"' || echo "balanced")
+```
+</step>
+
+<step name="validate_environment">
+Verify outline exists and plans are ready:
+
+```bash
+[ ! -f .planning/ROADMAP.md ] && echo "ERROR: No outline. Run /wtfp:create-outline" && exit 1
+```
+
+Check that PLAN.md files exist for sections:
+```bash
+PLAN_COUNT=$(ls .planning/sections/*/*-PLAN.md 2>/dev/null | wc -l)
+[ "$PLAN_COUNT" -eq 0 ] && echo "ERROR: No plans found. Run /wtfp:plan-section for each section" && exit 1
+```
+
+Check for already-completed sections (SUMMARY.md exists):
+```bash
+SUMMARY_COUNT=$(ls .planning/sections/*/*-SUMMARY.md 2>/dev/null | wc -l)
+```
+
+If all sections already have SUMMARYs, warn: "All sections already written. Re-execute?"
+</step>
+
+<step name="build_wave_plan">
+Parse ROADMAP.md and all PLAN.md files to group by wave:
+
+```bash
+for plan in .planning/sections/*/*-PLAN.md; do
+  section_dir=$(dirname "$plan")
+  section_name=$(basename "$section_dir")
+  wave=$(grep -m1 'wave:' "$plan" | grep -o '[0-9]*')
+  echo "wave=$wave section=$section_name plan=$plan"
+done | sort -t= -k2 -n
+```
+
+Build execution plan:
+- Group sections by wave number
+- Within each wave: list all plans per section
+- Identify max_wave for termination
+
+Present plan before execution.
+</step>
+
+<step name="resolve_models">
+Resolve models from profile for writer and coherence-checker:
+
+| Agent | quality | balanced | budget |
+|-------|---------|----------|--------|
+| section-writer | opus | sonnet | sonnet |
+| coherence-checker | sonnet | sonnet | haiku |
+
+Store writer_model and checker_model for spawn calls.
+</step>
+
+<step name="execute_waves">
+For wave = 1 to max_wave:
+
+**1. Display wave banner** with section list.
+
+**2. For each section in wave:**
+   - Find all PLAN.md files for the section
+   - Load section-specific context (CONTEXT.md, RESEARCH.md, prior SUMMARYs)
+   - Spawn Task() for each plan with section-writer agent
+
+   ```
+   Task(
+     prompt="First, read ~/.claude/agents/wtfp/section-writer.md...\n\n" + context,
+     subagent_type="general-purpose",
+     model="{writer_model}",
+     description="Write {section-name}"
+   )
+   ```
+
+   Sections within the same wave spawn in parallel.
+
+**3. Collect returns** from all writers in this wave.
+
+**4. Handle results:**
+   - WRITING COMPLETE: Update STATE.md, mark section in ROADMAP.md
+   - CHECKPOINT REACHED: Present to user, get response
+   - WRITING BLOCKED: Present to user with options (retry, skip, abort)
+
+**5. Verify all wave sections resolved** before proceeding to next wave.
+
+**6. Update progress** in STATE.md and ROADMAP.md.
+</step>
+
+<step name="spawn_coherence_checker">
+After the final wave completes:
+
+Read all written content inline:
+```bash
+ALL_PAPER_CONTENT=$(cat paper/*.md 2>/dev/null)
+ARGMAP=$(cat .planning/structure/argument-map.md 2>/dev/null)
+NARRATIVE=$(cat .planning/structure/narrative-arc.md 2>/dev/null)
+OUTLINE=$(cat .planning/structure/outline.md 2>/dev/null)
+```
+
+Spawn coherence-checker with explicit inline context (not file references):
+
+```
+Task(
+  prompt="First, read ~/.claude/agents/wtfp/coherence-checker.md...\n\n" +
+    "<paper_content>" + ALL_PAPER_CONTENT + "</paper_content>" +
+    "<argument_map>" + ARGMAP + "</argument_map>" +
+    "<narrative_arc>" + NARRATIVE + "</narrative_arc>" +
+    "<outline>" + OUTLINE + "</outline>",
+  subagent_type="general-purpose",
+  model="{checker_model}",
+  description="Verify Cross-Section Coherence"
+)
+```
+
+**Why inline:** Coherence-checker is read-only and needs all content in context. File references would require the agent to re-read everything, wasting context budget.
+</step>
+
+<step name="handle_coherence_result">
+Route based on coherence-checker return:
+
+**COHERENT:** All sections pass cross-verification.
+- Update STATE.md with coherence status
+- Proceed to completion
+
+**GAPS FOUND:** Issues detected across sections.
+- Present gap list to user
+- Options:
+  - Fix now: Re-spawn writers for affected sections
+  - Accept: Proceed with known gaps
+  - Plan revision: Create revision plans for affected sections
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] Wave execution plan built from ROADMAP.md and PLAN.md frontmatter
+- [ ] All waves executed in dependency order
+- [ ] Parallel Task() spawns within each wave
+- [ ] Checkpoints handled between waves
+- [ ] Coherence-checker spawned after final wave with inline paper content
+- [ ] Coherence result routed (COHERENT or GAPS FOUND)
+- [ ] STATE.md and ROADMAP.md updated throughout
+</success_criteria>

package/core/write-the-f-paper/workflows/execute-outline.wcn.md

@@ -0,0 +1,73 @@
+<purpose>
+Execute all sections via wave-based parallel execution. Sections grouped by wave number.
+Each wave runs parallel; waves run sequentially. After final wave, spawn coherence-checker.
+</purpose>
+
+<process>
+
+[step:load_state p=1]
+RUN: cat .planning/STATE.md 2>/dev/null
+RUN: cat .planning/config.json 2>/dev/null
+RESOLVE: MODEL_PROFILE from config (default: balanced)
+[/step]
+
+[step:validate_environment]
+REQUIRE: .planning/ROADMAP.md (else: /wtfp:create-outline)
+REQUIRE: .planning/sections/*/*-PLAN.md (else: /wtfp:plan-section)
+CHECK: existing SUMMARY.md count (warn if all complete)
+[/step]
+
+[step:build_wave_plan]
+PARSE: all PLAN.md frontmatter for wave numbers
+GROUP: sections by wave (wave 1 = independent, wave N = depends on N-1)
+PRESENT: execution plan (waves, sections per wave, total words)
+[/step]
+
+[step:resolve_models]
+MODEL_TABLE{agent,quality,balanced,budget}:
+  section-writer | opus | sonnet | sonnet
+  coherence-checker | sonnet | sonnet | haiku
+STORE: writer_model, checker_model
+[/step]
+
+[step:execute_waves]
+FOR wave = 1 to max_wave:
+  1. EMIT: wave banner with section list
+  2. FOR each section in wave:
+     - LOAD: CONTEXT.md, RESEARCH.md, prior SUMMARYs
+     - SPAWN: Task(section-writer, model=writer_model) per PLAN.md
+     - Parallel within wave
+  3. COLLECT: all returns
+  4. ROUTE:
+     - WRITING COMPLETE → update STATE.md, ROADMAP.md
+     - CHECKPOINT REACHED → present to user, get response
+     - WRITING BLOCKED → present options: retry | skip | abort
+  5. VERIFY: all wave sections resolved before next wave
+  6. UPDATE: progress in STATE.md
+[/step]
+
+[step:spawn_coherence_checker]
+AFTER final wave:
+READ_INLINE: paper/*.md, argument-map.md, narrative-arc.md, outline.md
+SPAWN: Task(coherence-checker, model=checker_model)
+  CONTEXT: <paper_content>, <argument_map>, <narrative_arc>, <outline> (all inline)
+NOTE: inline context avoids redundant file reads in checker agent
+[/step]
+
+[step:handle_coherence_result]
+ROUTE:
+  COHERENT → update STATE.md, proceed to completion
+  GAPS FOUND → present gaps, OPTIONS: fix now | accept | plan revision
+[/step]
+
+</process>
+
+<success_criteria>
+- [ ] Wave execution plan built from ROADMAP.md and PLAN.md frontmatter
+- [ ] All waves executed in dependency order
+- [ ] Parallel Task() spawns within each wave
+- [ ] Checkpoints handled between waves
+- [ ] Coherence-checker spawned after final wave with inline paper content
+- [ ] Coherence result routed (COHERENT or GAPS FOUND)
+- [ ] STATE.md and ROADMAP.md updated throughout
+</success_criteria>

package/core/write-the-f-paper/workflows/execute-section.wcn.md

@@ -1,219 +1,191 @@
 <purpose>
-Execute a section prompt (PLAN.md) and create the outcome summary (SUMMARY.md).
+Execute a section prompt (PLAN.md) via thin orchestrator pattern. Orchestrator validates, loads context, resolves model profile, spawns section-writer agent, then runs argument-verifier for goal-backward verification. Creates SUMMARY.md.
 </purpose>
 
+<architecture>
+ORCHESTRATOR: /wtfp:write-section (this command)
+AGENTS: section-writer (executes PLAN.md, writes prose), argument-verifier (goal-backward check)
+PATTERN: Orchestrator loads context → spawns writer → spawns verifier → handle gaps
+WHY_SUBAGENTS: Writer gets fresh context window with full PLAN.md + project context. Verifier checks independently whether section achieves its purpose, not just that tasks completed.
+</architecture>
+
 <required_reading>
+READ: ~/.claude/write-the-f-paper/references/orchestrator-pattern.md
+READ: ~/.claude/write-the-f-paper/references/context-fidelity.md
+READ: ~/.claude/write-the-f-paper/references/agent-model-matrix.md
+READ: ~/.claude/write-the-f-paper/references/git-integration.md
 Read STATE.md before any operation to load project context.
 </required_reading>
 
 <process>
 
-[step:load_project_state p=1]
+[step:validate_and_resolve_model p=1]
+RUN: ls .planning/ 2>/dev/null
+RUN: MODEL_PROFILE=$(cat .planning/config.json 2>/dev/null | grep -o '"model_profile"[[:space:]]*:[[:space:]]*"[^"]*"' | grep -o '"[^"]*"$' | tr -d '"' || echo "balanced")
+
+MODEL_LOOKUP{agent,quality,balanced,budget}:
+  section-writer | opus | sonnet | sonnet
+  argument-verifier | sonnet | sonnet | haiku
+
+RESOLVE: writer_model, verifier_model from MODEL_PROFILE
+[/step]
+
+[step:load_project_state]
 RUN: cat .planning/STATE.md 2>/dev/null
 PARSE: current, word, argument, open
 IF file_exists → parse_fields
-IF file_missing_but_.planning/_exists → ```
-IF .planning/_doesnt_exist → ERROR ""
+IF file_missing_but_.planning/_exists → OFFER reconstruct|continue
+IF .planning/_doesnt_exist → ERROR "project not initialized"
 [/step]
 
 [step:identify_plan]
 RUN: cat .planning/ROADMAP.md
 RUN: cat .planning/config.json 2>/dev/null
+FIND: first PLAN without matching SUMMARY in section dir
+IF ambiguous → ASK user which plan
 [/step]
 
-[step:record_start_time]
-RUN: PLAN_START_TIME=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
-[/step]
+[step:load_context_md]
+CRITICAL: Load CONTEXT.md early, pass to writer agent.
 
-[step:load_prompt]
-RUN: cat .planning/sections/XX-name/{section}-{plan}-PLAN.md
-IF plan_references_CONTEXT.md → The CONTEXT.md file provides the user's vision ...
-[/step]
+RUN: SECTION_DIR=$(ls -d .planning/sections/${SECTION}-* 2>/dev/null | head -1)
+RUN: CONTEXT_CONTENT=$(cat "${SECTION_DIR}"/*-CONTEXT.md 2>/dev/null)
+RUN: PLAN_CONTENT=$(cat "${SECTION_DIR}"/${SECTION}-${PLAN}-PLAN.md)
 
-[step:previous_section_check]
+CONTEXT.md rules:
+  Locked decisions → writer MUST implement exactly
+  Deferred ideas → writer MUST NOT include
+  Discretion areas → writer uses judgment
 [/step]
 
-[step:execute]
-IF `type=auto` → - Determine writing mode from task (co-author, ...
-IF mode=co-author → Write the prose directly
-IF mode=scaffold → Create detailed outline for user to fill
-IF mode=reviewer → Analyze existing text, provide feedback
+[step:record_start_time]
+RUN: PLAN_START_TIME=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
 [/step]
 
-<writing_modes>
-## Writing Mode Execution
-
-**Co-Author Mode (Claude drafts):**
-- Write complete prose following outline/structure
-- Match user's voice from prior sections
-- Flag claims needing citations with [CITE: topic]
-- Flag uncertain statements with [VERIFY: claim]
-- Aim for word target specified in task
-
-**Scaffold Mode (Claude outlines):**
-- Create detailed paragraph-level outline
-- Specify what each paragraph should accomplish
-- Identify where citations should go
-- Note transition needs between paragraphs
-- Leave actual prose writing to user
-
-**Reviewer Mode (Claude critiques):**
-- Read existing text carefully
-- Identify strengths first
-- Note logical gaps or weak arguments
-- Suggest specific improvements
-- Ask clarifying questions before major changes
-</writing_modes>
-
-<deviation_rules>
-
-## Automatic Adjustment Handling
-
-**While writing, you WILL discover issues.** This is normal.
-
-Apply these rules automatically. Track all adjustments for Summary documentation.
-
----
-
-[rule:autofix_factual_errors]
-TRIGGER: incorrect_fact | wrong_citation | logical_contradiction
-ACTION: fix immediately + track for summary
-PERMISSION: none_required
-[/rule]---
-
-[rule:autoadd_missing_critical_elements]
-TRIGGER: required_element_missing_for_section_completeness
-ACTION: add immediately + track for summary
-[/rule]---
-
-[rule:autofix_blocking_issues]
-TRIGGER: something_prevents_completing_the_writing_task
-ACTION: fix immediately to unblock + track for summary
-[/rule]---
-
-[rule:ask_about_structural_changes]
-TRIGGER: writing_requires_significant_restructuring
-ACTION: stop + present to user + wait for decision
-[/rule]---
-
-[rule:log_enhancement_ideas]
-TRIGGER: improvement_that_would_enhance_writing_but_isn't_essential_now
-ACTION: add to notes automatically + continue writing
-[/rule]---
-
-**RULE PRIORITY (when multiple could apply):**
-
-1. **If Rule 4 applies** → STOP and ask (structural decision)
-2. **If Rules 1-3 apply** → Fix automatically, track for Summary
-3. **If Rule 5 applies** → Log for later, continue
-
-</deviation_rules>
-
-<three_layer_verification>
-## Verification During Execution
-
-After each task, run verification checks:
-
-**1. Citation Check (Mechanical)**
-- All claims have citations or are clearly original claims
-- Citations formatted correctly
-- No [CITE: ] placeholders remaining
-- Page numbers where style requires
-
-**2. Argument Coherence (Logical)**
-- Claims follow from evidence
-- No logical contradictions with prior sections
-- Thesis supported by content
-- Flow between paragraphs makes sense
-
-**3. Rubric Check (Requirements)**
-- Word count within target range
-- Required elements present
-- Formatting requirements met
-- Section accomplishes its goal
-</three_layer_verification>
-
-<task_commit>
-## Task Commit Protocol
-
-After each task completes (verification passed, done criteria met), commit immediately:
-
-**1. Identify modified files:**
-
-Track files changed during this specific task:
-
-```bash
-git status --short
-```
-
-**2. Stage only task-related files:**
-
-```bash
-# Example - adjust to actual files modified
-git add paper/sections/introduction.md
-git add paper/references.bib
-```
-
-**3. Determine commit type:**
-
-| Type | When to Use | Example |
-|------|-------------|---------|
-| `content` | New prose, new paragraphs | content(02-01): draft introduction hook |
-| `cite` | Adding/fixing citations | cite(02-01): add Smith2023 to literature review |
-| `revise` | Revising existing text | revise(02-01): strengthen thesis statement |
-| `fix` | Fixing errors | fix(02-01): correct misattributed quote |
-| `structure` | Reorganizing | structure(02-01): reorder methods subsections |
-
-**4. Craft commit message:**
-
-```bash
-git commit -m "{type}({section}-{plan}): {task description}
-
-- {key change 1}
-- {key change 2}
-"
-```
-
-**5. Record commit hash for SUMMARY.md**
-</task_commit>
-
-[step:checkpoint_protocol]
+[step:spawn_section_writer]
+EMIT:
+  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+   WTF-P ► WRITING SECTION {X} PLAN {Y}
+  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+BUILD writer_prompt with inlined content:
+- <writing_context> STATE, PROJECT, ROADMAP, prior summaries, structure docs
+- <plan> full PLAN.md content
+- <user_decisions> CONTEXT_CONTENT (from CONTEXT.md)
+- <output> target paper file path, SUMMARY.md path
+
+SPAWN:
+  Task(
+    prompt="First, read ~/.claude/agents/wtfp/section-writer.md for your role and instructions.\n\n" + writer_prompt,
+    subagent_type="general-purpose",
+    model="{writer_model}",
+    description="Write Section {X} Plan {Y}"
+  )
+
+HANDLE returns:
+  "## WRITING COMPLETE" → proceed to argument-verifier
+  "## CHECKPOINT REACHED" → present to user, wait, then resume agent
+  "## WRITING BLOCKED" → present blocker, ask user
 [/step]
 
-[step:verification_failure_gate]
+[step:spawn_argument_verifier]
+IF config.workflow.verifier=false → SKIP to record_completion
+
+GOAL-BACKWARD VERIFICATION: Does written prose achieve section's purpose?
+Not "did tasks complete" but "does the output deliver what the section promises?"
+
+BUILD verifier_prompt:
+- <plan> original PLAN.md (what was intended)
+- <written_content> actual paper output (what was produced)
+- <user_decisions> CONTEXT_CONTENT (what user wanted)
+- <structure> argument-map.md, outline.md (what structure expects)
+
+SPAWN:
+  Task(
+    prompt="First, read ~/.claude/agents/wtfp/argument-verifier.md for your role and instructions.\n\n" + verifier_prompt,
+    subagent_type="general-purpose",
+    model="{verifier_model}",
+    description="Verify Section {X} Plan {Y}"
+  )
+
+HANDLE returns:
+  "VERIFIED" → proceed to record_completion
+  "GAPS_FOUND" → present gaps to user, offer: fix now | note for later | accept as-is
+  "HUMAN_NEEDED" → present concern, wait for user decision
 [/step]
 
 [step:record_completion_time]
 RUN: PLAN_END_TIME=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
 [/step]
 
-[step:create_summary]
-[/step]
-
 [step:update_state]
+UPDATE STATE.md: position, word count, argument strength, last activity
 [/step]
 
 [step:update_roadmap]
-IF more_plans_remain_in_this_section → - Update plan count: "2/3 plans complete"
-IF this_was_the_last_plan_in_the_section → - Mark section complete: status → "Complete"
+IF more_plans_remain_in_this_section → Update plan count: "2/3 plans complete"
+IF this_was_the_last_plan_in_the_section → Mark section complete: status → "Complete"
 [/step]
 
 [step:git_commit_metadata]
 RUN: git add .planning/sections/XX-name/{section}-{plan}-SUMMARY.md
+RUN: git add .planning/STATE.md
+RUN: git add .planning/ROADMAP.md
+COMMIT: "docs({section}-{plan}): complete [plan-name] - [N] tasks, [word-count] words"
 [/step]
 
 [step:offer_next]
 RUN: ls -1 .planning/sections/[current-section-dir]/*-PLAN.md 2>/dev/null | wc -l
+RUN: ls -1 .planning/sections/[current-section-dir]/*-SUMMARY.md 2>/dev/null | wc -l
+
+ROUTE_A (more plans remain):
+  EMIT: "{Y} of {X} plans complete. Next: /wtfp:write-section {next-plan}"
+
+ROUTE_B (section complete, more sections remain):
+  EMIT: "Section {Z} complete. Next: /wtfp:plan-section {Z+1}"
+
+ROUTE_C (document complete):
+  EMIT: "All sections complete. Next: /wtfp:submit-draft"
 [/step]
 
 </process>
 
-<success_criteria>
+<writing_modes>
+Co-Author (Claude drafts): Write prose, match voice, flag [CITE:] and [VERIFY:], hit word target.
+Scaffold (Claude outlines): Paragraph-level outline, citation placement, transitions. User writes.
+Reviewer (Claude critiques): Strengths first, gaps, suggestions. Ask before major changes.
+</writing_modes>
+
+<deviation_rules>
+RULE_PRIORITY:
+1. Rule 4 (structural changes) → STOP, ask user
+2. Rules 1-3 (errors, missing elements, blockers) → auto-fix, track for SUMMARY
+3. Rule 5 (enhancements) → log for later, continue
+
+[rule:autofix_factual_errors] TRIGGER: incorrect_fact | wrong_citation | contradiction → fix + track [/rule]
+[rule:autoadd_missing_critical] TRIGGER: required_element_missing → add + track [/rule]
+[rule:autofix_blocking] TRIGGER: something_prevents_task_completion → fix + track [/rule]
+[rule:ask_structural] TRIGGER: significant_restructuring_needed → STOP + present + wait [/rule]
+[rule:log_enhancements] TRIGGER: nice_improvement_not_essential → log + continue [/rule]
+</deviation_rules>
 
-- All tasks from PLAN.md completed
-- All verifications pass (citation, coherence, rubric)
-- SUMMARY.md created with substantive content
-- STATE.md updated (position, word count, argument strength)
-- ROADMAP.md updated
-- Paper content committed with meaningful messages
-</success_criteria>
+<task_commit>
+After each task: git status → stage task files → commit with type prefix.
+TYPES: content | cite | revise | fix | structure
+FORMAT: "{type}({section}-{plan}): {description}"
+Record hash for SUMMARY.md.
+</task_commit>
+
+<success_criteria>
+- [ ] Model profile resolved, agent models determined
+- [ ] CONTEXT.md loaded early and passed to writer agent
+- [ ] Section-writer agent spawned with full context + PLAN.md
+- [ ] All tasks from PLAN.md completed
+- [ ] All verifications pass (citation, coherence, rubric)
+- [ ] Argument-verifier confirmed section achieves purpose (or skipped per config)
+- [ ] SUMMARY.md created with substantive content
+- [ ] STATE.md updated (position, word count, argument strength)
+- [ ] ROADMAP.md updated
+- [ ] Paper content committed with meaningful messages
+- [ ] User knows next steps
+</success_criteria>