WTF-P

Write The F***ing Paper.

Also: Proposal. Presentation. Poster.

Portable, evidence-grounded academic workflows for modern coding agents.

WTF-P turns an AI coding agent into a structured research and writing system. It plans before drafting, grounds claims in evidence, isolates section context, delegates bounded work to specialist agents, and verifies the result against the approved plan.

Version 0.6.0-rc.1 is a ground-up modernization of the agent platform. One canonical protocol now generates native resources for Clio Coder, Claude Code, Codex, GitHub Copilot CLI, OpenCode, Antigravity CLI, and Gemini CLI.

Quick start

Install explicitly for the agent you use:

npx wtf-p install clio --advanced
npx wtf-p install claude --advanced
npx wtf-p install codex --advanced
npx wtf-p install copilot --advanced
npx wtf-p install opencode --advanced
npx wtf-p install antigravity --advanced
npx wtf-p install gemini --advanced

An interactive terminal can also run npx wtf-p and choose a target. A noninteractive bare invocation refuses to write anything; it requires an explicit target or scope.

Then start a paper with the native WTF-P action exposed by your client. The
following is the slash-command form used by Clio, Claude, Copilot CLI,
OpenCode, Antigravity, and Gemini:

/wtfp:new-paper
/wtfp:create-outline
/wtfp:plan-section 1
/wtfp:write-section 1
/wtfp:review-section 1

These five lifecycle commands are deliberately unavailable in the Copilot
cloud projection until that surface has an exact explicit-approval binding.

Clio also ships flat /wtfp-new-paper compatibility prompts for current releases. The coordinated Clio integration discovers the preferred nested /wtfp:new-paper namespace; installation probes that capability in a credential-free disposable profile and falls back gracefully for legacy clients.

Codex discovers all 36 stable method routes through seven native Agent Skills
instead of a /wtfp:* command namespace. Twenty-four are adapter-available in the
current adapter; the other 12 carry deterministic WTFP_ACTION_UNAVAILABLE
references instead of unsupported workflow instructions. Select the owning
plugin skill explicitly when the route must be unambiguous (for example,
$wtf-p:wtfp-start-project followed by the new-paper request and its exact
arguments). Existing user-level commands can take precedence over extension
commands in clients that support both; use the client's discovery listing to
confirm the reported source before testing a new installation.

First-class adapters

Discovery counts stable action routes, including deterministic refusal stubs;
it does not by itself establish behavioral support. Clio, Claude, Codex,
Copilot CLI, OpenCode, Antigravity, and Gemini project 24 of the 36 canonical
actions as adapter-available and return WTFP_ACTION_UNAVAILABLE for analyze-bib,
audit-milestone, check-refs, contribute, create-poster,
create-slides, export-latex, remove-section, report-bug,
request-feature, research-gap, and update, because those actions lack an
exact target binding for at least one declared capability or effect. The
Copilot cloud projection marks only add-todo, help, list-assumptions,
map-project, and pause-writing; it refuses the other 31 because it also
lacks an exact explicit-approval binding. Each generated target records its
machine-readable result in compatibility/action-availability.json.

An available action has complete semantic capability, effect, and approval
bindings; that is not automatically an action-scoped host tool allowlist.
Clio 0.3.8 prompt templates expand into an ordinary main-agent turn and retain
the session tool surface. The Clio manifest records this as
hostToolEnforcement.actionScoped: false. Use read-only for previews or
supervised suggest autonomy for mutations, and deny and stop on any tool call
outside the action contract. A run under auto-edit cannot earn WTF-P's
no-undeclared-tool safety result merely because the generated prompt told the
model not to use shell.

The adapters are generated artifacts, not seven hand-maintained copies. Every generated envelope includes a cryptographic inventory and the portable protocol resources needed to understand its workflows. Copilot additionally receives a generated, commit-ready .github projection for cloud/repository use.

For a GitHub-hosted Copilot coding agent, review and copy the .github/ tree from vendors/copilot/project/ in the release archive into the target repository, then commit it through that repository's normal review process. The user-level install copilot command configures the CLI plugin; it deliberately does not write into an unrelated project checkout.

