alignfirst 0.7.0 → 0.8.0-preview.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "alignfirst",
-  "version": "0.7.0",
+  "version": "0.8.0-preview.0",
   "license": "CC0-1.0",
   "author": "Thomas MUR",
   "description": "The AlignFirst CLI: protocols, work files and docs in one command.",

package/templates/guide/code-review/correctness-reviewer.md

@@ -38,6 +38,7 @@ The most useful findings come from here, because nobody looks for them.
 | Signal | Question | Severity |
 | --- | --- | --- |
 | Function modified | Who calls it? Do callers outside the diff assume the old behavior? | 🔴 |
+| Code, branch or condition removed | What did it handle? Is that case now impossible, handled elsewhere, or silently dropped? | 🔴 |
 | One occurrence of a pattern fixed | Does the same pattern exist elsewhere, unfixed? Report once, with the count. | 🟡 |
 | Code the diff touches contains a bug unrelated to the diff | Report it as 🟣, without requiring a fix in this PR. | 🟣 |
 | Constant, enumeration, or type union extended | Was every place that exhausts it updated? | 🔴 |

package/templates/guide/code-review/intent-reviewer.md

@@ -8,7 +8,7 @@ Evaluate the change as a whole: what it tries to accomplish, and whether the imp
    - Is there a simpler design that achieves the same intent?
    - Does the change fit the architecture and conventions of the codebase, or work against them?
    - Does it leave the codebase healthier than before?
-   - Is the size proportionate to the intent? Layers, options, and generality nobody asked for cost as much as missing pieces.
+   - Is the size proportionate to the intent? A diff that adds more lines than it removes owes a reason; layers, options, and generality nobody asked for cost as much as missing pieces.
    - Does the diff mix a refactor with a behavior change? If they cannot be told apart, say so — it is what makes a review reliable or not.
 4. Report portions of code that deserve a **rewrite** as findings: 🟡, or 🔴 when the flaw defeats the intent. Observations about the change as a whole belong in the assessment, not in the findings list.
 

package/templates/guide/code-review/quality-reviewer.md

@@ -16,6 +16,8 @@ Also check consistency by example: does the new code match its neighbors in stru
 | Abstraction introduced with a single implementation | Does it solve a present problem, or an anticipated one? | 🟡 |
 | Boolean parameter added to an existing function | Does the function now do two things? | 🟡 |
 | New file | Is it in the right place per the repo's conventions? | 🟡 |
+| Defect fixed by adding code | Is the line that caused it still there? Removing the cause is often a proper fix. | 🟡 |
+| Check or branch for a case already ruled out by a type, a caller or an earlier check | What guarantees it? A guard for an impossible case hides the real contract. | 🟡 |
 
 ## DRY and YAGNI
 
@@ -52,3 +54,4 @@ Also check consistency by example: does the new code match its neighbors in stru
 | Mock added | Does it reproduce the real contract of the dependency, or an idealized version that can never fail? | 🟡 |
 | Test depending on the clock, network, execution order, or shared state | Source of flakiness. | 🟡 |
 | Assertion modified to make a test pass | Was the test fixed, or aligned with a bug? Strong signal: find out why it failed. | 🔴 |
+| Test deleted or skipped | Which behavior stops being verified? Was it fixed, or made to stop failing? | 🔴 |

package/templates/guide/code-review/reviewer-common.md

@@ -10,6 +10,8 @@ You are one of several reviewers examining the same branch, each from a differen
 
 ## Method
 
+Assume nothing works until the code shows it does: your job is to find how this change goes wrong. The bar below decides what you report, not what you look for.
+
 Work signal by signal: each checklist item is a signal/question pair, and applies only when its signal is visible in the diff. This keeps the review on the change, away from a general audit of the repository. A defect in the changed code is a finding even without a matching checklist item.
 
 To answer a checklist question, read the code — including files outside the diff (callers, configuration, the installed version of a dependency). Never guess.

package/templates/guide/protocols/aad.md

@@ -10,30 +10,39 @@ This is a 4-step protocol. Follow each step in order.
 
 ## 1. Investigate
 
-Check your context for available **documentation** and **skills**. Read every document and skill relevant to any aspect of the task — this is not optional. For each skill, also **read its relevant references**.
+Your context lists the available **documentation** and **skills**. Read every document and skill that applies to any aspect of the task, and the relevant references of each skill. A familiar-looking task tempts you to skip this reading; the project conventions live in these files.
 
