Canonical role-definition toolkit for coding agents
Project description
role-forge
Canonical role-definition toolkit for coding agents.
role-forge keeps one canonical role source and renders it into platform-specific agent formats for tools like Claude Code, OpenCode, Cursor, and Windsurf.
Install
uv tool install role-forge
Quick start
role-forge add PFCCLab/precision-agents -y
role-forge add ./local-roles
role-forge render --target claude
role-forge list
add and update ask before overwriting existing files. Use --yes to skip confirmations.
Project installs are the default. Use role-forge add -g, role-forge list -g, and
role-forge remove -g for the user scope in ~/.agents/roles. Rendering merges both
scopes and lets project roles override same-id user roles.
Why this repo exists
- avoid maintaining the same role prompt in multiple tool-specific formats
- keep capabilities, delegation policy, and model tiers in one canonical source
- validate hierarchy and output layout before rendering
- support extension through adapter entry points
Capability model
Canonical roles declare abstract capabilities such as basic, read, write, web-access, delegate, bash, safe-bash, and all. role-forge expands those once into a shared intermediate capability model, then each adapter renders the matching tools and permissions for its target. If a role omits capabilities entirely, basic is applied by default.
Documentation
- live site:
https://role-forge.sixbones.dev - docs home:
docs/index.md - canonical role format:
docs/reference/canonical-role-definition.md - CLI reference:
docs/reference/cli.md - configuration:
docs/reference/configuration.md - adapters:
docs/reference/adapters.md - architecture:
docs/architecture/system-overview.md - development:
docs/development/contributing.md - deployment:
docs/development/deployment.md
Documentation site
This repo now includes a Zensical doc set inspired by the structure used in volvox.
uv add --dev zensical
zensical serve
License
MIT
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file role_forge-0.1.0.tar.gz.
File metadata
- Download URL: role_forge-0.1.0.tar.gz
- Upload date:
- Size: 286.6 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: uv/0.10.9 {"installer":{"name":"uv","version":"0.10.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
7dfa23c2dafb365e166fcf5cbea04adbe8b6736e4287f01015f67385016c912e
|
|
| MD5 |
8126b768dd80d8c7cba6da4a36e3622d
|
|
| BLAKE2b-256 |
7530f8c789ac7f7c8b7759feb0bcc9e2cd77a9e58463303d6b7c0fa282b10dda
|
File details
Details for the file role_forge-0.1.0-py3-none-any.whl.
File metadata
- Download URL: role_forge-0.1.0-py3-none-any.whl
- Upload date:
- Size: 27.9 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: uv/0.10.9 {"installer":{"name":"uv","version":"0.10.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
02bf295c54d40b2e41c470f303cc8fc17292883d6902b74754ce0b210f5d061a
|
|
| MD5 |
c34240f712c6d2c1bbbf154af6a91efb
|
|
| BLAKE2b-256 |
f6158fcc55be7dceaa22220c148f1fd30c3c834d0c623f799cf0882e4eaffe91
|
