plcode-linux-x64-baseline 2.1.0

package/.plcode/context/openagents-repo/core-concepts/registry.md

@@ -0,0 +1,473 @@
+# Core Concept: Registry System
+
+**Purpose**: Understanding how component tracking and distribution works  
+**Priority**: CRITICAL - Load this before working with registry
+
+---
+
+## What Is the Registry?
+
+The registry is a centralized catalog (`registry.json`) that tracks all components in OpenAgents:
+
+- **Agents** - AI agent prompts
+- **Subagents** - Delegated specialists
+- **Commands** - Slash commands
+- **Tools** - Custom tools
+- **Contexts** - Context files
+
+**Location**: `registry.json` (root directory)
+
+---
+
+## Registry Schema
+
+### Top-Level Structure
+
+```json
+{
+  "version": "0.5.0",
+  "schema_version": "2.0.0",
+  "components": {
+    "agents": [...],
+    "subagents": [...],
+    "commands": [...],
+    "tools": [...],
+    "contexts": [...]
+  },
+  "profiles": {
+    "essential": {...},
+    "developer": {...},
+    "business": {...}
+  }
+}
+```
+
+### Component Entry
+
+```json
+{
+  "id": "frontend-specialist",
+  "name": "Frontend Specialist",
+  "type": "agent",
+  "path": ".plcode/agent/development/frontend-specialist.md",
+  "description": "Expert in React, Vue, and modern CSS",
+  "category": "development",
+  "tags": ["react", "vue", "css", "frontend"],
+  "dependencies": ["subagent:tester"],
+  "version": "0.5.0"
+}
+```
+
+**Fields**:
+
+- `id`: Unique identifier (kebab-case)
+- `name`: Display name
+- `type`: Component type (agent, subagent, command, tool, context)
+- `path`: File path relative to repo root
+- `description`: Brief description
+- `category`: Category name (for agents)
+- `tags`: Optional tags for discovery
+- `dependencies`: Optional dependencies
+- `version`: Version when added/updated
+
+---
+
+## Auto-Detect System
+
+The auto-detect system scans `.plcode/` and automatically updates the registry.
+
+### How It Works
+
+```
+1. Scan .plcode/ directory
+2. Find all .md files with frontmatter
+3. Extract metadata (description, category, type, tags)
+4. Validate paths exist
+5. Generate component entries
+6. Update registry.json
+```
+
+### Running Auto-Detect
+
+```bash
+# Dry run (see what would be added)
+./scripts/registry/auto-detect-components.sh --dry-run
+
+# Actually add components
+./scripts/registry/auto-detect-components.sh --auto-add
+
+# Force update existing entries
+./scripts/registry/auto-detect-components.sh --auto-add --force
+```
+
+### What Gets Detected
+
+✅ **Agents** - `.plcode/agent/{category}/*.md`  
+✅ **Subagents** - `.plcode/agent/subagents/**/*.md`  
+✅ **Commands** - `.plcode/command/**/*.md`  
+✅ **Tools** - `.plcode/tool/**/index.ts`  
+✅ **Contexts** - `.plcode/context/**/*.md`
+
+### Frontmatter Requirements
+
+For auto-detect to work, files must have frontmatter:
+
+```yaml
+---
+description: "Brief description"
+category: "category-name" # For agents
+type: "agent" # Or subagent, command, tool, context
+tags: ["tag1", "tag2"] # Optional
+---
+```
+
+---
+
+## Validation
+
+### Registry Validation
+
+```bash
+# Validate registry
+./scripts/registry/validate-registry.sh
+
+# Verbose output
+./scripts/registry/validate-registry.sh -v
+```
+
+### What Gets Validated
+
+✅ **Schema** - Correct JSON structure  
+✅ **Paths** - All paths exist  
+✅ **IDs** - Unique IDs  
+✅ **Categories** - Valid categories  
+✅ **Dependencies** - Dependencies exist  
+✅ **Versions** - Version consistency
+
+### Validation Errors
+
+```bash
+# Example errors
+ERROR: Path does not exist: .plcode/agent/core/missing.md
+ERROR: Duplicate ID: frontend-specialist
+ERROR: Invalid category: invalid-category
+ERROR: Missing dependency: subagent:nonexistent
+```
+
+---
+
+## Component Profiles
+
+Profiles are pre-configured component bundles for quick installation.
+
+### Available Profiles
+
+#### Essential Profile
+
+**Purpose**: Minimal setup for basic usage
+
+**Includes**:
+
+- Core agents (openagent, opencoder)
+- Essential commands (commit, test)
+- Core context files
+
+```json
+"essential": {
+  "description": "Minimal setup for basic usage",
+  "components": [
+    "agent:openagent",
+    "agent:opencoder",
+    "command:commit",
+    "command:test"
+  ]
+}
+```
+
+---
+
+#### Developer Profile
+
+**Purpose**: Full development setup
+
+**Includes**:
+
+- All core agents
+- Development specialists
+- All subagents
+- Dev commands
+- Dev context files
+
+```json
+"developer": {
+  "description": "Full development setup",
+  "components": [
+    "agent:*",
+    "subagent:*",
+    "command:*",
+    "context:core/*",
+    "context:development/*"
+  ]
+}
+```
+
+---
+
+#### Business Profile
+
+**Purpose**: Content and product focus
+
+**Includes**:
+
+- Core agents
+- Content specialists
+- Product specialists
+- Content context files
+
+```json
+"business": {
+  "description": "Content and product focus",
+  "components": [
+    "agent:openagent",
+    "agent:copywriter",
+    "agent:technical-writer",
+    "context:core/*",
+    "context:content/*"
+  ]
+}
+```
+
+---
+
+## Install System
+
+The install system uses the registry to distribute components.
+
+### Installation Flow
+
+```
+1. User runs install.sh
+2. Check for local registry.json (development mode)
+3. If not local, fetch from GitHub (production mode)
+4. Parse registry.json
+5. Show component selection UI
+6. Resolve dependencies
+7. Download components from GitHub
+8. Install to .plcode/
+9. Handle collisions (skip/overwrite/backup)
+```
+
+### Local Registry (Development)
+
+```bash
+# Test with local registry
+REGISTRY_URL="file://$(pwd)/registry.json" ./install.sh --list
+
+# Install with local registry
+REGISTRY_URL="file://$(pwd)/registry.json" ./install.sh developer
+```
+
+### Remote Registry (Production)
+
+```bash
+# Install from GitHub
+./install.sh developer
+
+# List available components
+./install.sh --list
+```
+
+---
+
+## Dependency Resolution
+
+### Dependency Format
+
+```json
+"dependencies": [
+  "subagent:tester",
+  "context:core/standards/code"
+]
+```
+
+### Resolution Rules
+
+1. Parse dependency string (`type:id`)
+2. Find component in registry
+3. Check if already installed
+4. Add to install queue
+5. Recursively resolve dependencies
+6. Install in dependency order
+
+### Example
+
+```
+User installs: frontend-specialist
+  ↓
+Depends on: subagent:tester
+  ↓
+Depends on: context:core/standards/tests
+  ↓
+Install order:
+  1. context:core/standards/tests
+  2. subagent:tester
+  3. frontend-specialist
+```
+
+---
+
+## Collision Handling
+
+When installing components that already exist:
+
+### Collision Strategies
+
+1. **Skip** - Keep existing file
+2. **Overwrite** - Replace with new file
+3. **Backup** - Backup existing, install new
+
+### Interactive Mode
+
+```bash
+File exists: .plcode/agent/core/openagent.md
+[S]kip, [O]verwrite, [B]ackup, [A]ll skip, [F]orce all?
+```
+
+### Non-Interactive Mode
+
+```bash
+# Skip all collisions
+./install.sh developer --skip-existing
+
+# Overwrite all collisions
+./install.sh developer --force
+
+# Backup all collisions
+./install.sh developer --backup
+```
+
+---
+
+## Version Management
+
+### Version Fields
+
+- **Registry version**: Overall registry version (e.g., "0.5.0")
+- **Schema version**: Registry schema version (e.g., "2.0.0")
+- **Component version**: When component was added/updated
+
+### Version Consistency
+
+```bash
+# Check version consistency
+cat VERSION
+cat package.json | jq '.version'
+cat registry.json | jq '.version'
+
+# All should match
+```
+
+### Updating Versions
+
+```bash
+# Bump version
+echo "0.X.Y" > VERSION
+jq '.version = "0.X.Y"' package.json > tmp && mv tmp package.json
+jq '.version = "0.X.Y"' registry.json > tmp && mv tmp registry.json
+```
+
+---
+
+## CI/CD Integration
+
+### GitHub Workflows
+
+#### Validate Registry (PR Checks)
+
+```yaml
+# .github/workflows/validate-registry.yml
+- name: Validate Registry
+  run: ./scripts/registry/validate-registry.sh
+```
+
+#### Auto-Update Registry (Post-Merge)
+
+```yaml
+# .github/workflows/update-registry.yml
+- name: Update Registry
+  run: ./scripts/registry/auto-detect-components.sh --auto-add
+```
+
+#### Version Bump (On Release)
+
+```yaml
+# .github/workflows/version-bump.yml
+- name: Bump Version
+  run: ./scripts/versioning/bump-version.sh
+```
+
+---
+
+## Best Practices
+
+### Adding Components
+
+✅ **Add frontmatter** - Required for auto-detect  
+✅ **Run auto-detect** - Don't manually edit registry  
+✅ **Validate** - Always validate after changes  
+✅ **Test locally** - Use local registry for testing
+
+### Maintaining Registry
+
+✅ **Auto-detect first** - Let scripts handle updates  
+✅ **Validate often** - Catch issues early  
+✅ **Version consistency** - Keep versions in sync  
+✅ **CI validation** - Automate validation in CI
+
+### Dependencies
+
+✅ **Explicit dependencies** - List all dependencies  
+✅ **Test resolution** - Verify dependencies resolve  
+✅ **Avoid cycles** - No circular dependencies
+
+---
+
+## Common Issues
+
+### Path Not Found
+
+**Problem**: Registry references non-existent path  
+**Solution**: Run auto-detect or fix path manually
+
+### Duplicate ID
+
+**Problem**: Two components with same ID  
+**Solution**: Rename one component
+
+### Invalid Category
+
+**Problem**: Agent has invalid category  
+**Solution**: Use valid category (core, development, content, data, product, learning)
+
+### Missing Dependency
+
+**Problem**: Dependency doesn't exist in registry  
+**Solution**: Add dependency or remove reference
+
+### Version Mismatch
+
+**Problem**: VERSION, package.json, registry.json don't match  
+**Solution**: Update all version files to match
+
+---
+
+## Related Files
+
+- **Updating registry**: `guides/updating-registry.md`
+- **Adding agents**: `guides/adding-agent.md`
+- **Categories**: `core-concepts/categories.md`
+
+---
+
+**Last Updated**: 2025-12-10  
+**Version**: 0.5.0

package/.plcode/context/openagents-repo/errors/tool-permission-errors.md

@@ -0,0 +1,227 @@
+# Tool Permission Errors
+
+**Purpose**: Diagnose and fix tool permission issues in agents
+
+**Last Updated**: 2026-01-07
+
+---
+
+## Error: Tool Permission Denied
+
+### Symptom
+
+```json
+{
+  "type": "missing-approval",
+  "severity": "error",
+  "message": "Execution tool 'bash' called without requesting approval"
+}
+```
+
+Or agent tries to use a tool but gets blocked silently (0 tool calls).
+
+---
+
+### Cause
+
+Agent has tool **disabled** or **denied** in frontmatter:
+
+```yaml
+# In agent frontmatter
+tools:
+  bash: false # ← Tool disabled
+
+permissions:
+  bash:
+    "*": "deny" # ← Explicitly denied
+```
+
+**How it works**:
+
+- `bash: false` means agent doesn't have access to bash tool
+- Framework enforces this - agent can't use bash even if prompt says to
+- NOT an approval issue - it's a permission restriction
+
+---
+
+### Solution
+
+**Option 1: Emphasize Tool Restrictions in Prompt** (Recommended)
+
+Add critical rules section at top of agent prompt:
+
+```xml
+<critical_rules priority="absolute" enforcement="strict">
+  <rule id="tool_usage">
+    ONLY use: glob, read, grep, list
+    NEVER use: bash, write, edit, task
+    You're read-only—no modifications allowed
+  </rule>
+  <rule id="always_use_tools">
+    ALWAYS use tools to discover files
+    NEVER assume or fabricate file paths
+  </rule>
+</critical_rules>
+```
+
+**Why this works**: Makes tool restrictions crystal clear in first 15% of prompt.
+
+**Option 2: Enable Tool** (If agent needs it)
+
+```yaml
+tools:
+  bash: true # ← Enable if agent legitimately needs bash
+```
+
+**Warning**: Only enable if agent truly needs the tool. Read-only subagents should NOT have bash/write/edit.
+
+---
+
+### Prevention
+
+**For Read-Only Subagents**:
+
+```yaml
+# Correct configuration for read-only subagents
+tools:
+  read: true
+  grep: true
+  glob: true
+  list: true
+  bash: false # ← No execution
+  edit: false # ← No modifications
+  write: false # ← No file creation
+  task: false # ← No delegation (subagents don't delegate)
+
+permissions:
+  bash:
+    "*": "deny"
+  edit:
+    "**/*": "deny"
+  write:
+    "**/*": "deny"
+```
+
+**For Primary Agents**:
+
+```yaml
+# Primary agents may need execution tools
+tools:
+  read: true
+  grep: true
+  glob: true
+  list: true
+  bash: true # ← May need for operations
+  edit: true # ← May need for modifications
+  write: true # ← May need for file creation
+  task: true # ← May delegate to subagents
+```
+
+---
+
+## Error: Subagent Approval Gate Violation
+
+### Symptom
+
+```json
+{
+  "type": "missing-approval",
+  "message": "Execution tool 'bash' called without requesting approval"
+}
+```
+
+In a **subagent** test.
+
+---
+
+### Cause
+
+**Subagents should NOT have approval gates** - they're delegated to by primary agents who already got approval.
+
+The issue is usually:
+
+1. Subagent trying to use restricted tool (bash/write/edit)
+2. Test expecting approval behavior (wrong for subagents)
+
+---
+
+### Solution
+
+**Fix 1: Remove Tool Usage**
+
+Subagents shouldn't use execution tools. Update prompt to emphasize read-only nature.
+
+**Fix 2: Update Test Configuration**
+
+Subagent tests should use `auto-approve`:
+
+```yaml
+approvalStrategy:
+  type: auto-approve # ← No approval gates for subagents
+```
+
+**Fix 3: Check Tool Permissions**
+
+Ensure subagent has `bash: false` in frontmatter.
+
+---
+
+## Error: Tool Not Available
+
+### Symptom
+
+Agent tries to use a tool but framework says "tool not available".
+
+---
+
+### Cause
+
+Tool not enabled in frontmatter:
+
+```yaml
+tools:
+  glob: false # ← Tool disabled
+```
+
+---
+
+### Solution
+
+Enable the tool:
+
+```yaml
+tools:
+  glob: true # ← Enable
+```
+
+---
+
+## Verification Checklist
+
+After fixing tool permissions:
+
+- [ ] Agent frontmatter has correct `tools:` configuration?
+- [ ] Prompt emphasizes allowed tools in critical rules section?
+- [ ] Prompt warns against restricted tools?
+- [ ] Test uses `auto-approve` for subagents?
+- [ ] Test verifies tool usage with `mustUseTools`?
+
+---
+
+## Tool Permission Matrix
+
+| Agent Type             | bash | write | edit | task | read | grep | glob | list |
+| ---------------------- | ---- | ----- | ---- | ---- | ---- | ---- | ---- | ---- |
+| **Read-only subagent** | ❌   | ❌    | ❌   | ❌   | ✅   | ✅   | ✅   | ✅   |
+| **Primary agent**      | ✅   | ✅    | ✅   | ✅   | ✅   | ✅   | ✅   | ✅   |
+| **Orchestrator**       | ✅   | ✅    | ✅   | ✅   | ✅   | ✅   | ✅   | ✅   |
+
+---
+
+## Related
+
+- `concepts/subagent-testing-modes.md` - Understand subagent testing
+- `guides/testing-subagents.md` - How to test subagents
+- `examples/subagent-prompt-structure.md` - Prompt structure with tool emphasis
+
+**Reference**: `.plcode/agent/ContextScout.md` (lines 14-28, tool configuration)