-Explore the codebase. Take the time to understand how it currently works and what needs to change.
+Explore the codebase. Take the time to understand how it works today and what needs to change.
 
-Always seek a clean break solution by default. Never consider backward compatibility unless explicitly requested.
+Seek a clean break solution by default. Consider backward compatibility only when the user asks for it.
 
 ## 2. Discuss
 
-Present your findings and proposed approach. Ask clarifying questions. Explore trade-offs and edge cases.
+Nothing is implemented, and nothing is written in TICKET_DIR, before the user agrees. This step is where a small task reveals itself as a large one. It is never skipped.
 
-**Remember**: This discussion happens BEFORE any implementation or formal specification writing.
+The user is a developer who carries the global vision of the project and decides the choices that matter. You carry the details of the code you just read. The discussion keeps the user aware of what you found and hands them every decision worth taking.
 
-Engage in a thorough collaborative discussion covering:
+Manage the reader's attention. Open with the task as you understand it and the approach you propose, in two or three sentences. Then write one block per independent decision that needs the user. Write for a reader who has not opened the code today: a function, module or mechanism gets a few words of definition the first time you name it.
 
-- **Problem/Goal exploration**: Present your understanding and ask clarifying questions
-- **Current implementation analysis**: Share what you discovered and ask for confirmation or corrections
-- **Approach evaluation**: Discuss potential solutions and their trade-offs
-- **Edge cases and implications**: Explore potential issues and broader system impacts
+A block is a question and a recommendation:
 
-You're new to this project, the user can guide you.
+```
+❓ **Q1 - <title>**: <the problem in plain words, what the code does today in the words needed to decide, the options with their consequence>
+
+➡️ <your recommendation>
+```
+
+Look for edge cases and impacts on the rest of the system; each one that needs a decision gets its block.
+
+Every decision for the user is a numbered question, a yes/no one included; the simpler it is, the shorter its block. Numbering continues across rounds.
+
+Settle on your own what the code can answer; routine choices belong in the opening approach. Ask the user what needs their judgement: product behavior, scope, priorities, constraints the code does not show. Leave out the investigation narrative and the list of files you read.
+
+Ask in rounds: a question whose answer depends on another question still open waits for the next round. A question the reply skips stays open.
 
-Do not use your question tool. Always ask in plain text. Your questions will be the opportunity for a real discussion.
+When there is nothing to decide, say so in a few lines and ask for an explicit go.
 
-**This phase is mandatory.** If there is nothing to discuss, ask the user for an explicit validation.
+Do not use your question tool. Ask in plain text: your questions open a real discussion, a multiple-choice widget closes it.
 
 ## 3. Act
 
@@ -47,7 +56,7 @@ Use subagents (your subagent tool) for distinct, isolated units of work when ben
 
 Finalize the summary file: replace the working notes with the final content described below.
 
-Start the summary with a header, then a suggested commit message {{COMMIT_RULE}}. The shorter the better. Omit any field with nothing to list. Always exclude `alignfirst` from skills.
+Start the summary with a header, then a suggested commit message {{COMMIT_RULE}}. The shorter the better. Omit any field with nothing to list. Exclude `alignfirst` from the skills.
 
 Example:
 
@@ -64,15 +73,15 @@ Used documentation:
 Used skills: `skill-a`, `skill-b`
 ```
 
-The finalized summary is a **very concise handover document** that should capture:
+The finalized summary is a **very concise handover document**. It captures:
 
 - What was the topic or problem
 - What was decided or discovered
-- What action was taken (if any)
+- What action was taken, if any
 - Key outcomes or next steps
 
 The shorter the better.
 
-_Ignore markdown lint errors in the summary file._
+Ignore Markdown lint errors in the summary file.
 
 At the end, give the path of the summary file to the user.

package/templates/guide/protocols/description.md

@@ -24,23 +24,23 @@ Run `{{TICKET_CMD}}` once to identify TICKET_DIR and load the ticket directory c
 [description body]
 ```
 
-Start with a suggested commit message {{COMMIT_RULE}}. Refine it from the suggested commit messages found in the specs and summaries you read. Keep it brief—usually 3-5 words for the description part. Shorter is better when it's clear.
+Start with a suggested commit message {{COMMIT_RULE}}. Refine it from the suggested commit messages found in the specs and summaries you read. Keep it brief, usually 3 to 5 words for the description part. Shorter is better when it stays clear.
 
 ## Guidelines for the Description Body
 
 - Write in markdown:
   - If there is one subject, write a single paragraph.
   - Otherwise, write a bulleted list with one subject per item.
