Plan - Implementation Planning

Create an implementation plan for a feature or task. Two modes:

• Fast — quick plan, no git branch, saves to .ai-factory/PLAN.md
• Full — creates git branch, asks preferences, saves to .ai-factory/plans/<branch>.md

Workflow

Step 0: Load Project Context

FIRST: Read .ai-factory/DESCRIPTION.md if it exists to understand:

• Tech stack (language, framework, database, ORM)
• Project architecture
• Coding conventions
• Non-functional requirements

ALSO: Read .ai-factory/ARCHITECTURE.md if it exists 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 .ai-factory/ARCHITECTURE.md 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 .ai-factory/ROADMAP.md if it exists:

• 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 .ai-factory/RESEARCH.md 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: Ensure Git Repository

git rev-parse --is-inside-work-tree 2>/dev/null || git init

Step 0.2: Parse Arguments & Select Mode

Extract flags and mode from $ARGUMENTS:

--parallel  → Enable parallel worktree mode (full mode only)
--list      → Show all active worktrees, then STOP
--cleanup <branch> → Remove worktree and optionally delete branch, then STOP
fast        → Fast mode (first word)
full        → Full mode (first word)

Parsing rules:

• Strip --parallel, --list, --cleanup <branch>, fast, full from $ARGUMENTS
• Remaining text becomes the description
• --list and --cleanup execute immediately and STOP (do NOT continue to Step 1+)

If the description is empty:

• If .ai-factory/RESEARCH.md 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. If --cleanup is present, jump to --cleanup Subcommand.

Mode selection:

• fast keyword → fast mode
• full keyword → full mode
• Neither → ask interactively:

AskUserQuestion: Which planning mode?

Options:
1. Full (Recommended) — creates git branch, asks preferences, full plan
2. Fast — quick plan, no branch, saves to PLAN.md

If the user did not provide a description and .ai-factory/RESEARCH.md 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 Branch Name

Format: <type>/<short-description>

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

Rules:

• Lowercase with hyphens
• Max 50 characters
• No special characters except hyphens
• Descriptive but concise

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?
   - [ ] Yes, write tests
   - [ ] No, skip tests

2. Logging level for implementation:
   - [ ] Verbose (recommended) - detailed DEBUG logs for development
   - [ ] Standard - INFO level, key events only
   - [ ] Minimal - only WARN/ERROR

3. Documentation policy after implementation?
   - [ ] Yes — mandatory docs checkpoint at completion (recommended)
   - [ ] No — warn-only (`WARN [docs]`), no mandatory checkpoint

4. Roadmap milestone linkage (only if `.ai-factory/ROADMAP.md` exists):
   - [ ] Link this plan to a milestone
   - [ ] 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 .ai-factory/ROADMAP.md exists and the user chose milestone linkage:

• Read .ai-factory/ROADMAP.md 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: Create Branch or Worktree

If --parallel flag is set → create worktree:

Worktree Creation

DIRNAME=$(basename "$(pwd)")
git branch <branch-name> main
git worktree add ../${DIRNAME}-<branch-name-with-hyphens> <branch-name>

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:

WORKTREE="../${DIRNAME}-<branch-name-with-hyphens>"

# Ensure AI Factory directories exist before copy operations
mkdir -p "${WORKTREE}/.ai-factory"
mkdir -p "${WORKTREE}/.ai-factory/plans"
mkdir -p "${WORKTREE}/.ai-factory/patches"
mkdir -p "${WORKTREE}/.ai-factory/evolutions"

# Project context
cp .ai-factory/DESCRIPTION.md "${WORKTREE}/.ai-factory/DESCRIPTION.md" 2>/dev/null
cp .ai-factory/ARCHITECTURE.md "${WORKTREE}/.ai-factory/ARCHITECTURE.md" 2>/dev/null
cp .ai-factory/RESEARCH.md "${WORKTREE}/.ai-factory/RESEARCH.md" 2>/dev/null

# Skill-context (primary learning context)
cp -r .ai-factory/skill-context/ "${WORKTREE}/.ai-factory/skill-context/" 2>/dev/null

# Note: do not copy patch-cursor.json into a truncated patch set.
# The parallel worktree copies only a limited number of patches for fallback context.
# Copying the evolve cursor without the full patch history can cause /aif-evolve to skip patches
# or trigger a partial rescan.

