devlyn-cli 4.0.0 → 4.0.1

package/AGENTS.md

@@ -42,7 +42,7 @@ Conversational entry: Before loading a workflow or writing files, inspect the re
 
 Use full `/devlyn-resolve` automatically only when inspection identifies interacting requirements or verification work too complex to manage reliably in the current context, such as coupled durable state, concurrent ownership and failure recovery across boundaries. Name the concrete interaction or verification gap. Domain labels (security/auth/payment/persistence/concurrency/API), file count and a spec document alone do not trigger it. Investigate or clarify missing intent/access first; a pipeline cannot supply them. Direct work still requires risk-proportionate checks and independent review for consequential changes. Explicit resolve (even small), explicit spec-mode workflows and queue drains retain all canonical phases, independent verification, pins and failure handling. If the full-route condition emerges mid-edit, carry the existing delta into its scope/evidence; do not reset the baseline or reconfirm existing authorization.
 
-Full-route handoff + loop engineering: the orchestrating model — not the user — invokes the skills. `/devlyn-queue` fronts the intent queue (`docs/specs/queue.md`): no args = status, `add <intent>`, `drain` = serial unattended drain per the contract below. Work selected for full resolve is written to `docs/specs/<id>/spec.md` (always a spec file — the user's reviewed contract; free-form large assumes-and-logs instead of halting, zero-scope-signal goals still halt to ideate), summarized once for user review, then run hands-free via `--spec`. Outer loop per task: before the first full run, commit the scoped queue-item delta (when applicable) and linked spec bundle; findings-backed verdicts (NEEDS_WORK, BLOCKED:repair-budget-exhausted) get a committed spec amendment before re-run, max 3 iterations; infrastructure / invalid-input / engine-availability / implement-empty BLOCKED verdicts surface immediately. Unattended queue drain (`docs/specs/queue.md`, strictly serial): assumptions may only take scope-narrowing, reversible, non-user-visible defaults — material ambiguity marks the item `[F] needs-review`; commit every terminal `[x]` / `[F]` transition before advancing. The canonical commit order is `config/skills/devlyn-resolve/references/outer-loop.md`.
+Full-route handoff + loop engineering: the orchestrating model — not the user — invokes the skills. `/devlyn-queue` fronts the intent queue (`docs/specs/queue.md`): no args = status, `add <intent>`, `drain` = serial unattended drain per the contract below. Work selected for full resolve is written to `docs/specs/<id>/spec.md` (always a spec file — the user's reviewed contract; free-form large assumes-and-logs instead of halting, zero-scope-signal goals still halt to ideate), summarized once for user review, then run hands-free via `--spec`. Outer loop per task: before the first full run, commit the scoped queue-item delta (when applicable) and linked spec bundle; findings-backed verdicts (NEEDS_WORK, BLOCKED:repair-budget-exhausted) get a committed spec amendment before re-run, max 3 iterations; infrastructure / invalid-input / engine-availability / implement-empty BLOCKED verdicts surface immediately. Unattended queue drain (`docs/specs/queue.md`, strictly serial): assumptions may only take scope-narrowing, reversible, non-user-visible defaults — material ambiguity marks the item `[F] needs-review`; commit every terminal `[x]` / `[F]` transition before advancing. The canonical commit order is `references/outer-loop.md` in the installed `devlyn-resolve` skill.
 
 ## Subtractive-First Editing
 

package/CLAUDE.md

@@ -62,7 +62,7 @@ The user does not invoke skills manually; the orchestrating model does. For work
 3. On go-ahead, commit the scoped queue-item delta (when applicable) and linked spec bundle, then invoke `/devlyn-resolve --spec <path>` hands-free to completion.
 4. **Per-task outer loop**: read the terminal verdict. Successful normal-run archive → outer-owner completion per the canonical task-completion reference, after any terminal queue commit. Verdicts backed by spec/verification findings (NEEDS_WORK, BLOCKED:repair-budget-exhausted) → adjudicate the findings, amend the spec (recorded in the spec file; spec stays read-only inside a run), commit that scoped amendment, then re-invoke — at most 3 outer iterations, then surface with the findings trail. Infrastructure, invalid-input, engine-availability, and implement-empty BLOCKED verdicts are not spec-amendable: surface immediately. Every iteration re-enters through committed durable artifacts (spec, findings, run archive), never conversation memory.
 
-**Intent queue (unattended drain)**: the user stacks intents in `docs/specs/queue.md` (ordered checklist; `/devlyn-queue` is the front-end — no args shows status, `add <intent>` appends, `drain` starts the serial drain). Drain strictly serially — per item: spec it, commit the scoped owner baseline, run the outer loop, mark `[x]` done or `[F]` blocked with reason, commit that terminal transition, then complete eligible delivery once. Retain PR/pending workspaces; unavailable separate safe placement stops the drain with remaining items pending. A product-blocked item otherwise never halts the queue. The queue entry is the user's go-ahead, so assume-and-log replaces the interactive checkpoint — but unattended assumptions may only take scope-narrowing, reversible, non-user-visible defaults. Material ambiguity (user-visible behavior, data/state semantics, new files/scripts/flags, implementation surface) → mark `[F] needs-review`, commit it, and move on. End the drain with a per-item product verdict, separate delivery status/URL/resume and assumptions report. The canonical commit order is `config/skills/devlyn-resolve/references/outer-loop.md`.
+**Intent queue (unattended drain)**: the user stacks intents in `docs/specs/queue.md` (ordered checklist; `/devlyn-queue` is the front-end — no args shows status, `add <intent>` appends, `drain` starts the serial drain). Drain strictly serially — per item: spec it, commit the scoped owner baseline, run the outer loop, mark `[x]` done or `[F]` blocked with reason, commit that terminal transition, then complete eligible delivery once. Retain PR/pending workspaces; unavailable separate safe placement stops the drain with remaining items pending. A product-blocked item otherwise never halts the queue. The queue entry is the user's go-ahead, so assume-and-log replaces the interactive checkpoint — but unattended assumptions may only take scope-narrowing, reversible, non-user-visible defaults. Material ambiguity (user-visible behavior, data/state semantics, new files/scripts/flags, implementation surface) → mark `[F] needs-review`, commit it, and move on. End the drain with a per-item product verdict, separate delivery status/URL/resume and assumptions report. The canonical commit order is `references/outer-loop.md` in the installed `devlyn-resolve` skill.
 
 ## Subtractive-first editing — perfection = nothing left to remove
 <!-- runtime-principles:section=subtractive-first:begin -->

package/bin/devlyn.js

@@ -31,7 +31,6 @@ const RENAMED_SKILLS = {
   'devlyn:pencil-push': 'devlyn-pencil-push',
   'devlyn:reap': 'devlyn-reap',
 };
-const DEVLYN_SKILL_DIR_STAMP = '__DEVLYN_SKILL_DIR__';
 const DEVLYN_INSTALL_MARKER = '.devlyn-install.json';
 
 // Every spelling a colon name can have on disk: its own and npm's U+F03A extraction alias.
@@ -47,11 +46,25 @@ const PRE_STANDARD_SKILL_MD_SHA256 = new Set([
   '5f2e8b29609cbb2af72941579823bec598265ebf29cd3a375d6aa47d95b74354', // devlyn-pencil-push
 ]);
 
-function isPreStandardCopy(dir) {
+// Skills devlyn-cli shipped and later deleted without listing them, by SHA-256 of their only
+// file, SKILL.md (LF endings): a user's own folder of the same name is never removed.
+const RETIRED_SKILL_MD_SHA256 = {
+  // 0.2.0-1.15.0; deleted in iter-0034, it still routes agents to retired commands.
+  'workflow-routing': new Set([
+    '7fec2bb20d808a873a975d64a6223e404bc5b328c800760bb77257ae6b2f467a',
+    '8bfdaeff2ce48d5a79b5653de3bbe0d56a61a7fd750ed3ad11149fec5a502ecf',
+  ]),
+};
+
+// Whether `dir` is a real folder whose only file (dotfiles such as .DS_Store aside) is a SKILL.md
+// with an LF-normalized SHA-256 in `hashes`: an unedited copy devlyn-cli shipped, not something
+// the user added to or wrote.
+function isShippedCopy(dir, hashes) {
   const skill = path.join(dir, 'SKILL.md');
   return fs.lstatSync(dir, { throwIfNoEntry: false })?.isDirectory() === true
+    && fs.readdirSync(dir).filter((name) => !name.startsWith('.')).length === 1
     && fs.lstatSync(skill, { throwIfNoEntry: false })?.isFile() === true
-    && PRE_STANDARD_SKILL_MD_SHA256.has(crypto.createHash('sha256')
+    && hashes.has(crypto.createHash('sha256')
       .update(fs.readFileSync(skill, 'utf8').replace(/\r\n/g, '\n')).digest('hex'));
 }
 
@@ -368,6 +381,14 @@ function cleanupDeprecated(targetDir) {
       removed++;
     }
   }
+  for (const [name, hashes] of Object.entries(RETIRED_SKILL_MD_SHA256)) {
+    const fullPath = path.join(targetDir, 'skills', name);
+    if (isShippedCopy(fullPath, hashes)) {
+      fs.rmSync(fullPath, { recursive: true });
+      log(`  ✕ skills/${name}/ (removed)`, 'dim');
+      removed++;
+    }
+  }
   return removed;
 }
 
@@ -380,7 +401,7 @@ function retireRenamedSkills(skillsDir) {
   for (const [oldName, newName] of Object.entries(RENAMED_SKILLS)) {
     const found = legacySkillPaths(skillsDir, oldName).filter((fullPath) => fs.existsSync(fullPath));
     if (found.length > 0 && optional.has(newName)) installOptionalSkillInto(skillsDir, newName);
-    else if (isPreStandardCopy(path.join(skillsDir, newName))) refreshPreStandardCopy(skillsDir, newName);
+    else if (isShippedCopy(path.join(skillsDir, newName), PRE_STANDARD_SKILL_MD_SHA256)) refreshPreStandardCopy(skillsDir, newName);
     for (const fullPath of found) {
       fs.rmSync(fullPath, { recursive: true, force: true });
       log(`  ✕ ${path.basename(fullPath)}/ (renamed to ${newName})`, 'dim');
@@ -454,40 +475,6 @@ function writeInstallMarker(skillsDir) {
   }
 }
 
-function shellDoubleQuoteDefault(value) {
-  if (value.includes('\n')) {
-    throw new Error(`Cannot stamp skill path with newline: ${value}`);
-  }
-  return value.replace(/[\\$"`}]/g, '\\$&');
-}
-
-function stampInstalledSkillDir(rootDir, skillDir) {
-  // Stamp ONLY the assignment-default occurrence. The sentinel comparison
-  // literal on the guard line must stay intact: stamping it makes the guard
-  // compare the stamped default to itself and false-positive
-  // BLOCKED:shared-dir-unresolved on every codex/omp run that executes the
-  // block (CLAUDE_SKILL_DIR unset) — iter-0040 R3 latent finding.
-  const assignmentStamp = '${CLAUDE_SKILL_DIR:-' + DEVLYN_SKILL_DIR_STAMP + '}';
-  const stampedAssignment = '${CLAUDE_SKILL_DIR:-' + shellDoubleQuoteDefault(skillDir) + '}';
-
-  function visit(current) {
-    const stats = fs.statSync(current);
-    if (stats.isDirectory()) {
-      for (const item of fs.readdirSync(current)) {
-        visit(path.join(current, item));
-      }
-      return;
-    }
-    if (path.extname(current) !== '.md') return;
-
-    const content = fs.readFileSync(current, 'utf8');
-    if (!content.includes(assignmentStamp)) return;
-    fs.writeFileSync(current, content.split(assignmentStamp).join(stampedAssignment));
-  }
-
-  visit(rootDir);
-}
-
 // Dev artifacts that live under config/skills/ but must never ship or install.
 // Mirrors the `!` exclusions in package.json files[].
 const UNSHIPPED_SKILL_DIRS = new Set([
@@ -642,7 +629,6 @@ function installOptionalSkillInto(target, skillName) {
   const dest = path.join(target, skillName);
   fs.rmSync(dest, { recursive: true, force: true });
   copyRecursive(path.join(OPTIONAL_SKILLS_SOURCE, skillName), dest, target);
-  stampInstalledSkillDir(dest, dest);
   assertCompleteSkillInstall(OPTIONAL_SKILLS_SOURCE, target, [skillName]);
   const oldName = Object.keys(RENAMED_SKILLS).find((name) => RENAMED_SKILLS[name] === skillName);
   for (const fullPath of oldName ? legacySkillPaths(target, oldName) : []) {
@@ -737,7 +723,6 @@ function installSkillsForCLI(cliKey) {
       fs.rmSync(dest, { recursive: true, force: true });
     }
     copyRecursive(src, dest, cli.skillsDir);
-    stampInstalledSkillDir(dest, dest);
     copied++;
     log(`  → ${cli.skillsDir.replace(os.homedir(), '~')}/${skillName}`, 'dim');
   }
@@ -854,10 +839,6 @@ function installClaudeCore() {
   }
   copyRecursive(CONFIG_SOURCE, targetDir, targetDir);
   assertCompleteSkillInstall(path.join(CONFIG_SOURCE, 'skills'), skillsDir, DEVLYN_CORE_SKILLS);
-  for (const name of DEVLYN_CORE_SKILLS) {
-    const dest = path.join(skillsDir, name);
-    stampInstalledSkillDir(dest, dest);
-  }
   retireRenamedSkills(skillsDir);
   writeInstallMarker(skillsDir);
 

package/bin/instruction-templates.json

@@ -196,6 +196,7 @@
       "76517a747d47a3986b7181db4bbe5898ad3d6d82644ce39d8bf62edc998cecb9",
       "766c776b750cb84f084c49679fa377899693acf5f8d4e00751ca0fab97b4f030",
       "78690fc75b54ee634413fd0d5f6892692b2557e8838fbb8453f7bdd4b6519cc5",
+      "7a0d897737f705b0276b829df5b62fd9541e3897b872b2a2668f54e08b88dfff",
       "7aab816bfa43d73b4eb8bd9136242e8a4938f3610e7ad3c32e033b7ee3d28a1e",
       "7fde023e25658ff48c67b6708c5b6f383a6497a509946cb3bdc5da7d35e4f3f6",
       "8211bb3dcc9d7df40c393a4ef8e620526d84ded9faec25655cfa74801458515d",
@@ -455,6 +456,7 @@
       "3ab5f6021b62f21624e3eed505cc6849c66972d01ac67337533cff0e81dc9dc8",
       "3afe3870751373b6059ebddfb6c179ab70b7a1f3a9299555ecf5ea47c2970422",
       "3b5bf36be5ad797443dc5c1c407684c6f86b28894ca9a975a3fb5c18b3066fbb",
+      "3ba1747fbe0662a0aa9c42e6e442748f013a8e90febc330e2854ab9ad841dd77",
       "3cfc73fecd13c54fd400f5b04b2c4113cc776c102f6f09eaa401252276818e17",
       "3d321af4f48efc92735cc8772cf092f15789ac63e1e20f857ba20c0532453eac",
       "3def30362c96b6238021ab82e6f2ebd2974005ca94a84008f43528aaa7eb435f",

package/config/skills/_shared/codex-config.md

@@ -6,20 +6,20 @@ Single source of truth for how every skill calls Codex. **MCP is not used.** Ski
 
 All long-running Codex calls go through `codex-monitored.sh`. It streams full stdout and emits a `[codex-monitored] heartbeat` every 30s on stderr. Write multiline prompts as exact UTF-8 bytes to a task-local file; set `DEVLYN_CODEX_PROMPT_FILE` and pass the sole prompt argument `-`. The wrapper snapshots those bytes before dispatch and seals actual argv, prompt digest and completion in `<prompt-file>.transport.json`. Missing/unreadable files, competing prompt arguments and receipt/prompt mismatches fail before launch. Without file transport, stdin remains DEVNULL (avoiding the open-stdin plus argument-prompt hang).
 
-Before the first Codex call, resolve the wrapper from the invoked skill directory:
-
+Use the DEVLYN_SHARED_DIR established by the invoking skill; if it was
+lost, re-establish it by that skill's rules. When this document is
+opened directly, bind DEVLYN_SHARED_DIR to its reader-supplied
+containing directory, resolving directory symlinks. Never take it from
+an environment variable, cwd or another installation; without either
+source, stop with BLOCKED:skill-source-unresolved.
+
+Bind CODEX_MONITORED_PATH to DEVLYN_SHARED_DIR/codex-monitored.sh and
+verify the file before calling it; failure is
+BLOCKED:shared-dir-unresolved with the failed path.
+
+After establishing DEVLYN_SHARED_DIR in a Bash invocation:
 ```bash
-DEVLYN_SKILL_DIR="${CLAUDE_SKILL_DIR:-__DEVLYN_SKILL_DIR__}"
-if [ "$DEVLYN_SKILL_DIR" = "__DEVLYN_SKILL_DIR__" ] || [ ! -d "$DEVLYN_SKILL_DIR/../_shared" ]; then
-  echo "BLOCKED:shared-dir-unresolved: $DEVLYN_SKILL_DIR/../_shared" >&2
-  exit 1
-fi
-DEVLYN_SHARED_DIR="$(cd "$DEVLYN_SKILL_DIR/../_shared" && pwd)"
 CODEX_MONITORED_PATH="$DEVLYN_SHARED_DIR/codex-monitored.sh"
-if [ ! -f "$CODEX_MONITORED_PATH" ]; then
-  echo "BLOCKED:shared-dir-unresolved: $CODEX_MONITORED_PATH" >&2
-  exit 1
-fi
 ```
 
 **Read-only critique / adversarial review / debate** (`/devlyn-resolve` VERIFY pair-mode, plus any future ideate read-only critique). Codex returns findings on stdout; the orchestrator writes files.

package/config/skills/devlyn-engines/SKILL.md

@@ -10,16 +10,42 @@ $ARGUMENTS
 </args>
 
 <runtime_paths>
-Resolve shared scripts from this skill's installed directory, never from the project cwd, before step 2 below:
-
-```bash
-DEVLYN_SKILL_DIR="${CLAUDE_SKILL_DIR:-__DEVLYN_SKILL_DIR__}"
-if [ "$DEVLYN_SKILL_DIR" = "__DEVLYN_SKILL_DIR__" ] || [ ! -d "$DEVLYN_SKILL_DIR/../_shared" ]; then
-  echo "BLOCKED:shared-dir-unresolved: $DEVLYN_SKILL_DIR/../_shared" >&2
-  exit 1
-fi
-DEVLYN_SHARED_DIR="$(cd "$DEVLYN_SKILL_DIR/../_shared" && pwd)"
+Before the first command, establish the bindings below.
+
+Resolve bundled resources from the SKILL.md loaded for this invocation.
+
+Reader-rendered directory hint:
+```text
+${CLAUDE_SKILL_DIR}
 ```
+
+Treat the hint as literal path data, never shell code. If the reader
+replaced it with an absolute directory, use that directory. Otherwise
+use the filesystem path or base directory reported for this loaded
+SKILL.md. Resolve virtual URIs through the reader's native filesystem
+mapping. If available source locations name different directories,
+stop.
+
+Bind DEVLYN_SKILL_DIR to that absolute directory. Do not obtain this
+binding from an environment variable, cwd, or another installation.
+Verify its SKILL.md before proceeding. Missing or conflicting source
+identity is BLOCKED:skill-source-unresolved; include the failed path
+when known.
+
+Resolve bundled references against this directory. These bindings are
+workflow values: establish them explicitly using each tool or shell's
+literal-path rules, and include their absolute values in every fresh
+worker's prompt, telling it to set them from those values, never from
+its inherited environment. Do not rely on shell state surviving between
+calls.
+
+Resolve directory symlinks on DEVLYN_SKILL_DIR before deriving its
+sibling _shared. Bind that directory as DEVLYN_SHARED_DIR. References
+written as _shared/... use this binding. Verify the directory and each
+required resource before use; failure is BLOCKED:shared-dir-unresolved
+with the failed path. Never search another installation.
+
+Verify DEVLYN_SHARED_DIR/role-config.py and DEVLYN_SHARED_DIR/engine-doctor.sh before their respective commands. In omp, use `printf '%s\n' skill://devlyn-engines`.
 </runtime_paths>
 
 ## No args — status + how to choose

package/config/skills/devlyn-ideate/SKILL.md

@@ -28,22 +28,40 @@ Read `_shared/runtime-principles.md` (Subtractive-first / Goal-locked / Evidence
 </harness_principles>
 
 <runtime_paths>
-Resolve shared scripts from this skill's installed directory, never from the project cwd:
-
-```bash
-DEVLYN_SKILL_DIR="${CLAUDE_SKILL_DIR:-__DEVLYN_SKILL_DIR__}"
-if [ "$DEVLYN_SKILL_DIR" = "__DEVLYN_SKILL_DIR__" ] || [ ! -d "$DEVLYN_SKILL_DIR/../_shared" ]; then
-  echo "BLOCKED:shared-dir-unresolved: $DEVLYN_SKILL_DIR/../_shared" >&2
-  exit 1
-fi
-DEVLYN_SHARED_DIR="$(cd "$DEVLYN_SKILL_DIR/../_shared" && pwd)"
-if [ ! -f "$DEVLYN_SHARED_DIR/spec-verify-check.py" ]; then
-  echo "BLOCKED:shared-dir-unresolved: $DEVLYN_SHARED_DIR/spec-verify-check.py" >&2
-  exit 1
-fi
+Resolve bundled resources from the SKILL.md loaded for this invocation.
+
+Reader-rendered directory hint:
+```text
+${CLAUDE_SKILL_DIR}
 ```
 
-Use `python3 "$DEVLYN_SHARED_DIR/spec-verify-check.py"` for all spec validation commands. Claude Code supplies `CLAUDE_SKILL_DIR` by native render substitution; Codex/oh-my-pi installs receive an absolute copy-time stamp in the default branch. If the resolved skill directory is still the placeholder or `../_shared` is absent, stop with `BLOCKED:shared-dir-unresolved`.
+Treat the hint as literal path data, never shell code. If the reader
+replaced it with an absolute directory, use that directory. Otherwise
+use the filesystem path or base directory reported for this loaded
+SKILL.md. Resolve virtual URIs through the reader's native filesystem
+mapping. If available source locations name different directories,
+stop.
+
+Bind DEVLYN_SKILL_DIR to that absolute directory. Do not obtain this
+binding from an environment variable, cwd, or another installation.
+Verify its SKILL.md before proceeding. Missing or conflicting source
+identity is BLOCKED:skill-source-unresolved; include the failed path
+when known.
+
+Resolve bundled references against this directory. These bindings are
+workflow values: establish them explicitly using each tool or shell's
+literal-path rules, and include their absolute values in every fresh
+worker's prompt, telling it to set them from those values, never from
+its inherited environment. Do not rely on shell state surviving between
+calls.
+
+Resolve directory symlinks on DEVLYN_SKILL_DIR before deriving its
+sibling _shared. Bind that directory as DEVLYN_SHARED_DIR. References
+written as _shared/... use this binding. Verify the directory and each
+required resource before use; failure is BLOCKED:shared-dir-unresolved
+with the failed path. Never search another installation.
+
+Verify DEVLYN_SHARED_DIR/spec-verify-check.py before validation. Use `python3 "$DEVLYN_SHARED_DIR/spec-verify-check.py"` for spec validation commands after binding the path in that shell. In omp, use `printf '%s\n' skill://devlyn-ideate`.
 </runtime_paths>
 
 <engine_routing>

package/config/skills/devlyn-queue/SKILL.md

@@ -9,19 +9,42 @@ Utility front-end for the intent-queue contract in the project instructions ("In
 $ARGUMENTS
 </args>
 
-For `drain`, resolve the installed shared scripts before the first item:
-
-```bash
-DEVLYN_SKILL_DIR="${CLAUDE_SKILL_DIR:-__DEVLYN_SKILL_DIR__}"
-if [ "$DEVLYN_SKILL_DIR" = "__DEVLYN_SKILL_DIR__" ] || [ ! -d "$DEVLYN_SKILL_DIR/../_shared" ]; then
-  echo "BLOCKED:shared-dir-unresolved: $DEVLYN_SKILL_DIR/../_shared" >&2
-  exit 1
-fi
-DEVLYN_SHARED_DIR="$(cd "$DEVLYN_SKILL_DIR/../_shared" && pwd)"
+Before `add` or `drain`, establish the bindings below.
+
+Resolve bundled resources from the SKILL.md loaded for this invocation.
+
+Reader-rendered directory hint:
+```text
+${CLAUDE_SKILL_DIR}
 ```
 
-Before processing the first item, read and obey
-`../devlyn-resolve/references/outer-loop.md`. Its scoped-commit order is binding.
+Treat the hint as literal path data, never shell code. If the reader
+replaced it with an absolute directory, use that directory. Otherwise
+use the filesystem path or base directory reported for this loaded
+SKILL.md. Resolve virtual URIs through the reader's native filesystem
+mapping. If available source locations name different directories,
+stop.
+
+Bind DEVLYN_SKILL_DIR to that absolute directory. Do not obtain this
+binding from an environment variable, cwd, or another installation.
+Verify its SKILL.md before proceeding. Missing or conflicting source
+identity is BLOCKED:skill-source-unresolved; include the failed path
+when known.
+
+Resolve bundled references against this directory. These bindings are
+workflow values: establish them explicitly using each tool or shell's
+literal-path rules, and include their absolute values in every fresh
+worker's prompt, telling it to set them from those values, never from
+its inherited environment. Do not rely on shell state surviving between
+calls.
+
+Resolve directory symlinks on DEVLYN_SKILL_DIR before deriving its
+sibling _shared. Bind that directory as DEVLYN_SHARED_DIR. References
+written as _shared/... use this binding. Verify the directory and each
+required resource before use; failure is BLOCKED:shared-dir-unresolved
+with the failed path. Never search another installation.
+
+For `add`, verify DEVLYN_SKILL_DIR/scripts/append.py before invoking it. For `drain`, before processing the first item, read and obey ../devlyn-resolve/references/outer-loop.md (its scoped-commit order is binding) and read ../devlyn-resolve/references/task-completion.md, both relative to this bound skill directory. Load the sibling devlyn-resolve/SKILL.md by its absolute path and preserve this bundle's DEVLYN_SHARED_DIR when handing off; do not rediscover resolve by its bare command name. In omp, use `printf '%s\n' skill://devlyn-queue`.
 
 Queue state is base's `docs/specs/queue.md` plus owned receipts: for each `$(git rev-parse --git-common-dir)/devlyn-completion/*/receipt.json`, read `git show <ref>:docs/specs/queue.md` from its `recovery_ref` if that ref exists (it is never deleted), else its `branch` if it still exists; an item unmarked on base but `[x]`/`[F]` there counts as that mark. Two different terminal marks for one item stop for inspection. Status and drain selection both use this view.
 
@@ -31,10 +54,10 @@ Read the queue state above (absent `docs/specs/queue.md` → report "queue empty
 
 ## Subcommands
 
-- `add <intent text>` — append `- [ ] <intent>` to `docs/specs/queue.md` (create the file with its header if missing). If the intent came out of a conversation that already produced a spec, link it: `- [ ] (spec: docs/specs/<id>/spec.md) <intent>`.
+- `add <intent text>` — use the Write tool to place the exact full intent in a new file `.devlyn/queue-intent-<unique>.txt` (a name no other add uses, made of letters, digits, `.`, `_` and `-`, e.g. `queue-intent-20261001-1230-k3x9.txt`); do not create it with shell syntax. If the conversation already produced a spec, the file must start with `(spec: docs/specs/<id>/spec.md)`. Then, from the project root, run exactly once `python3 "$DEVLYN_SKILL_DIR/scripts/append.py" .devlyn/queue-intent-<unique>.txt`. The helper consumes that file, appends one `- [ ] <intent>` line at the physical end of `docs/specs/queue.md` under a lock (creating it with its header if missing), and is the sole queue writer. Never edit `docs/specs/queue.md` directly for `add` and never use a direct-edit fallback; a nonzero helper exit is shown to the user and stops the `add`.
 - `drain` — serial drain per the project-instructions contract. For each pending item, in order:
   1. Allocate the owner's absent task branch with `--worktree <absent path>` per `../devlyn-resolve/references/task-completion.md`, and work in that worktree; then spec it if unspecced (the queue entry is the user's go-ahead). Unattended assumptions may only take scope-narrowing, reversible, non-user-visible defaults; material ambiguity (user-visible behavior, data/state semantics, new files/scripts/flags, implementation surface) → mark `[F] needs-review: <question>`, commit that queue transition, and continue.
-  2. Bring only the current queue-item delta and linked spec bundle from the queue view into the task worktree, which starts from the fetched remote base with no other local commits, commit that scoped owner baseline, then run `/devlyn-resolve --spec <path>` hands-free.
+  2. Bring only the current queue-item delta and linked spec bundle from the queue view into the task worktree, which starts from the fetched remote base with no other local commits, commit that scoped owner baseline, then run the sibling devlyn-resolve loaded above with `--spec <path>` hands-free.
      After every resolve invocation, run `python3 "$DEVLYN_SHARED_DIR/terminal-claim-check.py" .`; exit 79 marks `[F] FAILED-INCOMPLETE` from the predicate, never from the session self-report.
   3. Outer loop on the terminal verdict: PASS → mark `[x]`. Findings-backed verdicts (NEEDS_WORK, BLOCKED:repair-budget-exhausted) → amend the spec, commit that scoped amendment, then re-run — at most 3 outer iterations. Infrastructure / invalid-input / engine-availability / implement-empty BLOCKED verdicts are not spec-amendable → mark `[F] <verdict>` immediately.
   4. Commit each terminal `[x]` / `[F]` queue transition before advancing. For successfully archived normal runs, invoke owner completion once after that declared queue-file-only commit; bind it separately from the verified source. Honor local-only/no-push. Failed products never publish. Retain PR/pending workspaces and use a separate owned branch from base for the next item; unavailable safe placement stops the drain with remaining items pending. A product-blocked item otherwise never halts the queue.

package/config/skills/devlyn-queue/scripts/append.py

@@ -0,0 +1,94 @@
+#!/usr/bin/env python3
+"""Append one normalized pending intent to the project queue."""
+
+import argparse
+import os
+import re
+import sys
+from contextlib import contextmanager
+from pathlib import Path
+
+
+QUEUE_PATH = Path("docs/specs/queue.md")
+LOCK_PATH = Path(".devlyn/queue.lock")
+# Each `add` writes its own handoff file, so two adds never consume each other's intent.
+HANDOFF = re.compile(r"\.devlyn/queue-intent-[A-Za-z0-9._-]+\.txt")
+MINIMAL_HEADER = b"# Intent Queue\n\n"
+
+
+@contextmanager
+def queue_lock():
+    """One writer at a time across processes, from creating the queue to the append."""
+    LOCK_PATH.parent.mkdir(parents=True, exist_ok=True)
+    fd = os.open(LOCK_PATH, os.O_RDWR | os.O_CREAT, 0o644)
+    try:
+        if os.name == "nt":
+            import msvcrt
+
+            # The CRT locks bytes that exist; give a new lock file its one byte.
+            if os.fstat(fd).st_size == 0:
+                os.write(fd, b"\0")
+            os.lseek(fd, 0, os.SEEK_SET)
+            msvcrt.locking(fd, msvcrt.LK_LOCK, 1)
+            try:
+                yield
+            finally:
+                os.lseek(fd, 0, os.SEEK_SET)
+                msvcrt.locking(fd, msvcrt.LK_UNLCK, 1)
+        else:
+            import fcntl
+
+            fcntl.flock(fd, fcntl.LOCK_EX)
+            yield
+    finally:
+        os.close(fd)
+
+
+def append_intent(queue_path, intent):
+    normalized = " ".join(intent.split())
+    if not normalized:
+        raise ValueError("intent must contain non-whitespace text")
+    item = f"- [ ] {normalized}\n".encode("utf-8")
+
+    with queue_lock():
+        if not queue_path.exists():
+            queue_path.parent.mkdir(parents=True, exist_ok=True)
+            queue_path.write_bytes(MINIMAL_HEADER + item)
+            return
+
+        with queue_path.open("rb") as queue:
+            queue.seek(0, 2)
+            size = queue.tell()
+            if size:
+                queue.seek(-1, 2)
+                ends_with_newline = queue.read(1) == b"\n"
+            else:
+                ends_with_newline = True
+
+        prefix = b"" if ends_with_newline else b"\n"
+        with queue_path.open("ab") as queue:
+            queue.write(prefix + item)
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(
+        description="Append one pending intent at the physical end of docs/specs/queue.md."
+    )
+    parser.add_argument("handoff", type=Path, help=".devlyn/queue-intent-<unique>.txt, relative to the project root")
+    args = parser.parse_args(argv)
+    if not HANDOFF.fullmatch(args.handoff.as_posix()):
+        parser.error(f"handoff must be .devlyn/queue-intent-<unique>.txt: {args.handoff}")
+    try:
+        try:
+            intent = args.handoff.read_text(encoding="utf-8")
+        finally:
+            args.handoff.unlink(missing_ok=True)
+        append_intent(QUEUE_PATH, intent)
+    except (OSError, UnicodeError, ValueError) as error:
+        print(f"queue add failed: {error}", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/config/skills/devlyn-resolve/SKILL.md

@@ -28,23 +28,42 @@ Every phase applies Subtractive-first / Goal-locked / No-workaround / Evidence,
 </harness_principles>
 
 <runtime_paths>
-Resolve shared scripts from this skill's installed directory, never from the project cwd. At PHASE 0, before any phase command:
-
-```bash
-DEVLYN_SKILL_DIR="${CLAUDE_SKILL_DIR:-__DEVLYN_SKILL_DIR__}"
-if [ "$DEVLYN_SKILL_DIR" = "__DEVLYN_SKILL_DIR__" ] || [ ! -d "$DEVLYN_SKILL_DIR/../_shared" ]; then
-  echo "BLOCKED:shared-dir-unresolved: $DEVLYN_SKILL_DIR/../_shared" >&2
-  exit 1
-fi
-DEVLYN_SHARED_DIR="$(cd "$DEVLYN_SKILL_DIR/../_shared" && pwd)"
-CODEX_MONITORED_PATH="$DEVLYN_SHARED_DIR/codex-monitored.sh"
-if [ ! -f "$CODEX_MONITORED_PATH" ]; then
-  echo "BLOCKED:shared-dir-unresolved: $CODEX_MONITORED_PATH" >&2
-  exit 1
-fi
+Before PHASE 0 or any phase command, establish the bindings below.
+
+Resolve bundled resources from the SKILL.md loaded for this invocation.
+
+Reader-rendered directory hint:
+```text
+${CLAUDE_SKILL_DIR}
 ```
 
-`DEVLYN_SHARED_DIR` is the only valid `_shared` anchor. Claude Code supplies `CLAUDE_SKILL_DIR` by native render substitution; Codex/oh-my-pi installs receive an absolute copy-time stamp in the default branch. If the resolved skill directory is still the placeholder, `../_shared` is absent, or a required script is missing, halt with report-level `BLOCKED:shared-dir-unresolved` and include the failed path. Pass the absolute `DEVLYN_SHARED_DIR` and `CODEX_MONITORED_PATH` into every fresh phase worker.
+Treat the hint as literal path data, never shell code. If the reader
+replaced it with an absolute directory, use that directory. Otherwise
+use the filesystem path or base directory reported for this loaded
+SKILL.md. Resolve virtual URIs through the reader's native filesystem
+mapping. If available source locations name different directories,
+stop.
+
+Bind DEVLYN_SKILL_DIR to that absolute directory. Do not obtain this
+binding from an environment variable, cwd, or another installation.
+Verify its SKILL.md before proceeding. Missing or conflicting source
+identity is BLOCKED:skill-source-unresolved; include the failed path
+when known.
+
+Resolve bundled references against this directory. These bindings are
+workflow values: establish them explicitly using each tool or shell's
+literal-path rules, and include their absolute values in every fresh
+worker's prompt, telling it to set them from those values, never from
+its inherited environment. Do not rely on shell state surviving between
+calls.
+
+Resolve directory symlinks on DEVLYN_SKILL_DIR before deriving its
+sibling _shared. Bind that directory as DEVLYN_SHARED_DIR. References
+written as _shared/... use this binding. Verify the directory and each
+required resource before use; failure is BLOCKED:shared-dir-unresolved
+with the failed path. Never search another installation.
+
+Bind CODEX_MONITORED_PATH to DEVLYN_SHARED_DIR/codex-monitored.sh and verify that file before proceeding. Pass DEVLYN_SKILL_DIR, DEVLYN_SHARED_DIR, and CODEX_MONITORED_PATH explicitly to every fresh phase worker. In omp, when this skill was selected by name, resolve it with `printf '%s\n' skill://devlyn-resolve` in its Bash tool.
 </runtime_paths>
 
 <engine_routing>

package/config/skills/devlyn-resolve/references/task-completion.md

@@ -7,8 +7,15 @@ authorized by the task scope; no additional approval ceremony is required.
 
 ## Allocate before work
 
-Use the installed `_shared/task-complete.py` from the anchor checkout,
-before committing owner inputs or starting direct/full work:
+Use the caller's DEVLYN_SHARED_DIR. When this reference is opened
+directly, derive that binding from ../../_shared relative to this
+reference's reader-supplied containing directory, resolving directory
+symlinks first. Missing source identity is
+BLOCKED:skill-source-unresolved; a missing task-complete.py is
+BLOCKED:shared-dir-unresolved. Never select another installation.
+
+Run the bound task-complete.py before committing owner inputs or
+starting direct/full work:
 
 ```sh
 python3 "$DEVLYN_SHARED_DIR/task-complete.py" allocate --repo . \

package/optional-skills/better-auth-setup/SKILL.md

@@ -30,13 +30,19 @@ The setup produces a dual-auth system: session cookies for browser users and API
 
 Read these when each step directs you to them:
 
-- `${CLAUDE_SKILL_DIR}/references/schema.md` — Complete Drizzle schema (auth, org, API key tables)
-- `${CLAUDE_SKILL_DIR}/references/middleware.md` — Auth middleware, tenant context, types, error handler
-- `${CLAUDE_SKILL_DIR}/references/api-keys.md` — Key generation, CRUD routes, security patterns
-- `${CLAUDE_SKILL_DIR}/references/config-and-entry.md` — Env config, error types, entry point wiring
-- `${CLAUDE_SKILL_DIR}/references/testing.md` — Test preload, seed factory, integration patterns
-- `${CLAUDE_SKILL_DIR}/references/proxy-setup.md` — Reverse proxy architecture, forwarding headers, OAuth callback routing
-- `${CLAUDE_SKILL_DIR}/references/proxy-gotchas.md` — Proxy-specific troubleshooting (redirect_uri_mismatch, state_mismatch, cookie prefix issues)
+Resolve the bundled references/... paths below against the directory
+containing the SKILL.md loaded for this invocation, using its opened
+path, reader-reported base directory, or native URI mapping. Never
+resolve them against cwd or another installation. Missing source
+identity is BLOCKED:skill-source-unresolved.
+
+- `references/schema.md` — Complete Drizzle schema (auth, org, API key tables)
+- `references/middleware.md` — Auth middleware, tenant context, types, error handler
+- `references/api-keys.md` — Key generation, CRUD routes, security patterns
+- `references/config-and-entry.md` — Env config, error types, entry point wiring
+- `references/testing.md` — Test preload, seed factory, integration patterns
+- `references/proxy-setup.md` — Reverse proxy architecture, forwarding headers, OAuth callback routing
+- `references/proxy-gotchas.md` — Proxy-specific troubleshooting (redirect_uri_mismatch, state_mismatch, cookie prefix issues)
 
 ## Handling Input
 
@@ -86,7 +92,7 @@ Generate the auth secret immediately (do not use a placeholder):
 bunx @better-auth/cli@latest secret
 ```
 
-Read `${CLAUDE_SKILL_DIR}/references/config-and-entry.md` for the complete Zod config implementation. Key env vars:
+Read `references/config-and-entry.md` for the complete Zod config implementation. Key env vars:
 
 | Variable | Required | Purpose |
 |----------|----------|---------|
@@ -104,7 +110,7 @@ Read `${CLAUDE_SKILL_DIR}/references/config-and-entry.md` for the complete Zod c
 **Entry:** Config validated at startup.
 **Exit:** Migration applied, tables created in PostgreSQL.
 
-Read `${CLAUDE_SKILL_DIR}/references/schema.md` for the complete schema. Key decisions:
+Read `references/schema.md` for the complete schema. Key decisions:
 
 - Use **plural table names** (`users`, `sessions`) — mapped to Better Auth's singular models in Step 3
 - Use **UUIDs** for all primary keys
@@ -284,7 +290,7 @@ authRoutes.on(["POST", "GET"], "/*", (c) => auth.handler(c.req.raw));
 **Entry:** Auth routes mounted.
 **Exit:** `src/middleware/auth.ts` validates API keys and session cookies.
 
-Read `${CLAUDE_SKILL_DIR}/references/middleware.md` for the complete implementation. The middleware:
+Read `references/middleware.md` for the complete implementation. The middleware:
 - Detects API keys via `Authorization: Bearer pyx_...` prefix
 - Validates via SHA-256 hash lookup + revocation + expiration checks
 - Falls back to Better Auth session cookie validation
@@ -299,7 +305,7 @@ Read `${CLAUDE_SKILL_DIR}/references/middleware.md` for the complete implementat
 **Entry:** Auth middleware populates `AuthContext` on the request.
 **Exit:** `src/middleware/tenant-context.ts` resolves org and plan.
 
-Read `${CLAUDE_SKILL_DIR}/references/middleware.md` for the implementation. Key behaviors:
+Read `references/middleware.md` for the implementation. Key behaviors:
 - API key auth: org already resolved from the key's project, just fetches plan
 - Session auth: looks up user's most recent org membership
 - Uses distinct error code `no_organization` (not generic `forbidden`) so the frontend can show "Create your first organization" instead of "Access denied"
@@ -311,7 +317,7 @@ Read `${CLAUDE_SKILL_DIR}/references/middleware.md` for the implementation. Key
 **Entry:** Middleware needs error classes to throw.
 **Exit:** `src/lib/errors.ts` with `AppError` hierarchy, `src/middleware/error-handler.ts`.
 
-Read `${CLAUDE_SKILL_DIR}/references/config-and-entry.md` for the complete error hierarchy and handler. Every error has a distinct `code` field for frontend differentiation:
+Read `references/config-and-entry.md` for the complete error hierarchy and handler. Every error has a distinct `code` field for frontend differentiation:
 
 | Error Class | Code | Status |
 |-------------|------|--------|
@@ -328,7 +334,7 @@ Read `${CLAUDE_SKILL_DIR}/references/config-and-entry.md` for the complete error
 **Entry:** All middleware and routes implemented.
 **Exit:** `src/index.ts` with correct middleware ordering.
 
-Read `${CLAUDE_SKILL_DIR}/references/config-and-entry.md` for the complete entry point. The middleware order is:
+Read `references/config-and-entry.md` for the complete entry point. The middleware order is:
 
 1. **Request ID** — first, so error handler can include it in responses
 2. **Security Headers** — HSTS (production), X-Frame-Options
@@ -348,7 +354,7 @@ CORS before auth routes is non-negotiable. If registered after, preflight OPTION
 **Entry:** Application fully functional.
 **Exit:** Test preload, seed factory, integration app, cleanup utilities.
 
-Read `${CLAUDE_SKILL_DIR}/references/testing.md` for the complete test setup. Essential components:
+Read `references/testing.md` for the complete test setup. Essential components:
 
 1. **Test preload** (`bunfig.toml` + `setup.ts`) — clears `RESEND_API_KEY`, bridges `TEST_DATABASE_URL`
 2. **Seed factory** (`seedTestData()`) — creates full tenant hierarchy with unique slugs
@@ -413,7 +419,7 @@ If any item fails, fix the root cause before proceeding.
 
 ## API Key System
 
-For the complete custom API key implementation (generation, validation, CRUD routes), read `${CLAUDE_SKILL_DIR}/references/api-keys.md`.
+For the complete custom API key implementation (generation, validation, CRUD routes), read `references/api-keys.md`.
 
 Summary:
 - **Format**: `pyx_` prefix + 32 random bytes base62-encoded (~50 chars)
@@ -447,7 +453,7 @@ Always append a unique suffix (UUID slice or timestamp) to prevent collisions.
 
 ## Proxy Architecture (Steps 12-14)
 
-These steps apply when the frontend is a separate application that proxies auth requests to the backend. Read `${CLAUDE_SKILL_DIR}/references/proxy-setup.md` for the complete guide with code examples.
+These steps apply when the frontend is a separate application that proxies auth requests to the backend. Read `references/proxy-setup.md` for the complete guide with code examples.
 
 ### Step 12: Configure Dynamic baseURL on Backend
 
@@ -499,7 +505,7 @@ socialProviders: {
 **Entry:** Backend uses `allowedHosts` with `trustedProxyHeaders`.
 **Exit:** Frontend proxies auth requests and OAuth callbacks correctly.
 
-The frontend proxy must do three things. Read `${CLAUDE_SKILL_DIR}/references/proxy-setup.md` for complete code.
+The frontend proxy must do three things. Read `references/proxy-setup.md` for complete code.
 
 #### 13a. Create two proxy routes
 
@@ -592,7 +598,7 @@ curl -s -X POST "https://your-frontend.com/api/auth/sign-in/social" \
 
 Expected: `redirect_uri: https://your-frontend.com/auth/callback/google`
 
-For detailed troubleshooting of proxy-specific failures, read `${CLAUDE_SKILL_DIR}/references/proxy-gotchas.md`.
+For detailed troubleshooting of proxy-specific failures, read `references/proxy-gotchas.md`.
 
 ---
 

package/optional-skills/devlyn-reap/SKILL.md

@@ -38,10 +38,41 @@ If the user's intent is ambiguous (e.g., they say "지워줘" but didn't specify
 
 Always run scan first — even in KILL mode — so the user sees what is about to happen.
 
-Run the bundled scanner. The skill is installed at `~/.claude/skills/devlyn-reap/`:
+Resolve bundled resources from the SKILL.md loaded for this invocation.
+
+Reader-rendered directory hint:
+```text
+${CLAUDE_SKILL_DIR}
+```
+
+Treat the hint as literal path data, never shell code. If the reader
+replaced it with an absolute directory, use that directory. Otherwise
+use the filesystem path or base directory reported for this loaded
+SKILL.md. Resolve virtual URIs through the reader's native filesystem
+mapping. If available source locations name different directories,
+stop.
+
+Bind DEVLYN_SKILL_DIR to that absolute directory. Do not obtain this
+binding from an environment variable, cwd, or another installation.
+Verify its SKILL.md before proceeding. Missing or conflicting source
+identity is BLOCKED:skill-source-unresolved; include the failed path
+when known.
+
+Resolve bundled references against this directory. These bindings are
+workflow values: establish them explicitly using each tool or shell's
+literal-path rules, and include their absolute values in every fresh
+worker's prompt, telling it to set them from those values, never from
+its inherited environment. Do not rely on shell state surviving between
+calls.
+
+In omp, use: printf '%s\n' skill://devlyn-reap
+Verify the requested script under this bound directory before running
+it; a missing script is BLOCKED:skill-source-unresolved with its path.
+
+Run the bundled scanner:
 
 ```bash
-bash ~/.claude/skills/devlyn-reap/scripts/scan.sh
+bash "$DEVLYN_SKILL_DIR/scripts/scan.sh"
 ```
 
 Report the output verbatim to the user. Then add your own 2-line summary:
@@ -60,7 +91,7 @@ sysctl kern.maxprocperuid kern.tty.ptmx_max 2>/dev/null
 Run the reap script with the parsed flags:
 
 ```bash
-bash ~/.claude/skills/devlyn-reap/scripts/reap.sh [flags]
+bash "$DEVLYN_SKILL_DIR/scripts/reap.sh" [flags]
 ```
 
 Show the output verbatim. The script re-verifies `PPID==1 && user==current` for every PID right before signaling — a process that was legitimately adopted since the scan will be skipped, not killed.

package/optional-skills/dokkit/COMMANDS.md

@@ -187,12 +187,12 @@ File path to the template document (DOCX or HWPX).
 
 **Phase 3 — Source Images**:
 7. **Cell-level images**: For each `field_type: "image"` with `image_file: null` and `image_type: "figure"`:
-   - Run: `python .claude/skills/dokkit/scripts/source_images.py generate --prompt "<prompt>" --preset technical_illustration --output-dir .dokkit/images/ --project-dir . --lang ko`
+   - Run: `python "$DEVLYN_SKILL_DIR/scripts/source_images.py" generate --prompt "<prompt>" --preset technical_illustration --output-dir .dokkit/images/ --project-dir . --lang ko`
    - Parse `__RESULT__` JSON, update `analysis.json`
    - Skip photo/signature types (require user-provided files)
    - Default `--lang ko` (Korean only). Override with user instruction if needed.
 8. **Section content images**: For each `image_opportunities` entry with `status: "pending"`:
-   - Run: `python .claude/skills/dokkit/scripts/source_images.py generate --prompt "<generation_prompt>" --preset <preset> --output-dir .dokkit/images/ --project-dir . --lang ko`
+   - Run: `python "$DEVLYN_SKILL_DIR/scripts/source_images.py" generate --prompt "<generation_prompt>" --preset <preset> --output-dir .dokkit/images/ --project-dir . --lang ko`
    - On failure: set `status: "skipped"`, log reason
    - Use `--lang ko+en` if the content contains technical terms that benefit from English (e.g., architecture diagrams with API names).
 9. Report: "Sourced X/Y images"
@@ -272,8 +272,8 @@ File path to the template document (DOCX or HWPX).
 > "Analyze the template at `<path>`. Detect all fillable fields INCLUDING image fields. Map to sources. Write `analysis.json`."
 
 **Image sourcing** (inline, between agents):
-- **Pass A — Cell-level**: For `field_type: "image"` with `image_file: null` and `image_type: "figure"`, run `python .claude/skills/dokkit/scripts/source_images.py generate --prompt "..." --preset ... --output-dir .dokkit/images/ --project-dir . --lang ko`
-- **Pass B — Section content**: For `image_opportunities` with `status: "pending"`, run `python .claude/skills/dokkit/scripts/source_images.py generate --prompt "..." --preset ... --output-dir .dokkit/images/ --project-dir . --lang ko`
+- **Pass A — Cell-level**: For `field_type: "image"` with `image_file: null` and `image_type: "figure"`, run `python "$DEVLYN_SKILL_DIR/scripts/source_images.py" generate --prompt "..." --preset ... --output-dir .dokkit/images/ --project-dir . --lang ko`
+- **Pass B — Section content**: For `image_opportunities` with `status: "pending"`, run `python "$DEVLYN_SKILL_DIR/scripts/source_images.py" generate --prompt "..." --preset ... --output-dir .dokkit/images/ --project-dir . --lang ko`
 - Default language is `ko` (Korean only). Use `--lang ko+en` for mixed content, or `--lang en` for English-only.
 
 **Then**: Spawn the dokkit-filler agent in fill mode:

package/optional-skills/dokkit/EXPORT.md

@@ -41,8 +41,8 @@ def compile_hwpx(work_dir: str, output_path: str):
 
 ### Scripts
 ```bash
-python .claude/skills/dokkit/scripts/compile_hwpx.py <work_dir> <output.hwpx>
-python .claude/skills/dokkit/scripts/export_pdf.py <input> <output.pdf>
+python "$DEVLYN_SKILL_DIR/scripts/compile_hwpx.py" <work_dir> <output.hwpx>
+python "$DEVLYN_SKILL_DIR/scripts/export_pdf.py" <input> <output.pdf>
 ```
 
 ## PDF Conversion
@@ -54,7 +54,7 @@ soffice --headless --convert-to pdf --outdir <output_dir> <input_file>
 
 ### Using Python Script
 ```bash
-python .claude/skills/dokkit/scripts/export_pdf.py <input> <output.pdf>
+python "$DEVLYN_SKILL_DIR/scripts/export_pdf.py" <input> <output.pdf>
 ```
 
 ## Cross-Format Conversion

package/optional-skills/dokkit/FILLING.md

@@ -15,24 +15,24 @@ Field detection, matching strategies, and surgical XML editing rules for the dok
 
 ### DOCX Field Detection
 ```bash
-python .claude/skills/dokkit/scripts/detect_fields.py <document.xml>
+python "$DEVLYN_SKILL_DIR/scripts/detect_fields.py" <document.xml>
 ```
 Outputs JSON array of detected fields with labels, types, and XML paths.
 
 ### HWPX Field Detection
 ```bash
-python .claude/skills/dokkit/scripts/detect_fields_hwpx.py <section.xml>
+python "$DEVLYN_SKILL_DIR/scripts/detect_fields_hwpx.py" <section.xml>
 ```
 Same output format, adapted for HWPX XML structure.
 
 ### DOCX Validation
 ```bash
-python .claude/skills/dokkit/scripts/validate_docx.py <work_dir>
+python "$DEVLYN_SKILL_DIR/scripts/validate_docx.py" <work_dir>
 ```
 
 ### HWPX Validation
 ```bash
-python .claude/skills/dokkit/scripts/validate_hwpx.py <work_dir>
+python "$DEVLYN_SKILL_DIR/scripts/validate_hwpx.py" <work_dir>
 ```
 
 ## Matching Strategy

package/optional-skills/dokkit/IMAGE-SOURCING.md

@@ -25,7 +25,7 @@ Via `/dokkit modify "use <file>"`:
 
 ### 3. AI Generation
 ```bash
-python .claude/skills/dokkit/scripts/source_images.py generate \
+python "$DEVLYN_SKILL_DIR/scripts/source_images.py" generate \
   --prompt "인포그래픽: AI 감정 케어 플랫폼 4단계 로드맵" \
   --preset infographic \
   --output-dir .dokkit/images/ \
@@ -61,7 +61,7 @@ Use `--aspect-ratio 16:9` to override. Use `--no-enhance` to skip preset style i
 
 ### 4. Web Search
 ```bash
-python .claude/skills/dokkit/scripts/source_images.py search \
+python "$DEVLYN_SKILL_DIR/scripts/source_images.py" search \
   --query "company logo example" \
   --output-dir .dokkit/images/
 ```

package/optional-skills/dokkit/INGESTION.md

@@ -12,11 +12,11 @@ Parsing strategies and format routing for converting source documents into the d
 | HTML | Docling | `python -m docling <file> --to md` |
 | CSV | Docling | `python -m docling <file> --to md` |
 | MD | Direct copy | Read and process as-is |
-| XLSX | Custom | `python .claude/skills/dokkit/scripts/parse_xlsx.py` |
-| HWPX | Custom | `python .claude/skills/dokkit/scripts/parse_hwpx.py` |
+| XLSX | Custom | `python "$DEVLYN_SKILL_DIR/scripts/parse_xlsx.py"` |
+| HWPX | Custom | `python "$DEVLYN_SKILL_DIR/scripts/parse_hwpx.py"` |
 | JSON | Custom | Read, format as structured markdown |
 | TXT | Custom | Read, wrap as markdown |
-| PNG/JPG | Gemini Vision | `python .claude/skills/dokkit/scripts/parse_image_with_gemini.py` |
+| PNG/JPG | Gemini Vision | `python "$DEVLYN_SKILL_DIR/scripts/parse_image_with_gemini.py"` |
 
 ## Docling Usage
 

package/optional-skills/dokkit/PIPELINE.md

@@ -1,7 +1,8 @@
 # Dokkit Pipeline Reference
 
 Detailed step-by-step procedure for the one-command document filling pipeline.
-Auto-loaded when `/dokkit` is invoked.
+Read by the invoking skill before execution; bundled paths use the
+DEVLYN_SKILL_DIR binding it passes.
 
 ## Table of Contents
 
@@ -119,7 +120,7 @@ Report: `Phase 3/6: Generated content for N fields`
 Run the python-docx assembly script (NOT raw XML surgery):
 
 ```bash
-python .claude/skills/dokkit/scripts/fill_docx.py \
+python "$DEVLYN_SKILL_DIR/scripts/fill_docx.py" \
   <template.docx> \
   .dokkit/analysis.json \
   .dokkit/fill_content.json \
@@ -150,7 +151,7 @@ For each image field and image opportunity in `analysis.json`, run in parallel.
 **CRITICAL: Always pass `--field-id` and `--purpose`** so the image manifest tracks which image was generated for which slot. Without this, images get randomly assigned to the wrong slots.
 
 ```bash
-python .claude/skills/dokkit/scripts/source_images.py generate \
+python "$DEVLYN_SKILL_DIR/scripts/source_images.py" generate \
   --prompt "<prompt>" \
   --preset <preset> \
   --output-dir .dokkit/images/ \
@@ -345,4 +346,4 @@ Phase 5 → quality_gates results, iterations_count
 Phase 6 → exports[] entry added
 ```
 
-Validate after every write: `python ${CLAUDE_SKILL_DIR}/scripts/validate_state.py .dokkit/state.json`
+Validate after every write: `python "$DEVLYN_SKILL_DIR/scripts/validate_state.py" .dokkit/state.json`

package/optional-skills/dokkit/SKILL.md

@@ -13,15 +13,45 @@ description: >
 user-invocable: true
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep, Agent
 argument-hint: "<template_path> <sources_folder> | improve [instruction]"
-context:
-  - type: file
-    path: ${CLAUDE_SKILL_DIR}/PIPELINE.md
 ---
 
 # Dokkit — One-Command Document Filling
 
 Source folder + template → finished document. Fully automatic, iterates until perfect.
 
+Resolve bundled resources from the SKILL.md loaded for this invocation.
+
+Reader-rendered directory hint:
+```text
+${CLAUDE_SKILL_DIR}
+```
+
+Treat the hint as literal path data, never shell code. If the reader
+replaced it with an absolute directory, use that directory. Otherwise
+use the filesystem path or base directory reported for this loaded
+SKILL.md. Resolve virtual URIs through the reader's native filesystem
+mapping. If available source locations name different directories,
+stop.
+
+Bind DEVLYN_SKILL_DIR to that absolute directory. Do not obtain this
+binding from an environment variable, cwd, or another installation.
+Verify its SKILL.md before proceeding. Missing or conflicting source
+identity is BLOCKED:skill-source-unresolved; include the failed path
+when known.
+
+Resolve bundled references against this directory. These bindings are
+workflow values: establish them explicitly using each tool or shell's
+literal-path rules, and include their absolute values in every fresh
+worker's prompt, telling it to set them from those values, never from
+its inherited environment. Do not rely on shell state surviving between
+calls.
+
+Read PIPELINE.md from this bound directory before executing the
+workflow. Bundled Markdown, references, and scripts use this same
+directory. Project data under .dokkit remains project-relative.
+Pass the absolute binding and required resource paths explicitly
+to every worker.
+
 ## Usage
 
 ```
@@ -113,7 +143,7 @@ These rules prevent the font corruption issues seen in previous versions:
 
 **Never write inline Gemini API calls for image generation.** Always use the provided script:
 ```bash
-python ${CLAUDE_SKILL_DIR}/scripts/source_images.py generate \
+python "$DEVLYN_SKILL_DIR/scripts/source_images.py" generate \
   --prompt "<prompt>" --preset <preset> --output-dir .dokkit/images/ \
   --project-dir . --lang ko
 ```
@@ -173,7 +203,7 @@ display_h = int(actual_h * scale)
 
 | File | Purpose | Used By |
 |------|---------|---------|
-| `PIPELINE.md` | Detailed pipeline steps (auto-loaded) | Orchestrator |
+| `PIPELINE.md` | Detailed pipeline steps (read before execution) | Orchestrator |
 | `STATE.md` | State schema and management | All agents |
 | `INGESTION.md` | Source file parsing | Ingestor |
 | `ANALYSIS.md` | Field detection, structure mapping | Analyzer |

package/optional-skills/dokkit/STATE.md

@@ -33,7 +33,7 @@ After any mutation:
 1. Read current state.json (avoid overwriting concurrent changes)
 2. Update only the relevant fields
 3. Write the full state back
-4. Validate: `python .claude/skills/dokkit/scripts/validate_state.py .dokkit/state.json`
+4. Validate: `python "$DEVLYN_SKILL_DIR/scripts/validate_state.py" .dokkit/state.json`
 
 ## State Transitions
 

package/optional-skills/dokkit/references/image-opportunity-heuristics.md

@@ -113,7 +113,7 @@ Each opportunity is added to the field's `image_opportunities` array:
 - `insertion_point.strategy`: Always `"after_paragraph"` for section content
 - `insertion_point.anchor_text`: Distinctive Korean phrase from the paragraph (used by filler to locate insertion point)
 - `generation_prompt`: English prompt for AI image generation
-- `preset`: Maps to `.claude/skills/dokkit/scripts/source_images.py` preset parameter
+- `preset`: Maps to the bundled `scripts/source_images.py` preset parameter
 - `content_type`: One of `flowchart`, `diagram`, `data`, `concept`, `infographic`
 - `rationale`: Brief explanation of why an image helps here
 - `dimensions`: Default size — filler may adjust based on content_type

package/optional-skills/generate-skill/REFERENCE.md

@@ -46,7 +46,6 @@ Complete catalog of YAML frontmatter fields for Claude Code skill files (`SKILL.
 | `argument-hint` | string | none | Placeholder shown to user (e.g., `"[file path]"`) |
 | `user-invocable` | boolean | `true` | Whether users can trigger via `/skill-name` |
 | `disable-model-invocation` | boolean | `false` | If `true`, Claude cannot proactively trigger the skill |
-| `context` | list | none | Files to inject into context when skill activates |
 | `agent` | object | none | Run skill as a subagent with its own context |
 | `model` | string | inherited | Override model (`opus`, `sonnet`, `haiku`) |
 | `hooks` | object | none | Shell commands to run on skill lifecycle events |
@@ -62,20 +61,15 @@ allowed-tools: Read, Bash(npm test *), Bash(npx *)
 
 Wildcard `*` matches any arguments. Without a glob, Bash runs any command.
 
-### `context` Field
+### Supporting files
 
-Inject files into the skill's context automatically:
+Read supporting files explicitly from the skill body:
 
-```yaml
-context:
-  - type: file
-    path: ${CLAUDE_SKILL_DIR}/PATTERNS.md
-  - type: file
-    path: ./CLAUDE.md
+```text
+Before proceeding, read PATTERNS.md relative to the directory
+containing this loaded SKILL.md.
 ```
 
-Use `${CLAUDE_SKILL_DIR}` for paths relative to the skill directory.
-
 ### `agent` Field
 
 Run the skill as an isolated subagent:
@@ -102,7 +96,10 @@ hooks:
 
 ## String Substitutions
 
-These placeholders are replaced at runtime:
+Claude Code replaces these placeholders when rendering a skill.
+They are reader substitutions, not portable shell environment
+variables. Portable resource references use the selected skill
+directory and relative paths.
 
 | Placeholder | Replaced With |
 |---|---|
@@ -116,7 +113,7 @@ These placeholders are replaced at runtime:
 ```markdown
 Parse `$ARGUMENTS` for the file path.
 If `$1` is empty, ask the user for a target file.
-Read the config from `${CLAUDE_SKILL_DIR}/config.yaml`.
+Read config.yaml relative to this loaded skill's directory.
 ```
 
 ---

package/optional-skills/generate-skill/SKILL.md

@@ -15,6 +15,13 @@ argument-hint: "[skill description or name]"
 Create production-quality Claude Code skills with correct frontmatter, structured workflows, and Claude 4.6 prompt patterns.
 
 Reference files in this skill directory:
+
+Resolve the bundled reference paths below against the directory
+containing the SKILL.md loaded for this invocation, using its opened
+path, reader-reported base directory, or native URI mapping. Never
+resolve them against cwd or another installation. Missing source
+identity is BLOCKED:skill-source-unresolved.
+
 - `REFERENCE.md` — Complete frontmatter field catalog and validation rules
 - `PROMPT-PATTERNS.md` — Claude 4.6 prompt engineering patterns for skill bodies
 - `CHECKLIST.md` — Quality verification checklist
@@ -50,11 +57,13 @@ Estimate the total line count for the skill content:
 Rules for reference files:
 - One level deep only (no nested references)
 - Add a table of contents if a reference file exceeds 100 lines
-- Reference files use `${CLAUDE_SKILL_DIR}/FILENAME.md` for paths
+- Reference files use paths relative to the generated SKILL.md, with
+  an explicit instruction to resolve them against the loaded skill
+  directory.
 
 ### Step 3: Write Frontmatter
 
-Read `${CLAUDE_SKILL_DIR}/REFERENCE.md` for the complete field catalog.
+Read `REFERENCE.md` for the complete field catalog.
 
 Apply these rules:
 - `name`: lowercase, hyphens only, max 64 chars, no "anthropic" or "claude"
@@ -64,7 +73,7 @@ Apply these rules:
 
 ### Step 4: Write Skill Body
 
-Read `${CLAUDE_SKILL_DIR}/PROMPT-PATTERNS.md` for Claude 4.6 patterns.
+Read `PROMPT-PATTERNS.md` for Claude 4.6 patterns.
 
 Structure the body in this order:
 1. **Title and purpose** — One-line summary of what the skill does and why
@@ -111,7 +120,7 @@ For multi-file skills, create reference files:
 
 ### Step 7: Validate
 
-Read `${CLAUDE_SKILL_DIR}/CHECKLIST.md` and verify the generated skill against every item.
+Read `CHECKLIST.md` and verify the generated skill against every item.
 
 Fix any issues before presenting the final output.
 
@@ -124,7 +133,6 @@ After generating the skill, present:
 3. **Test invocation** — Example command to test the skill
 
 Offer to:
-- Run `/devlyn:review` on the generated skill for quality assurance
 - Run `pyx-scan` if the skill will be published
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devlyn-cli",
-  "version": "4.0.0",
+  "version": "4.0.1",
   "description": "Loop & harness engineering for AI coding agents (Claude Code, Codex, and any AGENTS.md-driven agent) — take intent to shipped, engineer-quality software hands-free with phase-gated pipelines and agent orchestration",
   "homepage": "https://github.com/fysoul17/devlyn-cli#readme",
   "bin": {