setup-patdhlk-skills

name	setup-patdhlk-skills
description	Configure a repo for the patdhlk-skills workflows - reads or scaffolds ubproject.toml, persists the issue backend (github or sphinx-needs) and the role map, sets up a sphinx-needs spec via uv, detects/installs ubc, and offers devcontainer and CI. Use when the user runs /setup-patdhlk-skills or asks to set up patdhlk-skills, configure the issue backend, or scaffold a sphinx-needs spec for agent workflows.
disable-model-invocation	true

Setup patdhlk-skills

Run once per repo. Adapt to what exists — never impose a need-type catalog (ADR_0004): read the user's ubproject.toml and map roles onto their directives. Only add what is missing, and only with consent.

All templates referenced below live in REFERENCE.md.

Workflow

1. Detect existing state

• ubproject.toml at repo root (or spec*/, docs/)? Parse [needs.types] and any existing [tool.patdhlk-skills] (re-run = update, keep prior answers as defaults).
• A Sphinx project using sphinx_needs (a conf.py mentioning it)? Note its source dir — that becomes spec_dir.
• uv available? A pyproject.toml? A git remote GitHub can see (gh repo view)? ubc on PATH? pds on PATH (command -v pds)?

2. Choose the issue backend

Ask the user: github or sphinx-needs (ADR_0003). Recommend github when the repo has a GitHub remote with collaborators/public visibility; recommend sphinx-needs for solo or spec-driven repos. Persist as issue_backend.

3. Ensure the spec exists

Requirements, ADRs, and glossary terms are always sphinx-needs regardless of backend (ADR_0002), so a spec is required either way. If none exists, scaffold per REFERENCE.md §1: root ubproject.toml, spec/conf.py, spec/schemas.json, spec/index.rst + subdirs — and pin the toolchain with uv init (non-package) + uv add sphinx "sphinx-needs>=8,<9" furo sphinx-autobuild, committing uv.lock.

4. Build and persist the role map

For each role — issue, feature, requirement, decision, term, test — propose the best-matching directive from the user's [needs.types] (by directive name, then title, then prefix). Confirm the full map with the user in one question; unmatched roles stay unmapped unless the user names a directive. Persist under [tool.patdhlk-skills.roles] (REFERENCE.md §2).

If issue_backend = "sphinx-needs" and no directive maps to issue: offer to add the issue type plus the status state-machine schema (ADR_0005) and an issues/ doc — templates in REFERENCE.md §3.

5. Configure the builder and the gate CLI

ubc on PATH → persist builder = "ubc". Missing → on Linux offer the install script (REFERENCE.md §4); otherwise persist builder = "sphinx-build" and mention ubc is faster when available (ADR_0006).

pds is the gate-and-query CLI (ADR_0017): pds check is the strict gate, pds build produces a fresh needs.json. It runs whichever builder is configured above. Detect with command -v pds; when missing, OFFER the GitHub Releases installer one-liner with consent (REFERENCE.md §4a), and mention the cargo install pds-cli fallback. The raw sphinx-build / ubc commands remain the no-pds fallback everywhere the gate appears.

6. Optional extras (each opt-in, ask once)

• Devcontainer: copy the sphinx-needs-starter devcontainer (REFERENCE.md §5) — skip if .devcontainer/ exists; offer to merge instead.
• CI: strict-build workflow on push/PR (REFERENCE.md §6).
• Agent block: append ## Agent skills to CLAUDE.md/AGENTS.md (whichever exists; create CLAUDE.md if neither) per REFERENCE.md §7.
• Makefile: html / strict / needs / serve / clean targets (REFERENCE.md §8) — if a Makefile exists, offer to append the targets.
• pds config tables: offer to scaffold [tool.patdhlk-skills.gate] (optional needs_json / sphinx_command / exempt_statuses keys; REFERENCE.md §9) and the [tool.patdhlk-skills.lint] table (shipped; REFERENCE.md §9a) — rules required_sections, nontrivial_body, max_body_length, weasel_words, unenumerated_quantifiers; pds check runs lint automatically when the table is present. Also the forward-looking rubrics / verdicts tables plus the verdict type and role-map entry (REFERENCE.md §10). An absent table simply means that feature is off (ADR_0014) — never add a table the user declines.

7. Validate and report

Run the strict gate: pds check (ADR_0007, ADR_0017) — no pds: uv run sphinx-build -W -b html <spec_dir> <spec_dir>/_build/html. It must pass (exit 0) before reporting success; exit 1 means fix the corpus and re-run, exit 2 means a tool/config error to resolve. Then summarize: backend, role map, builder, whether pds is installed, what was scaffolded vs reused, and the build/query commands now available.

Hard rules

• Never overwrite an existing ubproject.toml section the user authored — edit additively, show diffs for anything touched.
• Never add need types without explicit consent (step 4 is the only place).
• A failed strict gate at step 7 is YOUR bug to fix before finishing.
• Re-running this skill must be safe (idempotent updates, not duplication).