compact-agent 1.10.1 → 1.11.1

package/resources/ecc/commands/kotlin-test.md

@@ -0,0 +1,312 @@
+---
+description: Enforce TDD workflow for Kotlin. Write Kotest tests first, then implement. Verify 80%+ coverage with Kover.
+---
+
+# Kotlin TDD Command
+
+This command enforces test-driven development methodology for Kotlin code using Kotest, MockK, and Kover.
+
+## What This Command Does
+
+1. **Define Types/Interfaces**: Scaffold function signatures first
+2. **Write Kotest Tests**: Create comprehensive test specs (RED)
+3. **Run Tests**: Verify tests fail for the right reason
+4. **Implement Code**: Write minimal code to pass (GREEN)
+5. **Refactor**: Improve while keeping tests green
+6. **Check Coverage**: Ensure 80%+ coverage with Kover
+
+## When to Use
+
+Use `/kotlin-test` when:
+- Implementing new Kotlin functions or classes
+- Adding test coverage to existing Kotlin code
+- Fixing bugs (write failing test first)
+- Building critical business logic
+- Learning TDD workflow in Kotlin
+
+## TDD Cycle
+
+```
+RED     -> Write failing Kotest test
+GREEN   -> Implement minimal code to pass
+REFACTOR -> Improve code, tests stay green
+REPEAT  -> Next test case
+```
+
+## Example Session
+
+````text
+User: /kotlin-test I need a function to validate user registration requests
+
+Agent:
+# TDD Session: Registration Validator
+
+## Step 1: Define Interface
+
+```kotlin
+// validator/RegistrationValidator.kt
+package com.example.validator
+
+data class RegistrationRequest(
+    val name: String,
+    val email: String,
+    val password: String,
+)
+
+sealed class ValidationResult {
+    data object Valid : ValidationResult()
+    data class Invalid(val errors: List<String>) : ValidationResult()
+}
+
+fun validateRegistration(request: RegistrationRequest): ValidationResult {
+    TODO("not implemented")
+}
+```
+
+## Step 2: Write Kotest Tests (RED)
+
+```kotlin
+// validator/RegistrationValidatorTest.kt
+package com.example.validator
+
+import io.kotest.core.spec.style.FunSpec
+import io.kotest.matchers.shouldBe
+import io.kotest.matchers.types.shouldBeInstanceOf
+
+class RegistrationValidatorTest : FunSpec({
+    test("valid registration returns Valid") {
+        val request = RegistrationRequest(
+            name = "Alice",
+            email = "alice@example.com",
+            password = "SecureP@ss1",
+        )
+
+        val result = validateRegistration(request)
+
+        result.shouldBeInstanceOf<ValidationResult.Valid>()
+    }
+
+    test("blank name returns Invalid") {
+        val request = RegistrationRequest(
+            name = "",
+            email = "alice@example.com",
+            password = "SecureP@ss1",
+        )
+
+        val result = validateRegistration(request)
+
+        val invalid = result.shouldBeInstanceOf<ValidationResult.Invalid>()
+        invalid.errors shouldBe listOf("Name is required")
+    }
+
+    test("invalid email returns Invalid") {
+        val request = RegistrationRequest(
+            name = "Alice",
+            email = "not-an-email",
+            password = "SecureP@ss1",
+        )
+
+        val result = validateRegistration(request)
+
+        val invalid = result.shouldBeInstanceOf<ValidationResult.Invalid>()
+        invalid.errors shouldBe listOf("Invalid email format")
+    }
+
+    test("short password returns Invalid") {
+        val request = RegistrationRequest(
+            name = "Alice",
+            email = "alice@example.com",
+            password = "short",
+        )
+
+        val result = validateRegistration(request)
+
+        val invalid = result.shouldBeInstanceOf<ValidationResult.Invalid>()
+        invalid.errors shouldBe listOf("Password must be at least 8 characters")
+    }
+
+    test("multiple errors returns all errors") {
+        val request = RegistrationRequest(
+            name = "",
+            email = "bad",
+            password = "short",
+        )
+
+        val result = validateRegistration(request)
+
+        val invalid = result.shouldBeInstanceOf<ValidationResult.Invalid>()
+        invalid.errors.size shouldBe 3
+    }
+})
+```
+
+## Step 3: Run Tests - Verify FAIL
+
+```bash
+$ ./gradlew test
+
+RegistrationValidatorTest > valid registration returns Valid FAILED
+  kotlin.NotImplementedError: An operation is not implemented
+
+FAILED (5 tests, 0 passed, 5 failed)
+```
+
+✓ Tests fail as expected (NotImplementedError).
+
+## Step 4: Implement Minimal Code (GREEN)
+
+```kotlin
+// validator/RegistrationValidator.kt
+package com.example.validator
+
+private val EMAIL_REGEX = Regex("^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.[A-Za-z]{2,}$")
+private const val MIN_PASSWORD_LENGTH = 8
+
+fun validateRegistration(request: RegistrationRequest): ValidationResult {
+    val errors = buildList {
+        if (request.name.isBlank()) add("Name is required")
+        if (!EMAIL_REGEX.matches(request.email)) add("Invalid email format")
+        if (request.password.length < MIN_PASSWORD_LENGTH) add("Password must be at least $MIN_PASSWORD_LENGTH characters")
+    }
+
+    return if (errors.isEmpty()) ValidationResult.Valid
+    else ValidationResult.Invalid(errors)
+}
+```
+
+## Step 5: Run Tests - Verify PASS
+
+```bash
+$ ./gradlew test
+
+RegistrationValidatorTest > valid registration returns Valid PASSED
+RegistrationValidatorTest > blank name returns Invalid PASSED
+RegistrationValidatorTest > invalid email returns Invalid PASSED
+RegistrationValidatorTest > short password returns Invalid PASSED
+RegistrationValidatorTest > multiple errors returns all errors PASSED
+
+PASSED (5 tests, 5 passed, 0 failed)
+```
+
+✓ All tests passing!
+
+## Step 6: Check Coverage
+
+```bash
+$ ./gradlew koverHtmlReport
+
+Coverage: 100.0% of statements
+```
+
+✓ Coverage: 100%
+
+## TDD Complete!
+````
+
+## Test Patterns
+
+### StringSpec (Simplest)
+
+```kotlin
+class CalculatorTest : StringSpec({
+    "add two positive numbers" {
+        Calculator.add(2, 3) shouldBe 5
+    }
+})
+```
+
+### BehaviorSpec (BDD)
+
+```kotlin
+class OrderServiceTest : BehaviorSpec({
+    Given("a valid order") {
+        When("placed") {
+            Then("should be confirmed") { /* ... */ }
+        }
+    }
+})
+```
+
+### Data-Driven Tests
+
+```kotlin
+class ParserTest : FunSpec({
+    context("valid inputs") {
+        withData("2026-01-15", "2026-12-31", "2000-01-01") { input ->
+            parseDate(input).shouldNotBeNull()
+        }
+    }
+})
+```
+
+### Coroutine Testing
+
+```kotlin
+class AsyncServiceTest : FunSpec({
+    test("concurrent fetch completes") {
+        runTest {
+            val result = service.fetchAll()
+            result.shouldNotBeEmpty()
+        }
+    }
+})
+```
+
+## Coverage Commands
+
+```bash
+# Run tests with coverage
+./gradlew koverHtmlReport
+
+# Verify coverage thresholds
+./gradlew koverVerify
+
+# XML report for CI
+./gradlew koverXmlReport
+
+# Open HTML report
+open build/reports/kover/html/index.html
+
+# Run specific test class
+./gradlew test --tests "com.example.UserServiceTest"
+
+# Run with verbose output
+./gradlew test --info
+```
+
+## Coverage Targets
+
+| Code Type | Target |
+|-----------|--------|
+| Critical business logic | 100% |
+| Public APIs | 90%+ |
+| General code | 80%+ |
+| Generated code | Exclude |
+
+## TDD Best Practices
+
+**DO:**
+- Write test FIRST, before any implementation
+- Run tests after each change
+- Use Kotest matchers for expressive assertions
+- Use MockK's `coEvery`/`coVerify` for suspend functions
+- Test behavior, not implementation details
+- Include edge cases (empty, null, max values)
+
+**DON'T:**
+- Write implementation before tests
+- Skip the RED phase
+- Test private functions directly
+- Use `Thread.sleep()` in coroutine tests
+- Ignore flaky tests
+
+## Related Commands
+
+- `/kotlin-build` - Fix build errors
+- `/kotlin-review` - Review code after implementation
+- `verification-loop` skill - Run full verification loop
+
+## Related
+
+- Skill: `skills/kotlin-testing/`
+- Skill: `skills/tdd-workflow/`

