@kodrunhq/opencode-autopilot 1.3.0 → 1.5.0

package/assets/skills/rust-patterns/SKILL.md

@@ -0,0 +1,293 @@
+---
+name: rust-patterns
+description: Rust patterns covering ownership, error handling with Result/Option, unsafe guidelines, and testing conventions
+stacks:
+  - rust
+requires: []
+---
+
+# Rust Patterns
+
+Idiomatic Rust patterns for writing safe, efficient, and maintainable code. Covers ownership and borrowing, error handling with `Result` and `Option`, unsafe guidelines, testing conventions, crate organization, and common anti-patterns. Apply these when writing, reviewing, or refactoring Rust code.
+
+## 1. Ownership and Borrowing
+
+**DO:** Leverage Rust's ownership system to write safe code without garbage collection.
+
+- Prefer borrowing (`&T`, `&mut T`) over taking ownership when the function doesn't need to own the data:
+  ```rust
+  // DO: Borrow -- caller keeps ownership
+  fn process(items: &[Item]) -> Summary { ... }
+
+  // DON'T: Take ownership unnecessarily
+  fn process(items: Vec<Item>) -> Summary { ... }
+  ```
+- Prefer `&str` over `String` in function parameters:
+  ```rust
+  fn greet(name: &str) -> String {
+      format!("Hello, {name}!")
+  }
+  // Accepts both String and &str via deref coercion
+  ```
+- Use lifetimes explicitly when the compiler cannot infer them:
+  ```rust
+  struct Parser<'a> {
+      input: &'a str,
+      position: usize,
+  }
+  ```
+- Understand move semantics -- types implementing `Copy` are copied, others are moved:
+  ```rust
+  let a = String::from("hello");
+  let b = a;  // a is MOVED to b, a is no longer valid
+  // For Copy types (i32, f64, bool): both remain valid
+  ```
+- Use `Cow<'_, str>` when a function sometimes needs to allocate and sometimes doesn't:
+  ```rust
+  fn normalize(input: &str) -> Cow<'_, str> {
+      if input.contains(' ') {
+          Cow::Owned(input.replace(' ', "_"))
+      } else {
+          Cow::Borrowed(input)
+      }
+  }
+  ```
+
+**DON'T:**
+
+- Use `Clone` to silence the borrow checker -- fix the ownership design instead
+- Pass `&String` -- pass `&str` (more general, no extra indirection)
+- Use `'static` lifetime unless the data truly lives for the entire program
+- Fight the borrow checker with `Rc<RefCell<T>>` everywhere -- rethink the data flow
+
+## 2. Error Handling
+
+**DO:** Use `Result<T, E>` for recoverable errors and the `?` operator for ergonomic propagation.
+
+- Use `Result<T, E>` for all operations that can fail:
+  ```rust
+  fn parse_config(path: &Path) -> Result<Config, ConfigError> {
+      let content = fs::read_to_string(path)?;
+      let config: Config = toml::from_str(&content)?;
+      Ok(config)
+  }
+  ```
+- Use `?` for error propagation -- it's Rust's equivalent of Go's `if err != nil`:
+  ```rust
+  fn process() -> Result<Output, AppError> {
+      let input = read_input()?;       // propagates on Err
+      let parsed = parse(input)?;       // propagates on Err
+      let result = transform(parsed)?;  // propagates on Err
+      Ok(result)
+  }
+  ```
+- Use `thiserror` for custom error types in library code:
+  ```rust
+  #[derive(Debug, thiserror::Error)]
+  enum AppError {
+      #[error("config error: {0}")]
+      Config(#[from] ConfigError),
+      #[error("database error: {0}")]
+      Database(#[from] sqlx::Error),
+      #[error("not found: {resource}")]
+      NotFound { resource: String },
+  }
+  ```
+- Use `anyhow::Result` in application code (binaries, CLI tools) where you don't need typed errors:
+  ```rust
+  fn main() -> anyhow::Result<()> {
+      let config = load_config().context("failed to load config")?;
+      run(config)?;
+      Ok(())
+  }
+  ```
+- Add context to errors with `.context()` or `.with_context()`:
+  ```rust
+  fs::read_to_string(path)
+      .with_context(|| format!("failed to read {}", path.display()))?;
+  ```
+
+**DON'T:**
+
+- Use `panic!` for recoverable errors -- `panic!` is for bugs, not expected failures
+- Use `.unwrap()` in production code -- use `?`, `.unwrap_or_default()`, or explicit match
+- Create error types without `#[derive(Debug)]` -- debug formatting is essential for logging
+- Return `Box<dyn Error>` in library code -- use typed errors for caller inspection
+
+## 3. Option Patterns
+
+**DO:** Use `Option<T>` instead of null/sentinel values, and prefer combinators over manual matching.
+
+- Use combinators for clean transformations:
+  ```rust
+  let display_name = user.nickname
+      .map(|n| format!("@{n}"))
+      .unwrap_or_else(|| user.full_name.clone());
+  ```
+- Use `if let` for conditional extraction:
+  ```rust
+  if let Some(config) = load_optional_config() {
+      apply(config);
+  }
+  ```
+- Use `?` with `Option` in functions returning `Option`:
+  ```rust
+  fn get_user_email(db: &Database, id: UserId) -> Option<String> {
+      let user = db.find_user(id)?;  // returns None if not found
+      Some(user.email.clone())
+  }
+  ```
+- Chain operations with `.and_then()` for flat-mapping:
+  ```rust
+  let port: Option<u16> = env::var("PORT").ok().and_then(|s| s.parse().ok());
+  ```
+
+**DON'T:**
+
+- Use `.unwrap()` outside of tests -- it panics on `None`
+- Use sentinel values (`-1`, `""`, `0`) when `Option` expresses the intent clearly
+- Match when a combinator is more concise -- `option.map(f)` beats `match option { Some(v) => Some(f(v)), None => None }`
+- Use `Option<Option<T>>` -- it's confusing. Use an enum with explicit variants instead
+
+## 4. Unsafe Guidelines
+
+**DO:** Minimize unsafe code and encapsulate it behind safe abstractions.
+
+- Wrap every `unsafe` block in a safe function with documented invariants:
+  ```rust
+  /// Returns a reference to the element at `index` without bounds checking.
+  ///
+  /// # Safety
+  /// Caller must ensure `index < self.len()`.
+  pub unsafe fn get_unchecked(&self, index: usize) -> &T { ... }
+  ```
+- Document every `unsafe` block with a `// SAFETY:` comment explaining the invariant:
+  ```rust
+  // SAFETY: We checked that index < len on the line above.
+  let value = unsafe { slice.get_unchecked(index) };
+  ```
+- Keep `unsafe` blocks as small as possible -- one operation per block
+- Prefer safe alternatives in all cases:
+  - `Vec<T>` over raw pointers and manual allocation
+  - `Arc<Mutex<T>>` over shared mutable raw pointers
+  - `std::sync::atomic` over `unsafe` for atomic operations
+  - `crossbeam` or channels over `unsafe` for concurrent data structures
+
+**DON'T:**
+
+- Use `unsafe` for performance without benchmarks proving it's necessary
+- Use `transmute` -- it's almost never the right answer. Use `from_ne_bytes`, `TryFrom`, or safe casts
+- Dereference raw pointers without validating alignment and lifetime
+- Implement `Send` or `Sync` manually unless you deeply understand the invariants
+- Use `unsafe` to bypass the borrow checker -- it means the design is wrong
+
+## 5. Testing
+
+**DO:** Write unit tests in the same file and integration tests in `tests/`.
+
+- Unit tests in the same file with `#[cfg(test)]`:
+  ```rust
+  #[cfg(test)]
+  mod tests {
+      use super::*;
+
+      #[test]
+      fn parse_valid_config() {
+          let config = parse_config("key = \"value\"").unwrap();
+          assert_eq!(config.key, "value");
+      }
+
+      #[test]
+      fn parse_empty_returns_error() {
+          assert!(parse_config("").is_err());
+      }
+  }
+  ```
+- Use `#[should_panic]` for expected panics:
+  ```rust
+  #[test]
+  #[should_panic(expected = "index out of bounds")]
+  fn panics_on_invalid_index() {
+      get_item(&[], 0);
+  }
+  ```
+- Use `assert_eq!` with descriptive messages:
+  ```rust
+  assert_eq!(result, expected, "failed for input: {input:?}");
+  ```
+- Integration tests in `tests/` directory access only the public API:
+  ```
+  tests/
+    integration_test.rs
+    common/
+      mod.rs  // shared test helpers
+  ```
+- Use `proptest` or `quickcheck` for property-based testing:
+  ```rust
+  proptest! {
+      #[test]
+      fn roundtrip_serialize(value: MyType) {
+          let bytes = serialize(&value);
+          let decoded = deserialize(&bytes).unwrap();
+          assert_eq!(value, decoded);
+      }
+  }
+  ```
+- Use `#[ignore]` for slow tests with a reason: `#[ignore = "requires database"]`
+
+**DON'T:**
+
+- Put test utilities in the main `src/` tree -- use `tests/common/` or a `dev-dependencies` crate
+- Use `.unwrap()` in tests without context -- prefer `.expect("reason")` for better panic messages
+- Test private implementation details -- test through the public API
+- Skip `#[cfg(test)]` on the test module -- tests will be compiled into release builds
+
+## 6. Crate Organization
+
+**DO:** Organize crates for clarity and minimal compilation units.
+
+- Use a workspace for multi-crate projects:
+  ```toml
+  # Cargo.toml (workspace root)
+  [workspace]
+  members = ["crates/*"]
+  ```
+- Separate library and binary crates:
+  ```
+  src/
+    lib.rs    # library logic
+    main.rs   # thin entry point calling lib
+  ```
+- Use `pub(crate)` for internal visibility -- not everything needs to be fully public
+- Group related types in modules:
+  ```rust
+  // src/lib.rs
+  pub mod config;
+  pub mod error;
+  pub mod client;
+  ```
+- Keep `main.rs` thin -- parse args, configure logging, call library functions
+
+**DON'T:**
+
+- Put everything in `lib.rs` -- split into modules when the file exceeds 400 lines
+- Use `pub` on everything -- default to private, expose only what's needed
+- Create deep module hierarchies -- flat is better than nested
+- Use `mod.rs` files (old style) -- prefer `module_name.rs` (2018 edition style)
+
+## 7. Anti-Pattern Catalog
+
+**Anti-Pattern: Unnecessary Clone**
+Calling `.clone()` to satisfy the borrow checker without understanding why it's needed. Cloning hides design problems -- if you need to clone, ask whether the ownership model is correct. Instead: restructure code to use references, or use `Cow<'_, T>` when cloning is sometimes needed.
+
+**Anti-Pattern: Unwrap Everywhere**
+Sprinkling `.unwrap()` in production code because "it should never be None/Err". It will be, and it will panic at 3am. Instead: use `?` for propagation, `.unwrap_or_default()` for safe defaults, or `match`/`if let` for explicit handling.
+
+**Anti-Pattern: Stringly Typed**
+Using `String` for everything -- status codes, identifiers, categories. Strings have no compile-time validation. Instead: use newtypes (`struct UserId(String)`) and enums (`enum Status { Active, Inactive }`) for domain concepts.
+
+**Anti-Pattern: Over-Generic Functions**
+`fn process<T: Debug + Clone + Send + Sync + 'static>(item: T)` when the function only ever processes `Widget`. Generics should be introduced when there are 2+ concrete types that need the same logic. Instead: start concrete, generalize when needed.
+
+**Anti-Pattern: Ignoring Clippy**
+Adding `#[allow(clippy::...)]` instead of fixing the lint. Clippy catches real bugs (unnecessary allocations, logic errors, unidiomatic code). Instead: fix the issue. If the lint is genuinely wrong, add a comment explaining why.