-- **Describe only WHAT was done, never WHY.** Never include explanations, justifications, or reasoning for the changes. Only state what was implemented or modified.
-- **Keep it minimal and functional.** Mention each subject very concisely—just the essentials. Most subjects can be summarized in one sentence of about 5 to 15 words.
-- **Always prefer functional/business descriptions.** Avoid technical implementation details unless absolutely necessary.
-- **CRITICAL: Merge related subjects whenever possible.** Look for opportunities to combine similar changes into a single, cohesive subject. This keeps the description focused and readable.
+- **Describe what was done, never why.** Explanations, justifications and reasoning stay out; the reader gets the result.
+- **Keep it minimal and functional.** Mention each subject very concisely, the essentials only. Most subjects fit in one sentence of about 5 to 15 words.
+- **Prefer functional descriptions.** Technical implementation details appear only when the reader needs them.
+- **Merge related subjects.** A long list of small items is the usual failure of a description; combine similar changes into one cohesive subject.
 - Include technical details only for major structural changes (e.g., renaming a database table, significant linter config changes, major codebase refactors).
-- Do not mention specs that were not implemented. If in doubt, explore the codebase to confirm what was actually done.
-- **Absorb fix-only summaries**: If a summary is about fixing issues introduced by previous summaries in the same ticket (e.g., bug fixes, corrections, adjustments to earlier work), do not mention it as a separate subject. An external reader only cares about the end state.
+- Leave out specs that were not implemented. In doubt, explore the codebase to confirm what was done.
+- **Absorb fix-only summaries.** A summary that fixes issues introduced by earlier work in the same ticket is not a subject of its own. An external reader only cares about the end state.
 
 ---
 
-_Ignore lint errors (formatting issues) in the description file._
+Ignore Markdown lint errors in the description file.
 
 At the end, give the path of the description file to the user.

package/templates/guide/protocols/merge.md

@@ -12,7 +12,7 @@ This protocol applies when a merge or rebase has produced conflicts, or when the
 
 Run `git status` to check for conflicts.
 
-**If there are no conflicts:** start the merge — use the incoming branch if the user provided one, {{BASE_BRANCH_RULE}} If the merge completes cleanly, you are done — no summary file needed. Otherwise, continue with the steps below.
+**If there are no conflicts:** start the merge — use the incoming branch if the user provided one, {{BASE_BRANCH_RULE}} A merge that completes cleanly ends the protocol, with no summary file. Otherwise, continue with the steps below.
 
 ## 2. Investigate
 
@@ -22,9 +22,9 @@ Take the time to understand how things work in the incoming branch and in the cu
 
 Run `{{TICKET_CMD}} --next merge.summary.md` to continue the current cycle. Append FILE_NAME to TICKET_DIR, then immediately create the summary at that path. Log each notable resolution in it as you resolve (see step 5 for the expected content).
 
-Resolve the conflicts properly — preserve both intents whenever possible. Do not blindly accept one side.
+Preserve both intents whenever possible. Accepting one side wholesale is the usual failure of a merge; it silently drops the other branch's work.
 
-Resolve conflicts one at a time. Avoid batch processing, broad search-and-replace operations, and other brute-force edits.
+Resolve conflicts one at a time. Batch processing, broad search-and-replace and other brute-force edits are out.
 
 **Special case for lock files:** If a lock file has conflicts:
 
@@ -41,7 +41,7 @@ If you need to execute the project, whether through E2E tests or manual checks,
 
 Finalize the summary file.
 
-**Keep it lean.** Only document challenging conflicts and the choices made to resolve them. Do not list straightforward resolutions — if everything was trivial, the summary should be almost empty (just a header and a one-line note that there was nothing tricky). Do not include a commit message — git already provides one for merges.
+**Keep it lean.** Document only the challenging conflicts and the choices made to resolve them. Straightforward resolutions stay out: when everything was trivial, the summary is a header and a one-line note that nothing was tricky. No commit message either; Git provides one for merges.
 
 Example:
 
@@ -59,6 +59,6 @@ Example:
 
 Omit any section with nothing to report.
 
-_Ignore markdown lint errors in the summary file._
+Ignore Markdown lint errors in the summary file.
 
 At the end, give the path of the summary file to the user.

package/templates/guide/protocols/plan.md

@@ -2,92 +2,85 @@
 
 ## Prerequisites
 
