Contributing to Hedgehog
Walks a user from "I want to fix/build this in Hedgehog itself" to an open
pull request against skyf0xx/hedgehog. This is for changes to the
discipline — src/agents/, src/skills/, src/templates/,
bin/cli.mjs, README.md — never for changes to the user's own project,
which is a different repo with different rules.
When this runs
- The user names a specific gap (a bug they hit, a roadmap item) and
wants to fix it in Hedgehog rather than work around it locally.
tweaker offered this at the end of a build and the user said yes.
If the user hasn't picked a target yet, browse issues labeled
roadmap
with them and let them choose one — prefer an issue also labeled
good-first-issue for a first contribution, since those are scoped to one
file or one narrow addition.
Before starting
Confirm where the Hedgehog source actually lives on this machine. A project
that ran npx @skyf0xx/hedgehog init has a copy of the payload
(.claude/agents/, .claude/skills/), not the Hedgehog repo itself —
editing those files changes nothing upstream. Ask the user:
- If they already have a local clone of
skyf0xx/hedgehog, use it.
- If not, offer to clone it:
gh repo fork skyf0xx/hedgehog --clone (forks
under their account and clones the fork), or git clone https://github.com/skyf0xx/hedgehog if they'd rather push directly to a
branch on a repo they already have write access to.
Do this in a separate directory from the user's own project — never inside
it.
Writing the issue or PR
Use the pr-writing skill for style: brief, info-dense, Simplified
Technical English, only verified claims. Most of Hedgehog's inbound queue
is read first by inbound-triage, an agent, before a human ever sees it —
the same register inbound-triage uses when it comments back (see that
skill's "Comment style" section) — so write plainly for both readers at
once.
Fill every field the bug-report template asks for as its own labeled fact
(symptom, expected behavior, exact repro steps) rather than one collapsed
paragraph.
Workflow
- Read
CONTRIBUTING.md at the Hedgehog repo root before touching
anything. It defines the rules this repo's content has to follow:
current-state-only files (no changelog narration inside the content
itself), one owning file per rule (nothing load-bearing lives outside
src/agents/ or src/skills/), and PRs scoped to one agent, one skill,
or one template at a time.
- Branch.
git checkout -b <type>/<short-description> off master —
feat/, fix/, or docs/ prefix matching the change, e.g.
feat/windsurf-host or fix/tweaker-job2-wording.
- Make the change, scoped to what
CONTRIBUTING.md and the target
roadmap issue actually call for — resist scope creep onto adjacent
files even if you notice something else worth fixing; that's a separate
PR.
- Verify the install path locally before committing, per
CONTRIBUTING.md:mkdir -p /tmp/hedgehog-smoke && cd /tmp/hedgehog-smoke
node /path/to/hedgehog/bin/cli.mjs init
Confirm .claude/agents/, .claude/skills/, and the root templates
land correctly, and that the specific thing you changed shows up as
expected (a new skill directory copied over, a new host's files in the
right place, a new blueprint reachable from hedgehog-core-design).
- Commit with Conventional Commits, in the format the
conventional-commits skill states. If the change is already one
logical unit, commit it directly. If the working tree has accumulated
several unrelated changes that need splitting into atomic commits, use
the conventional-commits skill rather than hand-rolling the split.
- Push and open the PR, following
pr-writing's checklist and shape
(CI passing, one change, only verified claims):git push -u origin <branch-name>
gh pr create --repo skyf0xx/hedgehog --title "<type>(<scope>): <summary>" --body "..."
The body follows pr-writing's shape (a short Summary, a Test plan
listing what was actually run — for this repo, node bin/cli.mjs init
in a scratch dir, confirming the change lands correctly). If the PR
closes or addresses a roadmap issue, reference it (Fixes #<n>).
- Check CI with
gh pr checks <number> --repo skyf0xx/hedgehog after
opening. Fix a red check before asking for review.
- Report the PR URL
gh returns and stop — don't merge, don't push
further commits without being asked.
1---2name: hedgehog-contributing3description: Use when the user wants to contribute a fix or roadmap item back to the Hedgehog project itself (skyf0xx/hedgehog) rather than their own project. Triggers on "let's fix that in Hedgehog", "I want to contribute", "let's pick up a roadmap item", or when `tweaker` offers this at the end of a build and the user says yes. Covers forking/branching, making the change under Hedgehog's own repo rules, committing with Conventional Commits, and opening the PR.4metadata:5 source: https://skillmd.com/skills/skyf0xx/hedgehog-contributing6---78# Contributing to Hedgehog910Walks a user from "I want to fix/build this in Hedgehog itself" to an open11pull request against `skyf0xx/hedgehog`. This is for changes to the12**discipline** — `src/agents/`, `src/skills/`, `src/templates/`,13`bin/cli.mjs`, `README.md` — never for changes to the user's own project,14which is a different repo with different rules.1516## When this runs1718- The user names a specific gap (a bug they hit, a roadmap item) and19 wants to fix it in Hedgehog rather than work around it locally.20- `tweaker` offered this at the end of a build and the user said yes.2122If the user hasn't picked a target yet, browse issues labeled23[`roadmap`](https://github.com/skyf0xx/hedgehog/issues?q=is%3Aissue+is%3Aopen+label%3Aroadmap)24with them and let them choose one — prefer an issue also labeled25`good-first-issue` for a first contribution, since those are scoped to one26file or one narrow addition.2728## Before starting2930Confirm where the Hedgehog source actually lives on this machine. A project31that ran `npx @skyf0xx/hedgehog init` has a *copy* of the payload32(`.claude/agents/`, `.claude/skills/`), not the Hedgehog repo itself —33editing those files changes nothing upstream. Ask the user:3435- If they already have a local clone of `skyf0xx/hedgehog`, use it.36- If not, offer to clone it: `gh repo fork skyf0xx/hedgehog --clone` (forks37 under their account and clones the fork), or `git clone38 https://github.com/skyf0xx/hedgehog` if they'd rather push directly to a39 branch on a repo they already have write access to.4041Do this in a separate directory from the user's own project — never inside42it.4344## Writing the issue or PR4546Use the `pr-writing` skill for style: brief, info-dense, Simplified47Technical English, only verified claims. Most of Hedgehog's inbound queue48is read first by `inbound-triage`, an agent, before a human ever sees it —49the same register `inbound-triage` uses when it comments back (see that50skill's "Comment style" section) — so write plainly for both readers at51once.5253Fill every field the bug-report template asks for as its own labeled fact54(symptom, expected behavior, exact repro steps) rather than one collapsed55paragraph.5657## Workflow58591. **Read `CONTRIBUTING.md`** at the Hedgehog repo root before touching60 anything. It defines the rules this repo's content has to follow:61 current-state-only files (no changelog narration inside the content62 itself), one owning file per rule (nothing load-bearing lives outside63 `src/agents/` or `src/skills/`), and PRs scoped to one agent, one skill,64 or one template at a time.652. **Branch.** `git checkout -b <type>/<short-description>` off `master` —66 `feat/`, `fix/`, or `docs/` prefix matching the change, e.g.67 `feat/windsurf-host` or `fix/tweaker-job2-wording`.683. **Make the change**, scoped to what `CONTRIBUTING.md` and the target69 roadmap issue actually call for — resist scope creep onto adjacent70 files even if you notice something else worth fixing; that's a separate71 PR.724. **Verify the install path locally** before committing, per73 `CONTRIBUTING.md`:74 ```bash75 mkdir -p /tmp/hedgehog-smoke && cd /tmp/hedgehog-smoke76 node /path/to/hedgehog/bin/cli.mjs init77 ```78 Confirm `.claude/agents/`, `.claude/skills/`, and the root templates79 land correctly, and that the specific thing you changed shows up as80 expected (a new skill directory copied over, a new host's files in the81 right place, a new blueprint reachable from `hedgehog-core-design`).825. **Commit with Conventional Commits**, in the format the83 `conventional-commits` skill states. If the change is already one84 logical unit, commit it directly. If the working tree has accumulated85 several unrelated changes that need splitting into atomic commits, use86 the `conventional-commits` skill rather than hand-rolling the split.876. **Push and open the PR**, following `pr-writing`'s checklist and shape88 (CI passing, one change, only verified claims):89 ```bash90 git push -u origin <branch-name>91 gh pr create --repo skyf0xx/hedgehog --title "<type>(<scope>): <summary>" --body "..."92 ```93 The body follows `pr-writing`'s shape (a short Summary, a Test plan94 listing what was actually run — for this repo, `node bin/cli.mjs init`95 in a scratch dir, confirming the change lands correctly). If the PR96 closes or addresses a roadmap issue, reference it (`Fixes #<n>`).977. **Check CI** with `gh pr checks <number> --repo skyf0xx/hedgehog` after98 opening. Fix a red check before asking for review.998. **Report the PR URL** `gh` returns and stop — don't merge, don't push100 further commits without being asked.