The release-candidate native-discovery matrix was exercised with Claude Code
2.1.251, Codex CLI 0.144.1, Copilot CLI 1.0.80, OpenCode 1.18.16,
Antigravity 1.1.22, Gemini CLI 0.57.0, and Clio Coder 0.3.8 at merged
commit 9b7b80cc. Real isolated new-paper evaluations used Claude Sonnet
5/xhigh, Codex GPT-5.4/xhigh (GPT-5.6 was unavailable through that CLI's
ChatGPT-auth route), and Clio GPT-5.6 Terra/xhigh. The compiler-v4 Clio rerun
earned 8/8 with independent validation of all five previewed records. The
broader paid routing matrix, full lifecycle chain, and cross-version baseline
remain separate evidence gates. See compatibility evidence
for exact claims and caveats. These are repository validation results, not a
claim that 0.6.0-rc.1 has been published.

The first retained local-model lifecycle reading used Clio 0.3.8 with
dynamo/qwen3.8-27b. Both native fleet contracts validated, but the lifecycle
did not pass: high effort timed out before writing, and an effort-off retry
stopped after new-paper because the model attempted a denied shell call and
made 5,600 section words disagree with the 6,000-word outline target. The five
records were individually schema-valid. See the
blocked evidence;
the remaining lifecycle and routing roadmap items stay open. That reading
binds the earlier WTF-P source 6b58b298; it predates later remediation for
exact outline totals and direct-tool use, and is not a behavioral reading of
the later source revisions.

Later post-remediation readings are retained separately because they bind
different WTF-P commits. At 0245818, exact /wtfp:new-paper arguments arrived
but the model listed excluded .git metadata, read an absolute host Clio
documentation path, looped on agent discovery, and produced no planning
records. Those accesses were read-only; zero mutating and network effects were
applied. At b4f0543, the plan/check fleet completed structurally but its
semantic checks were ungrounded. The cbba38c manuscript-path projection
observation placed draft/review manuscript and summary files in the correct
roots with no boundary violation, but drafted without the required approved
plan, left portable state unreconciled, and failed its word target. See the
retained RC readings.
Neither the full lifecycle nor a semantic fleet pass is claimed.

A final current-source Dynamo reading at bf50e23 created exactly five
initialization records and passed literal schema validation 5/5. It still
failed the release gate: the outline placed a dependency in the same wave, and
the model made three successful shell calls plus ten denied shell retries
despite an explicit no-shell policy. The operator stopped the run before
map-project; no terminal receipt or trustworthy numeric cost exists. See the
current-source blocked evidence.

The paper lifecycle

WTF-P keeps the human in control while making the repeatable work deterministic:

1. /wtfp:new-paper captures research questions, intended contribution, evidence, audience, venue, and constraints.
2. /wtfp:map-project indexes existing drafts, sources, data, figures, and decisions.
3. /wtfp:create-outline turns the argument into sections, dependencies, and word budgets.
4. /wtfp:research-gap and /wtfp:analyze-bib build an evidence map without inventing citations.
5. /wtfp:plan-section creates a traceable section plan and can send it through an independent plan checker.
6. /wtfp:write-section drafts from the approved plan in bounded context.
7. /wtfp:review-section, /wtfp:verify-work, and /wtfp:polish-prose check argument coverage, evidence, coherence, venue requirements, and prose quality.
8. /wtfp:audit-milestone, /wtfp:export-latex, /wtfp:create-slides, and /wtfp:create-poster prepare deliverables.

Use the native help route—/wtfp:help on slash-command clients—to inspect all
36 stable action contracts. Executable availability is target-specific and
recorded in the generated compatibility manifest.

What became portable

The canonical source lives under protocol/ and has four parts:

• A versioned .planning project protocol with 11 JSON schemas and ten templates for the project manifest, configuration, state, sources, evidence, decisions, outline, sections, checkpoints, and validation results.
• Seven standard Agent Skills for starting a project, literature research, section planning, section writing, manuscript review, project management, and research delivery.
• Thirty-six semantic action contracts declaring inputs, reads, outputs, specialist delegation, tools, effects, and approval boundaries.
• Eleven host-neutral specialist roles with strict mutation or verification result contracts.

Concrete model names and client tool syntax do not live in canonical workflow prose. Each adapter maps semantic needs such as filesystem access, research search, user interaction, and delegation into the active client's capabilities.

Project state

