Warm Up the Session

Load project context without changing the repository. Finish with a compact, self-contained handoff that can start the next task or a forked session.

Step 0: Resolve Context Paths

Use the nearest ancestor containing .ai-factory/ as the project root; otherwise use the current working directory. Read .ai-factory/config.yaml from that root first when it exists. Resolve:

• paths.description (default .ai-factory/DESCRIPTION.md)
• paths.architecture (default .ai-factory/ARCHITECTURE.md)
• paths.roadmap (default .ai-factory/ROADMAP.md)
• paths.research (default .ai-factory/RESEARCH.md)
• paths.rules_file (default .ai-factory/RULES.md)
• paths.rules (default .ai-factory/rules/)
• rules.base (default .ai-factory/rules/base.md)
• every named rules.<area> entry
• warmup.paths (default [])
• language.ui (default en)

Also retain these configured preferences for the handoff because they affect later workflow commands, even though warmup does not act on them:

• language.artifacts and language.technical_terms
• git.enabled, git.base_branch, git.create_branches, git.branch_prefix, and git.skip_push_after_commit
• workflow.plan_id_format and workflow.verify_mode

Resolve relative artifact and rule paths from the project root; keep absolute paths absolute. If config is missing or a required value is missing or empty, use its documented default. If config cannot be parsed confidently, report that and use defaults; do not modify it or invent semantics for unknown keys.

All user-facing output MUST use language.ui.

Step 1: Read Applicable Instructions

Read, when present:

• the repository-root AGENTS.md
• each AGENTS.md between the repository root and current working directory, from broadest to most specific
• .ai-factory/skill-context/aif-warmup/SKILL.md

Nested AGENTS.md files outside the current working-directory chain are scoped to future work in those directories. Do not load all of them during warmup. More specific AGENTS.md instructions override broader ones. The warmup skill-context file overrides this general skill when they conflict.

Step 2: Read Core Artifacts

Read every resolved file that exists, in this order:

1. DESCRIPTION
2. ARCHITECTURE
3. ROADMAP
4. RESEARCH
5. RULES: load from broadest to most specific: the top-level rules file, rules.base, then every named rules.<area> entry. Later, more specific rules override earlier ones: rules.<area> > rules.base > paths.rules_file. Keep every area rule tied to its configured area; never present it as a global rule.

Missing artifacts are normal. Record them as missing and continue.

For ultra research, derive research_bundles_dir as <parent(paths.research)>/research/. Read marked direct-child INDEX.md files only when they contain <!-- aif:research-mode:ultra --> exactly once. For bundles with Status: active, load the linked RESEARCH.md Active Summary and open questions. Do not load C4, ADR, dependency, or session-history details until a concrete task needs them.

Do not scan application code, plans, git history, external sources, or unrelated artifacts during warmup. The next task can load those on demand.

Additional Warmup Paths

Process warmup.paths in configured order after the core artifacts. Each entry may point to a file or directory:

• Require a sequence of non-empty strings. Report and ignore invalid entries; treat entries as literal paths, not glob patterns.
• Resolve entries from the project root and require the resolved path to remain inside it. Report and skip absolute paths and .. escapes.
• Read a file once when it is readable text, even if another entry or core artifact resolves to the same file.
• For a directory, recursively read text files in lexical path order.
• Do not follow symlinks. Skip binary files and VCS, dependency, build, cache, and coverage directories unless such a directory is itself the explicit entry.
• Never load likely secrets, credentials, tokens, or private keys from an extra path. Report the skipped path; an explicitly listed .env.example may be read.
• If an entry is missing, unreadable, or too large to load without crowding out the handoff, report it. For a large directory, inventory it, prioritize its root README* and INDEX* files, and list what was not loaded instead of silently truncating.

An absent or empty warmup.paths means no additional scan.

Step 3: Produce the Handoff

Return a concise summary with these sections:

• Configuration — resolved custom paths and configured language, git, and workflow preferences that can affect the next command, including warmup.paths
• Project — purpose, stack, and current state
• Architecture — important boundaries and entry points
• Direction — active roadmap priorities and research conclusions
• Rules — non-negotiable instructions and conventions
• Gaps — missing artifacts, contradictions, or open research questions
• Loaded — exact paths read
• Ready — state that context is loaded and the session can continue or be forked

Prefer facts that will affect later decisions. Do not reproduce whole artifacts. When two sources conflict, name both sources and the conflict instead of silently choosing one.

Artifact Ownership

• Primary ownership: none.
• All project files and AI Factory artifacts are read-only.

Boundaries

• Read-only: never create or modify files, code, branches, plans, or config.
• Do not start implementation in the same invocation.
• Do not ask setup questions unless the project root itself cannot be identified.
• Stop after the handoff so it remains a clean session fork point.