@poolzin/pool-bot 2026.2.20 → 2026.2.21

package/skills/plcode-controller/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: plcode-controller
+description: "Control and operate PLCODE via CLI commands, slash commands, and multi-agent orchestration. Manage sessions, select models, delegate to agents (plan/code/review), and coordinate development workflows."
+metadata: {"poolbot":{"emoji":"🎛️","requires":{"anyBins":["plcode"]}}}
+---
+
+# PLCODE Controller
+
+## Core Rule
+
+All planning, coding, and review happens inside PLCODE.
+Use the appropriate agent for each phase of work.
+Never skip the planning phase.
+
+## Pre-flight
+
+- Confirm the user's working directory and project.
+- Ask which AI provider/model to use if not already configured.
+- Run `plcode doctor` to verify the environment is healthy.
+- Do not proceed if critical issues are detected.
+
+## Session Management
+
+- Check for existing sessions using:
+  ```
+  plcode session list
+  ```
+- If the current project already has a session, reuse it.
+- Never create a new session without user approval.
+- Sessions are tied to project directories and preserve full context.
+
+## Agent Control
+
+PLCODE uses multi-agent orchestration (AGNOS) with specialized agents. List available agents:
+
+```
+plcode agents list
+```
+
+Key agents for the standard workflow:
+
+| Agent          | Role                                         |
+| -------------- | -------------------------------------------- |
+| planner_agent  | Task analysis, step-by-step planning         |
+| code_agent     | Code implementation and refactoring          |
+| review_agent   | Code review with metrics, no subjective bias |
+| test_agent     | Test-driven development (RED-GREEN-REFACTOR) |
+| critic_agent   | Compare approaches and select best plan      |
+| executor_agent | Execute code in controlled sandbox           |
+
+Inspect any agent for details:
+
+```
+plcode agents inspect <agent-name>
+```
+
+## Model Selection
+
+- List available models:
+  ```
+  plcode models
+  ```
+- For detailed provider info:
+  ```
+  plcode models --verbose
+  ```
+- If authentication is needed:
+  ```
+  plcode auth
+  ```
+- Wait for the user to confirm auth is complete before continuing.
+
+## Planning Phase
+
+Use the `/plan` command to create structured execution plans:
+
+```
+/plan <task description>
+```
+
+The TaskPlanner will:
+
+- Analyze task complexity (simple / moderate / complex).
+- Assess risk level (low / medium / high).
+- Generate step-by-step execution plan with agent assignments.
+- Identify required MCP tools per step.
+
+Review the plan carefully:
+
+- If the plan is incorrect or incomplete, ask PLCODE to revise it.
+- If complexity is high, consider breaking into smaller tasks.
+- Do not proceed to implementation without an approved plan.
+
+## Implementation Phase
+
+Once the plan is approved, execute it. Two modes are available:
+
+- **one-shot**: Execute all steps sequentially in the current session.
+- **background**: Execute steps in the background, freeing the session.
+
+During implementation:
+
+- The code_agent handles code changes.
+- The test_agent runs tests as each step completes.
+- If a step fails, PLCODE will attempt recovery or escalate.
+
+## Review Phase
+
+After implementation, trigger a review:
+
+```
+/review
+```
+
+The review_agent evaluates:
+
+- Code quality and adherence to standards.
+- Test coverage and correctness.
+- Security and performance implications.
+
+If the review flags issues, return to the planning phase for that specific issue.
+
+## Question Handling
+
+If PLCODE or any agent asks a clarification question during implementation:
+
+- Pause implementation.
+- Provide the answer or switch context to the planner_agent.
+- Confirm the revised approach before resuming.
+- Never ignore questions during implementation.
+
+## Completion
+
+- Repeat the Plan -> Implement -> Review loop until all requirements are satisfied.
+- Never skip the planning phase.
+- Never bypass review for non-trivial changes.
+- Use `plcode session list` to verify session state.
+
+## MCP Tools Available
+
+PLCODE exposes 32+ MCP tools across 5 categories:
+
+| Category      | Tools | Examples                                                     |
+| ------------- | ----- | ------------------------------------------------------------ |
+| Observability | 7     | `get_service_health`, `get_bra_health`, `get_memory_metrics` |
+| Git           | 8     | `get_repo_structure`, `get_diff`, `open_pull_request`        |
+| LSP           | 9     | `lsp_diagnostics`, `find_references`, `code_metrics`         |
+| Knowledge     | 5     | `check_dependency_cves`, `analyze_dependencies`              |
+| Web           | 3     | `web_search`, `web_fetch`, `web_extract`                     |
+
+## Output Format
+
+- Show all CLI commands and slash commands explicitly.
+- State which agent is active and what mode is selected.
+- Provide auth links verbatim when they appear.
+- Display plan summaries with complexity and risk assessments.

