Skip to content

CLAUDE.md

Latest commit

 

History

History
235 lines (175 loc) · 6.6 KB

CLAUDE.md

File metadata and controls

235 lines (175 loc) · 6.6 KB

CLAUDE.md

This file provides guidance to Claude Code when working with this repository.

Critical Rules

These rules override all other instructions:

  1. NEVER commit directly to main - Always create a feature branch and submit a pull request. No exceptions.
  2. Conventional commits - Format: type(scope): description
  3. GitHub Issues for TODOs - Use gh CLI to manage issues, no local TODO files. Use conventional commit format for issue titles
  4. Pull Request titles - Use conventional commit format (same as commits)
  5. Branch naming - Format: type/scope/short-description (e.g., feat/parser/yaml-support)
  6. Working an issue - When working an issue, always create a new branch from an updated main branch
  7. Check branch status before pushing - ALWAYS verify the remote tracking branch still exists before pushing. If a PR was merged/deleted, create a new branch from main instead of trying to push to the old one.
  8. Run validation before commits - Run cargo fmt, cargo clippy, and cargo test before committing and pushing
  9. Cross-platform - All features must work on Windows, macOS, and Linux
  10. No co-authors - Do not add any co-author information on commits or pull requests
  11. No "generated by" statements - Do not add generated-by statements on pull requests

Conventional Commit Types

Type Description
feat New feature
fix Bug fix
docs Documentation only
refactor Code change (no bug fix or feature)
test Adding or updating tests
chore Maintenance tasks
perf Performance improvement
ci CI/CD changes
build Build system or dependencies

Quick Reference

Build Commands

# Build
cargo build

# Build release (optimized for size)
cargo build --release

# Run tests
cargo test

# Run clippy (linting)
cargo clippy

# Format code
cargo fmt

# Run rnr locally
cargo run -- <args>

GitHub Issues

gh issue list                    # List open issues
gh issue view <number>           # View details
gh issue create --title "feat(scope): description" --label mvp --body "..."
gh issue close <number>

GitHub Issue Dependencies (Blocked By / Blocking)

# List what blocks an issue
gh api repos/CodingWithCalvin/rnr.cli/issues/<number>/dependencies/blocked_by --jq '.[] | "#\(.number) \(.title)"'

# List what an issue blocks
gh api repos/CodingWithCalvin/rnr.cli/issues/<number>/dependencies/blocking --jq '.[] | "#\(.number) \(.title)"'

# Add a blocking relationship (issue <number> is blocked by <blocker_id>)
# First get the blocker's numeric ID (not issue number):
gh api repos/CodingWithCalvin/rnr.cli/issues/<blocker_number> --jq '.id'
# Then add the dependency:
gh api repos/CodingWithCalvin/rnr.cli/issues/<number>/dependencies/blocked_by -X POST -F issue_id=<blocker_id>

# Remove a blocking relationship
gh api repos/CodingWithCalvin/rnr.cli/issues/<number>/dependencies/blocked_by/<blocker_id> -X DELETE

Note: The API uses numeric issue IDs (not issue numbers) for POST/DELETE operations. Get the ID with gh api repos/CodingWithCalvin/rnr.cli/issues/<number> --jq '.id'

Project Overview

rnr (pronounced "runner") is a cross-platform task runner designed for zero-setup execution. Clone a repo and tasks just work - no dependency installs, no global tools, no configuration.

Attribute Value
Language Rust
Target Platforms Windows, macOS, Linux
Task File Format YAML (rnr.yaml)

Project Structure

rnr.cli/
├── src/
│   ├── main.rs           # Entry point
│   ├── cli.rs            # CLI argument parsing (clap)
│   ├── config.rs         # rnr.yaml parsing (serde)
│   ├── runner.rs         # Task execution
│   ├── commands/
│   │   ├── mod.rs
│   │   ├── init.rs       # rnr init command
│   │   ├── upgrade.rs    # rnr upgrade command
│   │   └── list.rs       # rnr --list command
│   └── ...
├── Cargo.toml
├── DESIGN.md             # Detailed design document
├── CLAUDE.md             # This file
└── README.md

Architecture

See DESIGN.md for complete design documentation including:

  • Task file schema
  • Built-in commands
  • MVP features
  • Future features

Task File Schema

Tasks are defined in rnr.yaml:

# Shorthand
build: cargo build --release

# Full form
test:
  description: Run all tests
  dir: src/
  env:
    RUST_LOG: debug
  cmd: cargo test

# Sequential steps
ci:
  steps:
    - task: lint
    - task: test
    - task: build

# Parallel execution
build-all:
  steps:
    - parallel:
        - task: build-api
        - task: build-web

Code Style

Rust Conventions

  • Follow Rust idioms
  • Use clippy for linting
  • Use rustfmt for formatting
  • Prefer explicit error handling over .unwrap()

Error Handling

  • Use anyhow for application errors
  • Use thiserror for library errors
  • Provide clear, actionable error messages

Cross-Platform

  • Use std::path::PathBuf for paths, not string concatenation
  • Test on Windows, macOS, and Linux
  • Handle platform-specific shell execution (sh -c vs cmd /c)

CI/CD

Workflows

Workflow Trigger Purpose
build.yml PR, push to main Lint (fmt, clippy), build, test on Windows/macOS/Linux
integration-test.yml PR, push to main E2E tests for task execution and init command
commit-lint.yml PR Validate PR titles follow conventional commits
contributors.yml Push to main Auto-update contributors section in README
preview-changelog.yml PR Preview release notes for PRs
release.yml Manual dispatch Full release: validate, build, create GitHub Release, notify

Release Process

  1. Ensure build workflow passes on main
  2. Go to Actions -> Release -> Run workflow
  3. Enter version number (e.g., 1.0.0)
  4. Workflow validates version, builds all platforms, creates GitHub Release
  5. Publishes binaries and archives for all 5 platforms
  6. Creates GitHub Discussion announcement
  7. Posts to Bluesky and LinkedIn

Release Artifacts

Each release publishes:

  • Raw binaries: rnr-{platform} (for direct download by init command)
  • Archives: rnr-{version}-{platform}.{tar.gz|zip} (for manual installation)

Labels

Label Description Color
mvp MVP feature Green
future Future feature Purple
core Core functionality Blue
cli CLI commands Yellow
build Build and distribution Orange