Kiro Project development Workflow

gistfile1.txt

I'm creating a protocol for the organized creation of specifications.

In Cursor, I used a protocol called RIPER5; it was a set of rules, it worked well, but it consumed many tokens, thousands just to upload the rules. This time I'm adjusting it to be a step-by-step process, distilling the specifications and abstractions from Steering -> Spec -> Tasks (-a, -b...).

Steering:

Creating the Steering using a PRD or Briefing and then answering a series of questions to reduce ambiguity, such as which technologies are used, UI/UX details, or decisions the user needs to make or not make.

architecture.md
code-standards.md
project-overview.md
roadmap.md
security.md
testing.md

The quantity and types of files depend on the project, but these are the most common; they need to have objective decisions without many code examples.

A Roadmap file with the steps listed in stages is important:

## Stage 0: Foundation

Base infrastructure for the project.

| Task | Complexity | Tests | Dependencies |
|------|------------|-------|--------------|
| 0.1 Monorepo Setup | Simple | No | None |
| 0.2 CI/CD Configuration | Simple | No | 0.1 |
| 0.3 Base Crate Structure | Simple | No | 0.1 |
| 0.4 SQLite + SQLCipher | Medium | Yes (Unit/Integration) | 0.3 |
| 0.5 Configuration System | Simple | Yes (Unit) | 0.3 |
| 0.6 Logging and Error Handling | Simple | Yes (Unit) | 0.3 |


### Task Details

- **0.1 Monorepo Setup**: Configure Cargo workspace, define workspace-level dependencies
- **0.2 CI/CD Configuration**: GitHub Actions for lint, tests, builds, and automated releases
- **0.3 Base Crate Structure**: Create wakeru-core and wakeru-storage crates
- **0.4 SQLite + SQLCipher**: Encrypted database using rusqlite + bundled SQLCipher
- **0.5 Configuration System**: TOML-based user settings (paths, limits, preferences)
- **0.6 Logging and Error Handling**: tracing + tracing-appender, thiserror for errors

---

This way I can create each spec according to what's already in the Roadmap, and each spec goes through another series of questions. Simple doubts or ambiguities can change the course of the project, and there goes another 1k of credits.

I first create the requirements.md and design.md files using Kiro's SPECS, and then the tasks.md file according to some criteria:

| Task | Complexity | Doc/Context7? | Perplexity? | Tests? | Risks/Blockers | Dependencies |

The file needs to have a maximum of 5 task groups, and a maximum of two tasks with medium complexity. If there are more or one complex task, divide the tasks into more groups.

## Task Analysis Table

| Task | Complexity | Doc/Context7? | Perplexity? | Tests? | Risks/Blockers | Dependencies |
|------|------------|---------------|-------------|--------|----------------|--------------|
| **Group 1: TorrentManager Core** |
| 1.0 Validate librqbit Session/Api patterns | Trivial | ✅ | ⚠️ | ❌ | API signature variations | Stage 3 |
| 1.1 Extend TorrentManager with RwLock wrappers | Medium | ✅ | ⚠️ | ✅ | Concurrency complexity | 1.0 |
| 1.2 Implement torrent lifecycle methods | Medium | ✅ | ⚠️ | ✅ | State persistence timing | 1.1 |
| 1.3 Implement priority and stats methods | Simple | ✅ | ⚠️ | ✅ | Priority not native | 1.2 |
| 1.4 Commit | - | - | - | - | - | 1.3 |
| 1.5 Overview | - | - | - | - | - | 1.4 |
| **Group 2: EventEmitter & TorrentHandle** |
| 2.1 Implement EventEmitter and TorrentEvent | Simple | ✅ | ⚠️ | ✅ | Channel capacity | 1.3 |
| 2.2 Integrate EventEmitter with TorrentManager | Simple | ✅ | ⚠️ | ✅ | None | 2.1 |
| 2.3 Extend TorrentHandle with category/tags | Simple | ✅ | ⚠️ | ✅ | None | 2.2 |
| 2.4 Commit | - | - | - | - | - | 2.3 |
| 2.5 Overview | - | - | - | - | - | 2.4 |
| **Group 3: StatePersister** |
| 3.0 Validate SQLCipher persistence patterns | Trivial | ✅ | ⚠️ | ❌ | PRAGMA key timing | 2.3 |
| 3.1 Create SQLite schema and migrations | Medium | ✅ | ⚠️ | ✅ | Migration compatibility | 3.0 | | 3.2 Implement StatePersister save/load | Medium | ✅ | ⚠️ | ✅ | bitvec serialization | 3.1 |
| 3.3 Implement auto-save background task | Simple | ✅ | ⚠️ | ✅ | Task lifecycle | 3.2 |
| 3.4 Commit | - | - | - | - | - | 3.3 |
| 3.5 Overview | - | - | - | - | - | 3.4 |

In the end, there are some files: tasks-a.md, tasks-b.md...

The task format also has a flow.

## Workflow

``` ANALYZE → IMPLEMENT → TEST? → COMMIT → OVERVIEW
```

Each task follows this workflow as defined in `task-execution-guidelines.md`:

1. **ANALYZE**: Understand requirements, plan approach, determine test needs
2. **IMPLEMENT**: Execute the task following project standards
3. **TEST**: Run and validate tests (if required)
4. **COMMIT**: Create commit with spec reference
5. **OVERVIEW**: Document what was accomplished

and finally, each task may or may not search for documentation information on the web, context7 or via perplecity

