alignfirst 0.1.0-beta.0

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

@@ -0,0 +1,66 @@
+# Perspective — Change Safety
+
+What this change does to the systems around it: contracts, the database, security, data volume, dependencies.
+
+## Contracts and Compatibility
+
+| Signal | Question | Severity |
+| --- | --- | --- |
+| Public function signature modified | Are all callers in the diff? If not, is the change backward compatible? | 🔴 |
+| Field removed or renamed in an API response, event, or queue message | Does an existing consumer still read it? Does a progressive deployment make both versions coexist? | 🔴 |
+| Field added with a non-null constraint, or stricter validation | Do existing data satisfy the constraint? Do existing clients send the field? | 🔴 |
+| Default value changed | Does the change apply retroactively to existing records or configurations? Is that intended? | 🔴 |
+| Serialization format or cache key changed | Are entries written by the old version readable by the new one — and the reverse, during deployment? | 🔴 |
+| Environment variable or configuration key added | Safe default, or refusal to start without it? Documented in the diff? | 🟡 |
+
+## Database Changes
+
+Migrations and ORM classes deserve particular attention: they are the part of a diff that can break production without breaking a single test.
+
+| Signal | Question | Severity |
+| --- | --- | --- |
+| Schema migration | Is it backward compatible with the currently deployed application version? The rule: code deployed before the migration must keep working during and after it. | 🔴 |
+| Destructive migration (column or table dropped, type changed) | Does it follow an expand / backfill / switch / contract split across deployments, or attempt everything at once? Is a rollback possible without loss? | 🔴 |
+| Migration on a large table | Which lock is taken, for how long? Index created without a concurrent mode, massive `UPDATE` in one pass, type change rewriting the table. | 🔴 |
+| Auto-generated migration | Was it reviewed? Auto-generation regularly produces unwanted drops and re-creations. | 🔴 |
+| ORM model changed | Does it still match the schema after the migration? Are defaults and validations enforced at the same layer as before? | 🔴 |
+
+## Security
+
+| Signal | Question | Severity |
+| --- | --- | --- |
+| New entry point (route, handler, command, job) | Is it under the same authentication as its neighbors? An endpoint added without the neighboring middleware or decorator is the most frequent case. | 🔴 |
+| Resource identified by a client-supplied parameter | Does the caller have the right to **this specific resource**, or only a generic right to the resource type? | 🔴 |
+| Owner, organization, or tenant identifier read from the request | Does it come from a trusted source (session, verified token) or from the client-supplied body/parameters? | 🔴 |
+| Query on a table with a tenancy column | Is the tenancy filter present? An unfiltered query in a partitioned system is a leak. | 🔴 |
+| Query built by string concatenation or interpolation | Are values parameterized? Do dynamic identifiers (table, column, sort direction) go through an allowlist? | 🔴 |
+| External data rendered in an output (HTML, template, document, structured log) | Encoded for the output context? | 🔴 |
+| File path built from user input | Constrained to a base directory after resolution? | 🔴 |
+| Outbound URL built from user input | Destination restricted? Otherwise the application relays into the internal network. | 🔴 |
+| New log, error message, or trace | Does it contain a secret, personal data, a full request body, a token? | 🔴 |
+| Constant that looks like a secret | Hardcoded key, token, password, connection string — including in tests and fixtures. | 🔴 |
+| Deserialization of untrusted data | Does the format allow code execution? | 🔴 |
+| Comparison of a secret, signature, or token | Constant-time comparison? | 🟡 |
+
+## Data and Performance
+
+| Signal | Question | Severity |
+| --- | --- | --- |
+| Query inside a loop, or in a function called in a loop | N+1. Can the loading be batched? | 🔴 |
+| Query without limit or pagination | Is the volume bounded by construction, or only by today's data? | 🔴 |
+| New filter or sort on a column | Does an index exist? Adding the query without the index is a finding. | 🟡 |
+| Open transaction | Does it contain an external network call, a long wait, user interaction? Is its scope as narrow as possible? | 🔴 |
+| Cache added or modified | What is the exact key — does it include every dimension the value depends on (tenancy included)? What is the invalidation? | 🔴 |
+| Whole file, response, or result set loaded in memory | Is the size bounded? | 🟡 |
+| Quadratic algorithm on a hot path | Realistic input size? Quadratic over ten elements is not a finding. | 🟡 |
+| Resource opened (file, connection, lock, subscription) | Released on **all** paths, including exception and early return? | 🔴 |
+
+## New Dependencies
+
+| Signal | Question | Severity |
+| --- | --- | --- |
+| Package added to the manifest | Does it really exist, under exactly this name? Package-name confusion is an active attack vector. | 🔴 |
+| Package added to the manifest | Is it maintained, and is its license compatible with the project? | 🟡 |
+| Package added to the manifest | Is it necessary? Could the standard library or an already-installed dependency do the job? | 🟡 |
+| Manifest changed without the lockfile, or the reverse | — | 🟡 |
+| Dependency moved between runtime and dev dependencies | Is it used at runtime? | 🔴 |

