@jmylchreest/aide-plugin 0.0.38 → 0.0.40

package/skills/swarm/SKILL.md

@@ -432,43 +432,90 @@ message_ack: message_id=42, agent_id="agent-auth"
 ./.aide/bin/aide memory add --category=discovery "User model needs email validation"
 ```
 
-**Memory** (shared discoveries):
+## OpenCode Mode
 
-```bash
-./.aide/bin/aide memory add --category=discovery "User model needs email validation"
-```
+OpenCode has native `todowrite`/`todoread` for per-agent progress tracking, and a `task` tool for spawning subagents. However, OpenCode's todos are **session-private** — they are NOT shared across agents. For multi-agent coordination, use **aide tasks** (MCP tools) as the shared task system.
 
-## OpenCode Mode
+### Task System Roles (OpenCode)
 
-OpenCode does not have native subagent support. For multi-agent swarms with OpenCode:
+| System                                                                          | Role                                                | Scope                      |
+| ------------------------------------------------------------------------------- | --------------------------------------------------- | -------------------------- |
+| **aide tasks** (MCP: `task_create`, `task_list`, `task_claim`, `task_complete`) | Shared coordination — all agents see the same board | Cross-session, persistent  |
+| **todowrite** (native)                                                          | Personal progress tracking within each agent        | Session-private, per-agent |
+| **aide messages** (MCP: `message_send`, `message_list`)                         | Real-time coordination, status broadcasts, blockers | Cross-session              |
 
-**Setup:**
+### Setup
 
 1. Create worktrees as normal (one per story)
 2. Launch separate OpenCode terminal sessions, one per story
 3. Each session works in its assigned worktree directory
 
-**Coordination:**
+### Orchestrator Workflow
 
-- **No TaskList** — OpenCode sessions don't share a task system
-- **Use aide messages** as the primary coordination mechanism:
-  - Each session uses `message_send` to report status, blockers, and completion
-  - Check `message_list` at each stage transition
-  - The orchestrator monitors all agents via `message_list` with their own agent_id
-- **Use aide state** for progress tracking:
-  ```bash
-  ./.aide/bin/aide state set "agent-auth:stage" "TEST"
-  ./.aide/bin/aide state set "agent-auth:status" "running"
-  ```
-- Monitor all agents: `mcp__plugin_aide_aide__state_list`
-
-**Orchestrator role (human or primary session):**
+The orchestrator (human or primary session):
 
 1. Decompose stories (use `/aide:plan-swarm` first)
 2. Create worktrees
-3. Launch terminal sessions with instructions
-4. Monitor via `message_list` and `state_list`
-5. When all sessions report `completion`, run `/aide:worktree-resolve`
+3. Create aide tasks for all SDLC stages upfront:
+   ```
+   task_create: title="[story-auth][DESIGN] Design auth module"
+   task_create: title="[story-auth][TEST] Write auth tests"
+   task_create: title="[story-auth][DEV] Implement auth"
+   task_create: title="[story-auth][VERIFY] Verify auth"
+   task_create: title="[story-auth][DOCS] Document auth"
+   ```
+4. Launch terminal sessions with instructions (include agent ID and story assignment)
+5. Monitor progress via `task_list` (MCP tool) or `./.aide/bin/aide task list` (CLI)
+6. When all tasks show `done`, run `/aide:worktree-resolve`
+
+### Story Agent Workflow (OpenCode)
+
+Each story agent follows the same SDLC pipeline. Use aide tasks for shared tracking and native `todowrite` for personal step-by-step progress:
+
+```
+## Per SDLC Stage:
+
+1. Claim the stage task:
+   task_claim: task_id=<id>, agent_id=agent-auth
+
+2. Use todowrite for personal tracking:
+   todowrite: [{"content": "Design interfaces for auth", "status": "in_progress", "priority": "high"}]
+
+3. Execute the stage (use appropriate /aide: skill)
+
+4. Complete the aide task:
+   task_complete: task_id=<id>, result="Designed JWT auth with refresh tokens"
+
+5. Send status message:
+   message_send: from="agent-auth", type="status", content="[DESIGN] complete"
+
+6. Check for messages from other agents:
+   message_list: agent_id="agent-auth"
+```
+
+**Note:** aide tasks do not have `blockedBy` dependency chaining like Claude Code native tasks. Stage ordering is enforced by the SDLC pipeline instructions — each agent processes stages sequentially (DESIGN → TEST → DEV → VERIFY → DOCS).
+
+### Coordination (OpenCode)
+
+```
+# Shared task board — all agents see the same tasks
+task_list                                          # View all tasks
+task_list: status="pending"                        # View unclaimed work
+
+# Messages — real-time coordination
+message_send: from="agent-auth", type="status", content="[DESIGN] complete, starting TEST"
+message_send: from="agent-auth", to="agent-payments", type="request", content="Need payment API schema"
+message_list: agent_id="agent-auth"
+message_ack: message_id=42, agent_id="agent-auth"
+
+# State — supplementary progress tracking
+./.aide/bin/aide state set "agent-auth:stage" "TEST"
+
+# Decisions and discoveries — shared knowledge
+mcp__plugin_aide_aide__decision_get with topic="auth-strategy"
+./.aide/bin/aide decision set "auth-strategy" "JWT with refresh tokens"
+./.aide/bin/aide memory add --category=discovery "User model needs email validation"
+```
 
 ## Completion (MANDATORY STEPS)
 
@@ -477,7 +524,11 @@ Swarm completion checklist - ALL REQUIRED:
 ### Step 1: Verify All Stories Complete
 
 ```
