alignfirst 0.6.0-preview.1 → 0.6.0

package/README.md

@@ -81,6 +81,12 @@ Use your alignfirst-setup-guide skill. What AlignFirst tooling could we add in t
 
 The guide installs the selected components and configures the repository. You can remove the setup-guide skill once setup is complete.
 
+To leave the repository untouched, the guide keeps the project's AlignFirst files in a [companion directory](#companion-directories):
+
+```text
+Use your alignfirst-setup-guide skill. Set up AlignFirst in this project without touching the repository.
+```
+
 ## CLI commands
 
 - `guide` — Print an AlignFirst protocol.
@@ -101,11 +107,10 @@ Run `alignfirst --help` for command usage or `alignfirst guide` to choose a prot
 
 ## Companion directories
 
-A companion directory holds a project's AlignFirst files outside its repository, so the repository stays untouched. `~/.config/alignfirst/companions.json` declares which projects have one:
+A companion directory holds a project's AlignFirst files outside its repository, so the repository stays untouched. `~/.alignfirst/companions.json` declares which projects have one:
 
 ```json
 {
-  "root": "~/alignfirst-companions",
   "paths": {
     "~/projects/team-app": { ".plans": false, "_aligndev": true },
     "~/projects/client-api": {},
@@ -114,7 +119,6 @@ A companion directory holds a project's AlignFirst files outside its repository,
 }
 ```
 
-- `root` — the directory that holds the companion directories: an absolute path or a `~/` path.
 - `paths` — the projects, by absolute or `~/` path. Each value sets flags for the items a companion can hold: `.alignfirst.json`, `.alignfirst.md`, `DEVELOPERS.md`, `docs`, `.plans` and `_aligndev`. A flag is `true`, `false` or `"auto"`.
 
 An absent file means no project has a companion. An invalid file makes every command fail; `doctor` reports it and continues.
@@ -123,7 +127,7 @@ An absent file means no project has a companion. An invalid file makes every com
 
 A key matches a project when it names the project's main worktree or one of its ancestors, so every worktree of a project shares one companion. `"~": {}` matches every project under the home directory. For each item, the longest matching key that sets the flag wins, and an unset flag is `"auto"`. A bare repository or a directory outside git has no companion.
 
-The companion directory is `<root>/<name>`. The name is the main worktree path relative to the home directory, or the absolute path without its leading `/` outside it, with every `/` replaced by `_`. For example, `~/projects/client-api` gets `<root>/projects_client-api/`.
+The companion directory is `~/.alignfirst/companions/<name>`. The name is the main worktree path relative to the home directory, or the absolute path without its leading `/` outside it, with every `/` replaced by `_`. For example, `~/projects/client-api` gets `~/.alignfirst/companions/projects_client-api/`. To keep the companions elsewhere, make `~/.alignfirst/companions` a symlink.
 
 ### Resolution
 
@@ -146,7 +150,7 @@ The companion directory is `<root>/<name>`. The name is the main worktree path r
 An agent reads a repository's `AGENTS.md` on its own, but never a companion. When your repositories carry no AlignFirst instructions, add this line to your global agent instructions (`~/.claude/CLAUDE.md`, `~/.codex/AGENTS.md`, or the equivalent):
 
 ```text
-In a git repository, run `alignfirst context` once before investigating, unless the project's instructions already say so.
+In a git repository, run `alignfirst context` as your first command, whatever the task, unless the project's instructions already say so.
 ```
 
 ## Upgrade from v1, v2, or v3

package/dist/project-layout.js

@@ -12,6 +12,8 @@ export const ITEM_NAMES = [
     ".plans",
     "_aligndev",
 ];
+// The directory holding the companions. A symlink there moves them elsewhere.
+const COMPANIONS_ROOT = "~/.alignfirst/companions";
 const FLAG = "boolean | 'auto'";
 const flagsSchema = type({
     "+": "reject",
@@ -24,7 +26,6 @@ const flagsSchema = type({
 });
 const companionsSchema = type({
     "+": "reject",
-    root: "string > 0",
     paths: type.Record("string", flagsSchema),
 });
 export function layoutOf(ctx) {
@@ -48,7 +49,7 @@ function resolveCompanion(cwd, home) {
         return null;
     const flags = mergeFlags(matches);
     assertValidFlags(file, flags, matches);
-    const dir = join(normalizePath(file.root, realHome), companionName(mainWorktree, realHome));
+    const dir = join(normalizePath(COMPANIONS_ROOT, realHome), companionName(mainWorktree, realHome));
     return { dir, exists: pathExists(dir), entries: matches.map((match) => match.key), flags };
 }
 function readCompanionsFile(home) {
@@ -65,15 +66,13 @@ function readCompanionsFile(home) {
     const file = companionsSchema(value);
     if (file instanceof type.errors)
         throw invalidCompanions(path, file.summary.split("\n", 1)[0]);
-    if (!isUserPath(file.root))
-        throw invalidCompanions(path, `root must be an absolute path or start with ~/: ${file.root}`);
     const badKey = Object.keys(file.paths).find((key) => !isUserPath(key));
     if (badKey !== undefined)
         throw invalidCompanions(path, `paths key must be an absolute path or start with ~/: ${badKey}`);
-    return { path, root: file.root, paths: file.paths };
+    return { path, paths: file.paths };
 }
 export function companionsPath(home) {
-    return join(home, ".config", "alignfirst", "companions.json");
+    return join(home, ".alignfirst", "companions.json");
 }
 function invalidCompanions(path, detail) {
     return new CliError(`Invalid ${path}: ${detail}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "alignfirst",
-  "version": "0.6.0-preview.1",
+  "version": "0.6.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,7 +38,6 @@ 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? 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.
+   - Is the size proportionate to the intent? 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,8 +16,6 @@ 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
 
@@ -54,4 +52,3 @@ 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,8 +10,6 @@ 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,39 +10,30 @@ This is a 4-step protocol. Follow each step in order.
 
 ## 1. Investigate
 
-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.
+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**.
 
-Explore the codebase. Take the time to understand how it works today and what needs to change.
+Explore the codebase. Take the time to understand how it currently works and what needs to change.
 
-Seek a clean break solution by default. Consider backward compatibility only when the user asks for it.
+Always seek a clean break solution by default. Never consider backward compatibility unless explicitly requested.
 
 ## 2. Discuss
 
-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.
+Present your findings and proposed approach. Ask clarifying questions. Explore trade-offs and edge cases.
 
-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.
+**Remember**: This discussion happens BEFORE any implementation or formal specification writing.
 
-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.
+Engage in a thorough collaborative discussion covering:
 
-A block is a question and a recommendation:
+- **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
 
-```
-❓ **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.
+You're new to this project, the user can guide you.
 
-When there is nothing to decide, say so in a few lines and ask for an explicit go.
+Do not use your question tool. Always ask in plain text. Your questions will be the opportunity for a real discussion.
 
-Do not use your question tool. Ask in plain text: your questions open a real discussion, a multiple-choice widget closes it.
+**This phase is mandatory.** If there is nothing to discuss, ask the user for an explicit validation.
 
 ## 3. Act
 
@@ -56,7 +47,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. Exclude `alignfirst` from the 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. Always exclude `alignfirst` from skills.
 
 Example:
 
@@ -73,15 +64,15 @@ Used documentation:
 Used skills: `skill-a`, `skill-b`
 ```
 
-The finalized summary is a **very concise handover document**. It captures:
+The finalized summary is a **very concise handover document** that should capture:
 
 - 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 to 5 words for the description part. Shorter is better when it stays 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-5 words for the description part. Shorter is better when it's 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 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.
+- **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.
 - Include technical details only for major structural changes (e.g., renaming a database table, significant linter config changes, major codebase refactors).
-- 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.
+- 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.
 
 ---
 
-Ignore Markdown lint errors in the description file.
+_Ignore lint errors (formatting issues) 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}} A merge that completes cleanly ends the protocol, with no summary file. 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}} If the merge completes cleanly, you are done — no summary file needed. 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).
 
-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 the conflicts properly — preserve both intents whenever possible. Do not blindly accept one side.
 
-Resolve conflicts one at a time. Batch processing, broad search-and-replace and other brute-force edits are out.
+Resolve conflicts one at a time. Avoid batch processing, broad search-and-replace operations, and other brute-force edits.
 
 **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.** 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.
+**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.
 
 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,85 +2,92 @@
 
 ## 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
 
-Without a spec file, stop and ask the user.
+Identify TICKET_DIR and the spec file before starting the protocol. If either is missing, STOP AND ASK THE USER.
 
 ## Phases
 
-Read the spec file entirely before starting. Then plan in six phases, in this order:
+Before starting, **read the spec file** and understand it entirely.
 
-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.
+In order to generate implementation plans, you MUST follow this process:
 
-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.
+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)
 
 ## Phase 1. Investigation
 
-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.
+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**.
 
-Find the relevant source code. Take the time to understand how it works today and what has to change.
+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.
 
-The spec is the starting point, and it was written against an earlier state of the code. Verify each statement against the current implementation.
+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.
 
-For each operation in the spec, search for an existing function that does a similar job.
+For each operation in the spec, search for existing functions that do a similar job.
 
 ## Phase 2. Analysis
 
-### 2.1 Assess Work Scopes
-
-Prefer a single plan when the work fits one session, especially when it stays within one area.
+Based on your investigation, determine the plan structure:
 
-Split complex work into specialized plans, coordinated by a main plan. Split along:
+### 2.1 Assess Work Scopes
 
-- **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.
+Evaluate if the work should be split into multiple specialized plans or handled as a single plan:
 
-Each specialized plan produces a coherent deliverable.
+- **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**
 
 ### 2.2 Identify Relevant Documentation and Skills
 
-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.
+Identify which **documentation** and **skills** are relevant for the work. Omit if none apply.
+
+- 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
 
 ## Phase 3. Plan Design
 
-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.
+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.
 
 ### 3.1 Plan Content Guidelines
 
-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.
+Follow these guidelines for all plans (single or specialized):
 
-- 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.
+- 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.
 
 ### 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._
 
-**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.
+For specialized plans, add these additional requirements:
 
-_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._
+**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._
 
 Example:
 
@@ -94,23 +101,23 @@ Example:
 - **Skills**: `skill-a`, `skill-b`
 ```
 
-**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 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 numbered steps**, include only this plan's work. Each plan is self-contained.
+**In the numbered steps**, include only steps for this plan's work. Each plan should be self-contained.
 
-**Coordination notes**: when this plan depends on another plan, say so explicitly.
+**Coordination notes**: If this plan depends on another plan, mention it explicitly.
 
 ### 3.4 Add a Final Step to Plans
 
-For every plan, single or specialized, add a final step named "Write a Handover Document" with this content:
+_For all plans (single or specialized)_, add a final step named "Write a Handover Document" with this content:
 
 ```markdown
-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.
+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.
 ```
 
 Note:
 
-- This is a regular step, numbered like the others. A plan with 5 steps gets this one as step 6.
+- 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.
 - 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
@@ -122,21 +129,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.
 
-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.
+**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.
 ```
 
 ## Phase 4. Main Plan Design
 
-**Create a main plan only when there are several plans. Skip this section otherwise.**
+**Create a main plan only when multiple plans are created. Skip this section entirely if not applicable.**
 
 ### 4.1 Main Plan Guidelines
 
-The main plan coordinates the execution of the specialized plans. It contains:
+The main plan coordinates the execution of all specialized plans. It should contain:
 
-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.
+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
 
 Format example:
 
@@ -170,7 +177,7 @@ Execute these specialized plans:
      - `docs/topic-b/doc-3.md`
    - **Description**: [Brief description]
 
-_In the prompt given to the subagent tool, provide the file path of the specialized plan. Do not reproduce its content._
+_**Important:** In the prompt you give to the subagent tool, do not reproduce the specialized plan. Instead, provide the file path._
 
 ### Coordination Notes
 
@@ -178,10 +185,12 @@ _In the prompt given to the subagent tool, provide the file path of the speciali
 
 ## Main Handover Document
 
-Write a **main plan handover document**. This document:
+Write a **main plan handover document**. This document should:
 
-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
+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
 
 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.
 
@@ -189,7 +198,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.
 
-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.
+**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.
 ````
 
 Note:
@@ -215,19 +224,21 @@ 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.
 
-Ignore Markdown lint errors in the plan files. Fixing them wastes the session.
+_Important Note: There will be lint errors in the markdown files you write. Ignore them. NEVER FIX LINT ERRORS (FORMATTING ISSUES) IN THE PLANS._
 
 ## Phase 6. Review
 
-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.
+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.
 
 **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 references all specialized plans with their applicable fields
-- Dependencies between plans are stated
+- The main plan correctly references all specialized plans with their applicable fields
+- Dependencies between plans are clearly documented
 
 ---
 
-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,77 +6,68 @@ Run `{{TICKET_CMD}}` once to identify TICKET_DIR and load the ticket directory c
 
 ## Phases
 
-A specification is produced in three phases, in this order:
+When the user asks you for a SPEC (technical specification), you MUST follow this process:
 
-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.
+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
 
-The usual failure is to write the spec right after investigating. The discussion comes first, every time.
+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.
 
 ## Phase 1. Investigation
 
-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.
+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**.
 
-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.
+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.
 
-Seek a clean break solution by default. Consider backward compatibility only when the user asks for it.
+Always seek a clean break solution by default. Never consider backward compatibility unless explicitly requested.
 
 ## Phase 2. Discussion
 
-Nothing is written in TICKET_DIR before the user agrees.
+Engage in a thorough collaborative discussion covering:
 
-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.
+- **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
 
-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.
+You should ask questions freely to ensure you fully understand:
 
-A block is a question and a recommendation:
+- 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
 
-```
-❓ **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.
+Do not use your question tool. Always ask in plain text. Your questions will be the opportunity for a real discussion.
 
 ## 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.
 
-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
+- 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:
 
-Suggested commit message: `<commit message>`
+  ```text
+  # [{TICKET_ID}] Short Title
 
-Required Documentation:
+  Suggested commit message: `<commit message>`
 
-- `docs/topic-a/doc-1.md`
-- `docs/topic-b/doc-2.md`
+  Required Documentation:
 
-Required skills: `skill-1`, `skill-2`
-```
+  - `docs/topic-a/doc-1.md`
+  - `docs/topic-b/doc-2.md`
 
-Content rules:
+  Required skills: `skill-1`, `skill-2`
+  ```
 
-- 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.
+- **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.
 
-Ignore Markdown lint errors in the spec file. Fixing them wastes the session.
+_Important Note:_ There will be lint errors in the markdown file you write. Ignore them. NEVER FIX LINT ERRORS (FORMATTING ISSUES) IN THE SPEC.
 
 At the end, give the path of the spec file to the user.