package/templates/guide/core.md

@@ -0,0 +1,54 @@
+# AlignFirst Guide
+
+An agent that does not know which protocol to use runs `{{CMD}} guide overview`.
+
+## Protocols
+
+- **Technical Specification** (_spec_, or _alspec_): `{{CMD}} guide spec --protocol-only`
+- **Implementation Plans** (_plan_, or _alplan_): `{{CMD}} guide plan --protocol-only`
+- **Align-and-Do Protocol** (_AAD_): `{{CMD}} guide aad --protocol-only`
+- **Catch Up** (_catchup_, or _alcatchup_): `{{CMD}} guide catchup --protocol-only`
+- **Merge** (_merge_, or _almerge_): `{{CMD}} guide merge --protocol-only`
+- **Code Review** (_alreview_): `{{CMD}} guide review --protocol-only`
+- **Description** (_aldescription_): `{{CMD}} guide description --protocol-only`
+
+## TASK_DIR Location
+
+**TASK_DIR** is `.plans/{TICKET_ID}/`. Run `{{CMD}} ticket <id>` and use the directory it prints. The command creates a missing directory, restores an archived one, and lists its entries.
+
+{{TICKET_ID_RULE}}
+
+**Work without a ticket:** when the user says there is no ticket, run `{{CMD}} ticket --side`. Reuse an existing `side-N` directory when the user refers to that earlier work. Omit the ticket ID from commit messages.
+
+## File Naming Convention
+
+Format: `{CYCLE_LETTER}{FILE_NUMBER}-{FILE_TYPE}.md`
+
+**Common file types:**
+
+- `spec` - technical specification
+- `plan` - implementation plan
+- `AAD.summary` - AAD summary document
+- `description` - PR/MR description
+- `review` - code review report
+- `merge.summary` - merge conflicts resolution summary
+
+**Example structure:**
+
+```text
+.plans/
+├── 123/
+│   ├── A1-spec.md
+│   ├── A2-plan.md
+│   └── A3-AAD.summary.md
+│   └── B1-spec.md
+```
+
+## Notes
+
+- **TICKET_ID** is a unique identifier for the task, often an issue or ticket number.
+- `{{CMD}} ticket <id> --next <filename>` prints the next filename in the current cycle, the extension included (`--next spec.md` giving `.plans/123/A2-spec.md`).
+- `--new-cycle` starts a new cycle.
+- The protocol or the user decides whether to continue the current cycle or start a new one.
+- Cycle letters and file numbers are internal. Never discuss them with the user.
+- New file types are welcome.

package/templates/guide/overview.md