package/resources/ecc/commands/learn-eval.md

@@ -0,0 +1,116 @@
+---
+description: "Extract reusable patterns from the session, self-evaluate quality before saving, and determine the right save location (Global vs Project)."
+---
+
+# /learn-eval - Extract, Evaluate, then Save
+
+Extends `/learn` with a quality gate, save-location decision, and knowledge-placement awareness before writing any skill file.
+
+## What to Extract
+
+Look for:
+
+1. **Error Resolution Patterns** — root cause + fix + reusability
+2. **Debugging Techniques** — non-obvious steps, tool combinations
+3. **Workarounds** — library quirks, API limitations, version-specific fixes
+4. **Project-Specific Patterns** — conventions, architecture decisions, integration patterns
+
+## Process
+
+1. Review the session for extractable patterns
+2. Identify the most valuable/reusable insight
+
+3. **Determine save location:**
+   - Ask: "Would this pattern be useful in a different project?"
+   - **Global** (`~/.claude/skills/learned/`): Generic patterns usable across 2+ projects (bash compatibility, LLM API behavior, debugging techniques, etc.)
+   - **Project** (`.claude/skills/learned/` in current project): Project-specific knowledge (quirks of a particular config file, project-specific architecture decisions, etc.)
+   - When in doubt, choose Global (moving Global → Project is easier than the reverse)
+
+4. Draft the skill file using this format:
+
+```markdown
+---
+name: pattern-name
+description: "Under 130 characters"
+user-invocable: false
+origin: auto-extracted
+---
+
+# [Descriptive Pattern Name]
+
+**Extracted:** [Date]
+**Context:** [Brief description of when this applies]
+
+## Problem
+[What problem this solves - be specific]
+
+## Solution
+[The pattern/technique/workaround - with code examples]
+
+## When to Use
+[Trigger conditions]
+```
+
+5. **Quality gate — Checklist + Holistic verdict**
+
+   ### 5a. Required checklist (verify by actually reading files)
+
+   Execute **all** of the following before evaluating the draft:
+
+   - [ ] Grep `~/.claude/skills/` and relevant project `.claude/skills/` files by keyword to check for content overlap
+   - [ ] Check MEMORY.md (both project and global) for overlap
+   - [ ] Consider whether appending to an existing skill would suffice
+   - [ ] Confirm this is a reusable pattern, not a one-off fix
+
+   ### 5b. Holistic verdict
+
+   Synthesize the checklist results and draft quality, then choose **one** of the following:
+
+   | Verdict | Meaning | Next Action |
+   |---------|---------|-------------|
+   | **Save** | Unique, specific, well-scoped | Proceed to Step 6 |
+   | **Improve then Save** | Valuable but needs refinement | List improvements → revise → re-evaluate (once) |
+   | **Absorb into [X]** | Should be appended to an existing skill | Show target skill and additions → Step 6 |
+   | **Drop** | Trivial, redundant, or too abstract | Explain reasoning and stop |
+
+**Guideline dimensions** (informing the verdict, not scored):
+
+- **Specificity & Actionability**: Contains code examples or commands that are immediately usable
+- **Scope Fit**: Name, trigger conditions, and content are aligned and focused on a single pattern
+- **Uniqueness**: Provides value not covered by existing skills (informed by checklist results)
+- **Reusability**: Realistic trigger scenarios exist in future sessions
+
+6. **Verdict-specific confirmation flow**
+
+- **Improve then Save**: Present the required improvements + revised draft + updated checklist/verdict after one re-evaluation; if the revised verdict is **Save**, save after user confirmation, otherwise follow the new verdict
+- **Save**: Present save path + checklist results + 1-line verdict rationale + full draft → save after user confirmation
+- **Absorb into [X]**: Present target path + additions (diff format) + checklist results + verdict rationale → append after user confirmation
+- **Drop**: Show checklist results + reasoning only (no confirmation needed)
+
+7. Save / Absorb to the determined location
+
+## Output Format for Step 5
+
+```
+### Checklist
+- [x] skills/ grep: no overlap (or: overlap found → details)
+- [x] MEMORY.md: no overlap (or: overlap found → details)
+- [x] Existing skill append: new file appropriate (or: should append to [X])
+- [x] Reusability: confirmed (or: one-off → Drop)
+
+### Verdict: Save / Improve then Save / Absorb into [X] / Drop
+
+**Rationale:** (1-2 sentences explaining the verdict)
+```
+
+## Design Rationale
+
+This version replaces the previous 5-dimension numeric scoring rubric (Specificity, Actionability, Scope Fit, Non-redundancy, Coverage scored 1-5) with a checklist-based holistic verdict system. Modern frontier models (Opus 4.6+) have strong contextual judgment — forcing rich qualitative signals into numeric scores loses nuance and can produce misleading totals. The holistic approach lets the model weigh all factors naturally, producing more accurate save/drop decisions while the explicit checklist ensures no critical check is skipped.
+
+## Notes
+
+- Don't extract trivial fixes (typos, simple syntax errors)
+- Don't extract one-time issues (specific API outages, etc.)
+- Focus on patterns that will save time in future sessions
+- Keep skills focused — one pattern per skill
+- When the verdict is Absorb, append to the existing skill rather than creating a new file

