Structure implementation plan messages

build/api/index.js

@@ -6180,9 +6180,9 @@ exports.getRecommendStepsPrompt = getRecommendStepsPrompt;
  * Prompt for recommending implementation steps from an issue (RecommendStepsUseCase).
  */
 const fill_1 = __nccwpck_require__(2559);
-const TEMPLATE = `Based on the following issue description, recommend concrete steps to implement or address this issue. Order the steps logically (e.g. setup, implementation, tests, docs). Keep each step clear and actionable.
+const TEMPLATE = `Based on the following issue description, produce a concise implementation plan. Return three to eight logically ordered steps (for example: contract, implementation, tests, and documentation). Each step needs a short action title and zero to two brief supporting details. Add one specific, verifiable acceptance criterion for the whole plan.
 
-Write every human-readable sentence in {{targetLocale}}. Preserve code identifiers, paths, refs, commands, and URLs verbatim. Echo \`outputLocale\` exactly as \`{{targetLocale}}\`.
+Write every human-readable field in {{targetLocale}}. Preserve code identifiers, repository-relative paths, refs, and commands verbatim. Do not write Markdown or headings inside fields; the product owns presentation. Echo \`outputLocale\` exactly as \`{{targetLocale}}\`.
 
 {{projectContextInstruction}}
 
@@ -6191,20 +6191,29 @@ Write every human-readable sentence in {{targetLocale}}. Preserve code identifie
 
 {{previousRecommendation}}
 
-Return one JSON object with \`outputLocale\`, \`status\`, and \`steps\`. When a material recommendation is needed, set \`status\` to \`recommendation\` and put a complete numbered list in Markdown in \`steps\` (headings, lists, and code blocks are allowed). You can add brief sub-bullets per step if needed.
+Return one JSON object with \`outputLocale\`, \`status\`, \`steps\`, and \`acceptance\`. When a material recommendation is needed, set \`status\` to \`recommendation\`, return \`steps\` as an array of objects with \`title\` and \`details\`, and return the verifiable criterion in \`acceptance\`.
 
-If the current description does not require any material change to the previous recommendation, set \`status\` to \`unchanged\` and \`steps\` to null. Do not return \`unchanged\` when there is no previous recommendation.`;
+If the current description does not require any material change to the previous recommendation, set \`status\` to \`unchanged\` and set both \`steps\` and \`acceptance\` to null. Do not return \`unchanged\` when there is no previous recommendation.`;
 function getRecommendStepsPrompt(params) {
     return (0, fill_1.fillTemplate)(TEMPLATE, {
         projectContextInstruction: params.projectContextInstruction,
         issueNumber: String(params.issueNumber),
         issueDescription: params.issueDescription,
         targetLocale: params.targetLocale,
         previousRecommendation: params.previousRecommendation
-            ? `Previous recommendation (use only to detect whether the current plan is still valid):\n<previous-recommendation>\n${params.previousRecommendation}\n</previous-recommendation>`
+            ? `${previousRecommendationInstruction(params.previousRecommendationFormat)}\n<previous-recommendation>\n${params.previousRecommendation}\n</previous-recommendation>`
             : 'There is no previous recommendation for this issue.',
     });
 }
+function previousRecommendationInstruction(format) {
+    if (format === 'structured') {
+        return 'Previous structured recommendation (use only to detect whether the current plan is still valid):';
+    }
+    if (format === 'structured-other-locale') {
+        return 'Previous structured recommendation from another or unknown locale (return a complete structured replacement in the requested locale; do not return unchanged):';
+    }
+    return 'Previous legacy recommendation (return a complete structured replacement; do not return unchanged):';
+}
 
 
 /***/ }),

docs/features.mdx

@@ -38,7 +38,7 @@ When the workflow runs on `issues` (opened, edited, labeled, unlabeled, etc.):
 | **Issue type** | Sets the GitHub issue type (Task, Bug, Feature, Documentation, etc.) from labels. |
 | **Emoji titles** | Optionally adds emojis to issue titles based on labels (`emoji-labeled-title`). |
 | **Size labels** | Assigns size labels (XS–XXL) and checks size thresholds (lines, files, commits) for prioritization. |