@@ -0,0 +1,57 @@
+# AlignFirst Overview
+
+AlignFirst is a set of collaborative protocols for working with a user on coding tasks. The two workflows involve **alignment with the user** — investigating, discussing, and agreeing before acting.
+
+## Workflows
+
+### Spec-Plan-Execute (default)
+
+The standard workflow for most tasks. It produces formal artifacts at each stage:
+
+1. **Spec** (`/alspec`): Investigate the codebase, discuss with the user, then write a technical specification. There are usually several back-and-forths before the spec is written.
+2. **Plan** (`/alplan`): Read the spec, investigate further, then write implementation plan(s). The plan is a self-contained prompt for the implementing agent.
+3. **Execute**: A new session implements the plan and writes a handover document summarizing the changes.
+
+After execution, additional rounds of AAD (see below) can address follow-up fixes or adjustments.
+
+### AAD — Align-and-Do (light)
+
+For smaller tasks that don't justify a formal spec and plan. Everything happens in one session: investigate, discuss, implement, summarize.
+
+Use AAD (`/al`) when:
+
+- The task is small or well-understood
+- It's a follow-up change after a plan has already been executed
+- A quick fix or adjustment is needed
+
+Use Spec-Plan-Execute when:
+
+- The task is non-trivial or touches multiple areas
+- There are open design questions that need formal exploration
+- You're unsure — default to Spec-Plan-Execute
+
+## Catch Up
+
+A standalone utility (`/alcatchup`). It loads the ticket's history from its requests, specs, and summaries. It then follows the user's instructions or returns a short synthesis. To continue directly into a light workflow, use `/alcatchup then start an AAD: …`.
+
+## Description
+
+A standalone utility (`/aldescription`). It reads specs and summaries that have been generated for a ticket and produces a concise description of what was implemented. Typically used to generate a PR/MR description once the work is done.
+
+## Code Review
+
+A standalone utility (`/alreview`). It compares the current branch to a base branch (defaults to the repo's default branch) and runs parallel reviewers, each with its own perspective: intent, correctness, change safety, code quality. Ecosystem modules (strict TypeScript, JavaScript, Python) sharpen the language-specific checks. The findings are merged into a concise review report.
+
+## Merge
+
+A standalone utility (`/almerge`). After a merge or rebase, the agent investigates both sides, resolves the conflicts (with a special case for lock files), and writes a brief summary of the resolutions.
+
+## Typical Lifecycle of a Ticket
+
+A ticket usually progresses through:
+
+1. **Spec** — explore and formalize what needs to be done
+2. **Plan** — design how to do it
+3. **Execute** — implement the plan
+4. _(optional)_ **AAD** — address follow-up fixes or small adjustments
+5. **Description** — summarize the implemented work

package/templates/guide/protocols/aad.md

@@ -0,0 +1,85 @@
+# Align-and-Do Protocol (AAD)
+
+## Pre-requisites
+
+You need:
+
+- the TASK_DIR — run `{{CMD}} ticket <id>` (`{{CMD}} ticket` alone deduces the id from the branch when the project defines a ticket format; `{{CMD}} ticket --side` when there is no ticket)
+- the CYCLE_LETTER and FILE_NUMBER — continue the current cycle: `{{CMD}} ticket <id> --next AAD.summary.md` prints the file to create
+
+Identify and state these values before starting the protocol.
+
+---
+
+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**.
+
+Explore the codebase. Take the time to understand how it currently works and what needs to change.
+
+Always seek a clean break solution by default. Never consider backward compatibility unless explicitly requested.
+
+## 2. Discuss
+
+Present your findings and proposed approach. Ask clarifying questions. Explore trade-offs and edge cases.
+
+**Remember**: This discussion happens BEFORE any implementation or formal specification writing.
+
+Engage in a thorough collaborative discussion covering:
+
+- **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
+
+You're new to this project, the user can guide you.
+
+Do not use your question tool. Always ask in plain text. Your questions will be the opportunity for a real discussion.
+
+**This phase is mandatory.** If there is nothing to discuss, ask the user for an explicit validation.
+
+## 3. Act
+
+When you and the user agree, create the summary file in TASK_DIR, then start implementing.
+
+Compose the filename using the current CYCLE_LETTER and the bumped FILE_NUMBER, then append `-AAD.summary.md`. For example, if the last file is `E5-plan-something.md`, create `E6-AAD.summary.md`. Do not overwrite an existing file.
+
+Maintain the file as a **live report** while you work.
+
+Use subagents (your subagent tool) for distinct, isolated units of work when beneficial.
+
+## 4. Summarize
+
+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 (follow the convention you are aware of, or default to `<type>: [<ticket_id>] very short description`). The shorter the better. Omit any field with nothing to list. Always exclude `alignfirst` from skills.
+
+Example:
+
+```markdown
+# AAD Summary - [very short title]
+
+Suggested commit message: `<commit message>`
+
+Used documentation:
+
+- `docs/topic-a/doc-1.md`
+- `docs/topic-b/doc-2.md`
+
+Used skills: `skill-a`, `skill-b`
+```
+
+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)
+- Key outcomes or next steps
+
+The shorter the better.
+
+_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/catchup.md

