Aif Plan

Plan - Implementation Planning

Create an implementation plan for a feature or task. Three 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
• Ultra — exhaustive multi-file plan bundle under the configured full-plan directory: index.md is the manifest/progress ledger and every implementation phase is a separate, deeply specified markdown file. Use it when planning with a stronger model for later execution by a smaller model.

For ultra layout, detail requirements, integrity checks, and consumer behavior, read references/ULTRA-FORMAT.md before creating or modifying the bundle.

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 <!-- handoff:task:<HANDOFF_TASK_ID> --> as the very first line of the plan entrypoint (index.md for ultra; the plan file otherwise), 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 <HANDOFF_BRANCH_NAME>, actual <current>. 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/ultra plan identifier stem. Full writes <configured plans dir>/<stem>.md; ultra writes <configured plans dir>/<stem>/index.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 <!-- handoff:task:<id> --> annotation on the first line of the plan entrypoint (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: <extracted-id>, newStatus: "planning", sourceTimestamp: "<current UTC time in ISO 8601 format>", direction: "aif_to_handoff", paused: true }.
• On completion: Call handoff_push_plan with { taskId: <extracted-id>, planContent: <full plan text> }. For ultra, serialize the bundle as index.md followed by every Phase Index file in order, each prefixed with <!-- ultra-phase:<relative-path> -->. Then call handoff_sync_status with { taskId: <extracted-id>, newStatus: "plan_ready", sourceTimestamp: "<current UTC time in ISO 8601 format>", 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 <!-- handoff:task:<id> --> annotation on the first line when rewriting the plan entrypoint.

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, paths.rules, and paths.archive
  • Derive research_bundles_dir = <parent directory of paths.research>/research/ for opt-in ultra research bundles. No additional config key is required.
• Language: language.ui for AskUserQuestion prompts, language.artifacts for generated plan files, and language.technical_terms for human-readable technical terminology in plan artifacts
• Git: git.enabled, git.base_branch, git.create_branches, and git.branch_prefix
• Workflow: workflow.plan_id_format — controls the full/ultra plan identifier shape. Allowed values: slug (default), timestamp, uuid, sequential. Only slug and sequential are active; timestamp and uuid are reserved and currently behave like slug (with an INFO log). The sequential value writes a full plan as <NNNN>_<plan_file_stem>.md and an ultra bundle as <NNNN>_<plan_file_stem>/index.md (see Step 1.2 for the canonical stem and algorithm). Treat any unknown value as slug and emit WARN [aif-plan] unknown workflow.plan_id_format=<value>; falling back to slug.

If config.yaml doesn't exist, use defaults:

• Paths: .ai-factory/ for all artifacts
• ui_language: en
• artifact_language: en
• technical_terms_policy: keep
• Git: enabled: true, base_branch: main, create_branches: true, branch_prefix: feature/
• Workflow: plan_id_format: slug

Resolved language values:

• ui_language = language.ui || "en"
• artifact_language = language.artifacts || language.ui || "en"
• technical_terms_policy = language.technical_terms || "keep"

If technical_terms_policy is not one of keep, translate, or mixed, treat it as keep. Legacy values such as english also behave like keep.

All AskUserQuestion prompts, progress updates, summaries, and next-step guidance MUST be written in ui_language.

Generated plan artifacts under paths.plan or paths.plans MUST be written in artifact_language. For ultra this applies to index.md and every linked phase file.

Templates and examples define structure, not fixed English output. If artifact_language is not en, translate human-readable headings, labels, task prose, roadmap rationale, research summaries, settings explanations, and dependency notes before saving. Preserve markdown structure, checkbox syntax, task IDs, branch names, commit messages, commands, file paths, config keys, package names, API names, WARN/INFO labels, raw errors, and the exact ultra marker <!-- aif:plan-mode:ultra --> unchanged. Keep ## Research Context, Source:, Active Summary, Updated:, and SHA256: exact because downstream research drift checks parse them as compatibility tokens. Apply technical_terms_policy to other human-readable terminology.

Exception: the section heading and body of ## Original Request are fixed raw-source structure and must not be translated, summarized, normalized, or rewritten.

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, ultra bundle, and task format. The templates from TASK-FORMAT.md and ULTRA-FORMAT.md are 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): Resolve at most one relevant research source:

• A legacy source is the configured paths.research file.
• An ultra source is research_bundles_dir/<english-slug>/RESEARCH.md, but only when the sibling INDEX.md contains <!-- aif:research-mode:ultra --> exactly once and its ## Artifact Index links that RESEARCH.md. Do not treat arbitrary directories as research bundles.
• When the user supplied a topic or request, source priority is: an explicitly referenced bundle/file; then one clearly topic-matching marked Status: active bundle; then the relevant legacy file. An explicit source means a concrete RESEARCH.md or bundle path named in the request or follow-up; it is user content, not a stripped command token.
• Resolve a topic match by exact English slug first, then a normalized Topic: match, then a unique semantic match against Purpose / Active Summary. Never pick by recency. If no single match is clear or multiple sources would change scope, ask instead of merging or guessing. An explicitly referenced paused or superseded bundle requires a warning before use.
• Read an ultra INDEX.md first, then its linked RESEARCH.md. Read C4/ADR/dependency artifacts only for rationale needed by this plan. They are not independent requirement sources; material conclusions must already be reflected in the Active Summary.
• Store the chosen file as selected_research_path. Treat its ## 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 and linked optional artifacts only when you need deeper rationale.
• No-description fallback is the deliberate backward-compatibility exception to the topic-based priority: use the configured paths.research Active Summary topic when available. Otherwise use a single active marked ultra bundle; if several active bundles exist, ask the user to choose rather than guessing.
• Track whether research content influenced this plan. Set research_influenced_plan = true only when the Active Summary supplies the default description or when constraints, decisions, goals, open questions, or session rationale from the research artifact shape the plan scope, tasks, settings, or tradeoffs. If the research artifact exists but is stale or unrelated to the user's requested task, leave research_influenced_plan = false, ignore it for plan requirements, and do not add ## Research Context.
• If any research content influences the plan, the generated plan MUST include ## Research Context with canonical Source: `<selected_research_path>` (Active Summary, Updated: <timestamp>, SHA256: <digest>) metadata. Omitting this plan-owned research copy is a bug because downstream skills treat the embedded Research Context as the plan's authoritative requirements and use the source research file only for drift checks.
• Normalize the copied Active Summary before hashing: include exactly the text that will be pasted under ## Research Context after the Source: line, remove HTML comment blocks, preserve line order and leading whitespace, trim trailing spaces from every line, use LF line endings, and end with exactly one final newline. Calculate the digest without writing any temporary file or repository artifact: feed the normalized text through stdin / inline shell input to shasum -a 256; if shasum is unavailable, feed the same normalized text to sha256sum. Use the first output field as the SHA256: value.

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/ultra mode may create a branch/worktree
• git.create_branches: false → full/ultra mode still creates its plan artifact, but stays on the current branch / repository state

If git.enabled = false:

• Skip all branch/worktree commands
• Save full plans under paths.plans/<slug>.md and ultra bundles under paths.plans/<slug>/index.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/ultra only; requires `git.enabled=true` and `git.create_branches=true`)
--list      → Show all active worktrees, then STOP (git-only)
--cleanup <branch> → Remove worktree and optionally delete branch, then STOP (git-only)
fast        → Fast mode (first word)
full        → Full mode (first word)
ultra       → Ultra mode (first word)

Parsing rules:

• Strip only recognized command tokens in command positions from $ARGUMENTS:
  • fast, full, or ultra only when used as the leading mode token
  • recognized control flags --parallel, --list, and --cleanup <branch>
  • do not remove matching words inside the user's actual request text
• Remaining text becomes the description
• Preserve the remaining text as original_user_request when it is non-empty: trim only outer whitespace introduced by command parsing, but keep internal whitespace, line breaks, wording, casing, and punctuation exactly. This is the user's original planning request and MUST be saved into the plan entrypoint later.
• --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 configured paths.research file exists and its Active Summary has a non-empty Topic:, default the description to that topic (no extra user input required), set it as selected_research_path, and leave original_user_request empty.
• Otherwise, if exactly one marked active ultra bundle exists and its linked RESEARCH.md has a non-empty Topic:, use that topic and file. If multiple marked active bundles exist, ask the user to select a topic/source.
• Plans created from a selected RESEARCH.md without an explicit user request MUST NOT include an Original Request section.
• Otherwise, ask the user for a short feature description. Preserve the user's answer verbatim as original_user_request and save it into the plan entrypoint later.

