alignfirst 0.4.0 → 0.6.0-preview.0

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,75 @@ 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 point that deserves a decision. 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.
+
+A ❓ is open: the user's answer shapes what you build. When the only answers are go or veto, the block shrinks to a single ➡️ line stating your choice. The more obvious the choice, the shorter the line. Leave out the investigation narrative and the list of files you read.
+
+Settle on your own what the code can answer. Ask the user what needs their judgement: product behavior, scope, priorities, constraints the code does not show. Every ❓ carries a ➡️, so that "fine with all recommendations" is a valid answer. Ask in rounds: a question whose answer depends on another question still open waits for the next round.
+
+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.