-### Determine TICKET_DIR and the Spec File
-
 You need:
 
 - the TICKET_DIR and ticket directory context — run `{{TICKET_CMD}}` once (`{{CMD}} ticket --side` for a side ticket, when there is no ticket)
 - a **spec file** in the TICKET_DIR
 
-Identify TICKET_DIR and the spec file before starting the protocol. If either is missing, STOP AND ASK THE USER.
+Without a spec file, stop and ask the user.
 
 ## Phases
 
-Before starting, **read the spec file** and understand it entirely.
+Read the spec file entirely before starting. Then plan in six phases, in this order:
 
-In order to generate implementation plans, you MUST follow this process:
+1. **Investigation**: explore the codebase and check the spec against it.
+2. **Analysis**: decide the plan structure, single or multiple, and collect the documentation and skills.
+3. **Plan Design**: design each plan.
+4. **Main Plan Design**: with multiple plans, design the main plan that coordinates them.
+5. **Writing**: write the plan files.
+6. **Review**: reread the plans critically and improve them.
 
-1. **Investigation**: Explore the codebase, understand the current implementation, and identify the problem
-2. **Analysis**: Determine the plan structure (single or multiple plans) and identify relevant documentation and skills
-3. **Plan Design**: Design plan(s) based on the analysis - If you discover issues or missing design decisions, STOP AND ASK THE USER
-4. **Main Plan Design**: If multiple plans, design a main plan to coordinate them
-5. **Writing**: Write the plan file(s)
-6. **Review**: Critically review and improve the plan(s)
+One rule holds across all phases: an important design decision the spec leaves open, or a spec that is wrong or contradicts the code, stops the protocol. Ask the user. A plan is executed by an agent that trusts it, often while the user is away.
 
 ## Phase 1. Investigation
 
-Check your context for available **documentation** and **skills**. Read every document and skill relevant to any aspect of the task — this is not optional. For each skill, also **read its relevant references**.
+Your context lists the available **documentation** and **skills**. Read every document and skill that applies to any aspect of the task, and the relevant references of each skill. A familiar-looking task tempts you to skip this reading; the project conventions live in these files.
 
-Investigate the codebase yourself, find the relevant source code, think carefully, take the time to understand how it currently works and what has to be done.
+Find the relevant source code. Take the time to understand how it works today and what has to change.
 
-Use the SPEC text as a starting point, but do not trust it blindly. Verify the current implementation and ensure the spec is still accurate. If you discover that an important design choice still needs to be made, or if the spec has issues, STOP AND ASK THE USER.
+The spec is the starting point, and it was written against an earlier state of the code. Verify each statement against the current implementation.
 
-For each operation in the spec, search for existing functions that do a similar job.
+For each operation in the spec, search for an existing function that does a similar job.
 
 ## Phase 2. Analysis
 
-Based on your investigation, determine the plan structure:
-
 ### 2.1 Assess Work Scopes
 
-Evaluate if the work should be split into multiple specialized plans or handled as a single plan:
+Prefer a single plan when the work fits one session, especially when it stays within one area.
 
-- **Single plan**: Preferred when work is small enough to be manageable, especially if it is cohesive within one area
-- **Multiple specialized plans with a main plan**: Split the work when it is complex, based on:
-  - **Distinct logical units**: When large enough, separate features or modules within the same stack
-  - **Stack boundaries**: Different technologies or specialization areas (if custom agents are defined, their descriptions can help identify these boundaries)
-  - Each specialized plan should produce a **coherent deliverable**
+Split complex work into specialized plans, coordinated by a main plan. Split along:
 
-### 2.2 Identify Relevant Documentation and Skills
+- **Distinct logical units**: separate features or modules, each large enough to stand alone
+- **Stack boundaries**: different technologies or specialization areas. The descriptions of custom agents, when some are defined, help find these boundaries.
+
+Each specialized plan produces a coherent deliverable.
 
-Identify which **documentation** and **skills** are relevant for the work. Omit if none apply.
+### 2.2 Identify Relevant Documentation and Skills
 
-- List the documentation and skills that the implementing agent should read and follow. Always exclude `alignfirst` from skills.
-- For complex skills with reference files, identify specific files that should be loaded
+List the documentation and skills the implementing agent must read and follow. Exclude `alignfirst` from the skills. For a skill with reference files, name the files to load. Omit the list when nothing applies.
 
 ## Phase 3. Plan Design
 
