From 996eba03375f136242c2bcd7b17729daf539ab58 Mon Sep 17 00:00:00 2001 From: Mark Schaake Date: Thu, 28 May 2026 09:00:41 -0700 Subject: [PATCH 1/5] plan(make-planning-mode-playbooks-produce-actionable-implementation-plans): planning artifacts Models-Used: gpt-5.5 Co-Authored-By: forged-by-eforge --- .../orchestration.yaml | 55 ++++++++ .../plan-01-actionable-planning-playbooks.md | 127 ++++++++++++++++++ 2 files changed, 182 insertions(+) create mode 100644 eforge/plans/make-planning-mode-playbooks-produce-actionable-implementation-plans/orchestration.yaml create mode 100644 eforge/plans/make-planning-mode-playbooks-produce-actionable-implementation-plans/plan-01-actionable-planning-playbooks.md diff --git a/eforge/plans/make-planning-mode-playbooks-produce-actionable-implementation-plans/orchestration.yaml b/eforge/plans/make-planning-mode-playbooks-produce-actionable-implementation-plans/orchestration.yaml new file mode 100644 index 00000000..eac11804 --- /dev/null +++ b/eforge/plans/make-planning-mode-playbooks-produce-actionable-implementation-plans/orchestration.yaml @@ -0,0 +1,55 @@ +name: make-planning-mode-playbooks-produce-actionable-implementation-plans +description: Update first-party Pi and Claude Code planning-mode playbook + instructions and related copy so investigation findings are transformed into + implementation-ready session plans. +base_branch: main +mode: excursion +validate: + - pnpm docs:check-parity + - pnpm maintainability:check + - pnpm type-check + - pnpm test -- test/skills-docs-wiring.test.ts + test/pi-playbook-commands.test.ts +plans: + - id: plan-01-actionable-planning-playbooks + name: Make Planning Playbooks Produce Actionable Session Plans + depends_on: [] + branch: make-planning-mode-playbooks-produce-actionable-implementation-plans/plan-01-actionable-planning-playbooks + build: + - implement + - test-cycle + - review-cycle + review: + strategy: parallel + perspectives: + - code + - docs + maxRounds: 1 + evaluatorStrictness: standard +pipeline: + scope: excursion + compile: + - planner + - plan-review-cycle + defaultBuild: + - - implement + - doc-author + - - doc-sync + - test + - review-cycle + defaultReview: + strategy: auto + perspectives: + - code + - docs + maxRounds: 2 + evaluatorStrictness: standard + rationale: This is a cohesive multi-file consumer-facing instruction and + documentation fix across Pi and Claude plugin integrations, so excursion is + appropriate. A plan-review-cycle helps catch parity, scope, and + acceptance-criteria gaps before build. The build runs implementation + alongside documentation authoring, then syncs docs and runs + validation-oriented tests/checks before an iterative review cycle. Review + focuses on code and docs because the work changes skill instructions, + user-facing copy, and plugin packaging, without security-sensitive behavior. +diff_base_ref: 2243faacb70111953aaea547412beedb66c38514 diff --git a/eforge/plans/make-planning-mode-playbooks-produce-actionable-implementation-plans/plan-01-actionable-planning-playbooks.md b/eforge/plans/make-planning-mode-playbooks-produce-actionable-implementation-plans/plan-01-actionable-planning-playbooks.md new file mode 100644 index 00000000..61580dae --- /dev/null +++ b/eforge/plans/make-planning-mode-playbooks-produce-actionable-implementation-plans/plan-01-actionable-planning-playbooks.md @@ -0,0 +1,127 @@ +--- +id: plan-01-actionable-planning-playbooks +name: Make Planning Playbooks Produce Actionable Session Plans +branch: make-planning-mode-playbooks-produce-actionable-implementation-plans/plan-01-actionable-planning-playbooks +--- + +# Make Planning Playbooks Produce Actionable Session Plans + +## Architecture Context + +Planning-mode playbooks are consumer-facing instruction contracts in both Pi (`packages/pi-eforge/`) and the Claude Code plugin (`eforge-plugin/`). The daemon already returns `requires-agent` for planning playbooks; the bug is that first-party skill instructions allow agents to create plans that continue the audit instead of synthesizing an implementation handoff. Keep runtime behavior and data models unchanged. + +Key constraints: + +- Keep Pi and Claude Code skill narratives semantically aligned. `scripts/check-skill-parity.mjs` normalizes plugin MCP tool names and `/eforge:` command references, so mirrored wording outside parity-skip blocks must match after normalization. +- Bump `eforge-plugin/.claude-plugin/plugin.json` because plugin-facing skill files change. +- Do not bump `packages/pi-eforge/package.json`. +- Do not add daemon APIs, session-plan fields, or playbook schema fields. + +## Implementation + +### Overview + +Revise the planning-mode playbook flow so it has an explicit investigation-to-implementation synthesis step. The revised instructions must direct agents to record investigation results as evidence/context while writing Scope, Code Impact, Acceptance Criteria, topic, and open questions as an actionable build handoff with concrete targets, actions, non-goals, and validation criteria. + +### Key Decisions + +1. Fix the behavior through skill documentation and user-facing copy, not daemon code, because the observed failure happened in agent interpretation after investigation. +2. Mirror the same flow in Pi and Claude plugin skills to prevent integration drift. +3. Add static documentation wiring tests so the core wording does not regress during future skill edits. +4. Keep the Pi native command handler change to label/description copy only; no selection or daemon request behavior changes are needed. + +## Scope + +### In Scope + +- Add an explicit “synthesize implementation handoff” step to the planning-mode run flow in both playbook skills before session creation or update. +- Update planning-playbook Path (c) in both plan skills so topic, scope, code impact, and acceptance criteria describe the change to build rather than the completed investigation. +- Clarify that investigation findings belong in context/evidence sections. +- Require actionable sections to name concrete implementation targets, concrete actions, non-goals, validation criteria, and unresolved/open follow-up scope. +- Clarify that unresolved or judgment-heavy findings become open questions or follow-up scope, not a vague request to repeat the investigation during build. +- Update Pi native `/eforge:plan` menu copy that currently says “seed a session plan”. +- Update `docs/config.md` playbook description where it says planning playbooks create a session plan with findings. +- Bump the Claude plugin version. +- Add or update static tests that assert the actionable-handoff contract appears in the relevant skill/copy files. + +### Out of Scope + +- Daemon API changes. +- Session-plan data model changes. +- Playbook schema changes. +- Implementing any specific test-thinning changes discovered by a playbook. +- Changing autonomous playbook enqueue behavior. + +## Files + +### Create + +- None. + +### Modify + +- `packages/pi-eforge/skills/eforge-playbook/SKILL.md` — Update Playbook Modes wording, Branch Run summary, and Step 5.5 to require synthesis into an implementation-ready session plan before session creation or update. Include concrete targets/actions, non-goals, validation criteria, evidence/context placement, and unresolved findings handling. +- `eforge-plugin/skills/playbook/playbook.md` — Apply semantically equivalent playbook-skill changes with plugin MCP tool naming preserved. +- `packages/pi-eforge/skills/eforge-plan/SKILL.md` — Update the start menu and Path (c) to say a planning playbook investigates, synthesizes findings, then creates an implementation-ready session plan. Require the topic and actionable sections to describe the change to build. +- `eforge-plugin/skills/plan/plan.md` — Apply semantically equivalent plan-skill changes with plugin MCP tool naming preserved. +- `packages/pi-eforge/extensions/eforge/plan-command.ts` — Change the planning playbook option description from “investigate, and seed a session plan” to wording such as “investigate, then draft an implementation-ready session plan”. Do not change command dispatch behavior. +- `docs/config.md` — Update planning playbook prose to describe synthesizing investigation findings into an implementation-ready session plan, not merely creating a session plan with findings. +- `eforge-plugin/.claude-plugin/plugin.json` — Bump the patch version from `0.25.34` to `0.25.35` unless the current version has changed; in that case increment the current patch version by one. +- `test/skills-docs-wiring.test.ts` — Add static assertions for the actionable planning-playbook contract across Pi skills, plugin skills, Pi command copy, and docs/config wording. + +## Detailed Guidance + +### Playbook skill Step 5.5 + +Insert a new synthesis step after investigation/finding summary and before asking for the topic. The step must instruct the agent to: + +- Convert findings into a chosen implementation target list when evidence supports a choice. +- Pick concrete actions for each selected target. +- Put confirmed findings and assumptions in Context/evidence-oriented content. +- Put implementation targets, actions, non-goals, and validation criteria in actionable sections. +- Move unresolved or judgment-heavy findings into Open Questions, follow-up scope, or non-goals. +- Avoid leaving the build plan as “perform the audit/investigation again”. + +Then adjust the topic and section-writing steps so the topic describes the implementation change and section content covers scope, code impact, acceptance criteria, and open questions when those dimensions are known. + +### Plan skill Path (c) + +After the investigation step, add a synthesis step with the same contract. Update subsequent steps so: + +- The topic prompt says the topic must describe the change to build, not the investigation already performed. +- Section writing explicitly states Scope, Code Impact, and Acceptance Criteria describe the implementation handoff. +- Investigation findings are recorded as context/evidence. +- Step 2 resumes from the synthesized handoff without re-running covered investigation. + +### Parity + +For every Pi skill wording change, mirror the same narrative in the corresponding plugin skill. Preserve existing platform-specific tool names only where the files already differ (`eforge_*` in Pi, `mcp__eforge__eforge_*` in plugin). Do not add parity-skip blocks for these changes unless a platform-specific affordance truly requires one. + +### Tests + +Extend `test/skills-docs-wiring.test.ts` with assertions that fail if the actionable-handoff contract disappears. Suggested assertions: + +- Pi and plugin playbook skills contain `implementation-ready session plan` and a synthesis step heading. +- Pi and plugin plan skills state the topic describes the change to build. +- Pi and plugin plan skills mention Scope, Code Impact, and Acceptance Criteria as implementation-handoff sections. +- The planning instructions mention evidence/context placement, concrete implementation targets, concrete actions, non-goals, validation criteria, and unresolved judgment-heavy findings becoming open questions or follow-up scope. +- `packages/pi-eforge/extensions/eforge/plan-command.ts` no longer contains `seed a session plan` for the planning playbook option and does contain `implementation-ready session plan`. +- `docs/config.md` planning playbook prose contains `implementation-ready session plan`. + +## Database Migration + +Not applicable. + +## Verification + +- [ ] `packages/pi-eforge/skills/eforge-playbook/SKILL.md` contains an explicit synthesis step before session creation or update in Step 5.5. +- [ ] `packages/pi-eforge/skills/eforge-plan/SKILL.md` Path (c) states the session topic describes the change to build, not the investigation already performed. +- [ ] `packages/pi-eforge/skills/eforge-plan/SKILL.md` Path (c) states Scope, Code Impact, and Acceptance Criteria describe the implementation handoff. +- [ ] Pi and plugin skill files remain in parity according to `pnpm docs:check-parity`. +- [ ] `packages/pi-eforge/extensions/eforge/plan-command.ts` planning playbook option text does not contain `seed a session plan`. +- [ ] `docs/config.md` planning playbook prose contains `implementation-ready session plan`. +- [ ] `eforge-plugin/.claude-plugin/plugin.json` version is incremented by one patch version. +- [ ] `pnpm docs:check-parity` exits 0. +- [ ] `pnpm maintainability:check` exits 0. +- [ ] `pnpm type-check` exits 0. +- [ ] `pnpm test -- test/skills-docs-wiring.test.ts test/pi-playbook-commands.test.ts` exits 0. From 7d9c44b2e839fb74bf8b10a7b2200f089c6180ae Mon Sep 17 00:00:00 2001 From: Mark Schaake Date: Thu, 28 May 2026 09:00:41 -0700 Subject: [PATCH 2/5] build(make-planning-mode-playbooks-produce-actionable-implementation-plans): record PRD provenance Co-Authored-By: forged-by-eforge --- ...produce-actionable-implementation-plans.md | 172 ++++++++++++++++++ 1 file changed, 172 insertions(+) create mode 100644 eforge/prds/make-planning-mode-playbooks-produce-actionable-implementation-plans.md diff --git a/eforge/prds/make-planning-mode-playbooks-produce-actionable-implementation-plans.md b/eforge/prds/make-planning-mode-playbooks-produce-actionable-implementation-plans.md new file mode 100644 index 00000000..f606ad35 --- /dev/null +++ b/eforge/prds/make-planning-mode-playbooks-produce-actionable-implementation-plans.md @@ -0,0 +1,172 @@ +--- +title: Make Planning-Mode Playbooks Produce Actionable Implementation Plans +created: 2026-05-28 +profile: gpt-claude-combo +landing: pr +landing_auto_merge: true +--- + +# Make Planning-Mode Playbooks Produce Actionable Implementation Plans + +## Problem / Motivation + +Planning-mode playbooks can currently lead agents to create session plans that restate or continue the investigation, rather than converting investigation findings into an implementation-ready plan. + +A planning-mode playbook was run for test thinning. The agent performed the investigation correctly, but the first resulting session plan was framed as an audit plan rather than an implementation-ready plan based on the audit findings. The user had to clarify that the investigation was already done and that the plan should identify concrete changes to build. + +User-visible symptom: + +- Running the `test-thinning-audit` planning playbook produced useful audit evidence, including duplicate `monitor-ui` / `console-ui` test targets. +- The resulting session plan initially described doing an audit / thinning discovery again. +- The user expected the playbook to do planning work up front and produce a concrete actionable plan for `/eforge:build`. + +Why it matters: + +- Planning-mode playbooks are meant to front-load recurring investigation so the resulting session plan can be reviewed and built. +- If the session plan repeats the playbook investigation objective, eforge wastes human / agent time and risks enqueueing vague or non-actionable work. +- The ambiguity affects both Pi and Claude Code skill flows because both contain similar planning-mode instructions. + +Observed reproduction: + +1. Run `/skill:eforge-playbook run test-thinning-audit`. +2. The agent performs the intended audit investigation and reports concrete findings, including duplicate `monitor-ui` / `console-ui` test targets. +3. The user asks to create the session plan. +4. The initial session plan is created around a test-thinning audit / broad candidate review, not around implementing a concrete target list from the audit. +5. The user clarifies: “I want this plan to be for the actual test thinning, not for an audit.” +6. After another refinement, the user further clarifies that the playbook should have helped produce a concrete actionable plan rather than a plan that assumes the audit will happen again during build. + +Expected behavior: + +- After investigation, the agent synthesizes findings into a specific implementation-ready plan: chosen targets, scope boundaries, files to change, out-of-scope follow-ups, and build-ready acceptance criteria. + +Actual behavior: + +- Existing instructions allowed the agent to write investigation findings and continue generic planning, without an explicit transformation step from findings to actionable build plan. + +Confirmed root cause: + +- The planning-mode playbook instructions emphasize investigation and writing findings, but do not explicitly state that the created session plan must be an actionable implementation plan derived from those findings. + +Evidence: + +- `packages/pi-eforge/skills/eforge-playbook/SKILL.md` Step 5.5 says to identify targets, investigate, summarize findings, ask for a topic, create the session plan, and write concrete sections. +- `packages/pi-eforge/skills/eforge-playbook/SKILL.md` Step 6 says “At minimum write a scope or goal section reflecting the playbook intent plus investigation results.” +- This wording leaves room for the scope to mirror the playbook’s investigation goal rather than the implementation outcome. +- `packages/pi-eforge/skills/eforge-plan/SKILL.md` Path (c) says to write investigation findings as concrete section content and then proceed to Step 2. +- `packages/pi-eforge/skills/eforge-plan/SKILL.md` does not require selecting concrete implementation targets or re-scoping the plan from “investigate X” to “change Y based on the investigation.” +- `eforge-plugin/skills/playbook/playbook.md` and `eforge-plugin/skills/plan/plan.md` contain parallel wording, so fixing only Pi would create behavior drift. + +Likely contributing factor: + +- UI / help wording such as “investigate, and seed a session plan” can imply the output is a seeded investigation artifact rather than a build-ready implementation plan. + +Root cause category: + +- Instruction-contract bug in first-party skill documentation and possibly related UI / help copy, not a daemon / session-plan data model defect. + +Roadmap alignment: + +- This supports the Console Workbench planning workspace direction and thin integration strategy by improving the session-plan artifact handoff semantics. + +## Goal + +Planning-mode playbooks should produce implementation-ready session plans derived from investigation findings, rather than plans that repeat or continue the investigation. + +The resulting plan should identify concrete changes to build, including chosen targets, scope boundaries, code impact, open questions or follow-ups, and build-ready acceptance criteria. + +## Approach + +Update first-party skill instructions and related user-facing copy so planning-mode playbook flows explicitly transform investigation findings into actionable implementation plans. + +Primary skill instruction files to update: + +- `packages/pi-eforge/skills/eforge-playbook/SKILL.md` +- `packages/pi-eforge/skills/eforge-plan/SKILL.md` +- `eforge-plugin/skills/playbook/playbook.md` +- `eforge-plugin/skills/plan/plan.md` + +Likely wording updates: + +- Add an explicit “synthesize implementation plan” step after investigation and before session creation in the planning-mode playbook run flow. +- Require the session topic and scope to describe the change to build, not the investigation itself. +- Require choosing concrete targets / actions from the findings when evidence supports them. +- Require splitting unresolved judgment-heavy findings into follow-up / open questions instead of leaving the whole plan as another investigation. +- Clarify that investigation findings belong in Context / assumptions / evidence sections. +- Clarify that Scope / Code Impact / Acceptance Criteria must describe the actionable implementation handoff. + +Secondary user-facing copy to review / update if needed: + +- `packages/pi-eforge/extensions/eforge/plan-command.ts` option description currently says “Load a planning playbook, investigate, and seed a session plan.” +- Consider wording like “investigate, then draft an implementation-ready session plan.” +- `docs/config.md` planning playbook description may need to clarify “implementation-ready session plan derived from findings.” + +Parity and packaging requirements: + +- Keep Pi and Claude plugin skill wording semantically aligned. +- Bump `eforge-plugin/.claude-plugin/plugin.json` because plugin-facing files change. +- Keep `eforge-plugin/` and `packages/pi-eforge/` consumer-facing behavior in sync. + +Relevant tests / checks: + +- `pnpm docs:check-parity` or `node scripts/check-skill-parity.mjs` should pass after skill updates. +- `pnpm test -- test/skills-docs-wiring.test.ts test/pi-playbook-commands.test.ts` may be useful if wording or command behavior changes. +- `pnpm maintainability:check` should pass. + +Material assumptions: + +| Assumption | Evidence / validation performed | Confidence | Cost to validate further | Validation path | Impact if wrong | +|---|---|---:|---:|---|---| +| This is best fixed in skill / playbook instructions rather than daemon APIs. | The daemon already returns `requires-agent` for planning playbooks; the failure was agent interpretation during interactive planning. | High | Low | Inspect implementation only if skill wording cannot enforce behavior. | Changing daemon APIs would add unnecessary scope. | +| Updating both Pi and Claude plugin skill files is sufficient for first-party agent behavior. | Both integration packages carry the same planning-mode flow text. | High | Low | Run docs / skill parity checks after edits. | One integration could keep producing non-actionable plans. | +| Native Pi menu copy may contribute to the ambiguity. | The plan command option says “investigate, and seed a session plan.” | Medium | Low | Review and update copy if it still implies template seeding rather than actionable handoff. | Users and agents may keep thinking the output is just an investigation seed. | +| The exact wording can be improved without adding new daemon / session-plan fields. | The session plan format already supports context, scope, code-impact, acceptance criteria, and open questions. | High | Low | Validate by ensuring the revised instructions mention where findings vs implementation plan content should go. | A data-model change would be larger than needed. | + +Recommended profile: **Excursion**. + +Rationale: + +- This is a multi-file consumer-facing behavior / documentation fix across Pi and Claude plugin skills. +- The scope is cohesive and does not require delegated module planning. +- It is not an Errand because parity, wording, plugin versioning, and docs / checks must all be handled carefully. + +## Scope + +In scope: + +- Update planning-mode run flow instructions in `packages/pi-eforge/skills/eforge-playbook/SKILL.md`. +- Update planning-playbook path instructions in `packages/pi-eforge/skills/eforge-plan/SKILL.md`. +- Update semantically equivalent Claude Code skill instructions in `eforge-plugin/skills/playbook/playbook.md`. +- Update semantically equivalent Claude Code skill instructions in `eforge-plugin/skills/plan/plan.md`. +- Review and update `packages/pi-eforge/extensions/eforge/plan-command.ts` if the option copy remains misleading. +- Review and update `docs/config.md` if the planning playbook description needs wording changes for the new user-facing behavior. +- Bump `eforge-plugin/.claude-plugin/plugin.json` if any file under `eforge-plugin/` changes. +- Preserve Pi and Claude plugin behavior parity. +- Validate skill parity and maintainability checks. + +Out of scope: + +- Daemon API changes. +- Session-plan data model changes. +- New daemon / session-plan fields. +- Re-running the `test-thinning-audit` implementation itself. + +## Acceptance Criteria + +- `packages/pi-eforge/skills/eforge-playbook/SKILL.md` planning-mode run flow explicitly requires synthesizing investigation findings into an implementation-ready session plan before creating or updating the session. +- `packages/pi-eforge/skills/eforge-plan/SKILL.md` planning-playbook path explicitly requires the session topic to describe the change to build rather than the investigation that was already performed. +- `packages/pi-eforge/skills/eforge-plan/SKILL.md` planning-playbook path explicitly requires the scope to describe the change to build rather than the investigation that was already performed. +- `packages/pi-eforge/skills/eforge-plan/SKILL.md` planning-playbook path explicitly requires code impact to describe the change to build rather than the investigation that was already performed. +- `packages/pi-eforge/skills/eforge-plan/SKILL.md` planning-playbook path explicitly requires acceptance criteria to describe the change to build rather than the investigation that was already performed. +- `eforge-plugin/skills/playbook/playbook.md` contains semantically equivalent planning-mode run instructions to the Pi playbook skill. +- `eforge-plugin/skills/plan/plan.md` contains semantically equivalent planning-playbook path instructions to the Pi plan skill. +- Planning-mode instructions state that investigation findings should be recorded as evidence or context. +- Planning-mode instructions state that actionable sections should name concrete implementation targets. +- Planning-mode instructions state that actionable sections should name concrete actions. +- Planning-mode instructions state that actionable sections should name non-goals. +- Planning-mode instructions state that actionable sections should name validation criteria. +- Planning-mode instructions state that unresolved or judgment-heavy findings should become explicit open questions or follow-up scope. +- Planning-mode instructions do not allow unresolved or judgment-heavy findings to remain as a vague request to re-run the investigation during build. +- `packages/pi-eforge/extensions/eforge/plan-command.ts` planning playbook option copy no longer describes the output only as seeding a plan if that wording remains misleading. +- `eforge-plugin/.claude-plugin/plugin.json` version is bumped if any file under `eforge-plugin/` changes. +- `pnpm docs:check-parity` exits 0. +- `pnpm maintainability:check` exits 0. From b253a07543746316a07e1b3734b9d4025315d1e1 Mon Sep 17 00:00:00 2001 From: Mark Schaake Date: Thu, 28 May 2026 09:07:24 -0700 Subject: [PATCH 3/5] feat(plan-01-actionable-planning-playbooks): Make Planning Playbooks Produce Actionable Session Plans Co-Authored-By: forged-by-eforge --- docs/config.md | 2 +- eforge-plugin/.claude-plugin/plugin.json | 2 +- eforge-plugin/skills/plan/plan.md | 16 +- eforge-plugin/skills/playbook/playbook.md | 21 ++- .../extensions/eforge/plan-command.ts | 2 +- .../pi-eforge/skills/eforge-plan/SKILL.md | 16 +- .../pi-eforge/skills/eforge-playbook/SKILL.md | 21 ++- test/skills-docs-wiring.test.ts | 169 ++++++++++++++++++ 8 files changed, 222 insertions(+), 27 deletions(-) diff --git a/docs/config.md b/docs/config.md index b6c44a15..3aa85d96 100644 --- a/docs/config.md +++ b/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 `, `--profile `); `edit ` opens the resolved playbook in `$EDITOR` and validates the result before saving; `run [--after ]` runs the playbook (also available as `eforge play `) — 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 ` moves a playbook from `.eforge/playbooks/` to `eforge/playbooks/` and stages the new file; `demote ` 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 `, `--profile `); `edit ` opens the resolved playbook in `$EDITOR` and validates the result before saving; `run [--after ]` runs the playbook (also available as `eforge play `) — 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 ` moves a playbook from `.eforge/playbooks/` to `eforge/playbooks/` and stages the new file; `demote ` moves it back to project-local scope. ### Playbook `profile` field diff --git a/eforge-plugin/.claude-plugin/plugin.json b/eforge-plugin/.claude-plugin/plugin.json index 88ee3c1c..e45266c0 100644 --- a/eforge-plugin/.claude-plugin/plugin.json +++ b/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", diff --git a/eforge-plugin/skills/plan/plan.md b/eforge-plugin/skills/plan/plan.md index 76166e2c..00e39ce2 100644 --- a/eforge-plugin/skills/plan/plan.md +++ b/eforge-plugin/skills/plan/plan.md @@ -32,7 +32,7 @@ If `--session ` 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. +6.5. **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. +7. 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. 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. +10. 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. +11. Proceed to Step 2 (Gather Context) — the synthesized implementation handoff from step 6.5 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 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. +> **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. diff --git a/eforge-plugin/skills/playbook/playbook.md b/eforge-plugin/skills/playbook/playbook.md index 85dcfdf9..704212e1 100644 --- a/eforge-plugin/skills/playbook/playbook.md +++ b/eforge-plugin/skills/playbook/playbook.md @@ -18,7 +18,7 @@ A lower-tier playbook with the same name **shadows** a higher-tier one. eforge a Every playbook has a `mode` field in its frontmatter: - **`mode: autonomous`** — eforge builds the playbook end-to-end without further prompting. Hand-off-and-forget: the daemon enqueues it and runs it. Suitable for mechanical, repeatable workflows where the build agent does not need to consult the user mid-run. -- **`mode: planning`** — running the playbook triggers an investigation-first workflow. The agent loads the playbook, performs the investigation guided by the playbook's Goal, Acceptance criteria, and Notes for the planner, creates a session plan with concrete findings and action items, and continues the planning conversation interactively. The daemon does not create the session plan directly. +- **`mode: planning`** — running the playbook triggers an investigation-first workflow. The agent loads the playbook, performs the investigation guided by the playbook's Goal, Acceptance criteria, and Notes for the planner, synthesizes investigation findings into an implementation-ready session plan with concrete implementation targets, actions, non-goals, and validation criteria, and continues the planning conversation interactively. The daemon does not create the session plan directly. The `mode` field governs what happens when you run a playbook: `autonomous` enqueues a build; `planning` starts an investigation-first planning workflow. @@ -128,7 +128,7 @@ When classification is confident, state the inferred scope briefly: Ask the user which mode this playbook should use: -> "Should this be an **autonomous** playbook (eforge builds it end-to-end without further prompting — hand-off-and-forget) or a **planning** playbook (the agent investigates first, creates a session plan with findings, and continues `/eforge:plan` interactively before building)?" +> "Should this be an **autonomous** playbook (eforge builds it end-to-end without further prompting — hand-off-and-forget) or a **planning** playbook (the agent investigates first, synthesizes findings into an implementation-ready session plan, and continues `/eforge:plan` interactively before building)?" **Default heuristic** — pre-select a suggestion before asking, based on the workflow description: @@ -252,7 +252,7 @@ Same as Step 3.5. Validate before saving, surface errors verbatim, do NOT write ## Branch: Run (Step 5) -Run a playbook. For autonomous playbooks this enqueues a build (with an optional wait for an in-flight build to finish first). For planning playbooks the agent performs an investigation-first workflow: loads the playbook, investigates the codebase guided by the playbook's Goal, Acceptance criteria, and Notes, creates a session plan with concrete findings and action items, and continues interactively via `/eforge:plan`. +Run a playbook. For autonomous playbooks this enqueues a build (with an optional wait for an in-flight build to finish first). For planning playbooks the agent performs an investigation-first workflow: loads the playbook, investigates the codebase guided by the playbook's Goal, Acceptance criteria, and Notes, synthesizes findings into an implementation-ready session plan, and continues interactively via `/eforge:plan`. ### 5.1: Pick a playbook @@ -367,13 +367,20 @@ Do not call `mcp__eforge__eforge_playbook { action: "run" }` for planning playbo 3. **Summarize findings**: Build a clear summary of what was found — concrete evidence, confirmed facts, and any remaining assumptions with confidence levels. -4. **Ask for a topic**: Ask the user for a short topic to anchor this session (the playbook provides the shape; the topic anchors it to the current work). If the playbook's Goal makes the topic obvious, suggest it and allow override. +4. **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 (e.g., "refactor X to use Y", "add Z to module A"). + - **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 should not instruct the build agent to repeat the investigation. If evidence is insufficient to choose a target, state that as an open question. -5. **Create the session plan**: Generate a session ID `{YYYY-MM-DD}-{playbook-name}` (e.g. `2026-05-19-complexity-hotspot-reduction`). 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 the 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, do not abandon the flow: 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. +5. **Ask for a topic**: Ask the user for a short 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. -6. **Write concrete sections**: Write investigation findings as concrete section content using `mcp__eforge__eforge_session_plan { action: "set-section", session, dimension, content }`. At minimum write a scope or goal section reflecting the playbook intent plus investigation results. Include specific evidence — not generic playbook template language. +6. **Create the session plan**: Generate a session ID `{YYYY-MM-DD}-{playbook-name}` (e.g. `2026-05-19-complexity-hotspot-reduction`). 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 the 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, do not abandon the flow: 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. -7. **Continue planning**: Announce the session plan path and offer to continue into `/eforge:plan --resume` to work through the remaining dimensions before building. +7. **Write implementation-ready sections**: Write section content using `mcp__eforge__eforge_session_plan { action: "set-section", session, dimension, content }`. Scope, Code Impact, and Acceptance Criteria sections must describe the implementation handoff — concrete targets, actions, and validation criteria — not the investigation findings. Record confirmed findings and evidence in context-oriented sections. Include specific evidence — not generic playbook template language. + +8. **Continue planning**: Announce the session plan path and offer to continue into `/eforge:plan --resume` to work through the remaining dimensions before building. > "Investigation complete. Session plan created at `{path}`. Would you like to continue with `/eforge:plan --resume` to work through the remaining planning dimensions?" **Defensive fallback**: If `mcp__eforge__eforge_playbook { action: "run" }` is called for a planning playbook and returns `{ kind: "requires-agent", mode: "planning", name, message }`, apply the investigation-first flow above starting from step 1. Do not prompt for a landing action in this fallback path. diff --git a/packages/pi-eforge/extensions/eforge/plan-command.ts b/packages/pi-eforge/extensions/eforge/plan-command.ts index 23667bb4..760cd9b3 100644 --- a/packages/pi-eforge/extensions/eforge/plan-command.ts +++ b/packages/pi-eforge/extensions/eforge/plan-command.ts @@ -193,7 +193,7 @@ export async function handlePlanCommand( { value: "playbook", label: "Start from a planning-mode playbook", - description: "Load a planning playbook, investigate, and seed a session plan", + description: "Load a planning playbook, investigate, then draft an implementation-ready session plan", }, ]); diff --git a/packages/pi-eforge/skills/eforge-plan/SKILL.md b/packages/pi-eforge/skills/eforge-plan/SKILL.md index 862445cd..61a006f1 100644 --- a/packages/pi-eforge/skills/eforge-plan/SKILL.md +++ b/packages/pi-eforge/skills/eforge-plan/SKILL.md @@ -32,7 +32,7 @@ If `--session ` 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 `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. +6.5. **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. +7. 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. 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 `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 `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 `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. +10. Write section content using `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. +11. Proceed to Step 2 (Gather Context) — the synthesized implementation handoff from step 6.5 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 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. +> **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`**: `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. diff --git a/packages/pi-eforge/skills/eforge-playbook/SKILL.md b/packages/pi-eforge/skills/eforge-playbook/SKILL.md index 66dc3041..4e4efe51 100644 --- a/packages/pi-eforge/skills/eforge-playbook/SKILL.md +++ b/packages/pi-eforge/skills/eforge-playbook/SKILL.md @@ -20,7 +20,7 @@ A lower-tier playbook with the same name **shadows** a higher-tier one. eforge a Every playbook has a `mode` field in its frontmatter: - **`mode: autonomous`** — eforge builds the playbook end-to-end without further prompting. Hand-off-and-forget: the daemon enqueues it and runs it. Suitable for mechanical, repeatable workflows where the build agent does not need to consult the user mid-run. -- **`mode: planning`** — running the playbook triggers an investigation-first workflow. The agent loads the playbook, performs the investigation guided by the playbook's Goal, Acceptance criteria, and Notes for the planner, creates a session plan with concrete findings and action items, and continues the planning conversation interactively. The daemon does not create the session plan directly. +- **`mode: planning`** — running the playbook triggers an investigation-first workflow. The agent loads the playbook, performs the investigation guided by the playbook's Goal, Acceptance criteria, and Notes for the planner, synthesizes investigation findings into an implementation-ready session plan with concrete implementation targets, actions, non-goals, and validation criteria, and continues the planning conversation interactively. The daemon does not create the session plan directly. The `mode` field governs what happens when you run a playbook: `autonomous` enqueues a build; `planning` starts an investigation-first planning workflow. @@ -130,7 +130,7 @@ When classification is confident, state the inferred scope briefly: Ask the user which mode this playbook should use: -> "Should this be an **autonomous** playbook (eforge builds it end-to-end without further prompting — hand-off-and-forget) or a **planning** playbook (the agent investigates first, creates a session plan with findings, and continues `/eforge:plan` interactively before building)?" +> "Should this be an **autonomous** playbook (eforge builds it end-to-end without further prompting — hand-off-and-forget) or a **planning** playbook (the agent investigates first, synthesizes findings into an implementation-ready session plan, and continues `/eforge:plan` interactively before building)?" **Default heuristic** — pre-select a suggestion before asking, based on the workflow description: @@ -254,7 +254,7 @@ Same as Step 3.5. Validate before saving, surface errors verbatim, do NOT write ## Branch: Run (Step 5) -Run a playbook. For autonomous playbooks this enqueues a build (with an optional wait for an in-flight build to finish first). For planning playbooks the agent performs an investigation-first workflow: loads the playbook, investigates the codebase guided by the playbook's Goal, Acceptance criteria, and Notes, creates a session plan with concrete findings and action items, and continues interactively via `/eforge:plan`. +Run a playbook. For autonomous playbooks this enqueues a build (with an optional wait for an in-flight build to finish first). For planning playbooks the agent performs an investigation-first workflow: loads the playbook, investigates the codebase guided by the playbook's Goal, Acceptance criteria, and Notes, synthesizes findings into an implementation-ready session plan, and continues interactively via `/eforge:plan`. ### 5.1: Pick a playbook @@ -369,13 +369,20 @@ Do not call `eforge_playbook { action: "run" }` for planning playbooks — the d 3. **Summarize findings**: Build a clear summary of what was found — concrete evidence, confirmed facts, and any remaining assumptions with confidence levels. -4. **Ask for a topic**: Ask the user for a short topic to anchor this session (the playbook provides the shape; the topic anchors it to the current work). If the playbook's Goal makes the topic obvious, suggest it and allow override. +4. **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 (e.g., "refactor X to use Y", "add Z to module A"). + - **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 should not instruct the build agent to repeat the investigation. If evidence is insufficient to choose a target, state that as an open question. -5. **Create the session plan**: Generate a session ID `{YYYY-MM-DD}-{playbook-name}` (e.g. `2026-05-19-complexity-hotspot-reduction`). If the playbook has a `profile` field, call `eforge_session_plan { action: "create", session: "{session-id}", topic: "{topic}", open: true, agent_profile: "{playbook.profile}" }` so the session plan inherits the profile at enqueue time. If the playbook has no `profile`, call `eforge_session_plan { action: "create", session: "{session-id}", topic: "{topic}", open: true }`. If that session ID already exists, do not abandon the flow: 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. +5. **Ask for a topic**: Ask the user for a short 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. -6. **Write concrete sections**: Write investigation findings as concrete section content using `eforge_session_plan { action: "set-section", session, dimension, content }`. At minimum write a scope or goal section reflecting the playbook intent plus investigation results. Include specific evidence — not generic playbook template language. +6. **Create the session plan**: Generate a session ID `{YYYY-MM-DD}-{playbook-name}` (e.g. `2026-05-19-complexity-hotspot-reduction`). If the playbook has a `profile` field, call `eforge_session_plan { action: "create", session: "{session-id}", topic: "{topic}", open: true, agent_profile: "{playbook.profile}" }` so the session plan inherits the profile at enqueue time. If the playbook has no `profile`, call `eforge_session_plan { action: "create", session: "{session-id}", topic: "{topic}", open: true }`. If that session ID already exists, do not abandon the flow: 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. -7. **Continue planning**: Announce the session plan path and offer to continue into `/eforge:plan --resume` to work through the remaining dimensions before building. +7. **Write implementation-ready sections**: Write section content using `eforge_session_plan { action: "set-section", session, dimension, content }`. Scope, Code Impact, and Acceptance Criteria sections must describe the implementation handoff — concrete targets, actions, and validation criteria — not the investigation findings. Record confirmed findings and evidence in context-oriented sections. Include specific evidence — not generic playbook template language. + +8. **Continue planning**: Announce the session plan path and offer to continue into `/eforge:plan --resume` to work through the remaining dimensions before building. > "Investigation complete. Session plan created at `{path}`. Would you like to continue with `/eforge:plan --resume` to work through the remaining planning dimensions?" **Defensive fallback**: If `eforge_playbook { action: "run" }` is called for a planning playbook and returns `{ kind: "requires-agent", mode: "planning", name, message }`, apply the investigation-first flow above starting from step 1. Do not prompt for a landing action in this fallback path. diff --git a/test/skills-docs-wiring.test.ts b/test/skills-docs-wiring.test.ts index d95b4e7b..aa0f89d9 100644 --- a/test/skills-docs-wiring.test.ts +++ b/test/skills-docs-wiring.test.ts @@ -476,6 +476,175 @@ describe('eforge-plugin/skills/plan/plan.md — AC quality guidance', () => { }); }); +// --------------------------------------------------------------------------- +// Actionable planning-playbook contract (plan-01-actionable-planning-playbooks) +// --------------------------------------------------------------------------- + +describe('playbook skills — implementation-ready session plan contract', () => { + const piPlaybook = readRepoFile('packages/pi-eforge/skills/eforge-playbook/SKILL.md'); + const pluginPlaybook = readRepoFile('eforge-plugin/skills/playbook/playbook.md'); + + it('Pi playbook skill contains "implementation-ready session plan"', () => { + expect(piPlaybook).toContain('implementation-ready session plan'); + }); + + it('plugin playbook skill contains "implementation-ready session plan"', () => { + expect(pluginPlaybook).toContain('implementation-ready session plan'); + }); + + it('Pi playbook skill contains a synthesis step heading in Step 5.5', () => { + expect(piPlaybook).toContain('Synthesize implementation handoff'); + }); + + it('plugin playbook skill contains a synthesis step heading in Step 5.5', () => { + expect(pluginPlaybook).toContain('Synthesize implementation handoff'); + }); + + it('Pi playbook skill mentions concrete implementation targets in synthesis step', () => { + expect(piPlaybook).toContain('implementation targets'); + }); + + it('plugin playbook skill mentions concrete implementation targets in synthesis step', () => { + expect(pluginPlaybook).toContain('implementation targets'); + }); + + it('Pi playbook skill mentions concrete actions in synthesis step', () => { + expect(piPlaybook).toContain('concrete actions'); + }); + + it('plugin playbook skill mentions concrete actions in synthesis step', () => { + expect(pluginPlaybook).toContain('concrete actions'); + }); + + it('Pi playbook skill mentions non-goals in synthesis step', () => { + expect(piPlaybook).toContain('non-goals'); + }); + + it('plugin playbook skill mentions non-goals in synthesis step', () => { + expect(pluginPlaybook).toContain('non-goals'); + }); + + it('Pi playbook skill mentions validation criteria in synthesis step', () => { + expect(piPlaybook).toContain('validation criteria'); + }); + + it('plugin playbook skill mentions validation criteria in synthesis step', () => { + expect(pluginPlaybook).toContain('validation criteria'); + }); + + it('Pi playbook skill mentions evidence/context placement', () => { + expect(piPlaybook).toMatch(/context.oriented/i); + }); + + it('plugin playbook skill mentions evidence/context placement', () => { + expect(pluginPlaybook).toMatch(/context.oriented/i); + }); + + it('Pi playbook skill mentions unresolved findings becoming open questions or follow-up scope', () => { + expect(piPlaybook).toContain('Open Questions'); + expect(piPlaybook).toContain('follow-up scope'); + }); + + it('plugin playbook skill mentions unresolved findings becoming open questions or follow-up scope', () => { + expect(pluginPlaybook).toContain('Open Questions'); + expect(pluginPlaybook).toContain('follow-up scope'); + }); + + it('Pi playbook skill warns against audit-repeat plans', () => { + expect(piPlaybook).toContain('audit-repeat'); + }); + + it('plugin playbook skill warns against audit-repeat plans', () => { + expect(pluginPlaybook).toContain('audit-repeat'); + }); +}); + +describe('plan skills — implementation-handoff contract in Path (c)', () => { + const piPlan = readRepoFile('packages/pi-eforge/skills/eforge-plan/SKILL.md'); + const pluginPlan = readRepoFile('eforge-plugin/skills/plan/plan.md'); + + it('Pi plan skill Path (c) option 3 says create an implementation-ready session plan', () => { + expect(piPlan).toContain('implementation-ready session plan'); + }); + + it('plugin plan skill Path (c) option 3 says create an implementation-ready session plan', () => { + expect(pluginPlan).toContain('implementation-ready session plan'); + }); + + it('Pi plan skill Path (c) states the topic describes the change to build', () => { + // Step 7 must tell the agent to ask for a topic describing the implementation change + expect(piPlan).toMatch(/topic.*describes.*implementation change to build/s); + }); + + it('plugin plan skill Path (c) states the topic describes the change to build', () => { + expect(pluginPlan).toMatch(/topic.*describes.*implementation change to build/s); + }); + + it('Pi plan skill Path (c) mentions Scope as an implementation-handoff section', () => { + const pathCStart = piPlan.indexOf('**Path (c)'); + const pathCContent = piPlan.slice(pathCStart, pathCStart + 3000); + expect(pathCContent).toContain('Scope'); + }); + + it('Pi plan skill Path (c) mentions Code Impact as an implementation-handoff section', () => { + const pathCStart = piPlan.indexOf('**Path (c)'); + const pathCContent = piPlan.slice(pathCStart, pathCStart + 3000); + expect(pathCContent).toContain('Code Impact'); + }); + + it('Pi plan skill Path (c) mentions Acceptance Criteria as an implementation-handoff section', () => { + const pathCStart = piPlan.indexOf('**Path (c)'); + const pathCContent = piPlan.slice(pathCStart, pathCStart + 3000); + expect(pathCContent).toContain('Acceptance Criteria'); + }); + + it('plugin plan skill Path (c) mentions Scope, Code Impact, and Acceptance Criteria as handoff sections', () => { + const pathCStart = pluginPlan.indexOf('**Path (c)'); + const pathCContent = pluginPlan.slice(pathCStart, pathCStart + 3000); + expect(pathCContent).toContain('Scope'); + expect(pathCContent).toContain('Code Impact'); + expect(pathCContent).toContain('Acceptance Criteria'); + }); + + it('Pi plan skill Path (c) contains synthesis step', () => { + expect(piPlan).toContain('Synthesize implementation handoff'); + }); + + it('plugin plan skill Path (c) contains synthesis step', () => { + expect(pluginPlan).toContain('Synthesize implementation handoff'); + }); + + it('Pi plan skill sub-note mentions synthesized handoff', () => { + expect(piPlan).toContain('synthesized implementation handoff'); + }); + + it('plugin plan skill sub-note mentions synthesized handoff', () => { + expect(pluginPlan).toContain('synthesized implementation handoff'); + }); +}); + +describe('plan-command.ts — planning playbook option wording', () => { + const planCommand = readRepoFile('packages/pi-eforge/extensions/eforge/plan-command.ts'); + + it('does not contain "seed a session plan" for the planning playbook option', () => { + expect(planCommand).not.toContain('seed a session plan'); + }); + + it('contains "implementation-ready session plan" for the planning playbook option', () => { + expect(planCommand).toContain('implementation-ready session plan'); + }); +}); + +describe('docs/config.md — planning playbook prose', () => { + const docsConfig = readRepoFile('docs/config.md'); + + it('planning playbook prose contains "implementation-ready session plan"', () => { + expect(docsConfig).toContain('implementation-ready session plan'); + }); +}); + +// --------------------------------------------------------------------------- + describe('packages/pi-eforge/skills/eforge-plan/SKILL.md — AC quality guidance', () => { const raw = readRepoFile('packages/pi-eforge/skills/eforge-plan/SKILL.md'); From 25017837d67292d5c317a691a8b736112f82d733 Mon Sep 17 00:00:00 2001 From: Mark Schaake Date: Thu, 28 May 2026 09:18:58 -0700 Subject: [PATCH 4/5] fix(plan): recover actionable playbook review fixes --- README.md | 2 +- eforge-plugin/skills/plan/plan.md | 12 ++++++------ packages/pi-eforge/skills/eforge-plan/SKILL.md | 12 ++++++------ web/content/docs/playbooks.md | 4 ++-- 4 files changed, 15 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 0936b649..9797afbf 100644 --- a/README.md +++ b/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: diff --git a/eforge-plugin/skills/plan/plan.md b/eforge-plugin/skills/plan/plan.md index 00e39ce2..b2f5d459 100644 --- a/eforge-plugin/skills/plan/plan.md +++ b/eforge-plugin/skills/plan/plan.md @@ -58,17 +58,17 @@ 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. -6.5. **Synthesize implementation handoff**: Before asking for a topic, convert findings into an implementation-ready handoff: +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. -7. 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. -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 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. -11. Proceed to Step 2 (Gather Context) — the synthesized implementation handoff from step 6.5 is the authoritative starting context. Step 2 resumes from the synthesized handoff without re-running covered investigation. +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. > diff --git a/packages/pi-eforge/skills/eforge-plan/SKILL.md b/packages/pi-eforge/skills/eforge-plan/SKILL.md index 61a006f1..8618135e 100644 --- a/packages/pi-eforge/skills/eforge-plan/SKILL.md +++ b/packages/pi-eforge/skills/eforge-plan/SKILL.md @@ -58,17 +58,17 @@ Then follow the corresponding path below. 4. Call `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. -6.5. **Synthesize implementation handoff**: Before asking for a topic, convert findings into an implementation-ready handoff: +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. -7. 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. -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 `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 `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 section content using `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. -11. Proceed to Step 2 (Gather Context) — the synthesized implementation handoff from step 6.5 is the authoritative starting context. Step 2 resumes from the synthesized handoff without re-running covered investigation. +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 `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 `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 `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. > diff --git a/web/content/docs/playbooks.md b/web/content/docs/playbooks.md index 8f8a5334..e7757a01 100644 --- a/web/content/docs/playbooks.md +++ b/web/content/docs/playbooks.md @@ -13,11 +13,11 @@ Every playbook has a `mode` field in its YAML frontmatter: **`mode: autonomous`** - running the playbook enqueues a build directly, like any other eforge input. The daemon picks it up and runs the full pipeline without further interaction. Use this for mechanical, predictable workflows where the build agent does not need to consult you mid-run. -**`mode: planning`** - running the playbook triggers 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 action items, and then continues interactively via `/eforge:plan` before handing off to `/eforge:build`. The daemon does not create the session plan directly; you drive the planning conversation. +**`mode: planning`** - running the playbook triggers an investigation-first workflow. The agent loads the playbook, investigates the codebase guided by the playbook's Goal, Acceptance criteria, and Notes, synthesizes findings into an implementation-ready session plan, and then continues interactively via `/eforge:plan` before handing off to `/eforge:build`. The daemon does not create the session plan directly; you drive the planning conversation. When you call `eforge_playbook { action: "run" }` for a planning playbook, the daemon returns `{ kind: "requires-agent", mode: "planning" }` - this signals that a Claude Code or Pi agent must take over the investigation, not that the build failed. -Planning-mode playbooks produce session plans through the host agent workflow, not by directly enqueueing a PRD. The agent creates or resumes a file in `.eforge/session-plans/`, writes investigation findings into the relevant dimensions, checks readiness, and then `/eforge:build` submits the ready session-plan file as build source. If the playbook declares `profile`, the session plan inherits it as `agent_profile`; the profile is validated when that session plan is enqueued. If the playbook declares `postMerge`, those commands are forwarded only when an autonomous playbook is converted directly to build source. +Planning-mode playbooks produce session plans through the host agent workflow, not by directly enqueueing a PRD. The agent creates or resumes a file in `.eforge/session-plans/`, records confirmed investigation findings as context/evidence in context-oriented sections, and makes Scope, Code Impact, and Acceptance Criteria describe concrete implementation targets, actions, and validation criteria. Then `/eforge:build` submits the ready session-plan file as build source. If the playbook declares `profile`, the session plan inherits it as `agent_profile`; the profile is validated when that session plan is enqueued. If the playbook declares `postMerge`, those commands are forwarded only when an autonomous playbook is converted directly to build source. ## Scope tiers From e9315ac552599a4e23d9936d8b2e863b3e1bc756 Mon Sep 17 00:00:00 2001 From: Mark Schaake Date: Thu, 28 May 2026 09:25:12 -0700 Subject: [PATCH 5/5] docs: regenerate playbooks public mirror --- web/public/docs/playbooks.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/web/public/docs/playbooks.md b/web/public/docs/playbooks.md index 8f8a5334..e7757a01 100644 --- a/web/public/docs/playbooks.md +++ b/web/public/docs/playbooks.md @@ -13,11 +13,11 @@ Every playbook has a `mode` field in its YAML frontmatter: **`mode: autonomous`** - running the playbook enqueues a build directly, like any other eforge input. The daemon picks it up and runs the full pipeline without further interaction. Use this for mechanical, predictable workflows where the build agent does not need to consult you mid-run. -**`mode: planning`** - running the playbook triggers 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 action items, and then continues interactively via `/eforge:plan` before handing off to `/eforge:build`. The daemon does not create the session plan directly; you drive the planning conversation. +**`mode: planning`** - running the playbook triggers an investigation-first workflow. The agent loads the playbook, investigates the codebase guided by the playbook's Goal, Acceptance criteria, and Notes, synthesizes findings into an implementation-ready session plan, and then continues interactively via `/eforge:plan` before handing off to `/eforge:build`. The daemon does not create the session plan directly; you drive the planning conversation. When you call `eforge_playbook { action: "run" }` for a planning playbook, the daemon returns `{ kind: "requires-agent", mode: "planning" }` - this signals that a Claude Code or Pi agent must take over the investigation, not that the build failed. -Planning-mode playbooks produce session plans through the host agent workflow, not by directly enqueueing a PRD. The agent creates or resumes a file in `.eforge/session-plans/`, writes investigation findings into the relevant dimensions, checks readiness, and then `/eforge:build` submits the ready session-plan file as build source. If the playbook declares `profile`, the session plan inherits it as `agent_profile`; the profile is validated when that session plan is enqueued. If the playbook declares `postMerge`, those commands are forwarded only when an autonomous playbook is converted directly to build source. +Planning-mode playbooks produce session plans through the host agent workflow, not by directly enqueueing a PRD. The agent creates or resumes a file in `.eforge/session-plans/`, records confirmed investigation findings as context/evidence in context-oriented sections, and makes Scope, Code Impact, and Acceptance Criteria describe concrete implementation targets, actions, and validation criteria. Then `/eforge:build` submits the ready session-plan file as build source. If the playbook declares `profile`, the session plan inherits it as `agent_profile`; the profile is validated when that session plan is enqueued. If the playbook declares `postMerge`, those commands are forwarded only when an autonomous playbook is converted directly to build source. ## Scope tiers