feat: add opencode agents and skills for development workflows
CI / build-and-test (push) Successful in 27s
CI / build-and-test (pull_request) Successful in 26s

New agents:
- architect: system design, module interactions, data flow
- debugger: crash/memory/thread debugging with ASan, TSan, valgrind, gdb
- security-auditor: TLS, input validation, buffer safety, crypto audit
- refactorer: DRY, separation of concerns, API simplification
- integrator: integration tests, CI/CD pipeline, end-to-end verification
- code-explainer: architecture walkthrough, code explanation

New skills:
- debug-workflow: structured debugging workflow
- refactor: code restructuring with test verification
- security-audit: full security review with checklist
- benchmark: performance benchmarking with multi-run medians
- release: version bump, tests, tagging

Improved existing:
- c-reviewer: added security checklist
- cmake-expert: added ASan/TSan/UBSan configs, ccache, cross-compilation
- perf-analyst: added perf/valgrind/gprof commands
- test-writer: added fuzzing harnesses, integration test patterns
- pr-build: added sanitizer build variants
- pr-review: added security review, performance impact assessment
This commit is contained in:
2026-07-19 14:50:02 +02:00
parent 43ba149ad5
commit 8141158a3d
17 changed files with 1705 additions and 3 deletions
+125
View File
@@ -0,0 +1,125 @@
---
name: benchmark
description: Runs performance benchmarks on FastSync, collects metrics, compares configurations, and reports throughput. Use when the user says "benchmark", "measure performance", "profile", or wants to compare transfer speeds.
---
# Benchmark Skill
Runs performance benchmarks and collects metrics. This skill CAN edit files for benchmark scripts and run builds/tests.
## Workflow
### Step 1: Build Optimized
```bash
rm -rf build
cmake -B build -S . -DCMAKE_BUILD_TYPE=Release
cmake --build build -j$(nproc)
```
### Step 2: Generate Test Data
```bash
mkdir -p /tmp/fastsync_bench/src
# Small files
for i in $(seq 1 100); do
dd if=/dev/urandom of=/tmp/fastsync_bench/src/small_$i.bin bs=1K count=10 2>/dev/null
done
# Medium files
for i in $(seq 1 20); do
dd if=/dev/urandom of=/tmp/fastsync_bench/src/med_$i.bin bs=1M count=1 2>/dev/null
done
# Large files
dd if=/dev/urandom of=/tmp/fastsync_bench/src/large.bin bs=1M count=10 2>/dev/null
```
### Step 3: Run Benchmarks
Test each configuration 3 times, record median:
```bash
CONFIGS=(
"Standard|"
"Compression|-c"
"Multithreading|-m"
"MT+Compression|-m -c"
"Chunk Serialization|-s"
"MT+Compression+Chunk|-m -c -s"
"Sendfile|-f"
)
for config in "${CONFIGS[@]}"; do
IFS='|' read -r name flags <<< "$config"
echo "=== $name ==="
for run in 1 2 3; do
rm -rf /tmp/fastsync_bench/dst
mkdir -p /tmp/fastsync_bench/dst
./build/server &
SERVER_PID=$!
sleep 0.5
START=$(date +%s%N)
./build/client --source-dir /tmp/fastsync_bench/src \
--dest-dir /tmp/fastsync_bench/dst \
--save-to-disk $flags
END=$(date +%s%N)
ELAPSED=$(( (END - START) / 1000000 ))
echo " Run $run: ${ELAPSED}ms"
kill $SERVER_PID 2>/dev/null
wait $SERVER_PID 2>/dev/null
done
done
```
### Step 4: Full Integration Benchmark (Optional)
For comprehensive benchmarking with network shaping:
```bash
python3 test.py --full
```
This tests LAN/WAN profiles, SSH, TLS, and compares against rsync.
### Step 5: Report Results
```
=== BENCHMARK RESULTS ===
Test data: <size> MB (<file count> files)
Platform: <OS, CPU, network>
Configuration | Run 1 | Run 2 | Run 3 | Median
-----------------------|---------|---------|---------|--------
Standard | 0.12s | 0.11s | 0.12s | 0.12s
Compression (-c) | 0.09s | 0.08s | 0.09s | 0.09s
Multithreading (-m) | 0.07s | 0.07s | 0.08s | 0.07s
MT+Compression (-m -c) | 0.05s | 0.05s | 0.06s | 0.05s
Sendfile (-f) | 0.04s | 0.04s | 0.04s | 0.04s
Best configuration: MT+Compression (-m -c)
Throughput: <X> MB/s
```
### Step 6: Profiling (If Requested)
For detailed profiling:
```bash
# perf
perf record -g ./build/client [args...]
perf report
# gprof
gcc -pg -o build/client_profile [sources]
./build/client_profile [args]
gprof build/client_profile gmon.out
```
## Rules
- DO build with Release mode for benchmarks
- DO run each config multiple times (at least 3)
- DO clean destination between runs
- DO report median, not just one run
- DON'T run benchmarks during active development (noisy results)
- ALWAYS clean up test data after benchmarking
+138
View File
@@ -0,0 +1,138 @@
---
name: debug-workflow
description: Debugs crashes, memory errors, hangs, and logic bugs in FastSync using structured methodology. Use when the user says "debug X", "fix crash", "investigate failure", "there's a bug", or needs help diagnosing issues.
---
# Debug Workflow Skill
Structured debugging for FastSync: reproduce → isolate → diagnose → fix → verify. This skill CAN edit files, build, and run tests.
## Workflow
### Step 1: Understand the Problem
Ask or gather:
- What's the symptom? (crash, hang, wrong output, valgrind error)
- What command triggers it?
- Is it deterministic or intermittent?
- What's the environment? (OS, compiler, network conditions)
### Step 2: Reproduce
Build with debug info:
```bash
rm -rf build
cmake -B build -S . -DCMAKE_BUILD_TYPE=Debug
cmake --build build -j$(nproc)
```
Try to reproduce the issue with the exact command the user provides.
### Step 3: Isolate with Sanitizers
**Memory errors (first priority):**
```bash
rm -rf build
cmake -B build -S . \
-DCMAKE_C_FLAGS="-fsanitize=address -fno-omit-frame-pointer -g" \
-DCMAKE_EXE_LINKER_FLAGS="-fsanitize=address"
cmake --build build -j$(nproc)
./build/tests
# or run the failing command
```
**Thread errors:**
```bash
rm -rf build
cmake -B build -S . \
-DCMAKE_C_FLAGS="-fsanitize=thread -g" \
-DCMAKE_EXE_LINKER_FLAGS="-fsanitize=thread"
cmake --build build -j$(nproc)
./build/tests
```
**Valgrind (if ASan doesn't find it):**
```bash
valgrind --leak-check=full --show-leak-kinds=all --track-origins=yes \
./build/client --source-dir /tmp/src --dest-dir /tmp/dst --save-to-disk
```
### Step 4: GDB Analysis
If the issue is a crash or hang:
```bash
gdb --args ./build/client [args...]
(gdb) run
# when it crashes:
(gdb) bt full
(gdb) info locals
(gdb) print variable_name
```
For hangs:
```bash
# In another terminal:
kill -SIGABRT <pid> # generates core dump
gdb ./build/client core
(gdb) thread apply all bt
```
### Step 5: Read the Code
Read the relevant source files around the crash/failure point. Look for:
- Unchecked return values
- Null pointer dereferences
- Buffer overflows
- Use-after-free
- Race conditions
- Incorrect protocol handling
### Step 6: Diagnose Root Cause
Identify the exact file:line and what's wrong. Common patterns:
- `send_n_data` / `receive_n_data` return value not checked
- `data_destroy()` called but pointer still used
- Queue operation without mutex in threaded code
- Partial read/write not handled
- Integer overflow in size calculations
### Step 7: Fix
Apply the minimal fix. Don't refactor while debugging — one change at a time.
### Step 8: Verify
```bash
# Rebuild and test
cmake -B build -S . && cmake --build build -j$(nproc)
./build/tests
# If integration test needed
python3 test.py
# Re-run under sanitizer to confirm fix
rm -rf build
cmake -B build -S . -DCMAKE_C_FLAGS="-fsanitize=address -fno-omit-frame-pointer" \
-DCMAKE_EXE_LINKER_FLAGS="-fsanitize=address"
cmake --build build -j$(nproc)
# reproduce the original failing command
```
### Step 9: Report
Print a summary:
```
=== DEBUG SUMMARY ===
Symptom: <what was happening>
Root cause: <file:line — what's wrong>
Fix: <what was changed>
Verification: <how it was confirmed fixed>
```
## Rules
- DO edit source files to fix issues
- DO rebuild and test after fixes
- DON'T refactor while debugging — minimal changes only
- DON'T change behavior beyond fixing the bug
- PRESERVE existing code style
- ALWAYS verify with `./build/tests` after changes
+24
View File
@@ -32,6 +32,28 @@ cmake --build build -j$(nproc) 2>&1
Capture both stdout and stderr.
### Step 2b: Sanitizer build (if issues suspected)
If the PR touches threading, memory management, or network code, also build with sanitizers:
```bash
# AddressSanitizer
rm -rf build-asan
cmake -B build-asan -S . \
-DCMAKE_C_FLAGS="-fsanitize=address -fno-omit-frame-pointer -g" \
-DCMAKE_EXE_LINKER_FLAGS="-fsanitize=address"
cmake --build build-asan -j$(nproc)
./build-asan/tests
# ThreadSanitizer (if threading changes)
rm -rf build-tsan
cmake -B build-tsan -S . \
-DCMAKE_C_FLAGS="-fsanitize=thread -g" \
-DCMAKE_EXE_LINKER_FLAGS="-fsanitize=thread"
cmake --build build-tsan -j$(nproc)
./build-tsan/tests
```
### Step 3: Handle build failures
If the build fails, read the error output carefully. Common issues:
@@ -92,6 +114,8 @@ Print a summary:
Branch: <branch-name>
Build: [PASS/FAIL]
Unit tests: [PASS/FAIL] (<passed>/<total>)
ASan: [CLEAN/ERRORS]
TSan: [CLEAN/ERRORS/SKIPPED]
Integration tests: [PASS/FAIL/SKIPPED]
Fixes applied: <count>
+18 -1
View File
@@ -69,12 +69,29 @@ For each changed file, review for:
- Functions return appropriate error values
- Error messages are useful
**Security**
- No `strcpy`/`strcat`/`sprintf` — use `snprintf` with bounds
- `malloc` size calculations don't overflow
- Path traversal prevention (`..` in filenames)
- No fixed-size stack buffers for unbounded input
- TLS error codes checked after `SSL_read`/`SSL_write`
- No hardcoded certificates, keys, or credentials
- Received file permissions validated (no SUID/SGID injection)
- Denial of service: bounded memory, malformed messages handled
**Performance Impact**
- Unnecessary memory copies in hot paths
- Excessive malloc/free in tight loops
- Missing `sendfile()` opportunity for large files
- Compression level appropriate for use case
- Queue sizing appropriate for workload
### Step 5: Categorize findings
For each issue:
1. **File:line** — exact location
2. **Severity** — critical / warning / style
3. **Category** — memory / thread / protocol / logic / error
3. **Category** — memory / thread / protocol / security / performance / logic / error
4. **Description** — what's wrong and how to fix it
### Step 6: Output report
+81
View File
@@ -0,0 +1,81 @@
---
name: refactor
description: Refactors FastSync code for structural improvements — DRY, separation of concerns, API simplification. Use when the user says "refactor X", "clean up code", "improve structure", or wants to reduce duplication.
---
# Refactor Skill
Read-only analysis + code edits for structural improvements. This skill CAN edit files but MUST verify tests pass.
## Workflow
### Step 1: Identify Refactoring Target
Ask or determine:
- What code needs refactoring?
- What's the problem? (duplication, complexity, wrong abstraction, naming)
- What's the scope? (single function, module, cross-module)
### Step 2: Read and Understand
Read the relevant source files completely. Understand:
- What the code does
- How it fits in the larger system
- What depends on it
- What it depends on
### Step 3: Verify Baseline
Before any changes, confirm tests pass:
```bash
cmake -B build -S . && cmake --build build -j$(nproc)
./build/tests
```
### Step 4: Plan the Refactor
Document the plan:
1. What changes will be made
2. What behavior is preserved
3. What risks exist
4. How to verify correctness
### Step 5: Implement
Make the changes, one logical step at a time. Follow existing code conventions:
- Header guards: `#ifndef FILENAME_H`
- Naming: `snake_case` with module prefix
- `static` for file-local functions
- Pointer style: `Type *name`
- Error handling: return `false`/`NULL` on failure
### Step 6: Build and Test
```bash
cmake -B build -S . && cmake --build build -j$(nproc)
./build/tests
```
ALL tests must pass. If a test fails, investigate and fix.
### Step 7: Report
Print a summary:
```
=== REFACTOR SUMMARY ===
Target: <what was refactored>
Changes:
- <list of changes>
Tests: <passed/total>
Behavior preserved: yes
```
## Rules
- DO edit source files
- DO run tests after changes
- DO follow existing code conventions
- DON'T change observable behavior
- DON'T fix bugs while refactoring (separate concern)
- DON'T add new features during refactoring
- DON'T rewrite from scratch — incremental changes
- ALWAYS verify tests pass before AND after
+110
View File
@@ -0,0 +1,110 @@
---
name: release
description: Prepares a FastSync release — version bump, changelog, build verification, and git tagging. Use when the user says "prepare release", "bump version", "tag release", or wants to cut a new version.
---
# Release Skill
Prepares a new release of FastSync. This skill CAN edit files, commit, and tag.
## Workflow
### Step 1: Determine Version
Ask the user or determine from context:
- **Major** (X.0.0) — breaking protocol changes, incompatible CLI changes
- **Minor** (x.Y.0) — new features, backward compatible
- **Patch** (x.y.Z) — bug fixes, no protocol changes
Current version: `PROTOCOL_VERSION "1.1.0"` in `src/shared/config.h`
### Step 2: Check Protocol Version
If the wire protocol changed, bump `PROTOCOL_VERSION` in `src/shared/config.h`:
```c
#define PROTOCOL_VERSION "1.2.0" // or "2.0.0" for breaking
```
Protocol version changes require:
- Both client and server to be updated together
- Backward compatibility considerations documented
- Migration path clear
### Step 3: Verify Build and Tests
```bash
rm -rf build
cmake -B build -S .
cmake --build build -j$(nproc)
./build/tests
python3 test.py
```
ALL tests must pass before release.
### Step 4: Run Sanitizer Checks
```bash
# ASan
rm -rf build
cmake -B build -S . \
-DCMAKE_C_FLAGS="-fsanitize=address -fno-omit-frame-pointer" \
-DCMAKE_EXE_LINKER_FLAGS="-fsanitize=address"
cmake --build build -j$(nproc)
./build/tests
```
### Step 5: Update README (If Needed)
Check if README needs updates:
- New features documented
- New CLI flags documented
- Benchmark results updated
- Build instructions current
### Step 6: Create Release Commit
```bash
git add -A
git commit -m "Release vX.Y.Z
- <list of changes>
- Protocol version: X.Y.Z
- Tested: unit tests, integration tests, ASan"
```
### Step 7: Tag the Release
```bash
git tag -a vX.Y.Z -m "Release vX.Y.Z"
```
### Step 8: Push
```bash
git push origin main --tags
```
### Step 9: Report
```
=== RELEASE SUMMARY ===
Version: vX.Y.Z
Protocol: X.Y.Z
Commit: <hash>
Tag: vX.Y.Z
Changes:
- <list of changes in this release>
Build: PASS
Tests: PASS (<passed>/<total>)
ASan: CLEAN
```
## Rules
- DO verify all tests pass before release
- DO run sanitizer checks before release
- DO update README if features changed
- DO tag releases with annotated tags
- DON'T release if tests fail
- DON'T skip sanitizer checks
- DON'T change code during release (only version bump + docs)
+115
View File
@@ -0,0 +1,115 @@
---
name: security-audit
description: Performs a security audit of FastSync — checks TLS config, input validation, buffer safety, crypto hygiene, and network attack surface. Use when the user says "security audit", "check security", "harden", or wants a security review.
---
# Security Audit Skill
Read-only security review of the FastSync codebase or specific modules. Produces a report — does NOT edit files.
## Workflow
### Step 1: Scope the Audit
Determine what to audit:
- Full codebase audit
- Specific module (e.g., `transport_tls.c`, `protocol.c`)
- Specific vulnerability class (e.g., buffer overflows, TLS misconfig)
### Step 2: Identify Attack Surface
Network input points:
```
src/server/server.c — TCP accept, per-connection handling
src/shared/protocol.c — all wire protocol parsing
src/shared/config.c — config deserialization
src/shared/chunk.c — chunk deserialization
src/shared/transport_tls.c — TLS handshake and data
src/shared/transport_ssh.c — SSH data via stdio
```
### Step 3: Read All Relevant Files
Read every file in scope completely. Focus on:
- All `receive_*` calls and their validation
- All `malloc`/`calloc` calls and their size calculations
- All string operations (`strcpy`, `sprintf`, `snprintf`)
- All path operations (filename handling, directory creation)
- All TLS/SSL operations and error handling
### Step 4: Apply Security Checklist
#### Input Validation
- [ ] All `receive_*` return values checked
- [ ] Received size fields validated against bounds
- [ ] Path traversal prevention (`..` in filenames)
- [ ] Null bytes in filenames handled
- [ ] Chunk/file counts validated before allocation
#### Buffer Safety
- [ ] No `strcpy` — use `snprintf`
- [ ] `malloc` size calculations don't overflow
- [ ] No fixed-size stack buffers for unbounded input
- [ ] Off-by-one in path concatenation
#### TLS/SSL
- [ ] TLS 1.2 minimum enforced
- [ ] Certificate verification when CA provided
- [ ] SSL error codes checked after `SSL_read`/`SSL_write`
- [ ] No hardcoded certificates/keys
- [ ] Strong cipher suites only
#### Memory Safety in Error Paths
- [ ] All error paths free allocated resources
- [ ] No use-after-free on error paths
- [ ] Partial reads handled
#### Denial of Service
- [ ] Bounded memory allocation
- [ ] Timeout on connections
- [ ] Malformed messages handled gracefully
### Step 5: Check for Common Vulnerabilities
```bash
# Grep for dangerous patterns
grep -rn "strcpy\|strcat\|sprintf" src/
grep -rn "malloc.*\*" src/ # potential integer overflow in size calc
grep -rn "receive_n_data" src/ # check all return values
grep -rn "NULL" src/ | grep -v "//" # check null handling
```
### Step 6: Output Report
```
=== SECURITY AUDIT SUMMARY ===
Scope: <what was audited>
Files reviewed: <count>
Critical: <count>
High: <count>
Medium: <count>
Low: <count>
Informational: <count>
=== FINDINGS ===
[1] <file:line> — CRITICAL (<category>)
Description: <what's wrong>
Exploit scenario: <how it could be triggered>
Fix: <concrete code change>
...
=== VERDICT ===
[PASS] No critical/high issues found
— or —
[FAIL] <N> critical/high issues must be fixed
```
## Rules
- Do NOT edit any source files
- Do NOT run builds or tests
- Report ALL issues — don't filter or minimize
- Be specific about line numbers and fix suggestions
- Consider both remote and local attack vectors