Skip to content

Repository files navigation

PeopleForBikes AI Toolkit

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.

Quick start

Each resource can be used on its own.

Agent skills. Inside Claude Code:

/plugin marketplace add PeopleForBikes/ai-toolkit
/plugin install pfb-sdld@pfb-plugins

Then 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/project

This 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 claude

Review SECURITY.md for what the profile grants before installing, and create the agent's GitHub token first.

Agent skills: the pfb-sdld plugin

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 SQL

The 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.

Conventions the skills rely on

  • 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 root specs/. 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 that specs/ folder, so always use the full path), each with requirements.md, design.md and tasks.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-new adds the three documents next to spike.md.
  • Requirements use user stories with EARS acceptance criteria.
  • Cancelled features are renamed to specs/NNNN-feature-name-yanked/ and gain a yanked.md explaining why. Their number stays reserved. A No-Go spike is yanked the same way and keeps only spike.md and yanked.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.md is 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.md documents 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 with pfb-spec-new.

Typical flow

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
Loading

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.

Adopting the skills in a project

  • Make sure the project has a specs/ folder. Adding specs/xxxx-feature-templates/ is optional: the templates bundled with pfb-spec-new are used otherwise.
  • Make sure the project's CLAUDE.md / AGENTS.md names its quality command (e.g. just ci, cargo test, npm test) and states that docs/ is the published documentation website and must not receive planning material.
  • Optionally mention specs/learnings/ in CLAUDE.md / AGENTS.md up front; otherwise pfb-learning offers 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 with gh api …/actions/jobs/<id>/logs, which redirects to a storage host the profile blocks;
    • when gh reports it is not logged in, GitHub answers 401 Bad credentials, or nono's proxy answers 503 with credential_unavailable, stop and ask the contributor to set up the agent's GitHub token instead of looking for another way to authenticate.

Updating and removing the plugin

claude plugin marketplace update pfb-plugins
claude plugin update pfb-sdld@pfb-plugins
claude plugin uninstall pfb-sdld@pfb-plugins
claude plugin marketplace remove pfb-plugins

GitHub Copilot CLI

Copilot 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-plugins

Claude Code settings

Claude 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 git and gh commands, and nono why;
  • ask: anything that changes a repository or GitHub (git commit, git push, gh pr create, …);
  • deny: reading .env files and secrets/, 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/project

The 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/project

Personal 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 profiles

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 claude

just 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's GitHub token

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.

  1. Create a classic personal access token (GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic)) with only the public_repo and read:org scopes, and an expiry (90 days is a good default).

  2. 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
  3. Install the profile (just install-nono-profiles force when 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.

Layout

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.

Contributing

See CONTRIBUTING.md for the requirements, how to try changes locally and how to validate them (just ci).

Releasing

For maintainers:

  1. Merge the changes through pull requests and make sure CI passes.

  2. Bump version in plugins/pfb-sdld/.claude-plugin/plugin.json and keep metadata.version in .claude-plugin/marketplace.json consistent. Installed copies only pick up changes when the version changes.

  3. In CHANGELOG.md, move the Unreleased entries under a new heading for the version and date, and update the comparison links.

  4. Tag the release. claude plugin tag checks that plugin.json and the marketplace entry agree, then creates and pushes a pfb-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 force

Projects pick up new shared permission rules the next time just sync-claude-settings runs; their CI check flags when that is due.

Releases

Packages

Contributors

Languages