# rsfulmen - AI Agent Guide
## Read First
1. Check `AGENTS.local.md` if it exists (gitignored)
2. Read `MAINTAINERS.md` for contacts and governance
3. Understand project scope before making changes
## Operating Model
| Mode | Supervised (human reviews before commit) |
| Classification | code-substantive |
| Role Required | Yes |
See [AI Agents Standard](docs/crucible-rs/standards/ai-agents.md) for operating modes and identity scheme.
## Roles
| `devlead` | [devlead.yaml](config/crucible-rs/agentic/roles/devlead.yaml) | Implementation, features, fixes |
| `devrev` | [devrev.yaml](config/crucible-rs/agentic/roles/devrev.yaml) | Code review, four-eyes audit |
| `infoarch` | [infoarch.yaml](config/crucible-rs/agentic/roles/infoarch.yaml) | Documentation, schemas |
| `prodmktg` | [prodmktg.yaml](config/crucible-rs/agentic/roles/prodmktg.yaml) | Messaging, branding, personas |
See [Role Catalog](config/crucible-rs/agentic/roles/README.md) for full definitions.
## Project Overview
**rsfulmen** is the Rust implementation of the Fulmen helper library ecosystem. It provides:
- Configuration path utilities (XDG-compliant)
- Foundry catalogs (country codes, HTTP statuses, exit codes, patterns, MIME types)
- Schema validation utilities
- Cross-platform helpers
Built on patterns established by [gofulmen](https://github.com/fulmenhq/gofulmen), [tsfulmen](https://github.com/fulmenhq/tsfulmen), and [pyfulmen](https://github.com/fulmenhq/pyfulmen).
## Quick Reference
| Bootstrap | `make bootstrap` |
| Quality checks | `make check-all` |
| Tests | `make test` |
| Build | `make build` |
| Format | `make fmt` |
| Lint | `make lint` |
| Sync Crucible | `make sync` |
## Session Protocol
### Before Changes
- Read relevant code first
- Understand the scope
- Keep changes minimal and focused
- Run `make sync` if Crucible assets may have changed
### Before Committing
- Run `make check-all` (runs fmt-check, lint, test)
- Verify all tests pass
- Use proper attribution (see below)
- Include `Committer-of-Record` trailer
## Commit Attribution
Follow [Agentic Attribution Standard](docs/crucible-rs/standards/agentic-attribution.md):
```
<type>(<scope>): <subject>
<body>
Changes:
- <change 1>
- <change 2>
Generated by <Model> via <Interface> under supervision of @<maintainer>
Co-Authored-By: <Model> <noreply@3leaps.net>
Role: <role>
Committer-of-Record: <Name> <email> [@handle]
```
**Example:**
```
feat(foundry): add patterns module with regex support
Implements pattern matching from Crucible catalogs with lazy compilation.
Changes:
- Add patterns.rs with Pattern struct
- Implement regex/glob/literal pattern kinds
- Add lazy compilation with OnceLock
- Add tests for all pattern types
Generated by Claude Opus 4.5 via Claude Code under supervision of @3leapsdave
Co-Authored-By: Claude Opus 4.5 <noreply@3leaps.net>
Role: devlead
Committer-of-Record: Dave Thompson <dave.thompson@3leaps.net> [@3leapsdave]
```
**Key requirements:**
- Use `noreply@3leaps.net` for Co-Authored-By (NOT vendor email)
- Include `Role:` trailer matching your operating role
- Include `Committer-of-Record:` with full name, email, and handle
## DO / DO NOT
### DO
- Run `make check-all` before commits
- Read files before editing
- Keep changes focused
- Follow Rust idioms and best practices
- Use rsfulmen's existing patterns (OnceLock, thiserror, serde)
- Maintain API consistency with gofulmen where appropriate
- Document public APIs with rustdoc comments
### DO NOT
- Push without maintainer approval
- Skip quality gates
- Commit secrets or API keys
- Touch code outside task scope
- Edit synced files in `config/crucible-rs/`, `schemas/crucible-rs/`, `docs/crucible-rs/`
- Break API compatibility without discussion
- **Commit `.plans/` files** — this directory is gitignored; it contains local development notes, briefs, and memos that must never be committed (even with `git add -f`)
## Key Files
| `src/lib.rs` | Library root and version constants |
| `src/config/mod.rs` | XDG config path utilities |
| `src/foundry/mod.rs` | Foundry catalog entry point |
| `config/crucible-rs/` | Synced config from Crucible (SSOT) |
| `schemas/crucible-rs/` | Synced schemas from Crucible |
| `docs/crucible-rs/` | Synced docs from Crucible |
| `.goneat/ssot-consumer.yaml` | Crucible sync configuration |
## Local-Only Directories (Gitignored)
The `.plans/` directory is **gitignored and must never be committed**. It contains:
- Feature briefs and implementation plans
- Memos for upstream (e.g., Crucible fixes)
- Session notes and working documents
These files are for local development coordination only. If you see `.plans/` files in `git status`, do NOT stage them. The `.gitignore` entry `/.plans/` prevents accidental commits unless you force-add with `git add -f` — never do this.
## Synced Assets
Files in these directories are **synced from Crucible SSOT** via `make sync`:
- `config/crucible-rs/`
- `schemas/crucible-rs/`
- `docs/crucible-rs/`
**DO NOT edit these files directly.** If changes are needed:
1. Document proposed changes in `.plans/memos/fulmenhq-crucible/` (local, gitignored)
2. Reset synced files: `git checkout -- config/crucible-rs schemas/crucible-rs docs/crucible-rs`
3. Coordinate with Crucible team for upstream fixes
4. After Crucible updates, run `make sync`
## Standards Reference
- **Online**: https://crucible.3leaps.dev/
- **Full Spec**: https://github.com/fulmenhq/crucible (enterprise-grade)
- **Local synced** (run `make sync` to update):
- [AI Agents Standard](docs/crucible-rs/standards/ai-agents.md)
- [Agentic Attribution Standard](docs/crucible-rs/standards/agentic-attribution.md)
- [Role Catalog](config/crucible-rs/agentic/roles/README.md)