Proposal: Optional planning-with-files integration in ce-plan handoff (5.3.9)

[kmorebetter]

Hi! I'm a user of both compound-engineering and planning-with-files (23K+ GitHub stars) and wanted to float a small, optional integration between them before investing in a PR.

The problem

ce-plan writes detailed plans to docs/plans/. planning-with-files tracks live agent state in task_plan.md, which re-injects before every turn via a UserPromptSubmit hook. Today these are disconnected — a ce-plan run populates docs/plans/ but leaves task_plan.md stale, so the agent's turn-by-turn context doesn't reflect the plan just generated.

The current workaround is a CLAUDE.md instruction ("after /ce-plan, write to task_plan.md") — it works but can be forgotten or skipped.

The proposed fix

A small, optional detection-and-write step in ce-plan's 5.3.9 Final Checks phase:

1. Check if task_plan.md exists in the project root — if not, skip silently (no error, no output, no disruption to the post-generation menu)
2. If yes: extract the plan goal and ### U<N>. headings, write a concise ## Current Plan section to task_plan.md
3. Continue to 5.4 as normal

Zero coupling to planning-with-files internals — detection is purely task_plan.md file existence. Works for any project that has the file; gracefully skips for everyone who doesn't.

Minimal footprint

The change would touch:

• skills/ce-plan/references/plan-handoff.md (section 5.3.9) — one new paragraph: "Load references/planning-with-files-integration.md and execute the integration step"
• skills/ce-plan/references/planning-with-files-integration.md (new file) — the full detection-and-write protocol, following the same load-by-reference pattern already used throughout ce-plan

I've already written a full implementation plan as a planning exercise. Happy to share the specifics if useful.

Before I open a PR

Wanted to check a few things first:

• Is this kind of optional third-party integration something you'd consider for the CE plugin?
• Any concerns about using task_plan.md existence as the detection signal (vs. something more explicit)?
• Would you prefer this live somewhere else — a separate bridge skill, or a contribution to the planning-with-files side instead?

Thanks for maintaining such a solid plugin!

[tmchow]

@kmorebetter open to something here, but notice PR #972 where we are doing a huge refactor to combine our PRD and Implementation plan to make things more usable with /goal and other more autonomous workstreams. I'd we open to a proposal about how to handle the integration with planning-with-files, it just had to make sense with what we have. I think it also had to consider a robust detection on when it shoudl be used.

One thing to consider is that detection might be enabled if both the project uses planning-with-files (could be indicates in system context via AGENTS.md/CLAUDE.md) and the existence of the skill? I'm nto sure i love just file detection but open to ideas here.

[kmorebetter]

Appreciate you even responding. :)

Read through #972.

The unified readiness-staged artifact is a cleaner hook for this than the old 5.3.9 handoff, so I'd rebuild the proposal around it once it lands, triggering on the transition to implementation-ready rather than a baked final-checks step. On detection, I'll model it on the host-capability probe in ce-work's execution-engines lane rather than bare file existence. And to be clear on intent: the plan doc stays the single authority, task_plan.md just carries a thin pointer so the turn context reflects the current plan, not a competing source of truth.

Worth waiting for #972 to merge before I draft anything against it?

[tmchow]

@kmorebetter you can probably wait until #972 to land to avoid the churn

[tmchow]

@kmorebetter ok, with 3.15 out, I'd love to see your proposal for this given my guidance above.

[kmorebetter]

@tmchow Rebuilt the proposal around 3.15 / #972 as promised. Short version: an optional, CE-side bridge that, on the transition to implementation-ready, writes a thin pointer into an active planning-with-files task_plan.md. The docs/plans/… doc stays the single authority — task_plan.md just gets a short, idempotent pointer (canonical path + readiness + one-line goal) so the per-turn injected context reflects the plan that was just generated. Zero coupling to planning-with-files internals.

How it fits the unified artifact

• Trigger: the 5.3.9 final-checks step in references/plan-handoff.md, gated to artifact_readiness: implementation-ready + execution: code. Requirements-only and knowledge-work plans never fire. It's a load-by-reference step into a new self-contained skills/ce-plan/references/planning-with-files-integration.md, and a silent no-op when it doesn't apply — the 5.4 menu is untouched.
• No launch-block duplication issue: the pointer is a pointer, not plan content, so nothing drifts against the doc and nothing has to stay in sync the way a copied unit graph would.

On detection — answering your "not sure I love just file detection"

I dug into both codebases, and I think the conclusion flips: filesystem presence is the robust signal here, not the weak one. Two reasons:

1. It's exactly what planning-with-files gates its own hooks on. Its UserPromptSubmit injection resolves the active plan via $PLAN_ID → .planning/.active_plan → newest .planning/*/task_plan.md → root task_plan.md. If a plan resolves, the project is actively using planning-with-files this session. I reuse that same resolution order (reimplemented locally, no dependency on their scripts), framed as a host-capability probe in the style of ce-work's execution-engine probe — "probe for the primitive, don't infer it."
2. The AGENTS.md/CLAUDE.md marker idea doesn't have anything to key on. planning-with-files writes no such declaration, and the repo's own "Referencing Project Conventions" rule says we shouldn't name AGENTS.md/CLAUDE.md on the read path anyway. A marker would be a less reliable signal than an actual in-use plan file — it can go stale; a resolved task_plan.md can't.

For the "robust, not bare" part of your concern, I add a .compound-engineering/config.local.yaml switch (planning_with_files_bridge: auto | on | off, default auto, same precedence pattern as plan_output) so it's explicitly overridable.

Three things the research changed from my original sketch

Worth surfacing because they're the difference between "works" and "quietly breaks someone's setup":

1. The injection window is head -50. A ## Current Plan section appended at the bottom (my original idea) would never re-inject — and there's no ## Current Plan heading recognized upstream anyway. So the pointer goes near the top (after ## Goal), inside the window, as an idempotent block wrapped in stable <!-- ce-plan:… --> delimiters (re-running replaces in place, never stacks).
2. Attestation/autonomous mode hash-locks task_plan.md. Any external write that doesn't re-attest trips [PLAN TAMPERED — injection blocked] and suppresses injection entirely. So the bridge hard-skips when .attestation/.nonce/.mode=autonomous|gated markers are present — respects their SHA gate without touching their scripts.
3. task_plan.md is agent/orchestrator-owned, and its head is auto-injected (a prompt-injection surface upstream deliberately routes untrusted content away from). A thin pointer keeps that surface minimal; dumping plan content would not.

Scope

CE-side only, non-breaking, opt-out-able. New files: skills/ce-plan/references/planning-with-files-integration.md + tests/skills/planning-with-files-bridge.test.ts. Touches: references/plan-handoff.md (5.3.9), skills/ce-setup/references/config-template.yaml, the docs/skills/ce-plan.md mirror. Behavioral evals via the skill-creator workflow cover the write/idempotent/slug-resolution/attestation-skip/no-pwf/gating cases.

Two things I'd want your call on before I PR

• Pointer richness: path + readiness + one-line goal only, or also surface the active U-ID? I lean leanest (no U-ID) to avoid re-write churn as units progress.
• Config values: keep the auto | on | off enum for forward room, or collapse to a boolean? on and auto behave identically today.

Happy to open the PR against main once you've reacted to the detection approach and those two. Thanks for the steer on waiting for #972 — it's a much cleaner hook than the old 5.3.9.

[tmchow]

@kmorebetter — went and read the planning-with-files hook scripts properly before reacting, and I want to surface a real hesitation before you sink PR time in, because I think we may be about to build the low-value half of a fork.

The pointer model comes down to: your hook injects head -50 task_plan.md every turn, so all that matters is what those lines do when re-injected. Going field by field on the proposed pointer:

• path (Current plan: docs/plans/…) — the one line doing real work; it redirects the per-turn context to the fresh plan.
• readiness — re-injected every turn, changes nothing behaviorally. It's handoff-moment metadata, not turn context.
• active unit — dead end: ce-plan writes the pointer once at handoff and exits, and nothing (not ce-work, not /goal, not your hook) updates it after. It freezes at U1 and rots the instant execution moves past it — worse than omitting, since the stale line gets injected every turn.
• goal — mild, but a dup of the plan's own goal, which the agent gets the moment it opens the path.

So the pointer distills to ~one useful line. And even that only helps a specific user: if the plan is handed to ce-work or /goal, the executor already has the path, so the pointer is redundant — it only earns its keep for someone who keeps driving turns through your injection loop. Plus we don't clear the rest of task_plan.md, so head -50 injects our pointer plus the previous task's stale content around it.

Which makes me think the real fork is:

1. Pointer (what's scoped): "the real plan is over there." Safe, no drift — but marginal, and muddled by the surrounding stale content.
2. Sync: rewrite task_plan.md's goal + task list from the ce-plan output, so the injected content genuinely is the current plan — which is what task_plan.md is built to hold. Real value, but it duplicates plan content into a file whose head is a deliberate prompt-injection surface, and it breaks "the docs/plans/… doc is the single authority." You flagged those exact reasons for avoiding it, and I agree with them.

You use planning-with-files daily and we don't — so rather than guess, can you point at the concrete moment this pays off for you?

• After a /ce-plan run, are you actually continuing to drive turns through the planning-with-files loop, or handing off to an executor that already has the plan path?
• Given the trade-offs, is a one-line path pointer genuinely useful to you — or is the value really in the sync model? And if it's sync, is there a safe shape that doesn't dump plan content into the injection surface?

Not trying to talk you out of it — I want to build the half that helps and skip the ceremony half.