-Design an implementation plan based on the SPEC. Include all useful information from the spec. If the spec is already detailed enough, you can extract and reuse parts of it. Add implementation details, file paths, and a breakdown into steps that weren't in the spec.
+Design each plan from the spec. Reuse the parts of the spec that are detailed enough, and add what the spec lacks: implementation details, file paths, a breakdown into steps.
 
 ### 3.1 Plan Content Guidelines
 
-Follow these guidelines for all plans (single or specialized):
+These guidelines apply to every plan, single or specialized.
+
+The plan is a **self-explanatory prompt** for the coding agent. That agent starts from zero: tell it what you discovered.
 
-- The plan must be a **self-explanatory prompt** for the coding agent, so help it by explaining what you discovered that is relevant.
-- Give some context: explain how it works currently, and how it will work after the task is done.
-- In a "Prerequisites" section, list **relevant documentation and skills** to use. Do not repeat their content.
-- Mention a way to find **important source files**: by giving file paths, or by providing a function name to search for, for example. If needed, line numbers can be mentioned in the plan.
-- Include a list of **numbered steps**.
-- **Never plan backward compatibility** unless explicitly requested. Prefer clean code. Unused code must be removed.
-- About **tests**: First investigate the codebase to see if there are tests already in place for the kind of tests you're considering. Do not mention writing tests unless you are sure they will be well-integrated into the project.
-- Do not include sections like "Benefits", "Code Style Compliance", "Rationale" or anything that adds no actionable information. Focus on the problem and the solution.
-- List **existing functions to reuse or refactor**. Plan thin wrappers, not re-implementations. Each operation should have one proper place.
+- Give context: how it works today, and how it will work after the task.
+- In a "Prerequisites" section, list the relevant documentation and skills. Do not repeat their content.
+- Give a way to find the **important source files**: file paths, or a function name to search for. Line numbers are fine in a plan.
+- Give **numbered steps**.
+- List the **existing functions to reuse or refactor**. Plan thin wrappers, not re-implementations: each operation has one proper place.
+- Plan a clean break. Unused code is removed. Backward compatibility appears only when the user asked for it.
+- **Tests**: look first for existing tests of the kind you consider. Plan tests only when they fit the project's test setup.
+- Leave out sections that add no actionable information: "Benefits", "Code Style Compliance", "Rationale", and the like.
 
 ### 3.2 Single Plan Format
 
 _Use this when writing a single plan. Skip this section for multiple plans._
 
-A single plan has no header with assignment, documentation, or skills — they are listed in the Prerequisites section within the plan body.
+A single plan has no header with assignment, documentation, or skills. They are listed in the Prerequisites section within the plan body.
 
 ### 3.3 Specialized Plan Format
 
 _Use this when writing multiple plans. Skip this section for a single plan._
 
-For specialized plans, add these additional requirements:
+**At the top of each specialized plan**, add a header. Include only the fields that have content. One agent can be assigned to several plans, as separate instances.
 
-**At the top of each specialized plan**, add a header. Only include fields that have content — omit any field with nothing to list. One agent can be assigned to multiple plans (separate instances).
-
-_Note: "Custom agent" refers to configured agent profiles in your environment (e.g., custom agents in Copilot, custom subagents in Claude Code). If your environment doesn't support this, ignore the "Assigned to" field._
+_Note: "Custom agent" refers to configured agent profiles in your environment (custom agents in Copilot, custom subagents in Claude Code). Ignore the "Assigned to" field when your environment has none._
 
 Example:
 
@@ -101,23 +94,23 @@ Example:
 - **Skills**: `skill-a`, `skill-b`
 ```
 
-**In the context section**, explain what you discovered **relevant to this plan's scope** and how it works currently and will work after the task is done **within its scope**.
+**In the context section**, explain what you discovered **within this plan's scope**: how it works today and how it will work after the task.
 
-**In the numbered steps**, include only steps for this plan's work. Each plan should be self-contained.
+**In the numbered steps**, include only this plan's work. Each plan is self-contained.
 
-**Coordination notes**: If this plan depends on another plan, mention it explicitly.
+**Coordination notes**: when this plan depends on another plan, say so explicitly.
 
 ### 3.4 Add a Final Step to Plans
 
-_For all plans (single or specialized)_, add a final step named "Write a Handover Document" with this content:
+For every plan, single or specialized, add a final step named "Write a Handover Document" with this content:
 
 ```markdown
