@bradygaster/squad-sdk 0.6.2 → 0.8.0

package/dist/agents/model-selector.js

@@ -0,0 +1,198 @@
+/**
+ * Per-Agent Model Selection (M1-9) + Model Fallback (M3-5, Issue #145)
+ */
+/**
+ * Fallback chains by tier.
+ */
+const FALLBACK_CHAINS = {
+    premium: [
+        'claude-opus-4.6',
+        'claude-opus-4.6-fast',
+        'claude-opus-4.5',
+        'claude-sonnet-4.5',
+    ],
+    standard: [
+        'claude-sonnet-4.5',
+        'gpt-5.2-codex',
+        'claude-sonnet-4',
+        'gpt-5.2',
+    ],
+    fast: [
+        'claude-haiku-4.5',
+        'gpt-5.1-codex-mini',
+        'gpt-4.1',
+        'gpt-5-mini',
+    ],
+};
+/**
+ * Default model (cost-first).
+ */
+const DEFAULT_MODEL = 'claude-haiku-4.5';
+const DEFAULT_TIER = 'fast';
+/**
+ * Resolve the appropriate model using the 4-layer priority system.
+ *
+ * @param options - Model resolution options
+ * @returns Resolved model with tier and fallback chain
+ */
+export function resolveModel(options) {
+    const { userOverride, charterPreference, taskType } = options;
+    // Layer 1: User Override
+    if (userOverride && userOverride.trim().length > 0) {
+        const tier = inferTierFromModel(userOverride);
+        return {
+            model: userOverride,
+            tier,
+            source: 'user-override',
+            fallbackChain: FALLBACK_CHAINS[tier],
+        };
+    }
+    // Layer 2: Charter Preference
+    if (charterPreference && charterPreference.trim().length > 0 && charterPreference !== 'auto') {
+        const tier = inferTierFromModel(charterPreference);
+        return {
+            model: charterPreference,
+            tier,
+            source: 'charter',
+            fallbackChain: FALLBACK_CHAINS[tier],
+        };
+    }
+    // Layer 3: Task-Aware Auto-Selection
+    const autoSelected = selectModelForTask(taskType);
+    if (autoSelected) {
+        return autoSelected;
+    }
+    // Layer 4: Default
+    return {
+        model: DEFAULT_MODEL,
+        tier: DEFAULT_TIER,
+        source: 'default',
+        fallbackChain: FALLBACK_CHAINS[DEFAULT_TIER],
+    };
+}
+/**
+ * Select model based on task type.
+ *
+ * @param taskType - Type of task being performed
+ * @returns Resolved model or undefined if no match
+ */
+function selectModelForTask(taskType) {
+    switch (taskType) {
+        case 'code':
+            return {
+                model: 'claude-sonnet-4.5',
+                tier: 'standard',
+                source: 'task-auto',
+                fallbackChain: FALLBACK_CHAINS.standard,
+            };
+        case 'prompt':
+            return {
+                model: 'claude-sonnet-4.5',
+                tier: 'standard',
+                source: 'task-auto',
+                fallbackChain: FALLBACK_CHAINS.standard,
+            };
+        case 'visual':
+            return {
+                model: 'claude-opus-4.5',
+                tier: 'premium',
+                source: 'task-auto',
+                fallbackChain: FALLBACK_CHAINS.premium,
+            };
+        case 'docs':
+        case 'planning':
+        case 'mechanical':
+            return {
+                model: 'claude-haiku-4.5',
+                tier: 'fast',
+                source: 'task-auto',
+                fallbackChain: FALLBACK_CHAINS.fast,
+            };
+        default:
+            return undefined;
+    }
+}
+export function inferTierFromModel(model) {
+    const lowerModel = model.toLowerCase();
+    if (lowerModel.includes('opus')) {
+        return 'premium';
+    }
+    if (lowerModel.includes('haiku') || lowerModel.includes('mini')) {
+        return 'fast';
+    }
+    // Default to standard for sonnet, gpt-5.x, etc.
+    return 'standard';
+}
+// ============================================================================
+// Model Fallback Executor (M3-5, Issue #145)
+// ============================================================================
+const TIER_ORDER = { premium: 0, standard: 1, fast: 2 };
+export function isTierFallbackAllowed(fromTier, toTier, allowCrossTier) {
+    if (allowCrossTier)
+        return true;
+    if (fromTier === toTier)
+        return true;
+    return TIER_ORDER[toTier] <= TIER_ORDER[fromTier];
+}
+export class ModelFallbackExecutor {
+    allowCrossTier;
+    eventBus;
+    history = new Map();
+    constructor(config = {}) {
+        this.allowCrossTier = config.allowCrossTier ?? false;
+        this.eventBus = config.eventBus;
+    }
+    async execute(resolved, agentName, fn) {
+        const attempts = [];
+        const originalTier = resolved.tier;
+        const candidates = this.buildCandidateList(resolved);
+        for (const candidate of candidates) {
+            const candidateTier = inferTierFromModel(candidate);
+            if (!isTierFallbackAllowed(originalTier, candidateTier, this.allowCrossTier)) {
+                continue;
+            }
+            try {
+                const value = await fn(candidate);
+                if (!this.history.has(agentName))
+                    this.history.set(agentName, []);
+                this.history.get(agentName).push(...attempts);
+                return { value, model: candidate, tier: candidateTier, attempts, didFallback: attempts.length > 0 };
+            }
+            catch (error) {
+                const errorMsg = error instanceof Error ? error.message : String(error);
+                const attempt = { model: candidate, tier: candidateTier, error: errorMsg, timestamp: new Date() };
+                attempts.push(attempt);
+                await this.emitEvent('agent:milestone', { event: 'model.fallback', agentName, failedModel: candidate, failedTier: candidateTier, error: errorMsg, attemptNumber: attempts.length });
+            }
+        }
+        if (!this.history.has(agentName))
+            this.history.set(agentName, []);
+        this.history.get(agentName).push(...attempts);
+        await this.emitEvent('agent:milestone', { event: 'model.exhausted', agentName, originalModel: resolved.model, originalTier, totalAttempts: attempts.length });
+        throw new Error(`All models exhausted for agent '${agentName}'. Tried ${attempts.length} model(s): ${attempts.map(a => a.model).join(', ')}`);
+    }
+    getHistory(agentName) {
+        return this.history.get(agentName) ?? [];
+    }
+    clearHistory() {
+        this.history.clear();
+    }
+    buildCandidateList(resolved) {
+        const seen = new Set();
+        const result = [];
+        const add = (m) => { if (!seen.has(m)) {
+            seen.add(m);
+            result.push(m);
+        } };
+        add(resolved.model);
+        for (const fb of resolved.fallbackChain)
+            add(fb);
+        return result;
+    }
+    async emitEvent(type, payload) {
+        if (!this.eventBus)
+            return;
+        await this.eventBus.emit({ type: type, payload, timestamp: new Date() });
+    }
+}
+//# sourceMappingURL=model-selector.js.map

