plcode-windows-x64 2.1.0

package/.plcode/context/openagents-repo/lookup/subagent-framework-maps.md

@@ -0,0 +1,79 @@
+# Lookup: Subagent Framework Maps
+
+**Purpose**: Quick reference for adding subagents to eval framework  
+**Last Updated**: 2026-01-09
+
+---
+
+## Critical: THREE Maps Must Be Updated
+
+When adding a new subagent, update these THREE locations:
+
+### 1. Parent Map (run-sdk-tests.ts ~line 336)
+
+**Purpose**: Maps subagent → parent agent for delegation testing
+
+```typescript
+const subagentParentMap: Record<string, string> = {
+  contextscout: "openagent", // Core subagents → openagent
+  "task-manager": "openagent",
+  documentation: "openagent",
+
+  "coder-agent": "opencoder", // Code subagents → opencoder
+  tester: "opencoder",
+  reviewer: "opencoder",
+}
+```
+
+### 2. Path Map (run-sdk-tests.ts ~line 414)
+
+**Purpose**: Maps subagent name → file path for test discovery
+
+```typescript
+const subagentPathMap: Record<string, string> = {
+  contextscout: "ContextScout",
+  "task-manager": "TaskManager",
+  "coder-agent": "CoderAgent",
+}
+```
+
+### 3. Agent Map (test-runner.ts ~line 238)
+
+**Purpose**: Maps subagent name → agent file for eval-runner
+
+```typescript
+const agentMap: Record<string, string> = {
+  contextscout: "ContextScout.md",
+  "task-manager": "TaskManager.md",
+  "coder-agent": "CoderAgent.md",
+}
+```
+
+---
+
+## Error Messages
+
+| Error                  | Missing From    | Fix                        |
+| ---------------------- | --------------- | -------------------------- |
+| "No test files found"  | Path Map (#2)   | Add to `subagentPathMap`   |
+| "Unknown subagent"     | Parent Map (#1) | Add to `subagentParentMap` |
+| "Agent file not found" | Agent Map (#3)  | Add to `agentMap`          |
+
+---
+
+## Testing Commands
+
+```bash
+# Standalone mode (forces mode: primary)
+npm run eval:sdk -- --subagent=contextscout
+
+# Delegation mode (tests via parent)
+npm run eval:sdk -- --subagent=contextscout --delegate
+```
+
+---
+
+## Related
+
+- `guides/testing-subagents.md` - Full testing guide
+- `guides/adding-agent.md` - Creating new agents

package/.plcode/context/openagents-repo/lookup/subagent-test-commands.md

@@ -0,0 +1,213 @@
+# Subagent Testing Commands - Quick Reference
+
+**Purpose**: Quick command reference for testing subagents
+
+**Last Updated**: 2026-01-07
+
+---
+
+## Standalone Mode (Unit Testing)
+
+### Run All Standalone Tests
+
+```bash
+cd evals/framework
+npm run eval:sdk -- --subagent=ContextScout --pattern="standalone/*.yaml"
+```
+
+### Run Single Test
+
+```bash
+npm run eval:sdk -- --subagent=ContextScout --pattern="standalone/01-simple-discovery.yaml"
+```
+
+### Debug Mode
+
+```bash
+npm run eval:sdk -- --subagent=ContextScout --pattern="standalone/*.yaml" --debug
+```
+
+---
+
+## Delegation Mode (Integration Testing)
+
+### Run Delegation Tests
+
+```bash
+npm run eval:sdk -- --agent=core/openagent --pattern="delegation/*.yaml"
+```
+
+### Test Specific Delegation
+
+```bash
+npm run eval:sdk -- --agent=core/openagent --pattern="delegation/01-contextscout-delegation.yaml"
+```
+
+---
+
+## Verification Commands
+
+### Check Agent File
+
+```bash
+# View agent frontmatter
+head -30 .plcode/agent/ContextScout.md
+
+# Check tool permissions
+grep -A 10 "^tools:" .plcode/agent/ContextScout.md
+```
+
+### Check Test Config
+
+```bash
+cat evals/agents/ContextScout/config/config.yaml
+```
+
+### View Latest Results
+
+```bash
+# Summary
+cat evals/results/latest.json | jq '.summary'
+
+# Agent loaded
+cat evals/results/latest.json | jq '.meta.agent'
+
+# Tool calls
+cat evals/results/latest.json | jq '.tests[0]' | grep -A 5 "Tool"
+
+# Violations
+cat evals/results/latest.json | jq '.tests[0].violations'
+```
+
+---
+
+## Common Test Patterns
+
+### Smoke Test
+
+```bash
+npm run eval:sdk -- --subagent=ContextScout --pattern="smoke-test.yaml"
+```
+
+### Specific Test Suite
+
+```bash
+npm run eval:sdk -- --subagent=ContextScout --pattern="discovery/*.yaml"
+```
+
+### All Tests for Subagent
+
+```bash
+npm run eval:sdk -- --subagent=ContextScout
+```
+
+---
+
+## Flag Reference
+
+| Flag         | Purpose                            | Example                         |
+| ------------ | ---------------------------------- | ------------------------------- |
+| `--subagent` | Test subagent in standalone mode   | `--subagent=ContextScout`       |
+| `--agent`    | Test primary agent (or delegation) | `--agent=core/openagent`        |
+| `--pattern`  | Filter test files                  | `--pattern="standalone/*.yaml"` |
+| `--debug`    | Show detailed output               | `--debug`                       |
+| `--timeout`  | Override timeout                   | `--timeout=120000`              |
+
+---
+
+## Troubleshooting Commands
+
+### Check Which Agent Ran
+
+```bash
+# Should show subagent name for standalone mode
+cat evals/results/latest.json | jq '.meta.agent'
+```
+
+### Check Tool Usage
+
+```bash
+# Should show tool calls > 0
+cat evals/results/latest.json | jq '.tests[0]' | grep "Tool Calls"
+```
+
+### View Test Timeline
+
+```bash
+# See full conversation
+cat evals/results/history/2026-01/07-*.json | jq '.tests[0].timeline'
+```
+
+### Check for Errors
+
+```bash
+# View violations
+cat evals/results/latest.json | jq '.tests[0].violations.details'
+```
+
+---
+
+## File Locations
+
+### Agent Files
+
+```
+.plcode/agent/subagents/core/{subagent}.md
+```
+
+### Test Files
+
+```
+evals/agents/subagents/core/{subagent}/
+├── config/config.yaml
+└── tests/
+    ├── standalone/
+    │   ├── 01-simple-discovery.yaml
+    │   └── 02-advanced-test.yaml
+    └── delegation/
+        └── 01-delegation-test.yaml
+```
+
+### Results
+
+```
+evals/results/
+├── latest.json                    # Latest test run
+└── history/2026-01/              # Historical results
+    └── 07-HHMMSS-{agent}.json
+```
+
+---
+
+## Quick Checks
+
+### Is Agent Loaded Correctly?
+
+```bash
+# Should show: "agent": "ContextScout"
+cat evals/results/latest.json | jq '.meta.agent'
+```
+
+### Did Agent Use Tools?
+
+```bash
+# Should show: Tool Calls: 1 (or more)
+cat evals/results/latest.json | jq '.tests[0]' | grep "Tool Calls"
+```
+
+### Did Test Pass?
+
+```bash
+# Should show: "passed": 1, "failed": 0
+cat evals/results/latest.json | jq '.summary'
+```
+
+---
+
+## Related
+
+- `concepts/subagent-testing-modes.md` - Understand testing modes
+- `guides/testing-subagents.md` - Step-by-step testing guide
+- `errors/tool-permission-errors.md` - Fix common issues
+
+**Reference**: `evals/framework/src/sdk/run-sdk-tests.ts`

package/.plcode/context/openagents-repo/navigation.md

@@ -0,0 +1,143 @@
+# OpenAgents Repository Context
+
+**Purpose**: Context files specific to the OpenAgents repository
+
+**Last Updated**: 2026-01-07
+
+---
+
+## Quick Navigation
+
+| Function     | Files   | Purpose                   |
+| ------------ | ------- | ------------------------- |
+| **Concepts** | 2 files | Core ideas and principles |
+| **Examples** | 1 file  | Working code samples      |
+| **Guides**   | 8 files | Step-by-step workflows    |
+| **Lookup**   | 4 files | Quick reference tables    |
+| **Errors**   | 1 file  | Common issues + solutions |
+
+---
+
+## Concepts (Core Ideas)
+
+| File                                 | Topic                            | Priority   |
+| ------------------------------------ | -------------------------------- | ---------- |
+| `concepts/subagent-testing-modes.md` | Standalone vs delegation testing | ⭐⭐⭐⭐⭐ |
+
+**When to read**: Before testing any subagent
+
+---
+
+## Examples (Working Code)
+
+| File                                    | Topic                              | Priority |
+| --------------------------------------- | ---------------------------------- | -------- |
+| `examples/subagent-prompt-structure.md` | Optimized subagent prompt template | ⭐⭐⭐⭐ |
+
+**When to read**: When creating or optimizing subagent prompts
+
+---
+
+## Guides (Step-by-Step)
+
+| File                          | Topic                            | Priority   |
+| ----------------------------- | -------------------------------- | ---------- |
+| `guides/testing-subagents.md` | How to test subagents standalone | ⭐⭐⭐⭐⭐ |
+| `guides/adding-agent.md`      | How to add new agents            | ⭐⭐⭐⭐   |
+| `guides/testing-agent.md`     | How to test agents               | ⭐⭐⭐⭐   |
+| `guides/updating-registry.md` | How to update registry           | ⭐⭐⭐     |
+| `guides/debugging.md`         | How to debug issues              | ⭐⭐⭐     |
+| `guides/creating-release.md`  | How to create releases           | ⭐⭐       |
+
+**When to read**: When performing specific tasks
+
+---
+
+## Lookup (Quick Reference)
+
+| File                               | Topic                     | Priority   |
+| ---------------------------------- | ------------------------- | ---------- |
+| `lookup/subagent-test-commands.md` | Subagent testing commands | ⭐⭐⭐⭐⭐ |
+| `lookup/file-locations.md`         | Where files are located   | ⭐⭐⭐⭐   |
+| `lookup/commands.md`               | Available slash commands  | ⭐⭐⭐     |
+
+**When to read**: Quick command lookups
+
+---
+
+## Errors (Troubleshooting)
+
+| File                               | Topic                  | Priority   |
+| ---------------------------------- | ---------------------- | ---------- |
+| `errors/tool-permission-errors.md` | Tool permission issues | ⭐⭐⭐⭐⭐ |
+
+**When to read**: When tests fail with permission errors
+
+---
+
+## Core Concepts (Foundational)
+
+| File                          | Topic                  | Priority   |
+| ----------------------------- | ---------------------- | ---------- |
+| `core-concepts/agents.md`     | How agents work        | ⭐⭐⭐⭐⭐ |
+| `core-concepts/evals.md`      | How testing works      | ⭐⭐⭐⭐⭐ |
+| `core-concepts/registry.md`   | How registry works     | ⭐⭐⭐⭐   |
+| `core-concepts/categories.md` | How organization works | ⭐⭐⭐     |
+
+**When to read**: First time working in this repo
+
+---
+
+## Loading Strategy
+
+### For Subagent Testing:
+
+1. Load `concepts/subagent-testing-modes.md` (understand modes)
+2. Load `guides/testing-subagents.md` (step-by-step)
+3. Reference `lookup/subagent-test-commands.md` (commands)
+4. If errors: Load `errors/tool-permission-errors.md`
+
+### For Agent Creation:
+
+1. Load `core-concepts/agents.md` (understand structure)
+2. Load `guides/adding-agent.md` (step-by-step)
+3. Load `examples/subagent-prompt-structure.md` (if subagent)
+4. Load `guides/testing-agent.md` (validate)
+
+### For Debugging:
+
+1. Load `guides/debugging.md` (general approach)
+2. Load specific error file from `errors/`
+3. Reference `lookup/file-locations.md` (find files)
+
+---
+
+## File Size Compliance
+
+All files follow MVI principle (<200 lines):
+
+- ✅ Concepts: <100 lines
+- ✅ Examples: <100 lines
+- ✅ Guides: <150 lines
+- ✅ Lookup: <100 lines
+- ✅ Errors: <150 lines
+
+---
+
+## Related Context
+
+- `../core/` - Core system context (standards, patterns)
+- `../core/context-system/` - Context management system
+- `quick-start.md` - 2-minute repo orientation
+
+---
+
+## Contributing
+
+When adding new context files:
+
+1. Follow MVI principle (<200 lines)
+2. Use function-based organization (concepts/, examples/, guides/, lookup/, errors/)
+3. Update this README.md navigation
+4. Add cross-references to related files
+5. Validate with `/context validate`

package/.plcode/context/openagents-repo/plugins/context/architecture/lifecycle.md

@@ -0,0 +1,39 @@
+# Plugin Lifecycle & Packaging
+
+## File Structure for Complex Plugins
+
+For larger plugins, follow this recommended structure:
+
+```
+my-plugin/
+├── .claude-plugin/
+│   └── plugin.json          # Manifest (required for packaging)
+├── commands/                # Custom slash commands
+├── agents/                  # Custom agents
+├── hooks/                   # Event handlers
+└── README.md               # Documentation
+```
+
+## The Manifest (`plugin.json`)
+
+```json
+{
+  "name": "my-plugin",
+  "description": "A custom plugin",
+  "version": "1.0.0",
+  "author": {
+    "name": "Your Name"
+  }
+}
+```
+
+The `name` becomes the namespace prefix for commands: `/my-plugin:command`.
+
+## SDK Access
+
+Plugins have full access to the PLCode SDK via `context.client`. This allows:
+
+- Sending prompts programmatically: `client.session.prompt()`
+- Managing sessions: `client.session.list()`, `client.session.get()`
+- Showing UI elements: `client.tui.showToast()`
+- Appending to prompt: `client.tui.appendPrompt()`

package/.plcode/context/openagents-repo/plugins/context/architecture/overview.md

@@ -0,0 +1,61 @@
+# PLCode Plugins Overview
+
+PLCode plugins are JavaScript or TypeScript modules that hook into **25+ events** across the entire PLCode lifecycle—from when you type a prompt, to when tools execute, to when sessions complete.
+
+## Key Concepts
+
+- **Zero-Config**: No build step or compilation required. Just drop `.ts` or `.js` files into the plugin folder.
+- **Middleware Pattern**: Plugins subscribe to events and execute logic, similar to Express.js middleware.
+- **Access**: Plugins receive a `context` object with:
+  - `project`: Current project metadata.
+  - `client`: PLCode SDK client for programmatic control.
+  - `$`: Bun's shell API for running commands.
+  - `directory`: Current working directory.
+  - `worktree`: Git worktree path.
+
+## Plugin Registration
+
+PLCode looks for plugins in:
+
+1. **Project-level**: `.plcode/plugin/` (project root)
+2. **Global**: `~/.config/plcode/plugin/` (home directory)
+
+## Basic Structure
+
+```typescript
+export const MyPlugin = async (context) => {
+  const { project, client, $, directory, worktree } = context
+
+  return {
+    event: async ({ event }) => {
+      // Handle events here
+    },
+  }
+}
+```
+
+Each exported function becomes a separate plugin instance. The name of the export is used as the plugin name.
+
+## Build and Development
+
+PLCode plugins are typically written in TypeScript and bundled into a single JavaScript file for execution.
+
+### Build Command
+
+Use Bun to bundle the plugin into the `dist` directory:
+
+```bash
+bun build src/index.ts --outdir dist --target bun --format esm
+```
+
+The output will be a single file (e.g., `./index.js`) containing all dependencies.
+
+### Development Workflow
+
+1. **Source Code**: Write your plugin in `src/index.ts`.
+2. **Bundle**: Run the build command to generate `dist/index.js`.
+3. **Load**: Point PLCode to the bundled file or the directory containing the manifest.
+4. **Watch Mode**: For rapid development, use the `--watch` flag with Bun build:
+   ```bash
+   bun build src/index.ts --outdir dist --target bun --format esm --watch
+   ```

package/.plcode/context/openagents-repo/plugins/context/capabilities/agents.md

@@ -0,0 +1,45 @@
+# Custom Agents in PLCode
+
+Plugins can register custom AI agents that have specific roles, instructions, and toolsets.
+
+## Agent Definition
+
+Custom agents are configured in the plugin's `config` function.
+
+```typescript
+export const registerCustomAgents = (config) => {
+  return {
+    ...config,
+    agents: [
+      {
+        name: "my-helper",
+        description: "A friendly assistant for this project",
+        instructions: "You are a helpful assistant. Use your tools to help the user.",
+        model: "claude-3-5-sonnet-latest", // Specify the model
+        tools: ["say_hello", "read", "write"], // Reference built-in or custom tools
+      },
+    ],
+  }
+}
+```
+
+## Integrating into Plugin
+
+The `config` method in the plugin return object is used to register agents.
+
+```typescript
+export const MyPlugin: Plugin = async (context) => {
+  return {
+    config: async (currentConfig) => {
+      return registerCustomAgents(currentConfig)
+    },
+    // ... other properties
+  }
+}
+```
+
+## Agent Capabilities
+
+- **Model Choice**: You can select specific models for different agents.
+- **Scoped Tools**: Limit what tools an agent can use to ensure safety or focus.
+- **System Instructions**: Define the "personality" and rules for the agent.

package/.plcode/context/openagents-repo/plugins/context/capabilities/events.md

@@ -0,0 +1,48 @@
+# PLCode Plugin Events
+
+PLCode fires over 25 events that you can hook into. These are categorized below:
+
+## Command Events
+
+- `command.executed`: Fired when a user or plugin runs a command.
+
+## File Events
+
+- `file.edited`: Fired when a file is modified via PLCode tools.
+- `file.watcher.updated`: Fired when the file watcher detects changes.
+
+## Message Events (Read-Only)
+
+- `message.updated`: Fired when a message in the session updates.
+- `message.part.updated`: Fired when individual parts of a message update.
+- `message.part.removed`: Fired when a part is removed.
+- `message.removed`: Fired when entire message is removed.
+
+## Session Events
+
+- `session.created`: New session started.
+- `session.updated`: Session state changed.
+- `session.idle`: Session completed (no more activity expected).
+- `session.status`: Session status changed.
+- `session.error`: Error occurred in session.
+- `session.compacted`: Session was compacted (context summarized).
+
+## Tool Events (Interception)
+
+- `tool.execute.before`: Fired before a tool runs. **Can block execution** by throwing an error.
+- `tool.execute.after`: Fired after a tool completes with result.
+
+## TUI Events
+
+- `tui.prompt.append`: Text appended to prompt input.
+- `tui.command.execute`: Command executed from TUI.
+- `tui.toast.show`: Toast notification shown.
+
+## Mapping from Claude Code Hooks
+
+| Claude Hook      | PLCode Event        |
+| ---------------- | ------------------- |
+| PreToolUse       | tool.execute.before |
+| PostToolUse      | tool.execute.after  |
+| UserPromptSubmit | message.\* events   |
+| SessionEnd       | session.idle        |