New workflows use a versioned .planning/ directory. Its records are JSON-schema validated and designed to survive movement between clients:

.planning/
├── project.json
├── config.json
├── state.json
├── decisions.json
├── structure/outline.json
├── sources/*.json
├── evidence/*.json
├── sections/*/section.json
├── checkpoints/*.json
└── validations/*.json

The protocol records evidence separately from prose and records author decisions explicitly. That lets a reviewer trace a claim back to a source and lets a different agent resume without guessing what the author intended.

Installation safety

The 0.6 installer is an ownership-aware transaction engine:

• It rejects filesystem roots, the home directory itself, the repository root, traversal, and symlink escapes.
• It snapshots package sources and refuses source or destination path races.
• It publishes files atomically where possible and rolls back a failed transaction.
• It compensates native marketplace/plugin registration if a later activation step fails.
• It does not register a partial adapter when any conflicting file was preserved.
• It records only files it actually wrote, with SHA-256 hashes, adapter-contract v1, and generator-v4 metadata, in a v2 receipt.
• Reinstallation cannot claim ownership of files it skipped.
• Uninstall removes exact unchanged owned files. It preserves modified files and unrelated siblings by default.
• Dry runs are byte-preserving.

Use a custom isolated client root when evaluating an adapter:

CODEX_HOME=/tmp/wtfp-codex npx wtf-p install codex --advanced
CLIO_CODER_CONFIG_DIR=/tmp/wtfp-clio npx wtf-p install clio --advanced

Inspect or remove an installation with:

npx wtf-p status
npx wtf-p doctor
npx wtf-p uninstall --clio --dry-run
npx wtf-p uninstall --clio --yes

The legacy --global, --local, --claude, --gemini, and --opencode selectors remain compatibility aliases during the release-candidate cycle.

Developing adapters

Edit canonical resources under protocol/, then regenerate every native projection:

npm run build:adapters
npm run check:adapters
npm test
npm run test:integration

check:adapters fails when committed generated resources drift from their canonical inputs. The test suite also checks action parity, skills, portable roles, .planning schemas, resource containment, exact installer ownership, rollback, uninstall preservation, and native envelope structure.

The Clio reference integration is merged into Clio Coder v0.3.8 at
9b7b80cc. It adds recursive namespaced extension prompts, extension-owned
agents and fleets, same-extension skill binding, contained ${extensionRoot}
resource resolution, exact operator-argument preservation, preservation of
nested template state.json resources, and extension-aware fleet preflight.
Effective package discovery certifies 72 prompts (36 nested and 36 flat), 11
agents, seven skills, two fleets, and zero diagnostics. Of those prompts, 48
aliases represent 24 adapter-available semantic actions and 24 aliases are the nested
and flat forms of 12 deterministic refusal routes. WTF-P capability-probes that
surface because Clio currently records, but does not enforce,
compatibility.clio. The generated fleet contracts use directory boundaries
(.planning/ and paper/) so nested writes are authorized without broadening
the worker sandbox.

The two Clio fleets are operator-invoked native primitives, not implicit
routes behind /wtfp:*. Use
clio-coder fleet run wtfp-plan-section --var section=<id> or
clio-coder fleet run wtfp-draft-review --var section=<id> when their narrower
specialist contracts are appropriate; the slash-command orchestrator remains
responsible for approval and portable-state reconciliation around those worker
steps.

Design principles

• Evidence before eloquence: a fluent paragraph is not a substitute for a supported claim.
• Specification before drafting: author intent and acceptance criteria remain explicit.
• Portable semantics, native ergonomics: share the method while respecting each client's real plugin model.
• Bounded delegation: specialists receive the minimum context and authority their task requires.
• Human approval at consequential boundaries: deletion, commits, merges, package updates, and external issue creation remain explicit effects.
• Reversible installation: WTF-P never treats an agent's whole configuration directory as its property.

Origin

WTF-P was built at the Gnosis Research Center at Illinois Tech for research teams with papers to publish, grants to win, and no time for writer's block.

Links

• Changelog
• Modernization architecture
• Compatibility evidence
• Behavioral evaluation methodology
• Tool execution and MCP decision
• v0.5 → v0.6 migration guide
• Build and release
• Contributing
• Roadmap
• License
• GitHub