[question] Decouple Prawduct from TangleClaw — direct-integration drift risk as Prawduct moves to a Claude-embedded V2 skill

[Jason-Vaughan]

Context

TangleClaw embeds Prawduct (brookstalley's methodology framework) as a first-class methodology: bundled templates (data/templates/prawduct/), the V2 wrap pipeline (lib/wrap-pipeline.js + lib/wrap-steps/), session playbook, Independent Critic, .prawduct/ governance tooling (tools/product-hook, .test-evidence.json, build-governance), and the CLAUDE.md operating rules. This integration is deep and direct — TangleClaw consumes Prawduct's shapes (template schema, hook contracts, governance file formats) rather than treating it as a versioned, swappable dependency.

The concern

Two compounding problems:

1. Direct-integration drift. Relying on an externally-evolving framework and wiring it straight into TangleClaw's internals means every upstream change is a potential break. This is the same failure class we keep hitting with runtime-template staleness (cf. [bug] First user message of every bypass-mode session is a stray '2' #119, [bug] v3.13.7 wrap.steps fix doesn't reach existing installs — runtime templates at ~/.tangleclaw/templates/ stay stale #136) and stale governance files — the integration assumes a shape that upstream can move out from under us.

2. Prawduct is moving to "V2" — an embedded Claude skill. The author is reshaping Prawduct into a skill that lives inside Claude Code rather than as the file/template/hook framework TangleClaw currently integrates. If/when that lands, TangleClaw's assumptions about how Prawduct is structured and invoked could break wholesale — and it pulls Prawduct further into Claude-only territory, which conflicts with TangleClaw's engine-agnostic ambitions (TC also runs Gemini/Codex; see the existing position: plumbing → engine-agnostic, agent invocation → Claude-only).

What's at stake

• Breakage surface: template reconciliation, wrap pipeline step contracts, tools/product-hook, .prawduct/ governance formats, CLAUDE.md rules — all coupled to Prawduct's current shape.
• Engine-agnosticism: a Claude-embedded-skill Prawduct deepens Claude lock-in for the methodology layer.
• Ownership/control: TC's wrap/governance behavior is partly defined by an external project's roadmap.

Options to discuss (not yet decided)

1. Keep integrated, vendor-snapshot. Pin a frozen copy of Prawduct's shapes inside TC; absorb upstream changes deliberately, never automatically. Lowest churn, but TC keeps carrying Prawduct's concepts.
2. Decouple to TC-native methodology. Lift the useful pieces (wrap pipeline, Critic, governance) into TangleClaw-owned abstractions that don't depend on Prawduct's identity — Prawduct becomes one optional methodology among others, behind a stable TC-defined interface. Most work, best long-term insulation; aligns with the existing "plumbing engine-agnostic" stance.
3. Treat V2 skill as just another engine capability. Let the Claude-embedded Prawduct V2 run as a skill when the engine is Claude, and have TC provide a degraded-but-functional native path for other engines. Accepts Claude-only agent features (consistent with current design) but needs a clean boundary so the skill's absence doesn't break TC.
4. Drop Prawduct coupling entirely. TC ships its own methodology system; Prawduct becomes external/unsupported. Cleanest separation, biggest near-term loss of capability.

Asks before deciding

• Map the exact coupling points (which TC files assume which Prawduct shapes) so we know the real blast radius.
• Get clarity on Prawduct V2's actual shape/timeline (is the file-framework going away, or coexisting?).
• Decide the boundary: what does TangleClaw own vs consume.

Filing to capture the decision; let's discuss before committing to a direction. Related design note in session memory: project_prawduct_engine_design.

[Jason-Vaughan]

Recon: what Prawduct V2 actually is (looked at brookstalley/prawduct, currently v2.1.4, pushed 2026-06-11)

V2 is a Claude Code plugin, and its architecture is explicit

From .claude-plugin/plugin.json (v2.1.4):

"Dev-time governance plugin: ships immutable read-only code; all mutable state lives in each repo's .prawduct/."

• Installed once at user level via marketplace (claude plugin marketplace add brookstalley/prawduct → claude plugin install). Provides /prawduct:* skills (critic, pr, backlog, janitor, doctor, building, planning, discovery, learnings, advisory, migrate, onboard, repo-disable…) + Python hooks (hooks/) + governance tool now at bin/prawduct-hook + lib/*.py.
• A governed repo commits "zero framework files in your tree" — only a tiny install reference + its .prawduct/ mutable state.
• v2.0.3 (2026-06-04) "Retire the file-sync engine & strip pre-2.0 back-compat cruft" — the file-sync distribution model TC was built around is gone upstream.
• There is a dedicated migration path for exactly our situation: documentation/MIGRATION.md + /prawduct:migrate (dry-run → one git revert-able commit, preserves .prawduct/ state).

Where TangleClaw actually stands (the concrete drift)

TC is an un-migrated pre-2.0 file-sync repo:

• It vendors the governance tool into the repo: tools/product-hook — 182KB, dated May 30, still carrying the old name (product-hook; V2 renamed it to prawduct-hook) and the pre-v2.0.3 (pre-file-sync-retirement) shape. .prawduct/build-governance.md calls python3 tools/product-hook … (repo-relative) — the opposite of V2's "zero framework files."
• No .claude-plugin install reference in TC → not onboarded the V2 way. Yet the v2.x plugin skills ARE installed at user level (this session used /critic, /backlog, etc.). So TC runs a hybrid: current-version plugin skills calling a ~2-week-stale vendored tool against pre-2.0 governance files. It works today, but that's precisely the drift surface.

This splits the decision into two genuinely separate layers

• Layer A — TC governed by Prawduct (tools/product-hook, .prawduct/, the Prawduct rules in CLAUDE.md). This is the drifted/breakable part. Fix = stop vendoring, migrate to the V2 plugin model (/prawduct:migrate). Resolves the drift directly.
• Layer B — TC's own methodology-engine product feature (lib/wrap-pipeline.js, lib/wrap-steps/, data/templates/prawduct/template.json — the wrap pipeline TC offers to OTHER projects, e.g. today's [bug] memory-update wrap step times out at 300s and prints a misleading "wrap pipeline blocked" while the wrap commits anyway #328 work). This is TC-owned code that merely shares Prawduct's name/philosophy; it does NOT consume the plugin, so it has no breakage exposure — only a naming/positioning question (is calling it "prawduct" confusing now that the real plugin is a distinct thing?).

Recommended next step (non-destructive)

Run /prawduct:migrate in dry-run on TC — it shows exactly which files V2 would remove/edit without changing anything. That is the coupling-point map, and it tells us whether migrating Layer A is clean or whether TC's generated CLAUDE.md / hybrid setup needs hand-holding. Decide Layer A (adopt plugin) and Layer B (keep + maybe rename) separately after seeing it.

[Jason-Vaughan]

Dissection of /prawduct:migrate — read from source (lib/migrate_plugin.py + MIGRATION.md), mapped to TC

Correction to my earlier comment: the V2 plugin is not installed on this machine at all (only the official Anthropic marketplace is present; no prawduct-hook anywhere under ~/.claude/plugins). The prawduct skills this session used come from the repo's own .claude/skills/ + the vendored tools/product-hook. So TC is a fully repo-vendored v1.x-era setup with zero V2 adoption — that's the real state.

What migrate WOULD do to TC (registry-driven, single git revert-able commit)

Remove (all present in TC; plugin would provide them):

• .claude/skills/{backlog,critic,janitor,learnings,pr,prawduct-advisory,prawduct-doctor} (exactly TC's 7 skill dirs)
• tools/product-hook + tools/lib/
• .prawduct/{critic-review.md,pr-review.md,build-governance.md,sync-manifest.json}

Edit in place:

• .claude/settings.json — strip prawduct hooks + banner, merge the plugin install reference. (Note: TC's settings.json hooks are the prawduct hooks, so they go.)
• CLAUDE.md — TC has no PRAWDUCT:BEGIN/END block, so nothing is stripped; migrate just inserts the thin PRAWDUCT:ANCHOR and leaves all of TC's existing content.
• .prawduct/project-state.yaml — append distribution: plugin.

Never touched (registry excludes them): TC's product code — lib/, public/, server.js, data/templates/prawduct/, data/hooks/, rest of .prawduct/. Confirmed: TC's own wrap-pipeline + methodology-engine (Layer B) has zero exposure. TC code doesn't reference product-hook outside the settings hooks.

The TC-specific blocker the dissection exposed (bigger than the file moves)

TangleClaw regenerates CLAUDE.md + .claude/ config on session launch (it's a methodology-config generator — "Generated by TangleClaw"). So migrate's edits to CLAUDE.md/settings.json/skills wouldn't stick — TC's own boot regeneration would overwrite the anchor and re-inject the heavy inline rules + re-emit skills. TangleClaw and Prawduct-V2-the-plugin are competing owners of the same artifacts (CLAUDE.md, .claude/skills/, .prawduct/ governance): TC generates them from data/templates/prawduct/template.json; the plugin ships them read-only. That collision — not the file moves — is the actual decision.

Reframed decision

TangleClaw is effectively a homegrown reimplementation of what Prawduct V2 now is (a per-project methodology/governance system). The question isn't "migrate y/n" — it's which system owns the methodology layer, given TC's generator and the plugin both want to own .claude/ + CLAUDE.md + governance. Options 1–4 in the issue body still stand, but this is the axis they turn on.