@@ -0,0 +1,13 @@
+# How to Catch Up With a Task
+
+## Pre-requisites
+
+You need the TASK_DIR — run `{{CMD}} ticket <id>` (`{{CMD}} ticket` alone deduces the id from the branch when the project defines a ticket format; `{{CMD}} ticket --side` when there is no ticket).
+
+## Steps
+
+1. Determine TASK_DIR.
+2. Read every `*request.md`, `*spec.md` and `*summary.md` file in TASK_DIR, in filename order.
+3. When the user's message carries instructions, follow them with this context loaded, and write no synthesis. Otherwise reply with a short synthesis: what was requested, what was decided, what was done, what remains or is open.
+
+This protocol writes no file.

package/templates/guide/protocols/description.md

@@ -0,0 +1,51 @@
+# How to Write a Description for Implemented Work
+
+## Pre-requisites
+
+You need:
+
+- the TASK_DIR — run `{{CMD}} ticket <id>` (`{{CMD}} ticket` alone deduces the id from the branch when the project defines a ticket format; `{{CMD}} ticket --side` when there is no ticket)
+- the CYCLE_LETTER and FILE_NUMBER — start a new cycle: `{{CMD}} ticket <id> --next description.md --new-cycle` prints the file to create
+
+Identify and state these values before starting the protocol.
+
+## Steps
+
+1. Find the current ticket plan directory.
+2. Create your description as a new file `{CYCLE_LETTER}1-description.md` with the next cycle letter, containing just the header — this reserves the filename.
+3. If a previous `*description.md` file exists in the TASK_DIR, find the latest one. Only read `*spec.md` and `*summary.md` files that come *after* it — earlier work is already covered.
+   Otherwise, read all `*spec.md` and `*summary.md` files.
+4. Write the commit message and description into your file.
+
+## Output Format
+
+```md
+# Description - [very short title]
+
+**Suggested commit message:** `<commit message>`
+
+## PR/MR Description
+
+[description body]
+```
+
+Start with a suggested commit message (follow the convention you are aware of, or default to `<type>: [<ticket_id>] very short description`). 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 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).
+- 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 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

