--- name: aif-plan description: Plan implementation for a feature or task. Two modes — fast (single quick plan) or full (richer plan with optional git branch/worktree flow). Use when user says "plan", "new feature", "start feature", "create tasks". argument-hint: "[fast | full] [--parallel | --list | --cleanup ] " allowed-tools: Read Write Glob Grep Bash(git *) Bash(cd *) Bash(cp *) Bash(mkdir *) Bash(basename *) TaskCreate TaskUpdate TaskList AskUserQuestion Questions Task mcp__handoff__handoff_sync_status mcp__handoff__handoff_push_plan mcp__handoff__handoff_get_task mcp__handoff__handoff_list_tasks mcp__handoff__handoff_update_task disable-model-invocation: false version: 1.0.0 --- # Plan - Implementation Planning Create an implementation plan for a feature or task. Two modes: - **Fast** – quick plan, no git branch, saves to the configured fast plan path (default: `.ai-factory/PLAN.md`) - **Full** — richer plan, asks preferences, saves to the configured full-plan directory, and optionally creates a git branch/worktree when git is enabled and branch creation is allowed ## Workflow ### Step 0 (pre): Detect Handoff Mode Determine Handoff mode, task ID, and branch contract. Resolve each value independently so legacy callers that pass only `HANDOFF_MODE` and `HANDOFF_TASK_ID` still enter Handoff mode correctly: - `HANDOFF_MODE`: explicit prompt value if present; otherwise environment value; otherwise empty string. - `HANDOFF_TASK_ID`: explicit prompt value if present; otherwise environment value; otherwise empty string. - `HANDOFF_BRANCH_PREPARED`: explicit prompt value if present; otherwise environment value; otherwise `0`. - `HANDOFF_BRANCH_NAME`: explicit prompt value if present; otherwise environment value; otherwise empty string. Use the Bash tool only for values that were not passed explicitly in the prompt: ``` Bash: printenv HANDOFF_MODE || true Bash: printenv HANDOFF_TASK_ID || true Bash: printenv HANDOFF_BRANCH_PREPARED || true Bash: printenv HANDOFF_BRANCH_NAME || true ``` **Then check `HANDOFF_MODE`:** #### When `HANDOFF_MODE` is `1` (autonomous Handoff agent) The Handoff coordinator already manages status transitions and DB writes directly. Do NOT call MCP tools (`handoff_sync_status`, `handoff_push_plan`). Instead: - **No interactive questions:** Do not use `AskUserQuestion` — use sensible defaults (verbose logging, yes to tests, yes to docs, skip roadmap linkage). - **Mode default:** If mode is not specified, default to `fast`. - **Plan annotation (MANDATORY):** If `HANDOFF_TASK_ID` is non-empty, you MUST insert `` as the very first line of the plan file, before the title. This annotation links the plan to its Handoff task for bidirectional sync. **Omitting this annotation when HANDOFF_TASK_ID is set is a bug — verify before completing.** ##### Branch ownership under Handoff (CRITICAL) Handoff owns branch creation at the agent-code level. The skill must NOT create or switch branches when Handoff has prepared one. Apply these rules: **If `HANDOFF_BRANCH_PREPARED` is `1`:** - Do **NOT** execute `git checkout`, `git pull`, or `git checkout -b`. - Treat `--parallel` as disabled for all downstream behavior. - Do **NOT** create a worktree. - Read `HANDOFF_BRANCH_NAME` from the prompt / env. - Validate strict equality: ``` Bash: git rev-parse --abbrev-ref HEAD ``` The output must equal `HANDOFF_BRANCH_NAME` exactly. Do **not** accept partial matches, prefix matches, or "branch contains `/`" heuristics. - If the current branch does **not** match `HANDOFF_BRANCH_NAME`, STOP. Report a blocker in the plan summary: > `Branch drift: expected , actual .` Do **NOT** "fix" drift by switching or creating a branch — Handoff classifies that as `BranchIsolationError` / `blocked_external`. - Use `HANDOFF_BRANCH_NAME` (with `/` replaced by `-`) as the full-mode plan filename stem: `/.md`. Skip the slug derivation in Step 1.2. **If `HANDOFF_MODE` is `1` but `HANDOFF_BRANCH_PREPARED` is unset or `0`:** - Fallback path for older Handoff clients that have not adopted the prepared-branch contract. - Execute Step 1.4 branch creation normally per `git.create_branches` config. #### When `HANDOFF_MODE` is NOT `1` (manual Claude Code session) If polishing an existing plan, extract the Handoff task ID from the `` annotation on the first line (if present). If creating a new plan and no annotation context exists, skip all MCP sync — there is no linked Handoff task. If a task ID IS found in the plan annotation, sync with Handoff via MCP tools: - **On start:** Call `handoff_sync_status` with `{ taskId: , newStatus: "planning", sourceTimestamp: "", direction: "aif_to_handoff", paused: true }`. - **On completion:** Call `handoff_push_plan` with `{ taskId: , planContent: }`. Then call `handoff_sync_status` with `{ taskId: , newStatus: "plan_ready", sourceTimestamp: "", direction: "aif_to_handoff", paused: true }`. **CRITICAL:** Always pass `paused: true` with every `handoff_sync_status` call except `done`. This prevents the autonomous Handoff agent from picking up the task while you work manually. Only `done` passes `paused: false`. Preserve the `` annotation on the first line when rewriting the plan file. ### Step 0: Load Project Context **FIRST:** Read `.ai-factory/config.yaml` if it exists to resolve: - **Paths:** `paths.description`, `paths.architecture`, `paths.roadmap`, `paths.research`, `paths.rules_file`, `paths.plan`, `paths.plans`, `paths.patches`, `paths.evolutions`, `paths.specs`, and `paths.rules` - **Language:** `language.ui` for AskUserQuestion prompts - **Git:** `git.enabled`, `git.base_branch`, `git.create_branches`, and `git.branch_prefix` If config.yaml doesn't exist, use defaults: - Paths: `.ai-factory/` for all artifacts - Language: `en` (English) - Git: `enabled: true`, `base_branch: main`, `create_branches: true`, `branch_prefix: feature/` **THEN:** Read `.ai-factory/DESCRIPTION.md` (use path from config) if it exists to understand: - Tech stack (language, framework, database, ORM) - Project architecture - Coding conventions - Non-functional requirements **ALSO:** Read the resolved architecture artifact if it exists (`paths.architecture`, default: `.ai-factory/ARCHITECTURE.md`) to understand: - Chosen architecture pattern - Folder structure conventions - Layer/module boundaries - Dependency rules Use this context when: - Exploring codebase (know what patterns to look for) - Writing task descriptions (use correct technologies) - Planning file structure (follow project conventions) - **Follow architecture guidelines from the resolved architecture artifact when planning file structure and task organization** **Read `.ai-factory/skill-context/aif-plan/SKILL.md`** — MANDATORY if the file exists. This file contains project-specific rules accumulated by `/aif-evolve` from patches, codebase conventions, and tech-stack analysis. These rules are tailored to the current project. **How to apply skill-context rules:** - Treat them as **project-level overrides** for this skill's general instructions - When a skill-context rule conflicts with a general rule written in this SKILL.md, **the skill-context rule wins** (more specific context takes priority — same principle as nested CLAUDE.md files) - When there is no conflict, apply both: general rules from SKILL.md + project rules from skill-context - Do NOT ignore skill-context rules even if they seem to contradict this skill's defaults — they exist because the project's experience proved the default insufficient - **CRITICAL:** skill-context rules apply to ALL outputs of this skill — including the PLAN.md template and task format. The plan template from TASK-FORMAT.md is a **base structure**. If a skill-context rule says "tasks MUST include X" or "plan MUST have section Y" — you MUST augment the template accordingly. Generating a plan that violates skill-context rules is a bug. **Enforcement:** After generating any output artifact, verify it against all skill-context rules. If any rule is violated — fix the output before presenting it to the user. **OPTIONAL (recommended):** Read the resolved roadmap artifact if it exists (`paths.roadmap`, default: `.ai-factory/ROADMAP.md`): - Use it to link this plan to a specific milestone (when applicable) - This reduces ambiguity in `/aif-implement` milestone completion and `/aif-verify` roadmap gates **OPTIONAL (recommended):** Read the resolved research path if it exists: - Treat `## Active Summary (input for /aif-plan)` as an additional requirements source - Carry over constraints/decisions into tasks and plan settings - Prefer the summary over raw notes; use `## Sessions` only when you need deeper rationale - If the user omitted the feature description, use `Active Summary -> Topic:` as the default description ### Step 0.1: Resolve Git State Do **not** auto-run `git init`. Resolve the current git mode from config first: - `git.enabled: true` → git-aware workflow is allowed - `git.enabled: false` → no-git workflow only - `git.base_branch` → target branch for diffs/merge guidance (default: detected branch or `main`) - `git.create_branches: true` → full mode may create a branch/worktree - `git.create_branches: false` → full mode still creates a rich plan, but stays on the current branch / repository state If `git.enabled = false`: - Skip all branch/worktree commands - Save full-mode plans under `paths.plans/.md` - Treat `--parallel`, `--list`, and `--cleanup` as unavailable If `git.enabled = true` but the repository is not actually inside a git work tree: - Warn the user that git-aware actions are unavailable until the repository is initialized - Fall back to the same no-git behavior as above ### Step 0.2: Parse Arguments & Select Mode Extract flags and mode from `$ARGUMENTS`: ``` --parallel → Enable parallel worktree mode (full mode only; requires `git.enabled=true` and `git.create_branches=true`) --list → Show all active worktrees, then STOP (git-only) --cleanup → Remove worktree and optionally delete branch, then STOP (git-only) fast → Fast mode (first word) full → Full mode (first word) ``` **Parsing rules:** - Strip `--parallel`, `--list`, `--cleanup `, `fast`, `full` from `$ARGUMENTS` - Remaining text becomes the description - `--list` and `--cleanup` execute immediately and **STOP** (do NOT continue to Step 1+) - If `git.enabled = false`, reject `--parallel`, `--list`, and `--cleanup` with a short explanation instead of trying git commands - If `--parallel` is set while `git.create_branches = false`, reject it with a short explanation because parallel mode requires branch creation **If the description is empty:** - If the resolved research path exists and its `Active Summary` has a non-empty `Topic:`, default the description to that topic (no extra user input required) - Otherwise, ask the user for a short feature description **If `--list` is present**, jump to [--list Subcommand](#--list-subcommand). **If `--cleanup` is present**, jump to [--cleanup Subcommand](#--cleanup-subcommand). **Mode selection:** - `fast` keyword → fast mode - `full` keyword → full mode - Neither → ask interactively: ``` AskUserQuestion: Which planning mode? Options: 1. Full (Recommended) — richer plan, asks preferences, optional branch/worktree flow when git settings allow it 2. Fast – quick plan, no branch, saves to the resolved fast plan path ``` If the user did not provide a description and the resolved research path exists: - Mention that you will default the description to the `Active Summary` topic - Only ask for `full` vs `fast` (no description prompt needed) For concrete parsing examples and expected behavior per command shape, read `references/EXAMPLES.md` (Argument Parsing). --- ## Full Mode ### Step 1: Parse Description & Quick Reconnaissance From the description, extract: - Core functionality being added - Key domain terms - Type (feature, enhancement, fix, refactor) **Use `Task` tool with `subagent_type: Explore` to quickly understand the relevant parts of the codebase.** This runs as a subagent and keeps the main context clean. Based on the parsed description, launch 1-2 Explore agents in parallel: ``` Task(subagent_type: Explore, model: sonnet, prompt: "In [project root], find files and modules related to [feature domain keywords]. Report: key directories, relevant files, existing patterns, integration points. Thoroughness: quick. Be concise — return a structured summary, not file contents.") ``` **Rules:** - 1-2 agents max, "quick" thoroughness — this is reconnaissance, not deep analysis - Deep exploration happens later in Step 3 - If `.ai-factory/DESCRIPTION.md` already provides sufficient context, this step can be skipped ### Step 1.2: Generate Full-Mode Plan Identifier **If `HANDOFF_BRANCH_PREPARED = 1`:** skip slug generation entirely. Use `HANDOFF_BRANCH_NAME` as the branch identifier and `.md` as the plan filename stem. Continue to Step 1.3. Generate a reusable slug from the description first. This slug is used for: - the git branch name when branch creation is enabled - the full-mode plan filename when no branch is created If `git.enabled = true` and `git.create_branches = true`, generate a branch name: ``` Format: Examples: - feature/user-authentication - fix/cart-total-calculation - refactor/api-error-handling - chore/upgrade-dependencies ``` **Rules:** - Start with the configured `git.branch_prefix` when present (default: `feature/`) - Lowercase with hyphens - Max 50 characters - No special characters except hyphens - Descriptive but concise If `git.enabled = false` or `git.create_branches = false`: - Do **not** create a branch name - Use the slug to create `/.md` - Keep the user on the current branch or current non-git directory state ### Step 1.3: Ask About Preferences **IMPORTANT: Always ask the user before proceeding:** ``` AskUserQuestion: Before we start, a few questions: 1. Should I write tests for this feature? a. Yes, write tests b. No, skip tests 2. Logging level for implementation: a. Verbose (recommended) - detailed DEBUG logs for development b. Standard - INFO level, key events only c. Minimal - only WARN/ERROR 3. Documentation policy after implementation? a. Yes — mandatory docs checkpoint at completion (recommended) b. No — warn-only (`WARN [docs]`), no mandatory checkpoint 4. Roadmap milestone linkage (only if the resolved roadmap artifact exists): a. Link this plan to a milestone b. Skip — no linkage (allowed; `/aif-verify --strict` should report WARN, not fail, for missing linkage alone) 5. Any specific requirements or constraints? ``` **Default to verbose logging.** AI-generated code benefits greatly from extensive logging because: - Subtle bugs are common and hard to trace without logs - Users can always remove logs later - Missing logs during development wastes debugging time Store all preferences — they will be used in the plan file and passed to `/aif-implement`. Docs policy semantics: - `Docs: yes` → `/aif-implement` MUST show a mandatory documentation checkpoint and route docs changes through `/aif-docs` - `Docs: no` (or unset) → `/aif-implement` emits `WARN [docs]` and continues without a mandatory docs checkpoint **If the resolved roadmap artifact exists and the user chose milestone linkage:** - Read the resolved roadmap artifact and list candidate milestones (prefer unchecked items) - Ask the user to pick one milestone (or type a custom one) - Store the selected milestone name and a 1-sentence rationale for inclusion in the plan file ### Step 1.4: Optional Branch / Worktree Setup **If `HANDOFF_BRANCH_PREPARED = 1` (Handoff owns the branch):** - Skip this entire step. Branch validation already happened in Step 0. - The plan file path uses `HANDOFF_BRANCH_NAME` (slashes replaced by `-`) as the stem. - Do **NOT** run `git checkout`, `git pull`, `git checkout -b`, or `git worktree add`. - Treat `--parallel` as disabled: do not create a worktree and do not auto-invoke `/aif-implement`. **If `git.enabled = false` or `git.create_branches = false`:** - Skip all branch/worktree creation - Continue with the generated full plan file path under `paths.plans/.md` **If `--parallel` flag is set → create worktree:** #### Worktree Creation ```bash DIRNAME=$(basename "$(pwd)") git branch git worktree add ../${DIRNAME}- ``` Convert branch name for directory: replace `/` with `-`. **Example:** ``` Project dir: my-project Branch: feature/user-auth Worktree: ../my-project-feature-user-auth ``` Copy context files so the worktree has full AI context: - Create the parent directories for the resolved DESCRIPTION, ARCHITECTURE, RESEARCH, plan, patch, and evolution paths inside the worktree. - Copy the resolved DESCRIPTION, ARCHITECTURE, and RESEARCH artifacts into the same configured relative locations inside the worktree. - Copy `.ai-factory/skill-context/` as-is into the worktree. - Copy only the latest 10 patch files from the resolved `paths.patches` directory into the same configured relative path inside the worktree. - Do **not** copy `patch-cursor.json` when you copied only a truncated patch set; that cursor is valid only with the full patch history. - Copy agent settings (for example `.claude/`) and untracked `CLAUDE.md` when present. Create changes directory and switch: ```bash cd "${WORKTREE}" ``` Display confirmation: ``` Parallel worktree created! Branch: Directory: To manage worktrees later: /aif-plan --list /aif-plan --cleanup ``` Continue to Step 2. **If no `--parallel` → create branch normally:** ```bash git checkout git pull origin git checkout -b ``` If branch already exists, ask user: - Switch to existing branch? - Create with different name? --- ## Fast Mode ### Step 1: Ask About Preferences Ask a shorter set of questions: ``` AskUserQuestion: Before we start: 1. Should I include tests in the plan? a. Yes, include tests b. No, skip tests 2. Any specific requirements or constraints? 3. Roadmap milestone linkage (only if the resolved roadmap artifact exists): a. Link this plan to a milestone b. Skip — no linkage (allowed; `/aif-verify --strict` should report WARN, not fail, for missing linkage alone) ``` **Plan file:** Always the resolved `paths.plan` file (default: `.ai-factory/PLAN.md`). --- ## Shared Steps (both modes) ### Step 2: Analyze Requirements From the description, identify: - Core functionality to implement - Components/files that need changes - Dependencies between tasks - Edge cases to handle If requirements are ambiguous, ask clarifying questions: ``` I need a few clarifications before creating the plan: 1. [Specific question about scope] 2. [Question about approach] ``` ### Step 3: Explore Codebase Before planning, understand the existing code through **parallel exploration**. **Use `Task` tool with `subagent_type: Explore` to investigate the codebase in parallel.** This keeps the main context clean and speeds up research. Launch 2-3 Explore agents simultaneously, each focused on a different aspect: ``` Agent 1 — Architecture & affected modules: Task(subagent_type: Explore, model: sonnet, prompt: "Find files and modules related to [feature domain]. Map the directory structure, key entry points, and how modules interact. Thoroughness: medium.") Agent 2 — Existing patterns & conventions: Task(subagent_type: Explore, model: sonnet, prompt: "Find examples of similar functionality already implemented in the project. Show patterns for [relevant patterns: API endpoints, services, models, etc.]. Thoroughness: medium.") Agent 3 — Dependencies & integration points (if needed): Task(subagent_type: Explore, model: sonnet, prompt: "Find all files that import/use [module/service]. Identify integration points and potential side effects of changes. Thoroughness: medium.") ``` **If full mode passed codebase reconnaissance** from Step 1 — use it as a starting point. Focus Explore agents on areas that need deeper understanding. **After agents return, synthesize:** - Which files need to be created/modified - What patterns to follow (from existing code) - Dependencies between components - Potential risks or edge cases **Fallback:** If Task tool is unavailable, use Glob/Grep/Read directly. ### Step 4: Create Task Plan Create tasks using `TaskCreate` with clear, actionable items. **Task Guidelines:** - Each task should be completable in one focused session - Tasks should be ordered by dependency (do X before Y) - Include file paths where changes will be made - Be specific about what to implement, not vague Use `TaskUpdate` to set `blockedBy` relationships: - Task 2 blocked by Task 1 if it depends on Task 1's output - Keep dependency chains logical ### Step 5: Save Plan to File **Determine plan file path:** - **Fast mode** → the resolved `paths.plan` - **Full mode** → `/.md` **Before saving, ensure directory exists:** ```bash mkdir -p ``` **Plan file must include:** - Title with feature name - Branch and creation date - `Settings` section (Testing, Logging, Docs) - `Roadmap Linkage` section (optional, only if the resolved roadmap artifact exists) - `Research Context` section (optional, if the resolved research path exists) - `Tasks` section grouped by phases - `Commit Plan` section when there are 5+ tasks If the resolved roadmap artifact exists: - If the user linked a milestone, write `## Roadmap Linkage` with `Milestone: "..."` and `Rationale: ...` - If the user skipped linkage, write `## Roadmap Linkage` with `Milestone: "none"` and `Rationale: "Skipped by user"` If the resolved research path exists: - Include `## Research Context` by copying only the `Active Summary` (do not paste full `Sessions`) - Keep it compact; it should be readable as a one-screen requirements snapshot Use the canonical template in `references/TASK-FORMAT.md` (Plan File Template). **Commit Plan Rules:** - **5+ tasks** → add commit checkpoints every 3-5 tasks - **Less than 5 tasks** → single commit at the end, no commit plan needed - Group logically related tasks into one commit - Suggest meaningful commit messages following conventional commits ### Step 6: Next Steps **Full mode + parallel (`--parallel`):** Automatically invoke `/aif-implement` — the whole point of parallel is autonomous end-to-end execution in an isolated worktree. If `HANDOFF_BRANCH_PREPARED = 1`, treat `--parallel` as disabled and do not auto-invoke `/aif-implement`. ``` /aif-implement CONTEXT FROM /aif-plan: - Plan file: /.md - Testing: yes/no - Logging: verbose/standard/minimal - Docs: yes/no # yes => mandatory docs checkpoint, no => warn-only ``` **Full mode normal:** STOP after planning. The user reviews the plan and decides when to implement. ``` Plan created with [N] tasks. Plan file: /.md To start implementation, run: /aif-implement To view tasks: /tasks (or use TaskList) ``` **Fast mode:** STOP after planning. ``` Plan created with [N] tasks. Plan file: To start implementation, run: /aif-implement To view tasks: /tasks (or use TaskList) ``` ### Context Cleanup Suggest the user to free up context space if needed: `/clear` (full reset) or `/compact` (compress history). --- ## --list Subcommand When `--list` is passed, show all active worktrees and their feature status. Then **STOP**. ```bash git worktree list ``` For each worktree path: 1. Check whether the resolved plans directory exists under that worktree (`/`, default: `/.ai-factory/plans/`) and contains any plan files 2. Show name and whether it looks complete (has tasks) or is still in progress **Output format:** ``` Active worktrees: /path/to/my-project () <- you are here /path/to/my-project-feature-user-auth (feature/user-auth) -> Plan: feature-user-auth.md /path/to/my-project-fix-cart-bug (fix/cart-bug) -> No plan yet ``` ## --cleanup Subcommand When `--cleanup ` is passed, remove the worktree and optionally delete the branch. Then **STOP**. ```bash DIRNAME=$(basename "$(pwd)") BRANCH_DIR=$(echo "" | tr '/' '-') WORKTREE="../${DIRNAME}-${BRANCH_DIR}" git worktree remove "${WORKTREE}" git branch -d # -d (not -D) will fail if unmerged, which is safe ``` If `git branch -d` fails because the branch is unmerged: ``` Branch has unmerged changes. To force-delete: git branch -D To merge first: git checkout && git merge ``` If the worktree path doesn't exist, check `git worktree list` and suggest the correct path. --- ## Task Description Requirements Every `TaskCreate` item MUST include: - Clear deliverable and expected behavior - File paths to change/create - Logging requirements (what to log, where, and levels) - Dependency notes when applicable **Never create tasks without logging instructions.** Use canonical examples in `references/TASK-FORMAT.md`: - TaskCreate Example - Logging Requirements Checklist ## Important Rules 1. **NO tests if user said no** — Don't sneak in test tasks 2. **NO reports** — Don't create summary/report tasks at the end 3. **Actionable tasks** — Each task should have clear deliverable 4. **Right granularity** — Not too big (overwhelming), not too small (noise) 5. **Dependencies matter** — Order tasks so they can be done sequentially 6. **Include file paths** — Help implementer know where to work 7. **Commit checkpoints for large plans** — 5+ tasks need commit plan with checkpoints every 3-5 tasks 8. **Plan file location** – Fast mode: `paths.plan`. Full mode: `paths.plans/.md` 9. **Ownership boundary** – This command owns plan files only (the resolved fast plan path and files under `paths.plans`). Use owner commands (`/aif-roadmap`, `/aif-rules`, `/aif-explore`) for their artifacts. 10. **Roadmap linkage (when available)** — If the resolved roadmap artifact exists, include a `## Roadmap Linkage` section in the plan (or explicitly state it was skipped). ## Plan File Handling **Fast mode (`paths.plan`, default: `.ai-factory/PLAN.md`)** - Temporary plan for quick work - `/aif-implement` may offer deletion after completion **Full mode (`paths.plans/.md`)** - Long-lived plan for feature delivery - Branch-scoped when a branch is created; slug-scoped when full mode runs without branch creation For concrete end-to-end flows (fast/full/full+parallel/interactive), read `references/EXAMPLES.md` (Flow Scenarios).