lee-to/ai-factory/aif-implement

Implement - Execute Task Plan

Execute tasks from the plan, track progress, and enable session continuation.

Workflow

Step 0 (pre): Detect Handoff Mode

Determine Handoff mode. If the caller passed HANDOFF_MODE and HANDOFF_SKIP_REVIEW as explicit text in the prompt, use those values. Otherwise, use the Bash tool:

Bash: printenv HANDOFF_MODE || true
Bash: printenv HANDOFF_SKIP_REVIEW || 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. Instead:

• No interactive questions: Do not use AskUserQuestion — use sensible defaults (auto-commit at checkpoints, skip pause prompts).
• No pause/resume prompts: Execute all tasks sequentially without stopping

for confirmation. Blocking integrity, safety, or requirement conflicts still stop with their defined non-interactive outcome.

When HANDOFF_MODE is NOT 1 (manual Claude Code session)

Handoff sync is handled inline — see Step 0.2 (after reading the plan file) for the task ID extraction and MCP sync trigger. The sync points are:

• On start (Step 0.2): handoff_sync_status → "implementing" (with paused: true)
• On checklist update (Step 3.6): handoff_push_plan with updated plan content
• On completion (Step 5): handoff_push_plan with final plan, then handoff_sync_status → "review" (with paused: true) or "done" (with paused: false when HANDOFF_SKIP_REVIEW=1)

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.

Step 0: Check Current State

FIRST: Determine what state we're in:

1. Read `.ai-factory/config.yaml` if it exists to resolve:
   - `paths.description`, `paths.architecture`, `paths.rules_file`, `paths.roadmap`, `paths.research`; derive `research_bundles_dir = <parent directory of paths.research>/research/`
   - `paths.plan`, `paths.plans`, `paths.fix_plan`, `paths.patches`
   - `paths.archive`
   - `paths.rules`
   - `language.ui`, `language.artifacts`
   - `git.enabled`, `git.base_branch`, `git.create_branches`
   - `workflow.plan_id_format` (default: `slug`) — used by branch-based plan discovery.
     Active values: `slug` and `sequential`. Discovery treats a root `*.md` as
     a full plan unless it is the resolved `paths.plan` or `paths.fix_plan`.
     Treat a direct child `*/index.md` as an ultra bundle only after reading it
     and confirming that it contains exactly one
     `<!-- aif:plan-mode:ultra -->`; ignore unrelated directories and never count
     phase files independently.
     When `sequential`, resolve both
     `<paths.plans>/[0-9]{4}_<branch-slug>.md` and
     `<paths.plans>/[0-9]{4}_<branch-slug>/index.md`, then choose the
     highest-numbered matching artifact.
     `timestamp` and `uuid` are **reserved values** and currently behave like `slug`.
     Treat any unknown value as `slug`.
   - `rules.base` plus any named `rules.<area>` entries
2. Parse arguments:
   - --list → list available plans only (no implementation; STOP)
   - --without-plan <description> → inline implementation mode; skip plan discovery and jump to Step 0.inline
   - @<path> → explicit plan file, ultra directory, or ultra `index.md` override (highest priority)
   - <number> → start from specific task
   - status → status-only mode
   - Optional inline-mode flag: --docs=yes|no|warn (only valid with --without-plan; default: warn)
3. If `git.enabled = true`, check for uncommitted changes (`git status`)
4. If `git.enabled = true`, check current branch

Step 0.list: List Available Plans (--list)

If $ARGUMENTS contains --list, run read-only plan discovery and stop.

1. Get current branch:
   git branch --show-current (git mode only)
2. Convert branch to canonical stem: replace "/" with "-" (git mode only)
3. Check existence of:
   - <configured plans dir>/<branch-stem>.md and
     <configured plans dir>/<branch-stem>/index.md (git mode only); Read the
     directory entrypoint and report it only when it contains exactly one
     `<!-- aif:plan-mode:ultra -->`
   - when `workflow.plan_id_format = sequential`: also glob
     `<configured plans dir>/[0-9][0-9][0-9][0-9]_<branch-stem>.md` and
     `<configured plans dir>/[0-9][0-9][0-9][0-9]_<branch-stem>/index.md`;
     Read every directory entrypoint, discard those without exactly one marker,
     and report all valid matches (highest-numbered first)
   - if git mode is off or branch creation is disabled: any root `*.md` full
     plan or declared-ultra direct child `*/index.md` entrypoint in
     `<configured plans dir>/`; exclude the resolved fast/fix plan paths
   - <resolved fast plan path>
   - <resolved fix plan path>
4. Print plan availability summary and usage hints
5. STOP.

Important: In --list mode:

• Do not execute tasks
• Do not modify files
• Do not update TaskList statuses

For detailed output format and examples, see:

• skills/aif-implement/references/IMPLEMENTATION-GUIDE.md → "List Available Plans (--list)"

Step 0.inline: Inline Implementation Mode (--without-plan)

If $ARGUMENTS contains --without-plan, execute a single scoped task from the description WITHOUT creating or reading any plan file. This is the lightweight path for small feat/chore tasks that do not justify a full plan but are not bug fixes either (use /aif-fix for bugs).

Argument parsing:

1. description = everything after `--without-plan`, excluding any recognized flag tokens (`--docs=...`).
2. docs_policy = value of `--docs=yes|no|warn` if present, else `warn` (default).
3. Validation:
   - description is empty →
     ERROR: "Usage: /aif-implement --without-plan <description> [--docs=yes|no|warn]"
     → STOP
   - arguments also contain `@<path>`, `status`, or a bare task id number →
     ERROR: "`--without-plan` is mutually exclusive with @plan-file, status, and task id."
     → STOP
   - `--docs=<value>` where <value> not in {yes, no, warn} →
     ERROR: "Invalid --docs value. Expected yes|no|warn."
     → STOP

