@dtt_siye/atool 1.1.0

package/skills/rust-conventions/SKILL.md

@@ -0,0 +1,361 @@
+---
+name: rust-conventions
+description: Rust/Cargo/Tauri development conventions and best practices
+version: 1.0.0
+---
+
+# Rust Conventions
+
+Use this skill when working on Rust projects.
+
+## When to Use
+- Detected Rust project (Cargo.toml)
+- Detected Tauri project (src-tauri/Cargo.toml)
+- User asks about Rust or Tauri best practices
+- Writing or reviewing Rust/Tauri code
+
+## Code Style
+
+### General
+- Follow Rust API Guidelines
+- Run `cargo fmt` for formatting
+- Run `cargo clippy -- -D warnings` for linting
+- 4-space indentation
+- Use `rustfmt.toml` for project-specific formatting
+
+### Naming
+- Types & Traits: `PascalCase` (`UserService`)
+- Functions & Methods: `snake_case` (`get_user`)
+- Constants: `UPPER_SNAKE_CASE` (`MAX_RETRIES`)
+- Lifetime parameters: short names (`'a`, `'b`)
+- Type parameters: `PascalCase` with `T` prefix (`TValue`)
+
+### Idioms
+- Use `Option<T>` instead of null
+- Use `Result<T, E>` instead of exceptions
+- Use `impl Trait` for simple trait bounds
+- Use `&str` for borrowed strings, `String` for owned
+- Use `Cow<str>` when ownership varies
+- Use iterators over index-based loops
+- Use pattern matching (`match`, `if let`, `let else`)
+
+## Error Handling
+
+### Custom Errors with thiserror
+```rust
+use thiserror::Error;
+
+#[derive(Error, Debug)]
+pub enum AppError {
+    #[error("User not found: {0}")]
+    UserNotFound(String),
+
+    #[error("Database error: {0}")]
+    Database(#[from] sqlx::Error),
+
+    #[error("Unauthorized")]
+    Unauthorized,
+}
+
+pub type AppResult<T> = Result<T, AppError>;
+```
+
+### Error Handling Pattern
+```rust
+// In library code: return Result
+fn get_user(id: u32) -> AppResult<User> {
+    let user = db.query_user(id)?;
+    Ok(user)
+}
+
+// In application code: handle errors
+match get_user(id) {
+    Ok(user) => println!("{user:?}"),
+    Err(AppError::UserNotFound(_)) => println!("User not found"),
+    Err(e) => eprintln!("Error: {e}"),
+}
+```
+
+## Architecture
+
+### Module Organization
+```
+src/
+├── main.rs
+├── lib.rs
+├── config.rs
+├── error.rs
+├── models/
+│   ├── mod.rs
+│   └── user.rs
+├── services/
+│   ├── mod.rs
+│   └── user_service.rs
+└── api/
+    ├── mod.rs
+    └── handlers.rs
+```
+
+### Trait-based Abstraction
+```rust
+pub trait UserRepository {
+    fn find_by_id(&self, id: u32) -> AppResult<User>;
+    fn save(&self, user: &User) -> AppResult<()>;
+}
+```
+
+### Async/Await
+```rust
+use tokio;
+
+async fn fetch_user(id: u32) -> AppResult<User> {
+    let user = repository.find_by_id(id).await?;
+    Ok(user)
+}
+```
+
+## Ownership Patterns
+
+### Borrowing
+```rust
+fn process(data: &str) -> usize {
+    data.len()
+}
+
+fn take_ownership(data: String) -> usize {
+    data.len() // data is moved
+}
+```
+
+### Lifetimes
+```rust
+fn first_word<'a>(text: &'a str) -> &'a str {
+    text.split_whitespace().next().unwrap_or("")
+}
+```
+
+## Testing
+
+### Unit Tests
+```rust
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_process() {
+        assert_eq!(process("hello"), 5);
+    }
+
+    #[test]
+    #[should_panic(expected = "division by zero")]
+    fn test_panic_case() {
+        divide(1, 0);
+    }
+}
+```
+
+### Integration Tests (tests/ directory)
+```rust
+// tests/api_tests.rs
+use myapp::create_app;
+
+#[tokio::test]
+async fn test_get_user() {
+    let app = create_app().await;
+    let resp = app.get("/users/1").send().await;
+    assert!(resp.status().is_success());
+}
+```
+
+## Common Commands
+```bash
+cargo build          # Build
+cargo run           # Run
+cargo test          # Test
+cargo clippy -- -D warnings  # Lint strictly
+cargo fmt           # Format
+cargo build --release  # Release build
+cargo doc           # Generate docs
+cargo outdated      # Check dependency updates
+```
+
+## Tauri 2 Desktop Development
+
+### IPC Command Pattern
+
+```rust
+// src-tauri/src/commands/system.rs
+#[tauri::command]
+pub async fn get_system_info(state: tauri::State<'_, AppState>) -> Result<SysInfo, String> {
+    let info = state.get_system_info().await
+        .map_err(|e| e.to_string())?;
+    Ok(info)
+}
+```
+
+```typescript
+// src/services/system.ts
+import { invoke } from '@tauri-apps/api/core';
+
+export async function getSystemInfo(): Promise<SysInfo> {
+  return await invoke<SysInfo>('get_system_info');
+}
+```
+
+**Rules**:
+- All system operations must go through `#[tauri::command]` functions
+- Never access file system, network, or OS APIs directly from frontend
+- Commands return `Result<T, String>` for user-facing errors
+- Use `tauri::State` for shared application state
+
+### Command Registration
+
+```rust
+// src-tauri/src/lib.rs
+#[cfg_attr(mobile, tauri::mobile_entry_point)]
+pub fn run() {
+    tauri::Builder::default()
+        .plugin(tauri_plugin_shell::init())
+        .manage(AppState::new())
+        .invoke_handler(tauri::generate_handler![
+            commands::system::get_system_info,
+            commands::file::read_file,
+            commands::config::save_config,
+        ])
+        .run(tauri::generate_context!())
+        .expect("error while running tauri application");
+}
+```
+
+### State Management
+
+```rust
+// src-tauri/src/state.rs
+use std::sync::Mutex;
+
+pub struct AppState {
+    pub config: Mutex<AppConfig>,
+    pub cache: Mutex<HashMap<String, String>>,
+}
+
+impl AppState {
+    pub fn new() -> Self {
+        Self {
+            config: Mutex::new(AppConfig::default()),
+            cache: Mutex::new(HashMap::new()),
+        }
+    }
+}
+```
+
+### Error Handling in Commands
+
+```rust
+// Use thiserror for typed errors
+#[derive(Debug, thiserror::Error)]
+pub enum CommandError {
+    #[error("File not found: {0}")]
+    FileNotFound(String),
+    #[error("Permission denied: {0}")]
+    PermissionDenied(String),
+    #[error("IO error: {0}")]
+    Io(#[from] std::io::Error),
+}
+
+// Convert to user-friendly string in command boundary
+impl From<CommandError> for String {
+    fn from(err: CommandError) -> String {
+        err.to_string()
+    }
+}
+
+#[tauri::command]
+pub async fn read_file(path: String) -> Result<String, CommandError> {
+    std::fs::read_to_string(&path)
+        .map_err(CommandError::Io)
+}
+```
+
+### Security (Capabilities)
+
+```json
+// src-tauri/capabilities/default.json
+{
+  "identifier": "default",
+  "windows": ["main"],
+  "permissions": [
+    "core:default",
+    "shell:allow-open",
+    "dialog:allow-open",
+    "fs:allow-read-text-file"
+  ]
+}
+```
+
+**Rules**:
+- Declare all permissions explicitly in `capabilities/`
+- Use scoped file system access (limit paths)
+- Never use `core:window:allow-*` wildcards in production
+- Principle of least privilege
+
+### Frontend IPC Best Practices
+
+```typescript
+// Encapsulate all invoke calls in services/
+// src/services/system.ts
+import { invoke } from '@tauri-apps/api/core';
+
+export interface SysInfo {
+  os: string;
+  arch: string;
+  version: string;
+}
+
+export async function getSystemInfo(): Promise<SysInfo> {
+  return invoke<SysInfo>('get_system_info');
+}
+
+// Error handling wrapper
+export async function safeInvoke<T>(cmd: string, args?: Record<string, unknown>): Promise<T> {
+  try {
+    return await invoke<T>(cmd, args);
+  } catch (error) {
+    console.error(`IPC error [${cmd}]:`, error);
+    throw new Error(`Command '${cmd}' failed: ${error}`);
+  }
+}
+```
+
+### Shared Types
+
+Mirror Rust structs as TypeScript interfaces:
+
+```rust
+// Rust
+#[derive(Serialize, Deserialize)]
+pub struct AppConfig {
+    pub theme: String,
+    pub language: String,
+    pub auto_start: bool,
+}
+```
+
+```typescript
+// TypeScript
+export interface AppConfig {
+  theme: string;
+  language: string;
+  auto_start: boolean;
+}
+```
+
+### Common Tauri Commands
+
+```bash
+pnpm tauri dev              # Development with hot reload
+pnpm tauri build            # Production build
+cd src-tauri && cargo check # Quick Rust check
+cd src-tauri && cargo clippy # Lint Rust code
+cd src-tauri && cargo test  # Run Rust tests
+```