package/skills/plcode-controller/assets/operator-prompts.md

@@ -0,0 +1,65 @@
+### Ask for Provider
+
+Which AI provider and model do you want to use?
+Run `plcode models` to see what's available.
+
+### Ask for Auth
+
+The selected provider requires authentication.
+Run `plcode auth` to authenticate, then confirm when you're ready.
+
+### Environment Check
+
+Let me verify your environment is ready.
+Running `plcode doctor` to check for issues.
+
+### Plan Request
+
+Analyze this task and create a structured execution plan.
+Break it into clear steps, assign the right agent to each step, and identify which MCP tools are needed.
+Flag any risks or questions before we start.
+
+### Plan Revision
+
+The plan needs changes. Here's what to adjust:
+[specify issues]
+Please revise the plan and present the updated version.
+
+### Implementation Request
+
+The plan is approved. Proceed with implementation using the assigned agents and tools.
+Report progress after each step.
+
+### Review Request
+
+Implementation is complete. Run a review to check:
+
+- Code quality and standards compliance
+- Test coverage and correctness
+- Security and performance implications
+
+### Parallel Dispatch
+
+This task has independent subtasks. Dispatching parallel agents:
+
+- Agent A: [subtask 1]
+- Agent B: [subtask 2]
+- Agent C: [subtask 3]
+
+Each agent works independently. I'll integrate results when all complete.
+
+### Session Reuse Check
+
+I found an existing session for this project.
+Do you want to continue from where we left off, or start fresh?
+
+### Failure Report
+
+Step [N] failed during execution.
+Error: [error details]
+Options:
+
+1. Retry the step
+2. Skip and continue
+3. Abort the plan and re-plan
+   Which do you prefer?

package/skills/plcode-controller/references/command-cheatsheet.md

@@ -0,0 +1,53 @@
+## PLCODE Command Cheatsheet
+
+### CLI Commands
+
+| Command                         | Description                                  |
+| ------------------------------- | -------------------------------------------- |
+| `plcode`                        | Start PLCODE (TUI mode)                      |
+| `plcode run <prompt>`           | Run a one-shot task                          |
+| `plcode session list`           | List all sessions                            |
+| `plcode agents list`            | List all available agents (PLCODE + AGNOS)   |
+| `plcode agents inspect <agent>` | Show agent details and capabilities          |
+| `plcode agents test [agent]`    | Test agent connectivity                      |
+| `plcode agents restart [agent]` | Restart an agent                             |
+| `plcode models`                 | List available AI providers and models       |
+| `plcode models --verbose`       | Detailed model info with capabilities        |
+| `plcode models --refresh`       | Force refresh model list                     |
+| `plcode auth`                   | Authenticate with an AI provider             |
+| `plcode doctor`                 | Check environment health                     |
+| `plcode status`                 | Show current session and system status       |
+| `plcode logs`                   | View recent logs                             |
+| `plcode tools`                  | List available MCP tools                     |
+| `plcode bra`                    | BRA (Background Repository Agent) management |
+| `plcode mcp`                    | MCP server management                        |
+| `plcode stats`                  | Show usage statistics                        |
+| `plcode debug`                  | Debug mode                                   |
+| `plcode export`                 | Export session data                          |
+| `plcode import`                 | Import session data                          |
+| `plcode upgrade`                | Upgrade PLCODE                               |
+| `plcode acp`                    | Git add, commit, push in one command         |
+
+### Slash Commands (Inside TUI)
+
+| Command   | Description                                         |
+| --------- | --------------------------------------------------- |
+| `/plan`   | Create a structured execution plan with TaskPlanner |
+| `/review` | Trigger code review via review_agent                |
+| `/init`   | Initialize project configuration                    |
+
+### Keyboard Shortcuts (TUI)
+
+| Key      | Action                   |
+| -------- | ------------------------ |
+| `Enter`  | Send message             |
+| `Ctrl+C` | Cancel current operation |
+| `Ctrl+D` | Exit PLCODE              |
+
+### AGNOS Multi-Agent Commands
+
+| Command                     | Description                              |
+| --------------------------- | ---------------------------------------- |
+| `plcode agnos`              | AGNOS orchestration management           |
+| `plcode task <description>` | Dispatch a task to the appropriate agent |
+| `plcode agent <name>`       | Interact with a specific agent directly  |

package/skills/plcode-controller/references/failure-handling.md

