Make planning-mode playbooks produce actionable implementation plans

README.md

@@ -48,7 +48,7 @@ eforge also runs standalone. By default, `eforge build` enqueues and a daemon pr
 
 ## How It Works
 
-**Formatting and enqueue** - eforge accepts input from multiple sources: a CLI prompt, rough notes, a session plan, a playbook, or a detailed PRD file. Autonomous-mode playbooks and session plans are reusable input artifacts that the daemon compiles to ordinary build source via `@eforge-build/input` before reaching the engine queue. Planning-mode playbooks instead trigger an investigation-first workflow: the agent loads the playbook, investigates the codebase guided by the playbook's Goal, Acceptance criteria, and Notes, creates a session plan with concrete findings, and continues the planning conversation interactively before a build is enqueued. The engine always receives normalized build source and does not know whether that source originated from a playbook, session plan, wrapper app, CLI prompt, or PRD file.
+**Formatting and enqueue** - eforge accepts input from multiple sources: a CLI prompt, rough notes, a session plan, a playbook, or a detailed PRD file. Autonomous-mode playbooks and session plans are reusable input artifacts that the daemon compiles to ordinary build source via `@eforge-build/input` before reaching the engine queue. Planning-mode playbooks instead trigger an investigation-first workflow: the agent loads the playbook, investigates the codebase guided by the playbook's Goal, Acceptance criteria, and Notes, synthesizes investigation findings into an implementation-ready session plan, and continues the planning conversation interactively before a build is enqueued. The engine always receives normalized build source and does not know whether that source originated from a playbook, session plan, wrapper app, CLI prompt, or PRD file.
 
 **Build artifact kinds** — three kinds of artifacts appear during a build, and it helps to keep them distinct:
 

docs/config.md