# Limited patch fallback: copy only recent patches (latest 10 by filename)
for patch in $(ls -1 .ai-factory/patches/*.md 2>/dev/null | sort | tail -n 10); do
  cp "${patch}" "${WORKTREE}/.ai-factory/patches/"
done

# Agent skills + settings
cp -r .claude/ "${WORKTREE}/.claude/" 2>/dev/null

# CLAUDE.md only if untracked
if [ -f CLAUDE.md ] && ! git ls-files --error-unmatch CLAUDE.md &>/dev/null; then
  cp CLAUDE.md "${WORKTREE}/CLAUDE.md"
fi

Create changes directory and switch:

cd "${WORKTREE}"

Display confirmation:

Parallel worktree created!

  Branch:    <branch-name>
  Directory: <worktree-path>

To manage worktrees later:
  /aif-plan --list
  /aif-plan --cleanup <branch-name>

Continue to Step 2.

If no --parallel → create branch normally:

git checkout main
git pull origin main
git checkout -b <branch-name>

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?
   - [ ] Yes, include tests
   - [ ] No, skip tests

2. Any specific requirements or constraints?

3. Roadmap milestone linkage (only if `.ai-factory/ROADMAP.md` exists):
   - [ ] Link this plan to a milestone
   - [ ] Skip — no linkage (allowed; `/aif-verify --strict` should report WARN, not fail, for missing linkage alone)

Plan file: Always .ai-factory/PLAN.md (no branch, no branch-named file).

---

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 → .ai-factory/PLAN.md
• Full mode → .ai-factory/plans/<branch-name>.md (replace / with -)

Before saving, ensure directory exists:

mkdir -p .ai-factory/plans  # only when saving to branch-named plan files

Plan file must include:

• Title with feature name
• Branch and creation date
• Settings section (Testing, Logging, Docs)
• Roadmap Linkage section (optional, only if .ai-factory/ROADMAP.md exists)
• Research Context section (optional, if .ai-factory/RESEARCH.md exists)
• Tasks section grouped by phases
• Commit Plan section when there are 5+ tasks

If .ai-factory/ROADMAP.md 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 .ai-factory/RESEARCH.md 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.

/aif-implement

CONTEXT FROM /aif-plan:
- Plan file: .ai-factory/plans/<branch-name>.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: .ai-factory/plans/<branch-name>.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: .ai-factory/PLAN.md

To start implementation, run:
/aif-implement

To view tasks:
/tasks (or use TaskList)

Context Cleanup

Context is heavy after planning. All results are saved to the plan file — suggest freeing space:

AskUserQuestion: Free up context before continuing?

Options:
1. /clear — Full reset (recommended)
2. /compact — Compress history
3. Continue as is

---

--list Subcommand

When --list is passed, show all active worktrees and their feature status. Then STOP.

git worktree list

For each worktree path:

1. Check if <worktree>/.ai-factory/plans/ 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          (main)        <- 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 <branch> is passed, remove the worktree and optionally delete the branch. Then STOP.

DIRNAME=$(basename "$(pwd)")
BRANCH_DIR=$(echo "<branch>" | tr '/' '-')
WORKTREE="../${DIRNAME}-${BRANCH_DIR}"

git worktree remove "${WORKTREE}"
git branch -d <branch>  # -d (not -D) will fail if unmerged, which is safe

If git branch -d fails because the branch is unmerged:

Branch <branch> has unmerged changes.
To force-delete: git branch -D <branch>
To merge first: git checkout main && git merge <branch>

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: .ai-factory/PLAN.md. Full mode: .ai-factory/plans/<branch-name>.md
9. Ownership boundary — This command owns plan files only (.ai-factory/PLAN.md, .ai-factory/plans/<branch>.md). Use owner commands (/aif-roadmap, /aif-rules, /aif-explore) for their artifacts.
10. Roadmap linkage (when available) — If .ai-factory/ROADMAP.md exists, include a ## Roadmap Linkage section in the plan (or explicitly state it was skipped).

Plan File Handling

Fast mode (.ai-factory/PLAN.md)

• Temporary plan for quick work
• /aif-implement may offer deletion after completion

Full mode (.ai-factory/plans/<branch>.md)

• Branch-scoped, long-lived plan for feature delivery
• Used to resume work from current branch context

For concrete end-to-end flows (fast/full/full+parallel/interactive), read references/EXAMPLES.md (Flow Scenarios).