package/resources/ecc/commands/learn.md

@@ -0,0 +1,74 @@
+---
+description: Extract reusable patterns from the current session and save them as candidate skills or guidance.
+---
+
+# /learn - Extract Reusable Patterns
+
+Analyze the current session and extract any patterns worth saving as skills.
+
+## Trigger
+
+Run `/learn` at any point during a session when you've solved a non-trivial problem.
+
+## What to Extract
+
+Look for:
+
+1. **Error Resolution Patterns**
+   - What error occurred?
+   - What was the root cause?
+   - What fixed it?
+   - Is this reusable for similar errors?
+
+2. **Debugging Techniques**
+   - Non-obvious debugging steps
+   - Tool combinations that worked
+   - Diagnostic patterns
+
+3. **Workarounds**
+   - Library quirks
+   - API limitations
+   - Version-specific fixes
+
+4. **Project-Specific Patterns**
+   - Codebase conventions discovered
+   - Architecture decisions made
+   - Integration patterns
+
+## Output Format
+
+Create a skill file at `~/.claude/skills/learned/[pattern-name].md`:
+
+```markdown
+# [Descriptive Pattern Name]
+
+**Extracted:** [Date]
+**Context:** [Brief description of when this applies]
+
+## Problem
+[What problem this solves - be specific]
+
+## Solution
+[The pattern/technique/workaround]
+
+## Example
+[Code example if applicable]
+
+## When to Use
+[Trigger conditions - what should activate this skill]
+```
+
+## Process
+
+1. Review the session for extractable patterns
+2. Identify the most valuable/reusable insight
+3. Draft the skill file
+4. Ask user to confirm before saving
+5. Save to `~/.claude/skills/learned/`
+
+## Notes
+
+- Don't extract trivial fixes (typos, simple syntax errors)
+- Don't extract one-time issues (specific API outages, etc.)
+- Focus on patterns that will save time in future sessions
+- Keep skills focused - one pattern per skill