+# Claude Code:
 TaskList  # All story tasks must show [completed]
+
+# OpenCode:
+task_list  # All aide tasks must show [done]
 ```
 
 - Every story must have completed all 5 SDLC stages

package/skills/test/SKILL.md

@@ -17,6 +17,7 @@ Write comprehensive tests and run test suites.
 ## Prerequisites
 
 Before starting:
+
 - Identify the code to be tested (function, module, feature)
 - Understand the testing framework used in the project
 
@@ -27,6 +28,7 @@ Before starting:
 Use the `mcp__plugin_aide_aide__decision_get` tool with topic `testing` to check for testing framework decisions.
 
 Common frameworks by language:
+
 - **TypeScript/JavaScript:** Vitest, Jest, Mocha
 - **Go:** built-in `go test`
 - **Python:** pytest, unittest
@@ -34,13 +36,18 @@ Common frameworks by language:
 ### Step 2: Discover Existing Test Patterns
 
 Use `Glob` to find test files:
+
 - Pattern: `**/*.test.ts`, `**/*.spec.ts` (TypeScript)
 - Pattern: `**/*_test.go` (Go)
 - Pattern: `**/test_*.py`, `**/*_test.py` (Python)
 
-Use `mcp__plugin_aide_aide__code_search` with query `describe` and `it` to find test patterns.
+Use **Grep** to find test patterns in existing test files:
+
+- `Grep pattern="describe\(" include="*.test.*"` — find test suites
+- `Grep pattern="it\(|test\(" include="*.test.*"` — find test cases
 
 Read an existing test file to understand:
+
 - Import patterns
 - Setup/teardown patterns
 - Mocking approach
@@ -52,6 +59,7 @@ Use `mcp__plugin_aide_aide__code_symbols` with the target file path to get funct
 Use `mcp__plugin_aide_aide__code_search` to find related types.
 
 Identify:
+
 - Input parameters and types
 - Return type
 - Side effects
@@ -63,12 +71,14 @@ Identify:
 Follow the project's testing conventions. Cover these scenarios:
 
 **Test Categories:**
+
 1. **Happy path** - Normal, expected inputs
 2. **Edge cases** - Empty, null, boundary values
 3. **Error cases** - Invalid inputs, expected failures
 4. **Async behavior** - If applicable
 
 **Naming convention:**
+
 - Descriptive names that explain what is being tested
 - Format: "should [expected behavior] when [condition]"
 
@@ -103,51 +113,52 @@ go tool cover -html=coverage.out
 ```
 
 **Coverage targets:**
+
 - New code: aim for >80%
 - Critical paths: aim for >90%
 - Focus on meaningful tests, not just coverage numbers
 
 ## Failure Handling
 
-| Failure | Action |
-|---------|--------|
-| Test imports fail | Check path aliases, ensure test config matches main |
-| Mock not working | Verify mock setup, check dependency injection |
-| Async test timeout | Add proper await, increase timeout if needed |
-| Flaky test | Check for shared state, timing issues, or external deps |
-| Coverage too low | Add edge case tests, error path tests |
+| Failure            | Action                                                  |
+| ------------------ | ------------------------------------------------------- |
+| Test imports fail  | Check path aliases, ensure test config matches main     |
+| Mock not working   | Verify mock setup, check dependency injection           |
+| Async test timeout | Add proper await, increase timeout if needed            |
+| Flaky test         | Check for shared state, timing issues, or external deps |
+| Coverage too low   | Add edge case tests, error path tests                   |
 
 ## Test Structure Templates
 
 ### TypeScript/JavaScript (Vitest/Jest)
 
 ```typescript
-import { describe, it, expect, beforeEach, vi } from 'vitest';
-import { functionToTest } from './module';
+import { describe, it, expect, beforeEach, vi } from "vitest";
+import { functionToTest } from "./module";
 
-describe('functionToTest', () => {
+describe("functionToTest", () => {
   beforeEach(() => {
     // Reset state before each test
     vi.clearAllMocks();
   });
 
-  it('should return expected result for valid input', () => {
-    const result = functionToTest('valid input');
-    expect(result).toBe('expected output');
+  it("should return expected result for valid input", () => {
+    const result = functionToTest("valid input");
+    expect(result).toBe("expected output");
   });
 
-  it('should handle empty input', () => {
-    const result = functionToTest('');
-    expect(result).toBe('');
+  it("should handle empty input", () => {
+    const result = functionToTest("");
+    expect(result).toBe("");
   });
 
-  it('should throw error for null input', () => {
-    expect(() => functionToTest(null)).toThrow('Input required');
+  it("should throw error for null input", () => {
+    expect(() => functionToTest(null)).toThrow("Input required");
   });
 
-  it('should handle async operation', async () => {
-    const result = await functionToTest('async input');
-    expect(result).resolves.toBe('async output');
+  it("should handle async operation", async () => {
+    const result = await functionToTest("async input");
+    expect(result).resolves.toBe("async output");
   });
 });
 ```
@@ -213,6 +224,7 @@ class TestFunctionToTest:
 ## Verification Criteria
 
 Before completing:
+
 - [ ] All new tests pass
 - [ ] Existing tests still pass
 - [ ] Coverage meets project standards
@@ -225,9 +237,11 @@ Before completing:
 ## Tests Added
 
 ### Files
+
 - `path/to/file.test.ts` - 5 tests for UserService
 
 ### Test Cases
+
 1. should create user with valid data
 2. should reject duplicate email
 3. should hash password before saving
@@ -235,10 +249,12 @@ Before completing:
 5. should validate email format
 
 ### Coverage
+
 - New code: 92%
 - Total project: 84%
 
 ### Verification
+
 - All tests: PASS
 - No flaky tests observed
 ```

package/src/core/context-guard.ts

@@ -0,0 +1,214 @@
+/**
+ * Context Guard — platform-agnostic core logic.
+ *
+ * Monitors Read tool calls and advises agents to use code_outline
+ * before reading large files. This preserves context window for
+ * the actual task by avoiding dumping entire files into conversation.
+ *
+ * Behaviour:
+ *   - Triggers on Read tool calls for files > 5KB (~150 lines)
+ *   - Tracks which files have been outlined (code_outline/code_symbols)
+ *   - Returns an advisory message (never blocks)
+ *   - Also tracks code_outline/code_symbols calls to mark files as "known"
+ *
+ * Used by both Claude Code hooks (PreToolUse) and OpenCode plugin.
+ */
+
+import { statSync, readFileSync, writeFileSync, existsSync } from "fs";
+import { resolve, isAbsolute, normalize } from "path";
+import { tmpdir } from "os";
+import { join } from "path";
+import { debug } from "../lib/logger.js";
+
+const SOURCE = "context-guard";
+
+/** Default size threshold in bytes (~150 lines) */
+const DEFAULT_SIZE_THRESHOLD = 5120;
+
+/** File extensions that are typically not source code (skip advisory) */
+const SKIP_EXTENSIONS = new Set([
+  ".json",
+  ".lock",
+  ".sum",
+  ".mod",
+  ".yaml",
+  ".yml",
+  ".toml",
+  ".env",
+  ".md",
+  ".txt",
+  ".csv",
+  ".svg",
+  ".png",
+  ".jpg",
+  ".gif",
+  ".ico",
+  ".woff",
+  ".woff2",
+  ".ttf",
+  ".eot",
+]);
+
+export interface ContextGuardResult {
+  /** Whether to inject an advisory message */
+  shouldAdvise: boolean;
+  /** Advisory message to inject */
+  advisory?: string;
+  /** Whether this call should be tracked (code_outline/code_symbols) */
+  tracked?: boolean;
+}
+
+/**
+ * Get the path to the tracking file for this session.
+ */
+function getTrackingPath(sessionId: string): string {
+  return join(tmpdir(), `aide-context-guard-${sessionId}.json`);
+}
+
+/**
+ * Load the set of files that have been outlined in this session.
+ */
+function loadOutlinedFiles(sessionId: string): Set<string> {
+  const trackingPath = getTrackingPath(sessionId);
+  try {
+    if (existsSync(trackingPath)) {
+      const data = JSON.parse(readFileSync(trackingPath, "utf-8"));
+      return new Set(data.files || []);
+    }
+  } catch {
+    // Corrupted file, start fresh
+  }
+  return new Set();
+}
+
+/**
+ * Save a file as "outlined" in the tracking file.
+ */
+function trackOutlinedFile(sessionId: string, filePath: string): void {
+  const files = loadOutlinedFiles(sessionId);
+  files.add(filePath);
+  const trackingPath = getTrackingPath(sessionId);
+  try {
+    writeFileSync(
+      trackingPath,
+      JSON.stringify({ files: Array.from(files) }),
+      "utf-8",
+    );
+  } catch (err) {
+    debug(SOURCE, `Failed to write tracking file: ${err}`);
+  }
+}
+
+/**
+ * Estimate line count from file size (rough: ~35 bytes per line average).
+ */
+function estimateLines(sizeBytes: number): number {
+  return Math.round(sizeBytes / 35);
+}
+
+/**
+ * Check whether a Read call should receive a context-efficiency advisory.
+ *
+ * Also handles tracking code_outline/code_symbols calls.
+ */
+export function checkContextGuard(
+  toolName: string,
+  toolInput: Record<string, unknown>,
+  cwd: string,
+  sessionId: string,
+): ContextGuardResult {
+  const normalizedTool = toolName.toLowerCase();
+
+  // Track code_outline and code_symbols calls
+  if (
+    normalizedTool.includes("code_outline") ||
+    normalizedTool.includes("code_symbols")
+  ) {
+    const filePath =
+      (toolInput.file as string) ||
+      (toolInput.filePath as string) ||
+      (toolInput.file_path as string);
+    if (filePath && sessionId) {
+      const resolved = normalize(
+        isAbsolute(filePath) ? filePath : resolve(cwd, filePath),
+      );
+      trackOutlinedFile(sessionId, resolved);
+      debug(SOURCE, `Tracked outline for: ${filePath}`);
+    }
+    return { shouldAdvise: false, tracked: true };
+  }
+
+  // Only advise on Read tool calls
+  if (normalizedTool !== "read") {
+    return { shouldAdvise: false };
+  }
+
+  // Extract file path from tool input
+  const filePath =
+    (toolInput.filePath as string) ||
+    (toolInput.file_path as string) ||
+    (toolInput.path as string);
+
+  if (!filePath) {
+    return { shouldAdvise: false };
+  }
+
+  // Resolve to absolute path
+  const resolvedPath = normalize(
+    isAbsolute(filePath) ? filePath : resolve(cwd, filePath),
+  );
+
+  // Skip non-source-code files
+  const ext = filePath.substring(filePath.lastIndexOf(".")).toLowerCase();
+  if (SKIP_EXTENSIONS.has(ext)) {
+    return { shouldAdvise: false };
+  }
+
+  // Check if the agent is already using offset/limit (targeted read)
+  const offset = toolInput.offset as number | undefined;
+  const limit = toolInput.limit as number | undefined;
+  if (offset !== undefined && offset > 1) {
+    // Agent is doing a targeted read — no advisory needed
+    return { shouldAdvise: false };
+  }
+  if (limit !== undefined && limit < 100) {
+    // Agent is limiting the read — no advisory needed
+    return { shouldAdvise: false };
+  }
+
+  // Check file size
+  let fileSize: number;
+  try {
+    const stat = statSync(resolvedPath);
+    fileSize = stat.size;
+  } catch {
+    // Can't stat file — don't advise (file might not exist yet)
+    return { shouldAdvise: false };
+  }
+
+  // Skip small files
+  if (fileSize < DEFAULT_SIZE_THRESHOLD) {
+    return { shouldAdvise: false };
+  }
+
+  // Check if this file has already been outlined in this session
+  if (sessionId) {
+    const outlinedFiles = loadOutlinedFiles(sessionId);
+    if (outlinedFiles.has(resolvedPath)) {
+      debug(SOURCE, `File already outlined, skipping advisory: ${filePath}`);
+      return { shouldAdvise: false };
+    }
+  }
+
+  // Generate advisory
+  const estLines = estimateLines(fileSize);
+  const sizeKB = (fileSize / 1024).toFixed(1);
+
+  const advisory =
+    `[aide:context] This file is ~${estLines} lines (${sizeKB}KB). Consider using \`code_outline\` ` +
+    `first to see its structure, then \`Read\` with offset/limit for specific sections. ` +
+    `This preserves your context window for the full task.`;
+
+  debug(SOURCE, `Advisory for ${filePath}: ${estLines} lines, ${sizeKB}KB`);
+  return { shouldAdvise: true, advisory };
+}

