lee-to/ai-factory/aif-loop

Loop - Reflex Iteration Workflow

Run a result-focused iterative loop with strict phase contracts, evaluation rules, and persistent state between sessions.

Step 0: Load Config

FIRST: Read .ai-factory/config.yaml if it exists to resolve:

• Paths: paths.description, paths.architecture, paths.rules_file, paths.roadmap, paths.plan, paths.plans, and paths.evolution
• Language: language.ui for prompts, language.artifacts for generated content

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

• Paths: .ai-factory/ for all artifacts
• Language: en (English)

Terminology:

• loop = one full execution for a task alias (stored in run.json, identified by run_id)
• iteration = one cycle inside that loop

Core Idea

Each iteration executes 6 phases with parallel execution where possible:

1. PLAN - short plan for current iteration
2. PRODUCE - produce one artifact.md ← runs in parallel with PREPARE
3. PREPARE - generate check scripts and test definitions from rules ← runs in parallel with PRODUCE
4. EVALUATE - run prepared checks + content rules against artifact, score result. Uses parallel Task agents for independent check groups
5. CRITIQUE - precise issues + fixes (only if fail)
6. REFINE - rewrite artifact using critique (only if fail)

         PLAN
           │
    ┌──────┴──────┐
    ↓             ↓          ← parallel (Task tool)
 PRODUCE      PREPARE
 (artifact)   (checks)
    ↓             ↓
    └──────┬──────┘
           ↓
       EVALUATE              ← parallel check execution (Task tool)
       ┌───┼───┐
       ↓   ↓   ↓
      exec content aggregate
       └───┼───┘
           ↓
       CRITIQUE (if fail)
           ↓
       REFINE (if fail)

Stop when quality is good enough, no major issues remain, the user stops the run, progress stagnates, or a resource guard trips (optional time budget, iteration limit). The full precedence order is in Step 5.

Persistence Contract

Use exactly 3+1 files for state inside the resolved evolution directory (where current.json exists only while a loop is active):

<resolved evolution dir>/current.json
<resolved evolution dir>/<task-alias>/run.json
<resolved evolution dir>/<task-alias>/history.jsonl
<resolved evolution dir>/<task-alias>/artifact.md

Do not create extra index files or per-iteration folder trees unless user explicitly asks.

File Roles

• current.json: pointer to active loop only; delete it when loop becomes completed/stopped/failed
• run.json: single source of truth for current loop state
• history.jsonl: append-only event log (one JSON object per line)
• artifact.md: single source of truth for artifact content (written after PRODUCE and REFINE phases, never duplicated in run.json)

Command Modes

Parse $ARGUMENTS:

• status - show active loop status from current.json and stop
• resume [alias] - continue active loop or loop by alias
• stop [reason] - stop active loop with reason (user_stop if omitted)
• new <task> or no mode + task text - start new loop
• list - list all task aliases with status (running/stopped/completed/failed)
• history [alias] - show event history for a loop (default: active loop)
• clean [alias|--all] - remove loop files for a stopped/completed/failed loop (requires user confirmation, always confirm before deleting)

If no task and no active loop exists, ask user for task prompt.

Step 0: Load Context

Read these files if present:

• the resolved description path
• the resolved architecture path
• the resolved RULES.md path

Use them to keep outputs aligned with project conventions.

