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:

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

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

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 (see sub-sections 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.

These transformation prompts are self-instructions executed by the agent using its own in-context LLM reasoning. No external API call, subprocess, or tool invocation is required to apply them — the agent reads the prompt and generates the output directly.

Shared STRIP Preamble

The following items MUST be stripped from ALL target outputs. Each transformation prompt below references this block — apply it in addition to any target-specific delta listed in that prompt.

• All slash commands used as executable triggers (any /<word> pattern that is a Claude Code meta-tool or SDD phase command)
• Task tool references and sub-agent delegation patterns ("Task tool:", "subagent_type:", "Launch sub-agent", "Sub-agent launch pattern")
• install.sh and sync.sh references
• Claude Code-specific identity statements ("I am an expert development assistant…")
• The ## Skills Registry section of CLAUDE.md (lines beginning with ~/.claude/skills/ or .claude/skills/)
• Any section whose content is enclosed between <!-- [auto-updated] and <!-- [/auto-updated] --> comment markers in ai-context/ files

STRIP in core mode: when the source is core/ (core mode), the bundle is already neutral — none of the above items are present. The preamble collapses to a thin guard: drop only any residual ~/.claude/ path or slash-command that leaked into a core fragment. Do not run the full project-mode strip.

---

Copilot transformation prompt

Apply the following prompt to the source bundle to generate .github/copilot-instructions.md:

---

You are transforming a Claude Code project configuration into a GitHub Copilot instruction file.

Source bundle: CLAUDE.md + any available ai-context/ files provided above.

STRIP:

Apply the Shared STRIP Preamble above, then additionally strip:

• Plan Mode rules section (Claude Code-specific)

ADAPT — do NOT strip; rewrite for Copilot:

1. SDD phase DAG and workflow → Convert to a ## SDD Development Workflow section written in declarative prose:

• Describe each phase (explore, propose, spec, design, tasks, apply, verify, archive) and its artifacts
• Include the artifact types (proposal, spec, design, tasks, verify-report, archive-report) and explain they are persisted to engram
• Do NOT include any slash command syntax — describe the phases as steps the developer initiates

2. SDD available commands table → Replace with a ## Active SDD Coaching Instructions section containing Copilot behavioral instructions:

   When a developer mentions implementing a new feature, change, or fix:
   - Proactively ask: "Would you like to follow the SDD workflow for this change?"
   - If yes, guide them step by step: propose → (spec + design in parallel) → tasks → apply → verify → archive
   - Before starting apply, confirm that proposal, design, and tasks artifacts exist in the project's engram
   - Remind the developer to run verify after implementation and archive once confirmed

Adapt the phrasing to be Copilot-idiomatic (imperative instructions telling Copilot how to behave).

3. Project memory layer (ai-context/) → Retain the table and description verbatim; it applies directly to projects using Copilot too.

RETAIN and adapt:

• Tech stack (language, framework, key tools, versions)
• Coding conventions (naming, style, patterns) — rephrase as direct instructions to the AI assistant in imperative voice
• Architecture decisions and rationale
• Known issues and gotchas relevant to a developer working in the project
• Key working principles (clean code, no over-engineering, tests as first-class citizens, etc.)
• SDD artifact types and engram topic key patterns

FORMAT:

• Single flat Markdown file
• UTF-8, no BOM
• H2 sections (no YAML frontmatter)
• Start with a top-level heading: # Project Instructions
• Required H2 sections in this order:

1. ## Tech Stack (if stack data available) 2. ## Architecture (if architecture data available) 3. ## Conventions 4. ## SDD Development Workflow ← always present, even in bootstrap mode 5. ## Active SDD Coaching Instructions ← always present 6. ## Working Principles 7. ## Known Issues (if known-issues.md available) 8. ## Source Notes (only if any source file was absent)

• Begin with the generated-file banner (verbatim, before the H1):

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

• In bootstrap mode (no project CLAUDE.md), the ## SDD Development Workflow and ## Active SDD Coaching Instructions sections MUST still be fully generated from the global SDD methodology; all project-specific sections are omitted and noted under ## Source Notes.
• Output path: .github/copilot-instructions.md

---

Gemini transformation prompt

Apply the following prompt to the source bundle to generate GEMINI.md:

---

You are transforming a Claude Code project configuration into a Google Gemini instruction file (GEMINI.md).

Source bundle: CLAUDE.md + any available ai-context/ files provided above.

STRIP:

Apply the Shared STRIP Preamble above, then additionally strip:

• SDD phase DAG diagram
• SDD artifact storage details specific to Claude Code

ADAPT (do not strip wholesale):

• SDD command tables: remove the command table verbatim; you MAY include an adapted prose paragraph describing a structured development workflow if it adds value for Gemini users — but no slash commands
• Claude-specific section headers (e.g., "How I Execute Commands", "SDD Orchestrator — Delegation Pattern"): rename to Gemini equivalents or remove if the content has no value outside Claude Code

RETAIN:

• Tech stack, coding conventions, architecture decisions, known issues
• Working principles and development philosophy
• Project memory layer description (ai-context/ structure)

FORMAT:

• Single Markdown file at project root
• UTF-8, no BOM
• Structure similar to CLAUDE.md (not flat — preserve H2/H3 hierarchy where content warrants it)
• Start with a top-level heading (e.g., # Gemini — Project Configuration)
• Begin with the generated-file banner (verbatim, before the H1):

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

• Output path: GEMINI.md

---

Codex transformation prompt

Apply the following prompt to the source bundle to generate AGENTS.md:

---

You are transforming the source bundle into an OpenAI Codex CLI instruction file (AGENTS.md).

STRIP: Apply the Shared STRIP Preamble (thin guard in core mode).

RETAIN and adapt: persona, conventions, working principles, and the SDD Development Workflow as declarative prose (no slash commands). Same content contract as the Copilot target — Codex AGENTS.md is a flat neutral instruction file.

FORMAT:

• Single Markdown file at project root, UTF-8 no BOM, H2/H3 hierarchy preserved.
• Top-level heading: # AGENTS — Project Configuration.
• Begin with the generated-file banner (verbatim, before the H1):

  <!-- GENERATED BY config-export — DO NOT EDIT MANUALLY -->
  <!-- Source: core/ (or 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.

• Keep within the ~32 KiB combined AGENTS.md budget; prefer the essential neutral sections.
• AGENTS.md is merged hierarchically root→cwd by Codex — the rendered root file is the base layer.
• Output path: AGENTS.md

---

Cursor transformation prompt

Apply the following prompt to the source bundle to generate .cursor/rules/*.mdc files:

---

You are transforming a Claude Code project configuration into Cursor MDC rule files.

Source bundle: CLAUDE.md + any available ai-context/ files provided above.

STRIP the following from all output files:

Apply the Shared STRIP Preamble above, then additionally strip:

• SDD phase DAG diagram
• SDD artifact storage details specific to Claude Code

OUTPUT STRUCTURE — split into exactly three domain files:

1. `conventions.mdc` — coding rules, naming conventions, style guidelines, error handling patterns 2. `stack.mdc` — tech stack, language versions, key frameworks and tools, package manager 3. `architecture.mdc` — architecture decisions, system design patterns, data flow, inter-component contracts

If source material is insufficient to produce meaningful content for a domain (e.g., no architecture.md and no architecture content in CLAUDE.md), produce a minimal file with the frontmatter and a one-line note rather than omitting the file.

MDC FRONTMATTER CONTRACT — every file MUST have:

---
description: "[one-line description of this rules domain]"
globs: "[glob pattern or empty string]"
alwaysApply: [true|false]
---

Domain defaults:

CRITICAL — globs field: Use "" when no meaningful file-pattern can be inferred. NEVER guess at glob patterns. The globs field MUST be a string (not YAML null).

FORMAT per file:

• UTF-8, no BOM
• YAML frontmatter block first (between --- delimiters)
• Generated-file banner immediately after the closing --- of the frontmatter:

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

• File name: lowercase slug with .mdc extension (e.g., conventions.mdc)
• If source material was only CLAUDE.md (no ai-context/), set description to note it: e.g., "Generated from CLAUDE.md — ai-context/ not found"
• Output paths: .cursor/rules/conventions.mdc, .cursor/rules/stack.mdc, .cursor/rules/architecture.mdc

---

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

config-export — Command mode (Step 3-CMD)

Reference companion to config-export/SKILL.md. Holds the full command-mode

render contract (invocable SDD commands for Copilot, Gemini, Codex). Extracted

from SKILL.md to keep it under the 450-line SKILL.md budget

(docs/config-guidelines.md Principle 4). SKILL.md Step 3-CMD points here.

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

Command mode renders the SDD pipeline skills as invocable commands for Copilot, Gemini, and Codex. It is distinct from the instruction render above and is selected when the user runs /config-export --commands (or picks the commands target). It does NOT replace the instruction targets.

CRITICAL — deterministic, NOT LLM-transformation. The instruction render (Step 3) adapts prose via in-context LLM reasoning, where faithful wording is not required. An invocable command carries an executable process (diagnosis gates, retry counters, TDD cycle, BLOCKED handling) that MUST port FAITHFULLY. Command mode therefore performs a deterministic envelope-wrap of the neutral logic — it copies the logic body verbatim and wraps it in each tool's envelope. It MUST NOT paraphrase, summarize, or "adapt" the logic body. (See ADR-006.)

Source — two roots: in-scope skills draw their neutral logic from one of two roots, by skill class. Both are already neutral (no Claude execution wiring).

• `core/skills/<name>/logic.md` — skills whose neutral logic IS the shared body

of a wrapped Claude SKILL.md (the Tier-A/B pattern; install.sh splices the same logic into the Claude skill via its ASSEMBLY region). In-scope: the SDD pipeline skills (sdd-explore, sdd-propose, sdd-spec, sdd-design, sdd-tasks, sdd-apply, sdd-verify, sdd-archive), the Tier-A methodology skills (codebase-teach, feature-domain-expert, memory-manage), and the Tier-B skill (feature-define).

• `core/commands/<name>/logic.md` — command-only skills that exist ONLY for the

ported tools, with no shared Claude body. Their Claude counterpart (if any) keeps a separate, fuller SKILL.md that is deliberately NOT wrapped (ADR-012), so the logic lives under core/commands/ — NOT core/skills/ — to keep the single-sourcing invariant of core/skills/ (every logic.md pairs a wrapped SKILL.md, enforced by core/skills/validate.sh) intact. In-scope: the Tier-D config commands (config-audit, config-refactor) — a partial audit of the 7 per-tool-portable config-guidelines principles — and the Tier-C command project-setup — a partial port covering stack detection + an initial instruction-file scaffold (the full bootstrap stays Claude-only; see ADR-013).

Per-tool envelope — wrap the verbatim logic body per each adapter's Invocable command envelope section in adapters/<tool>/target.md:

The description (and Codex name) come from the logic file's H1 / one-line summary. The body is the logic content below the summary, copied verbatim.

STRIP guard (BLOCKING) — after rendering each command file and BEFORE writing it, assert zero forbidden Claude execution tokens:

FORBIDDEN = ~/.claude/ | mem_save | mem_search | mem_get_observation
          | _shared/ | Skill( | subagent_type

If any forbidden token appears in a rendered command file, the export FAILS for that file: do NOT write it, report the offending token + file, and halt command mode. A clean source (the skill's logic.md under its root — core/skills/ or core/commands/ — with zero forbidden tokens) renders clean; a leak means the neutral source was incomplete and must be fixed at the source, never patched in the rendered output.

Memory-contract prelude injection — AFTER the STRIP guard passes for a command file and BEFORE writing it, prepend the memory contract exactly once. Read core/skills/config-export/memory-contract.md (the single neutral source — a render INPUT owned by this skill, NOT a Claude force-read protocol; it opens with the <!-- MEMORY-CONTRACT v1 --> sentinel and contains zero forbidden tokens) and inject it into the envelope body region per tool:

The prelude is ADDED at the envelope, NOT inside the stripped body — so it is never re-scanned by the STRIP guard and the guard (and FORBIDDEN list above) stays byte-for-byte unchanged. Inject exactly one prelude per command file regardless of how many persistence references the neutral body contained (including zero). The prelude is prose carrying no mem_*, ~/.claude/, or _shared/ token, so it does not reintroduce any forbidden token into the output.

Dry-run + write: command mode follows the same dry-run-then-confirm and idempotent-overwrite discipline as Step 3 / Step 4. Directories (.github/prompts/, .gemini/commands/, .agents/skills/<name>/) are created silently.