plcode-windows-x64-baseline 2.1.0

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

@@ -0,0 +1,400 @@
+# Lookup: Command Reference
+
+**Purpose**: Quick reference for common commands
+
+---
+
+## Registry Commands
+
+### Validate Registry
+
+```bash
+# Basic validation
+./scripts/registry/validate-registry.sh
+
+# Verbose output
+./scripts/registry/validate-registry.sh -v
+```
+
+### Auto-Detect Components
+
+```bash
+# Dry run (see what would change)
+./scripts/registry/auto-detect-components.sh --dry-run
+
+# Add new components
+./scripts/registry/auto-detect-components.sh --auto-add
+
+# Force update existing
+./scripts/registry/auto-detect-components.sh --auto-add --force
+```
+
+### Validate Component Structure
+
+```bash
+./scripts/registry/validate-component.sh
+```
+
+---
+
+## Testing Commands
+
+### Run Tests
+
+```bash
+# Single test
+cd evals/framework
+npm run eval:sdk -- --agent={category}/{agent} --pattern="{test}.yaml"
+
+# All tests for agent
+npm run eval:sdk -- --agent={category}/{agent}
+
+# All tests (all agents)
+npm run eval:sdk
+
+# With debug
+npm run eval:sdk -- --agent={agent} --debug
+```
+
+### Validate Test Suites
+
+```bash
+./scripts/validation/validate-test-suites.sh
+```
+
+---
+
+## Installation Commands
+
+### Install Components
+
+```bash
+# List available components
+./install.sh --list
+
+# Install profile
+./install.sh {profile}
+# Profiles: essential, developer, business
+
+# Install specific component
+./install.sh --component agent:{agent-name}
+
+# Test with local registry
+REGISTRY_URL="file://$(pwd)/registry.json" ./install.sh --list
+```
+
+### Collision Handling
+
+```bash
+# Skip existing files
+./install.sh developer --skip-existing
+
+# Overwrite all
+./install.sh developer --force
+
+# Backup existing
+./install.sh developer --backup
+```
+
+---
+
+## Version Commands
+
+### Check Version
+
+```bash
+# Check all version files
+cat VERSION
+cat package.json | jq '.version'
+cat registry.json | jq '.version'
+```
+
+### Update Version
+
+```bash
+# Update VERSION
+echo "0.X.Y" > VERSION
+
+# Update package.json
+jq '.version = "0.X.Y"' package.json > tmp && mv tmp package.json
+
+# Update registry.json
+jq '.version = "0.X.Y"' registry.json > tmp && mv tmp registry.json
+```
+
+### Bump Version Script
+
+```bash
+./scripts/versioning/bump-version.sh 0.X.Y
+```
+
+---
+
+## Git Commands
+
+### Create Release
+
+```bash
+# Commit version changes
+git add VERSION package.json CHANGELOG.md
+git commit -m "chore: bump version to 0.X.Y"
+
+# Create tag
+git tag -a v0.X.Y -m "Release v0.X.Y"
+
+# Push
+git push origin main
+git push origin v0.X.Y
+```
+
+### Create GitHub Release
+
+```bash
+# Via GitHub CLI
+gh release create v0.X.Y \
+  --title "v0.X.Y" \
+  --notes "See CHANGELOG.md for details"
+```
+
+---
+
+## Validation Commands
+
+### Full Validation
+
+```bash
+# Validate everything
+./scripts/registry/validate-registry.sh && \
+./scripts/validation/validate-test-suites.sh && \
+cd evals/framework && npm run eval:sdk
+```
+
+### Check Context Dependencies
+
+```bash
+# Analyze all agents
+/check-context-deps
+
+# Analyze specific agent
+/check-context-deps contextscout
+
+# Auto-fix missing dependencies
+/check-context-deps --fix
+```
+
+### Validate Context References
+
+```bash
+./scripts/validation/validate-context-refs.sh
+```
+
+### Setup Pre-Commit Hook
+
+```bash
+./scripts/validation/setup-pre-commit-hook.sh
+```
+
+---
+
+## Development Commands
+
+### Run Demo
+
+```bash
+./scripts/development/demo.sh
+```
+
+### Run Dashboard
+
+```bash
+./scripts/development/dashboard.sh
+```
+
+---
+
+## Maintenance Commands
+
+### Cleanup Stale Sessions
+
+```bash
+./scripts/maintenance/cleanup-stale-sessions.sh
+```
+
+### Uninstall
+
+```bash
+./scripts/maintenance/uninstall.sh
+```
+
+---
+
+## Debugging Commands
+
+### Check Sessions
+
+```bash
+# List recent sessions
+ls -lt .tmp/sessions/ | head -5
+
+# View session
+cat .tmp/sessions/{session-id}/session.json | jq
+
+# View events
+cat .tmp/sessions/{session-id}/events.json | jq
+```
+
+### Check Context Logs
+
+```bash
+# Check session cache
+./scripts/check-context-logs/check-session-cache.sh
+
+# Count agent tokens
+./scripts/check-context-logs/count-agent-tokens.sh
+
+# Show API payload
+./scripts/check-context-logs/show-api-payload.sh
+
+# Show cached data
+./scripts/check-context-logs/show-cached-data.sh
+```
+
+---
+
+## Quick Workflows
+
+### Adding a New Agent
+
+```bash
+# 1. Create agent file
+touch .plcode/agent/{category}/{agent-name}.md
+# (Add frontmatter and content)
+
+# 2. Create test structure
+mkdir -p evals/agents/{category}/{agent-name}/{config,tests}
+# (Create config.yaml and smoke-test.yaml)
+
+# 3. Update registry
+./scripts/registry/auto-detect-components.sh --auto-add
+
+# 4. Validate
+./scripts/registry/validate-registry.sh
+cd evals/framework && npm run eval:sdk -- --agent={category}/{agent-name}
+```
+
+### Testing an Agent
+
+```bash
+# 1. Run smoke test
+cd evals/framework
+npm run eval:sdk -- --agent={category}/{agent} --pattern="smoke-test.yaml"
+
+# 2. If fails, debug
+npm run eval:sdk -- --agent={category}/{agent} --debug
+
+# 3. Check session
+ls -lt .tmp/sessions/ | head -1
+cat .tmp/sessions/{session-id}/session.json | jq
+```
+
+### Creating a Release
+
+```bash
+# 1. Update version
+echo "0.X.Y" > VERSION
+jq '.version = "0.X.Y"' package.json > tmp && mv tmp package.json
+
+# 2. Update CHANGELOG
+# (Edit CHANGELOG.md)
+
+# 3. Commit and tag
+git add VERSION package.json CHANGELOG.md
+git commit -m "chore: bump version to 0.X.Y"
+git tag -a v0.X.Y -m "Release v0.X.Y"
+
+# 4. Push
+git push origin main
+git push origin v0.X.Y
+
+# 5. Create GitHub release
+gh release create v0.X.Y --title "v0.X.Y" --notes "See CHANGELOG.md"
+```
+
+---
+
+## Common Patterns
+
+### Find Files
+
+```bash
+# Find agent
+find .plcode/agent -name "{agent-name}.md"
+
+# Find tests
+find evals/agents -name "*.yaml"
+
+# Find context
+find .plcode/context -name "*.md"
+
+# Find scripts
+find scripts -name "*.sh"
+```
+
+### Check Registry
+
+```bash
+# List all agents
+cat registry.json | jq '.components.agents[].id'
+
+# Check specific component
+cat registry.json | jq '.components.agents[] | select(.id == "{agent-name}")'
+
+# Count components
+cat registry.json | jq '.components.agents | length'
+```
+
+### Test Locally
+
+```bash
+# Test with local registry
+REGISTRY_URL="file://$(pwd)/registry.json" ./install.sh --list
+
+# Install locally
+REGISTRY_URL="file://$(pwd)/registry.json" ./install.sh developer
+```
+
+---
+
+## NPM Commands (Eval Framework)
+
+```bash
+cd evals/framework
+
+# Install dependencies
+npm install
+
+# Run tests
+npm test
+
+# Run eval SDK
+npm run eval:sdk
+
+# Build
+npm run build
+
+# Lint
+npm run lint
+```
+
+---
+
+## Related Files
+
+- **Quick start**: `quick-start.md`
+- **File locations**: `lookup/file-locations.md`
+- **Guides**: `guides/`
+
+---
+
+**Last Updated**: 2025-12-10  
+**Version**: 0.5.0