package/dist/agents/model-selector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-selector.js","sourceRoot":"","sources":["../../src/agents/model-selector.ts"],"names":[],"mappings":"AAAA;;GAEG;AA+CH;;GAEG;AACH,MAAM,eAAe,GAAgC;IACnD,OAAO,EAAE;QACP,iBAAiB;QACjB,sBAAsB;QACtB,iBAAiB;QACjB,mBAAmB;KACpB;IACD,QAAQ,EAAE;QACR,mBAAmB;QACnB,eAAe;QACf,iBAAiB;QACjB,SAAS;KACV;IACD,IAAI,EAAE;QACJ,kBAAkB;QAClB,oBAAoB;QACpB,SAAS;QACT,YAAY;KACb;CACF,CAAC;AAEF;;GAEG;AACH,MAAM,aAAa,GAAG,kBAAkB,CAAC;AACzC,MAAM,YAAY,GAAc,MAAM,CAAC;AAEvC;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,OAA+B;IAC1D,MAAM,EAAE,YAAY,EAAE,iBAAiB,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC;IAE9D,yBAAyB;IACzB,IAAI,YAAY,IAAI,YAAY,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACnD,MAAM,IAAI,GAAG,kBAAkB,CAAC,YAAY,CAAC,CAAC;QAC9C,OAAO;YACL,KAAK,EAAE,YAAY;YACnB,IAAI;YACJ,MAAM,EAAE,eAAe;YACvB,aAAa,EAAE,eAAe,CAAC,IAAI,CAAC;SACrC,CAAC;IACJ,CAAC;IAED,8BAA8B;IAC9B,IAAI,iBAAiB,IAAI,iBAAiB,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,IAAI,iBAAiB,KAAK,MAAM,EAAE,CAAC;QAC7F,MAAM,IAAI,GAAG,kBAAkB,CAAC,iBAAiB,CAAC,CAAC;QACnD,OAAO;YACL,KAAK,EAAE,iBAAiB;YACxB,IAAI;YACJ,MAAM,EAAE,SAAS;YACjB,aAAa,EAAE,eAAe,CAAC,IAAI,CAAC;SACrC,CAAC;IACJ,CAAC;IAED,qCAAqC;IACrC,MAAM,YAAY,GAAG,kBAAkB,CAAC,QAAQ,CAAC,CAAC;IAClD,IAAI,YAAY,EAAE,CAAC;QACjB,OAAO,YAAY,CAAC;IACtB,CAAC;IAED,mBAAmB;IACnB,OAAO;QACL,KAAK,EAAE,aAAa;QACpB,IAAI,EAAE,YAAY;QAClB,MAAM,EAAE,SAAS;QACjB,aAAa,EAAE,eAAe,CAAC,YAAY,CAAC;KAC7C,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,SAAS,kBAAkB,CAAC,QAAkB;IAC5C,QAAQ,QAAQ,EAAE,CAAC;QACjB,KAAK,MAAM;YACT,OAAO;gBACL,KAAK,EAAE,mBAAmB;gBAC1B,IAAI,EAAE,UAAU;gBAChB,MAAM,EAAE,WAAW;gBACnB,aAAa,EAAE,eAAe,CAAC,QAAQ;aACxC,CAAC;QAEJ,KAAK,QAAQ;YACX,OAAO;gBACL,KAAK,EAAE,mBAAmB;gBAC1B,IAAI,EAAE,UAAU;gBAChB,MAAM,EAAE,WAAW;gBACnB,aAAa,EAAE,eAAe,CAAC,QAAQ;aACxC,CAAC;QAEJ,KAAK,QAAQ;YACX,OAAO;gBACL,KAAK,EAAE,iBAAiB;gBACxB,IAAI,EAAE,SAAS;gBACf,MAAM,EAAE,WAAW;gBACnB,aAAa,EAAE,eAAe,CAAC,OAAO;aACvC,CAAC;QAEJ,KAAK,MAAM,CAAC;QACZ,KAAK,UAAU,CAAC;QAChB,KAAK,YAAY;YACf,OAAO;gBACL,KAAK,EAAE,kBAAkB;gBACzB,IAAI,EAAE,MAAM;gBACZ,MAAM,EAAE,WAAW;gBACnB,aAAa,EAAE,eAAe,CAAC,IAAI;aACpC,CAAC;QAEJ;YACE,OAAO,SAAS,CAAC;IACrB,CAAC;AACH,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,KAAa;IAC9C,MAAM,UAAU,GAAG,KAAK,CAAC,WAAW,EAAE,CAAC;IAEvC,IAAI,UAAU,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;QAChC,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,IAAI,UAAU,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,UAAU,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;QAChE,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,gDAAgD;IAChD,OAAO,UAAU,CAAC;AACpB,CAAC;AAED,+EAA+E;AAC/E,6CAA6C;AAC7C,+EAA+E;AAE/E,MAAM,UAAU,GAA8B,EAAE,OAAO,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;AAEnF,MAAM,UAAU,qBAAqB,CACnC,QAAmB,EACnB,MAAiB,EACjB,cAAuB;IAEvB,IAAI,cAAc;QAAE,OAAO,IAAI,CAAC;IAChC,IAAI,QAAQ,KAAK,MAAM;QAAE,OAAO,IAAI,CAAC;IACrC,OAAO,UAAU,CAAC,MAAM,CAAC,IAAI,UAAU,CAAC,QAAQ,CAAC,CAAC;AACpD,CAAC;AAsBD,MAAM,OAAO,qBAAqB;IACxB,cAAc,CAAU;IACxB,QAAQ,CAAY;IACpB,OAAO,GAAmC,IAAI,GAAG,EAAE,CAAC;IAE5D,YAAY,SAAiC,EAAE;QAC7C,IAAI,CAAC,cAAc,GAAG,MAAM,CAAC,cAAc,IAAI,KAAK,CAAC;QACrD,IAAI,CAAC,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC;IAClC,CAAC;IAED,KAAK,CAAC,OAAO,CACX,QAAuB,EACvB,SAAiB,EACjB,EAAiC;QAEjC,MAAM,QAAQ,GAAsB,EAAE,CAAC;QACvC,MAAM,YAAY,GAAG,QAAQ,CAAC,IAAI,CAAC;QACnC,MAAM,UAAU,GAAG,IAAI,CAAC,kBAAkB,CAAC,QAAQ,CAAC,CAAC;QAErD,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;YACnC,MAAM,aAAa,GAAG,kBAAkB,CAAC,SAAS,CAAC,CAAC;YACpD,IAAI,CAAC,qBAAqB,CAAC,YAAY,EAAE,aAAa,EAAE,IAAI,CAAC,cAAc,CAAC,EAAE,CAAC;gBAC7E,SAAS;YACX,CAAC;YACD,IAAI,CAAC;gBACH,MAAM,KAAK,GAAG,MAAM,EAAE,CAAC,SAAS,CAAC,CAAC;gBAClC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC;oBAAE,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;gBAClE,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,CAAE,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAC,CAAC;gBAC/C,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,aAAa,EAAE,QAAQ,EAAE,WAAW,EAAE,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACtG,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,MAAM,QAAQ,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;gBACxE,MAAM,OAAO,GAAoB,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,IAAI,IAAI,EAAE,EAAE,CAAC;gBACnH,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;gBACvB,MAAM,IAAI,CAAC,SAAS,CAAC,iBAAiB,EAAE,EAAE,KAAK,EAAE,gBAAgB,EAAE,SAAS,EAAE,WAAW,EAAE,SAAS,EAAE,UAAU,EAAE,aAAa,EAAE,KAAK,EAAE,QAAQ,EAAE,aAAa,EAAE,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;YACtL,CAAC;QACH,CAAC;QAED,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC;YAAE,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;QAClE,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,CAAE,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAC,CAAC;QAC/C,MAAM,IAAI,CAAC,SAAS,CAAC,iBAAiB,EAAE,EAAE,KAAK,EAAE,iBAAiB,EAAE,SAAS,EAAE,aAAa,EAAE,QAAQ,CAAC,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;QAC9J,MAAM,IAAI,KAAK,CAAC,mCAAmC,SAAS,YAAY,QAAQ,CAAC,MAAM,cAAc,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAChJ,CAAC;IAED,UAAU,CAAC,SAAiB;QAC1B,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC;IAC3C,CAAC;IAED,YAAY;QACV,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;IACvB,CAAC;IAEO,kBAAkB,CAAC,QAAuB;QAChD,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;QAC/B,MAAM,MAAM,GAAa,EAAE,CAAC;QAC5B,MAAM,GAAG,GAAG,CAAC,CAAS,EAAE,EAAE,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;YAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;YAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAAC,CAAC,CAAC,CAAC,CAAC;QAClF,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;QACpB,KAAK,MAAM,EAAE,IAAI,QAAQ,CAAC,aAAa;YAAE,GAAG,CAAC,EAAE,CAAC,CAAC;QACjD,OAAO,MAAM,CAAC;IAChB,CAAC;IAEO,KAAK,CAAC,SAAS,CAAC,IAAY,EAAE,OAAgC;QACpE,IAAI,CAAC,IAAI,CAAC,QAAQ;YAAE,OAAO;QAC3B,MAAM,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAW,EAAE,OAAO,EAAE,SAAS,EAAE,IAAI,IAAI,EAAE,EAAE,CAAC,CAAC;IAClF,CAAC;CACF"}

