@compilr-dev/sdk 0.17.14 → 0.17.16

package/dist/project-types/configs.js

@@ -50,11 +50,11 @@ export const softwareConfig = {
         },
     ],
     suggestedAgents: [
-        { role: 'developer', label: 'Developer', description: 'Writes and debugs code' },
-        { role: 'architect', label: 'Architect', description: 'System design and technical decisions' },
+        { role: 'dev', label: 'Developer', description: 'Writes and debugs code' },
+        { role: 'arch', label: 'Architect', description: 'System design and technical decisions' },
         { role: 'qa', label: 'QA', description: 'Testing and quality assurance' },
         { role: 'pm', label: 'PM', description: 'Project planning and coordination' },
-        { role: 'security', label: 'Security', description: 'Security review and hardening' },
+        { role: 'security', label: 'Security Auditor', description: 'Security review and hardening' },
     ],
     documentTemplates: [
         { type: 'prd', label: 'PRD', description: 'Product Requirements Document' },
@@ -485,13 +485,20 @@ export const contentConfig = {
             role: 'strategist',
             label: 'Content Strategist',
             description: 'Planning, ideation, calendar, repurposing',
+            systemPromptAddition: 'You own the content STRATEGY — audience, pillars, editorial calendar, channel mix, and repurposing. Turn goals into a publishable plan and brief the copywriter and visual director. Think in campaigns and cadence, not one-off posts.',
         },
         {
             role: 'writer',
             label: 'Copywriter',
             description: 'Headlines, captions, CTAs, long-form copy',
+            systemPromptAddition: 'You write the COPY — headlines, hooks, captions, CTAs, and long-form. Match the brand voice, write for the channel, and make every line earn attention. Hand visuals to the Visual Director.',
+        },
+        // Canonical `visual` role (Visual Director) — carries its own canvas-first prompt.
+        {
+            role: 'visual',
+            label: 'Visual Director',
+            description: 'Infographics, carousels, visual briefs',
         },
-        { role: 'designer', label: 'Visual Director', description: 'Visual briefs from Brand Model' },
         {
             role: 'editor',
             label: 'Editor',
@@ -601,7 +608,7 @@ export const techDocsConfig = {
     ],
     suggestedAgents: [
         {
-            role: 'technical-writer',
+            role: 'docs',
             label: 'Technical Writer',
             description: 'Clear technical writing and documentation',
         },
@@ -711,9 +718,10 @@ export const courseConfig = {
             description: 'Curriculum design, sequencing, pedagogy',
         },
         {
-            role: 'content-designer',
+            role: 'writer',
             label: 'Content Designer',
             description: 'Lesson planning, exercises, assessments',
+            systemPromptAddition: 'You are the INSTRUCTIONAL DESIGNER — turn learning objectives into lessons, activities, and assessments with clear scaffolding and pacing. Align every piece to an objective.',
         },
         { role: 'reviewer', label: 'Reviewer', description: 'Pedagogical quality, balance, coverage' },
     ],
@@ -820,21 +828,25 @@ export const bookConfig = {
         },
         { id: 'review', label: 'Review', description: 'Structural review', completionCheck: 'manual' },
     ],
+    // Three writer-based specialists — distinct prompts, distinct display names.
     suggestedAgents: [
         {
-            role: 'plotter',
+            role: 'writer',
             label: 'Plotter',
             description: 'Story architecture, beats, pacing, plot threads',
+            systemPromptAddition: 'You own STRUCTURE — premise, arc, beats, pacing, and stakes across the whole book. Keep the throughline coherent and flag sagging middles. You outline; you do not prose scenes.',
         },
         {
-            role: 'character-dev',
+            role: 'writer',
             label: 'Character Dev',
             description: 'Characters, arcs, relationships, voice',
+            systemPromptAddition: 'You own CHARACTER — motivation, voice, arcs, and relationships. Keep each character consistent and growing, and ensure their voices are distinct.',
         },
         {
-            role: 'scene-writer',
+            role: 'writer',
             label: 'Scene Writer',
             description: 'Scene construction, setting, POV, transitions',
+            systemPromptAddition: 'You write SCENES — prose that shows, with sensory detail, subtext, and momentum. Enter late, leave early; every scene turns on a change.',
         },
     ],
     documentTemplates: [

package/dist/project-types/types.d.ts

@@ -23,11 +23,24 @@ export interface ProjectPhase {
  * A suggested agent role for this project type.
  */
 export interface SuggestedAgent {
+    /** BASE canonical role the specialist runs on (dev, writer, strategist, …). */
     role: string;
+    /** Display name — becomes the created agent's displayName (not the generic role name). */
     label: string;
     description: string;
     /** Auto-add on project creation? */
     autoAdd?: boolean;
+    /**
+     * Specialist prompt appended to the base role's prompt — makes an advertised
+     * specialist real (e.g. a "Plotter" on the `writer` role). Optional: when
+     * absent, the agent is a plain base-role agent that just carries `label` as
+     * its display name. See specialized-team-agents-spec §4.
+     */
+    systemPromptAddition?: string;
+    /** Optional tool-profile override when the base role's profile lacks a need. */
+    toolProfile?: string;
+    /** Optional extra skills to enable for this specialist. */
+    skills?: string[];
 }
 /**
  * A document template available for this project type.

package/dist/team/role-aliases.js

@@ -31,8 +31,10 @@ export const ROLE_NAME_ALIASES = {
     developer: 'dev',
     architect: 'arch',
     'technical-writer': 'docs',
-    security: 'reviewer',
-    designer: 'default',
+    // 'security' is now a canonical role (Security Auditor) — passthrough handles it.
+    designer: 'visual',
+    'art-director': 'visual',
+    'visual-director': 'visual',
     'character-dev': 'writer',
     'content-designer': 'writer',
     plotter: 'writer',

package/dist/team/team-agent.d.ts

@@ -8,7 +8,7 @@
  * - Optional tool filtering
  */
 import type { Agent, AgentConfig, ContextManager } from '@compilr-dev/agents';
-import type { TeamAgentConfig, SerializedTeamAgent, MascotExpression, AgentRole } from './types.js';
+import type { TeamAgentConfig, SerializedTeamAgent, MascotExpression, AgentRole, ToolProfile } from './types.js';
 import type { ModelTier } from '../models/index.js';
 import type { ProviderType } from '../config.js';
 import type { SharedContextManager } from './shared-context.js';
@@ -186,6 +186,20 @@ export declare class TeamAgent {
      * @param modelTier - Optional model tier override (defaults to role's default tier)
      */
     static fromRole(role: AgentRole, id?: string, modelTier?: ModelTier): TeamAgent;
+    /**
+     * Create a specialized TeamAgent from a BASE role plus overrides — used for the
+     * project wizard's "specialist" agents (e.g. a Copywriter on the `writer` role, a
+     * Plotter on `writer`). Runs the base role's behavior with an appended specialist
+     * prompt and a custom display name (the wizard label), without needing a new
+     * first-class AgentRole. See specialized-team-agents-spec §4.
+     */
+    static fromSpecialist(baseRole: AgentRole, opts: {
+        id?: string;
+        displayName?: string;
+        systemPromptAddition?: string;
+        toolProfile?: ToolProfile;
+        modelTier?: ModelTier;
+    }): TeamAgent;
     /**
      * Create a TeamAgent from a custom agent definition
      */

package/dist/team/team-agent.js

@@ -479,6 +479,49 @@ export class TeamAgent {
             modelTier: modelTier ?? metadata.defaultModelTier,
         });
     }
+    /**
+     * Create a specialized TeamAgent from a BASE role plus overrides — used for the
+     * project wizard's "specialist" agents (e.g. a Copywriter on the `writer` role, a
+     * Plotter on `writer`). Runs the base role's behavior with an appended specialist
+     * prompt and a custom display name (the wizard label), without needing a new
+     * first-class AgentRole. See specialized-team-agents-spec §4.
+     */
+    static fromSpecialist(baseRole, opts) {
+        const metadata = ROLE_METADATA[baseRole];
+        const profile = opts.toolProfile ?? metadata.defaultToolProfile;
+        const toolFilter = profile ? getToolsForProfile(profile) : undefined;
+        // Base role prompt + the specialist addition (specialization on top of role).
+        let systemPromptAddition = metadata.defaultSystemPromptAddition ?? '';
+        if (opts.systemPromptAddition?.trim()) {
+            systemPromptAddition = systemPromptAddition
+                ? `${systemPromptAddition}\n\n${opts.systemPromptAddition.trim()}`
+                : opts.systemPromptAddition.trim();
+        }
+        if (profile && profile !== 'full') {
+            const toolAwareness = generateToolAwarenessPrompt({ profile });
+            systemPromptAddition = systemPromptAddition
+                ? `${systemPromptAddition}\n\n${toolAwareness}`
+                : toolAwareness;
+        }
+        // Specialists always get collaboration guidance (never the coordinator path).
+        const specialistGuidance = generateSpecialistGuidance(baseRole);
+        systemPromptAddition = systemPromptAddition
+            ? `${systemPromptAddition}\n\n${specialistGuidance}`
+            : specialistGuidance;
+        return new TeamAgent({
+            id: opts.id ?? baseRole,
+            displayName: opts.displayName ?? metadata.displayName,
+            mascot: metadata.mascot,
+            role: baseRole,
+            description: metadata.description,
+            systemPromptAddition: systemPromptAddition || undefined,
+            useMinimalSystemPrompt: metadata.useMinimalSystemPrompt,
+            noTools: metadata.noTools,
+            toolFilter,
+            toolProfile: profile,
+            modelTier: opts.modelTier ?? metadata.defaultModelTier,
+        });
+    }
     /**
      * Create a TeamAgent from a custom agent definition
      */

package/dist/team/team.d.ts

@@ -173,6 +173,18 @@ export declare class AgentTeam {
      * @param modelTier - Optional model tier override (defaults to role's default tier)
      */
     addAgentFromRole(role: AgentRole, id?: string, modelTier?: ModelTier): Promise<TeamAgent>;
+    /**
+     * Add a SPECIALIST agent — a base role with a custom display name and an
+     * appended specialist prompt (project-wizard specialists, e.g. Copywriter on
+     * `writer`, Plotter on `writer`). See specialized-team-agents-spec §4.
+     */
+    addSpecialistAgent(baseRole: AgentRole, opts: {
+        id?: string;
+        displayName?: string;
+        systemPromptAddition?: string;
+        toolProfile?: import('./tool-config.js').ToolProfile;
+        modelTier?: ModelTier;
+    }): Promise<TeamAgent>;
     /**
      * Add a custom agent from a CustomAgentDefinition
      */

package/dist/team/team.js

@@ -239,6 +239,43 @@ export class AgentTeam {
         this.emit({ type: 'agent:added', agentId });
         return teamAgent;
     }
+    /**
+     * Add a SPECIALIST agent — a base role with a custom display name and an
+     * appended specialist prompt (project-wizard specialists, e.g. Copywriter on
+     * `writer`, Plotter on `writer`). See specialized-team-agents-spec §4.
+     */
+    async addSpecialistAgent(baseRole, opts) {
+        // Default the id to a slug of the display name so same-base-role specialists
+        // (three writers: Plotter/Character Dev/Scene Writer) get distinct ids.
+        const slug = opts.displayName
+            ? opts.displayName
+                .toLowerCase()
+                .replace(/[^a-z0-9]+/g, '-')
+                .replace(/^-+|-+$/g, '')
+            : '';
+        let agentId = opts.id ?? (slug || baseRole);
+        if (this._sessionRegistry) {
+            const globalIds = this._sessionRegistry.getGlobalAgentIds();
+            const localIds = Array.from(this.agents.keys());
+            const resolved = resolveAgentIdCollision(agentId, localIds, globalIds);
+            if (resolved.wasCollision) {
+                const originalId = agentId;
+                agentId = resolved.id;
+                this.emit({ type: 'agent:collision', originalId, agentId: resolved.id });
+            }
+        }
+        if (this.agents.has(agentId)) {
+            throw new Error(`Agent '${agentId}' already exists in team`);
+        }
+        const teamAgent = TeamAgent.fromSpecialist(baseRole, { ...opts, id: agentId });
+        this.agents.set(agentId, teamAgent);
+        await teamAgent.initialize(this.agentFactory, this._sharedContext);
+        this._sharedContext.addAgent(agentId);
+        this.updateTeamRoster();
+        this.updatedAt = new Date();
+        this.emit({ type: 'agent:added', agentId });
+        return teamAgent;
+    }
     /**
      * Add a custom agent from a CustomAgentDefinition
      */

package/dist/team/tool-config.d.ts

@@ -7,7 +7,7 @@
  * Tool names are defined as string constants below. These cover all tools
  * from @compilr-dev/agents, @compilr-dev/agents-coding, and platform tools.
  */
-export type ToolProfile = 'full' | 'read-only' | 'developer' | 'security' | 'docs' | 'devops' | 'qa' | 'architect' | 'planner' | 'analyst' | 'custom';
+export type ToolProfile = 'full' | 'read-only' | 'developer' | 'security' | 'docs' | 'devops' | 'qa' | 'architect' | 'planner' | 'analyst' | 'designer' | 'custom';
 export interface ToolConfig {
     /** Tool profile (predefined set) */
     profile: ToolProfile;

package/dist/team/tool-config.js

@@ -670,6 +670,25 @@ export const TOOL_PROFILES = {
         'web',
         'factory_models',
     ],
+    // Designer - visual canvas authoring (canvas/artifacts/documents), reads code
+    // but does not edit source files.
+    designer: [
+        'file_read',
+        'interaction',
+        'handoff',
+        'consult',
+        'guide',
+        'subagents',
+        'meta',
+        'project',
+        'search',
+        'documents',
+        'canvas',
+        'artifacts',
+        'anchors',
+        'web',
+        'factory_models',
+    ],
     // Custom - user selected (groups specified in customGroups)
     custom: [],
 };
@@ -724,6 +743,11 @@ export const PROFILE_INFO = {
         description: 'Requirements gathering - user stories, documents, business analysis',
         isReadOnly: true,
     },
+    designer: {
+        label: 'Visual Designer',
+        description: 'Create visual canvases, infographics, and decks - reads code, no source edits',
+        isReadOnly: true,
+    },
     custom: {
         label: 'Custom',
         description: 'Select tool groups manually',

package/dist/team/types.d.ts

@@ -5,7 +5,7 @@
  */
 import type { AgentConfig, AgentState } from '@compilr-dev/agents';
 import type { ModelTier } from '../models/index.js';
-export type ToolProfile = 'full' | 'read-only' | 'developer' | 'security' | 'docs' | 'devops' | 'qa' | 'architect' | 'planner' | 'analyst' | 'custom';
+export type ToolProfile = 'full' | 'read-only' | 'developer' | 'security' | 'docs' | 'devops' | 'qa' | 'architect' | 'planner' | 'analyst' | 'designer' | 'custom';
 /**
  * Information about a background agent session.
  * Used by /bg overlay to display status.
@@ -29,11 +29,11 @@ export interface BackgroundSessionInfo {
 /**
  * Mascot expressions for visual differentiation of agents
  */
-export type MascotExpression = '[•_•]' | '[◈_◈]' | '[▣_▣]' | '[◉_◉]' | '[▲_▲]' | '[◆_◆]' | '[○_○]' | '[◇_◇]' | '[◎_◎]' | '[⊘_⊘]' | '[✎_✎]' | '[◒_◒]' | '[◔_◔]' | '[◓_◓]' | '[◕_◕]' | '[□_□]';
+export type MascotExpression = '[•_•]' | '[◈_◈]' | '[▣_▣]' | '[◉_◉]' | '[▲_▲]' | '[◆_◆]' | '[○_○]' | '[◇_◇]' | '[◎_◎]' | '[⊘_⊘]' | '[✎_✎]' | '[◒_◒]' | '[◔_◔]' | '[◓_◓]' | '[◕_◕]' | '[◐_◐]' | '[⊗_⊗]' | '[□_□]';
 /**
  * Predefined agent roles with default configurations
  */
-export type AgentRole = 'default' | 'pm' | 'arch' | 'qa' | 'dev' | 'ops' | 'docs' | 'ba' | 'researcher' | 'reviewer' | 'editor' | 'writer' | 'analyst' | 'strategist' | 'instructor' | 'custom';
+export type AgentRole = 'default' | 'pm' | 'arch' | 'qa' | 'dev' | 'ops' | 'docs' | 'ba' | 'researcher' | 'reviewer' | 'editor' | 'writer' | 'analyst' | 'strategist' | 'instructor' | 'visual' | 'security' | 'custom';
 /**
  * Role groups for UI display (Workshop, team overlay).
  * Groups roles by domain — used for visual categorization.
@@ -42,7 +42,7 @@ export declare const ROLE_GROUPS: Record<string, AgentRole[]>;
 /**
  * List of predefined role IDs (for validation against custom agent IDs)
  */
-export declare const PREDEFINED_ROLE_IDS: readonly ["default", "pm", "arch", "qa", "dev", "ops", "docs", "ba", "researcher", "reviewer", "editor", "writer", "analyst", "strategist", "instructor"];
+export declare const PREDEFINED_ROLE_IDS: readonly ["default", "pm", "arch", "qa", "dev", "ops", "docs", "ba", "researcher", "reviewer", "editor", "writer", "analyst", "strategist", "instructor", "visual", "security"];
 /**
  * Role metadata for predefined roles
  */

package/dist/team/types.js

@@ -8,8 +8,9 @@
  * Groups roles by domain — used for visual categorization.
  */
 export const ROLE_GROUPS = {
-    Software: ['dev', 'arch', 'qa', 'pm', 'ops'],
+    Software: ['dev', 'arch', 'qa', 'pm', 'ops', 'security'],
     'Writing & Analysis': ['writer', 'editor', 'reviewer', 'researcher', 'analyst', 'docs', 'ba'],
+    Design: ['visual'],
     'Business & Education': ['strategist', 'instructor'],
 };
 /**
@@ -31,6 +32,8 @@ export const PREDEFINED_ROLE_IDS = [
     'analyst',
     'strategist',
     'instructor',
+    'visual',
+    'security',
 ];
 /**
  * Role expertise keywords for team awareness
@@ -70,6 +73,8 @@ export const ROLE_EXPERTISE = {
     analyst: ['market research', 'data analysis', 'competitive intelligence', 'trends'],
     strategist: ['business strategy', 'vision', 'go-to-market', 'planning'],
     instructor: ['curriculum design', 'lesson planning', 'assessment', 'pedagogy'],
+    visual: ['infographics', 'carousels', 'boards', 'data-viz', 'visual hierarchy'],
+    security: ['security review', 'OWASP', 'vulnerabilities', 'dependency risk', 'threat modeling'],
     custom: [], // User-defined
 };
 /**
@@ -901,6 +906,51 @@ You are the **Instructor** in this multi-agent team. You specialize in education
         defaultToolProfile: 'docs', // Read + write educational content
         defaultModelTier: 'balanced',
     },
+    visual: {
+        displayName: 'Visual Director',
+        mascot: '[◐_◐]',
+        description: 'Visual canvases — infographics, carousels, boards',
+        defaultToolProfile: 'designer',
+        defaultModelTier: 'balanced',
+        defaultSystemPromptAddition: `# ROLE: VISUAL DIRECTOR
+
+You are the **Visual Director**. Your PRIMARY deliverable is a **visual canvas**, not prose.
+
+## How you work
+- When a request can be answered visually — a stat, a comparison, a process, an announcement, a summary, a pitch, a layout — you produce a CANVAS, not a text reply.
+- Pick the type deliberately: **infographic** (one composition), **carousel** (a sequence / deck), **board** (spatial mind-map / UI sketch). Then follow the matching craft skill (infographic / carousel / board) for the design rules.
+- Author with \`canvas_write\` / \`canvas_edit\` incrementally (small calls). Theme with \`var(--canvas-*)\`; set an explicit \`var(--canvas-bg)\` (except boards — keep those transparent); add 2–4 bound Tweaks.
+- You MAY add a one-line framing note, but the ARTIFACT is the canvas.
+
+## Collaboration
+- Take copy, data, and structure from the writer / strategist / researcher and turn it into visuals. You are the team's eyes: turn text into something worth looking at.
+
+## Guardrail
+- Canvas is your DEFAULT, not your cage. If the user explicitly asks for text, a document, or prose, honor that — don't force a canvas where words are wanted.`,
+    },
+    security: {
+        displayName: 'Security Auditor',
+        mascot: '[⊗_⊗]',
+        description: 'Security review — vulnerabilities, dependencies, unsafe patterns',
+        defaultToolProfile: 'security',
+        defaultModelTier: 'balanced',
+        defaultSystemPromptAddition: `# ROLE: SECURITY AUDITOR
+
+You are the **Security Auditor**. You review code, config, and dependencies for vulnerabilities and unsafe patterns — you do NOT ship features or edit code.
+
+## Focus
+- OWASP Top 10: injection, broken authn/authz, secrets in code, SSRF, path traversal, unsafe deserialization, insecure defaults.
+- Dependencies: known-vuln packages, supply-chain risk, over-broad permissions.
+- Input validation, output encoding, least privilege, safe defaults.
+
+## How you work
+- READ code / config / dependencies (you have read + search + dependency tools; you have NO edit tools — that is intentional).
+- Use the \`security-review\` / \`code-review\` skills for structured passes.
+- Report findings with **SEVERITY**, \`file:line\`, and a concrete fix. Rank by exploitability × impact; surface the top risks first. Hand off remediation to the developer.
+
+## Boundary
+- Advisory only — you flag and recommend; you do not apply the fix.`,
+    },
     custom: {
         displayName: 'Custom Agent',
         mascot: '[□_□]',
@@ -986,4 +1036,14 @@ export const ROLE_COPY = {
         bestFor: "you're teaching something and need it structured for learners.",
         pairsWith: ['reviewer', 'writer'],
     },
+    visual: {
+        tagline: 'Turns ideas and copy into visual canvases — infographics, decks, boards.',
+        bestFor: 'you want something SHOWN, not written — a one-pager, a carousel, a mind-map.',
+        pairsWith: ['writer', 'strategist'],
+    },
+    security: {
+        tagline: 'Audits code and dependencies for vulnerabilities — advisory, no edits.',
+        bestFor: 'you want a security pass — OWASP risks, dependency vulns, unsafe patterns.',
+        pairsWith: ['dev', 'arch'],
+    },
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compilr-dev/sdk",
-  "version": "0.17.14",
+  "version": "0.17.16",
   "description": "Universal agent runtime for building AI-powered applications",
   "type": "module",
   "main": "dist/index.js",