Original request contract:

• If the user explicitly supplied a planning request (for example /aif-plan ТУТ ЗАПРОС НА ПЛАН, /aif-plan full ТУТ ЗАПРОС НА ПЛАН, /aif-plan ultra ТУТ ЗАПРОС НА ПЛАН, or an answer to the description prompt), the generated plan entrypoint MUST include ## Original Request.
• ## Original Request contains the exact user-provided request text after only recognized command tokens are removed and only outer whitespace is trimmed. Do not rewrite, summarize, translate, or normalize its wording, even when artifact_language differs.
• If the description was derived only from a selected RESEARCH.md because the user did not provide a request, omit ## Original Request; the committed source is ## Research Context instead.
• If the user supplied a request and selected research also influenced the plan, include both ## Original Request and ## Research Context.

If --list is present, jump to --list Subcommand. If --cleanup is present, jump to --cleanup Subcommand.

Mode selection:

• fast keyword → fast mode
• full keyword → full mode
• ultra keyword → ultra mode
• Neither → preserve the pre-ultra interactive contract and ask only between full and fast. Ultra is strictly opt-in and is selected only by the explicit leading ultra mode token:

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 a research source was selected:

• Mention that you will default the description to the Active Summary topic
• Only ask for full vs fast (no description prompt needed)
• Do not mention, recommend, or auto-select ultra unless the caller used the explicit leading ultra token

For concrete parsing examples and expected behavior per command shape, read references/EXAMPLES.md (Argument Parsing).

Full and Ultra Modes

Step 1: Parse Description & 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 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:

• Full: 1-2 agents max, "quick" thoroughness — this is reconnaissance, not deep analysis
• Ultra: 2-3 focused agents when available; cover architecture, existing patterns, integration/side effects, and test/operations surfaces. This reconnaissance feeds the deeper evidence required by ULTRA-FORMAT.md.
• 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/Ultra Plan Identifier

This step produces two distinct values:

• branch_name — the git branch (only when git.enabled = true and git.create_branches = true)
• plan_file_stem — the canonical unprefixed plan stem under <configured plans dir>/
• plan_identifier — plan_file_stem with an optional NNNN_ prefix; it becomes the full-plan filename stem or ultra directory name

These are derived in a fixed order so the producer here and the branch-based consumers in /aif-implement / /aif-improve / /aif-verify / /aif-rules-check always agree on either the full-plan file or ultra entrypoint.

1.2.a — Resolve the canonical plan_file_stem

Pick the first matching case:

1. HANDOFF_BRANCH_PREPARED = 1 → plan_file_stem = HANDOFF_BRANCH_NAME with every / replaced by -. Skip slug generation entirely. No branch_name is created here (Handoff already owns the branch).
2. git.enabled = true AND git.create_branches = true → generate a description slug, then branch_name = <git.branch_prefix><slug> (default prefix: feature/). Set plan_file_stem = branch_name with every / replaced by - (for example feature-user-authentication).
3. Otherwise (git.enabled = false OR git.create_branches = false) → plan_file_stem = <description slug>. No branch_name is created.

Slug rules (cases 2 and 3):

• Lowercase, hyphen-separated, max 50 characters
• No special characters except hyphens
• Descriptive but concise

Branch examples (case 2):

• feature/user-authentication
• fix/cart-total-calculation
• refactor/api-error-handling
• chore/upgrade-dependencies

Invariant: branch-based consumer skills compute their lookup stem as current-branch-with-slashes-replaced. Cases 1 and 2 above already match that. Case 3 never has a branch, so consumers fall back to the lone full/ultra plan artifact in <configured plans dir>/ (see aif-implement Step 0.2). Producing a plan_file_stem outside these rules breaks discovery.

1.2.b — Apply the workflow.plan_id_format prefix

Default: no prefix. Set plan_identifier = plan_file_stem. Full writes <configured plans dir>/<plan_identifier>.md; ultra writes <configured plans dir>/<plan_identifier>/index.md.

Format-specific handling:

• slug (default) → no prefix.
• timestamp / uuid → reserved values; treat as slug for now. Emit INFO [aif-plan] workflow.plan_id_format=<value> is reserved and behaves like slug; numbering is not applied. Do NOT invent a stem shape — branch-based consumers do not know how to discover non-sequential prefixes.
• Unknown values → already handled in Step 0: emit WARN [aif-plan] unknown workflow.plan_id_format=<value>; falling back to slug. Behaves like slug here.
• sequential → apply the algorithm in 1.2.c to plan_file_stem to produce plan_identifier.