package/skills/smart-dispatch/SKILL.md

@@ -0,0 +1,296 @@
+---
+name: smart-dispatch
+description: Use when executing an implementation plan with parallelizable tasks. Parses plan into chunks, detects file-level dependencies, and dispatches independent tasks as parallel background agents with two-stage review. Falls back to sequential execution on platforms without subagent support.
+version: 0.1.0
+---
+
+# Smart-Dispatch: Dependency-Aware Parallel Plan Execution
+
+Execute implementation plans by dispatching independent tasks as parallel background agents, while respecting task dependencies and file-level conflicts.
+
+## When to Use
+
+- You have a written implementation plan with tasks to execute
+- The plan uses `## Chunk N: Title` groupings (or you can infer chunks from task structure)
+- Your platform supports subagents (Claude Code with Agent tool, Cursor)
+- Tasks within chunks touch different files and can run independently
+
+**Do NOT use when:**
+- Platform lacks subagent support → use `executing-plans` instead
+- All tasks are tightly coupled (modify same files) → use `subagent-driven-development`
+- You need debugging, not plan execution → use `dispatching-parallel-agents`
+
+## Decision Flowchart
+
+```dot
+digraph smart_dispatch {
+  "Have implementation plan?" [shape=diamond];
+  "Platform has subagents?" [shape=diamond];
+  "Tasks have file overlap?" [shape=diamond];
+  "Use smart-dispatch" [shape=box];
+  "Use executing-plans" [shape=box];
+  "Use subagent-driven-development" [shape=box];
+
+  "Have implementation plan?" -> "Platform has subagents?" [label="yes"];
+  "Have implementation plan?" -> "Write plan first" [label="no"];
+  "Platform has subagents?" -> "Use smart-dispatch" [label="yes"];
+  "Platform has subagents?" -> "Use executing-plans" [label="no"];
+  "Use smart-dispatch" -> "Tasks have file overlap?";
+  "Tasks have file overlap?" -> "Split into sub-waves" [label="yes"];
+  "Tasks have file overlap?" -> "Full parallel" [label="no"];
+}
+```
+
+## Platform Detection
+
+Before dispatching, detect the platform:
+
+| Platform | Detection | Parallel Mechanism |
+|----------|-----------|-------------------|
+| Claude Code | `Agent` tool available with `run_in_background` parameter | `Agent` tool + `run_in_background: true` |
+| Cursor | Cursor agent tool available | Cursor background tasks |
+| Kiro | No subagent support | Fallback to `executing-plans` |
+| Gemini CLI | No subagent support | Fallback to `executing-plans` |
+
+When platform doesn't support background agents:
+```
+Parallel agents not available on this platform.
+Falling back to sequential execution via executing-plans.
+Consider using Claude Code for full parallel support.
+```
+
+---
+
+## Phase 1: Parse Plan into Chunks
+
+### Chunk Syntax
+
+Plans use `## Chunk N: Title` headers to group tasks:
+
+```markdown
+## Chunk 1: Foundation Tasks
+
+### Task 1: Create Types
+**Files:**
+- Create: `src/types.ts`
+
+### Task 2: Create Config
+**Files:**
+- Create: `src/config.ts`
+
+## Chunk 2: Components
+**Depends on:** Chunk 1
+
+### Task 3: Button Component
+**Files:**
+- Create: `src/Button.tsx`
+```
+
+### Parsing Rules
+
+1. `## Chunk N: Title` starts a new chunk; all tasks until the next chunk header belong to it
+2. `**Depends on:** Chunk M` declares explicit dependency (optional)
+3. Without `Depends on:`, Chunk N depends on Chunk N-1 (sequential by number)
+4. Each task has `**Files:**` with `Create:`, `Modify:`, or `Test:` entries
+5. **Backward compatible**: plans without chunk headers → single chunk, all tasks sequential
+
+### Build Chunk DAG
+
+```
+For each chunk:
+  Extract dependency from "Depends on:" or default to previous chunk
+  Build directed acyclic graph (DAG)
+  Verify: no cycles (if cycle detected → error, ask user to fix plan)
+```
+
+---
+
+## Phase 2: Compute Sub-Waves (Within Each Chunk)
+
+### File Overlap Analysis
+
+For each pair of tasks within a chunk:
+
+```
+For each task pair (Ti, Tj) where i < j:
+  If Ti.Files ∩ Tj.Files ≠ ∅ (Create or Modify same file):
+    → Add edge Ti → Tj
+  If Ti creates file X AND Tj modifies file X:
+    → Add edge Ti → Tj
+```
+
+### Sub-wave Computation
+
+```
+1. Build file-overlap graph from analysis above
+2. Topological sort → BFS level-by-level → sub-waves
+3. Tasks with no edges between them → same sub-wave (PARALLEL)
+4. Tasks with edges → different sub-waves (SEQUENTIAL)
+```
+
+### Output: Dispatch Plan
+
+Print the dispatch plan before executing:
+
+```
+Dispatch Plan:
+  Chunk 1: Foundation (no dependencies)
+    Sub-wave 1: [Task 1, Task 2] — PARALLEL (no file overlap)
+    Sub-wave 2: [Task 3] — depends on Task 1 (modifies types.ts)
+
+  Chunk 2: Components (depends on Chunk 1)
+    Sub-wave 1: [Task 4, Task 5, Task 6] — PARALLEL (different files)
+
+  Chunk 3: Integration (depends on Chunk 2)
+    Sub-wave 1: [Task 7] — SEQUENTIAL (touches multiple files)
+```
+
+---
+
+## Phase 3: Execute
+
+### Execution Loop
+
+```
+For each chunk (in topological order from DAG):
+
+  Compute sub-waves via file-overlap analysis
+
+  For each sub-wave:
+
+    1. DISPATCH: Send all tasks in sub-wave as background agents
+       - **HARD LIMIT: Maximum 5 concurrent background agents**
+       - If sub-wave has more than 5 tasks, queue in batches of 5
+       - Wait for ALL agents in current batch to complete before starting next batch
+       - Use implementer-prompt.md template
+       - Each agent gets: task description, file list, steps, scope constraints
+       - Monitor all agents until ALL complete
+
+    2. REVIEW: Sequential two-stage review per completed task
+       For each task (one at a time):
+         a. Spec Review → use reviewer-prompt.md (spec mode)
+            - If FAIL → re-dispatch fix agent (max 2 retries)
+         b. Code Quality Review → use reviewer-prompt.md (quality mode)
+            - If FAIL → re-dispatch fix agent (max 2 retries)
+         c. If both PASS → mark task COMPLETE
+
+    3. COMMIT: Controller commits after each task passes both reviews
+       - One commit per task: git commit -m "feat: [task description]"
+       - Commits are SEQUENTIAL (never parallel)
+
+    4. HANDLE FAILURES:
+       - BLOCKED task → halt chunk, report blocker to user
+       - FAILED after retries → report, continue with remaining tasks
+       - Agent crash/timeout → treat as BLOCKED
+
+  Next sub-wave
+
+Next chunk
+
+FINAL: Run verification-before-completion + doc sync
+```
+
+### Model Selection
+
+| Task Type | Model | Reason |
+|-----------|-------|--------|
+| Mechanical (1-2 files, clear spec) | fast/cheap | Simple implementation |
+| Integration (multi-file, patterns) | standard | Needs broader context |
+| Architecture/design/review | most capable | Requires judgment |
+
+---
+
+## Safety Rules
+
+### What Can Run in Parallel
+
+| Operation | Parallel? | Reason |
+|-----------|-----------|--------|
+| Create different new files | YES | No conflict possible |
+| Modify different existing files | YES | No conflict |
+| Run linter/formatter | YES | Read-only operation |
+| Create + modify same file | NO → sequential | Dependency |
+| Modify same file different sections | NO → sequential | Conservative; avoid conflicts |
+| git commit/push | NO → Controller only | Parallel commits conflict |
+| Install dependencies (npm/cargo/pip) | NO → sequential | Shared lock files |
+| Run tests | NO → sequential | May depend on shared state |
+
+### Agent Scope Constraints
+
+Each implementer agent receives these strict rules in its prompt:
+
+```
+**Scope Limitations:**
+- ONLY create/modify: {explicit file list from task}
+- FORBIDDEN: git commit, git push, git add
+- FORBIDDEN: npm install, cargo build, pip install, go mod tidy
+- FORBIDDEN: Modify any file NOT in the above list
+- If you need to modify additional files → return BLOCKED status
+```
+
+### Failure Handling
+
+| Status | Action |
+|--------|--------|
+| DONE | Proceed to review |
+| DONE_WITH_CONCERNS | Read concerns, decide proceed or fix |
+| BLOCKED | Halt chunk, report blocker to user |
+| NEEDS_CONTEXT | Provide context, re-dispatch same agent |
+| Review FAIL | Re-dispatch fix agent (max 2 retries per stage) |
+| All retries exhausted | Mark FAILED, report, continue other tasks |
+| Agent crash/timeout | Treat as BLOCKED, report last known output |
+
+---
+
+## Review Integration
+
+### Two-Stage Review (Per Task, Sequential)
+
+**Stage 1: Spec Compliance Review**
+- Did the implementer build exactly what was requested?
+- All steps completed? All files created/modified?
+- No extra features added? No missing requirements?
+- Reviewer MUST read actual code, not trust implementer's report
+
+**Stage 2: Code Quality Review** (only after Stage 1 passes)
+- Dead code? Duplication? Overly complex functions?
+- Error handling adequate? Security issues?
+- Follows project conventions? File organization clean?
+
+### Review Scheduling
+
+- Reviews run **sequentially per task** (not parallelized)
+- A task must pass spec review BEFORE code quality review starts
+- A sub-wave must have ALL tasks pass both reviews before the next sub-wave starts
+- Between sub-waves: Controller commits all passed tasks
+
+---
+
+## Checklist
+
+Before starting execution, verify:
+
+- [ ] Plan has been parsed into chunks
+- [ ] Chunk DAG has been built (no cycles)
+- [ ] Sub-waves computed for each chunk
+- [ ] Dispatch plan printed and confirmed
+- [ ] Platform supports background agents (or fallback chosen)
+
+During execution:
+
+- [ ] Each sub-wave dispatched as background agents
+- [ ] All agents monitored until completion
+- [ ] Two-stage review run on each task
+- [ ] Failures handled per the table above
+- [ ] Commits made after reviews pass (sequential)
+
+After execution:
+
+- [ ] All tasks completed (or failures reported)
+- [ ] Documentation sync task executed
+- [ ] verification-before-completion run
+
+## Prompt Templates
+
+- **Implementer prompt:** `skills/smart-dispatch/implementer-prompt.md`
+- **Reviewer prompt:** `skills/smart-dispatch/reviewer-prompt.md`