/writing-plans

name: writing-plans
description: "Use when you have an approved spec or written requirements for a multi-step task that needs a durable plan document before touching code. Small, single-owner, or fast-path tasks do not need this skill."

<EXPLICIT-MODE-GATE> If activation mode is explicit (`~/.config/aegis/config.toml` has `activation_mode = "explicit"`, or `AEGIS_ACTIVATION_MODE=explicit` is visible in the environment) and the current user request did not explicitly invoke Aegis or this skill by name, exit back to the fast path: answer concisely without this workflow's checklist, ceremony, or document requirements. If the user explicitly named Aegis or this skill, proceed normally. </EXPLICIT-MODE-GATE>

Execute

→ Have an existing parent plan/spec and a tiny execution slice? → **Use Planless Slice Lane.** 1. Emit a compact Slice Card: goal, parent plan/spec, files, boundary, verification, stop 2. Update the parent workstream checkpoint/evidence/drift state if persistent state is needed 3. Do not save a new plan for the micro-slice → Mechanical or bounded change with no durable boundary (no new owner, contract, schema, public API, migration, or compat surface)? → **Use Planless Slice Lane without a parent document.** Emit the compact Slice Card, skip the plan file, and record the change in the commit message. → Have approved spec/requirements for a new workstream or an escalation trigger? → **Write implementation plan. Assume engineer has zero context.** 1. Scope check: fact/assumption/unknown, baseline, Requirement Ready Check, Ripple Signal Triage, compatibility boundary, dual-track needs 2. File map: what files created/modified, clear boundaries, follow existing patterns 3. Bite-sized tasks (2-5 min each): exact file paths, complete code, exact commands, expected output 4. Self-review: spec coverage, placeholders, type consistency, compatibility, verification, dual-track 5. Save → select and announce the execution route; proceed unless a real authorization or safety boundary requires the user → Plan must answer: problem, baseline, files, compat, verification, risks, retirement. → Escalate from Planless Slice Lane to a durable plan when the slice adds a new owner, contract, schema, public API, architecture boundary, migration, persistence, security/permission, distribution/release surface, or unclear verification boundary.

Writing Plans

Overview

Write comprehensive implementation plans assuming the engineer has zero context for our codebase and questionable taste. Document everything they need to know: which files to touch for each task, code, testing, docs they might need to check, how to test it. Give them the whole plan as bite-sized tasks. DRY. YAGNI. Chosen TDD route. One verified commit per coherent Task or slice.

Assume they are a skilled developer, but know almost nothing about our toolset or problem domain. Assume they don't know good test design very well.

This skill is the canonical planning workflow for multi-step implementation work. Use it to convert approved specs or requirements into plans that are executable, testable, impact-aware, and bounded by compatibility and authority constraints.

Strict RED / GREEN steps belong only to an explicit user/project TDD request or `TDD Route: strict`. With TDD mode `off` and no strict route, plan the minimum implementation and proportional regression/verification steps; do not prescribe a TDD cycle from risk alone.

TDD Route Guard

Before task decomposition, every plan that includes implementation work must record:

TDD Route:
- Mode: off | auto
- Decision: strict | light | skipped
- Strict authority: explicit user/project request | recorded auto decision | not applicable
- Test posture: diagnostic reproduction | post-change regression | strict RED test
- Reason:
- Verification:

In `off`, record `Decision: skipped` unless an explicit user/project strict request overrides it. The record makes the boundary reviewable; it does not load `test-driven-development`. An approved plan, bug label, architecture risk, contract risk, or shared-module label is not strict authority.

Only `Decision: strict` with stated strict authority may prescribe `Write failing test`, `Verify RED`, `GREEN`, or `REFACTOR` as task steps. Otherwise, write the minimum change plus diagnostic reproduction or post-change regression as appropriate. In `auto`, if the plan lacks a recorded decision, return to route selection before writing implementation tasks; never infer `strict` during decomposition.

**Announce at start:** "I'm using the writing-plans skill to create the implementation plan."

**Execution context:** Reuse the current branch/workspace by default. A branch needs independent history; a worktree needs concurrent checkout, blocking unrelated dirty state, or explicit user/repository authority.

**Input:** approved requirements, a Spec Brief, or a Design Spec.

**Save plans to:** `docs/aegis/plans/YYYY-MM-DD-<feature-name>.md` Plan always goes to `plans/` — never to `work/`. (User preferences for plan location override this default.)

Exception: if an existing parent plan/spec already owns the current tiny execution slice, use `Planless Slice Lane`. Do not save a new plan. Emit a compact `Slice Card` in the conversation or the active long-task checkpoint instead:

Slice Card:
- Goal:
- Parent plan/spec:
- Files:
- Boundary:
- Verification:
- Stop:

If `docs/aegis/` does not exist and configured Aegis workspace support is available, initialize the target project first:

python <aegis-workspace-helper> init --root <target-project-root>

Project authority overrides workspace initialization. In particular, the Aegis Method Pack repository must not create or ship a live `docs/aegis/` workspace; use its formal `docs/adr/`, `docs/current/`, and active session plan.

If installed Aegis workspace support is unavailable, initialize the workspace manually: 1. Create `docs/aegis/READ