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:

1. Display the full generated content for each file and its destination path.
2. If a target output file already exists at its canonical path, emit a warning before the confirmation prompt:

   WARNING: Overwriting existing file: <path>
   

3. Prompt the user:

   Write these files? [y/N]
   

   Default is N.
4. If the user responds with anything other than y, exit cleanly:

   Export cancelled — no files written
   

   No files are written.
5. 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:

1. 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.

2. 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.

3. 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