Skip to main content

Agent Awareness Adoption

This spec defines how X4 makes agents aware of X4 workspaces without silently rewriting tracked repo policy files during normal workspace creation.

Problem​

Agents only reliably learn about X4 when a repo-level AGENTS.md tells them to read the generated .x4/ context. Workspace bootstrap already generates .x4/context.md, .x4/agent-instructions.md, and .x4/commands.md, but agents may not discover those files unless the stable repo pointer exists.

At the same time, AGENTS.md is tracked repo policy. Updating it on every feature workspace would create dirty tracked files, merge noise, and surprising repo mutations.

Decision​

X4 separates agent adoption from workspace creation.

  • x4 workspace bootstrap must not silently edit tracked AGENTS.md files.
  • x4 workspace bootstrap must detect missing X4 agent pointers and print a clear next step.
  • x4 agents bootstrap-pr remains the explicit adoption command that appends the stable AGENTS.md pointer.
  • Cursor and VS Code should surface missing agent adoption as an action, not silently apply it.

Desired User Flow​

First-time repo-set adoption:

x4 workspace bootstrap --entry "$PWD" --repo-set <repo-set>

If one or more workspace repos are missing the X4 pointer, bootstrap prints:

warn agent awareness incomplete: AGENTS.md X4 pointer missing in 3 repos
  missing: app, api, web
next:
  x4 agents bootstrap-pr --entry "$PWD" --dry-run
  x4 agents bootstrap-pr --entry "$PWD"

The user previews and applies the adoption change:

x4 agents bootstrap-pr --entry "$PWD" --dry-run
x4 agents bootstrap-pr --entry "$PWD"

Then the user reviews, commits, and opens a normal repo PR for the stable AGENTS.md pointer. After that PR is merged, future X4 workspaces are agent-aware automatically because the tracked AGENTS.md points agents to the generated .x4/context.md.

Stable Pointer Content​

The adoption command appends this stable section when missing:

## X4 workspaces

If `.x4/context.md` exists, read it before editing code. Use it as the source of
truth for related repos, branches, sandbox profile, and test commands.

Use:
- `x4 workspace bootstrap`
- `x4 status`
- `x4 workspace commit -m "message"`
- `x4 test`
- `x4 sandbox up`
- `x4 preview up`
- `x4 pr plan`
- `x4 pr create --dry-run`
- `x4 cleanup`

Keep changes and PR summaries split by repository.

The pointer is intentionally generic. Feature-specific context stays in generated .x4/ files.

CLI Behavior​

x4 workspace bootstrap​

After writing workspace files, bootstrap should inspect each repo in workspace.repos:

  • AGENTS.md missing: report missing pointer.
  • AGENTS.md exists without ## X4 workspaces: report missing pointer.
  • AGENTS.md already contains ## X4 workspaces: report nothing.

Bootstrap exits successfully even when pointers are missing. Missing pointers are an adoption warning, not a workspace creation failure.

x4 doctor agents​

doctor agents remains the detailed diagnostic command. It should report each repo as ok or warn, including whether AGENTS.md exists and whether the X4 pointer is present.

x4 agents bootstrap-pr​

The adoption command must be:

  • idempotent: running it twice does not duplicate the section;
  • append-only: existing repo guidance is preserved;
  • explicit: no writes happen in workspace bootstrap;
  • reviewable: --dry-run prints every file that would change;
  • multi-repo aware: it handles every repo in the current X4 workspace.

The command name says bootstrap-pr because the output should be committed and reviewed like a normal repo policy PR. It does not need to create the PR itself in the first implementation.

Cursor And VS Code Behavior​

The extension should expose the same model:

  • show an Agent Pointer row when an X4 workspace is open;
  • show ok when all workspace repos contain the pointer;
  • show Missing in N repos when adoption is incomplete;
  • offer commands:
    • X4: Check Agent Pointers;
    • X4: Preview AGENTS.md Pointer Changes;
    • X4: Apply AGENTS.md Pointer Changes.

After X4: Bootstrap and Open, the extension should run the pointer check and surface a non-blocking prompt when adoption is incomplete:

X4 agent pointer missing in 3 repos.
[Preview Changes] [Apply Pointer] [Skip]

Apply Pointer must call the explicit CLI adoption command. The extension should not mutate AGENTS.md directly.

Non-Goals​

  • Do not make every workspace bootstrap dirty tracked files.
  • Do not write feature-specific instructions into AGENTS.md.
  • Do not require the pointer for metadata-only bootstrap to succeed.
  • Do not ask an AI model to edit AGENTS.md; the pointer is deterministic.

Acceptance Criteria​

  • Creating a workspace with missing pointers exits successfully and prints the exact adoption next step.
  • Creating a workspace with all pointers present prints no warning.
  • x4 agents bootstrap-pr --dry-run shows all repos that would change.
  • x4 agents bootstrap-pr appends the section once per missing repo.
  • Running x4 agents bootstrap-pr twice is a no-op on the second run.
  • Cursor shows missing agent adoption immediately after bootstrap.
  • Cursor applies adoption only by invoking the CLI.
  • Generated .x4/context.md remains the source of per-workspace context.

Implementation Notes​

The current CLI already has the explicit adoption command and the doctor check. The missing product behavior is the bootstrap-time warning and the editor surface that makes the first-time adoption step obvious.