.cursor

# BitKnotsRS Project Configuration for AI Agents

## Issue Management & Collaboration
This project uses **Radicle** (https://radicle.xyz) for decentralized issue management and code collaboration.

### Radicle Setup
- **Protocol**: Peer-to-peer Git collaboration without centralized servers
- **Installation Guide**: https://radicle.xyz/guides/user#installation
- **CLI Tool**: `rad` command for managing repositories, issues, and patches

### Key Radicle Commands
- `rad issue list` - List project issues
- `rad issue show <id>` - View specific issue details
- `rad issue open` - Create new issue
- `rad patch list` - List patches/pull requests
- `rad patch show <id>` - View patch details
- `rad sync` - Synchronize with network peers

### Project Workflow
1. Issues are managed through Radicle's decentralized issue tracker
2. Code collaboration happens via Radicle patches (equivalent to pull requests)
3. No dependency on GitHub/GitLab for issue tracking
4. Peer-to-peer collaboration model

### For AI Agents
- When discussing issues, refer to Radicle's issue management system
- Suggest using `rad` commands for issue-related tasks
- Remember this is a decentralized, peer-to-peer development environment
- The project values sovereignty and decentralization in development tools

### Issue Workflow for AI Agents
1. **Review checklist FIRST** with `just issue-checklist` before creating any issue
2. **Check existing issues** with `just issues` to avoid duplicates
3. **Search for similar issues** with `just search-issues <keyword>`
4. **If similar issue exists**: Comment on existing issue or suggest collaboration
5. **If new issue needed**: Draft locally using `.issues/` workspace before creating in Radicle
6. **Use templates** from `.issues/templates/` for consistency
7. **Create drafts** with `just draft-issue <name>`
8. **Create Radicle issues** with `just create-issue "<title>" <draft>`
9. **Track progress** with `just issues` and `just issue <id>`
10. **Clean up** with `just clean-drafts` after syncing

### Before Creating New Issues - ALWAYS CHECK:
- Run `just issues` to see all existing issues
- Use `just search-issues <keyword>` to find similar issues by topic
- Use `just issues-summary` for a quick overview of all issues
- Look for similar functionality, components, or goals
- Check if the work could be added to an existing issue as a subtask
- Consider if it's better to collaborate on existing work vs. creating new issue

### Development Workflow Commands
- `just dev-workflow` - Format, lint, test, and sync with Radicle
- `just patch-prep` - Prepare code for patch submission
- `just patch-new` - Create new patch from current branch
- `just sync` - Sync with Radicle network
- `just issues` - List all issues
- `just search-issues <keyword>` - Search for issues by keyword
- `just issues-summary` - Quick overview of all issues
- `just patches` - List all patches

### Issue Collaboration Guidelines
- **Always search before creating**: Use search commands to find existing work
- **Comment on existing issues**: Add thoughts, suggestions, or offer help
- **Break down large issues**: Suggest subtasks or related issues when appropriate
- **Reference related issues**: Use issue IDs when creating patches or related work
- **Update issue status**: Comment on progress and completion

### Git & Repository Management
- `just git-status` - Enhanced git status with ignored files
- `just git-clean` - Clean git ignored files
- `just clean-drafts` - Clean up temporary issue/patch drafts
- `just list-drafts` - Show current drafts in workspace

### File Structure Notes
- `.issues/` - Local workspace for drafting (drafts/ and temp/ are git-ignored)
- `justfile` - All development commands (50+ commands available)
- `.gitignore` - Comprehensive ignore rules for Bitcoin node development
- `.gitattributes` - Ensures consistent line endings and file handling

### Current Active Issues
- Issue #09a530958b8db3b8899b9531edc4ae4cea041f7b: "Implement P2P Networking and Peer Discovery"
  - Status: Open, tracking P2P networking implementation
  - Phases: Network Foundation → Peer Discovery → Connection Management → Protocol Messages → Integration

## Project Context
- **Language**: Rust
- **Type**: Bitcoin node implementation
- **Architecture**: Actor-based with Actix
- **Storage**: RocksDB
- **Build Tool**: Cargo + Just command runner
- **Testing**: Comprehensive unit test suite (18+ tests)