The AI resources PeopleForBikes uses across its projects: agent skills for a specification-driven workflow, shared Claude Code permission rules, and a sandbox profile to run AI agents safely. They are written for PeopleForBikes contributors and shared with anyone who finds them useful.
| Resource | What it is | Where |
|---|---|---|
| Agent skills | The pfb-sdld Claude Code plugin: specification-driven workflow |
plugins/ |
| Claude Code settings | Shared permission rules, merged into each project's settings file | claude/settings/ |
| nono profiles | Sandbox profile used to run AI agents across our projects | nono/profiles/ |
Everything is released under the MIT license.
Each resource can be used on its own.
Agent skills. Inside Claude Code:
/plugin marketplace add PeopleForBikes/ai-toolkit
/plugin install pfb-sdld@pfb-pluginsThen try /pfb-spec-new add a --version flag to the CLI.
Claude Code settings. From a clone of this repository, merge the shared rules into a project and commit the result:
just sync-claude-settings path/to/project
just check-claude-settings path/to/projectThis also registers the pfb-plugins marketplace and enables pfb-sdld for the
project, so everyone who opens it is offered the skills.
nono profiles. From a clone of this repository:
nono pull nolabs-ai/claude
just install-nono-profiles
nono run --profile pfb-claude claudeReview SECURITY.md for what the profile grants before installing, and create the agent's GitHub token first.
pfb-sdld packages our Specification-Driven LLM Development (SDLD) workflow.
| Skill | Purpose |
|---|---|
pfb-spike |
Research a possible feature with real experiments; records evidence and a Go / No-Go verdict in spike.md |
pfb-spec-new |
Interview-style conversation resulting in requirements.md, design.md, tasks.md |
pfb-spec-implement |
Execute tasks.md in order, ticking tasks, running the project's checks, recording findings.md |
pfb-spec-review |
Strict review of an implementation against its spec (report only) |
pfb-spec-update |
Sync a spec with what was built, or yank a cancelled feature or No-Go spike |
pfb-learning |
Capture a lesson in specs/learnings/, or review an approved feature's findings.md before merging |
Examples:
/pfb-spike is downloading OSM data per city faster than clipping the region?
/pfb-spec-new add a --version flag to the CLI
/pfb-spec-implement specs/0006-version-flag
/pfb-spec-review specs/0006-version-flag
/pfb-spec-update specs/0006-version-flag yank superseded by #1234
/pfb-learning specs/0006-version-flag
/pfb-learning the SRID mismatch we just fixed in the stress SQLThe fully qualified names (/pfb-sdld:pfb-spec-new, …) also work and are what
/help lists.
pfb-spec-implement only runs when invoked explicitly. The other skills can
also be picked up automatically when a request matches their description.
pfb-spec-review always runs in a fresh context (context: fork with
agent: general-purpose in its frontmatter): Claude Code starts a separate
subagent that sees none of the current conversation, only the repository, the
spec and the arguments. This keeps the reviewer from inheriting the reasoning of
the session that wrote the code. Because the subagent cannot ask questions
mid-review, pass the spec folder explicitly
(/pfb-spec-review specs/NNNN-feature-name); if it is missing and cannot be
inferred from the branch, the review stops and lists the candidates. The report
comes back to the main session when the subagent finishes. Other agents, such as
Copilot, may ignore these frontmatter fields and run the review inline; start a
new session before reviewing there.
- In a workspace, a feature that belongs to one member lives in
<member>/specs/. Work spanning several members, and repositories that are not workspaces, use the rootspecs/. Existing folders stay where they are. Searches cover the current member and the root, and other members only when the work touches them. - Feature specs live in
specs/NNNN-feature-name/(four digits, sequential within thatspecs/folder, so always use the full path), each withrequirements.md,design.mdandtasks.md. A folder may also hold:spike.md: the research done before specifying the feature (pfb-spike), ending in a Go, Conditional Go or No-Go verdict;findings.md: everything non-obvious learned while implementing it (pfb-spec-implement), reviewed by a teammate at the end.
- Every spike is numbered like a feature. A Go spike's folder becomes the
feature's folder;
pfb-spec-newadds the three documents next tospike.md. - Requirements use user stories with EARS acceptance criteria.
- Cancelled features are renamed to
specs/NNNN-feature-name-yanked/and gain ayanked.mdexplaining why. Their number stays reserved. A No-Go spike is yanked the same way and keeps onlyspike.mdandyanked.md, so teammates know why the team stopped and do not repeat the investigation. - Learnings live in
specs/learnings/<category>/<slug>.md: in the member when they concern only that member, at the root otherwise. specs/README.mdis never modified by the skills, at any level.docs/is reserved for the published documentation website. No skill writes planning material there.- Each repository's
CLAUDE.md/AGENTS.mddocuments its stack and its quality command (e.g.just ci), which the skills read instead of assuming. - Repo templates in the root
specs/xxxx-feature-templates/override the ones bundled withpfb-spec-new.
flowchart TD
idea(["Feature idea"])
sure{"Clear what to build<br/>and that it is worth it?"}
spike["/pfb-spike<br/>experiments → spike.md"]
verdict{"Reviewer feedback<br/>on the verdict"}
new["/pfb-spec-new<br/>requirements.md → design.md → tasks.md"]
senior{"Senior engineer<br/>reviews the specs"}
implement["/pfb-spec-implement<br/>execute tasks.md, record findings.md"]
review{"/pfb-spec-review<br/>report against the spec"}
update["/pfb-spec-update<br/>sync design.md and tasks.md"]
yank["/pfb-spec-update yank<br/>NNNN-name-yanked/ + yanked.md"]
learning["/pfb-learning specs/NNNN-name<br/>review findings.md → specs/learnings/"]
final{"Reviewer feedback<br/>on code and findings.md"}
done(["Merge"])
idea --> sure
sure -- yes --> new
sure -- no --> spike
spike --> verdict
verdict -- Go / Conditional Go --> new
verdict -- No-Go --> yank
new --> senior
senior -- changes requested --> new
senior -- approved --> implement
senior -- feature cancelled --> yank
implement --> review
review -- needs revision --> implement
review -- spec diverged --> update
update --> review
review -- pass --> final
final -- changes requested --> implement
final -- approved --> learning
learning --> done
The last step before merging is /pfb-learning on the feature's spec folder. It
goes through findings.md, proposes which entries matter beyond this feature,
and writes the ones you select, so the learnings ship in the same pull request.
Selecting none is a normal outcome. This step is not automated: Claude Code has
no hook event for a feature being accepted, so the feature's author runs it.
/pfb-learning also works at any other time, without a spec folder, to capture
one lesson from the current session.
- Make sure the project has a
specs/folder. Addingspecs/xxxx-feature-templates/is optional: the templates bundled withpfb-spec-neware used otherwise. - Make sure the project's
CLAUDE.md/AGENTS.mdnames its quality command (e.g.just ci,cargo test,npm test) and states thatdocs/is the published documentation website and must not receive planning material. - Optionally mention
specs/learnings/inCLAUDE.md/AGENTS.mdup front; otherwisepfb-learningoffers to add the line the first time it runs. - If agents run in the nono profile, add two lines to
CLAUDE.md/AGENTS.md:- read CI logs with
gh run view(--log,--log-failed,--job <id> --log), not withgh api …/actions/jobs/<id>/logs, which redirects to a storage host the profile blocks; - when
ghreports it is not logged in, GitHub answers401 Bad credentials, or nono's proxy answers503withcredential_unavailable, stop and ask the contributor to set up the agent's GitHub token instead of looking for another way to authenticate.
- read CI logs with
claude plugin marketplace update pfb-plugins
claude plugin update pfb-sdld@pfb-pluginsclaude plugin uninstall pfb-sdld@pfb-plugins
claude plugin marketplace remove pfb-pluginsCopilot CLI reads Claude-compatible plugin manifests. This has not been tested with these skills yet; please report how it goes.
copilot plugin marketplace add PeopleForBikes/ai-toolkit
copilot plugin install pfb-sdld@pfb-pluginsClaude Code plugins cannot carry permission rules, and without an organization
plan there are no managed settings to push them. Shared rules therefore live in
each project's committed .claude/settings.json, which applies to everyone who
opens the project. claude/settings/base.json holds the rules every
PeopleForBikes project starts from:
- allow: read-only
gitandghcommands, andnono why; - ask: anything that changes a repository or GitHub (
git commit,git push,gh pr create, …); - deny: reading
.envfiles andsecrets/,curl,wget,sudo.
It also registers this repository as the pfb-plugins marketplace and enables
pfb-sdld, so Claude Code offers to install the skills when a contributor
trusts the project.
A deny rule in a project's committed settings applies even if a contributor allows the same thing in their personal settings; allow rules only save prompts.
Merge the base into a project with:
just sync-claude-settings path/to/projectThe merge only adds: project-specific rules (e.g. Bash(uv run pytest*) or
Bash(cargo test*)) and other settings are kept. Lists are combined, objects
merged, and the project's value wins for anything else. Running it again is
harmless. To keep projects in line, run the check in each project's CI; it exits
with status 1 and lists what is missing:
just check-claude-settings path/to/projectPersonal preferences (model, theme, telemetry, …) belong in each contributor's
own ~/.claude/settings.json or the project's .claude/settings.local.json,
not in the base.
nono runs AI agents in an OS-enforced sandbox.
nono/profiles/pfb-claude.json is a single profile meant for all our projects
rather than one per project: most of them need the same access (Overpass and
Geofabrik downloads, services on port 3000, PostgreSQL on port 5432), and
per-project profiles would add overhead for little security gain.
It extends the nolabs-ai/claude pack and adds a reviewed list of hosts
(package registries, GitHub, documentation, OpenStreetMap), the tools installed
by mise, and a GitHub token dedicated to the agent, which nono's proxy adds to
the agent's requests without the agent ever seeing it. It also keeps the
developer's own GitHub tokens out of the sandbox, refuses pushes over HTTPS, and
blocks Git hooks and VS Code's configuration. Review SECURITY.md
for what it grants, and the gaps it leaves, before installing.
Install and use it:
nono pull nolabs-ai/claude
just install-nono-profiles
nono run --profile pfb-claude claudejust install-nono-profiles copies the profiles into
$XDG_CONFIG_HOME/nono/profiles/ (~/.config/nono/profiles/ by default). It
refuses to overwrite a local copy that differs and shows the difference; run
just install-nono-profiles force to overwrite it. Inspect the fully resolved
policy with nono profile show pfb-claude.
The agent uses its own GitHub token, never yours. nono reads it from your login
keychain, outside the sandbox, and adds it only to the GitHub API requests the
profile allows: reading, GraphQL, and creating issues, pull requests, comments
and reviews. Inside the sandbox, GITHUB_TOKEN holds a placeholder.
-
Create a classic personal access token (GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic)) with only the
public_repoandread:orgscopes, and an expiry (90 days is a good default). -
Store it in the keychain; the command prompts for the token, so it stays out of your shell history:
security add-generic-password -s nono -a github_agent -w -
Install the profile (
just install-nono-profiles forcewhen updating) and restart running sessions.
To rotate the token, store the new one with
security add-generic-password -U -s nono -a github_agent -w and start a new
session.
Without the token, sessions still start, but gh is not logged in inside the
sandbox: GitHub commands fail until the token exists. The line recommended in
Adopting the skills in a project makes the
agent stop and ask you when that happens.
ai-toolkit/
├── .claude-plugin/marketplace.json # marketplace "pfb-plugins"
├── .github/workflows/ci.yaml # runs `just ci`
├── plugins/pfb-sdld/
│ ├── .claude-plugin/plugin.json
│ └── skills/
│ ├── pfb-spike/ # SKILL.md + assets/spike-template.md
│ ├── pfb-spec-new/ # SKILL.md + assets/ (spec templates)
│ ├── pfb-spec-implement/ # SKILL.md + assets/findings-template.md
│ ├── pfb-spec-review/
│ ├── pfb-spec-update/
│ └── pfb-learning/ # SKILL.md + assets/learning-template.md
├── claude/settings/base.json # shared permission rules + marketplace
├── nono/profiles/pfb-claude.json # organization-wide sandbox profile
├── scripts/ # settings merge, profile install, tests
├── justfile
├── CLAUDE.md (AGENTS.md) # instructions for AI agents
├── CONTRIBUTING.md · SECURITY.md · code-of-conduct.md · LICENSE
Each skill is a SKILL.md file: YAML frontmatter (name, description,
argument-hint) followed by the instructions the agent follows. The
description decides when the agent picks the skill on its own, so keep it
specific.
See CONTRIBUTING.md for the requirements, how to try changes
locally and how to validate them (just ci).
For maintainers:
-
Merge the changes through pull requests and make sure CI passes.
-
Bump
versioninplugins/pfb-sdld/.claude-plugin/plugin.jsonand keepmetadata.versionin.claude-plugin/marketplace.jsonconsistent. Installed copies only pick up changes when the version changes. -
In CHANGELOG.md, move the
Unreleasedentries under a new heading for the version and date, and update the comparison links. -
Tag the release.
claude plugin tagchecks thatplugin.jsonand the marketplace entry agree, then creates and pushes apfb-sdld--v<version>tag:claude plugin tag ./plugins/pfb-sdld --push
Users then update with:
claude plugin marketplace update pfb-plugins
claude plugin update pfb-sdld@pfb-plugins
just install-nono-profiles forceProjects pick up new shared permission rules the next time
just sync-claude-settings runs; their CI check flags when that is due.