Mainline Intent Tracking Integration

Relevant source files

The following files were used as context for generating this wiki page:

• AGENTS.md
• CLAUDE.md
• skill-packages/cxs/SKILL.md
• CONTRIBUTING.md
• README.md

Mainline is a git-native intent memory layer implemented within the cxs project to facilitate AI-assisted engineering. Its primary purpose is to capture the historical "why" behind code changes, providing coding agents with context before they inspect the current state of the codebase. By recording intent claims, decisions, and risks, Mainline ensures that every AI-driven change is documented and that potential conflicts between different developer intents are surfaced before reaching the Pull Request (PR) review stage.

Sources: AGENTS.md:144-152, CLAUDE.md:1-8

In the current v0.3 implementation, Mainline maintains an invariant where every commit on the main branch exists in one of three states: covered (claimed by a sealed intent), skipped (explicitly ignored via config or git trailers), or uncovered.

Sources: AGENTS.md:154-159

Core Workflow and Lifecycle

The Mainline integration enforces an "intent-first" workflow. Agents are required to retrieve and understand relevant historical intents before performing any non-trivial code modifications.

The Intent-First Retrieval Flow

This diagram illustrates the mandatory steps an agent must take at the start of any task to align with the historical context of the repository.

Explanation: The workflow prioritizes status and context checks to ensure the agent understands the "why" before verifying the "what" via direct code inspection.
Sources: AGENTS.md:175-197

Lifecycle Stages of an Intent

Intents follow a specific progression from creation to permanent record. Agents use "turns" as a lightweight scaffold to track progress before the final seal.

1. Start: Claim the work with mainline start "<goal>".
2. Append: Record logical turns using mainline append "<change>" as subtasks complete or plans pivot.
3. Commit: Perform standard git operations (git add and git commit).
4. Seal: Submit the structured conclusion including decisions, risks, and fingerprints.

Sources: AGENTS.md:166-172, AGENTS.md:280-285, CLAUDE.md:14-22

Data Structures and Intent Metadata

Every retrieved intent provides structured data that dictates how an agent should process the information.

Intent Retrieval Status

Status	Interpretation	Action Required
current	Effective decision	Verify against current code and apply.
superseded	Replaced by newer intent	Read the superseded_by ID instead.
abandoned	Approach tried and failed	Do not repeat; understand the failure rationale.
stale	Old or high file churn	Verify if decisions still hold true.

Sources: AGENTS.md:199-206

Constraints: Risks and Anti-Patterns

Mainline distinguishes between soft warnings and hard constraints to guide future development.

• Risks: Soft warnings for reviewers to weigh during the PR process.
• Anti-Patterns: Hard constraints that must not be violated. Each anti-pattern must include a what (the violation), a why (the rationale), and a severity.

Sources: AGENTS.md:209-212, AGENTS.md:322-332

The Sealing Protocol

Sealing is the process of finalizing an intent. It involves a two-stage submission process designed to ensure worktree integrity and detect conflicts.

Sealing Sequence

Explanation: The sealing process captures a snapshot of the worktree at preparation time and validates it upon submission to prevent drift.
Sources: AGENTS.md:307-332

Conflict Detection and Checking

Mainline provides two phases of conflict detection:

1. Phase 1 (Automatic): Occurs during seal --submit. It checks for overlaps in files, subsystems, or tags against proposed and merged intents.
2. Phase 2 (Semantic): Triggered manually when Phase 1 flags an overlap. It requires an agent or human to provide a CheckJudgmentResult.

Sources: AGENTS.md:334-340, AGENTS.md:342-351

Integration and Tooling

Agent Hooks

Mainline can be integrated directly into agent runtimes (e.g., Cursor, Codex) as a context provider.

• Session Start: Hooks automatically run mainline sync and mainline status to inject a state snapshot into the system prompt.
• No-op Logic: Hooks do not make decisions (start, append, or seal); these remain purely agent-driven.

Sources: AGENTS.md:353-371, CLAUDE.md:25-30

The Hub

The Hub is a human-centric surface that exports a static HTML site of the local synced intent view. It allows users to browse file history, author rollups, and conflict graphs.

• Command: mainline hub open or mainline hub export <dir>.

Sources: AGENTS.md:373-383

Intent Rescue (Uncovered Commits)

When commits land on main without an associated intent (uncovered), Mainline provides rescue paths:

1. Unpushed: git reset --soft HEAD^ and restart the proper intent flow.
2. Pushed (Backfill): Start an intent claiming the specific commits via mainline start --commits <sha> and seal post-hoc.
3. Routine/Chore: Mark as skipped using the Mainline-Skip: <reason> git trailer or regex patterns in .mainline/config.toml.

Sources: AGENTS.md:386-412

Mainline Intent Tracking Integration transforms the development process from simple code editing to an intent-aware workflow, ensuring that the rationale behind every change is preserved and searchable for both human and AI collaborators.