[mbeps]

1. High-Level Overview

Goal: Enable prompt shortcuts and agent skills to be scoped to multiple projects, multiple assistants, both simultaneously, or neither (global), replacing single-entity mutual exclusion with multi-entity array scoping and an intuitive Shadcn UI selector.

flowchart TD
    subgraph UI ["User Interface (Shadcn UI)"]
        Tab["Scope & Visibility Tab / Form"]
        Mode["Mode: Global vs. Scoped"]
        ProjSelect["Projects Multi-Select (Combobox / Popover + Badges)"]
        AsstSelect["Assistants Multi-Select (Combobox / Popover + Badges)"]
    end

    subgraph DataModel ["Data Model & Validation"]
        Zod["Zod Schemas: projectIds: string[], assistantIds: string[]"]
        Drizzle["Drizzle: project_ids text[], assistant_ids text[]"]
    end

    subgraph Runtime ["Execution & Scoping Context"]
        FilterPrompts["filterAccessiblePrompts(prompts, context)"]
        FilterSkills["filterAccessibleSkills(skills, context)"]
        ChatCtx["loadChatContext & registerSkillTool"]
    end

    Mode -->|"Global"| Zod
    Mode -->|"Scoped"| ProjSelect & AsstSelect
    ProjSelect & AsstSelect --> Zod
    Zod --> Drizzle
    Drizzle --> Runtime

Loading

Global Constraints

• Zero-Git commit policy (only read-only git commands).
• Use Podman for database containers if needed.
• No modifications to Shadcn UI primitives in components/ui/; compose them into high-level features.
• Radical simplicity (YAGNI/Ponytail): Reuse existing array column patterns from assistant and project rather than introducing junction tables.
• No backwards compatibility required; migrate existing PostgreSQL data directly.

---

2. User Review Required

Important

Database Migration: The single-column foreign keys project_id and assistant_id on both prompt and skill tables are replaced with PostgreSQL native array columns project_ids text[] DEFAULT '{}'::text[] NOT NULL and assistant_ids text[] DEFAULT '{}'::text[] NOT NULL. Existing rows with non-null values will be migrated into 1-element arrays before dropping the legacy columns.

Note

Scope UI Concept:
The UI replaces the 3 mutually-exclusive radio buttons (Global, Project, Assistant) with:

1. A clean two-state selector: Global (available everywhere) vs. Scoped (restricted to specific entities).
2. When Scoped is active, two multi-select pickers appear side-by-side or stacked:
   • Projects Multi-Select: Combobox/Popover with search, checkable items, and removable badges.
   • Assistants Multi-Select: Combobox/Popover with search, checkable items, and removable badges.
3. Users can select any combination (e.g., 2 projects AND 1 assistant, or 3 projects only, or 2 assistants only).

---

3. Alternatives Evaluated

Architecture	Pros	Cons	Verdict
Array Columns (project_ids text[], assistant_ids text[])	100% consistent with project.skill_ids, project.prompt_ids, assistant.skill_ids, assistant.prompt_ids. Zero joins needed. Instant client hydration into Zustand store. Minimal code changes.	Relies on PostgreSQL array operations instead of standard relational junction tables.	Selected (Recommended)
Junction Tables (prompt_projects, prompt_assistants, skill_projects, skill_assistants)	Standard relational 3NF design with native cascading foreign keys.	Requires 4 new tables, complex SQL joins on every fetch (listPrompts, listSkills, loadChatContext), complex Drizzle relational mapping, much higher code bloat. Violates YAGNI.	Rejected
JSONB Scope Document (scopes: jsonb)	Flexible schema.	Overkill for simple lists of UUIDs, worse typing in Drizzle, harder array search index.	Rejected

---

4. Edge Cases & Failure Modes

• Entity Deletion: If a user deletes a project or assistant, any prompt or skill that included that entity ID will still function for its remaining scopes. If it had only that entity, it becomes global or empty scoped. We also sanitize IDs in filterAccessiblePrompts / filterAccessibleSkills.
• Empty Scoped Selection: If a user selects "Scoped" mode but doesn't select any projects or assistants, form validation requires at least 1 selection or switching back to "Global".
• Chat in Project WITH Assistant: If a chat is set to Project A and uses Assistant B, prompts/skills scoped to Project A, OR Assistant B, OR Global (governed by modes) will all be accessible.
• Pre-filling from URL parameters: When opening /settings/prompts/new?projectId=123, projectIds is initialized with ['123'], and the user can easily add more projects or assistants.