rulesify: Instructions file for Codex

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