package/.plcode/context/openagents-repo/lookup/file-locations.md

@@ -0,0 +1,322 @@
+# Lookup: File Locations
+
+**Purpose**: Quick reference for finding files
+
+---
+
+## Directory Tree
+
+```
+opencode-agents/
+├── .plcode/
+│   ├── agent/
+│   │   ├── core/                    # Core system agents
+│   │   ├── development/             # Dev specialists
+│   │   ├── content/                 # Content creators
+│   │   ├── data/                    # Data analysts
+│   │   ├── product/                 # Product managers (ready)
+│   │   ├── learning/                # Educators (ready)
+│   │   └── subagents/               # Delegated specialists
+│   │       ├── code/                # Code-related
+│   │       ├── core/                # Core workflows
+│   │       ├── system-builder/      # System generation
+│   │       └── utils/               # Utilities
+│   ├── command/                     # Slash commands
+│   ├── context/                     # Shared knowledge
+│   │   ├── core/                    # Core standards & workflows
+│   │   ├── development/             # Dev context
+│   │   ├── content-creation/        # Content creation context
+│   │   ├── data/                    # Data context
+│   │   ├── product/                 # Product context
+│   │   ├── learning/                # Learning context
+│   │   └── openagents-repo/         # Repo-specific context
+│   ├── prompts/                     # Model-specific variants
+│   ├── tool/                        # Custom tools
+│   └── plugin/                      # Plugins
+├── evals/
+│   ├── framework/                   # Eval framework (TypeScript)
+│   │   ├── src/                     # Source code
+│   │   ├── scripts/                 # Test utilities
+│   │   └── docs/                    # Framework docs
+│   └── agents/                      # Agent test suites
+│       ├── core/                    # Core agent tests
+│       ├── development/             # Dev agent tests
+│       └── content/                 # Content agent tests
+├── scripts/
+│   ├── registry/                    # Registry management
+│   ├── validation/                  # Validation tools
+│   ├── testing/                     # Test utilities
+│   ├── versioning/                  # Version management
+│   ├── docs/                        # Doc tools
+│   └── maintenance/                 # Maintenance
+├── docs/                            # Documentation
+│   ├── agents/                      # Agent docs
+│   ├── contributing/                # Contribution guides
+│   ├── features/                    # Feature docs
+│   └── getting-started/             # User guides
+├── registry.json                    # Component catalog
+├── install.sh                       # Installer
+├── VERSION                          # Current version
+└── package.json                     # Node dependencies
+```
+
+---
+
+## Where Is...?
+
+| Component              | Location                              |
+| ---------------------- | ------------------------------------- |
+| **Core agents**        | `.plcode/agent/core/`                 |
+| **Category agents**    | `.plcode/agent/{category}/`           |
+| **Subagents**          | `.plcode/agent/subagents/`            |
+| **Commands**           | `.plcode/command/`                    |
+| **Context files**      | `.plcode/context/`                    |
+| **Prompt variants**    | `.plcode/prompts/{category}/{agent}/` |
+| **Tools**              | `.plcode/tool/`                       |
+| **Plugins**            | `.plcode/plugin/`                     |
+| **Agent tests**        | `evals/agents/{category}/{agent}/`    |
+| **Eval framework**     | `evals/framework/src/`                |
+| **Registry scripts**   | `scripts/registry/`                   |
+| **Validation scripts** | `scripts/validation/`                 |
+| **Documentation**      | `docs/`                               |
+| **Registry**           | `registry.json`                       |
+| **Installer**          | `install.sh`                          |
+| **Version**            | `VERSION`                             |
+
+---
+
+## Where Do I Add...?
+
+| What                   | Where                                                |
+| ---------------------- | ---------------------------------------------------- |
+| **New core agent**     | `.plcode/agent/core/{name}.md`                       |
+| **New category agent** | `.plcode/agent/{category}/{name}.md`                 |
+| **New subagent**       | `.plcode/agent/subagents/{category}/{name}.md`       |
+| **New command**        | `.plcode/command/{name}.md`                          |
+| **New context**        | `.plcode/context/{category}/{name}.md`               |
+| **Agent tests**        | `evals/agents/{category}/{agent}/tests/`             |
+| **Test config**        | `evals/agents/{category}/{agent}/config/config.yaml` |
+| **Documentation**      | `docs/{section}/{topic}.md`                          |
+| **Script**             | `scripts/{purpose}/{name}.sh`                        |
+
+---
+
+## Specific File Paths
+
+### Core Files
+
+```
+registry.json                        # Component catalog
+install.sh                           # Main installer
+update.sh                            # Update script
+VERSION                              # Current version (0.5.0)
+package.json                         # Node dependencies
+CHANGELOG.md                         # Release notes
+README.md                            # Main documentation
+```
+
+### Core Agents
+
+```
+.plcode/agent/core/openagent.md
+.plcode/agent/core/opencoder.md
+```
+
+### Meta Agents
+
+```
+.plcode/agent/meta/system-builder.md
+```
+
+### Development Agents
+
+```
+.plcode/agent/development/frontend-specialist.md
+.plcode/agent/development/backend-specialist.md
+.plcode/agent/development/devops-specialist.md
+.plcode/agent/development/codebase-agent.md
+```
+
+### Content Agents
+
+```
+.plcode/agent/content/copywriter.md
+.plcode/agent/content/technical-writer.md
+```
+
+### Key Subagents
+
+```
+.plcode/agent/TestEngineer.md
+.plcode/agent/CodeReviewer.md
+.plcode/agent/CoderAgent.md
+.plcode/agent/TaskManager.md
+.plcode/agent/DocWriter.md
+```
+
+### Core Context
+
+```
+.plcode/context/core/standards/code-quality.md
+.plcode/context/core/standards/documentation.md
+.plcode/context/core/standards/test-coverage.md
+.plcode/context/core/standards/security-patterns.md
+.plcode/context/core/workflows/task-delegation.md
+.plcode/context/core/workflows/code-review.md
+```
+
+### Registry Scripts
+
+```
+scripts/registry/validate-registry.sh
+scripts/registry/auto-detect-components.sh
+scripts/registry/register-component.sh
+scripts/registry/validate-component.sh
+```
+
+### Validation Scripts
+
+```
+scripts/validation/validate-context-refs.sh
+scripts/validation/validate-test-suites.sh
+scripts/validation/setup-pre-commit-hook.sh
+```
+
+### Eval Framework
+
+```
+evals/framework/src/sdk/              # Test runner
+evals/framework/src/evaluators/       # Rule evaluators
+evals/framework/src/collector/        # Session collection
+evals/framework/src/types/            # TypeScript types
+```
+
+---
+
+## Path Patterns
+
+### Agents
+
+```
+.plcode/agent/{category}/{agent-name}.md
+```
+
+**Examples**:
+
+- `.plcode/agent/core/openagent.md`
+- `.plcode/agent/development/frontend-specialist.md`
+- `.plcode/agent/TestEngineer.md`
+
+### Context
+
+```
+.plcode/context/{category}/{topic}.md
+```
+
+**Examples**:
+
+- `.plcode/context/core/standards/code-quality.md`
+- `.plcode/context/development/react-patterns.md`
+- `.plcode/context/content-creation/principles/copywriting-frameworks.md`
+
+### Tests
+
+```
+evals/agents/{category}/{agent-name}/
+├── config/config.yaml
+└── tests/{test-name}.yaml
+```
+
+**Examples**:
+
+- `evals/agents/core/openagent/tests/smoke-test.yaml`
+- `evals/agents/development/frontend-specialist/tests/approval-gate.yaml`
+
+### Scripts
+
+```
+scripts/{purpose}/{action}-{target}.sh
+```
+
+**Examples**:
+
+- `scripts/registry/validate-registry.sh`
+- `scripts/validation/validate-test-suites.sh`
+- `scripts/versioning/bump-version.sh`
+
+---
+
+## Naming Conventions
+
+### Files
+
+- **Agents**: `{name}.md` or `{domain}-specialist.md`
+- **Context**: `{topic}.md`
+- **Tests**: `{test-name}.yaml`
+- **Scripts**: `{action}-{target}.sh`
+- **Docs**: `{topic}.md`
+
+### Directories
+
+- **Categories**: lowercase, singular (e.g., `development`, `content`)
+- **Purposes**: lowercase, descriptive (e.g., `registry`, `validation`)
+
+---
+
+## Quick Lookups
+
+### Find Agent File
+
+```bash
+# By name
+find .plcode/agent -name "{agent-name}.md"
+
+# By category
+ls .plcode/agent/{category}/
+
+# All agents
+find .plcode/agent -name "*.md" -not -path "*/subagents/*"
+```
+
+### Find Test File
+
+```bash
+# By agent
+ls evals/agents/{category}/{agent}/tests/
+
+# All tests
+find evals/agents -name "*.yaml"
+```
+
+### Find Context File
+
+```bash
+# By category
+ls .plcode/context/{category}/
+
+# All context
+find .plcode/context -name "*.md"
+```
+
+### Find Script
+
+```bash
+# By purpose
+ls scripts/{purpose}/
+
+# All scripts
+find scripts -name "*.sh"
+```
+
+---
+
+## Related Files
+
+- **Quick start**: `quick-start.md`
+- **Categories**: `core-concepts/categories.md`
+- **Commands**: `lookup/commands.md`
+
+---
+
+**Last Updated**: 2025-12-10  
+**Version**: 0.5.0