Skip to content

The design language that makes your AI harness better at design.

JavaScript

Fix: resolve the asset producer's component-review link in every emitted copy (#905) (#906)

Abdul Wahab0f0f2d55213a
diff --git a/CLAUDE.md b/CLAUDE.md
index 54ce1f7bf..087298671 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -129,6 +129,7 @@ Source files use placeholders that get replaced per-provider:
- `{{command_prefix}}` — `/` or `$` depending on provider
- `{{available_commands}}` — auto-populated list of commands (from `IMPECCABLE_SUB_COMMANDS` in `scripts/lib/utils.js`)
- `{{scripts_path}}` — provider-aware path to the skill's scripts directory
+- `{{reference_path}}` — agent bodies only (`skill/agents/*.md`): the skill's `reference/` directory, relative to each emitted copy
### Generated provider output policy
diff --git a/scripts/lib/transformers/factory.js b/scripts/lib/transformers/factory.js
index 1a1fe3062..b7ca16118 100644
--- a/scripts/lib/transformers/factory.js
+++ b/scripts/lib/transformers/factory.js
@@ -185,11 +185,14 @@ function buildCursorAgent(agent, body) {
* here, so all three resolve provider blocks, {{placeholders}}, rule markers,
* and {{scripts_path}} the same way. The nested Codex .toml used to skip the
* last two and shipped `node {{scripts_path}}/embed-prompt.mjs` literally.
+ * {{reference_path}} is the skill's reference/ dir relative to emitDir: a
+ * markdown link resolves against its own file, and each surface lands elsewhere.
*/
-function renderAgentBody(agent, { providerTags, placeholderKey, allSkillNames, scriptsPath }) {
+function renderAgentBody(agent, { providerTags, placeholderKey, allSkillNames, scriptsPath, emitDir, skillDir }) {
let body = compileProviderBlocks(agent.body, providerTags);
body = replacePlaceholders(body, placeholderKey, [], allSkillNames);
body = stripRuleMarkers(body);
+ body = body.replace(/\{\{reference_path\}\}/g, path.relative(emitDir, path.join(skillDir, 'reference')).split(path.sep).join('/'));
return body.replace(/\{\{scripts_path\}\}/g, scriptsPath);
}
@@ -357,7 +360,7 @@ export function createTransformer(config) {
ensureDir(degradedDir);
for (const agent of skill.agents) {
const role = agent.name.replace(/^impeccable-/, '');
- const body = renderAgentBody(agent, { providerTags, placeholderKey, allSkillNames, scriptsPath });
+ const body = renderAgentBody(agent, { providerTags, placeholderKey, allSkillNames, scriptsPath, emitDir: degradedDir, skillDir });
const content = `${DEGRADED_PREAMBLE}\n\n${body.replace(/^\s+/, '')}`;
writeFile(path.join(degradedDir, `${role}.md`), content);
refCount++;
@@ -387,7 +390,7 @@ export function createTransformer(config) {
if (CODEX_SKILL_PROVIDERS.has(provider)) {
for (const agent of skill.agents || []) {
if (agent.providers && !agent.providers.includes('codex')) continue;
- const agentBody = renderAgentBody(agent, { providerTags, placeholderKey, allSkillNames, scriptsPath });
+ const agentBody = renderAgentBody(agent, { providerTags, placeholderKey, allSkillNames, scriptsPath, emitDir: path.join(skillDir, 'agents'), skillDir });
const filename = `${agent.codexName || agent.name.replace(/-/g, '_')}.toml`;
ensureDir(path.join(skillDir, 'agents'));
writeFile(path.join(skillDir, 'agents', filename), buildCodexAgent(agent, agentBody));
@@ -425,7 +428,7 @@ export function createTransformer(config) {
// Agents can declare `providers: <list>` to limit which harnesses
// they emit to. Default (no field) ships everywhere with agentFormat.
if (agent.providers && !agent.providers.includes(provider)) continue;
- const body = renderAgentBody(agent, { providerTags, placeholderKey, allSkillNames, scriptsPath });
+ const body = renderAgentBody(agent, { providerTags, placeholderKey, allSkillNames, scriptsPath, emitDir: agentsDir, skillDir: path.join(skillsDir, skill.name) });
const agentFile = buildAgentFile(config, agent, body);
if (!agentFile) continue;
ensureDir(agentsDir);
diff --git a/skill/agents/impeccable-asset-producer.md b/skill/agents/impeccable-asset-producer.md
index 5ba1386eb..e1284f82b 100644
--- a/skill/agents/impeccable-asset-producer.md
+++ b/skill/agents/impeccable-asset-producer.md
@@ -26,7 +26,7 @@ When the parent hands you a decision card packet instead of an approved mock, th
## Review handoff
-Return the actual files and any unresolved drift to the parent for the user's plan and asset review in [component-review.md](../reference/component-review.md). A parent or automatic visual check is not a substitute for that human checkpoint. The parent may call you again after it: for regions the user reclassified from code to raster (the spec now lists them with a plate path), or for plates the user asked to revise, with their feedback as the prompt notes. Produce only those, preserve unchanged assets, and hand off real files as before; never self-approve. This checkpoint does not apply to the Decision Comps job above.
+Return the actual files and any unresolved drift to the parent for the user's plan and asset review in [component-review.md]({{reference_path}}/component-review.md). A parent or automatic visual check is not a substitute for that human checkpoint. The parent may call you again after it: for regions the user reclassified from code to raster (the spec now lists them with a plate path), or for plates the user asked to revise, with their feedback as the prompt notes. Produce only those, preserve unchanged assets, and hand off real files as before; never self-approve. This checkpoint does not apply to the Decision Comps job above.
## Input Contract
diff --git a/tests/build.test.js b/tests/build.test.js
index fe36c931f..d2a53896c 100644
--- a/tests/build.test.js
+++ b/tests/build.test.js
@@ -683,6 +683,16 @@ describe('agent bodies resolve placeholders on every surface that ships them', (
}
});
+ // A markdown link resolves against its own file, so it differs per surface.
+ test('the asset producer links to component-review.md from every surface', () => {
+ for (const [relPath] of SURFACES) {
+ const file = path.join(DIST, relPath);
+ const match = fs.readFileSync(file, 'utf-8').match(/\[component-review\.md\]\(([^)]+)\)/);
+ expect(match).not.toBeNull();
+ expect(fs.existsSync(path.resolve(path.dirname(file), match[1]))).toBe(true);
+ }
+ });
+
test('no emitted agent body carries an unresolved placeholder or a rule marker', () => {
const synthetic = {
name: 'impeccable',
@@ -693,7 +703,7 @@ describe('agent bodies resolve placeholders on every surface that ships them', (
name: 'impeccable-synthetic',
codexName: 'impeccable_synthetic',
description: 'synthetic agent',
- body: 'Run `{{scripts_path}}/impeccable embed-prompt` and ask {{model}}. <!-- rule:synthetic-marker -->',
+ body: 'Run `{{scripts_path}}/impeccable embed-prompt` and ask {{model}}. See [x.md]({{reference_path}}/x.md). <!-- rule:synthetic-marker -->',
},
],
};