Sequential is force-disabled when HANDOFF_BRANCH_PREPARED = 1. In that case keep the bare plan_file_stem and emit INFO [aif-plan] sequential numbering disabled under HANDOFF_BRANCH_PREPARED=1.

1.2.c — Sequential numbering algorithm

Prepend a 4-digit numeric prefix to plan_file_stem to produce plan_identifier. Compute the prefix from existing numbered full-plan files and numbered directories whose index.md contains the exact ultra marker in <configured plans dir>. The branch name (when one exists) stays unchanged so existing git tooling, CI, and PR conventions are unaffected.

1. Find existing numbered plans in <configured plans dir>:
     Glob A: <configured plans dir>/[0-9][0-9][0-9][0-9]_*.md
     Glob B: <configured plans dir>/[0-9][0-9][0-9][0-9]_*/index.md
2. Every Glob A match is a numbered full-plan candidate.
   For every Glob B match, Read index.md and keep it only when it contains the
   exact marker <!-- aif:plan-mode:ultra -->. Ignore numbered directories whose
   index.md lacks the marker; they are not plans and cannot consume an ID.
3. Parse the leading 4 digits from each retained full-plan filename or marked
   ultra directory
   basename into an integer. Deduplicate equal prefixes.
   Filter out entries whose relevant basename does not match
   ^[0-9]{4}_.+(\.md)?$.
4. If any matches exist:
     max_existing = max(prefixes)
     If max_existing >= 9999:
       ABORT with error:
         "sequential cap reached: a plan numbered 9999 already exists in <configured plans dir>."
         "Switch workflow.plan_id_format back to slug, or move the 9999-numbered file out of the directory (note: doing so will free 9999 for the next plan to reuse)."
     next = max_existing + 1
   Else:
     next = 1
5. prefix = zero-padded 4-digit string of next   (e.g. 1 → "0001", 42 → "0042")
6. Set plan_identifier = <prefix>_<plan_file_stem>
7. Final artifact:
     full  → <configured plans dir>/<plan_identifier>.md
     ultra → <configured plans dir>/<plan_identifier>/index.md

Implementation notes:

• Use Glob to enumerate candidates and Read to validate every numbered ultra candidate's marker. Do NOT shell out to ls — aif-plan's frontmatter does not grant Bash(ls *), so the ls path would fail in production.
• The 4-digit [0-9][0-9][0-9][0-9] glob is strict by contract: the format supports 0001..9999 only. The error in step 4 enforces this.
• --parallel scope (TL;DR — source-worktree scoped):
  • Where the prefix is computed: the source worktree's <configured plans dir> (the repo where /aif-plan was invoked) — i.e. exactly here, in Step 1.2.c.
  • When it is computed: before the optional cd <WORKTREE> in Step 1.4.
  • Where the plan artifact is written: the same relative full file or ultra directory path inside the target worktree, so the prefix and destination directory stay consistent.
  • What you must NOT do: never recompute the prefix from the target worktree's plans dir after cd <WORKTREE>. The target dir is typically empty and would re-allocate 0001 on every parallel run, breaking the cross-worktree numbering contract on merge.

Rules:

• Numbering is derived from existing full-plan files and marked ultra directories in <configured plans dir>. Unmarked numbered directories are ignored. Deleting or moving a numbered plan out of the directory can free that number for reuse on the next run — keep plans in place if you rely on stable cross-references.
• Archived plans are excluded from numbering. Plans moved to paths.archive/plans/ by /aif-archive are not in <configured plans dir> and therefore not counted. Archiving the highest-numbered plan frees that number for reuse.
• Numbering is bounded — 9999 is a hard cap; the algorithm errors instead of writing 10000_… so consumer globs (also 4-digit) cannot drift out of contract.
• The prefix lives only on the full-plan filename or ultra directory. The git branch (when present) stays <branch_prefix><slug> without a number.
• This setting is ignored for fast plans (paths.plan is a single file) and fix plans (paths.fix_plan is a single file).

Logging: INFO [aif-plan] resolved plan artifact: <path> (mode=<mode>, format=<value>).