AGENTS.md · git:20260420.cb9e0fb · 2026-04-20 · sha256 a33340fb3d322d7a
AGENTS.md git:20260420.cb9e0fbA
Immutable. This exact content is served forever at /api/v1/blob/a33340fb3d322d7a.
# AGENTS.md - Rulesify Project Guide
> Quick reference for AI agents working on this Rust CLI project.
---
## Tech Stack
### Core
- **Rust** 1.94+ (Edition 2021)
- **Cargo** - Build system and package manager
### Dependencies
| Package | Version | Purpose |
|---------|---------|---------|
| `clap` | 4.5 | CLI argument parsing (derive macros) |
| `tokio` | 1.37 | Async runtime (rt-multi-thread, macros) |
| `reqwest` | 0.12 | HTTP client for GitHub API (json feature) |
| `serde` | 1.0 | Serialization (derive) |
| `serde_yaml` | 0.9 | YAML parsing for SKILL.md frontmatter |
| `serde_json` | 1.0 | JSON for API response cache |
| `toml` | 0.8 | TOML parsing for config and registry |
| `ratatui` | 0.26 | Terminal UI framework |
| `crossterm` | 0.27 | Cross-platform terminal control |
| `chrono` | 0.4 | Date/time with serde support |
| `anyhow` | 1.0 | Application error handling |
| `thiserror` | 1.0 | Custom error types |
| `dirs` | 5.0 | System directory paths |
| `walkdir` | 2.4 | Recursive directory traversal |
| `env_logger` | 0.10 | Logging implementation |
| `log` | 0.4 | Logging facade |
### Dev Dependencies
- `tempfile` 3.8 - Temporary files for tests
---
## Project Structure
```
rulesify/
├── Cargo.toml # Dependencies and metadata
├── registry.toml # Skills catalog (generated by update-registry)
├── src/
│ ├── main.rs # Entry point (tokio runtime, CLI dispatch)
│ ├── lib.rs # Library exports
│ ├── bin/
│ │ └── update-registry.rs # Registry automation binary
│ ├── cli/
│ │ ├── mod.rs # CLI structure (clap Parser/Subcommand)
│ │ ├── init.rs # Main TUI interface (default command)
│ │ └── skill.rs # `rulesify skill list/add/remove/update`
│ ├── models/
│ │ ├── mod.rs # Model exports
│ │ ├── skill.rs # Skill struct (name, description, stars, install_action)
│ │ ├── registry.rs # Registry struct (HashMap of skills)
│ │ ├── skill_metadata.rs # Raw skill data from GitHub
│ │ ├── install_action.rs # Install types (copy/command)
│ │ ├── context.rs # ProjectContext (languages, frameworks, tools)
│ │ ├── config.rs # ProjectConfig (installed skills tracking)
│ │ ├── global_config.rs # GlobalConfig (per-tool global skills tracking)
│ │ └── *_tests.rs # Unit tests
│ ├── registry/
│ │ ├── mod.rs # Registry module exports
│ │ ├── data.rs # Built-in registry loader (include_str!)
│ │ ├── fetch.rs # Remote registry fetcher
│ │ ├── cache.rs # Local cache management
│ │ ├── source.rs # SourceRepo enum (GitHub repos)
│ │ ├── github.rs # GitHub API v3 client
│ │ ├── parser.rs # SKILL.md frontmatter parser
│ │ ├── scorer.rs # Quality scoring (stars-based)
│ │ ├── generator.rs # TOML registry generator
│ │ └── *_tests.rs # Unit tests
│ ├── scanner/
│ │ ├── mod.rs # Scanner orchestration
│ │ ├── language.rs # Language detection (file extensions + configs)
│ │ ├── framework.rs # Framework detection (package files)
│ │ ├── tool_config.rs # AI tool config detection (.cursor, CLAUDE.md)
│ │ └ *_tests.rs # Unit tests
│ ├── tui/
│ │ ├── mod.rs # TUI module exports
│ │ ├── tool_picker.rs # Interactive tool selection (ratatui)
│ │ └ skill_selector.rs # Interactive skill selection (ratatui)
│ ├── installer/
│ │ ├── mod.rs # Installer module exports
│ │ ├── instructions.rs # Install/uninstall instruction generator
│ │ ├── tool_paths.rs # Tool-specific skill path mapping
│ │ └ *_tests.rs # Unit tests
│ └ utils/
│ ├── mod.rs # Utils exports
│ └ error.rs # Error types (RulesifyError enum)
│ └ *_tests.rs # Unit tests
├── .github/
│ └── workflows/
│ └── update-registry.yml # Weekly registry automation
├── .planning/ # GSD project management files
│ ├── STATE.md # Current project state
│ ├── ROADMAP.md # Phase breakdown
│ ├── PROJECT.md # Project description
│ └ REQUIREMENTS.md # Requirements list
│ └ codebase/ # Codebase documentation
│ └ research/ # Research artifacts
├── docs/
│ └ plans/ # Execution plans and summaries
└── target/ # Build output (release/debug)
```
rulesify/
├── Cargo.toml # Dependencies and metadata
├── registry.toml # Built-in skill registry (compiled into binary)
├── src/
│ ├── main.rs # Entry point (tokio runtime, CLI dispatch)
│ ├── lib.rs # Library exports
│ ├── cli/
│ │ ├── mod.rs # CLI structure (clap Parser/Subcommand)
│ │ ├── init.rs # Main TUI interface (default command)
│ │ └── skill.rs # `rulesify skill list/add/remove/update`
│ ├── models/
│ │ ├── mod.rs # Model exports
│ │ ├── skill.rs # Skill struct (name, description, tags, tools)
│ │ ├── registry.rs # Registry struct (HashMap of skills)
│ │ ├── context.rs # ProjectContext (languages, frameworks, tools)
│ │ ├── config.rs # ProjectConfig (installed skills tracking)
│ │ ├── global_config.rs # GlobalConfig (per-tool global skills tracking)
│ │ └── *_tests.rs # Unit tests
│ ├── registry/
│ │ ├── mod.rs # Registry module exports
│ │ ├── data.rs # Built-in registry loader (include_str!)
│ │ ├── fetch.rs # GitHub registry fetcher (async)
│ │ ├── cache.rs # Local cache management
│ │ └ *_tests.rs # Unit tests
│ ├── scanner/
│ │ ├── mod.rs # Scanner orchestration
│ │ ├── language.rs # Language detection (file extensions + configs)
│ │ ├── framework.rs # Framework detection (package files)
│ │ ├── tool_config.rs # AI tool config detection (.cursor, CLAUDE.md)
│ │ └ *_tests.rs # Unit tests
│ ├── tui/
│ │ ├── mod.rs # TUI module exports
│ │ ├── tool_picker.rs # Interactive tool selection (ratatui)
│ │ └ skill_selector.rs # Interactive skill selection (ratatui)
│ ├── installer/
│ │ ├── mod.rs # Installer module exports
│ │ └ instructions.rs # Installation instruction generator
│ └ utils/
│ ├── mod.rs # Utils exports
│ └ error.rs # Error types (RulesifyError enum)
├── .planning/ # GSD project management files
│ ├── STATE.md # Current project state
│ ├── ROADMAP.md # Phase breakdown
│ ├── PROJECT.md # Project description
│ └ REQUIREMENTS.md # Requirements list
│ └ codebase/ # Codebase documentation
│ └ research/ # Research artifacts
├── docs/
│ └ plans/ # Execution plans and summaries
└── target/ # Build output (release/debug)
```
---
## Common Commands
### Build & Run
```bash
# Check compilation (fast)
cargo check
# Build debug version
cargo build
# Build optimized release version
cargo build --release
# Run tests
cargo test
# Run with verbose logging
RUST_LOG=debug cargo run --bin rulesify
# Run release binary
./target/release/rulesify --help
./target/release/rulesify
./target/release/rulesify skill list
```
### Development
```bash
# Format code
cargo fmt
# Lint with clippy
cargo clippy
# Generate documentation
cargo doc --open
# Watch for changes (requires cargo-watch)
cargo watch -x check
```
### Registry Automation
```bash
# Update registry from GitHub repos (requires GITHUB_TOKEN)
GITHUB_TOKEN=your_token cargo run --bin update-registry
# Run with verbose logging
RUST_LOG=debug cargo run --bin update-registry
# The binary fetches skills from:
# - anthropics/skills
# - openai/skills
# - mattpocock/skills
# - MiniMax-AI/skills
# Scores them, filters by threshold (60), and generates registry.toml
```
### CLI Commands
```bash
# Interactive TUI (default, shows global skills with [g] tag)
rulesify
# List installed skills (shows both global and project)
rulesify skill list
rulesify -v skill list # verbose shows source URLs
# Add skill from registry (project level)
rulesify skill add test-driven-development
# Add skill globally (per-tool tracking)
rulesify skill add test-driven-development --global
# Remove installed skill (project level)
rulesify skill remove test-driven-development
# Remove skill from global
rulesify skill remove test-driven-development --global
# Update registry cache and installed skills
rulesify skill update
```
**Note:** Global skills are tracked per-tool in `~/.config/rulesify/.registry.toml`. If a skill is installed globally, installing it project-level will skip with info message.
---
## Supported AI Tools
| Tool | Project Path | Global Path |
|------|---------------|--------------|
| **Claude Code** | `.claude/skills/<name>/SKILL.md` | `~/.claude/skills/<name>/SKILL.md` |
| **Codex** | `.agents/skills/<name>/SKILL.md` | `~/.agents/skills/<name>/SKILL.md` |
| **Cursor** | `.cursor/skills/<name>/SKILL.md` | `~/.cursor/skills/<name>/SKILL.md` |
| **OpenCode** | `.opencode/skills/<name>/SKILL.md` | `~/.config/opencode/skills/<name>/SKILL.md` |
| **Pi** | `.pi/skills/pi-skills/<name>/SKILL.md` | `~/.pi/agent/skills/pi-skills/<name>/SKILL.md` |
**Scope:**
- `--global` flag installs to user's global skill directory
- Default (no flag) installs to project-level directory
---
## Skill Install/Uninstall Flow
1. `rulesify init` → Creates `.rulesify.toml` with selected tools (project-level only)
2. `rulesify skill add <id>` → Installs skill to project, skips if already global
3. `rulesify skill add <id> --global` → Installs skill globally for each tool
4. `rulesify skill remove <id>` → Removes skill from project
5. `rulesify skill remove <id> --global` → Removes skill from global config
6. AI agent executes the instructions (copy/delete files)
**No auto-installation** - rulesify provides paths, AI agent performs file operations.
**Duplication Prevention:**
- Global skills shown with `[g]` tag in init selector
- If skill already global, project-level install skips with info message
---
## Standards
### Code Style
1. **No comments** unless explicitly requested
- Code should be self-documenting through clear naming
- Complex logic may have brief inline comments
2. **Formatting**
- Use `cargo fmt` before committing
- Default Rust style: 4-space indentation, max 100 chars
- Opening braces on same line
3. **Naming Conventions**
- Functions/variables: `snake_case`
- Types/structs/enums: `PascalCase`
- Constants: `SCREAMING_SNAKE_CASE`
- Modules: `snake_case` (directory names match)
### Error Handling
1. **Use `anyhow::Result<T>`** for all fallible operations
2. **Use `.context()`** to add descriptive error messages:
```rust
fs::read_to_string(path)
.with_context(|| format!("Failed to read config: {}", path))?
```
3. **Use `thiserror`** for custom error types (see `src/utils/error.rs`)
4. **Early returns** with `?` operator
### Async Pattern
1. **Tokio runtime** is available but most operations are synchronous
2. **Use `async fn`** for:
- Network operations (registry fetch)
- Operations that may benefit from async in future
3. **Mark main with `#[tokio::main]`**
### Testing
1. **Unit tests** in same module with `_tests.rs` suffix:
```
src/models/skill.rs
src/models/skill_tests.rs
```
2. **Test imports** use `crate::` not `super::`:
```rust
use crate::models::Skill; // Correct
use super::Skill; // Wrong (fails for test modules)
```
3. **Use `tempfile`** for tests needing file operations
4. **Run tests** before claiming work complete
### Module Organization
1. **Each module has `mod.rs`** exposing public types:
```rust
pub mod skill;
pub use skill::Skill;
```
2. **Private implementations** in separate files
3. **Tests** conditionally compiled with `#[cfg(test)]`
### Logging
1. **Use `log` crate** with macros: `debug!`, `info!`, `error!`
2. **Initialize in main**: `env_logger::init()`
3. **Enable with env var**: `RUST_LOG=debug cargo run`
### Git Commits
1. **Atomic commits** - each task commits independently
2. **Conventional commit format**:
```
feat: add feature
fix: fix bug
test: add tests
refactor: code cleanup
docs: documentation
chore: tooling/config
```
3. **Stage files individually** - never `git add .`
4. **Run tests** before committing
### TOML Data Files
1. **Registry** (`registry.toml`):
- Compiled into binary with `include_str!`
- Fallback when network unavailable
2. **Global config** (`~/.config/rulesify/.registry.toml`):
- Per-tool tracking of globally installed skills
- Structure: `{ tool: { skill_id: InstalledSkill } }`
3. **Project config** (`./.rulesify.toml`):
- Installed skills tracking (project-level)
- Selected AI tools
---
## Important Files
| File | Purpose | Edit Frequency |
|------|---------|----------------|
| `Cargo.toml` | Dependencies | Low (add new deps) |
| `registry.toml` | Skill registry | Medium (add skills) |
| `src/cli/mod.rs` | CLI structure | Low (new commands) |
| `src/models/config.rs` | ProjectConfig, InstalledSkill, Scope enum | Medium |
| `src/models/global_config.rs` | GlobalConfig (per-tool global tracking) | Medium |
| `src/installer/tool_paths.rs` | Tool-specific skill paths | Low |
| `src/installer/instructions.rs` | Install/uninstall instruction generators | Medium |
| `src/utils/error.rs` | Error types | Low |
| `.planning/STATE.md` | Project state | High (update per task) |
---
## Before Making Changes
1. **Run `cargo check`** to ensure current state compiles
2. **Understand module dependencies** - check `mod.rs` exports
3. **Check similar code** for patterns to follow
4. **Run tests** after changes: `cargo test`
5. **Format code**: `cargo fmt`
6. **Update STATE.md** if completing a phase/plan
---
## Key Architectural Decisions
1. **Layered modules** - cli → models → utils (no circular deps)
2. **Registry as catalog** - registry.toml contains metadata only (no skill files)
3. **Install actions** - skills have `install_action` (copy vs command types)
4. **Scope support** - skills can be installed at project or global level
5. **Tool-specific paths** - each AI tool has its own skill directory structure
6. **Global tracking per-tool** - global skills tracked separately for each AI tool
7. **Duplication prevention** - installing a global skill project-level skips with info message
8. **Separation of concerns**:
- Scanner: detects context (languages, frameworks, tools)
- Registry: provides skill metadata + install instructions
- TUI: interactive selection (shows [g] for global, [i] for installed)
- Installer: generates instructions (AI executes them)
9. **No auto-installation** - rulesify outputs install command, AI agent executes
10. **Terminal UI** - ratatui for interactive selection (arrow keys, space, enter)
11. **GitHub Actions** - weekly automation updates registry from source repos
### Registry Data Flow
```
GitHub API → fetch_tree → find SKILL.md files
↓
parse frontmatter → extract name, description, tags
↓
score skills → filter by threshold → sort and limit
↓
generate registry.toml → write to file
```
---
## Verification Before Completion
Always run these before claiming work is done:
```bash
cargo check # Must pass
cargo test # Must pass
cargo fmt # Format code
cargo clippy # Optional but recommended
```
---
*Last updated: 2026-04-19*