rulesify

Imported from ydeng11/rulesify (AGENTS.md). Install upstream with npx skills add ydeng11/rulesify. Copyright stays with the author.

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

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

# 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

# Update registry from GitHub repos (requires GH_TOKEN)
GH_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

# 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

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:

   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:::

   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:

   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

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:

cargo check    # Must pass
cargo test     # Must pass
cargo fmt      # Format code
cargo clippy   # Optional but recommended

Last updated: 2026-04-19