brand_build_journey

Instructions

Implementation Reference

• src/tools/brand-build-journey.ts:313-332 (handler)

  Main handler function that dispatches to handleInterview, handleRecord, or handleView based on the 'mode' parameter.

  async function handler(input: Params) {
    const brandDir = new BrandDir(process.cwd());
  
    if (!(await brandDir.exists())) {
      return buildResponse({
        what_happened: "No .brand/ directory found",
        next_steps: ["Run brand_start first to create a brand system"],
        data: { error: ERROR_CODES.NOT_INITIALIZED },
      });
    }
  
    switch (input.mode) {
      case "interview":
        return handleInterview(brandDir);
      case "record":
        return handleRecord(brandDir, input.answers);
      case "view":
        return handleView(brandDir);
    }
  }

• src/tools/brand-build-journey.ts:9-25 (schema)

  Zod schema for the brand_build_journey tool parameters: mode (enum: interview/record/view) and optional answers (JSON string).

  const paramsShape = {
    mode: z
      .enum(["interview", "record", "view"])
      .default("interview")
      .describe(
        "'interview' presents default journey stages for customization; 'record' writes stages to strategy.yaml; 'view' returns current stages"
      ),
    answers: z
      .string()
      .optional()
      .describe(
        "JSON string with journey stage customizations (for record mode). Array of stage objects, or a single stage object to update."
      ),
  };
  
  const ParamsSchema = z.object(paramsShape);
  type Params = z.infer<typeof ParamsSchema>;

• src/tools/brand-build-journey.ts:334-345 (registration)

  Registration function that calls server.tool() to register the brand_build_journey tool with the McpServer.

  export function register(server: McpServer) {
    server.tool(
      "brand_build_journey",
      "Define buyer journey stages for content strategy — the path from awareness to purchase. Ships with 4 proven defaults (First Touch, Context & Meaning, Validation & Proof, Decision Support) that can be customized per brand. Mode 'interview' presents defaults for review. Mode 'record' writes stages (omit answers to accept defaults). Mode 'view' shows current stages. Part of Session 4 (content strategy). Returns stage definitions with buyer mindset, content goals, and tone shifts.",
      paramsShape,
      async (args) => {
        const parsed = safeParseParams(ParamsSchema, args);
        if (!parsed.success) return parsed.response;
        return handler(parsed.data);
      }
    );
  }

• src/server.ts:84-88 (registration)

  Registration call in server.ts where registerBuildJourney is invoked as part of Session 4 Content Strategy tools.

  // ── Session 4: Content Strategy ──
  registerBuildPersonas(server);
  registerBuildJourney(server);
  registerBuildThemes(server);
  registerBuildMatrix(server);

• src/tools/brand-build-journey.ts:29-85 (helper)

  Provides the 4 default buyer journey stages (First Touch, Context & Meaning, Validation & Proof, Decision Support) used by interview and record modes.

  function getDefaultStages(): JourneyStage[] {
    return [
      {
        id: "first-touch",
        name: "First Touch",
        buyer_mindset: "What is this? Why should I care?",
        content_goal: "Spark interest. Lead with problem recognition.",
        story_types: ["Brand Narrative"],
        narrative_elements: ["Problem", "Hero"],
        claims_policy: {
          preferred_salience: "Lead",
          max_per_piece: 1,
        },
        tone_shift: "More provocative, less consultative",
      },
      {
        id: "context-and-meaning",
        name: "Context & Meaning",
        buyer_mindset: "Do I understand this? Is it for me?",
        content_goal: "Deepen context. Show unique POV.",
        story_types: ["Brand Narrative", "Product/Service Story"],
        narrative_elements: ["Problem", "Guide", "Journey"],
        claims_policy: {
          preferred_salience: ["Lead", "Support"],
          max_per_piece: 3,
        },
        tone_shift: "More educational, framework-oriented",
      },
      {
        id: "validation-and-proof",
        name: "Validation & Proof",
        buyer_mindset: "Is this legit? Do others trust this?",
        content_goal: "Offer credibility. Show outcomes.",
        story_types: ["Customer/Social Proof", "Product/Service Story"],
        narrative_elements: ["Victory", "Proof Point", "Journey"],
        claims_policy: {
          preferred_salience: ["Support", "Lead"],
          max_per_piece: null,
          min_confidence: 0.8,
        },
        tone_shift: "More concrete, metrics-forward",
      },
      {
        id: "decision-support",
        name: "Decision Support",
        buyer_mindset: "Am I ready? What happens next?",
        content_goal: "Remove friction. Provide clarity.",
        story_types: ["Product/Service Story"],
        narrative_elements: ["Guide", "Victory", "Hero"],
        claims_policy: {
          preferred_salience: "Lead",
          max_per_piece: 2,
        },
        tone_shift: "More direct, consultative, action-oriented",
      },
    ];
  }