Development
codex-support
Multi-target output system — target abstraction, backend routing, content transforms for Codex CLI and future targets
aspenkit · AI review on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add aspenkit/aspens --skill codex-supportAbout this skill
name: codex-support description: Multi-target output system — target abstraction, backend routing, content transforms for Codex CLI and future targets triggers: files: - src/lib/target.js - src/lib/target-transform.js - src/lib/backend.js - AGENTS.md - .aspens.json keywords: - codex - target - backend - AGENTS.md - .aspens.json - sanitize - transform - multi-target - parity
You are working on multi-target output support — the system that lets aspens generate documentation for Claude Code, Codex CLI, or both simultaneously.
Key Concepts
- Target vs Backend: Target = where output goes (claude →
.claude/skills/, codex →.agents/skills/+ directory-scopedAGENTS.md). Backend = which LLM CLI generates the content (claude -porcodex exec). - Target definitions:
TARGETS.claude(centralized) andTARGETS.codex(directory-scoped). Each defines paths and capability flags:supportsHooks,supportsSettings,supportsGraph,supportsSkills,needsActivationSection,needsCodeMapEmbed,supportsMCP. Codex also hasmaxInstructionsBytes(32 KiB) anduserSkillsDir. Codex'sneedsCodeMapEmbedisfalse— condensed cluster/framework data goes into the synthetic.agents/skills/architecture/skill instead of the root AGENTS.md. - Canonical generation: Generation always produces Claude-canonical format first. Prompts always receive
CANONICAL_VARS(hardcoded Claude paths fromdoc-init.js). Transforms run after generation to produce other target formats. - Content transform:
transformForTarget()remaps paths and content. For Codex: base skill → rootAGENTS.md, domain skills → both.agents/skills/{domain}/SKILL.mdand source directoryAGENTS.md.generateCodexSkillReferences()creates.agents/skills/architecture/with code-map data. - Skills section completeness:
collectSkillsForList()(internal) reads every skill from disk undersourceTarget.skillsDirand overlays pending in-flight changes (filespassed to the transform) so the root instructions file's## Skillssection always lists every on-disk skill — not just the subset that changed in this sync. Pending changes win for descriptions; on-disk content survives for unchanged skills. - Instructions file disk fallback:
transformToDirectoryScopedloadsinstructionsFilefrom disk viarepoPathcontext parameter when it's not in the canonical files array (e.g., duringdoc init --strategy skip-existingor incrementaldoc sync). Uses a singlereadFileSyncfromfswrapped in try/catch (no separateexistsSynccheck). - Content sanitization:
sanitizeCodexInstructions()andsanitizeCodexSkill()strip Claude-specific references (hooks, skill-rules.json, Claude Code mentions) from Codex output. sanitizePublishedContent(content, filePath)— Single-chokepoint sanitizer invoked byskill-writer.json every disk write. Always strips## Activationblocks and## Key Filesblocks. Outsidecode-map.md, also strips count-bearing blocks:**Hub files…**,**Domain clusters:**,**High-churn hotspots:**,**Framework entry points…**. Defense in depth — upstream leaks can't reach the user.- Skills-variant stripping:
syncSkillsSection()removes LLM-emitted Skill-section variants (## Skills Reference,## Skills Overview, etc.) before injecting the canonical## Skillslist. Doc-init and doc-sync prompts also forbid such headings. ensureRootKeyFilesSection(content)— Backwards-compat shim only. Strips legacy## Key Fileshub blocks left in older docs and collapses extra blank lines. Does not insert anything — hub rankings live incode-map.md/graph.jsonexclusively.mergeConfiguredTargets(existing, next)— Merges target arrays to avoid dropping previously configured targets during narrower runs. Validates againstTARGETSkeys, deduplicates.getAllowedPaths(targets)— Returns{ dirPrefixes, exactFiles }union across all active targets.- Backend detection:
detectAvailableBackends()checks ifclaudeandcodexCLIs are installed.resolveBackend()picks best match: explicit flag > target match > fallback. - Config persistence:
.aspens.jsonat repo root stores{ targets, backend, version, saveTokens? }.readConfig()returnsnullif missing or if the config is structurally invalid.isValidConfig()validates targets, backend, version, andsaveTokens(viaisValidSaveTokensConfig()). loadConfig(repoPath, { persist })— Reads.aspens.jsonand, if missing, recovers viainferConfig()from on-disk artifacts. Returns{ config, recovered }. Persists inferred config to disk by default unlesspersist: falseis passed.- Feature config (
saveTokens): Optional object in.aspens.jsonvalidated byisValidSaveTokensConfig()— checksenabled(boolean),warnAtTokens/compactAtTokens(positive integers, compact > warn unless either isMAX_SAFE_INTEGER),saveHandoff/sessionRotation(booleans), optionalclaude/codexsub-objects withenabledandmode. writeConfigpreserves feature config:writeConfig()reads existing config and merges —saveTokenspreserved unless explicitly set tonull(intentional removal) orundefined(keep existing). Targets and backend also merge with existing.- Multi-target publish:
doc-syncusespublishFilesForTargets()to generate output for all configured targets from a single LLM run.repoPathis passed through to the transform context. - Codex inference tightened:
inferConfig()only adds'codex'to inferred targets when.codex/config dir or.agents/skills/dir exists. - Conditional architecture ref: Codex
buildCodexSkillRefs()only includes the architecture skill reference when a graph was actually serialized. - Architecture skill is codex-only synthetic: The codex
architectureskill is generated from graph d