pi-subagents-router 1.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Asdrubal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,119 @@
+# Pi Subagents Router Extension
+
+A TypeScript extension for Pi that intelligently routes tasks to appropriate agent types based on task descriptions using `useWhen` and `avoidWhen` criteria.
+
+## Features
+
+- **Automatic Agent Routing**: Analyzes task descriptions and automatically selects the best agent type
+- **Custom Tools**: Provides tools for manual routing (`route_agent`) and agent information (`list_agents`)
+- **Custom Commands**: Includes `/assign-agent` command for manual routing
+- **Input Interception**: Automatically routes tasks based on natural language input
+- **Configurable Agents**: Easy to extend with additional agent types and criteria
+- **Second-best Fallback**: When the top agent is penalized, tries the next best alternative instead of giving up
+
+## Routing Algorithm
+
+```
+1. Scans ALL trigger keywords across ALL agents, picks the earliest position in input text
+2. Scoring: counts useWhen matches per agent (most matches = highest score)
+3. Check avoidWhen penalties (keyword found → penalize that agent)
+4. If top-scoring agent is penalized, find the next-highest unpenalized agent (fallback)
+5. If all agents penalized, fall back to general-purpose
+```
+
+> **Key improvement** (v1.1): Trigger matching is now **text-order aware** — the earliest keyword in the input determines routing priority. For example, \"implement documentation\" routes to the software-engineer (\"implement\" at pos 0) instead of the documenter (\"documentation\" at pos 9).
+
+## Usage
+
+### Automatic Routing
+
+The extension automatically analyzes your input and routes to the appropriate agent:
+
+```
+User: "Create documentation for the new API endpoint"
+→ Automatically routed to: documenter
+
+User: "Research the latest React hooks best practices"
+→ Automatically routed to: researcher
+
+User: "Implement the user authentication feature"
+→ Automatically routed to: software-engineer
+```
+
+### Manual Routing
+
+Use the `/assign-agent` command:
+
+```
+/assign-agent Create comprehensive documentation for the database schema
+```
+
+### List Available Agents
+
+```
+Use the list_agents tool to see all available agents and their criteria.
+```
+
+### Force Specific Agent
+
+```
+Use the route_agent tool with forceAgent parameter to override automatic routing.
+```
+
+## Agent Configuration
+
+The extension comes with predefined agents:
+
+### Documenter
+- **Description**: Documentation specialist responsible for creating and maintaining project documentation
+- **Use When**: documentation creation, knowledge documentation, technical writing
+- **Avoid When**: implementation, testing, deployment operations
+- **Triggers**: documentation, docs, write docs, documentation update, README
+
+### Researcher  
+- **Description**: Research specialist responsible for information gathering, analysis, and evidence-based insights
+- **Use When**: information gathering, market research, technical research, competitive analysis
+- **Avoid When**: implementation, debugging, testing
+- **Triggers**: research, investigate, find information, look up
+
+### Software Engineer
+- **Description**: Senior software engineering implementation specialist
+- **Use When**: software development, coding, implementation, feature development
+- **Avoid When**: documentation, research, testing
+- **Triggers**: code, implement, build, develop, program
+
+### Reviewer
+- **Description**: Code quality reviewer responsible for validating implementation quality
+- **Use When**: code review, quality assurance, architecture review, security review
+- **Avoid When**: implementation, documentation, research
+- **Triggers**: review, audit, check, validate
+
+## Customization
+
+To add or modify agent configurations:
+
+1. Edit the `agents` array in `src/agent-router.ts`
+2. Add new agent configurations with appropriate `useWhen`, `avoidWhen`, and `triggers`
+3. Reload the extension with `/reload`
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Run tests
+npx tsx test/test-routing.ts
+```
+
+## License
+
+MIT License
+
+## Contributing
+
+Pull requests are welcome! Please open an issue first to discuss major changes.
+
+## Support
+
+For issues and questions, please open a GitHub issue.

package/dist/AgentConfig.d.ts

@@ -0,0 +1,52 @@
+/**
+ * AgentConfig — Shared type for all agents (builtin + filesystem).
+ *
+ * This file extracts the AgentConfig interface from the monolithic
+ * agent-router.ts so it can be imported by all modules.
+ */
+export type AgentSource = "builtin" | "filesystem";
+export interface AgentConfig {
+    name: string;
+    description: string;
+    thinking?: string;
+    tools?: string[];
+    systemPromptMode?: string;
+    inheritProjectContext?: boolean;
+    inheritSkills?: boolean;
+    triggers?: string[];
+    useWhen?: string[];
+    avoidWhen?: string[];
+    capabilities?: string[];
+    consumes?: string[];
+    produces?: string[];
+    dependsOn?: string[];
+    source?: AgentSource;
+}
+/**
+ * Simple routing decision
+ */
+export interface RoutingDecision {
+    agentType: string;
+    reason: string;
+}
+/**
+ * Route result — single agent
+ */
+export interface RouteResult {
+    success: boolean;
+    error?: string;
+    agentId?: string;
+    agentType?: string;
+    reason?: string;
+    details?: Record<string, any>;
+}
+/**
+ * Plan result — multi-agent workflow
+ */
+export interface PlanResult {
+    success: boolean;
+    error?: string;
+    agents?: string[];
+    steps?: string[];
+    results?: Record<string, any>;
+}

package/dist/AgentConfig.js

@@ -0,0 +1,7 @@
+/**
+ * AgentConfig — Shared type for all agents (builtin + filesystem).
+ *
+ * This file extracts the AgentConfig interface from the monolithic
+ * agent-router.ts so it can be imported by all modules.
+ */
+export {};

package/dist/BuiltinAgents.d.ts

@@ -0,0 +1,10 @@
+/**
+ * BuiltinAgents — The 4 hardcoded agents extracted from agent-router.ts
+ */
+import type { AgentConfig } from "./AgentConfig.ts";
+export declare const BUILTIN_AGENTS: AgentConfig[];
+/**
+ * Simple keyword → capability mapping for built-in routing.
+ * Used when capabilities are not explicitly declared on agents.
+ */
+export declare const KEYWORD_TO_CAPABILITY: Record<string, string[]>;

package/dist/BuiltinAgents.js

@@ -0,0 +1,156 @@
+/**
+ * BuiltinAgents — The 4 hardcoded agents extracted from agent-router.ts
+ */
+export const BUILTIN_AGENTS = [
+    {
+        name: "documenter",
+        description: "Documentation specialist responsible for creating and maintaining project documentation",
+        thinking: "high",
+        tools: [
+            "read",
+            "grep",
+            "find",
+            "ls",
+            "bash",
+            "edit",
+            "write",
+            "contact_supvisor",
+        ],
+        systemPromptMode: "replace",
+        inheritProjectContext: true,
+        inheritSkills: false,
+        triggers: [
+            "documentation",
+            "docs",
+            "write docs",
+            "documentation update",
+            "README",
+        ],
+        useWhen: [
+            "documentation creation",
+            "knowledge documentation",
+            "technical writing",
+        ],
+        avoidWhen: [
+            "implementation",
+            "testing",
+            "deployment operations",
+        ],
+        capabilities: ["documentation", "knowledge", "writing"],
+        produces: ["docs", "readme", "technical-writing"],
+        source: "builtin",
+    },
+    {
+        name: "researcher",
+        description: "Research specialist responsible for information gathering, analysis, and evidence-based insights",
+        thinking: "high",
+        tools: [
+            "read",
+            "grep",
+            "find",
+            "ls",
+            "bash",
+            "web_search",
+            "fetch_content",
+        ],
+        systemPromptMode: "replace",
+        inheritProjectContext: true,
+        inheritSkills: true,
+        triggers: [
+            "research",
+            "investigate",
+            "find information",
+            "look up",
+        ],
+        useWhen: [
+            "information gathering",
+            "market research",
+            "technical research",
+            "competitive analysis",
+        ],
+        avoidWhen: ["implementation", "debugging", "testing"],
+        capabilities: ["research", "analysis", "information-gathering"],
+        produces: ["research-report", "findings", "evidence"],
+        source: "builtin",
+    },
+    {
+        name: "software-engineer",
+        description: "Senior software engineering implementation specialist",
+        thinking: "medium",
+        tools: [
+            "read",
+            "grep",
+            "find",
+            "ls",
+            "bash",
+            "edit",
+            "write",
+            "contact_supvisor",
+        ],
+        systemPromptMode: "replace",
+        inheritProjectContext: true,
+        inheritSkills: true,
+        triggers: ["code", "implement", "build", "develop", "program"],
+        useWhen: [
+            "software development",
+            "coding",
+            "implementation",
+            "feature development",
+        ],
+        avoidWhen: [
+            "documentation",
+            "research",
+            "testing",
+        ],
+        capabilities: ["implementation", "coding", "software-development"],
+        produces: ["code", "source-files", "implementation"],
+        source: "builtin",
+    },
+    {
+        name: "reviewer",
+        description: "Code quality reviewer responsible for validating implementation quality",
+        thinking: "medium",
+        tools: ["read", "grep", "find", "ls", "bash"],
+        systemPromptMode: "replace",
+        inheritProjectContext: true,
+        inheritSkills: true,
+        triggers: ["review", "audit", "check", "validate"],
+        useWhen: [
+            "code review",
+            "quality assurance",
+            "architecture review",
+            "security review",
+        ],
+        avoidWhen: ["implementation", "documentation", "research"],
+        capabilities: ["review", "quality-assurance", "auditing"],
+        produces: ["review-report", "quality-feedback", "audit"],
+        source: "builtin",
+    },
+];
+/**
+ * Simple keyword → capability mapping for built-in routing.
+ * Used when capabilities are not explicitly declared on agents.
+ */
+export const KEYWORD_TO_CAPABILITY = {
+    // Documentation
+    documentation: ["documentation", "knowledge", "writing"],
+    docs: ["documentation", "knowledge", "writing"],
+    "write docs": ["documentation", "knowledge", "writing"],
+    readme: ["documentation", "knowledge", "writing"],
+    // Research
+    research: ["research", "analysis", "information-gathering"],
+    investigate: ["research", "analysis", "information-gathering"],
+    "find information": ["research", "analysis", "information-gathering"],
+    "look up": ["research", "analysis", "information-gathering"],
+    // Engineering
+    implement: ["implementation", "coding", "software-development"],
+    build: ["implementation", "coding", "software-development"],
+    develop: ["implementation", "coding", "software-development"],
+    program: ["implementation", "coding", "software-development"],
+    code: ["implementation", "coding", "software-development"],
+    // Review
+    review: ["review", "quality-assurance", "auditing"],
+    audit: ["review", "quality-assurance", "auditing"],
+    check: ["review", "quality-assurance", "auditing"],
+    validate: ["review", "quality-assurance", "auditing"],
+};

package/dist/Supvisor.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Supvisor — The agent routing supervisor.
+ *
+ * Extracts the agent management logic from agent-router.ts and provides
+ * two entry points:
+ *   - routeAgent() — single-agent routing (same behavior as old)
+ *   - planAndRoute() — multi-agent workflow (NEW)
+ */
+import type { AgentConfig, RoutingDecision, RouteResult } from "./AgentConfig.ts";
+export declare function analyzeTaskDescription(taskDescription: string, agents: AgentConfig[]): RoutingDecision;
+export declare class Supervisor {
+    private agents;
+    private pi;
+    constructor(agents: AgentConfig[], pi: any);
+    routeAgent(taskDescription: string, forceAgent?: string, runInBackground?: boolean, thinking?: string, model?: string): Promise<RouteResult>;
+    /**
+     * Plan and route a workflow for multiple agents.
+     * Uses keyword matching to find relevant agents, then executes
+     * them in parallel (where dependencies allow).
+     */
+    planAndRoute(goal: string, options?: {
+        forceAgents?: string[];
+        background?: boolean;
+    }): Promise<{
+        success: boolean;
+        agents?: string[];
+        steps?: string[];
+        results?: Record<string, any>;
+        error?: string;
+    }>;
+    private _findRelevantAgents;
+    static getAllAgents(): Promise<AgentConfig[]>;
+}