sdlc

Agent skills

Issue tracker

Issues live in GitHub Issues on pumpkit-io/sdlc, managed with the gh CLI. See docs/agents/issue-tracker.md.

Domain docs

Single-context: one root GLOSSARY.md plus ADRs in docs/adr/. See docs/agents/domain.md.

Code comments

Load the code-comments skill before writing or editing any comment.

Worktrees

Never edit files or commit in the main checkout, even for a one-line change. Before your first file change or commit, load the worktrees skill and resolve a worktree for the work, then work and commit there. Release its lock when the work is committed. The one exception is a main-checkout path a skill names, such as improve-codebase-architecture's notes.

Repo rules

Every skill lives in skills/<type>/<name>/, where <type> is commands, auto or reference (the three types below), and ships in the plugin: each one has an entry in .claude-plugin/plugin.json's skills array and in the skill-types table in README.md. Adding, renaming or removing a skill means updating both. A skill you don't want to ship doesn't belong in this repo.

Each skill is one of three types:

• Command (user-invoked): disable-model-invocation: true in the frontmatter, plus policy.allow_implicit_invocation: false in agents/openai.yaml. Only the human can start it.
• Automatic (model-invoked): no invocation flag; the description carries the trigger phrases the agent matches on.
• Reference: user-invocable: false in the frontmatter. Reached only by other skills, hidden from the slash menu.

skills/reference/writing-for-agents/SKILL-MECHANICS.md explains how to choose. Every skill keeps an agents/openai.yaml so the set stays installable in Codex and other Agent Skills harnesses via npx skills add. The installer finds nested skills and flattens them into .agents/skills/<name>/, so the type folders exist only in this repo; a layout with the type folders at the repo root would hide them from it.

Portability: the skills must work in every agent the README's support matrix names. Skills load other skills with "Load the X skill" and never name a vendor tool. Every sub-agent instruction carries an inline fallback for agents that can't spawn one. A skill that can't degrade declares it in a compatibility frontmatter field and its first body line says what to use instead. Changing a skill's type flags, or the hook, means updating the README support matrix. docs/adr/0002-agent-neutral-skills-single-native-package.md records why the Claude Code plugin is the only native package.

Run claude plugin validate . after touching either manifest. Two warnings are expected: no version (on purpose, so installs follow the latest commit) and CLAUDE.md at the plugin root (it is repo context, not plugin context).

hooks/block-dangerous-git.sh is the always-on git and Portless guardrail. hooks/check-commit-slop.sh blocks a git commit whose added comments fail hooks/comment-slop.pl.

Test the hooks with hooks/test-hooks.sh. It pipes each case's payload (tool_input.command or tool_input.file_path, plus cwd) through its hook, expects exit 2 for blocked and 0 for allowed, and builds the scratch repos the commit-slop cases need. When you change a hook, add a case for the change to the table and rerun the script. When you change comment-slop.pl, also pipe a known-clean history through it (git diff -U0 <first commit> HEAD | perl hooks/comment-slop.pl on a repo the skills already cleaned): every finding there is a false positive to fix.

Each skill script has a test script that drives it against scratch repos under $TMPDIR and exits non-zero on any failing case; run it after changing the script. They share helpers in tests/lib.sh.

• skills/auto/worktrees/scripts/worktree.sh: tests/worktrees.sh
• skills/auto/domain-modeling/scripts/next-adr.sh: tests/next-adr.sh
• skills/commands/check-sdlc/scripts/check.sh: tests/check-sdlc.sh
• skills/auto/dev-stack/scripts/dev-stack.template.sh: tests/dev-stack.sh, against fake portless, docker, curl, node, npm and npx, so it touches no real proxy or container.
• The skill layout: tests/skill-layout.sh checks that each skill's folder matches its frontmatter type and that the manifest lists every skill once.

Skills that cannot work without per-repo config point to /setup-sdlc; the others degrade silently. See docs/adr/0001-explicit-setup-pointer-only-for-hard-dependencies.md.

All of this repo's prose follows the prose-style skill: SKILL.md files, docs, README.md, ADRs and code comments.

This repo started as a fork of mattpocock/skills and no longer merges from it. To port an upstream improvement, see "Credits and upstream" in README.md.