@@ -0,0 +1,60 @@
+## Common Failures and Responses
+
+### Authentication Fails
+
+- Run `plcode auth` again
+- Ask the user to verify their credentials or API key
+- Do not proceed without confirmed authentication
+
+### Model Not Available
+
+- Run `plcode models --refresh` to update the model list
+- Inform the user which models are available
+- Ask for an alternative provider or model
+
+### Plan Generation Fails
+
+- Simplify the task description
+- Break into smaller sub-tasks
+- Check if required MCP tools are available with `plcode tools`
+
+### Agent Not Responding
+
+- Check agent status: `plcode agents inspect <agent-name>`
+- Restart the agent: `plcode agents restart <agent-name>`
+- If persistent, check BRA health: use `get_bra_health` MCP tool
+
+### Circuit Breaker Tripped
+
+- A circuit breaker trips after repeated failures on the same operation
+- Wait for the cooldown period (automatic)
+- Check which circuit tripped via `get_bra_health`
+- The circuit will auto-reset; retry after the cooldown
+
+### Memory Pressure
+
+- PLCODE monitors memory pressure at 4 levels: normal, warning, critical, emergency
+- At warning (70%): automatic pruning of expired entries
+- At critical (85%): aggressive cleanup + forced GC
+- At emergency (95%): full data cleanup
+- If operations slow down, check with `get_memory_metrics`
+
+### Session Issues
+
+- If session state is corrupt, list sessions: `plcode session list`
+- Start a new session only with user approval
+- Export important session data first: `plcode export`
+
+### MCP Tool Errors
+
+- Verify tool availability: `plcode tools`
+- Check MCP server status: `plcode mcp`
+- Some tools require specific permissions or connections
+- Retry once before reporting failure to the user
+
+### Step Execution Fails During Plan
+
+- The TaskPlanner will attempt automatic recovery
+- If recovery fails, it escalates to the user
+- Options: retry the step, skip the step, or abort the plan
+- Never silently skip a failed step

package/skills/plcode-controller/references/model-selection.md

@@ -0,0 +1,57 @@
+## Model Selection Procedure
+
+### List Available Models
+
+```
+plcode models
+```
+
+For detailed capabilities and pricing info:
+
+```
+plcode models --verbose
+```
+
+To force refresh the model list from providers:
+
+```
+plcode models --refresh
+```
+
+### Select a Provider
+
+- The user specifies which provider/model they want to use
+- PLCODE supports multiple providers (Anthropic, OpenAI, etc.)
+- Each provider may have different authentication requirements
+
+### Authentication
+
+If the selected provider requires authentication:
+
+```
+plcode auth
+```
+
+- PLCODE will guide through the auth flow
+- If a login URL is generated, copy it exactly and send it to the user
+- Wait for the user to confirm authentication is complete
+- Never assume authentication succeeded without confirmation
+
+### Switching Models Mid-Session
+
+- Models can be changed during a session
+- Run `plcode models` again to switch
+- Existing session context is preserved across model changes
+
+### Model Selection for Agents
+
+- Different agents may use different models
+- The planner_agent benefits from high-reasoning models
+- The code_agent works best with code-specialized models
+- Model assignment per agent is configured in PLCODE settings
+
+### Troubleshooting
+
+- If a model is listed but fails to respond, check auth status
+- If no models appear, run `plcode models --refresh`
+- If a provider is not listed, it may need to be configured first

package/skills/plcode-controller/references/plan-vs-build.md

@@ -0,0 +1,52 @@
+## Planning Phase
+
+Uses the `/plan` command and TaskPlanner:
+
+- Analyzes task complexity (simple / moderate / complex)
+- Assesses risk level (low / medium / high)
+- Generates step-by-step execution plan
+- Assigns the right agent to each step
+- Identifies required MCP tools per step
+- No code is written during planning
+
+Key agents in planning:
+
+- **planner_agent**: Creates execution plans
+- **critic_agent**: Compares approaches and selects the best plan
+
+## Implementation Phase
+
+Executes the approved plan:
+
+- **code_agent**: Writes and refactors code
+- **test_agent**: Writes tests (TDD: RED-GREEN-REFACTOR)
+- **executor_agent**: Runs code in sandbox
+- Two execution modes:
+  - `one-shot`: Sequential execution in current session
+  - `background`: Background execution, frees the session
+
+## Review Phase
+
+Uses the `/review` command:
+
+- **review_agent**: Metrics-based code review (no subjective decisions)
+- Checks code quality, test coverage, security, performance
+- Flags issues for re-planning if needed
+
+## Phase Switching
+
+| Transition          | When                                                  |
+| ------------------- | ----------------------------------------------------- |
+| Plan -> Implement   | Plan approved by user                                 |
+| Implement -> Plan   | Question arises, step fails, or approach needs change |
+| Implement -> Review | All implementation steps complete                     |
+| Review -> Plan      | Review flags issues that need re-planning             |
+| Review -> Done      | All checks pass, no issues found                      |
+
+## Rules
+
+- Always start with Plan for non-trivial tasks
+- Never write code during the planning phase
+- Never skip review for changes touching multiple files
+- If implementation raises questions, pause and return to Plan
+- The plan must include agent assignments and MCP tool requirements

