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:

Check if <worktree>/.ai-factory/plans/ contains any plan files
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

NO tests if user said no — Don't sneak in test tasks
NO reports — Don't create summary/report tasks at the end
Actionable tasks — Each task should have clear deliverable
Right granularity — Not too big (overwhelming), not too small (noise)
Dependencies matter — Order tasks so they can be done sequentially
Include file paths — Help implementer know where to work
Commit checkpoints for large plans — 5+ tasks need commit plan with checkpoints every 3-5 tasks
Plan file location — Fast mode: .ai-factory/PLAN.md. Full mode: .ai-factory/plans/<branch-name>.md
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.
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).

aif-plan

Safety Notice

Copy this and send it to your AI assistant to learn