@poolzin/plcode 2.1.1 → 3.0.0

package/.plcode/command/openagents/new-agents/templates/agent-template.md

@@ -0,0 +1,123 @@
+---
+description: "{one-line purpose of this agent}"
+mode: primary
+temperature: 0.1
+tools:
+  read: true
+  write: true
+  edit: true
+  bash: true
+  task: false # Only if delegates to subagents
+  glob: true
+  grep: true
+permissions:
+  bash:
+    "rm -rf *": "ask"
+    "sudo *": "deny"
+    "chmod *": "ask"
+  edit:
+    "**/*.env*": "deny"
+    "**/*.key": "deny"
+    "**/*.secret": "deny"
+---
+
+# {Agent Name}
+
+<role>
+{Clear, concise role - what this agent does in one sentence}
+</role>
+
+<approach>
+1. Read and understand the context
+2. Think about the approach before acting
+3. Implement changes incrementally
+4. Verify each step with appropriate tools
+5. Complete with clear summary
+</approach>
+
+<heuristics>
+- Decompose problems before implementing
+- Use tools intentionally (not speculatively)
+- Verify outputs before claiming completion
+- Stop on errors and report (don't auto-fix blindly)
+</heuristics>
+
+<output>
+Always include:
+- What you did
+- Why you did it that way
+- Test/validation results
+</output>
+
+<tools>
+  <tool name="read">
+    <purpose>Load specific files for analysis or modification</purpose>
+    <when_to_use>You need to examine file contents</when_to_use>
+    <when_not_to_use>You already have the file content in context</when_not_to_use>
+  </tool>
+  
+  <tool name="write">
+    <purpose>Create new files or overwrite existing ones</purpose>
+    <when_to_use>Creating new files or completely replacing file contents</when_to_use>
+    <when_not_to_use>Making small changes to existing files (use edit instead)</when_not_to_use>
+  </tool>
+  
+  <tool name="edit">
+    <purpose>Make targeted changes to existing files</purpose>
+    <when_to_use>Modifying specific sections of existing files</when_to_use>
+    <when_not_to_use>Creating new files or replacing entire files (use write instead)</when_not_to_use>
+  </tool>
+  
+  <tool name="bash">
+    <purpose>Execute commands for testing, building, linting, etc.</purpose>
+    <when_to_use>Running tests, type checks, linters, builds</when_to_use>
+    <when_not_to_use>Risky operations without approval (rm, sudo, etc.)</when_not_to_use>
+  </tool>
+  
+  <tool name="glob">
+    <purpose>Find files matching patterns</purpose>
+    <when_to_use>You need to discover files by name/pattern</when_to_use>
+    <when_not_to_use>You already know the exact file path</when_not_to_use>
+  </tool>
+  
+  <tool name="grep">
+    <purpose>Search file contents for patterns</purpose>
+    <when_to_use>You need to find code/text within files</when_to_use>
+    <when_not_to_use>You need to find files by name (use glob instead)</when_not_to_use>
+  </tool>
+</tools>
+
+<examples>
+  <example name="Typical Use Case">
+    **User**: "{typical request for this agent}"
+    
+    **Agent**:
+    1. Read relevant files to understand context
+    2. Think about approach: "{reasoning}"
+    3. Implement change: "{what was done}"
+    4. Verify: "{validation performed}"
+    
+    **Result**: {Expected outcome}
+  </example>
+</examples>
+
+<validation>
+  <pre_flight>
+    - Required files/context available
+    - Tools needed are accessible
+    - Clear understanding of task
+  </pre_flight>
+  
+  <post_flight>
+    - Changes implemented correctly
+    - Tests/validation passing
+    - Output meets requirements
+  </post_flight>
+</validation>
+
+<principles>
+  <minimal_prompt>Keep system prompt ~500 tokens at "right altitude"</minimal_prompt>
+  <just_in_time>Load context on demand, not pre-loaded</just_in_time>
+  <tool_clarity>Use tools intentionally with clear purpose</tool_clarity>
+  <outcome_focused>Measure: Does it solve the task?</outcome_focused>
+</principles>

package/.plcode/command/openagents/new-agents/templates/context-template.md

@@ -0,0 +1,37 @@
+# {Agent Name} Context
+
+## Key Commands
+
+- {command 1}: {what it does}
+- {command 2}: {what it does}
+- {command 3}: {what it does}
+
+## File Structure
+
+- {path pattern}: {what goes here}
+- {path pattern}: {what goes here}
+- {path pattern}: {what goes here}
+
+## Code Style
+
+- {style rule 1}
+- {style rule 2}
+- {style rule 3}
+
+## Workflow Rules
+
+- {workflow rule 1}
+- {workflow rule 2}
+- {workflow rule 3}
+
+## Common Patterns
+
+- {pattern 1}: {when to use}
+- {pattern 2}: {when to use}
+- {pattern 3}: {when to use}
+
+## Before Committing
+
+1. {check 1}
+2. {check 2}
+3. {check 3}

package/.plcode/command/openagents/new-agents/templates/test-1-planning-approval.yaml

@@ -0,0 +1,41 @@
+id: planning-approval-001
+name: Planning & Approval Workflow
+description: |
+  Tests that {agent-name} creates a plan before implementation and requests approval.
+  Verifies the agent follows plan-first approach and doesn't execute without approval.
+
+category: planning
+agent: { agent-name }
+model: anthropic/claude-sonnet-4-5
+
+prompt: |
+  Create a simple function that adds two numbers.
+  The function should be called 'add' and take two parameters.
+
+behavior:
+  # Agent should create plan first and request approval
+  mustContain:
+    - "plan"
+    - "approval"
+    - "Approval needed"
+    - "proceed"
+  # Should NOT execute immediately
+  mustNotUseInFirstN:
+    tools: [write, edit]
+    n: 2 # First 2 tool calls
+
+expectedViolations:
+  - rule: approval-gate
+    shouldViolate: false
+    severity: error
+
+approvalStrategy:
+  type: manual
+  # Don't approve - test should stop at planning stage
+
+timeout: 30000
+
+tags:
+  - planning
+  - approval
+  - critical

package/.plcode/command/openagents/new-agents/templates/test-2-context-loading.yaml

@@ -0,0 +1,36 @@
+id: context-before-code-001
+name: Context Loading Before Code
+description: |
+  Tests that {agent-name} loads relevant context files before writing code.
+  Verifies context is loaded BEFORE any write/edit operations (just-in-time retrieval).
+
+category: context-loading
+agent: { agent-name }
+model: anthropic/claude-sonnet-4-5
+
+prompt: |
+  Write a simple utility function following our coding standards.
+
+behavior:
+  # Should read context files first
+  mustUseInOrder:
+    - [read] # Context files
+    - [write, edit] # Then code
+  # Should reference standards/context
+  mustContain:
+    - "standard"
+
+expectedViolations:
+  - rule: context-loading
+    shouldViolate: false
+    severity: error
+
+approvalStrategy:
+  type: auto-approve
+
+timeout: 30000
+
+tags:
+  - context
+  - just-in-time
+  - critical

package/.plcode/command/openagents/new-agents/templates/test-3-incremental.yaml

@@ -0,0 +1,38 @@
+id: incremental-001
+name: Incremental Implementation
+description: |
+  Tests that {agent-name} implements features step-by-step with validation.
+  Verifies one step at a time, not all at once, with validation after each step.
+
+category: implementation
+agent: { agent-name }
+model: anthropic/claude-sonnet-4-5
+
+prompt: |
+  Implement a simple calculator with add, subtract, multiply, and divide functions.
+  Make sure to test each function after implementing it.
+
+behavior:
+  # Should implement incrementally
+  minToolCalls: 4 # Multiple steps
+  # Should validate after each step
+  mustUseAnyOf: [[bash]] # For running tests/validation
+  # Should NOT implement everything at once
+  mustNotContain:
+    - "all at once"
+    - "complete implementation"
+
+expectedViolations:
+  - rule: incremental-execution
+    shouldViolate: false
+    severity: error
+
+approvalStrategy:
+  type: auto-approve
+
+timeout: 60000
+
+tags:
+  - implementation
+  - incremental
+  - validation

package/.plcode/command/openagents/new-agents/templates/test-4-tool-usage.yaml

@@ -0,0 +1,35 @@
+id: tool-usage-001
+name: Tool Usage Clarity
+description: |
+  Tests that {agent-name} uses tools correctly based on their definitions.
+  Verifies agent follows tool purpose, when_to_use, and when_not_to_use guidelines.
+
+category: implementation
+agent: { agent-name }
+model: anthropic/claude-sonnet-4-5
+
+prompt: |
+  Find all TypeScript files in the src directory and check if they use proper imports.
+
+behavior:
+  # Should use glob to find files and grep to search contents
+  mustUseAnyOf: [[glob], [grep]]
+  # Should NOT use bash for file finding
+  mustNotContain:
+    - "ls -la"
+    - "find ."
+
+expectedViolations:
+  - rule: tool-clarity
+    shouldViolate: false
+    severity: warning
+
+approvalStrategy:
+  type: auto-approve
+
+timeout: 30000
+
+tags:
+  - tools
+  - clarity
+  - best-practice

package/.plcode/command/openagents/new-agents/templates/test-5-error-handling.yaml

@@ -0,0 +1,49 @@
+id: stop-on-failure-001
+name: Stop on Failure
+description: |
+  Tests that {agent-name} stops on test/build failures and reports issues.
+  Verifies agent doesn't auto-fix without understanding the problem.
+
+category: error-handling
+agent: { agent-name }
+model: anthropic/claude-sonnet-4-5
+
+prompt: |
+  Run the tests in the test suite. If any fail, report the failures.
+
+# Setup: Create a failing test
+setup:
+  - action: write
+    file: test_example.py
+    content: |
+      def test_failing():
+          assert 1 == 2, "This test should fail"
+
+behavior:
+  # Should run tests
+  mustUseAnyOf: [[bash]]
+  # Should detect failure and report
+  mustContain:
+    - "fail"
+    - "error"
+    - "report"
+  # Should STOP and report (not auto-fix)
+  mustNotContain:
+    - "fixing"
+    - "correcting"
+    - "let me fix"
+
+expectedViolations:
+  - rule: stop-on-failure
+    shouldViolate: false
+    severity: error
+
+approvalStrategy:
+  type: auto-approve
+
+timeout: 30000
+
+tags:
+  - error-handling
+  - stop-on-failure
+  - critical

package/.plcode/command/openagents/new-agents/templates/test-6-extended-thinking.yaml

@@ -0,0 +1,42 @@
+id: extended-thinking-001
+name: Extended Thinking for Decomposition
+description: |
+  Tests that {agent-name} uses extended thinking for complex tasks.
+  Verifies agent decomposes problems before jumping to implementation.
+
+category: implementation
+agent: { agent-name }
+model: anthropic/claude-sonnet-4-5
+
+prompt: |
+  Think hard about how to implement a user authentication system.
+  What files need to change? What are the dependencies? What should we test?
+
+behavior:
+  # Should think before acting and decompose the problem
+  mustContain:
+    - "think"
+    - "approach"
+    - "dependencies"
+    - "files"
+    - "changes"
+    - "test"
+  # Should NOT jump straight to implementation
+  mustNotUseInFirstN:
+    tools: [write, edit]
+    n: 3 # First 3 tool calls
+
+expectedViolations:
+  - rule: extended-thinking
+    shouldViolate: false
+    severity: warning
+
+approvalStrategy:
+  type: auto-approve
+
+timeout: 45000
+
+tags:
+  - thinking
+  - decomposition
+  - planning

package/.plcode/command/openagents/new-agents/templates/test-7-compaction.yaml

@@ -0,0 +1,38 @@
+id: compaction-001
+name: Compaction for Long Sessions
+description: |
+  Tests that {agent-name} can handle long-horizon tasks with compaction.
+  Verifies agent summarizes when context fills and preserves critical info.
+
+category: long-horizon
+agent: { agent-name }
+model: anthropic/claude-sonnet-4-5
+
+prompt: |
+  Implement a multi-step feature across several files.
+  Keep notes of architectural decisions and progress.
+
+behavior:
+  # Should handle multiple steps
+  minToolCalls: 5
+  # Should maintain notes/progress and summarize
+  mustContain:
+    - "progress"
+    - "decision"
+    - "summary"
+    - "completed"
+
+expectedViolations:
+  - rule: compaction
+    shouldViolate: false
+    severity: warning
+
+approvalStrategy:
+  type: auto-approve
+
+timeout: 90000
+
+tags:
+  - long-horizon
+  - compaction
+  - notes

package/.plcode/command/openagents/new-agents/templates/test-8-completion.yaml

@@ -0,0 +1,38 @@
+id: handoff-001
+name: Completion Handoff
+description: |
+  Tests that {agent-name} provides clear completion output.
+  Verifies agent includes what was done, why, and results.
+
+category: completion
+agent: { agent-name }
+model: anthropic/claude-sonnet-4-5
+
+prompt: |
+  Create a simple calculator function. When done, provide a summary.
+
+behavior:
+  # Should complete implementation
+  mustUseAnyOf: [[write, edit]]
+  # Should provide clear output with what/why/results
+  mustContain:
+    - "what"
+    - "why"
+    - "result"
+    - "complete"
+    - "summary"
+
+expectedViolations:
+  - rule: completion-output
+    shouldViolate: false
+    severity: warning
+
+approvalStrategy:
+  type: auto-approve
+
+timeout: 45000
+
+tags:
+  - completion
+  - handoff
+  - output

package/.plcode/command/openagents/new-agents/templates/test-config-template.yaml

@@ -0,0 +1,27 @@
+# {Agent Name} Test Configuration
+
+agent: { agent-name }
+description: { agent description }
+
+# Default settings for all tests
+defaults:
+  model: anthropic/claude-sonnet-4-5
+  timeout: 60000
+  approvalStrategy:
+    type: auto-approve
+
+# Test discovery paths
+testPaths:
+  - tests/planning
+  - tests/context-loading
+  - tests/implementation
+  - tests/error-handling
+  - tests/long-horizon
+  - tests/completion
+
+# Agent-specific expectations
+expectations:
+  requiresTextApproval: true
+  usesToolPermissions: true
+  loadsContextOnDemand: true
+  responsePrefix: "" # e.g., "DIGGING IN..." if agent has one