package/skills/plcode-controller/references/question-handling.md

@@ -0,0 +1,40 @@
+## Handling Questions During Execution
+
+### From Agents During Implementation
+
+If any agent asks a clarification question during implementation:
+
+1. Pause the current execution step immediately
+2. Present the question to the user clearly
+3. Wait for the user's answer
+4. Feed the answer back to the planner_agent if it affects the plan
+5. Revise the plan if needed
+6. Resume implementation only after the question is resolved
+
+### From the User
+
+If the user asks a question mid-workflow:
+
+1. Pause current execution
+2. Answer using available context (session history, plan state, code state)
+3. If the question implies a change in direction, return to the planning phase
+4. If it's informational only, answer and resume
+
+### Escalation Pattern
+
+PLCODE uses an escalation pattern for unresolved questions:
+
+| Level | Handler       | When                                                 |
+| ----- | ------------- | ---------------------------------------------------- |
+| 1     | Current agent | Agent can answer from its own context                |
+| 2     | planner_agent | Question affects the plan or approach                |
+| 3     | critic_agent  | Multiple valid approaches, need to pick the best     |
+| 4     | User          | Decision requires human judgment or domain knowledge |
+
+### Rules
+
+- Never ignore a question and continue implementing
+- Never make assumptions about ambiguous requirements
+- If in doubt, escalate to the user rather than guessing
+- Questions that affect the plan must go through the planner_agent
+- Questions about code style or conventions can be handled by the code_agent

package/skills/plcode-controller/references/session-management.md

@@ -0,0 +1,63 @@
+## Session Rules
+
+### Core Principles
+
+- PLCODE keeps a full history of sessions per project
+- The same project must always reuse its existing session
+- Reusing sessions preserves context, decisions, and plan history
+- Starting a new session is allowed only if the user explicitly asks
+
+### Listing Sessions
+
+```
+plcode session list
+```
+
+Output includes:
+
+- Session ID
+- Project directory
+- Creation timestamp
+- Last activity
+- Parent session (if any)
+
+### Session Reuse
+
+- When starting work on a project, always check for existing sessions first
+- If a session exists for the current project directory, use it
+- Session context includes: conversation history, plan state, agent state, MCP tool state
+
+### Creating New Sessions
+
+- Only create a new session when:
+  - No session exists for the project
+  - The user explicitly requests a fresh start
+  - The existing session is corrupt or unrecoverable
+- Before creating a new session, consider exporting the old one:
+  ```
+  plcode export
+  ```
+
+### Session Data
+
+Sessions store:
+
+- Full conversation history
+- Active and completed plans
+- Agent delegation history
+- MCP tool invocations and results
+- Model/provider selections
+
+### Importing and Exporting
+
+- Export session: `plcode export`
+- Import session: `plcode import`
+- Useful for backup, migration, or sharing context between machines
+
+### Parent Sessions
+
+- Sessions can have parent sessions, forming a hierarchy
+- Child sessions inherit context from their parent
+- Useful for branching exploration without losing the main thread
+
+If unsure whether to reuse or create, always ask the user.

package/skills/plcode-controller/references/workflow.md

@@ -0,0 +1,35 @@
+## Standard Workflow
+
+1. Verify environment health with `plcode doctor`
+2. Confirm AI provider and model with the user
+3. Authenticate if needed using `plcode auth`
+4. Reuse existing project session via `plcode session list`
+5. Use `/plan <task>` to create a structured execution plan
+6. Review the plan: check complexity, risk, agent assignments
+7. Approve or revise the plan
+8. Execute the plan (one-shot or background mode)
+9. Handle interruptions: if questions arise, pause and clarify before resuming
+10. Run `/review` to evaluate implemented changes
+11. If review flags issues, return to step 5 for the specific issue
+12. Repeat until all user requirements are satisfied
+
+## Delegation Workflow (Complex Tasks)
+
+For tasks involving multiple independent subsystems:
+
+1. Use `/plan` to break the task into subtasks
+2. Identify independent subtasks that can run in parallel
+3. Dispatch parallel agents using the Task tool (one agent per domain)
+4. Review each agent's output when complete
+5. Verify changes don't conflict
+6. Run full test suite
+7. Integrate all changes
+
+## Quick Fix Workflow (Simple Tasks)
+
+For trivial changes that don't need full orchestration:
+
+1. Describe the change directly
+2. code_agent implements it
+3. Verify with a targeted test run
+4. Done -- no formal plan/review needed for single-line fixes