-Write a **handover document**. This document must contain the list of all files you updated. Also, summarize the changes made in a very concise way. Add only relevant information that will help your teammates understand what's new. Do not mention obvious information. It's not a course or a tutorial, if there is nothing to explain, then do not explain. Create its path by replacing the final `.md` in `{PLAN_FILE_PATH}` with `.summary.md`, then write the handover there. Ignore lint errors (formatting issues) in this file. At the end, give the path of this handover file to the user.
+Write a **handover document** for your teammates. List every file you updated, then summarize the changes very concisely. Keep only what helps a teammate understand what is new; leave out the obvious. When there is nothing to explain, explain nothing. Create its path by replacing the final `.md` in `{PLAN_FILE_PATH}` with `.summary.md`, then write the handover there. Ignore lint errors (formatting issues) in this file. At the end, give the path of this handover file to the user.
 ```
 
 Note:
 
-- This is a regular step, it should be numbered like the other steps. For example, if your plan has 5 steps, this becomes step 6.
+- This is a regular step, numbered like the others. A plan with 5 steps gets this one as step 6.
 - Replace "{PLAN_FILE_PATH}" with the complete plan file path, such as `.plans/123/A2-plan-backend.md`. Its handover path is `.plans/123/A2-plan-backend.summary.md`.
 
 ### 3.5 Common Footer for All Plans
@@ -129,21 +122,21 @@ Add the following content to the very end of each plan:
 
 Do not trust this plan blindly. Be sure you understand the codebase and the plan by yourself before applying it.
 
-**IMPORTANT**: Do NOT use external search tools (Context7, web search, documentation fetching) during implementation unless explicitly allowed in this plan. All context should be provided in this plan or discoverable in the codebase.
+Do not use external search tools (Context7, web search, documentation fetching) during implementation unless this plan explicitly allows it. Everything needed is in this plan or discoverable in the codebase.
 ```
 
 ## Phase 4. Main Plan Design
 
-**Create a main plan only when multiple plans are created. Skip this section entirely if not applicable.**
+**Create a main plan only when there are several plans. Skip this section otherwise.**
 
 ### 4.1 Main Plan Guidelines
 
-The main plan coordinates the execution of all specialized plans. It should contain:
+The main plan coordinates the execution of the specialized plans. It contains:
 
-1. **Reference to the specification**: Mention the spec file but do not repeat its content.
-2. **Execution strategy** section: Specify if plans can be executed in parallel or must be sequential, with dependencies clearly noted.
-3. **Plan assignments** section: For each specialized plan, include only applicable fields — assignment, documentation, skills, and a brief description
-4. **Main Handover Document** section
+1. **Reference to the specification**: mention the spec file; do not repeat its content.
+2. **Execution strategy** section: parallel or sequential, with the dependencies stated.
+3. **Plan assignments** section: for each specialized plan, the applicable fields only: assignment, documentation, skills, and a brief description.
+4. **Main Handover Document** section.
 
 Format example:
 
@@ -177,7 +170,7 @@ Execute these specialized plans:
      - `docs/topic-b/doc-3.md`
    - **Description**: [Brief description]
 
-_**Important:** In the prompt you give to the subagent tool, do not reproduce the specialized plan. Instead, provide the file path._
+_In the prompt given to the subagent tool, provide the file path of the specialized plan. Do not reproduce its content._
 
 ### Coordination Notes
 
@@ -185,12 +178,10 @@ _**Important:** In the prompt you give to the subagent tool, do not reproduce th
 
 ## Main Handover Document
 
-Write a **main plan handover document**. This document should:
+Write a **main plan handover document**. This document:
 
-1. Reference each specialized plan's handover file
-2. For each referenced handover:
-   - State "Completed" if the plan was executed successfully
-   - Detail any issues encountered during execution
+1. References each specialized plan's handover file
+2. For each referenced handover, states "Completed" when the plan was executed successfully, and details any issue encountered otherwise
 
 Keep this handover very short. Do not combine or repeat the content of individual handovers. Create its path by replacing the final `.md` in `{PLAN_FILE_PATH}` with `.summary.md`, then write the handover there. Ignore lint errors (formatting issues) in this file.
 
@@ -198,7 +189,7 @@ Keep this handover very short. Do not combine or repeat the content of individua
 
 Do not trust this plan blindly. Be sure you understand the codebase and all specialized plans before coordinating their execution.
 
-**IMPORTANT**: Do NOT use external search tools (Context7, web search, documentation fetching) during implementation unless explicitly allowed in these plans. All context should be provided in these plans or discoverable in the codebase.
+Do not use external search tools (Context7, web search, documentation fetching) during implementation unless these plans explicitly allow it. Everything needed is in these plans or discoverable in the codebase.
 ````
 
 Note:
@@ -224,21 +215,19 @@ Continue the current cycle. Request the file names with `{{TICKET_CMD}} --next`,
 - Specialized plans: `{TICKET_DIR}{CYCLE_LETTER}{FILE_NUMBER}-plan-{DESCRIPTOR}.md`, e.g. `.plans/123/A3-plan-api.md`, `.plans/123/A4-plan-ui.md`. The descriptor is lowercase and hyphenated and names the work scope or stack area.
 - Handovers: replace the final `.md` with `.summary.md`, e.g. `.plans/123/A3-plan-api.summary.md`. The main plan handover is written after all specialized plans complete.
 
-_Important Note: There will be lint errors in the markdown files you write. Ignore them. NEVER FIX LINT ERRORS (FORMATTING ISSUES) IN THE PLANS._
+Ignore Markdown lint errors in the plan files. Fixing them wastes the session.
 
 ## Phase 6. Review
 
-When you think the plan(s) are complete, read them again with a critical eye and edit them to improve them.
-
-Repeat the review until you think all plans are solid.
+When you think the plans are complete, read them again with a critical eye and edit them to improve them. Repeat until every plan is solid.
 
 **Additional review for multiple plans**:
 
 - Each specialized plan is self-contained
 - Each specialized plan header includes only applicable fields (assignment, documentation, skills)
-- The main plan correctly references all specialized plans with their applicable fields
-- Dependencies between plans are clearly documented
+- The main plan references all specialized plans with their applicable fields
+- Dependencies between plans are stated
 
 ---
 
-At the end, give the path of the plan file to the user (for a single plan: the plan file; for multiple plans: the main plan file)
+At the end, give the path of the plan file to the user (for a single plan: the plan file; for multiple plans: the main plan file).

package/templates/guide/protocols/spec.md

@@ -6,68 +6,77 @@ Run `{{TICKET_CMD}}` once to identify TICKET_DIR and load the ticket directory c
 
 ## Phases
 
-When the user asks you for a SPEC (technical specification), you MUST follow this process:
+A specification is produced in three phases, in this order:
 
-1. **Investigation**: Research the codebase to understand the current implementation and identify the problem
-2. **Discussion**: Collaborate with the user to explore the problem space and potential solutions BEFORE writing the specification file
-3. **Specification**: Only after user approval, write the final specification file
+1. **Investigation**: understand the current implementation and the problem.
+2. **Discussion**: align with the user on the problem and the solution.
+3. **Specification**: write the spec file, once the user has approved.
 
-The discussion phase is MANDATORY. Remember that you are a newcomer to this project while the user has extensive experience with the codebase and will be happy to help guide you.
+The usual failure is to write the spec right after investigating. The discussion comes first, every time.
 
 ## Phase 1. Investigation
 
-Check your context for available **documentation** and **skills**. Read every document and skill relevant to any aspect of the task — this is not optional. For each skill, also **read its relevant references**.
+Your context lists the available **documentation** and **skills**. Read every document and skill that applies to any aspect of the task, and the relevant references of each skill. A familiar-looking task tempts you to skip this reading; the project conventions live in these files.
 
-Investigate the codebase yourself, find the relevant source code, think carefully, take the time to understand how it currently works and what has to be done. If the Context7 MCP is available, feel free to use it.
+Find the relevant source code. Take the time to understand how it works today and what has to change. Documentation lookup tools are welcome in this phase.
 
-Always seek a clean break solution by default. Never consider backward compatibility unless explicitly requested.
+Seek a clean break solution by default. Consider backward compatibility only when the user asks for it.
 
 ## Phase 2. Discussion
 
-Engage in a thorough collaborative discussion covering:
+Nothing is written in TICKET_DIR before the user agrees.
 
-- **Problem exploration**: Present your understanding of the problem and ask clarifying questions
-- **Current implementation analysis**: Share what you discovered and ask for confirmation or corrections
-- **Multiple solution approaches**: Present several viable alternatives when they exist, explaining trade-offs
-- **Sub-subject identification**: Break down the problem into all relevant sub-components and ensure each is addressed
-- **Design decisions**: Ask for user input on key architectural choices
-- **Edge cases and implications**: Explore potential issues and broader system impacts
+The user is a developer who carries the global vision of the project and decides the choices that matter. You carry the details of the code you just read. The discussion keeps the user aware of what you found and hands them every decision worth taking.
 
