ai-driven-dev Translate
translate is the core: it turns the canonical, Claude-format framework source into
target-native content for every tool at once. It reaches two places and no others: tools, its
one outbound context edge, and kernel. Everything it reaches in tools is that context's
declared public surface (contracts.ts, registry.ts, build-contract.ts, and the handful of
capability and port modules listed as public), never an internal file. The whole graph is in
.claude/rules/00-architecture/0-contexts.md.
What goes in
| Concept | Location |
|---|---|
| A transform whose behavior differs by target tool | domain/formats/ |
| The plugin-files-to-installed-files translator | domain/content-translator.ts (PluginContentTranslator) |
| The canonical framework-doc shape | domain/canon.ts |
| The canonical single-plugin shape | domain/plugin-distribution.ts |
| Build targets and modes | domain/build-target.ts |
The aidd translate use-case |
application/translate-source.ts (FrameworkBuildUseCase) |
| A build orchestrator (one per mode, never per tool) | application/strategies/ |
| Schema validation for marketplace/plugin manifests | infrastructure/schema-validator.ts |
A transform used by exactly one tool profile does not belong here — it lives in that profile's
own directory. A transform shared by ≥2 profiles but identical regardless of target lives in
contexts/tools/domain/formats/ instead. What belongs in translate/domain/formats/ is a
transform that is aware of which target it is producing for.
How
PluginContentTranslatortakes one plugin's canonical files and one tool'sAiTool<C>, and calls the tool's ownrewriteContent— it does not reimplement a tool's rewrite logic, it invokes whattoolsdeclared. That function is one-way and has no inverse; thetoolsskill'sreferences/content-rewrite.mdsays why, and names the trap an identity rewrite sets.FrameworkBuildUseCase(aidd translate) reads aToolBuildContractper target and mode fromtools, and dispatches toMarketplaceBuildStrategyorFlatBuildStrategy— both implementBuildOutputStrategyand iterate the six artifact kinds generically, with zero per-tool or per-kind branching. Adding a build target means the target tool declares a contract intools; it never means adding a case here. See thetoolsskill'sreferences/build-contract.md.runtime/wiring/translate.tsderives the"<target>:<mode>"build registry by iterating every registered tool and reading its contract — there is no hand-maintained per-tool row.- Follow the use-case and orchestration rules in
.claude/rules/00-architecture/for the application layer's shape, and the shared-module rule there before promoting a helper used by only one strategy intoshared-plugin-helpers.ts.
Public surface
Nothing outside contexts/translate/ may import a module this context has not declared public —
tests/architecture/context-boundary.arch.test.ts holds the list (PUBLIC_MODULES.translate).
framework is the only context that imports from here (framework → translate); a module used
by framework must be on that list.
How it's tested
tests/contexts/translate/mirrorssrc/contexts/translate/— formats, content-translator, canon, and the two build strategies each have unit or integration coverage.tests/golden/framework-build-golden.e2e.test.tssnapshots a full build across every target — seetestskill's golden/machine-independence rules before touching a snapshot.- A new target-aware transform gets a unit test over a representative input carrying the marker it is meant to rewrite. A transform that is the identity for the fixture it was given is indistinguishable from one that never ran.