@@ -0,0 +1,65 @@
+# How to Resolve Merge Conflicts
+
+## Pre-requisites
+
+You need:
+
+- the TASK_DIR — run `{{CMD}} ticket <id>` (`{{CMD}} ticket` alone deduces the id from the branch when the project defines a ticket format; `{{CMD}} ticket --side` when there is no ticket)
+- the CYCLE_LETTER and FILE_NUMBER — continue the current cycle: `{{CMD}} ticket <id> --next merge.summary.md` prints the file to create
+
+Identify and state these values before starting the protocol.
+
+---
+
+This protocol applies when a merge or rebase has produced conflicts, or when the user provides an incoming branch to merge. Follow the steps below.
+
+## 1. Check git status
+
+Run `git status` to check for conflicts.
+
+**If there are no conflicts:** start the merge — use the incoming branch if the user provided one, otherwise ask which branch to merge. If the merge completes cleanly, you are done — no summary file needed. Otherwise, continue with the steps below.
+
+## 2. Investigate
+
+Take the time to understand how things work in the incoming branch and in the current branch. For each conflicting file, read enough surrounding context to understand the intent on both sides.
+
+## 3. Resolve
+
+Create the summary file now: a new file `{CYCLE_LETTER}{FILE_NUMBER}-merge.summary.md` in the TASK_DIR. 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.
+
+**Special case for lock files:** If a lock file has conflicts:
+
+1. Accept all the changes from the incoming branch.
+2. After all other conflicts are resolved, run the proper install command so the package manager re-applies the current branch's dependency changes.
+
+## 4. Finalize the merge
+
+Finalize the merge using git's default commit message (e.g. `git commit --no-edit`). Do not write your own commit message — git has already prepared the proper merge message.
+
+## 5. Summarize
+
+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.
+
+Example:
+
+```markdown
+# Merge Summary - [very short title]
+
+## Notable resolutions
+
+- `path/to/file.ts`: [what made it tricky and which choice was made, in one or two sentences]
+
+## Lock file
+
+[Only if there was a lock file conflict: which lock file, which install command was run]
+```
+
+Omit any section with nothing to report.
+
+_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