package/resources/ecc/commands/loop-start.md

@@ -0,0 +1,36 @@
+---
+description: Start a managed autonomous loop pattern with safety defaults and explicit stop conditions.
+---
+
+# Loop Start Command
+
+Start a managed autonomous loop pattern with safety defaults.
+
+## Usage
+
+`/loop-start [pattern] [--mode safe|fast]`
+
+- `pattern`: `sequential`, `continuous-pr`, `rfc-dag`, `infinite`
+- `--mode`:
+  - `safe` (default): strict quality gates and checkpoints
+  - `fast`: reduced gates for speed
+
+## Flow
+
+1. Confirm repository state and branch strategy.
+2. Select loop pattern and model tier strategy.
+3. Enable required hooks/profile for the chosen mode.
+4. Create loop plan and write runbook under `.claude/plans/`.
+5. Print commands to start and monitor the loop.
+
+## Required Safety Checks
+
+- Verify tests pass before first loop iteration.
+- Ensure `ECC_HOOK_PROFILE` is not disabled globally.
+- Ensure loop has explicit stop condition.
+
+## Arguments
+
+$ARGUMENTS:
+- `<pattern>` optional (`sequential|continuous-pr|rfc-dag|infinite`)
+- `--mode safe|fast` optional

package/resources/ecc/commands/loop-status.md