-You should ask questions freely to ensure you fully understand:
+Manage the reader's attention. Open with the task as you understand it and the approach you propose, in two or three sentences. Then write one block per independent decision that needs the user. Write for a reader who has not opened the code today: a function, module or mechanism gets a few words of definition the first time you name it.
 
-- The problem context and requirements
-- Existing patterns and conventions in the codebase
-- User preferences for implementation approaches
-- Any constraints or considerations you might have missed
+A block is a question and a recommendation:
 
-Do not use your question tool. Always ask in plain text. Your questions will be the opportunity for a real discussion.
+```
+❓ **Q1 - <title>**: <the problem in plain words, what the code does today in the words needed to decide, the options with their consequence>
+
+➡️ <your recommendation>
+```
+
+Look for edge cases and impacts on the rest of the system; each one that needs a decision gets its block.
+
+Every decision for the user is a numbered question, a yes/no one included; the simpler it is, the shorter its block. Numbering continues across rounds.
+
+Settle on your own what the code can answer; routine choices belong in the opening approach. Ask the user what needs their judgement: product behavior, scope, priorities, constraints the code does not show. Leave out the investigation narrative and the list of files you read.
+
+Ask in rounds: a question whose answer depends on another question still open waits for the next round. A question the reply skips stays open.
+
+When several approaches are viable, present them with their trade-offs. Check that every sub-subject of the task has its block; a sub-subject skipped here is missing from the spec.
+
+Do not use your question tool. Ask in plain text: your questions open a real discussion, a multiple-choice widget closes it.
 
 ## Phase 3. Specification
 
 After the user approves your proposal, run `{{TICKET_CMD}} --next spec.md --new-cycle` to start a new cycle. Append FILE_NAME to TICKET_DIR, then immediately write the specification at that path. Do not overwrite an existing file.
 
-- After the title, include a suggested commit message {{COMMIT_RULE}}. The shorter the better. Then list the required documentation and skills. List each doc file individually — never a folder. Always exclude `alignfirst` from skills. Omit any field with nothing to list. Example:
+Start with the title, a suggested commit message {{COMMIT_RULE}}, then the required documentation and skills. The shorter the commit message, the better. List each doc file individually, never a folder. Exclude `alignfirst` from the skills. Omit a field with nothing to list.
+
+```text
+# [{TICKET_ID}] Short Title
 
-  ```text
-  # [{TICKET_ID}] Short Title
+Suggested commit message: `<commit message>`
 
-  Suggested commit message: `<commit message>`
+Required Documentation:
 
-  Required Documentation:
+- `docs/topic-a/doc-1.md`
+- `docs/topic-b/doc-2.md`
 
-  - `docs/topic-a/doc-1.md`
-  - `docs/topic-b/doc-2.md`
+Required skills: `skill-1`, `skill-2`
+```
 
-  Required skills: `skill-1`, `skill-2`
-  ```
+Content rules:
 
-- **Do not specify backward compatibility** unless explicitly requested. Prefer clean break by default. Unused code must be removed.
-- A specification is not always immediately executed, and you have to assume that the code can change before it is executed. You can mention a function by name, but NEVER mention specific line numbers as they will become obsolete.
-- Spell out every change to code contracts: database schema and migrations, API shapes, critical type definitions.
-- Do not include other detailed code. Refer to source files by path or function name.
-- Cover the full scope of the task. Never drop parts to shrink the spec — splitting work across plans is handled later by the *plan* protocol. If you anticipate a section should land in a separate plan, flag it inline (e.g. "candidate for a specialized plan").
-- Do not include sections like "Benefits", "Code Style Compliance" or anything that adds no new information. Focus on the problem and the solution.
+- The spec covers the full scope of the task. Dropping a part to shrink the spec is a frequent failure; splitting the work is the job of the *plan* protocol. Flag inline a section that should land in its own plan ("candidate for a specialized plan").
+- Spell out every change to a code contract: database schema and migrations, API shapes, critical type definitions. Leave out other code; refer to source files by path or function name.
+- The code may change before the spec is executed. Name functions, never line numbers.
+- Specify a clean break. Unused code is removed. Backward compatibility appears only when the user asked for it.
+- Leave out sections that add no information: "Benefits", "Code Style Compliance", and the like. Problem and solution only.
 
-_Important Note:_ There will be lint errors in the markdown file you write. Ignore them. NEVER FIX LINT ERRORS (FORMATTING ISSUES) IN THE SPEC.
+Ignore Markdown lint errors in the spec file. Fixing them wastes the session.
 
 At the end, give the path of the spec file to the user.