package/assets/skills/strategic-compaction/SKILL.md

@@ -0,0 +1,217 @@
+---
+name: strategic-compaction
+description: Context window management through strategic summarization -- keep working memory lean without losing critical information
+stacks: []
+requires: []
+---
+
+# Strategic Compaction
+
+Context window management through strategic summarization. When your working context grows large, compaction keeps you productive by preserving what matters and discarding what does not. This skill teaches when to compact, what to keep, and how to rebuild context from a summary.
+
+## When to Use
+
+- Context window is filling up (more than 60% used)
+- Working on a long task spanning many files
+- Need to switch subtasks without losing prior context
+- Session is slowing down or responses are becoming less detailed
+- You are about to start a new phase of work that does not need the details of the previous phase
+- After completing a major subtask and before starting the next
+
+## The Compaction Process
+
+Compaction is a four-step process. Follow each step in order.
+
+### Step 1: Identify What to Keep
+
+These items are essential and must survive compaction:
+
+- **Current task requirements** -- the active goal and acceptance criteria
+- **Key decisions made so far** -- and the rationale behind each one (the WHY is more important than the WHAT)
+- **File paths and function signatures** -- for files currently being modified or about to be modified
+- **Error messages and test failures** -- if you are actively investigating or debugging
+- **Constraints and invariants** -- rules that must not be violated (security requirements, API contracts, performance budgets)
+- **Dependency relationships** -- what depends on what, what must be done in order
+
+### Step 2: Identify What to Compact
+
+These items can be summarized or discarded:
+
+- **File contents already read and understood** -- keep only the path plus the key insight (e.g., "src/auth.ts: JWT validation using jose library, exports verifyToken()")
+- **Exploration dead ends** -- reduce to one line: "Tried approach X, did not work because Y"
+- **Verbose tool output** -- keep the conclusion, discard the raw output (e.g., "Tests pass: 47/47" instead of the full test runner output)
+- **Background context not needed for the current subtask** -- prior phase decisions that are not relevant to what you are doing right now
+- **Completed work details** -- reduce to "Task N done: implemented feature X in file Y" with the commit hash
+
+### Step 3: Create a Summary
+
+Structure your summary using this template:
+
+```
+## Working Context Summary
+
+**Goal:** [one sentence describing the active objective]
+
+**Key Decisions:**
+- [Decision 1]: [rationale]
+- [Decision 2]: [rationale]
+
+**Current State:**
+- Done: [what has been completed]
+- In Progress: [what is currently being worked on]
+- Next: [what comes after the current task]
+
+**Active Files:**
+- [path]: [what you are doing with this file]
+- [path]: [key insight about this file]
+
+**Constraints:**
+- [constraint 1]
+- [constraint 2]
+
+**Errors/Blockers:**
+- [any active issues being investigated]
+```
+
+Target 500-1000 tokens for the summary. This is your restore point -- it should contain everything needed to resume work without re-reading files.
+
+### Step 4: Apply Compaction
+
+When starting a new session or after context reset:
+
+1. Load the summary first -- this is your map
+2. Read only the files actively being modified (the "Active Files" list)
+3. Re-read constraints and interfaces only if you need to verify a specific detail
+4. Do NOT re-read files that were already summarized unless you need to edit them
+
+## What to NEVER Compact
+
+Some information is too dangerous to summarize. Always keep these in full:
+
+- **Active error messages being debugged** -- the exact error text matters for diagnosis
+- **Type definitions and interfaces being implemented against** -- approximate types lead to type errors
+- **Test expectations being satisfied** -- the exact assertion values matter
+- **Security constraints and validation rules** -- approximate security is no security
+- **API contracts with external systems** -- exact field names, types, and required headers
+- **Migration scripts in progress** -- partial migration state is dangerous to approximate
+
+## Compaction Strategies by Scenario
+
+### Scenario: Multi-File Refactoring
+
+You have read 15 files and identified the refactoring pattern. Compact by keeping:
+- The list of files to modify (paths only)
+- The transformation pattern (e.g., "replace direct DB calls with repository pattern")
+- Files already transformed (path + done status)
+- The next file to transform
+
+### Scenario: Debugging a Complex Issue
+
+You have explored multiple hypotheses. Compact by keeping:
+- The symptom (exact error message)
+- Hypotheses tested and their results (one line each)
+- Current hypothesis being investigated
+- Files relevant to the current hypothesis
+
+### Scenario: Implementing a Feature Across Layers
+
+You are building a feature that touches API, service, and data layers. Compact by keeping:
+- The feature requirements
+- Interface contracts between layers (function signatures, types)
+- Which layers are done, which are in progress
+- Test status for completed layers
+
+## Anti-Pattern Catalog
+
+### Anti-Pattern: Compacting Too Early
+
+**What it looks like:** Summarizing after reading just 2-3 files, before you have a full picture of the problem space.
+
+**Why it is harmful:** You do not yet know what is important. Early summaries miss critical context that you discover later.
+
+**Instead:** Compact when context is more than 60% full, or when you are transitioning between major subtasks. Not before.
+
+### Anti-Pattern: Losing Key Decisions
+
+**What it looks like:** Summarizing away the reasoning behind a decision, keeping only the outcome.
+
+**Why it is harmful:** Without the WHY, you (or a future session) may revisit and reverse a well-reasoned decision, wasting time.
+
+**Instead:** Always keep decision rationale. "Chose JWT over session cookies because the API is stateless and serves mobile clients" -- not just "Using JWT."
+
+### Anti-Pattern: Over-Compacting
+
+**What it looks like:** Reducing context to a single paragraph that says "working on auth feature."
+
+**Why it is harmful:** Too little context means you have to re-read everything, defeating the purpose of compaction.
+
+**Instead:** Keep file paths, function signatures, decision rationale, and current task state. The summary should be 500-1000 tokens, not 50.
+
+### Anti-Pattern: Never Compacting
+
+**What it looks like:** Accumulating context until the window is full and responses degrade.
+
+**Why it is harmful:** The last 20% of the context window produces worse results. By the time you notice degradation, you have already lost quality.
+
+**Instead:** Proactively compact when you pass 60% usage, or at natural transition points between subtasks.
+
+### Anti-Pattern: Compacting Active Work
+
+**What it looks like:** Summarizing files you are still actively editing, losing the detailed state.
+
+**Why it is harmful:** You will need to re-read those files immediately, wasting the effort of compaction.
+
+**Instead:** Only compact information from COMPLETED subtasks. Keep active work in full detail.
+
+## Failure Modes
+
+### Summary Is Too Vague
+
+**Symptom:** After loading the summary, you do not know which file to open or what to do next.
+
+**Fix:** Add specific file paths, function names, and the exact next action. A good summary answers: "What file do I open first, and what do I do in it?"
+
+### Lost Critical Context
+
+**Symptom:** You make a mistake that contradicts a decision or constraint from the compacted context.
+
+**Fix:** The information is on disk -- re-read the relevant files. Then update your summary to include the missing constraint. This is recoverable, not catastrophic.
+
+### Summary Is Too Long
+
+**Symptom:** The summary itself is 2000+ tokens and does not fit well as a context primer.
+
+**Fix:** Focus on what is needed for the NEXT task, not everything done so far. Completed work can be reduced to one line per task. Only the current and next tasks need detail.
+
+### Rebuilt Context Drifts from Original
+
+**Symptom:** After loading a summary and re-reading files, you reach a different understanding than before compaction.
+
+**Fix:** Include concrete artifacts in your summary (exact function signatures, test names, error messages) rather than prose descriptions. Concrete details resist drift; abstract descriptions invite reinterpretation.
+
+## Compaction Checklist
+
+Use this checklist before and after compaction to ensure quality:
+
+### Before Compacting
+
+- [ ] Context is more than 60% full OR you are transitioning between major subtasks
+- [ ] You have completed a logical unit of work (not mid-task)
+- [ ] You are not actively debugging an error (keep full error context)
+- [ ] You have identified the next task clearly
+
+### Writing the Summary
+
+- [ ] Goal is stated in one sentence
+- [ ] Every key decision includes its rationale (the WHY)
+- [ ] Active file paths are listed with their purpose
+- [ ] Current state is explicit (done, in progress, next)
+- [ ] Constraints and invariants are preserved verbatim
+- [ ] Summary is between 500 and 1000 tokens
+
+### After Loading a Summary
+
+- [ ] You know which file to open first
+- [ ] You know what action to take next
+- [ ] You have not re-read files unnecessarily
+- [ ] If anything is unclear, you re-read the specific source file (not everything)