- [x] 1. TorrentManager Core 
- **Complexity:** Medium | **Doc/Context7:** Yes | **Perplexity:** Maybe | **Tests:** Yes | **Risks/Blockers:** Concurrency, API variations | **Commit:** Yes

- _Requirements: 7.1, 7.2, 12.1-12.6, 13.1-13.4_ 
- _References: #[[file:.kiro/steering/architecture.md]], #[[file:.kiro/steering/code-standards.md]]_ 

- [x] 1.0 Validate librqbit Session/Api patterns 
- **Spec Analysis**: Read `requirements.md` (Req 7, 12, 13) and `design.md` (TorrentManager Architecture, librqbit API Corrections) 
- **Docs**: Consult https://docs.rs/librqbit/latest/librqbit/ 
- **Validation**: Use Context7 `/websites/rs-librqbit` for Session, Api, and ManagedTorrent patterns 
- Verify Api::new() signature (2 vs 3 params based on `tracing-subscriber-utils` feature) 
- Verify TorrentStats fields: `progress_bytes`, `uploaded_bytes`, `file_progress: Vec<u64>` 
- Verify speed types are `f64` MiB/s (not `u64` bytes/s) 
- Verify Session lifecycle: `pause()`, `unpause()`, `delete()` 
- **If in doubt**: Use Perplexity quick search for librqbit v9 API patterns 
- _Complexity: Trivial | Doc/Context7: Yes | Perplexity: Maybe | Tests: No | Risks/Blockers: API understanding | Commit: No (**Validation**)_ 

- [x] 1.1 Extend TorrentManager with RwLock wrappers 
- **Spec Analysis**: Read `requirements.md` (Req 30.6, 30.7, 30.11) and `design.md` (TorrentManager struct with RwLock wrappers, uTP Protocol Management) 
- **Docs**: Consult https://docs.rs/tokio/latest/tokio/sync/struct.RwLock.html 
- **Validation**: Use Context7 `/websites/rs_tokio_tokio` for RwLock patterns 
- Wrap `session` and `api` fields with `Arc<RwLock<Arc<librqbit::Session/Api>>>` 
- Wrap `config` with `Arc<RwLock<TorrentConfig>>` for runtime updates 
-Add `utp_monitor: Arc<UtpMonitor>` field (stub for now) 
- Update all existing methods to use `.read().await` / `.write().await` 
- **If in doubt**: Use Perplexity quick search for tokio RwLock best practices 
- _Complexity: Medium | Doc/Context7: Yes | Perplexity: Maybe | Tests: Yes (Unit) | Risks/Blockers: Competition | Commit: No_ 
- _Requirements: 30.6, 30.7, 30.11_ 
- _Design: Property 9 (Connection Limits), TorrentManager Architecture_ 

- [x] 1.2 Implement torrent lifecycle methods 
- **Spec Analysis**: Read `requirements.md` (Req 12.1-12.3) and `design.md` (TorrentManager Complete Core Interface, TorrentState Model) 
- **Docs**: Consult https://docs.rs/librqbit/latest/librqbit/ 
- **Validation**: Use Context7 `/websites/rs-librqbit` for pause/unpause/delete patterns 
- Implement `remove_torrent(info_hash, delete_files)` - calls `session.delete()`, optionally removes files 
- Implement `pause_torrent(info_hash)` - calls `session.pause()`, save state immediately 
- Implement `resume_torrent(info_hash)` - calls `session.unpause()`, restores connections 
- Handle errors with `TorrentError::NotFound`, `TorrentError::InvalidState` 
- **If in doubt**: Use Perplexity quick search for librqbit torrent lifecycle 
- _Complexity: Medium | Doc/Context7: Yes | Perplexity: Maybe | Tests: Yes (Unit + Integration) | Risks/Blockers: State timing | Commit: No_ 
- _Requirements: 12.1, 12.2, 12.3_ 
- _Design: Property 16 (Torrent Completion Triggers Seeding), Property 17 (Active Download Limit)_ 

- [x] 1.3 Implement priority and stats methods 
- **Spec Analysis**: Read `requirements.md` (Req 12.6, 13.4, 28.4) and `design.md` (GlobalStats struct, TorrentPriority enum, Property 18, Property 20) 
- **Docs**: Consult https://docs.rs/librqbit/latest/librqbit/ 
- Implement `set_priority(info_hash, TorrentPriority)` - store in local HashMap (librqbit doesn't support native priority) 
- Implement `get_stats() -> GlobalStats` - aggregate stats from all torrents 
- implement `shutdown()` - pause all torrents, save state, drop session gracefully 
- Add `TorrentPriority` enum: `Low`, `Normal`, `High` 
- Add `GlobalStats` struct: `total_downloaded`, `total_uploaded`, `download_speed`, `upload_speed`, `active_torrents`, `seeding_torrents`, `paused_torrents` 
- **If in doubt**: Use Perplexity quick search for torrent client priority patterns 
- _Complexity: Simple | Doc/Context7: Yes | Perplexity: Maybe | Tests: Yes (Unit) | Risks/Blockers: Priority not native | Commit: No

Requirements: 12.6, 13.4, 28.4

Design: Property 18 (Priority-Based Bandwidth), Property 20 (Upload Statistics)

[x] 1.4 Commit

feat(torrent): extend TorrentManager with lifecycle and stats [stage-4-torrent-download#1]

[x] 1.5 Overview

Summarize TorrentManager extensions, RwLock wrappers, lifecycle methods, and stats aggregation

Note: Chat summary only - do NOT create files

---

A lot needs to be organized and I'm going to automate this like a Power of Kiro, it's not a silver bullet, but it helps to structure and organize in a more predictable pattern.