-| **Planning guidance** | When planning is requested, maintains one bounded plan card with the outcome and next action. The Job Summary keeps only compact operator state; internal execution narration remains machine/log evidence. |
+| **Planning guidance** | When planning is requested, maintains one bounded card with 3–8 ordered steps, at most 2 short details per step, and a verifiable acceptance criterion. Copilot owns the layout; the issue locale defaults to English. Equivalent reruns are silent, while a material issue edit updates the same card. The Job Summary keeps only compact operator state. |
 | **Lifecycle labels** | Maintains an exclusive durable `state:*` phase, an optional `state:ai-processing` activity marker, and an optional human-waiting label. Activity can coexist with the durable phase and is removed when the agent run finishes. |
 
 ### 2. Pull request events (`on: pull_request`)

docs/issues/comment-commands.mdx

@@ -59,6 +59,47 @@ same source comment updates or reuses that response instead of creating another.
 These replies contain only their requested content; they are never wrapped in an
 “Automatic Actions” summary or a list of internal steps.
 
+### Implementation-plan response
+
+`/copilot plan` returns one implementation-plan card. The same card is also the
+planning surface used when a normal issue is opened with the planner configured,
+or when `recommend_steps_action` is invoked. It contains three to eight ordered
+steps, no more than two short details per step, and one specific, verifiable
+acceptance criterion. For example:
+
+```markdown
+## Implementation plan
+
+> **Current status:** Ready to start. No action is required from maintainers before implementation.
+
+1. **Define the locale contract**
+   - Add the repository default and issue/PR inheritance rules.
+   - Preserve BCP-47 identifiers in stored state.
+2. **Apply the contract at publication boundaries**
+   - Keep command names, paths, refs, and error codes unchanged.
+3. **Verify replay and migration behavior**
+   - Cover English defaults, a configured locale, and legacy stored plans.
+
+**Acceptance:** Replaying the same event creates no additional comment, while a material issue edit updates this card in the configured issue locale.
+
+Need something else? Mention the bot with a question or use `/copilot help`.
+```
+
+This visible structure is owned by Copilot rather than generated as arbitrary
+Markdown by the agent. The agent supplies only bounded titles, details, and the
+acceptance text in the effective issue locale. English (`en-US`) is the default;
+any configured valid locale uses the complete resolved catalog or fails back
+atomically to English. A plan with the wrong output locale or an invalid shape
+is rejected before publication. Material issue edits update the existing card;
+equivalent edits and webhook retries are silent. Stored free-form plans remain
+readable when no agent is available and migrate to this structure on the next
+configured planning run. Structured plan state also records the exact effective
+issue locale. A replay is allowed only while that locale still matches. Changing
+the issue or repository locale makes the next configured planning run replace
+the complete plan in the new language; an agent that returns `unchanged` is
+rejected. Without a configured agent, Copilot leaves the existing card untouched
+instead of republishing content whose language is unknown or no longer current.
+
 GitHub delivers a comment in the main PR conversation as an `issue_comment`
 event. Copilot uses GitHub's PR marker and exact PR number to keep that transport
 detail from changing the target: read-only commands such as `/copilot recheck`

docs/single-actions/available-actions.mdx

@@ -15,7 +15,7 @@ These actions need **`single-action-issue`** set to the issue number. The workfl
 |--------|-----------------|-------------|-------------|
 | **`check_progress_action`** | `single-action-issue` | Runs **progress check** on demand. The configured agent compares the issue description with the branch diff, updates the **progress** label (0–100%) on the issue and any open PR for that branch, and creates or updates one progress card. It snapshots the remote branch `HEAD` before analysis and suppresses every mutation if that source changes. | Progress is normally updated on every **push** (commit workflow). Use this to re-run without pushing, or when you don’t use the push workflow. Check out the branch you intend to assess; an absent remote branch fails closed. |
 | **`detect_potential_problems_action`** | `single-action-issue` | **Bugbot:** the configured agent analyzes the branch vs base and reports findings on the issue when no PR exists, or in one summarized review on an open PR; updates stored findings and resolves PR threads when findings are fixed. | Same as push-time Bugbot but on demand. See [Bugbot](/bugbot). |
