config-export

config-export

Exports CLAUDE.md and ai-context/ to tool-native instruction files for GitHub Copilot, Google Gemini, and Cursor.

Triggers: /config-export, export config, copilot instructions, gemini config, cursor rules

Purpose

config-export reads a source configuration bundle, lets the user select one or more target AI assistants, generates tool-specific instruction files via LLM transformation, shows a dry-run preview, and writes the confirmed files to their canonical locations. It never modifies source files and never writes without explicit user confirmation.

Two source modes:

Core mode (preferred when core/ exists): the agent-config repo's tool-neutral core/ directory (persona, protocols, methodology, format-types) is the single source of truth. Because core/ is already strip-free (no ~/.claude/ paths, no slash commands), the heavy STRIP preamble collapses to a thin guard — see "STRIP in core mode" below. Detect by the presence of core/PORTABILITY.md at the repo root.
Project mode (fallback): the consumer project's CLAUDE.md + ai-context/ files, as described in Step 1. Used when no core/ is present (a downstream consumer project, not the agent-config repo itself).

Process

Step 1 — Source collection

Mode detection (first): If core/PORTABILITY.md exists at the repo root, use core mode: bundle core/instructions/*.md, core/protocols/*.md, core/methodology/*.md, and core/format-types.md as the source. Skip the CLAUDE.md/ai-context guards below (they are project-mode only) and proceed to Step 2. Note "core mode — neutral source" in the transformation context. Otherwise, use project mode and apply the guards below.

Guard — no CLAUDE.md: If no CLAUDE.md exists in the current working directory, present the user with two paths:

No CLAUDE.md found in the current directory.

Choose an option:
  1. project-setup first  — run /project-setup to scaffold CLAUDE.md + ai-context/ in this project,
                            then re-run /config-export (recommended for new projects with SDD workflow)
  2. SDD bootstrap         — generate a minimal .github/copilot-instructions.md from the global SDD
                            template only (no project-specific stack or conventions)

Enter 1 or 2 (or press Enter to cancel):

If the user selects 1: emit Run /project-setup, then re-run /config-export and stop. No files are written.
If the user selects 2: proceed using the global SDD methodology as the sole source bundle (skip ai-context/ collection; note "No project CLAUDE.md — bootstrap mode" in transformation context).
If the user cancels: emit Export cancelled — no files written and stop.

Guard — no ai-context/: If no ai-context/ directory is present, emit:

WARNING: ai-context/ not found — export quality will be lower; only CLAUDE.md will be used as source

Continue; CLAUDE.md alone is sufficient.

Read and bundle source files in priority order:

#	File	Required?	Behavior when absent
1	`CLAUDE.md`	Yes	Halt (see guard above)
2	`ai-context/stack.md`	No	Skip; note "stack.md not available" in transformation context
3	`ai-context/architecture.md`	No	Skip; note "architecture.md not available" in transformation context
4	`ai-context/conventions.md`	No	Skip; note "conventions.md not available" in transformation context
5	`ai-context/known-issues.md`	No	Skip silently if absent

All present files are read into the in-context bundle before any transformation begins.

Step 2 — Target selection

If the user provided a target as a CLI argument (e.g., /config-export copilot), skip the interactive menu and proceed directly to Step 3 with that target.

Otherwise, present the target menu:

Available export targets:

  1. copilot  →  .github/copilot-instructions.md
  2. gemini   →  GEMINI.md
  3. codex    →  AGENTS.md
  4. cursor   →  .cursor/rules/conventions.mdc
               →  .cursor/rules/stack.mdc
               →  .cursor/rules/architecture.mdc
               (adapter spec: adapters/cursor/target.md)
  5. agents   →  per-tool custom-agent render (deterministic)
               →  copilot: .github/agents/<name>.agent.md
               →  cursor:  .cursor/rules/agent-<name>.mdc

Enter targets (comma-separated numbers or names, or "all"):

Deterministic delegation (agents + command mode): the agents target and command mode (Step 3-CMD) are deterministic envelope-wraps, single-sourced in the standalone splitter. When Bash is available, DELEGATE the render to core/scripts/config-export.sh <tool> <target-project-dir> --constructs=agents (or --constructs=commands) instead of re-implementing the wrap in-context — one implementation, zero divergence. Fall back to the in-context deterministic procedure (per adapters/<tool>/target.md envelope sections and command-mode.md) only when the script cannot run. Agent envelope specs: adapters/copilot/target.md § "Agent envelope", adapters/cursor/target.md § "Agent envelope (PROVISIONAL)".

Claude target rejection: If the user requests target claude or CLAUDE.md, respond with:

The Claude target is not supported in V1 — refresh CLAUDE.md manually

Do not write any files; re-present the menu or halt based on user choice.

Step 3 — Dry-run generation and confirmation

For each selected target, apply the corresponding transformation prompt (full prompts in transformation-prompts.md — see "Transformation prompts" below). Then:

Display the full generated content for each file and its destination path.
If a target output file already exists at its canonical path, emit a warning before the confirmation prompt:
```
WARNING: Overwriting existing file: <path>
```
Prompt the user:
```
Write these files? [y/N]
```
Default is N.
If the user responds with anything other than y, exit cleanly:
```
Export cancelled — no files written
```
No files are written.
If the user responds y, proceed to Step 4.

Transformation prompts (per target)

The full transformation contract — the Shared STRIP Preamble plus the four per-target STRIP/ADAPT/RETAIN/FORMAT prompts — lives in transformation-prompts.md to keep this SKILL.md within the 450-line budget (docs/config-guidelines.md Principle 4). READ that file before generating any target — the summary below is orientation, not the contract. The prompts are self-instructions applied via in-context LLM reasoning; no external API call or subprocess is involved.

Target	Output	Transformation core
copilot	`.github/copilot-instructions.md` — single flat file, fixed H2 section order	STRIP Claude Code machinery + Plan Mode; ADAPT SDD workflow to declarative prose + `## Active SDD Coaching Instructions`; maximum-parity `## Rules` (parity wins over brevity)
gemini	`GEMINI.md` at project root — CLAUDE.md-like H2/H3 hierarchy	STRIP SDD DAG + Claude-specific artifact storage; adapt command tables to prose, no slash commands
codex	`AGENTS.md` at project root — flat, ~32 KiB budget, merged root→cwd by Codex	Same content contract as Copilot; SDD workflow as declarative prose
cursor	`.cursor/rules/{conventions,stack,architecture}.mdc` — exactly three domain files	Split by domain; MDC frontmatter contract (`description`/`globs`/`alwaysApply`; `globs: ""` when no pattern can be inferred — never guess)

All targets: apply the Shared STRIP Preamble (thin guard in core mode), begin with the generated-file banner (see Step 4) dated today, UTF-8 no BOM.

Step 3-CMD — Command mode (invocable SDD commands)

Command mode renders the SDD pipeline skills as invocable commands for Copilot, Gemini, and Codex (selected via /config-export --commands). It is a deterministic envelope-wrap of the neutral logic (see ADR-006), gated by the BLOCKING STRIP guard, and injects the once-per-file memory-contract prelude after the guard passes.

The full command-mode contract — source scope, per-tool envelope table, STRIP guard, and memory-contract prelude injection — lives in command-mode.md to keep this SKILL.md within the 450-line budget (docs/config-guidelines.md Principle 4). Read it before running command mode.

Step 4 — File writing

For each confirmed target:

Create required directories silently if they do not exist:
- Copilot: .github/
- Cursor: .cursor/rules/
- Gemini: no directory required (file at project root)
- Codex: no directory required (AGENTS.md at project root)
- Do NOT emit any output for directory creation unless it fails.

Write the generated file to its canonical path, prepending the generated-file banner:

<!-- GENERATED BY config-export — DO NOT EDIT MANUALLY -->
<!-- Source: CLAUDE.md + ai-context/ | Generated: YYYY-MM-DD -->
<!-- Re-generate: run /config-export in your Claude Code session -->

Replace YYYY-MM-DD with today's date.

Overwrite any existing file at the canonical path — this is idempotent behavior. No error is raised when overwriting.

Step 5 — Summary

After all confirmed files have been written, print a summary table:

Export complete — files written:

  File                                  Status
  ──────────────────────────────────    ───────
  .github/copilot-instructions.md       written
  GEMINI.md                             written
  AGENTS.md                             written
  .cursor/rules/conventions.mdc         written
  .cursor/rules/stack.mdc               written
  .cursor/rules/architecture.mdc        written

(Only include rows for targets that were written in this run.)

Then append the snapshot reminder:

Exported files are snapshots. Re-run /config-export after significant changes to CLAUDE.md or ai-context/

Rules

If no CLAUDE.md is found in CWD, the skill MUST present the two-path menu (project-setup or bootstrap) before any file write; the hard ERROR path is NOT the default
Bootstrap mode (option 2) MUST produce a valid Copilot instructions file containing the full SDD workflow and coaching instructions even when no project CLAUDE.md exists
The Copilot transformation MUST NOT strip the SDD phase workflow or artifact paths — it MUST adapt them to prose and Copilot coaching instructions
The ## SDD Development Workflow and ## Active SDD Coaching Instructions sections MUST always be present in the Copilot output (whether from project mode or bootstrap mode)
Dry-run preview MUST precede any file write — there is no flag to skip dry-run
Overwrite warnings MUST appear in the dry-run step (before user confirmation), not after
The skill MUST NOT modify CLAUDE.md or any ai-context/ file — read-only with respect to all source files
Directory creation (.github/, .cursor/rules/) MUST be silent — no output for directory creation unless it fails
The Claude target (CLAUDE.md) is NOT supported in V1 — respond with the defined rejection message; do not write any files for that target
All generated files MUST be UTF-8, no BOM
Each Cursor .mdc file MUST have valid YAML frontmatter with description, globs, and alwaysApply fields
Cursor .mdc file names MUST be valid slugs: lowercase letters, digits, and hyphens only, with the .mdc extension
Copilot output MUST be a single file at .github/copilot-instructions.md — no splitting
Gemini output MUST be a single file at GEMINI.md at the project root — no subdirectories
The globs field in Cursor MDC files MUST use "" when no meaningful pattern can be inferred — never guess
All content in generated files MUST be free of Claude Code-specific execution syntax: no Task tool invocations, no sub-agent patterns, no ~/.claude/skills/ file paths
Copilot MUST adapt SDD content (workflow, phases, artifacts) — stripping rules apply only to execution-layer Claude Code syntax; SDD methodology is RETAINED and adapted for all targets
No target receives a verbatim copy of CLAUDE.md