add-resource-path-convention

name	add-resource-path-convention
description	Use when writing commands or skills that reference other commands, skills, or scripts — ensures paths resolve correctly across all providers after installation

Resource Path Convention

Commands and skills in framwork/.codeadd/ are the source of truth. After build, they are placed in provider-specific directories (.claude/commands/, .agents/skills/, .gemini/commands/, etc.). Hardcoded .codeadd/commands/ or .codeadd/skills/ paths break because these directories do not exist in the installed project. Use build-time variables to reference resources.

When to Use

• Writing a command that references another command (e.g., autopilot loading add.plan)
• Writing a command or skill that references a skill file
• Reviewing existing commands/skills for broken path references
• Creating new commands via /add.make

When NOT to Use

• Referencing scripts (.codeadd/scripts/*.sh is always correct — fixed path)
• Referencing project files outside the framework (docs/, src/, etc.)
• Writing code in build.js or cli/ (these operate on the build/install pipeline, not agent runtime)

Variables

Build-time variables are available. build.js replaces them with the correct provider path during build.

{{cmd:NAME}}

Resolves to the full path of a command file for the target provider.

{{cmd:add.plan}}

# Claude → .claude/commands/add.plan.md
# Gemini → .gemini/commands/add.plan.toml

{{skill:NAME/FILE}}

Resolves to the full path of a skill file. Use SKILL.md for the main file, or any sub-file name.

{{skill:add-backend-development/SKILL.md}}

# Claude → .claude/skills/add-backend-development/SKILL.md
# Gemini → .gemini/skills/add-backend-development/SKILL.md

Scripts (no variable needed)

Scripts are always at .codeadd/scripts/. Use the literal path.

bash .codeadd/scripts/status.sh
bash .codeadd/scripts/done.sh

{{addpath:X}}

Resolves to the literal .codeadd/X path — same across all providers. Use for runtime paths that exist in the user's installed project (the installer preserves .codeadd/), but are NOT distributed by the build pipeline.

Typical cases: artefacts generated at runtime by commands like /add.wiki (which writes wiki/), the manifest file, or any artefact materialized in the user's project after install.

{{addpath:wiki/domains/backend.md}}  # → .codeadd/wiki/domains/backend.md
{{addpath:manifest.json}}            # → .codeadd/manifest.json

When to use {{addpath:}} vs {{skill:}}:

	{{skill:NAME/FILE}}	{{addpath:skills/NAME/FILE}}
Skill exists in framwork/.codeadd/skills/ (source)	✅	❌
Skill is generated at runtime in user project	❌	✅
Resolves per-provider	✅	❌ (always .codeadd/)

Examples

Correct

## STEP 1: Load Context
1. Read {{cmd:add.plan}} — PRIMARY reference
2. Run: bash .codeadd/scripts/status.sh
3. Read {{skill:add-backend-development/SKILL.md}}
4. For components, Grep {{skill:add-ux-design/shadcn-docs.md}}

Incorrect

## STEP 1: Load Context
Read .codeadd/commands/add.plan.md          ← BROKEN: doesn't exist after install
cat .codeadd/skills/backend-development/SKILL.md  ← BROKEN: wrong path
bash .codeadd/scripts/status.sh             ← CORRECT: scripts are at .codeadd/

Validation Checklist

[ ] No raw references to .codeadd/commands/ (use {{cmd:NAME}})
[ ] No raw references to .codeadd/skills/ (use {{skill:NAME/FILE}} for source skills, {{addpath:skills/NAME/FILE}} for runtime-generated skills)
[ ] Script references use .codeadd/scripts/ (literal, no variable)
[ ] Runtime artefacts in installed project use {{addpath:X}}
[ ] Command names match provider-map.json commands keys
[ ] Skill names match provider-map.json skills keys (with add- prefix)
[ ] Skill sub-files exist in the source skill directory