using-superctx

SuperCtx Reference Guide (Agent Reference / Advanced)

This is an agent reference and advanced skill. Normal users do not need to run this; the agent uses it automatically to orient itself on how to interact with the project-local SuperCtx context hub.

When to Use

Use this skill whenever:

• A .ctx/ directory exists in the project root.
• The user asks about project context, agent instructions, or tool configuration.
• The user asks about sync, health, candidates, broken shims, or cross-tool context.
• The user asks to update or apply context changes across agents.

Core Model

SuperCtx provides a central project-local context layer using a hub-and-shim model:

• .ctx/SUPERCTX.md is the canonical project context hub.
• Tool-specific instruction files (e.g. .claude/CLAUDE.md, .codex/AGENTS.md) are generated shims/adapters pointing to the hub.
• .ctx/sources/ contains inactive recovery copies of original instruction files.

Edit Policy

When updating shared project context, the agent edits .ctx/SUPERCTX.md directly. The other managed files are not authoring surfaces.

Agent Rules

1. Stay quiet about internals. Do not explain hub/shim/backup mechanics unless the user asks. Use SuperCtx context naturally without announcing how it works.

2. Announce SuperCtx interactions. When SuperCtx is relevant or actively shaping the work, announce in one short sentence before taking action: Using SuperCtx to <purpose>. Keep the announcement task-specific.

3. Do NOT ask users to manually edit manifest.toml or SUPERCTX.md, or manually run /superctx:sync or /superctx:add as the happy path unless they explicitly ask for commands. Prefer agent action and internal command execution. If /superctx:sync reports setup, add, repair, or migration opportunities, offer the action in natural language and ask for consent.

4. Avoid saying "sync context" unless actually running /superctx:sync.

5. Do NOT read, import, or edit .ctx/sources/** as active context. .ctx/sources/ contains inactive recovery copies of original pre-SuperCtx files. These files are for recovery and audit only, not canonical editable context. When updating project context, edit .ctx/SUPERCTX.md.

6. Do NOT edit generated shims as the source of truth. Tool-specific files are thin generated pointers to .ctx/SUPERCTX.md.

7. Use /superctx:sync for convergence. It handles initialization, health checks, and repairs.

8. Offer agent-guided setup with explicit user consent when relevant. If a candidate repository is detected (no .ctx/ folder but candidate files exist), do not run /superctx:sync or mutate files without the user's explicit natural-language consent. Present the detected files, explain what setup will do, and ask for confirmation. Use this exact consent prompt:

   Using SuperCtx, I can set up one shared context hub for this repo.

   This will:

   • create .ctx/SUPERCTX.md
   • back up the original instruction files under .ctx/sources/
   • replace the live instruction files with generated shims pointing to the hub

   Proceed?

   Once the user confirms, run /superctx:sync. If the user declines, leave the repo unchanged.

9. Guide legacy or broken setups to repair/migration/inspection.

   • If /superctx:sync reports managed_needs_repair and the recommended action is repair, offer to repair the broken or missing shims and run /superctx:sync internally after getting consent.
   • If it reports inspect (due to missing or invalid manifest), explain the problem clearly and do not run sync or init.
   • If it reports legacy layout, explain the situation clearly, warning that migration/recovery is required. Preserve existing instruction contents and use explicit user-approved migration steps. Never run /superctx:sync or mutate files on a legacy/inspect state without explicit user consent.

Action Cues (Before Action)

Announce these cues before starting the corresponding action or command. Replace <path> with the actual file path.

Result Confirmation Phrases (After Action)

Use these phrases to report successful execution when the command output is healthy.

Command Guide

• /superctx:sync: Global setup, check, repair, and report command.
• /superctx:add <path>: Tracks a local custom candidate file.
• /using-superctx: Agent-facing reference skill.

Example Workflows

Workflow 1: Updating project instructions

• User: "Update the project instructions to include Y."
• Agent Action: Update .ctx/SUPERCTX.md, then run /superctx:sync to verify that registered shims are still healthy.

Workflow 2: Checking context for a specific tool

• User: "What context does Codex have?"
• Agent Action: Inspect the registered Codex shim, then read .ctx/SUPERCTX.md as the canonical project context. If freshness matters, run /superctx:sync.

Workflow 3: Checking connection and health

• User: "Is everything connected?"
• Agent Action: Run /superctx:sync.

Workflow 4: Repairing generated shims

• User: "The Codex instruction file is missing."
• Agent Action: Run /superctx:sync. If the registered shim is missing or broken, explain the issue and offer to repair the shims. Once the user gives consent, run /superctx:sync internally.

Workflow 5: Tracking a new instruction file

• User: "I added a new tool instruction file at .agy/ANTIGRAVITY.md."
• Agent Action: Explain that you can connect the new instruction file to the shared context hub, and offer to do so. Once the user gives consent, run /superctx:add .agy/ANTIGRAVITY.md internally.

Workflow 6: Agent-guided setup in a candidate repo

• Context: Session starts; hook reports candidate_repo with detected files .claude/CLAUDE.md and .codex/AGENTS.md.
• Agent Action: Present the detected files and make the consent-based offer (see Rule 8). Do not run /superctx:sync yet.
• User: "Yes, go ahead."
• Agent Action: Announce Using SuperCtx to set up the shared project context for this repo., then run /superctx:sync. Report the result concisely.