Repo Context Forge
Relevant source files
The following files were used as context for generating this wiki page:
Repo Context Forge serves as the global gate for all repository-based operations, including coding, debugging, review, and exploration. It injects a targeted context packet that establishes the initial target and coverage surface before any code reasoning or editing begins. This system ensures that the agent operates with a verified understanding of the repository's state, blast radius, and execution flow.
The module integrates heavily with GitNexus to provide graph-based evidence of symbol relationships and impacts. It acts as the mandatory first step in the Repo Production Workflow to prevent "empty target" analysis and ensure that every production edit is grounded in pre-validated repository data.
Sources: CLAUDE.md:275-279, skills/repo-context-forge/SKILL.md:9-11
Global Workflow Integration
Repo Context Forge is a mandatory global gate. You must run it before choosing files, editing code, or executing GitNexus analysis, except for documentation-only changes. In a governed production pass, the bootstrap.py script records the step and establishes an immutable baseOid for branch-cumulative growth tracking.
The diagram shows the standard progression from initial request to production preflight, highlighting Repo Context Forge as the bridge between workflow initialization and detailed analysis.
Sources: CLAUDE.md:280-285, skills/repo-production-workflow/SKILL.md:43-52, skills/repo-large-implementation/SKILL.md:12-20
Operation Modes
The system automatically selects an operation mode based on the current state of the repository and the nature of the task.
| Mode | Trigger Condition | Focus |
|---|---|---|
pr | A base ref is available and base...HEAD has changed files. | Change detection between base and head. |
local | Dirty local work exists before a PR is pushed. | Uncommitted changes in the worktree. |
intent | No current changes; user provides an --intent description. | Task-ranked targets based on planned work. |
repo | Clean checkout with no diff or provided intent. | Whole-repo context for broad exploration. |
Sources: skills/repo-context-forge/SKILL.md:144-151
The Context Packet
The successful execution of the bootstrap script produces a packet starting with the banner REPO_CONTEXT_FORGE_REQUIRED_INTAKE. This packet contains several critical components that govern subsequent agent behavior.
Packet Components
- Context Digest: Summarizes mode, head SHA, token budget, and top targets.
- Scope Rules: Defines how to handle delegation, GitNexus calls, and target narrowing.
- Coverage Plan: Lists specific areas that must be satisfied before proceeding to edits or findings.
- SoulForge Impact: Provides blast-radius context using repository-map data.
- GitNexus Analysis: Contains pre-executed symbol context and impact checks.
Sources: skills/repo-context-forge/SKILL.md:46-60, skills/repo-context-forge/SKILL.md:92-100
GitNexus and SoulForge Coordination
Repo Context Forge coordinates two primary analysis engines: SoulForge and GitNexus. While SoulForge focuses on the repository-map blast radius, GitNexus validates execution flows and symbol-level relationships.
The sequence illustrates the pre-computation of graph evidence during the bootstrap phase, reducing the need for redundant MCP calls during exploration.
Sources: skills/repo-context-forge/SKILL.md:107-115, skills/repo-production-workflow/SKILL.md:58-63
Revalidation and Turn Refresh
For long-running tasks or post-edit verification, Repo Context Forge provides mechanisms to refresh context and revalidate the target surface.
Turn Refresh Procedure
When the task context changes materially, you must refresh the packet:
- Start task context with
context-start. - Record activities using
context-record-read,search, andedit. - Execute
context-refreshto boost relevant files in the next packet.
Post-Edit Revalidation
After final production edits, run the bootstrap with the --revalidate flag. This forces local mode and skips the heavy SoulForge map rebuild while re-recording snapshot-bound graph evidence. This step is critical for the production-code quality gate to evaluate "owner competition" rules against the actual candidate tree.
Sources: skills/repo-context-forge/SKILL.md:126-136, skills/repo-context-forge/SKILL.md:167-175
Execution Requirements and Constraints
- Bootstrap first: Never edit files or narrow to single symbols before reading the packet.
- Intent integrity: When beginning a workflow, the exact request text must be passed to
--intentto ensure the recorded contract is not corrupted by paraphrasing. - Analysis checkouts: Packets are generated from cache-owned analysis checkouts to keep the user's worktree clean.
- Blocker handling: If a blocker occurs (e.g., detached head, empty targets), all repository analysis must stop until the environment is corrected.
Sources: skills/repo-context-forge/SKILL.md:39-44, skills/repo-production-workflow/SKILL.md:32-37, skills/repo-context-forge/SKILL.md:153-156
Repo Context Forge ensures that all repository work begins with a high-fidelity, data-backed intake. By centralizing initial exploration and blast-radius analysis, it provides the necessary "Forge Packet" that drives predictable and safe implementation through the Repo Production Workflow.