@@ -0,0 +1,256 @@
+# How to Write Implementation Plans
+
+## Pre-requisites
+
+### Determine TASK_DIR, CYCLE_LETTER, and FILE_NUMBER
+
+You need:
+
+- the TASK_DIR — run `{{CMD}} ticket <id>` (`{{CMD}} ticket` alone deduces the id from the branch when the project defines a ticket format; `{{CMD}} ticket --side` when there is no ticket)
+- the CYCLE_LETTER and FILE_NUMBER — continue the current cycle: `{{CMD}} ticket <id> --next plan.md` or `{{CMD}} ticket <id> --next main-plan.md` prints the file to create
+- a **spec file** in the TASK_DIR
+
+Identify and state these values before starting the protocol. If any of these pieces of information is missing, STOP AND ASK THE USER.
+
+## Phases
+
+Before starting, **read the spec file** and understand it entirely.
+
+In order to generate implementation plans, you MUST follow this process:
+
+1. **Investigation Phase**: Explore the codebase, understand the current implementation, and identify the problem
+2. **Analysis Phase**: Determine the plan structure (single or multiple plans) and identify relevant documentation and skills
+3. **Designing Phase - Implementation Plan(s)**: Design plan(s) based on the analysis - If you discover issues or missing design decisions, STOP AND ASK THE USER
+4. **Designing Phase - Main Plan**: If multiple plans, design a main plan to coordinate them
+5. **Writing Phase**: Write the plan file(s)
+6. **Review Phase**: Critically review and improve the plan(s)
+
+## Phase 1. Investigation Phase
+
+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**.
+
+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.
+
+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 existing functions that do a similar job.
+
+## Phase 2. Analysis Phase
+
+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:
+
+- **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
+
+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. Designing Phase - Implementation Plan Structure
+
+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
+
+Follow these guidelines for all plans (single or specialized):
+
+- 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.
+
+### 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. 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:
+
+```markdown
+# Specialized Plan - [Short Title Here]
+
+- **Assigned to**: `agent-name`
+- **Documentation**:
+  - `docs/topic-a/relevant-doc.md`
+  - `docs/topic-b/other-doc.md`
+- **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 numbered steps**, include only steps for this plan's work. Each plan should be self-contained.
+
+**Coordination notes**: If this plan depends on another plan, mention it 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:
+
+```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. Write this handover document in `{PLAN_FILE_PATH}.summary.md`. 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.
+- Replace "{PLAN_FILE_PATH}" with the actual plan file path without extension (e.g., for plan `.plans/123/A2-plan-backend.md`, use `.plans/123/A2-plan-backend`, resulting in `.plans/123/A2-plan-backend.summary.md`).
+
+### 3.5 Common Footer for All Plans
+
+Add the following content to the very end of each plan:
+
+```markdown
+---
+
+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.
+```
+
+## Phase 4. Designing Phase - Main Plan
+
+**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 all specialized plans. It should contain:
+
+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:
+
+````markdown
+# Main Plan - [Short Title Here]
+
+This main plan coordinates the implementation of [reference spec file].
+
+## Execution Strategy
+
+**Parallel execution possible**: Plans A3, A4, and A5 are independent and can be executed simultaneously.
+
+OR
+
+**Sequential execution required**: A3 must complete before A4 (A4 depends on API endpoints from A3).
+
+## Plan Assignments
+
+Execute these specialized plans:
+
+1. **Plan A** (`A3-plan-xxx.md`)
+   - **Assigned to**: `agent-name`
+   - **Documentation**:
+     - `docs/topic-a/doc-1.md`
+     - `docs/topic-b/doc-2.md`
+   - **Skills**: `skill-a`, `skill-b`
+   - **Description**: [Brief description]
+
+2. **Plan B** (`A4-plan-yyy.md`)
+   - **Documentation**:
+     - `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._
+
+### Coordination Notes
+
+[Any important notes about how the plans interact, if applicable]
+
+## Main Handover Document
+
+Write a **main plan handover document**. This document should:
+
+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. Write this document in `{PLAN_FILE_PATH}.summary.md`. Ignore lint errors (formatting issues) in this file.
+
+---
+
+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.
+````
+
+Note:
+
+- Replace "{PLAN_FILE_PATH}" with the actual plan file path without extension (e.g., for plan `.plans/123/A2-main-plan.md`, use `.plans/123/A2-main-plan`, resulting in `.plans/123/A2-main-plan.summary.md`)
+
+## Phase 5. Writing Phase
+
+Write the plan file(s) according to the determined structure:
+
+Use `{{CMD}} ticket <id> --next plan.md`, `{{CMD}} ticket <id> --next main-plan.md`, or `{{CMD}} ticket <id> --next plan-<descriptor>.md` to get the next number. Run one command per file.
+
+**Single Plan**:
+
+- **Single plan**: `{TASK_DIR}/{CYCLE_LETTER}{FILE_NUMBER}-plan.md`
+  - Example: `.plans/123/A2-plan.md`
+  - Handover: `.plans/123/A2-plan.summary.md`
+  - No main plan needed
+
+**Multiple Plans**:
+
+- **Main plan**: `{TASK_DIR}/{CYCLE_LETTER}{FILE_NUMBER}-main-plan.md`
+  - Example: `.plans/123/A2-main-plan.md`
+  - Handover: `.plans/123/A2-main-plan.summary.md` (written after all specialized plans complete)
+- **Specialized plans**: `{TASK_DIR}/{CYCLE_LETTER}{FILE_NUMBER}-plan-{DESCRIPTOR}.md`
+  - Use a descriptive name as `{DESCRIPTOR}` (e.g., work scope, stack area)
+  - Example: `.plans/123/A3-plan-api.md`, `.plans/123/A4-plan-ui.md`
+  - Handovers: `.plans/123/A3-plan-api.summary.md`, etc.
+
+**Important**:
+
+- Increment FILE_NUMBER for each plan file
+- Use lowercase, hyphenated descriptors for plan names (work scope descriptor)
+- When multiple plans are created, the main plan should be written first and have the lowest FILE_NUMBER
+- Be careful never to overwrite an existing file
+
+_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 Phase
+
+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 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)