package/src/core/persistence-logic.ts

@@ -74,17 +74,23 @@ export function buildReinforcement(
  * Returns null if stop is allowed, or { reason } if stop should be blocked.
  * When a persistence mode is active and todos exist, the reinforcement
  * message includes the specific incomplete tasks.
+ *
+ * When agentId is provided, only tasks claimed by that agent are considered
+ * for blocking. This prevents subagents from being blocked by tasks that
+ * belong to other agents. Global (unclaimed) tasks still count for all agents.
  */
 export function checkPersistence(
   binary: string,
   cwd: string,
+  agentId?: string,
 ): { reason: string } | null {
   const mode = getActiveMode(binary, cwd);
   if (!mode) return null;
 
-  // Get and increment iteration counter
+  // Get and increment iteration counter (guard against NaN from corrupted state)
   const iterStr = getState(binary, cwd, `${mode}_iterations`) || "0";
-  const iteration = parseInt(iterStr, 10) + 1;
+  const parsed = parseInt(iterStr, 10);
+  const iteration = (Number.isNaN(parsed) ? 0 : parsed) + 1;
   setState(binary, cwd, `${mode}_iterations`, String(iteration));
 
   if (iteration > MAX_PERSISTENCE_ITERATIONS) {
@@ -94,21 +100,37 @@ export function checkPersistence(
     return null;
   }
 
-  // Fetch todos and build a specific continuation message if incomplete tasks exist
+  // Fetch todos and build a specific continuation message if incomplete tasks exist.
+  // If all tasks are complete (or no tasks exist), auto-release: allow stop.
   let todoSummary: string | undefined;
+  let allTasksComplete = false;
   try {
     const todos = fetchTodosFromAide(binary, cwd);
-    const todoResult = checkTodos(todos);
+    const todoResult = checkTodos(todos, agentId);
     if (todoResult.hasIncomplete) {
       todoSummary = todoResult.message;
       debug(
         SOURCE,
         `Found ${todoResult.incompleteCount} incomplete todos for persistence reinforcement`,
       );
+    } else if (todoResult.totalCount > 0) {
+      // All tasks exist and are in terminal states — work is done
+      allTasksComplete = true;
+      debug(
+        SOURCE,
+        `All ${todoResult.totalCount} tasks complete — auto-releasing ${mode} mode`,
+      );
     }
   } catch (err) {
     debug(SOURCE, `Failed to fetch todos for persistence (non-fatal): ${err}`);
   }
 
+  // Auto-release: if tasks exist and all are complete, allow stop
+  if (allTasksComplete) {
+    setState(binary, cwd, "mode", "");
+    setState(binary, cwd, `${mode}_iterations`, "0");
+    return null;
+  }
+
   return { reason: buildReinforcement(mode, iteration, todoSummary) };
 }