ancongui · Nov 6, 2026 · Nov 6, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -5,6 +5,15 @@ All notable changes to devkit. Versions follow CalVer `YY.MM.PATCH` (PATCH resta
 
 ## [Unreleased]
 
+### Added
+
+- A security policy (`SECURITY.md`) with private vulnerability reporting on GitHub, and a contributing guide
+  (`CONTRIBUTING.md`), now that the repository is public.
+
+### Changed
+
+- The release process in Developing devkit uses `dev pr merge`, `dev release`, and a check of the published archive.
+
 ### Fixed
 
 - `dev agents test` reads the hooks log from the byte offset it recorded, so the guard check no longer reports

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,74 @@
+# Contributing to devkit
+
+Thank you for helping. This guide covers how to propose a change, the checks a pull request must pass, and the
+conventions devkit follows. The code layout and the design principles are in
+[Developing devkit](docs/development.md).
+
+## Before you start
+
+- **A bug or an idea:** open an issue. For a bug, say what you expected, what happened, the devkit version
+  (`dev version`), your macOS version, and the agent (Claude Code, Codex, Claude Desktop, or the ChatGPT app).
+- **A security issue:** never in an issue. Follow the [security policy](SECURITY.md).
+- **A larger change** (a new command, a new hook, a change to the guard or the installer): open an issue first, so
+  you and the maintainers agree on the approach before you write the code.
+
+## Work on a clone
+
+devkit is standard-library Python and runs from its folder, so you can change it and run its tests without
+installing it:
+
+```bash
+git clone https://github.com/fireflysoftwaresolutions/devkit.git
+cd devkit
+python3 -m unittest discover -s tests
+/usr/bin/python3 -m unittest discover -s tests   # Python 3.9, the macOS system Python
+bin/dev --help
+```
+
+Installing devkit (`./install.sh`) changes your agents' global settings, hooks, and instructions under `~/.claude`
+and `~/.codex`. Do it only when you want devkit to manage your machine; see [Getting started](docs/getting-started.md).
+
+## Make the change
+
+1. Branch from an up-to-date `main`: `<type>/<topic>`, for example `fix/guard-quoted-paths`. Types are `feat`, `fix`,
+   `docs`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, and `deps`; the topic is lowercase kebab-case, and
+   the whole name is at most 60 characters.
+2. Write the test first, and see it fail for the reason you expect. A test must be able to fail for a real bug:
+   `bin/dev test prove` checks that new tests fail without your change.
+3. Keep the design principles: the standard library only, Python 3.9 compatible, hooks that fail open, and a guard
+   refusal that always names the right way to do the thing.
+4. Update the documentation in the same branch, with a command in [Commands](docs/commands.md), a guard rule in
+   [Guard rules](docs/guard.md), and anything a user notices in the `[Unreleased]` section of the
+   [CHANGELOG](CHANGELOG.md).
+5. To change a crew member, edit `config/crew.json` and run `bin/dev crew sync`. The files in `plugin/agents/` are
+   generated: never edit them by hand.
+
+## Run the checks
+
+Every check must pass before you open the pull request. CI runs the tests on Python 3.9 and 3.13 and a security job.
+
+| Check | Command |
+| --- | --- |
+| The tests, on both Pythons | `python3 -m unittest discover -s tests` and `/usr/bin/python3 -m unittest discover -s tests` |
+| The code compiles | `python3 -m compileall -q lib bin` |
+| No test that cannot fail | `bin/dev test audit tests/` |
+| No unfinished work (stubs, placeholders, TODOs without a task) | `bin/dev stubs` |
+| The documentation | `bin/dev docs check` (markdownlint, lychee, and Vale) |
+| Everything CI runs, locally | `bin/dev ci --run` (the security job needs Docker) |
+
+## Commits and pull requests
+
+- Write commit messages as Conventional Commits: `type(scope): summary`, in the imperative, at most 72 characters,
+  with a body that says why. Make one logical change per commit.
+- Do not add AI attribution, such as `Co-Authored-By` lines for tools or "Generated with" lines.
+- Fill in every section of the pull request template (what and why, changes, how to verify, risk and rollback, and
+  links).
+- Keep one change per pull request, rebased on `main`. A maintainer merges it after CI passes and a review.
+
+## License
+
+devkit is licensed under the [Apache License 2.0](LICENSE). By submitting a contribution, you agree that it is
+licensed under the same terms (section 5 of the license) and that you have the right to submit it.
+
+See also [Developing devkit](docs/development.md), [Commands](docs/commands.md), and the
+[security policy](SECURITY.md).
diff --git a/README.md b/README.md
@@ -222,3 +222,7 @@ devkit is designed and maintained by **Andrés Contreras Guillén** for **Firefl
 
 Copyright © 2026 Firefly Software Solutions Inc. Licensed under the Apache License 2.0; see [LICENSE](LICENSE).
 Third-party skills and tools installed by devkit keep their own licenses; see [NOTICE](NOTICE).
+
+Contributions are welcome: the [contributing guide](CONTRIBUTING.md) explains how to propose a change and the checks
+a pull request must pass. Report a vulnerability privately, as the [security policy](SECURITY.md) describes, never in
+a public issue.
diff --git a/SECURITY.md b/SECURITY.md
@@ -0,0 +1,68 @@
+# Security policy
+
+devkit runs inside developers' agent sessions. Its hooks see every tool call, its guard decides what an agent may
+run, and its installer writes the agents' settings, hooks, and instructions. A vulnerability in devkit can reach every
+machine that installs it, so report it privately, as described here.
+
+## Supported versions
+
+| Version | Supported |
+| --- | --- |
+| The latest release (see [Releases](https://github.com/fireflysoftwaresolutions/devkit/releases)) | Yes |
+| Older releases | No: update with `dev update` |
+
+Fixes ship as a new patch version (CalVer `YY.MM.PATCH`), with notes in the [CHANGELOG](CHANGELOG.md).
+
+## Report a vulnerability
+
+Use GitHub's private vulnerability reporting: open the repository's **Security** tab and choose **Report a
+vulnerability**, or go straight to
+[the new advisory form](https://github.com/fireflysoftwaresolutions/devkit/security/advisories/new). Only you and the
+maintainers see the report.
+
+Do not report a vulnerability in a public issue, pull request, or discussion.
+
+Include what helps the maintainers reproduce it:
+
+- the devkit version (`dev version`) and your macOS version;
+- the agent and the surface, such as Claude Code in the terminal or in Claude Desktop's Code tab, Codex in the
+  terminal or the ChatGPT app, or the Claude Desktop extension;
+- the steps, the impact you see, and a proof of concept if you have one.
+
+Redact secrets before you send logs or transcripts: devkit's logs can contain command lines and file paths.
+
+## What happens next
+
+1. The maintainers confirm in the advisory that they received the report, and keep you updated there.
+2. They reproduce the issue and fix it in the advisory's private fork.
+3. They release the fix as a patch version, publish the advisory, and request a CVE when the issue qualifies.
+4. The advisory credits you, unless you prefer not to be named.
+
+## Scope
+
+In scope:
+
+- the `dev` CLI and everything under `lib/` and `bin/`;
+- the hooks, including the guard: a way to make an agent run what the guard should refuse is a vulnerability;
+- the installer (`install.sh`, `dev setup`, `dev install`) and the settings, hooks, and instructions it writes;
+- the MCP server (`dev mcp`) and the Claude Desktop extension;
+- the dashboard, a generated HTML file: data it shows without escaping is in scope;
+- the CI/CD templates that `dev ci init` writes.
+
+Out of scope:
+
+- third-party skills, plugins, and tools that devkit installs: report those upstream ([NOTICE](NOTICE) lists their
+  sources);
+- issues in the agents themselves (Claude Code, Codex, Claude Desktop, the ChatGPT app): report those to their
+  vendors;
+- attacks that need an already compromised machine or account.
+
+## How this repository is protected
+
+- Secret scanning and push protection are on.
+- CI runs a security job on every pull request: gitleaks, Semgrep, osv-scanner, Trivy, and zizmor.
+- GitHub Actions are pinned by commit SHA and container images by digest, with least-privilege tokens.
+- Dependabot keeps the pinned actions current.
+- devkit bundles no third-party code.
+
+See also [Guard rules](docs/guard.md) and the [contributing guide](CONTRIBUTING.md).
diff --git a/docs/development.md b/docs/development.md
@@ -114,16 +114,14 @@ devkit follows its own delivery method: integrate locally, run the full suite, p
 2. Run the tests on both Pythons (see [Running the tests](#running-the-tests)), `dev docs check` and
    `dev diagram check docs/diagrams`.
 3. Run `dev install` on your machine, then `dev doctor` and `dev agents test`; every check must pass.
-4. Push the release branch once, open one PR, and watch CI (`gh pr checks --watch`).
-5. Merge, tag, and publish:
-
-   ```bash
-   git tag -a vYY.MM.PATCH -m "devkit vYY.MM.PATCH"
-   git push origin vYY.MM.PATCH
-   gh release create vYY.MM.PATCH --title "devkit vYY.MM.PATCH" --notes-file <(sed -n '/^## \[YY.MM.PATCH\]/,/^## \[/p' CHANGELOG.md | sed '$d')
-   ```
-
-6. Developers update with `dev update`.
+4. Run what CI runs (`dev ci --run`), then push the release branch once (`dev push`), open one PR
+   (`dev pr create`), and watch its CI (`dev pr checks --watch`).
+5. Merge with `dev pr merge`, wait for the CI run on `main` (`dev ci status --watch`), and publish with
+   `dev release`. It tags `vYY.MM.PATCH` on `main` and creates the GitHub release with the CHANGELOG section as its
+   notes. The guard refuses a raw `gh pr merge` or `gh release create`.
+6. Verify what was published: download the source archive into an empty folder
+   (`gh release download vYY.MM.PATCH --archive tar.gz -D <folder>`), compare it with the tag, and run its tests.
+7. Developers update with `dev update`.
 
 ## Conventions