# Fix Worktree Opsx Skills Not Created

> Diagnose/fix worktrees missing the generated openspec-* (opsx) skills after worktreeInit. Root cause: bare `npx openspec` can resolve a squatted registry stub instead of the real CLI.

- Skill: `blackbelttechnology/fix-worktree-opsx-skills-not-created` (Agent Skill)
- Install (CLI): `npx skillmds@latest add blackbelttechnology/fix-worktree-opsx-skills-not-created`
- Raw SKILL.md: https://api.skillmd.com/api/skills/blackbelttechnology/fix-worktree-opsx-skills-not-created/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: BlackBeltTechnology (https://skillmd.com/u/blackbelttechnology)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/blackbelttechnology/fix-worktree-opsx-skills-not-created

---

## When to Use
Use when a git worktree lacks the OpenSpec lifecycle skills (`.pi/skills/openspec-explore`, `openspec-propose`, and related directories), `/opsx:` commands are missing, `openspec-apply-change` stalls, or `.pi/settings.json#worktreeInit` needs an audit.

## Procedure
1. Confirm the skills are generated, not committed. `.pi/.gitignore` contains `skills/openspec-*/**`; each fresh worktree must run `openspec init`.
2. Confirm the repository declares `@fission-ai/openspec` and identify its package-manager install command. The unscoped npm package `openspec` is a `0.0.0` stub.
3. Require a clean `git status --porcelain=v1`, then install repository dependencies. For this repository, run `pnpm install --frozen-lockfile`.
4. Use the repository-pinned binary when it exists:
   ```bash
   pnpm exec openspec init --tools pi --force
   ```
   `pnpm exec` uses the declared local dependency and fails when the binary is absent. In a repository that does not declare the CLI, use the version-pinned scoped package explicitly: `npx @fission-ai/openspec@1.6.0 init --tools pi --force`.
5. Verify the CLI reports setup success. Check the lifecycle skills this repository requires by name: `openspec-explore`, `openspec-propose`, `openspec-apply-change`, `openspec-update-change`, and `openspec-archive-change`.
6. Check `git status --short`. Generated `openspec-*` skill directories should remain ignored. Review any tracked context-file rewrite before continuing.

## Why the old path fails

Bare `npx openspec init ...` can fetch `openspec@0.0.0` when `node_modules/.bin/openspec` is absent. The stub exits without generating lifecycle skills. Installing dependencies first and using `pnpm exec openspec` preserves the lockfile-selected CLI and fails visibly when setup is incomplete.

## Pitfalls
- Run the dependency install first. `pnpm exec openspec` cannot recover a missing local binary.
- Do not hard-code the number of generated skills or commands. OpenSpec releases generate different sets; validate the required lifecycle names.
- The worktree-init gate `test ! -d .pi/skills/openspec-explore` correctly re-triggers initialization when generated skills are absent.
- `openspec init --force` can rewrite tracked `AGENTS.md` or `CLAUDE.md`. Generated skill directories are safe; tracked context changes require review.

## Verification

```bash
set -euo pipefail
before_status="$(git status --porcelain=v1)"
if [ -n "$before_status" ]; then
  printf '%s\n' "Refusing recovery in a dirty worktree" >&2
  exit 1
fi
pnpm install --frozen-lockfile
pnpm exec openspec --version
pnpm exec openspec init --tools pi --force
for skill in openspec-explore openspec-propose openspec-apply-change openspec-update-change openspec-archive-change; do
  test -d ".pi/skills/$skill" || exit 1
done
after_status="$(git status --porcelain=v1)"
test -z "$after_status"
```

Completion requires setup success, every named directory, and empty Git status before and after recovery.