@@ -0,0 +1,77 @@
+---
+description: Inspect active loop state, progress, failure signals, and recommended intervention.
+---
+
+# Loop Status Command
+
+Inspect active loop state, progress, and failure signals.
+
+This slash command can only run after the current session dequeues it. If you
+need to inspect a wedged or sibling session, run the packaged CLI from another
+terminal:
+
+```bash
+npx --package ecc-universal ecc loop-status --json
+```
+
+The CLI scans local Claude transcript JSONL files under
+`~/.claude/projects/**` and reports stale `ScheduleWakeup` calls or `Bash`
+tool calls that have no matching `tool_result`.
+
+## Usage
+
+`/loop-status [--watch]`
+
+## What to Report
+
+- active loop pattern
+- current phase and last successful checkpoint
+- failing checks (if any)
+- estimated time/cost drift
+- recommended intervention (continue/pause/stop)
+
+## Cross-Session CLI
+
+- `ecc loop-status --json` emits machine-readable status for recent local
+  Claude transcripts.
+- `ecc loop-status --home <dir>` scans a different home directory when
+  inspecting another local profile or mounted workspace.
+- `ecc loop-status --transcript <session.jsonl>` inspects one transcript
+  directly.
+- `ecc loop-status --bash-timeout-seconds 1800` adjusts the stale Bash
+  threshold.
+- `ecc loop-status --exit-code` exits `2` when stale loop or tool signals are
+  found, or `1` when transcripts cannot be scanned.
+- `--exit-code` with `--watch` requires `--watch-count` so watchdog scripts do
+  not wait forever for a process exit.
+- `ecc loop-status --watch` refreshes status until interrupted.
+- `ecc loop-status --watch --watch-count 3 --exit-code` refreshes a bounded
+  number of times, then exits with the highest status seen.
+- `ecc loop-status --watch --watch-count 3` emits a bounded watch stream for
+  scripts and handoffs.
+- `ecc loop-status --watch --write-dir ~/.claude/loops` maintains
+  `index.json` and per-session JSON snapshots for sibling terminals or
+  watchdog scripts.
+
+## Watch Mode
+
+When `--watch` is present, refresh status periodically. With `--json`, each
+refresh is emitted as one JSON object per line so another terminal or script can
+consume the stream.
+
+## Snapshot Files
+
+Use `--write-dir <dir>` when a separate process needs to inspect loop state
+without waiting for the current Claude session to dequeue `/loop-status`. The
+CLI writes:
+
+- `index.json` with one row per inspected session.
+- `<session-id>.json` with the full status payload for that session.
+
+These files are snapshots of local transcript analysis. They do not control or
+timeout Claude Code runtime tool calls.
+
+## Arguments
+
+$ARGUMENTS:
+- `--watch` optional

package/resources/ecc/commands/model-route.md

@@ -0,0 +1,30 @@
+---
+description: Recommend the best model tier for the current task based on complexity, risk, and budget.
+---
+
+# Model Route Command
+
+Recommend the best model tier for the current task by complexity and budget.
+
+## Usage
+
+`/model-route [task-description] [--budget low|med|high]`
+
+## Routing Heuristic
+
+- `haiku`: deterministic, low-risk mechanical changes
+- `sonnet`: default for implementation and refactors
+- `opus`: architecture, deep review, ambiguous requirements
+
+## Required Output
+
+- recommended model
+- confidence level
+- why this model fits
+- fallback model if first attempt fails
+
+## Arguments
+
+$ARGUMENTS:
+- `[task-description]` optional free-text
+- `--budget low|med|high` optional