package/dist/agents/onboarding.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Agent Onboarding Module (M2-10, PRD #111)
+ *
+ * Handles runtime agent onboarding with context-aware charter generation.
+ * Creates agent directory, charter, and history with project context.
+ *
+ * @module agents/onboarding
+ */
+/**
+ * Agent onboarding options.
+ */
+export interface OnboardOptions {
+    /** Root directory for Squad team files */
+    teamRoot: string;
+    /** Agent name (kebab-case) */
+    agentName: string;
+    /** Agent role identifier */
+    role: string;
+    /** Display name (optional, defaults to titlecased name) */
+    displayName?: string;
+    /** Project context for charter generation */
+    projectContext?: string;
+    /** User name for initial history entry */
+    userName?: string;
+    /** Custom charter template override */
+    charterTemplate?: string;
+}
+/**
+ * Agent onboarding result.
+ */
+export interface OnboardResult {
+    /** Created file paths */
+    createdFiles: string[];
+    /** Agent directory path */
+    agentDir: string;
+    /** Charter file path */
+    charterPath: string;
+    /** History file path */
+    historyPath: string;
+}
+/**
+ * Onboard a new agent to the Squad.
+ *
+ * Creates:
+ * - Agent directory at .squad/agents/{name}/
+ * - charter.md from role template + project context
+ * - history.md with project description and tech stack
+ *
+ * @param options - Onboarding options
+ * @returns Result with created file paths
+ */
+export declare function onboardAgent(options: OnboardOptions): Promise<OnboardResult>;
+/**
+ * Update an agent's configuration to squad.config.ts (if it exists).
+ *
+ * This is a helper function to add agent routing after onboarding.
+ * Only works with TypeScript configs (JSON requires manual edit).
+ *
+ * @param teamRoot - Team root directory
+ * @param agentName - Agent name to add
+ * @param role - Agent role
+ * @returns True if config was updated, false if not found or JSON format
+ */
+export declare function addAgentToConfig(teamRoot: string, agentName: string, role: string): Promise<boolean>;
+//# sourceMappingURL=onboarding.d.ts.map

package/dist/agents/onboarding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"onboarding.d.ts","sourceRoot":"","sources":["../../src/agents/onboarding.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAUH;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,0CAA0C;IAC1C,QAAQ,EAAE,MAAM,CAAC;IACjB,8BAA8B;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,4BAA4B;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,2DAA2D;IAC3D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6CAA6C;IAC7C,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,0CAA0C;IAC1C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,uCAAuC;IACvC,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,yBAAyB;IACzB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,2BAA2B;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,wBAAwB;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,wBAAwB;IACxB,WAAW,EAAE,MAAM,CAAC;CACrB;AAoQD;;;;;;;;;;GAUG;AACH,wBAAsB,YAAY,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CA2ElF;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,gBAAgB,CACpC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,OAAO,CAAC,CAwDlB"}

package/dist/agents/onboarding.js

@@ -0,0 +1,373 @@
+/**
+ * Agent Onboarding Module (M2-10, PRD #111)
+ *
+ * Handles runtime agent onboarding with context-aware charter generation.
+ * Creates agent directory, charter, and history with project context.
+ *
+ * @module agents/onboarding
+ */
+import { mkdir, writeFile, readFile } from 'fs/promises';
+import { join } from 'path';
+import { existsSync } from 'fs';
+// ============================================================================
+// Default Charter Templates
+// ============================================================================
+/**
+ * Default charter templates for standard roles.
+ */
+const CHARTER_TEMPLATES = {
+    'lead': (displayName, context) => `# ${displayName} — Technical Lead
+
+Technical lead responsible for architecture, delegation, and project coordination.
+
+## Project Context
+
+${context || 'Context will be provided by the team.'}
+
+## Responsibilities
+
+- Define technical direction and architecture
+- Coordinate work across team members
+- Review proposals and make final decisions
+- Maintain code quality standards
+- Mentor team members
+
+## Work Style
+
+- Think strategically about long-term maintainability
+- Delegate work effectively to specialists
+- Balance technical excellence with pragmatic delivery
+- Document architectural decisions
+- Foster collaborative team environment
+`,
+    'developer': (displayName, context) => `# ${displayName} — Software Developer
+
+Software developer focused on feature implementation and code quality.
+
+## Project Context
+
+${context || 'Context will be provided by the team.'}
+
+## Responsibilities
+
+- Implement features according to specifications
+- Write clean, maintainable code
+- Create and maintain tests
+- Review code from team members
+- Document implementation decisions
+
+## Work Style
+
+- Follow established patterns and conventions
+- Write tests alongside implementation
+- Ask questions when requirements are unclear
+- Collaborate with team members on complex problems
+- Keep code simple and readable
+`,
+    'tester': (displayName, context) => `# ${displayName} — Quality Assurance
+
+Quality assurance specialist responsible for test coverage and validation.
+
+## Project Context
+
+${context || 'Context will be provided by the team.'}
+
+## Responsibilities
+
+- Design and implement test strategies
+- Write comprehensive test suites
+- Validate features against requirements
+- Identify edge cases and failure modes
+- Maintain test infrastructure
+
+## Work Style
+
+- Think adversarially about how things can break
+- Automate testing wherever possible
+- Document test scenarios and coverage
+- Collaborate with developers on testability
+- Balance thoroughness with pragmatism
+`,
+    'scribe': (displayName, context) => `# ${displayName} — Documentation Specialist
+
+Documentation specialist maintaining history, decisions, and technical records.
+
+## Project Context
+
+${context || 'Context will be provided by the team.'}
+
+## Responsibilities
+
+- Maintain agent history files
+- Document team decisions
+- Keep technical records organized
+- Summarize work sessions
+- Preserve institutional knowledge
+
+## Work Style
+
+- Write clear, concise documentation
+- Organize information for easy retrieval
+- Capture both what and why
+- Update documentation proactively
+- Maintain consistent formatting
+`,
+    'ralph': (displayName, context) => `# ${displayName} — Persistent Memory Agent
+
+Persistent memory agent that maintains context across sessions.
+
+## Project Context
+
+${context || 'Context will be provided by the team.'}
+
+## Responsibilities
+
+- Maintain session-to-session continuity
+- Surface relevant historical context
+- Track long-running initiatives
+- Connect current work to past decisions
+- Preserve institutional knowledge
+
+## Work Style
+
+- Read team history before responding
+- Surface relevant past work without overwhelming
+- Connect dots across sessions
+- Maintain perspective on long-term goals
+- Help team avoid repeating mistakes
+`,
+    'designer': (displayName, context) => `# ${displayName} — User Experience Designer
+
+User experience designer focused on interface design and user interactions.
+
+## Project Context
+
+${context || 'Context will be provided by the team.'}
+
+## Responsibilities
+
+- Design user interfaces and interactions
+- Create prototypes and mockups
+- Validate designs with users
+- Maintain design consistency
+- Document design decisions
+
+## Work Style
+
+- Think from the user's perspective
+- Balance aesthetics with usability
+- Iterate based on feedback
+- Maintain design system consistency
+- Collaborate with developers on implementation
+`,
+    'architect': (displayName, context) => `# ${displayName} — Software Architect
+
+Software architect responsible for system design and technical strategy.
+
+## Project Context
+
+${context || 'Context will be provided by the team.'}
+
+## Responsibilities
+
+- Design system architecture
+- Define technical standards
+- Evaluate technology choices
+- Plan for scalability and maintainability
+- Document architectural decisions
+
+## Work Style
+
+- Think holistically about the system
+- Balance ideal design with practical constraints
+- Consider long-term implications
+- Document trade-offs clearly
+- Mentor team on architectural patterns
+`
+};
+/**
+ * Generate a generic charter when no template matches.
+ */
+function generateGenericCharter(displayName, role, context) {
+    return `# ${displayName} — ${titleCase(role)}
+
+Team member focused on ${role} responsibilities.
+
+## Project Context
+
+${context || 'Context will be provided by the team.'}
+
+## Responsibilities
+
+- Collaborate with team members on assigned work
+- Maintain code quality and project standards
+- Document decisions and progress in history
+- Follow team conventions and guidelines
+
+## Work Style
+
+- Read project context and team decisions before starting work
+- Communicate clearly with team members
+- Follow established patterns and conventions
+- Ask questions when requirements are unclear
+- Keep work focused and incremental
+`;
+}
+/**
+ * Generate history.md content with project context.
+ */
+function generateHistory(displayName, role, projectContext, userName) {
+    const now = new Date().toISOString().split('T')[0];
+    return `# Project Context
+
+${userName ? `- **Owner:** ${userName}\n` : ''}- **Agent:** ${displayName}
+- **Role:** ${titleCase(role)}
+- **Onboarded:** ${now}
+
+## Core Context
+
+${projectContext || 'Project context will be provided by the team.'}
+
+## Recent Updates
+
+📌 Agent ${displayName} onboarded on ${now}
+
+## Learnings
+
+Ready to contribute to the team.
+`;
+}
+/**
+ * Convert kebab-case or snake_case to Title Case.
+ */
+function titleCase(str) {
+    return str
+        .split(/[-_]/)
+        .map(word => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase())
+        .join(' ');
+}
+// ============================================================================
+// Onboarding Functions
+// ============================================================================
+/**
+ * Onboard a new agent to the Squad.
+ *
+ * Creates:
+ * - Agent directory at .squad/agents/{name}/
+ * - charter.md from role template + project context
+ * - history.md with project description and tech stack
+ *
+ * @param options - Onboarding options
+ * @returns Result with created file paths
+ */
+export async function onboardAgent(options) {
+    const { teamRoot, agentName, role, displayName, projectContext, userName, charterTemplate } = options;
+    const createdFiles = [];
+    // Validate inputs
+    if (!teamRoot) {
+        throw new Error('teamRoot is required');
+    }
+    if (!agentName) {
+        throw new Error('agentName is required');
+    }
+    if (!role) {
+        throw new Error('role is required');
+    }
+    // Normalize agent name (kebab-case)
+    const normalizedName = agentName.toLowerCase().replace(/[^a-z0-9-]/g, '-');
+    // Create agent directory
+    const agentDir = join(teamRoot, '.squad', 'agents', normalizedName);
+    if (existsSync(agentDir)) {
+        throw new Error(`Agent directory already exists: ${agentDir}`);
+    }
+    await mkdir(agentDir, { recursive: true });
+    // Determine display name
+    const effectiveDisplayName = displayName || titleCase(normalizedName);
+    // Generate charter
+    let charterContent;
+    if (charterTemplate) {
+        charterContent = charterTemplate;
+    }
+    else {
+        const templateFn = CHARTER_TEMPLATES[role.toLowerCase()];
+        if (templateFn) {
+            charterContent = templateFn(effectiveDisplayName, projectContext);
+        }
+        else {
+            charterContent = generateGenericCharter(effectiveDisplayName, role, projectContext);
+        }
+    }
+    // Write charter.md
+    const charterPath = join(agentDir, 'charter.md');
+    await writeFile(charterPath, charterContent, 'utf-8');
+    createdFiles.push(charterPath);
+    // Generate history
+    const historyContent = generateHistory(effectiveDisplayName, role, projectContext, userName);
+    // Write history.md
+    const historyPath = join(agentDir, 'history.md');
+    await writeFile(historyPath, historyContent, 'utf-8');
+    createdFiles.push(historyPath);
+    return {
+        createdFiles,
+        agentDir,
+        charterPath,
+        historyPath
+    };
+}
+/**
+ * Update an agent's configuration to squad.config.ts (if it exists).
+ *
+ * This is a helper function to add agent routing after onboarding.
+ * Only works with TypeScript configs (JSON requires manual edit).
+ *
+ * @param teamRoot - Team root directory
+ * @param agentName - Agent name to add
+ * @param role - Agent role
+ * @returns True if config was updated, false if not found or JSON format
+ */
+export async function addAgentToConfig(teamRoot, agentName, role) {
+    const configPath = join(teamRoot, 'squad.config.ts');
+    if (!existsSync(configPath)) {
+        return false; // No TypeScript config to update
+    }
+    try {
+        const content = await readFile(configPath, 'utf-8');
+        // Simple heuristic: add routing rule if role matches common work types
+        const workTypeMap = {
+            'developer': 'feature-dev',
+            'tester': 'testing',
+            'scribe': 'documentation',
+            'architect': 'architecture',
+            'designer': 'design'
+        };
+        const workType = workTypeMap[role.toLowerCase()];
+        if (!workType) {
+            return false; // No obvious work type mapping
+        }
+        // Check if this work type already has a rule
+        const workTypePattern = new RegExp(`workType:\\s*['"]${workType}['"]`);
+        if (workTypePattern.test(content)) {
+            return false; // Already has a rule for this work type
+        }
+        // Find the routing rules array and add new rule
+        const rulesPattern = /rules:\s*\[([^\]]*)\]/s;
+        const match = content.match(rulesPattern);
+        if (!match) {
+            return false; // Cannot parse rules array
+        }
+        const newRule = `      {
+        workType: '${workType}',
+        agents: ['@${agentName}'],
+        confidence: 'high'
+      }`;
+        const updatedRules = match[1].trim() + ',\n' + newRule;
+        const updatedContent = content.replace(rulesPattern, `rules: [\n${updatedRules}\n    ]`);
+        await writeFile(configPath, updatedContent, 'utf-8');
+        return true;
+    }
+    catch (error) {
+        // Silently fail if we can't parse/update the config
+        return false;
+    }
+}
+//# sourceMappingURL=onboarding.js.map

package/dist/agents/onboarding.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"onboarding.js","sourceRoot":"","sources":["../../src/agents/onboarding.ts"],"names":[],"mappings":"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"}