-| **`recommend_steps_action`** | `single-action-issue` | Uses the configured agent's analysis role to recommend **implementation steps** from the issue description and creates or updates one bounded plan card. | When you want a one-off suggestion for how to implement the issue. |
+| **`recommend_steps_action`** | `single-action-issue` | Uses the configured agent's analysis role to create or update one bounded plan card with 3–8 ordered steps, at most 2 details per step, and a verifiable acceptance criterion. Copilot owns the layout; the issue locale defaults to English. | When you want a one-off implementation plan without an internal-step recap or duplicate comment. |
 | **`publish_issue_comment`** | `single-action-issue`, `single-action-message` | Creates a Markdown comment. With `single-action-comment-id`, it replaces that issue comment by default; set `single-action-comment-mode: append` to preserve its current content and append the message. | Reusable workflow notifications such as release or hotfix failures. |
 
 ## Actions that do not require an issue

docs/single-actions/examples.mdx

@@ -56,7 +56,9 @@ See [Bugbot](/bugbot) for full documentation.
 
 ## Workflow: recommend steps
 
-Get implementation steps for issue `789` and post them as a comment:
+Create or update the single implementation-plan card for issue `789`. The card
+contains 3–8 structured steps plus a verifiable acceptance criterion, uses the
+effective issue locale (English by default), and is reused on later runs:
 
 ```yaml
 - uses: vypdev/copilot@v3
@@ -200,6 +202,9 @@ copilot detect-potential-problems -i 456 -b feature/456-fix-bug --debug
 copilot recommend-steps -i 789
 ```
 
+This creates or updates the same bounded, English-default plan card as
+`recommend_steps_action`; equivalent reruns do not append another comment.
+
 ### think
 
 ```bash

docs/single-actions/workflow-and-cli.mdx

@@ -378,7 +378,22 @@ copilot detect-potential-problems -i 456 --dry-run --output json --effort high
 
 ### `copilot recommend-steps`
 
-Uses the configured analysis agent to recommend implementation steps from an issue and posts the recommendation as an issue comment.
+Uses the configured analysis agent to create or update one bounded implementation-plan
+card from an issue. The agent returns structured content: three to eight ordered
+steps, zero to two details per step, and one verifiable acceptance criterion.
+Copilot owns the Markdown layout, so model-generated headings or generic
+“Automatic Actions” wrappers cannot become the presentation.
+
+The plan uses the effective issue locale, defaulting to English (`en-US`). Paths,
+commands, refs, and code identifiers remain unchanged. A mismatched locale or
+malformed plan fails before publication. Re-running against an unchanged issue
+reconciles the existing card without creating a new comment; a material issue
+edit updates that card. Legacy free-form stored plans remain readable without an
+agent and migrate on the next configured run. Structured state records the exact
+plan locale: when the effective issue locale changes, the next agent-backed run
+must return a complete replacement in that locale and cannot answer `unchanged`.
+If no agent is configured, Copilot does not replay a structured plan whose locale
+is missing or different, so it cannot knowingly republish mixed-language UI.
 
 | Option | Required | Description |
 | --- | --- | --- |

scripts/coverage-budgets.json

@@ -359,6 +359,31 @@
       ],
       "successMessage": "repository localization coverage: PASS (pure policies 100%; changed path 95% lines/statements, 90% branches/functions)"
     },
+    {
+      "name": "Structured implementation plan",
+      "missingEntryLabel": "structured implementation plan",
+      "rules": [
+        {
+          "files": [
+            "src/domain/implementation_plan.ts"
+          ],
+          "mode": "each",
+          "thresholdProfile": "exhaustive"
+        },
+        {
+          "files": [
+            "src/data/model/recommendation_state.ts",
+            "src/application/policies/agent_response_schemas.ts",
+            "src/application/policies/semantic_result_publication_policy.ts",
+            "src/application/usecases/actions/recommend_steps_result_policy.ts",
+            "src/application/usecases/actions/recommend_steps_workflow.ts"
+          ],
+          "mode": "aggregate",
+          "thresholdProfile": "default"
+        }
+      ],
+      "successMessage": "structured implementation plan coverage: PASS (domain contract 100%; schema/workflow/publication path 95% lines/statements, 90% branches/functions)"
+    },
     {
       "name": "Branch synchronization presentation",
       "missingEntryLabel": "branch synchronization presentation",