T-ZQ3M-project-local-extension-doc-shows-invocation

Status: planning/backlog · Impact: low · Complexity: small

Auto-generated from a /sdlc:task-work post-mortem. Review and promote to open/ready before picking up.

Goal

plugin/conventions/project-local-skill-extension.md describes the hook contract declaratively (“working directory: the project root”; “environment: TASK_FILE=…”). It does NOT show the actual shell invocation an upstream skill should use to honor those constraints. A future skill author following the prose literally without setting cwd may invoke a hook with the wrong working directory and silently break it. Cited by T-R4XL-project-local-skill-extension-mechanism.

Today

The convention doc says:

3. Invoke the hook with the documented inputs, in the project root’s working directory (so relative paths in the hook resolve against the project, not the worktree).

But it doesn’t show how to do that — there’s no example invocation. plugin/skills/task-work/SKILL.md Step 1a likewise describes the contract but doesn’t show the invocation, so the prose pattern propagates.

Proposed

The convention doc carries a canonical example of how to invoke a hook from a SKILL.md, e.g.:

if `-x .sdlc/skill-ext/<slug>/<event>.sh`; then
    (cd "<project-root>" && TASK_FILE="<abs-path>" \
        .sdlc/skill-ext/<slug>/<event>.sh) || true
fi

The || true makes the informational-hook exit-code contract explicit; the subshell scopes the cwd change; the env-var assignment is inline. Skill authors copy the pattern verbatim instead of re-deriving it.

Approach

1. Add a “Reference invocation” subsection to the convention doc showing the bash snippet above.
2. Optionally: cross-reference the snippet from each SKILL.md that declares an extension point, so the contract stays executable.

Files to touch

Location	Kind	Change
plugin/conventions/project-local-skill-extension.md	modify	add the

Acceptance criteria

• AC-1: The convention doc contains a copy-pasteable bash snippet showing the canonical hook invocation (subshell + cwd + env var + ignore-exit-code).
• AC-2: At least one upstream SKILL.md declaring an extension point references the snippet (or inlines an instance of it) so the contract is executable, not just declarative.

Out of scope

• none

Dependencies

• none

Discovery context

Spawned by /sdlc:task-work post-mortem of T-R4XL-project-local-skill-extension-mechanism on 2026-05-21.

---

← Back to Tasks