@sellable/mcp 0.1.0

package/skills/create-campaign/ARCHITECTURE.md

@@ -0,0 +1,232 @@
+# Create Campaign Prompt Architecture
+
+This document explains the architecture of the create-campaign prompt system,
+what we learned from GSD, and how to extend the system safely.
+
+## What GSD Gets Right (Patterns to Reuse)
+
+GSD is not "one big prompt." It is a layered system:
+
+1. Skills orchestrate
+2. Workflows define processes
+3. References capture reusable rules
+4. Templates standardize artifacts
+5. State files provide runtime memory
+6. Config files control modes, models, and gates
+
+Key architectural ideas worth copying:
+
+- Separation of concerns (orchestration vs execution vs policy)
+- Versioned, file-based contracts (templates + frontmatter)
+- Deterministic verification as a first-class workflow
+- Explicit gating and safety rails
+- Registry-style extensibility (map-codebase, templates, references)
+
+## Our Architecture Overview
+
+We now follow a similar layered design for `/sellable:create-campaign`.
+
+### Layer 1: Skill Orchestrator
+
+File:
+
+- `mcp/sellable/skills/create-campaign/SKILL.md`
+
+Responsibilities:
+
+- Load the framework at runtime
+- Apply overrides deterministically
+- Execute the configured flow
+- Keep the user oriented in watch mode
+
+The skill is now a thin orchestrator, not the source of truth.
+
+### Layer 2: Framework Loader (Runtime Contract)
+
+File:
+
+- `mcp/sellable/src/tools/framework.ts`
+
+Tools:
+
+- `get_campaign_framework`
+- `get_campaign_context`
+
+`get_campaign_navigation_state` remains available for internal debugging but is
+not part of the official skill interface.
+
+`get_campaign_framework` loads all versioned configuration:
+
+- Policy text
+- Flow definition
+- Provider registry
+- Provider configs
+- Plugin context
+- Plugin overrides
+
+This mirrors GSD's "load state/config first" pattern.
+
+### Layer 3: Policy (Invariant Rules)
+
+File:
+
+- `mcp/sellable/skills/create-campaign/core/policy.md`
+
+Policy defines what must remain true even if other instructions drift:
+
+- Bootstrap requirements
+- Watch-mode protocol
+- Debug-tool rules
+- Wait-state rules
+- Provider contract rules
+- User-directed research overrides
+
+This is our equivalent of GSD references.
+
+### Layer 4: Flow (State Machine)
+
+File:
+
+- `mcp/sellable/skills/create-campaign/core/flow.v1.json`
+
+Flow is the state machine:
+
+- Steps
+- Required on-enter actions
+- Wait conditions
+- Transitions
+- Watch-mode templates
+
+This removes ambiguity from the main prompt.
+
+### Layer 5: Providers (Registry + Plugins)
+
+Files:
+
+- `mcp/sellable/skills/create-campaign/core/providers/registry.json`
+- `mcp/sellable/skills/create-campaign/core/providers/*.json`
+
+Each provider is now a plugin-style config with:
+
+- `currentStep` mapping
+- `leadSourceProvider` value
+- `promptProvider` for `get_provider_prompt`
+- Watch-mode text
+- Recommendation metadata
+- AskUserQuestion option text
+
+This is the main extensibility surface for adding new providers.
+
+### Layer 6: Customization (User/Org Context + Overrides)
+
+Files:
+
+- `mcp/sellable/skills/create-campaign/context/registry.json`
+- `mcp/sellable/skills/create-campaign/context/*.md`
+
+Plugins provide two things:
+
+1. Freeform context (markdown)
+2. Structured overrides (in registry entries)
+
+Overrides are merged in the loader and applied by the skill.
+
+This is directly inspired by GSD's "state + config + references" layering.
+
+## Determinism Strategy
+
+Determinism comes from configuration, not phrasing:
+
+1. The skill must load the framework before acting
+2. The flow defines what happens on step entry
+3. Provider configs define how selection maps to state
+4. Policy defines the guardrails
+5. Validation scripts check integrity offline
+
+In practice, this means:
+
+- No hardcoded provider tables in SKILL.md
+- No provider-specific step mapping in prose
+- Watch-mode behavior is a protocol, not a suggestion
+
+## Extensibility Strategy
+
+### Add a Provider
+
+1. Create `core/providers/<id>.json`
+2. Add it to `core/providers/registry.json`
+3. Ensure the provider prompt exists (if needed)
+4. Run:
+   - `npm run validate:create-campaign-framework`
+   - `npx tsc -p mcp/sellable/tsconfig.json --noEmit`
+
+Provider config is the only place you should define:
+
+- Step mapping
+- Provider wiring
+- Watch-mode copy
+
+### Add Custom Context or Overrides
+
+1. Add a context file in `context/`
+2. Register it in `context/registry.json`
+3. Put structured overrides in the registry entry
+4. Re-run the validator
+
+Customization allows teams and users to shape behavior without editing the
+orchestrator.
+
+## Validation and Safety Rails
+
+We added an offline validator:
+
+- `scripts/validate-create-campaign-framework.mjs`
+- `npm run validate:create-campaign-framework`
+
+This plays the same role as GSD's verification workflow:
+
+- Ensure flows reference real steps
+- Ensure providers are complete and consistent
+- Ensure plugin files exist
+
+We also ensure the JSON framework is versioned:
+
+- Root `.gitignore` allows `web/mcp/sellable/skills/create-campaign/**/*.json`
+
+## Architecture Diagram (Mental Model)
+
+Runtime call graph:
+
+1. Skill loads tools
+2. Skill calls `get_campaign_framework`
+3. Loader reads policy + flow + registries + plugins
+4. Skill executes flow using provider configs + policy rules
+5. Provider prompts remain the domain experts for search execution
+
+This matches the GSD pattern:
+
+- Orchestrator delegates execution expertise to specialized modules
+
+## What We Borrowed from GSD
+
+From GSD, we explicitly adopted:
+
+- Lean orchestration
+- File-based contracts
+- A runtime "load config first" step
+- Separation between policy vs workflow vs implementation detail
+- Verification as a separate concern
+
+## Suggested Next Improvements (Optional)
+
+If we want to push this even closer to GSD-level determinism:
+
+1. Move recommendation logic into the framework tool
+   - e.g., `resolve_provider_recommendation(...)`
+2. Add tool availability detection for Chrome URL opening
+   - e.g., `get_client_capabilities`
+3. Add a flow validator that checks required tool fields per step
+4. Version provider prompts alongside provider configs
+
+These are not required for the current architecture to work, but they would
+reduce prompt-level decision-making further.

