devlyn-cli 4.0.0 → 4.1.0

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>
@@ -318,7 +337,7 @@ When the OTHER engine is available, persist `pair_trigger` before spawn with `pa
 
 Keep the existing reasons as telemetry: `mode.verify-only`, `mode.pair-verify`, `complexity.high`, `complexity.large`, `spec.complexity.high`, `spec.complexity.large`, `spec.solo_headroom_hypothesis`, `risk.high`, `risk_probes.enabled`, `risk_probes.present`, `coverage.failed`, `mechanical.warning`, and `judge.warning`. Append the outcome-dependent reasons only after both judges return. Eligible schema-v3 state must include `pair.default`; all other applicable reasons remain completeness-checked. Malformed risk or trigger state BLOCKs VERIFY.
 
-Pair-mode JUDGE: spawn a second Agent with the OTHER engine's adapter; the second judge is a bounded adversarial complement, not a duplicate broad audit. The primary judge owns broad coverage; pair-JUDGE reviews the two highest-risk explicit `## Verification` bullets that cross state mutation, all-or-nothing rollback, ordering, idempotency, auth, or error-priority clauses. It must not read `.claude/skills`, `.codex/skills`, `CLAUDE.md`, `AGENTS.md`, or other harness docs unless the orchestrator pasted a specific excerpt into the prompt. It may use only the spec, diff, implementation files, tests, and sealed MECHANICAL evidence. It performs at most two targeted reviews before first output; inspection remains read-only. When the spec names exact keys, row shapes, JSON object shape, or an exact error body, pair-JUDGE compares the sealed parsed key sets/deep equality so aliased keys, missing keys, and extra keys are verdict-binding failures. For priority/stateful specs, trace code order for an earlier input entity that would succeed under input-order processing, a later higher-priority entity that consumes or blocks the critical resource, and a failure/blocked/rollback edge that determines a later entity's state. Scope qualifiers are binding: pair-JUDGE must not reinterpret `inside a warehouse`, `per resource`, or line-scoped rules as global rules. When both priority ordering and rollback/blocked-interval behavior appear in the spec, this dominance-loss review comes first: trace whether the earlier lower-priority entity loses because the later higher-priority entity is processed first, whether a failed/blocked middle entity leaves later state intact, and whether the sealed evidence covers complete accepted/scheduled and rejected output ordering. Missing executable coverage is a verdict-binding coverage finding; JUDGE does not invent or run the missing scenario. Pair-JUDGE output: emit JSONL findings then a bare terminal verdict line, or emit only `PASS` when clean. `_shared/judge-output-parser.py` is the single acceptance rule for pair output: JSONL findings, then a `# SUMMARY {json}` line or a bare verdict line (`PASS` alone when clean); it ignores bare code-fence lines and unwraps the registered Codex JSON envelope including its narrated-preamble recovery (iter-0082), and binds a whole-message NDJSON capture only through its uniquely attested terminal `end_turn` assistant message (iter-0106); every other non-empty line blocks the pair source. Both judgments merge with the rule "any HIGH/CRITICAL finding is verdict-binding; any MEDIUM with literal `verdict_binding: true` is also binding, regardless of confidence." Demonstrated applicable mandatory-clause violations, including unmet new requirements and incorrect customer documentation, must use one of those binding forms. Apply the canonical VERIFY clause/evidence and advisory boundaries; impact, rarity or pre-existing origin alone does not excuse an applicable violation. Cross-model disagreement on advisory lower-severity findings is logged but does not change the verdict. A primary JUDGE verdict-binding finding on a concurrent run does not cancel or discard the pair-JUDGE; both finding sets join the same fix round, and the merged verdict remains the worst source verdict without vote counting. `primary_judge_blocker` is parser-recognized only for archived v2.0 replay; new runs never write it. A verdict-binding MECHANICAL blocker still skips both judges and records `pair_judge: null`.
+Pair-mode JUDGE: spawn a second Agent with the OTHER engine's adapter; the second judge is a bounded adversarial complement, not a duplicate broad audit. The primary judge owns broad coverage; pair-JUDGE reviews the two highest-risk explicit `## Verification` bullets that cross state mutation, all-or-nothing rollback, ordering, idempotency, auth, or error-priority clauses. It must not read `.claude/skills`, `.codex/skills`, `.agents/skills`, `CLAUDE.md`, `AGENTS.md`, or other harness docs unless the orchestrator pasted a specific excerpt into the prompt. It may use only the spec, diff, implementation files, tests, and sealed MECHANICAL evidence. It performs at most two targeted reviews before first output; inspection remains read-only. When the spec names exact keys, row shapes, JSON object shape, or an exact error body, pair-JUDGE compares the sealed parsed key sets/deep equality so aliased keys, missing keys, and extra keys are verdict-binding failures. For priority/stateful specs, trace code order for an earlier input entity that would succeed under input-order processing, a later higher-priority entity that consumes or blocks the critical resource, and a failure/blocked/rollback edge that determines a later entity's state. Scope qualifiers are binding: pair-JUDGE must not reinterpret `inside a warehouse`, `per resource`, or line-scoped rules as global rules. When both priority ordering and rollback/blocked-interval behavior appear in the spec, this dominance-loss review comes first: trace whether the earlier lower-priority entity loses because the later higher-priority entity is processed first, whether a failed/blocked middle entity leaves later state intact, and whether the sealed evidence covers complete accepted/scheduled and rejected output ordering. Missing executable coverage is a verdict-binding coverage finding; JUDGE does not invent or run the missing scenario. Pair-JUDGE output: emit JSONL findings then a bare terminal verdict line, or emit only `PASS` when clean. `_shared/judge-output-parser.py` is the single acceptance rule for pair output: JSONL findings, then a `# SUMMARY {json}` line or a bare verdict line (`PASS` alone when clean); it ignores bare code-fence lines and unwraps the registered Codex JSON envelope including its narrated-preamble recovery (iter-0082), and binds a whole-message NDJSON capture only through its uniquely attested terminal `end_turn` assistant message (iter-0106); every other non-empty line blocks the pair source. Both judgments merge with the rule "any HIGH/CRITICAL finding is verdict-binding; any MEDIUM with literal `verdict_binding: true` is also binding, regardless of confidence." Demonstrated applicable mandatory-clause violations, including unmet new requirements and incorrect customer documentation, must use one of those binding forms. Apply the canonical VERIFY clause/evidence and advisory boundaries; impact, rarity or pre-existing origin alone does not excuse an applicable violation. Cross-model disagreement on advisory lower-severity findings is logged but does not change the verdict. A primary JUDGE verdict-binding finding on a concurrent run does not cancel or discard the pair-JUDGE; both finding sets join the same fix round, and the merged verdict remains the worst source verdict without vote counting. `primary_judge_blocker` is parser-recognized only for archived v2.0 replay; new runs never write it. A verdict-binding MECHANICAL blocker still skips both judges and records `pair_judge: null`.
 
 If the OTHER engine is unavailable, only unconfigured automatic VERIFY records
 `auto_pair_other_engine_unavailable` and continues solo. Explicit `--pair-verify`,

