Skip to content

10-session-bootstrap.md

Latest commit

 

History

History
62 lines (53 loc) · 3.33 KB

10-session-bootstrap.md

File metadata and controls

62 lines (53 loc) · 3.33 KB
Raw
layout default
title Agent session bootstrap
permalink /contributing/agent-rules/session-bootstrap/
description Deterministic startup sequence for repository sessions after AGENTS.md is loaded.
keywords
agents
bootstrap
worktree
cache
instructions
audience
team
enterprise
expertise_level
advanced
doc_owner specfact-cli-modules
tracks
AGENTS.md
docs/agent-rules/**
.specfact/backlog/github_hierarchy_cache.md
scripts/sync_github_hierarchy_cache.py
last_reviewed 2026-10-05
exempt false
exempt_reason
id agent-rules-session-bootstrap
always_load true
applies_when
session-bootstrap
priority 10
blocking true
user_interaction_required true
stop_conditions
unsupported branch or worktree context
cache-dependent GitHub work without refreshed hierarchy cache
depends_on
agent-rules-index
agent-rules-non-negotiable-checklist

Agent session bootstrap

Required startup checks

  1. Detect repository root, active branch, and whether the session is running in a worktree.
  2. If the session is on dev or main, do not implement until the user explicitly allows it or a worktree is created.
  3. Confirm AGENTS.md is already loaded, then load the rule index and non-negotiable checklist.
  4. Determine whether the task is read-only, artifact-only, or implementation work.
  5. If GitHub hierarchy data is required, confirm .specfact/backlog/github_hierarchy_cache.md is present and fresh enough for the task.
  6. If the cache is missing or stale, refresh it with python scripts/sync_github_hierarchy_cache.py.
  7. Load the additional rule files required by the task signal from the index.
  8. Apply 15-intent-and-scope.md; reuse confirmed intent and decisions from the session, and identify consequential gaps before architectural work. Do not require clarification for read-only explanations or routine choices with clear scope.

Hatch environment bootstrap

  • In a fresh worktree, run the first Hatch command serially and wait for it to complete before starting any other hatch run ... process.
  • Do not launch parallel Hatch commands until the worktree environment has successfully run hatch run python -m pip --version or another Hatch command that proves the environment is fully created.
  • If Hatch reports missing pip._internal modules or other partial pip imports, treat the local .venv as corrupted: remove the Hatch environment, recreate it with one serial Hatch command, and retry validation only after pip is healthy.
  • Do not interpret Hatch environment-creation failures as code failures until the local environment has been recreated serially.

Stop and continue behavior

  • If the session is on the main checkout and the user did not override, stop implementation and create or switch to a worktree.
  • If the requested work is tied to stale or ambiguous change metadata, continue only in read-only investigation mode until the user clarifies.
  • If GitHub hierarchy metadata is needed and the cache cannot answer after refresh, manual GitHub lookup is allowed.
  • If the task is purely explanatory or read-only, full implementation gates do not need to run.

Why this file exists

This file keeps session bootstrap deterministic after AGENTS.md becomes compact. It is small enough to load every time, but specific enough to prevent drift across models and sessions.