@poolzin/plcode 2.1.1 → 3.0.1

package/.plcode/command/validate-repo.md

@@ -0,0 +1,369 @@
+---
+description: Comprehensive validation of repository consistency
+---
+
+# Validate Repository
+
+Comprehensive validation command that checks the entire OpenAgents repository for consistency between CLI, documentation, registry, and components.
+
+## Usage
+
+```bash
+/validate-repo
+```
+
+## What It Checks
+
+This command performs a comprehensive validation of:
+
+1. **Registry Integrity**
+   - JSON syntax validation
+   - Component definitions completeness
+   - File path references
+   - Dependency declarations
+
+2. **Component Existence**
+   - All agents exist at specified paths
+   - All subagents exist at specified paths
+   - All commands exist at specified paths
+   - All tools exist at specified paths
+   - All plugins exist at specified paths
+   - All context files exist at specified paths
+   - All config files exist at specified paths
+
+3. **Profile Consistency**
+   - Component counts match documentation
+   - Profile descriptions are accurate
+   - Dependencies are satisfied
+   - No duplicate components
+
+4. **Documentation Accuracy**
+   - README component counts match registry
+   - OpenAgent documentation references are valid
+   - Context file references are correct
+   - Installation guide is up to date
+
+5. **Context File Structure**
+   - All referenced context files exist
+   - Context file organization is correct
+   - No orphaned context files
+
+6. **Cross-References**
+   - Agent dependencies exist
+   - Subagent references are valid
+   - Command references are valid
+   - Tool dependencies are satisfied
+
+## Output
+
+The command generates a detailed report showing:
+
+- ✅ What's correct and validated
+- ⚠️ Warnings for potential issues
+- ❌ Errors that need fixing
+- 📊 Summary statistics
+
+## Instructions
+
+You are a validation specialist. Your task is to comprehensively validate the OpenAgents repository for consistency and correctness.
+
+### Step 1: Validate Registry JSON
+
+1. Read and parse `registry.json`
+2. Validate JSON syntax
+3. Check schema structure:
+   - `version` field exists
+   - `repository` field exists
+   - `categories` object exists
+   - `components` object exists with all types
+   - `profiles` object exists
+   - `metadata` object exists
+
+### Step 2: Validate Component Definitions
+
+For each component type (agents, subagents, commands, tools, plugins, contexts, config):
+
+1. Check required fields:
+   - `id` (unique)
+   - `name`
+   - `type`
+   - `path`
+   - `description`
+   - `tags` (array)
+   - `dependencies` (array)
+   - `category`
+
+2. Verify file exists at `path`
+3. Check for duplicate IDs
+4. Validate category is in defined categories
+
+### Step 3: Validate Profiles
+
+For each profile (essential, developer, business, full, advanced):
+
+1. Count components in profile
+2. Verify all component references exist in components section
+3. Check dependencies are satisfied
+4. Validate no duplicate components
+
+### Step 4: Cross-Reference with Documentation
+
+1. **navigation.md**:
+   - Extract component counts from profile descriptions
+   - Compare with actual registry counts
+   - Check profile descriptions match registry descriptions
+
+2. **docs/agents/openagent.md**:
+   - Verify delegation criteria mentioned
+   - Check context file references
+   - Validate workflow descriptions
+
+3. **docs/getting-started/installation.md**:
+   - Check profile descriptions
+   - Verify installation commands
+
+### Step 5: Validate Context File Structure
+
+1. List all files in `.plcode/context/`
+2. Check against registry context entries
+3. Identify orphaned files (exist but not in registry)
+4. Identify missing files (in registry but don't exist)
+5. Validate structure:
+   - `core/standards/` files
+   - `core/workflows/` files
+   - `core/system/` files
+   - `project/` files
+
+### Step 6: Validate Dependencies
+
+For each component with dependencies:
+
+1. Parse dependency string (format: `type:id`)
+2. Verify referenced component exists
+3. Check for circular dependencies
+4. Validate dependency chain completeness
+
+### Step 7: Generate Report
+
+Create a comprehensive report with sections:
+
+#### ✅ Validated Successfully
+
+- Registry JSON syntax
+- Component file existence
+- Profile integrity
+- Documentation accuracy
+- Context file structure
+- Dependency chains
+
+#### ⚠️ Warnings
+
+- Orphaned files (exist but not referenced)
+- Unused components (defined but not in any profile)
+- Missing descriptions or tags
+- Outdated metadata dates
+
+#### ❌ Errors
+
+- Missing files
+- Broken dependencies
+- Invalid JSON
+- Component count mismatches
+- Broken documentation references
+- Duplicate component IDs
+
+#### 📊 Statistics
+
+- Total components: X
+- Total profiles: X
+- Total context files: X
+- Components per profile breakdown
+- File coverage percentage
+
+### Step 8: Provide Recommendations
+
+Based on findings, suggest:
+
+- Files to create
+- Registry entries to add/remove
+- Documentation to update
+- Dependencies to fix
+
+## Example Report Format
+
+```markdown
+# OpenAgents Repository Validation Report
+
+Generated: 2025-11-19 14:30:00
+
+## Summary
+
+✅ 95% validation passed
+⚠️ 3 warnings found
+❌ 2 errors found
+
+---
+
+## ✅ Validated Successfully
+
+### Registry Integrity
+
+✅ JSON syntax valid
+✅ All required fields present
+✅ Schema structure correct
+
+### Component Existence (45/47 files found)
+
+✅ Agents: 3/3 files exist
+✅ Subagents: 15/15 files exist
+✅ Commands: 8/8 files exist
+✅ Tools: 2/2 files exist
+✅ Plugins: 2/2 files exist
+✅ Contexts: 13/15 files exist
+✅ Config: 2/2 files exist
+
+### Profile Consistency
+
+✅ Essential: 9 components (matches README)
+✅ Developer: 29 components (matches README)
+✅ Business: 15 components (matches README)
+✅ Full: 35 components (matches README)
+✅ Advanced: 42 components (matches README)
+
+### Documentation Accuracy
+
+✅ README component counts match registry
+✅ OpenAgent documentation up to date
+✅ Installation guide accurate
+
+---
+
+## ⚠️ Warnings (3)
+
+1. **Orphaned Context File**
+   - File: `.plcode/context/legacy/old-patterns.md`
+   - Issue: Exists but not referenced in registry
+   - Recommendation: Add to registry or remove file
+
+2. **Unused Component**
+   - Component: `workflow-orchestrator` (agent)
+   - Issue: Defined in registry but not in any profile
+   - Recommendation: Add to a profile or mark as deprecated
+
+3. **Outdated Metadata**
+   - Field: `metadata.lastUpdated`
+   - Current: 2025-11-15
+   - Recommendation: Update to current date
+
+---
+
+## ❌ Errors (2)
+
+1. **Missing Context File**
+   - Component: `context:advanced-patterns`
+   - Expected path: `.plcode/context/core/advanced-patterns.md`
+   - Referenced in: developer, full, advanced profiles
+   - Action: Create file or remove from registry
+
+2. **Broken Dependency**
+   - Component: `agent:opencoder`
+   - Dependency: `subagent:pattern-matcher`
+   - Issue: Dependency not found in registry
+   - Action: Add missing subagent or fix dependency reference
+
+---
+
+## 📊 Statistics
+
+### Component Distribution
+
+- Agents: 3
+- Subagents: 15
+- Commands: 8
+- Tools: 2
+- Plugins: 2
+- Contexts: 15
+- Config: 2
+- **Total: 47 components**
+
+### Profile Breakdown
+
+- Essential: 9 components (19%)
+- Developer: 29 components (62%)
+- Business: 15 components (32%)
+- Full: 35 components (74%)
+- Advanced: 42 components (89%)
+
+### File Coverage
+
+- Total files defined: 47
+- Files found: 45 (96%)
+- Files missing: 2 (4%)
+- Orphaned files: 1
+
+### Dependency Health
+
+- Total dependencies: 23
+- Valid dependencies: 22 (96%)
+- Broken dependencies: 1 (4%)
+- Circular dependencies: 0
+
+---
+
+## 🔧 Recommended Actions
+
+### High Priority (Errors)
+
+1. Create missing file: `.plcode/context/core/advanced-patterns.md`
+2. Fix broken dependency in `opencoder`
+
+### Medium Priority (Warnings)
+
+1. Remove orphaned file or add to registry
+2. Add `workflow-orchestrator` to a profile or deprecate
+3. Update metadata.lastUpdated to 2025-11-19
+
+### Low Priority (Improvements)
+
+1. Add more tags to components for better searchability
+2. Consider adding descriptions to all context files
+3. Document component categories in README
+
+---
+
+## Next Steps
+
+1. Review and fix all ❌ errors
+2. Address ⚠️ warnings as needed
+3. Re-run validation to confirm fixes
+4. Update documentation if needed
+
+---
+
+**Validation Complete** ✓
+```
+
+## Implementation Notes
+
+The command should:
+
+- Use bash/python for file system operations
+- Parse JSON with proper error handling
+- Generate markdown report
+- Be non-destructive (read-only validation)
+- Provide actionable recommendations
+- Support verbose mode for detailed output
+
+## Error Handling
+
+- Gracefully handle missing files
+- Continue validation even if errors found
+- Collect all issues before reporting
+- Provide clear error messages with context
+
+## Performance
+
+- Should complete in < 30 seconds
+- Cache file reads where possible
+- Parallel validation where safe
+- Progress indicators for long operations

package/.plcode/command/worktrees.md

@@ -0,0 +1,116 @@
+---
+description: Manage git worktrees for parallel development workflows
+---
+
+# Git Worktree Management
+
+You are a git workflow specialist. When provided with $ARGUMENTS, manage git worktrees to enable parallel development on multiple branches. Common arguments: "create", "list", "cleanup", or specific branch names.
+
+## Your Worktree Management Process:
+
+**Step 1: Assess Current State**
+
+- Check if git worktrees are already in use with `git worktree list`
+- Verify GitHub CLI is available and authenticated for PR operations
+- Identify the main repository directory structure
+- Check for existing `./tree` directory or similar worktree organization
+
+**Step 2: Execute Worktree Operations**
+
+### Create Worktrees for All Open PRs
+
+When $ARGUMENTS includes "prs" or "all":
+
+1. Run `gh pr list --json headRefName,title,number` to get open PRs
+2. For each PR branch:
+   - Create directory structure: `./tree/[branch-name]`
+   - Execute `git worktree add ./tree/[branch-name] [branch-name]`
+   - Handle branch names with slashes by creating nested directories
+3. Report successful worktree creation
+
+### Create Worktree for Specific Branch
+
+When $ARGUMENTS specifies a branch name:
+
+1. Check if branch exists locally or remotely
+2. Create worktree at `./tree/[branch-name]`
+3. If branch doesn't exist, offer to create it with `git worktree add -b [branch-name] ./tree/[branch-name]`
+
+### Create New Branch with Worktree
+
+When $ARGUMENTS includes "new" and a branch name:
+
+1. Prompt for base branch (default: main/master)
+2. Create new branch and worktree simultaneously
+3. Set up proper tracking if needed
+
+### List and Status Check
+
+When $ARGUMENTS includes "list" or "status":
+
+1. Show all current worktrees with `git worktree list`
+2. Check status of each worktree
+3. Identify any stale or problematic worktrees
+
+### Cleanup Operations
+
+When $ARGUMENTS includes "cleanup":
+
+1. Identify branches that no longer exist remotely
+2. Remove corresponding worktrees safely
+3. Clean up empty directories in `./tree`
+
+**Step 3: Present Worktree Report**
+
+## 📋 Worktree Management Results
+
+### 🎯 Operation Summary
+
+- **Command**: [What operation was performed]
+- **Target**: [Specific branches or "all open PRs"]
+- **Location**: [Worktree directory structure used]
+
+### 🌳 Active Worktrees
+
+```
+[List of active worktrees with format:]
+/path/to/main/repo          [main branch] (main repository)
+/path/to/tree/feature-123   [feature-123] (worktree)
+/path/to/tree/bugfix-456    [bugfix-456]  (worktree)
+```
+
+### ✅ Actions Completed
+
+- **Created**: [Number of new worktrees created]
+- **Removed**: [Number of stale worktrees cleaned up]
+- **Skipped**: [Worktrees that already existed]
+
+### 🚨 Issues Encountered
+
+- [Any problems with branch checkout or worktree creation]
+- [Missing branches or authentication issues]
+
+### 📁 Directory Structure
+
+```
+project/
+├── main repository files
+└── tree/
+    ├── feature-branch-1/
+    ├── feature-branch-2/
+    └── bugfix-branch/
+```
+
+### 🔧 Next Steps
+
+- **To work on a branch**: `cd tree/[branch-name]`
+- **To switch branches**: Use different worktree directories
+- **To clean up later**: Use `/worktrees cleanup` command
+
+## Worktree Best Practices Applied:
+
+- **Parallel Development**: Work on multiple branches simultaneously
+- **Clean Organization**: Structured directory layout in `./tree`
+- **PR Integration**: Automatic worktree creation for all open PRs
+- **Safe Cleanup**: Only remove worktrees for deleted branches
+- **Authentication Check**: Verify GitHub CLI access before PR operations

package/.plcode/command/write-plan.md

@@ -0,0 +1,5 @@
+---
+description: Create detailed implementation plan with bite-sized tasks
+---
+
+Use the writing-plans skill exactly as written

package/.plcode/command/writing-plans.md

@@ -0,0 +1,14 @@
+---
+description: Create a detailed implementation plan
+argument-hint: [design-doc-path]
+---
+
+# Write Implementation Plan
+
+**User Input:** $ARGUMENTS
+
+**Instructions:**
+
+1.  **Target:** I want to create a detailed implementation plan.
+2.  **Action:** Please **invoke/use the `writing-plans` skill** immediately.
+3.  Refer to the design document or requirements in "$ARGUMENTS" (if provided).

package/.plcode/context/content/README.md

@@ -0,0 +1,39 @@
+# Content Context
+
+This directory contains context files for content creation, copywriting, and communication guidelines.
+
+## Available Context Files
+
+### copywriting-frameworks.md
+
+Proven copywriting frameworks and persuasive writing techniques.
+
+**Topics covered**:
+
+- AIDA, PAS, BAB, FAB frameworks
+- Headline formulas
+- Emotional triggers (FOMO, social proof, authority)
+- Power words and sensory language
+- Copy checklist
+
+**Used by**: copywriter
+
+### tone-voice.md
+
+Maintaining consistent brand voice and adapting tone for different contexts.
+
+**Topics covered**:
+
+- Voice vs. tone distinction
+- Voice dimensions (formality, enthusiasm, expertise)
+- Tone guidelines by context (marketing, docs, errors, support)
+- Emotional tone mapping
+- Brand voice examples
+
+**Used by**: copywriter, technical-writer
+
+## Usage
+
+These context files are referenced by content-focused agents to ensure consistent brand voice, persuasive messaging, and appropriate tone across all communications.
+
+Agents load these files before creating content to align with established writing standards and frameworks.