Scope guard (prevent silent mega-tasks):

Before executing, assess the description. If it looks too broad for a one-shot inline task — multiple unrelated imperatives joined by "and"/"и", references to multiple subsystems, or roughly more than ~300 characters of scope — do NOT attempt to guess a plan. Instead print:

Description looks too broad for inline implementation. Recommended:
  /aif-plan fast <description>

→ STOP.

Small, focused descriptions (e.g. "add GET /healthz returning 200 with {status:\"ok\"}") proceed.

Surprise-warn on existing plan artifacts (non-blocking):

Inline mode ignores plan files by design. If any of these exist on disk, emit a WARN [inline] line so the user notices the intentional skip (do NOT read them, do NOT redirect):

• <configured plans dir>/<branch>.md or

<configured plans dir>/<branch>/index.md (git mode only) — or their [0-9]{4}_<branch> sequential forms

• resolved fast plan path (paths.plan)
• resolved fix plan path (paths.fix_plan)

Example: WARN [inline] paths.plan exists but is ignored in --without-plan mode.

Load project context (same as regular implement):

Use the resolved config from Step 0:

• paths.description (DESCRIPTION.md) if present
• paths.architecture (ARCHITECTURE.md) if present
• paths.rules_file (RULES.md) + rules.base + named rules.<area> entries
• .ai-factory/skill-context/aif-implement/SKILL.md — MANDATORY if the file exists (same precedence and enforcement as regular mode in Step 0.1)
• language.ui, language.artifacts

Plan artifact policy: inline mode does NOT load or use plan/fix-plan files. Plan files are never read, parsed, or executed. A minimal existence probe is permitted (see the surprise-warn section above) solely to emit the WARN [inline] line — nothing is read from disk. Also skip: resume/recovery reconciliation, TaskList loading, checkbox state comparison.

Execute the task (one-shot):

1. Announce: Inline implementation: <description>
2. Read only files relevant to the described scope
3. Apply changes following existing code patterns and skill-context rules
4. Apply verbose logging per references/LOGGING-GUIDE.md
5. Do not add tests by default. Add them only if the description explicitly requests tests (e.g. "with tests", "add tests for X") OR if existing project conventions / touched code paths clearly require them (e.g. a test file mirrors every source file in the area being changed, or a RULES.md / skill-context rule mandates test coverage for this kind of change). When in doubt, prefer NO tests and let the user follow up via /aif-plan if wider test coverage is needed.
6. Verify the change compiles/runs and the described behavior works

Prohibited in inline mode:

• Do NOT create or read paths.plan / paths.plans/* / paths.fix_plan.
• Do NOT invoke /aif-plan or /aif-fix.
• Do NOT create entries under paths.patches (no [FIX] self-improvement patch — this is not a bugfix flow).
• Do NOT call TaskList / TaskGet / TaskUpdate (no plan = no persisted tasks).
• Do NOT search for or modify plan checkboxes on disk.
• Do NOT trigger the roadmap milestone completion check, docs checkpoint-from-plan-setting, plan-file cleanup prompt, or worktree merge prompt (those belong to the plan-backed workflow).

Handoff inline support:

Naming clarification: --without-plan means "without a local plan artifact on disk" (no paths.plan / paths.plans/* / paths.fix_plan). When a Handoff task is linked, the task is still represented as a synthetic plan inside Handoff via handoff_push_plan — that's a remote representation, not a local file. The local-no-plan contract is preserved; only the remote sync surface is unchanged.

When `HANDOFF_MODE` is `1` (autonomous Handoff agent invoked inline mode):

• Do NOT call any mcp__handoff__* tool (the coordinator manages status/sync directly — same rule as Step 0 (pre)).
• Do NOT create local plan artifacts (the regular Prohibited list above still applies).
• Do NOT switch branches, create worktrees, merge worktrees, or otherwise alter the branch/worktree the coordinator set up — inline mode operates on the working tree it was invoked in.
• Proceed with the one-shot execution; the coordinator marks the task complete after the skill returns.

When `HANDOFF_MODE` is NOT `1` and `HANDOFF_TASK_ID` is set (manual Claude Code session linked to a Handoff task):

1. Build synthetic plan content:

```markdown # Inline implementation

• [ ] <description>

```

1. Call handoff_sync_status with { taskId: <HANDOFF_TASK_ID>, newStatus: "implementing", sourceTimestamp: "<current UTC ISO 8601>", direction: "aif_to_handoff", paused: true }.
2. Call handoff_push_plan with { taskId: <HANDOFF_TASK_ID>, planContent: <synthetic content above> }.
3. After successful execution, flip the checkbox to - [x] in the synthetic content and call handoff_push_plan again with the updated text.
4. Finalize sync:

• If HANDOFF_SKIP_REVIEW is 1 → handoff_sync_status → "done" with paused: false.
• Otherwise → handoff_sync_status → "review" with paused: true.

If HANDOFF_TASK_ID is missing → skip all MCP sync for this run.

Docs policy (inline mode, driven by `--docs`):

• --docs=yes → after completion, show the docs checkpoint (same AskUserQuestion as Docs: yes in regular mode) and route changes through /aif-docs.
• --docs=no → suppress the documentation checkpoint, emit WARN [docs] --docs=no in inline mode; documentation checkpoint skipped.
• --docs=warn (default) → emit WARN [docs] Inline mode default is warn-only; documentation checkpoint skipped. Pass --docs=yes to enable.