lee-to/ai-factory/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: Resolve explicit mode → valid workflow.plan_mode → fast. The ask default falls back to fast in non-interactive Handoff mode; never ask a mode question there. Resolve config in Step 0 before applying this fallback.
• 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:

• Command default: workflow.plan_mode (ask by default; allowed: ask, fast, full, ultra). An absent value uses ask; an invalid value/type emits WARN [config] invalid workflow.plan_mode; falling back to ask and uses ask.
• 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. Keep ## Requirements Reconciliation exact because downstream workflow checks parse it as a compatibility token. 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

ALSO: Read the resolved rules hierarchy when present:

1. paths.rules_file — project-wide axioms
2. rules.base — base project conventions
3. named rules.<area> entries relevant to the requested work

Treat explicit rules as authoritative requirements. More-specific area rules override base rules, which override project-wide axioms.

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.