@difflab/pi 0.3.0 → 0.4.0-rc.202609231122.7b4400b

package/workflows/plan/help.md

@@ -0,0 +1,20 @@
+# help
+
+## Arguments
+
+- **Invocation:** `/plan help`
+- This workflow accepts no arguments.
+
+## Instructions
+
+Show these commands:
+
+- `/plan init <short-slug> [--branch <name>]` creates a phase-less draft.
+- `/plan new <short-slug> [--branch <name>] [--bg] [prompt...]` creates and populates a plan.
+- `/plan update [short-slug] [--branch <name>] [--bg] [instructions...]` applies the current plan review before other instructions.
+- `/plan annotate [short-slug]` reviews the plan with tuicr and saves an immutable review dump when tuicr closes.
+- `/plan finalize [short-slug]` validates and marks a plan ready.
+- `/plan go <short-slug> [--mode <no-commit|commit|push>] [--bg]` starts execution.
+- `/plan help` shows this reference.
+
+`--branch` records or filters a branch. It does not create or switch branches. Background workflows do not ask questions.

package/workflows/plan/init.md

@@ -0,0 +1,13 @@
+# init
+
+## Arguments
+
+- **Invocation:** `/plan init <short-slug> [--branch <name>]`
+- `<short-slug>` (required): Short, stable name used to identify the plan.
+- `--branch <name>` (optional): Branch metadata to record on the plan. It does not create or switch branches.
+
+## Instructions
+
+1. Call `plan_init` with the supplied slug and branch metadata. Include explicit intent, title and issue tracker id/url when available. The tool creates only `PLAN.md`.
+2. Open `PLAN.md` in supported IDEs/terminals/multiplexers in a new or available chat-adjacent tab. Skip to next step if IDE/terminal/mux is unsupported.
+3. Report the plan ID and path (clickable link so users can click to open in their environment). Explain that `/plan annotate` records a plan review and `/plan update` applies that plan review or direct chat instructions until `/plan finalize` is called.

package/workflows/plan/new.md

@@ -0,0 +1,20 @@
+# new
+
+## Arguments
+
+- **Invocation:** `/plan new <short-slug> [--branch <name>] [--bg] [prompt...]`
+- `<short-slug>` (required): Short, stable name used to identify the plan.
+- `--branch <name>` (optional): Branch metadata to record on the plan. It does not create or switch branches.
+- `--bg` (optional): Whether this is a background agent, or running in chat thread
+- `[prompt...]` (optional): Natural-language scope, requirements, or constraints for the plan.
+
+## Instructions
+
+1. Call `plan_context`, then `plan_init` if the supplied plan does not exist.
+2. In foreground mode, if `prompt` is not provided, ask the user "What would you like to plan?". If its clear from recent chat or branch name what is going to be worked on, provide options for the user to choose from along with a free text entry option. Use `ask_user_question` only for decisions that materially change scope.
+3. In background mode, never ask; record safe assumptions and stop with a blocker if ambiguity cannot be resolved.
+4. Once goal is understood, ground the plan in repository files and the supplied prompt if chat has not established this context..
+5. Use `plan_update_overview`, `plan_add_phase`, and `plan_update_phase` to create the plan. Use the planning tools to enforce the declared requirements, references, phase dependencies, file scopes, steps, and acceptance criteria; do not write PLAN.md by hand when a tool can make the change.
+6. Create one implementation file per phase at `.diffpi/plan/<plan-id>/implementation/phase-<phase-id>.md`. Fill in the implementation template with the phase summary, file tree, public APIs and data contracts, required libraries or algorithms, and implementation constraints. Keep each phase focused on one or two modules or libraries, preferably one. The only exception is when scaffolding structures for new projects/modules/libraries/etc.
+7. Keep Design near 300 words and call `plan_validate` in the background.
+8. After validation, if in foreground mode, notify the user that you will continue updating the plan with continued conversation. In background mode, finish planning and notify the user that they can explicitly call `/plan update` if they want to make updates and re-enter plan mode. Also notify them to use `/plan finalize` when ready for implementation.

package/workflows/plan/update.md

@@ -0,0 +1,18 @@
+# update
+
+## Arguments
+
+- **Invocation:** `/plan update [short-slug] [--branch <name>] [--bg] [instructions...]`
+- `[short-slug]` (optional): Plan to update. Omit it only when exactly one plan candidate is selected.
+- `--branch <name>` (optional): Branch metadata used to select or update the plan. It does not create or switch branches.
+- `--bg` (optional): Whether workflow is running in a bacground agent or main chat thread.
+- `[instructions...]` (optional): Natural-language changes to apply after the current plan review.
+
+## Instructions
+
+1. Call `plan_context` with the supplied slug and branch metadata. Infer slug based on recency/chat if not provided.
+2. Call `plan_review` before interpreting the supplied instructions. It returns the latest immutable tuicr review dump for the current plan revision. If no review exists, continue with the supplied instructions alone.
+3. Apply the review feedback and then the explicit instructions through `plan_update_overview`, `plan_add_phase`, `plan_remove_phase`, or `plan_update_phase`. Updating the plan advances its revision, so the review dump will not be applied again.
+4. In foreground mode, use `ask_user_question` for requests which need further discussion. In background mode, do not ask; address with best effort.
+5. Call `plan_validate` and address any issues.
+6. Tell the user they can continue updating the plan through chat, run `/plan annotate` for another review, finalize with `/plan finalize`, or proceed to implementation.