package/config/skills/devlyn-resolve/references/phases/probe-derive.md

@@ -24,7 +24,7 @@ second planner, critic essay, or debate participant. Your output is JSONL only.
 <forbidden_input>
 Do not read `spec.expected.json`, `.devlyn/spec-verify.json`,
 `BENCH_FIXTURE_DIR`, benchmark fixture/verifier paths, `.devlyn/*.findings.jsonl`,
-`.claude/skills`, `.codex/skills`, `CLAUDE.md`, `AGENTS.md`, or other harness
+`.claude/skills`, `.codex/skills`, `.agents/skills`, `CLAUDE.md`, `AGENTS.md`, or other harness
 docs unless the orchestrator pasted a specific excerpt into the prompt.
 </forbidden_input>
 

package/config/skills/devlyn-resolve/references/phases/verify.md

@@ -187,7 +187,7 @@ When eligible and the orchestrator spawns a second VERIFY agent with the OTHER e
   state mutation, all-or-nothing rollback, ordering, idempotency, auth, or
   error-priority clauses. The primary judge owns broad coverage; the pair judge
   is a bounded adversarial complement. Do not read `.claude/skills`,
-  `.codex/skills`, `CLAUDE.md`, `AGENTS.md`, or other harness docs unless the
+  `.codex/skills`, `.agents/skills`, `CLAUDE.md`, `AGENTS.md`, or other harness docs unless the
   orchestrator pasted a specific excerpt into the prompt. Use only the spec,
   diff, implementation files, tests, and sealed MECHANICAL evidence. Complete at
   most two targeted reviews before first output; inspection remains read-only.

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.
 ```
 
 ---