@@ -825,7 +825,7 @@ Object sections (`langfuse`, `agents`, `build`, `plan`, `plugins`, `extensions`,
 
 Agent runtime profiles follow the same three-level pattern. Profile files can exist at project-local scope (`.eforge/profiles/` - gitignored), project scope (`eforge/profiles/`), or user scope (`~/.config/eforge/profiles/`). The active-profile marker can be set at any level: `.eforge/.active-profile` (project-local, highest precedence), `eforge/.active-profile` (project), or `~/.config/eforge/.active-profile` (user). When a profile name is resolved, the profile file is looked up local-first, then project, then user-fallback - so a local profile shadows project and user profiles with the same name.
 
-Playbooks are reusable input artifacts owned by `@eforge-build/input`, resolved across scopes by `@eforge-build/scopes`. The daemon compiles autonomous playbooks to ordinary build source via `playbookToBuildSource` before enqueue. Playbooks follow the same three-tier pattern: `.eforge/playbooks/` (project-local, highest precedence), `eforge/playbooks/` (project scope), and `~/.config/eforge/playbooks/` (user scope). When the same playbook name exists at multiple tiers, the highest-precedence tier wins and lower-tier copies are reported as shadows. Each playbook carries a `scope` frontmatter field that must match the tier it was loaded from; a mismatch is surfaced as a warning in the listing. The `eforge playbook` command manages playbooks from the CLI: `list` shows all available playbooks with source labels and shadow chains; `new` scaffolds a new playbook file non-interactively (accepts `--scope`, `--name`, `--description`, `--from <file>`, `--profile <name>`); `edit <name>` opens the resolved playbook in `$EDITOR` and validates the result before saving; `run <name> [--after <queue-id>]` runs the playbook (also available as `eforge play <name>`) — autonomous playbooks are enqueued as a build; planning playbooks return a `requires-agent` response directing the agent to perform an investigation-first workflow (load the playbook, investigate the codebase, create a session plan with findings, and continue via `/eforge:plan`); `promote <name>` moves a playbook from `.eforge/playbooks/` to `eforge/playbooks/` and stages the new file; `demote <name>` moves it back to project-local scope.
+Playbooks are reusable input artifacts owned by `@eforge-build/input`, resolved across scopes by `@eforge-build/scopes`. The daemon compiles autonomous playbooks to ordinary build source via `playbookToBuildSource` before enqueue. Playbooks follow the same three-tier pattern: `.eforge/playbooks/` (project-local, highest precedence), `eforge/playbooks/` (project scope), and `~/.config/eforge/playbooks/` (user scope). When the same playbook name exists at multiple tiers, the highest-precedence tier wins and lower-tier copies are reported as shadows. Each playbook carries a `scope` frontmatter field that must match the tier it was loaded from; a mismatch is surfaced as a warning in the listing. The `eforge playbook` command manages playbooks from the CLI: `list` shows all available playbooks with source labels and shadow chains; `new` scaffolds a new playbook file non-interactively (accepts `--scope`, `--name`, `--description`, `--from <file>`, `--profile <name>`); `edit <name>` opens the resolved playbook in `$EDITOR` and validates the result before saving; `run <name> [--after <queue-id>]` runs the playbook (also available as `eforge play <name>`) — autonomous playbooks are enqueued as a build; planning playbooks return a `requires-agent` response directing the agent to perform an investigation-first workflow (load the playbook, investigate the codebase, synthesize findings into an implementation-ready session plan, and continue via `/eforge:plan`); `promote <name>` moves a playbook from `.eforge/playbooks/` to `eforge/playbooks/` and stages the new file; `demote <name>` moves it back to project-local scope.
 
 ### Playbook `profile` field
 

eforge-plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "eforge",
   "description": "Conversational planning and MCP-based daemon integration for eforge — enqueue, run, and monitor builds from within Claude Code",
-  "version": "0.25.34",
+  "version": "0.25.35",
   "commands": [
     "./skills/build/build.md",
     "./skills/status/status.md",

eforge-plugin/skills/plan/plan.md

@@ -32,7 +32,7 @@ If `--session <session-id>` is provided, skip the start menu and follow Path (a)
 > "How would you like to start?
 > 1. **Resume** an existing planning session
 > 2. **New** session — start from scratch
-> 3. **Start from a planning-mode playbook** — load a planning playbook, investigate the codebase, and create a session plan with concrete findings"
+> 3. **Start from a planning-mode playbook** — load a planning playbook, investigate the codebase, synthesize findings, and create an implementation-ready session plan"
 
 Then follow the corresponding path below.
 
@@ -58,13 +58,19 @@ Then follow the corresponding path below.
 4. Call `mcp__eforge__eforge_playbook { action: 'show', name: '{name}' }` to load the full playbook content. If an exact `--playbook` was provided but the playbook is not `mode: planning`, stop and explain that `/eforge:plan` only starts from planning-mode playbooks.
 5. Read the playbook's Goal, Acceptance criteria, and Notes for the planner sections. Identify what needs to be investigated: relevant files, codebase areas, questions to answer, commands to run.
 6. Perform the investigation using read, search, and command capabilities. Gather evidence from the codebase. Validate cheap assumptions immediately.
-7. Ask the user for a topic to anchor the session (the playbook provides the shape; the topic anchors it to the current work). If the Goal makes the topic obvious, suggest it and allow override.
-8. Generate a session ID: `{YYYY-MM-DD}-{playbook-name}` (e.g., `2026-05-19-complexity-hotspot-reduction`).
-9. Create the session plan. If the playbook has a `profile` field, call `mcp__eforge__eforge_session_plan { action: 'create', session: '{session-id}', topic: '{topic}', open: true, agent_profile: '{playbook.profile}' }` so the session plan inherits that profile at enqueue time. If the playbook has no `profile`, call `mcp__eforge__eforge_session_plan { action: 'create', session: '{session-id}', topic: '{topic}', open: true }`. If that session ID already exists, ask whether to resume and update the existing session or create a new suffixed session ID (for example `{YYYY-MM-DD}-{playbook-name}-2`), then continue with the chosen session.
-10. Write investigation findings as concrete section content using `mcp__eforge__eforge_session_plan { action: 'set-section', session, dimension, content }` for each covered dimension. Include specific evidence — not generic playbook template language.
-11. Proceed to Step 2 (Gather Context) — investigation findings already written into the session provide the starting context.
-
-> **Sub-note — investigation-seeded sessions**: when starting from a planning-mode playbook (path c), the investigation and findings are written into the session plan before Step 2 begins. In Step 2 (Gather Context), treat existing section content as established starting context — do NOT re-investigate areas already covered. Instead, read the session file, summarize what was found, and continue planning from there. The session content can be refined and extended throughout the planning conversation.
+7. **Synthesize implementation handoff**: Before asking for a topic, convert findings into an implementation-ready handoff:
+   - **Choose implementation targets**: When evidence supports a clear choice, name the specific files, modules, or components that will change.
+   - **Define concrete actions**: For each selected target, state what will be done.
+   - **Separate evidence from spec**: Put confirmed findings and assumptions in context/evidence-oriented content. Put implementation targets, actions, non-goals, and validation criteria in actionable sections (Scope, Code Impact, Acceptance Criteria).
+   - **Move unresolved findings**: Judgment-heavy or inconclusive findings become Open Questions, follow-up scope, or non-goals — not a directive to re-run the investigation during the build.
+   - **Avoid audit-repeat plans**: The session plan must not instruct the build agent to repeat the investigation. If evidence is insufficient to choose a target, state that as an open question.
+8. Ask the user for a topic that describes the implementation change to build — not the investigation already performed (e.g., "Reduce complexity in event parser" rather than "Audit complexity hotspots"). If the synthesized targets make the topic obvious, suggest it and allow override.
+9. Generate a session ID: `{YYYY-MM-DD}-{playbook-name}` (e.g., `2026-05-19-complexity-hotspot-reduction`).
+10. Create the session plan. If the playbook has a `profile` field, call `mcp__eforge__eforge_session_plan { action: 'create', session: '{session-id}', topic: '{topic}', open: true, agent_profile: '{playbook.profile}' }` so the session plan inherits that profile at enqueue time. If the playbook has no `profile`, call `mcp__eforge__eforge_session_plan { action: 'create', session: '{session-id}', topic: '{topic}', open: true }`. If that session ID already exists, ask whether to resume and update the existing session or create a new suffixed session ID (for example `{YYYY-MM-DD}-{playbook-name}-2`), then continue with the chosen session.
+11. Write section content using `mcp__eforge__eforge_session_plan { action: 'set-section', session, dimension, content }` for each covered dimension. **Scope, Code Impact, and Acceptance Criteria** sections must describe the implementation handoff — concrete targets, actions, and validation criteria. Record confirmed investigation findings in context-oriented content (e.g., a Context section or Notes). Include specific evidence — not generic playbook template language.
+12. Proceed to Step 2 (Gather Context) — the synthesized implementation handoff from step 7 is the authoritative starting context. Step 2 resumes from the synthesized handoff without re-running covered investigation.
+
+> **Sub-note — investigation-seeded sessions**: when starting from a planning-mode playbook (path c), the investigation is performed and findings are synthesized into an implementation-ready handoff before Step 2 begins. Scope, Code Impact, and Acceptance Criteria sections describe the implementation targets and actions — not the investigation. In Step 2 (Gather Context), treat existing section content as established starting context — do NOT re-investigate areas already covered. Instead, read the session file, summarize the synthesized handoff, and continue planning from there. The session content can be refined and extended throughout the planning conversation.
 >
 > **Note on `create-from-playbook`**: `mcp__eforge__eforge_session_plan { action: 'create-from-playbook' }` is a static template helper that pre-populates Goal, Out of scope, Acceptance criteria, and Notes from a playbook without performing investigation. It is retained for scratch/template seeding scenarios but is not the planning-playbook Run path — use path (c) above for investigation-first planning.