package/skills/create-campaign/DISCUSS.md

@@ -0,0 +1,296 @@
+# Create Campaign - Design Discussion
+
+Purpose: align on how the create-campaign system should work before adding
+more features.
+
+This doc is for decisions, not implementation details.
+
+---
+
+## 1) What the user runs
+
+User interface stays simple:
+
+- `/sellable:create-campaign`
+
+Everything else is internal structure that loads automatically.
+
+---
+
+## 2) Current runtime architecture (as built)
+
+At the start of every run:
+
+1. `SKILL.md` calls `get_campaign_framework({ flowVersion: "v1", includePlugins: true })`
+2. The framework loader reads from:
+   - Core system config: `core/`
+   - User/org context: `context/`
+
+During the run, state is confirmed server-side:
+
+- `update_campaign(...)` returns `navigation` diagnostics immediately
+- `get_campaign_context({ campaignId })` returns cached framework + navigation
+- After `confirm_lead_list(...)`, advance UI immediately with
+  `update_campaign({ currentStep: "filter-choice" })`, then gate on
+  `wait_for_campaign_table_ready({ campaignId })` and sample via
+  `get_rows_minimal(...)` for the filter recommendation
+
+Provider search expertise is still injected separately via:
+
+- `get_provider_prompt(...)` -> `mcp/sellable/skills/providers/*.md`
+
+So there are two kinds of prompt injection:
+
+1. Framework injection (policy + flow + providers + context)
+2. Provider prompt injection (provider-specific search playbooks)
+
+---
+
+## 3) Folder structure and touch zones
+
+Goal: a user should know what they can safely edit by looking at the tree.
+
+Safe to edit:
+
+- `context/context.md` (business context)
+- `context/registry.json` (defaults and overrides)
+- `context/learnings.md` (notes)
+
+System-owned (edit rarely and intentionally):
+
+- `core/policy.md`
+- `core/flow.v1.json`
+- `core/providers/*.json`
+
+Orchestrator (do not edit for normal customization):
+
+- `SKILL.md`
+
+---
+
+## 4) Flow map and gating model
+
+Gates are intentional. After UI state changes, the assistant should orient and
+wait.
+
+High-level flow:
+
+1. Bootstrap
+2. Discovery + enrichment
+3. Direction + onboarding
+4. Create campaign (Gate: review brief)
+5. Move to provider selection (Gate: confirm step is visible)
+6. Move to provider step (Gate: confirm provider UI is visible)
+7. Provider prompt injection + search
+8. Import leads -> review list -> confirm (Gate: confirm list looks right)
+9. Enable filtering (yes/no) then handoff to rubric/messages
+
+Gating rule:
+
+- After every `update_campaign({ currentStep: ... })`: check returned `navigation`, orient in watch mode, and wait for confirmation.
+
+Import rule:
+
+- After `import_leads(...)`, call `wait_for_lead_list_ready({ campaignOfferId })`
+  before asking the user to confirm the list.
+- After `confirm_lead_list(...)`, call `update_campaign({ currentStep: "filter-choice" })`
+  immediately, then `wait_for_campaign_table_ready({ campaignId })`, then
+  `get_campaign_context({ refresh: true })` + `get_rows_minimal(...)`.
+
+Debug rule:
+
+- Only use Chrome tools when the user says something is wrong.
+
+---
+
+## 5) Proposed data model (MVP contract)
+
+This is the minimum contract we should agree on and then enforce.
+
+### 5.1 Framework response shape
+
+```ts
+type CampaignFramework = {
+  version: "v1";
+  flowVersion: "v1";
+  policy: string;
+  flow: FlowConfig;
+
+  providerRegistry: ProviderRegistry;
+  providers: Record<ProviderId, ProviderConfig>;
+
+  contextRegistry: ContextRegistry;
+  contextEntries: LoadedContextEntry[];
+  overrides: FrameworkOverrides;
+
+  warnings: string[];
+};
+```
+
+### 5.2 Providers
+
+```ts
+type ProviderId = "signal-discovery" | "sales-nav" | "apollo";
+
+type ProviderConfig = {
+  id: ProviderId;
+  label: string;
+  leadSourceProvider: string;
+  currentStep: string;
+  promptProvider: "signal-discovery" | "sales-nav" | "apollo";
+
+  requiredTools: string[];
+  watch: { stepVisible: string; afterImport: string };
+  askOption: { label: string; description: string };
+};
+```
+
+### 5.3 Context entries (currently called plugins)
+
+We can keep the current JSON key (`plugins`) but treat each item as a context
+entry.
+
+```ts
+type ContextRegistry = {
+  version: "v1";
+  plugins: ContextEntry[];
+};
+
+type ContextEntry = {
+  id: string;
+  path: string;
+  enabled: boolean;
+  description?: string;
+  overrides?: FrameworkOverrides;
+};
+```
+
+### 5.4 Overrides
+
+```ts
+type FrameworkOverrides = {
+  providerPreference?: ProviderId;
+  providerOrder?: ProviderId[];
+  defaultLeadTarget?: number;
+  researchMode?: "framework-driven" | "user-directed";
+  researchNotes?: string;
+};
+```
+
+---
+
+## 6) Decisions to lock (proposed)
+
+If you agree, we can treat these as v1 decisions.
+
+1. The interface remains `/sellable:create-campaign`
+2. `context/` is the only user-safe customization surface
+3. Provider prompts stay in `mcp/sellable/skills/providers/*.md`
+4. Gates are required after every `currentStep` change
+5. We do not support manual upload yet (3 providers only)
+
+---
+
+## 7) Open questions
+
+Use this section as a checklist.
+
+- Should we rename `plugins` -> `contextEntries` in the registry JSON?
+- Should provider recommendation logic move into MCP (tool) vs prompt?
+- Should we add a capabilities tool so gating can be verified via Chrome when available?
+- Do we want per-workspace context files later, or keep repo-only for now?
+
+---
+
+## 8) ASCII flow map (what loads, when, and why)
+
+This is the end-to-end control flow for `/sellable:create-campaign`.
+
+```text
+USER
+  |
+  |  invokes /sellable:create-campaign
+  v
+SKILL: mcp/sellable/skills/create-campaign/SKILL.md
+  |
+  |-- ToolSearch (bootstrap tools)
+  |
+  |-- get_campaign_framework({ flowVersion: "v1", includePlugins: true })
+  |     |
+  |     v
+  |   TOOL: mcp/sellable/src/tools/framework.ts
+  |     |
+  |     |-- loads core policy:
+  |     |     mcp/sellable/skills/create-campaign/core/policy.md
+  |     |
+  |     |-- loads state machine flow:
+  |     |     mcp/sellable/skills/create-campaign/core/flow.v1.json
+  |     |
+  |     |-- loads provider registry:
+  |     |     mcp/sellable/skills/create-campaign/core/providers/registry.json
+  |     |        -> then loads each provider config it references
+  |     |           (apollo.json, sales-nav.json, signal-discovery.json)
+  |     |
+  |     |-- loads context registry:
+  |     |     mcp/sellable/skills/create-campaign/context/registry.json
+  |     |        -> then loads each enabled context entry it references
+  |     |           (for example: context/context.md, context/learnings.md)
+  |     |
+  |     '-- returns: policy + flow + providers + context entries + overrides
+  |
+  |== From here on, the flow is driven by core/flow.v1.json ==
+  |
+  |  Step 1: campaign-created (Campaign Brief)
+  |    - Tool: create_campaign(...)
+  |    - No currentStep jump yet
+  |
+  |  Step 2: pick-provider (Provider Selection)
+  |    - Tool: update_campaign({ campaignId, currentStep: "pick-provider" })
+  |    - Result: update_campaign returns navigation diagnostics
+  |    - Watch gate: tell user what changed -> wait for confirmation
+  |
+  |  Step 3: provider-search (Provider Search)
+  |    - Tool: update_campaign({ campaignId, currentStep, leadSourceProvider })
+  |    - Tool: get_provider_prompt({ provider })
+  |         -> loads provider instructions from:
+  |            mcp/sellable/skills/providers/{provider}.md
+  |    - Tools: search_* -> import_leads(...) -> wait_for_lead_list_ready(...) -> confirm_lead_list(...)
+  |    - Wait for user confirmation on lead list
+  |    - Tool: confirm_lead_list({ campaignId })
+  |    - Tool: update_campaign({ campaignId, currentStep: "filter-choice" })  // move UI immediately after confirm
+  |    - Tool: wait_for_campaign_table_ready({ campaignId })
+  |    - Tool: get_campaign_context({ campaignId, refresh: true })
+  |    - Tool: get_rows_minimal({ tableId: workflowTableId, ... })
+  |    - Watch gate + recommendation after sample
+  |
+  |  Step 4: confirm-lead-list (Confirm Lead List)
+  |    - Tool: update_campaign({ campaignId, currentStep: "confirm-lead-list" })
+  |    - Result: update_campaign returns navigation diagnostics
+  |    - Tool: get_campaign_context({ campaignId, refresh: true }) when needed
+  |    - Watch gate: confirm the list looks right
+  |
+  |  Step 5: filter-choice (Enable Filtering)
+  |    - Tool: update_campaign({ campaignId, currentStep: "filter-choice" })
+  |  Step 6: filter-rules (Rubric Builder)
+  |    - Tool: update_campaign({ campaignId, currentStep: "filter-rules" })
+  |  Step 7: handoff (Terminal)
+  |    - Action: handoff_to_subskill -> /sellable:create-rubric
+```
+
+If you want, we can also add this same map (shorter) to
+`mcp/sellable/skills/create-campaign/README.md` so the structure explains itself.
+
+---
+
+## 9) Are we overengineering this?
+
+Mostly no. The core is still small:
+
+1. `get_campaign_framework`
+2. `update_campaign` (returns `navigation`)
+3. `import_leads`
+4. `confirm_lead_list`
+5. `wait_for_campaign_table_ready`
+6. `get_campaign_context`
+
+`get_campaign_navigation_state` is internal/debug only.