1  # BitKnotsRS Project Configuration for AI Agents
 2  
 3  ## Issue Management & Collaboration
 4  This project uses **Radicle** (https://radicle.xyz) for decentralized issue management and code collaboration.
 5  
 6  ### Radicle Setup
 7  - **Protocol**: Peer-to-peer Git collaboration without centralized servers
 8  - **Installation Guide**: https://radicle.xyz/guides/user#installation
 9  - **CLI Tool**: `rad` command for managing repositories, issues, and patches
10  
11  ### Key Radicle Commands
12  - `rad issue list` - List project issues
13  - `rad issue show <id>` - View specific issue details
14  - `rad issue open` - Create new issue
15  - `rad patch list` - List patches/pull requests
16  - `rad patch show <id>` - View patch details
17  - `rad sync` - Synchronize with network peers
18  
19  ### Project Workflow
20  1. Issues are managed through Radicle's decentralized issue tracker
21  2. Code collaboration happens via Radicle patches (equivalent to pull requests)
22  3. No dependency on GitHub/GitLab for issue tracking
23  4. Peer-to-peer collaboration model
24  
25  ### For AI Agents
26  - When discussing issues, refer to Radicle's issue management system
27  - Suggest using `rad` commands for issue-related tasks
28  - Remember this is a decentralized, peer-to-peer development environment
29  - The project values sovereignty and decentralization in development tools
30  
31  ### Issue Workflow for AI Agents
32  1. **Review checklist FIRST** with `just issue-checklist` before creating any issue
33  2. **Check existing issues** with `just issues` to avoid duplicates
34  3. **Search for similar issues** with `just search-issues <keyword>`
35  4. **If similar issue exists**: Comment on existing issue or suggest collaboration
36  5. **If new issue needed**: Draft locally using `.issues/` workspace before creating in Radicle
37  6. **Use templates** from `.issues/templates/` for consistency
38  7. **Create drafts** with `just draft-issue <name>`
39  8. **Create Radicle issues** with `just create-issue "<title>" <draft>`
40  9. **Track progress** with `just issues` and `just issue <id>`
41  10. **Clean up** with `just clean-drafts` after syncing
42  
43  ### Before Creating New Issues - ALWAYS CHECK:
44  - Run `just issues` to see all existing issues
45  - Use `just search-issues <keyword>` to find similar issues by topic
46  - Use `just issues-summary` for a quick overview of all issues
47  - Look for similar functionality, components, or goals
48  - Check if the work could be added to an existing issue as a subtask
49  - Consider if it's better to collaborate on existing work vs. creating new issue
50  
51  ### Development Workflow Commands
52  - `just dev-workflow` - Format, lint, test, and sync with Radicle
53  - `just patch-prep` - Prepare code for patch submission
54  - `just patch-new` - Create new patch from current branch
55  - `just sync` - Sync with Radicle network
56  - `just issues` - List all issues
57  - `just search-issues <keyword>` - Search for issues by keyword
58  - `just issues-summary` - Quick overview of all issues
59  - `just patches` - List all patches
60  
61  ### Issue Collaboration Guidelines
62  - **Always search before creating**: Use search commands to find existing work
63  - **Comment on existing issues**: Add thoughts, suggestions, or offer help
64  - **Break down large issues**: Suggest subtasks or related issues when appropriate
65  - **Reference related issues**: Use issue IDs when creating patches or related work
66  - **Update issue status**: Comment on progress and completion
67  
68  ### Git & Repository Management
69  - `just git-status` - Enhanced git status with ignored files
70  - `just git-clean` - Clean git ignored files
71  - `just clean-drafts` - Clean up temporary issue/patch drafts
72  - `just list-drafts` - Show current drafts in workspace
73  
74  ### File Structure Notes
75  - `.issues/` - Local workspace for drafting (drafts/ and temp/ are git-ignored)
76  - `justfile` - All development commands (50+ commands available)
77  - `.gitignore` - Comprehensive ignore rules for Bitcoin node development
78  - `.gitattributes` - Ensures consistent line endings and file handling
79  
80  ### Current Active Issues
81  - Issue #09a530958b8db3b8899b9531edc4ae4cea041f7b: "Implement P2P Networking and Peer Discovery"
82    - Status: Open, tracking P2P networking implementation
83    - Phases: Network Foundation → Peer Discovery → Connection Management → Protocol Messages → Integration
84  
85  ## Project Context
86  - **Language**: Rust
87  - **Type**: Bitcoin node implementation
88  - **Architecture**: Actor-based with Actix
89  - **Storage**: RocksDB
90  - **Build Tool**: Cargo + Just command runner
91  - **Testing**: Comprehensive unit test suite (18+ tests)