Read `.ai-factory/skill-context/aif-loop/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 generated

artifact, run state, and evaluation criteria. If a skill-context rule says "artifact MUST include X" or "evaluation MUST check Y" — you MUST comply. Producing loop outputs that violate 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.

Step 0.1: Handle Non-Iteration Commands

If command is status, stop, list, history, or clean, execute and stop:

• `status`: read current.json; if file exists, read pointed run.json and display alias | status | iteration | phase | current_step | last_score | updated_at, plus completed_phase_seconds / max_completed_phase_seconds when a budget is set; if file is missing, report that no loop is active
• `stop [reason]`: stop active running loop only; set run.json.status = "stopped" and run.json.stop.reason = <reason or "user_stop">, append stopped event to history.jsonl, then delete current.json (active pointer cleared) and exit
• `list`: scan the resolved evolution directory, read each run.json, display table of alias | status | iteration | last_score | updated_at
• `history [alias]`: read history.jsonl for the alias (or active loop), display formatted event timeline
• `clean [alias|--all]`: show what will be deleted, ask for explicit user confirmation via AskUserQuestion, then delete loop directory. Only clean stopped/completed/failed loops — refuse to clean running loops. Update current.json if needed.

Step 1: Initialize or Resume Loop

1.1 Ensure directories

mkdir -p <resolved evolution dir>

1.2 Alias and IDs (new loop)

Generate:

• task_alias: lowercase hyphen slug (3-64 chars)
• run_id: <task_alias>-<yyyyMMdd-HHmmss>

1.3 Write current.json

{
  "active_run_id": "courses-api-ddd-20260218-120000",
  "task_alias": "courses-api-ddd",
  "status": "running",
  "updated_at": "2026-02-18T12:00:00Z"
}

1.4 Write initial run.json

{
  "run_id": "courses-api-ddd-20260218-120000",
  "task_alias": "courses-api-ddd",
  "status": "running",
  "iteration": 1,
  "max_iterations": 4,
  "max_completed_phase_seconds": null,
  "completed_phase_seconds": 0,
  "phase_started_epoch_seconds": null,
  "phase": "A",
  "current_step": "PLAN",
  "task": {
    "prompt": "OpenAPI 3.1 spec + DDD notes + JSON examples",
    "ideal_result": "..."
  },
  "criteria": {
    "name": "loop_default_v1",
    "version": 1,
    "phase": {
      "A": { "threshold": 0.8, "active_levels": ["A"] },
      "B": { "threshold": 0.9, "active_levels": ["A", "B"] }
    },
    "rules": []
  },
  "plan": [],
  "prepared_checks": null,
  "evaluation": null,
  "critique": null,
  "stop": { "passed": false, "reason": "" },
  "last_score": 0,
  "stagnation_count": 0,
  "created_at": "2026-02-18T12:00:00Z",
  "updated_at": "2026-02-18T12:00:00Z"
}

1.5 Resume Logic

When resuming a loop:

1. Read run.json to get current_step and iteration
2. Read last event from history.jsonl to confirm consistency
3. If run.json.current_step indicates a phase was interrupted:

• Re-execute from that phase (do not skip)
• PRODUCE_PREPARE: always re-run both PRODUCE and PREPARE (idempotent — artifact overwrites, checks regenerate)

1. If run.json.status is stopped, completed, or failed, inform user and suggest new (for failed runs, also show the last phase_error event from history.jsonl so user understands what went wrong)
2. Discard a stale phase_started_epoch_seconds: set it to the current date +%s when the interrupted phase actually re-starts. The interrupted attempt contributes nothing to the budget — only completed_phase_seconds already accumulated from finished segments carries over (see references/ACTIVE-TIME-BUDGET.md).

Step 2: Interactive Setup (new loop)

Quick mode (default, confirmation-first)

If the task prompt contains enough context to infer task type and ideal result:

1. Auto-detect task type from prompt (API spec, code, docs, config)
2. Load matching template from references/CRITERIA-TEMPLATES.md
3. Draft inferred rules, phase thresholds (fallback: A=0.8, B=0.9), max iterations (default: 4), and a completed-phase time budget (default: none; infer one only per the setup rules in references/ACTIVE-TIME-BUDGET.md)
4. Show inferred settings as a draft summary, with the normalized budget next to max iterations
5. Always ask explicit confirmation of success criteria (rules/thresholds) via AskUserQuestion, even if criteria were already present in the task text
6. Always ask explicit confirmation of max iterations via AskUserQuestion, even if iteration count was already present in the task text
7. Ask explicit confirmation of the time budget via AskUserQuestion whenever the drafted value is not null, always offering none as an option
8. If user changes criteria, max iterations, or the budget, update the draft and re-confirm all three fields
9. Start iteration 1 only after the confirmations are explicit
10. If task type cannot be auto-detected (ambiguous or mixed prompt), fall through to full setup immediately

Full setup

Critical guardrail:

• Always re-ask and explicitly confirm success criteria and max iterations, even if both are already written in the task prompt.

Ask concise setup questions before first iteration:

1. Task type - what kind of artifact? (API spec, code, docs, config, other) - used to load template from references/CRITERIA-TEMPLATES.md
2. Ideal result definition
3. Mandatory checks (tests, schema/contract, specific requirements)
4. Quality threshold (A/B phases)
5. Max iterations (default: 4)
6. Completed-phase time budget in seconds (default: none) — offer none explicitly; a domain-level timeout is not a loop budget
7. What counts as a major issue
8. Explicit confirmation: "Confirm these success criteria?"
9. Explicit confirmation: "Confirm max iterations = N?"
10. Explicit confirmation of the budget when it is not none: "Confirm time budget = N seconds?"

Generate evaluation rules from answers:

• Load matching template from references/CRITERIA-TEMPLATES.md as starting point
• Add task-specific rules based on ideal result and mandatory checks
• Let user review and adjust rules before starting

Persist answers and generated rules inside run.json.criteria (snapshot for reproducibility).

Never treat criteria, iteration limits, or a time budget parsed from task text as final until the user explicitly confirms them.

Normalization rules before persisting: