@compilr-dev/sdk 0.1.27 → 0.2.0

package/dist/team/skill-requirements.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Skill Requirements Mapping
+ *
+ * Maps skills to the tools they require to function properly.
+ * This enables automatic filtering of incompatible skills based
+ * on an agent's tool configuration.
+ */
+export interface SkillToolRequirement {
+    /** Tools that MUST be available for this skill to work */
+    required: string[];
+    /** Tools that enhance this skill but aren't strictly required */
+    optional?: string[];
+    /** Brief description of why these tools are needed */
+    reason?: string;
+}
+/**
+ * Maps skill names to their tool requirements.
+ *
+ * Based on analysis of each skill's prompt and what tools it uses:
+ * - Required tools: The skill will fail without these
+ * - Optional tools: The skill works better with these but can function without
+ */
+export declare const SKILL_REQUIREMENTS: Record<string, SkillToolRequirement>;
+/**
+ * Get all skill names that have requirements defined.
+ */
+export declare function getDefinedSkillNames(): string[];
+/**
+ * Get the tool requirements for a skill.
+ */
+export declare function getSkillRequirements(skillName: string): SkillToolRequirement | undefined;
+/**
+ * Check if a skill is compatible with a set of available tools.
+ *
+ * @param skillName - Name of the skill to check
+ * @param availableTools - Set of tool names available to the agent
+ * @returns Object with compatibility status and missing tools
+ */
+export declare function checkSkillCompatibility(skillName: string, availableTools: Set<string> | string[]): {
+    compatible: boolean;
+    missingRequired: string[];
+    missingOptional: string[];
+};
+/**
+ * Get all skills that are compatible with a set of available tools.
+ *
+ * @param availableTools - Tools available to the agent
+ * @param allSkillNames - All skill names to check (default: defined skills)
+ * @returns Object with compatible and incompatible skill names
+ */
+export declare function getCompatibleSkills(availableTools: Set<string> | string[], allSkillNames?: string[]): {
+    compatible: string[];
+    incompatible: Array<{
+        name: string;
+        missingTools: string[];
+    }>;
+};
+/**
+ * Get all required tools across all skills.
+ * Useful for showing what tools are needed for full skill support.
+ */
+export declare function getAllRequiredTools(): string[];
+/**
+ * Get skills grouped by their primary category.
+ */
+export declare function getSkillsByCategory(): Record<string, string[]>;

package/dist/team/skill-requirements.js

@@ -0,0 +1,178 @@
+/**
+ * Skill Requirements Mapping
+ *
+ * Maps skills to the tools they require to function properly.
+ * This enables automatic filtering of incompatible skills based
+ * on an agent's tool configuration.
+ */
+// =============================================================================
+// Skill Requirements
+// =============================================================================
+/**
+ * Maps skill names to their tool requirements.
+ *
+ * Based on analysis of each skill's prompt and what tools it uses:
+ * - Required tools: The skill will fail without these
+ * - Optional tools: The skill works better with these but can function without
+ */
+export const SKILL_REQUIREMENTS = {
+    // Development skills
+    'code-review': {
+        required: ['read_file', 'glob', 'grep'],
+        optional: ['git_status', 'git_diff'],
+        reason: 'Needs to read and search code files',
+    },
+    debug: {
+        required: ['read_file', 'glob', 'grep'],
+        optional: ['bash', 'run_tests', 'edit'],
+        reason: 'Needs to read code, optionally run tests and fix issues',
+    },
+    explain: {
+        required: ['read_file', 'glob'],
+        optional: ['grep'],
+        reason: 'Needs to read actual code to explain it',
+    },
+    refactor: {
+        required: ['read_file', 'write_file', 'edit', 'glob', 'grep'],
+        optional: ['run_tests', 'run_lint', 'git_diff'],
+        reason: 'Needs full file access to restructure code safely',
+    },
+    // Security skills
+    'security-review': {
+        required: ['read_file', 'glob', 'grep'],
+        optional: ['bash', 'find_vulnerabilities', 'check_outdated'],
+        reason: 'Needs to search for security patterns in code',
+    },
+    // Planning skills
+    planning: {
+        required: ['read_file', 'glob'],
+        optional: ['ask_user', 'ask_user_simple', 'todo_write'],
+        reason: 'Needs to understand codebase to plan effectively',
+    },
+    design: {
+        required: ['ask_user', 'workitem_add'],
+        optional: ['detect_project', 'document_save', 'edit'],
+        reason: 'Needs to gather requirements and create backlog',
+    },
+    refine: {
+        required: ['workitem_query', 'workitem_update', 'ask_user_simple'],
+        optional: ['ask_user', 'todo_write'],
+        reason: 'Needs to read and update backlog items',
+    },
+    sketch: {
+        required: ['ask_user_simple', 'workitem_add'],
+        optional: ['detect_project', 'todo_write'],
+        reason: 'Quick outline needs user input and backlog creation',
+    },
+    'refine-item': {
+        required: ['workitem_query', 'workitem_update', 'ask_user_simple'],
+        optional: ['ask_user'],
+        reason: 'Needs to read specific item and update it',
+    },
+    // Documentation skills
+    architecture: {
+        required: ['read_file', 'write_file', 'edit'],
+        optional: ['backlog_read', 'ask_user', 'glob'],
+        reason: 'Creates architecture documents',
+    },
+    prd: {
+        required: ['read_file', 'edit', 'ask_user_simple'],
+        optional: ['ask_user', 'backlog_read'],
+        reason: 'Reads and updates PRD document',
+    },
+    'session-notes': {
+        required: ['write_file'],
+        optional: ['read_file', 'ask_user_simple'],
+        reason: 'Creates session note documents',
+    },
+};
+// =============================================================================
+// Helper Functions
+// =============================================================================
+/**
+ * Get all skill names that have requirements defined.
+ */
+export function getDefinedSkillNames() {
+    return Object.keys(SKILL_REQUIREMENTS);
+}
+/**
+ * Get the tool requirements for a skill.
+ */
+export function getSkillRequirements(skillName) {
+    return SKILL_REQUIREMENTS[skillName];
+}
+/**
+ * Check if a skill is compatible with a set of available tools.
+ *
+ * @param skillName - Name of the skill to check
+ * @param availableTools - Set of tool names available to the agent
+ * @returns Object with compatibility status and missing tools
+ */
+export function checkSkillCompatibility(skillName, availableTools) {
+    const toolSet = availableTools instanceof Set ? availableTools : new Set(availableTools);
+    // If no requirements defined, assume compatible
+    if (!(skillName in SKILL_REQUIREMENTS)) {
+        return {
+            compatible: true,
+            missingRequired: [],
+            missingOptional: [],
+        };
+    }
+    const requirement = SKILL_REQUIREMENTS[skillName];
+    const missingRequired = requirement.required.filter((t) => !toolSet.has(t));
+    const missingOptional = (requirement.optional ?? []).filter((t) => !toolSet.has(t));
+    return {
+        compatible: missingRequired.length === 0,
+        missingRequired,
+        missingOptional,
+    };
+}
+/**
+ * Get all skills that are compatible with a set of available tools.
+ *
+ * @param availableTools - Tools available to the agent
+ * @param allSkillNames - All skill names to check (default: defined skills)
+ * @returns Object with compatible and incompatible skill names
+ */
+export function getCompatibleSkills(availableTools, allSkillNames) {
+    const skillNames = allSkillNames ?? getDefinedSkillNames();
+    const compatible = [];
+    const incompatible = [];
+    for (const skillName of skillNames) {
+        const result = checkSkillCompatibility(skillName, availableTools);
+        if (result.compatible) {
+            compatible.push(skillName);
+        }
+        else {
+            incompatible.push({
+                name: skillName,
+                missingTools: result.missingRequired,
+            });
+        }
+    }
+    return { compatible, incompatible };
+}
+/**
+ * Get all required tools across all skills.
+ * Useful for showing what tools are needed for full skill support.
+ */
+export function getAllRequiredTools() {
+    const allTools = new Set();
+    for (const requirement of Object.values(SKILL_REQUIREMENTS)) {
+        for (const tool of requirement.required) {
+            allTools.add(tool);
+        }
+    }
+    return Array.from(allTools).sort();
+}
+/**
+ * Get skills grouped by their primary category.
+ */
+export function getSkillsByCategory() {
+    return {
+        development: ['code-review', 'debug', 'explain', 'refactor'],
+        security: ['security-review'],
+        planning: ['planning', 'design', 'refine', 'sketch', 'refine-item'],
+        documentation: ['architecture', 'prd', 'session-notes'],
+    };
+}

package/dist/team/task-assignment.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Task Assignment - Loop prevention and assignment tracking
+ *
+ * Prevents reassignment loops where tasks bounce between agents
+ * (e.g., A → B → A within a short time window).
+ */
+/**
+ * Record of a task reassignment
+ */
+interface AssignmentRecord {
+    from: string;
+    to: string;
+    timestamp: number;
+}
+/**
+ * Check if an assignment would create a loop
+ *
+ * A loop is detected if:
+ * - The task was recently assigned from B to A
+ * - And we're now trying to assign from A to B
+ *
+ * @param taskId - The task ID (todo ID or work item ID)
+ * @param from - The current owner (or 'unassigned')
+ * @param to - The target owner
+ * @returns true if this would create a loop
+ */
+export declare function wouldCreateLoop(taskId: string, from: string, to: string): boolean;
+/**
+ * Record a task assignment
+ *
+ * @param taskId - The task ID (todo ID or work item ID)
+ * @param from - The previous owner (or 'unassigned')
+ * @param to - The new owner
+ */
+export declare function recordAssignment(taskId: string, from: string, to: string): void;
+/**
+ * Get assignment history for a task
+ *
+ * @param taskId - The task ID
+ * @returns Array of recent assignment records
+ */
+export declare function getAssignmentHistory(taskId: string): AssignmentRecord[];
+/**
+ * Clear assignment history for a task
+ * Call this when a task is completed or deleted
+ *
+ * @param taskId - The task ID
+ */
+export declare function clearAssignmentHistory(taskId: string): void;
+/**
+ * Clear all assignment history
+ * Useful for testing or session reset
+ */
+export declare function clearAllAssignmentHistory(): void;
+/**
+ * Check if an agent can reassign a task
+ *
+ * Rules:
+ * - Owner can always reassign their own tasks
+ * - PM can reassign any task (coordinator role)
+ * - Unassigned tasks can be claimed by anyone
+ *
+ * @param currentOwner - Current owner of the task (or null for unassigned)
+ * @param requestingAgent - Agent trying to reassign
+ * @param isPm - Whether the requesting agent is PM/coordinator
+ * @returns true if the agent can reassign
+ */
+export declare function canReassign(currentOwner: string | null, requestingAgent: string, isPm?: boolean): boolean;
+export {};

package/dist/team/task-assignment.js

@@ -0,0 +1,123 @@
+/**
+ * Task Assignment - Loop prevention and assignment tracking
+ *
+ * Prevents reassignment loops where tasks bounce between agents
+ * (e.g., A → B → A within a short time window).
+ */
+/**
+ * In-memory tracking of recent reassignments per task
+ * Map of taskId → list of recent assignments
+ */
+const recentAssignments = new Map();
+/**
+ * How long to remember assignments (30 minutes)
+ */
+const ASSIGNMENT_MEMORY_MS = 30 * 60 * 1000;
+/**
+ * Clean up old assignment records
+ */
+function cleanupOldRecords(taskId) {
+    const records = recentAssignments.get(taskId);
+    if (!records)
+        return;
+    const now = Date.now();
+    const filtered = records.filter((r) => now - r.timestamp < ASSIGNMENT_MEMORY_MS);
+    if (filtered.length === 0) {
+        recentAssignments.delete(taskId);
+    }
+    else {
+        recentAssignments.set(taskId, filtered);
+    }
+}
+/**
+ * Check if an assignment would create a loop
+ *
+ * A loop is detected if:
+ * - The task was recently assigned from B to A
+ * - And we're now trying to assign from A to B
+ *
+ * @param taskId - The task ID (todo ID or work item ID)
+ * @param from - The current owner (or 'unassigned')
+ * @param to - The target owner
+ * @returns true if this would create a loop
+ */
+export function wouldCreateLoop(taskId, from, to) {
+    cleanupOldRecords(taskId);
+    const records = recentAssignments.get(taskId);
+    if (!records || records.length === 0) {
+        return false;
+    }
+    // Check for reverse assignment in recent history
+    return records.some((r) => r.from === to && r.to === from);
+}
+/**
+ * Record a task assignment
+ *
+ * @param taskId - The task ID (todo ID or work item ID)
+ * @param from - The previous owner (or 'unassigned')
+ * @param to - The new owner
+ */
+export function recordAssignment(taskId, from, to) {
+    cleanupOldRecords(taskId);
+    const records = recentAssignments.get(taskId) || [];
+    records.push({
+        from,
+        to,
+        timestamp: Date.now(),
+    });
+    recentAssignments.set(taskId, records);
+}
+/**
+ * Get assignment history for a task
+ *
+ * @param taskId - The task ID
+ * @returns Array of recent assignment records
+ */
+export function getAssignmentHistory(taskId) {
+    cleanupOldRecords(taskId);
+    return [...(recentAssignments.get(taskId) || [])];
+}
+/**
+ * Clear assignment history for a task
+ * Call this when a task is completed or deleted
+ *
+ * @param taskId - The task ID
+ */
+export function clearAssignmentHistory(taskId) {
+    recentAssignments.delete(taskId);
+}
+/**
+ * Clear all assignment history
+ * Useful for testing or session reset
+ */
+export function clearAllAssignmentHistory() {
+    recentAssignments.clear();
+}
+/**
+ * Check if an agent can reassign a task
+ *
+ * Rules:
+ * - Owner can always reassign their own tasks
+ * - PM can reassign any task (coordinator role)
+ * - Unassigned tasks can be claimed by anyone
+ *
+ * @param currentOwner - Current owner of the task (or null for unassigned)
+ * @param requestingAgent - Agent trying to reassign
+ * @param isPm - Whether the requesting agent is PM/coordinator
+ * @returns true if the agent can reassign
+ */
+export function canReassign(currentOwner, requestingAgent, isPm = false) {
+    // Unassigned tasks can be claimed by anyone
+    if (!currentOwner) {
+        return true;
+    }
+    // Owner can always reassign their own tasks
+    if (currentOwner === requestingAgent) {
+        return true;
+    }
+    // PM/coordinator can reassign any task
+    if (isPm) {
+        return true;
+    }
+    return false;
+}

package/dist/team/task-suggestion.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Task Suggestion - Auto-suggest owner based on task content
+ *
+ * Uses keyword matching to suggest which agent should own a task.
+ * This is used as a hint when creating tasks without explicit owner.
+ */
+/**
+ * Suggest an owner agent based on task content
+ *
+ * @param content - The task content/title to analyze
+ * @param availableAgents - List of available agent IDs in the team
+ * @returns Suggested agent ID, or undefined if no match
+ */
+export declare function suggestOwner(content: string, availableAgents: string[]): string | undefined;
+/**
+ * Get all agents that might be relevant for a task
+ * Returns multiple suggestions in priority order
+ *
+ * @param content - The task content/title to analyze
+ * @param availableAgents - List of available agent IDs in the team
+ * @returns Array of suggested agent IDs, in priority order
+ */
+export declare function suggestOwners(content: string, availableAgents: string[]): string[];
+/**
+ * Check if a task content strongly matches a specific agent's expertise
+ *
+ * @param content - The task content/title to analyze
+ * @param agentId - The agent ID to check
+ * @returns true if the content strongly matches the agent's expertise
+ */
+export declare function matchesAgentExpertise(content: string, agentId: string): boolean;

package/dist/team/task-suggestion.js

@@ -0,0 +1,84 @@
+/**
+ * Task Suggestion - Auto-suggest owner based on task content
+ *
+ * Uses keyword matching to suggest which agent should own a task.
+ * This is used as a hint when creating tasks without explicit owner.
+ */
+/**
+ * Mapping of keywords to agent roles
+ */
+const KEYWORD_TO_AGENT = [
+    // Architecture
+    { pattern: /\b(design|architect|api|schema|structure|pattern|trade-?off)\b/i, agent: 'arch' },
+    // Quality Assurance
+    {
+        pattern: /\b(test|qa|coverage|e2e|unit|integration|regression|bug|fix|validate)\b/i,
+        agent: 'qa',
+    },
+    // Development
+    { pattern: /\b(implement|code|refactor|debug|function|class|method|feature)\b/i, agent: 'dev' },
+    // Operations/DevOps
+    {
+        pattern: /\b(deploy|ci|cd|docker|infra|kubernetes|k8s|pipeline|release|build|monitor)\b/i,
+        agent: 'ops',
+    },
+    // Documentation
+    { pattern: /\b(document|readme|docs|tutorial|guide|explain|write up)\b/i, agent: 'docs' },
+    // Business Analysis
+    {
+        pattern: /\b(requirement|story|acceptance|criteria|stakeholder|user story|epic)\b/i,
+        agent: 'ba',
+    },
+    // Project Management
+    {
+        pattern: /\b(plan|track|coordinate|sprint|timeline|prioriti[zs]e|schedule|status)\b/i,
+        agent: 'pm',
+    },
+];
+/**
+ * Suggest an owner agent based on task content
+ *
+ * @param content - The task content/title to analyze
+ * @param availableAgents - List of available agent IDs in the team
+ * @returns Suggested agent ID, or undefined if no match
+ */
+export function suggestOwner(content, availableAgents) {
+    for (const { pattern, agent } of KEYWORD_TO_AGENT) {
+        if (pattern.test(content) && availableAgents.includes(agent)) {
+            return agent;
+        }
+    }
+    return undefined;
+}
+/**
+ * Get all agents that might be relevant for a task
+ * Returns multiple suggestions in priority order
+ *
+ * @param content - The task content/title to analyze
+ * @param availableAgents - List of available agent IDs in the team
+ * @returns Array of suggested agent IDs, in priority order
+ */
+export function suggestOwners(content, availableAgents) {
+    const suggestions = [];
+    for (const { pattern, agent } of KEYWORD_TO_AGENT) {
+        if (pattern.test(content) && availableAgents.includes(agent) && !suggestions.includes(agent)) {
+            suggestions.push(agent);
+        }
+    }
+    return suggestions;
+}
+/**
+ * Check if a task content strongly matches a specific agent's expertise
+ *
+ * @param content - The task content/title to analyze
+ * @param agentId - The agent ID to check
+ * @returns true if the content strongly matches the agent's expertise
+ */
+export function matchesAgentExpertise(content, agentId) {
+    for (const { pattern, agent } of KEYWORD_TO_AGENT) {
+        if (agent === agentId && pattern.test(content)) {
+            return true;
+        }
+    }
+    return false;
+}