Build a goal-to-plan promplet with runtime lookup.

0. Setup

Work from the repository root. The complete checked-in version lives in promplets/stdlib/definitions/planning/goals.weavemark.md, promplets/catalog/standalone/financial-independence-goal-plan-prompt.weavemark.md, and promplets/catalog/executable/financial-independence-goal-plan.weavemark.md.

cd weavemark
mkdir -p outputs/tutorial-goal

1. Write a semantic macro

A semantic macro is a reusable source-level move. It does not call a tool, fetch data, or ask an LLM at runtime. It expands a compact instruction into structure. Here the macro turns a goal into a planning specification.

@promplet version: 0.7

@module weavemark.std.planning.goals

@define planning_checkpoint
  @param name
    The checkpoint heading.

  @param purpose
    Why this checkpoint exists.

  @param done_when
    Observable completion condition.

  @body
    ### @{name}

    Purpose: @{purpose}

    Done when: @{done_when}

@define goal_plan
  @param goal
    Plain-language user goal.

  @param domain
    Domain where the goal lives.

  @param horizon
    Desired time horizon.

  @param starting_point
    Brief description of the user's current situation.

  @param constraints
    Boundaries, preferences, and things the plan must avoid.

  @param assumption_source
    Public assumptions, runtime lookup result, or user-verified reference material.

  @body
    # Goal-to-plan compiler

    Turn one plain-language goal into a practical plan.

    - Goal: @{goal}
    - Domain: @{domain}
    - Horizon: @{horizon}
    - Starting point: @{starting_point}
    - Constraints: @{constraints}
    - Assumption source: @{assumption_source}

    First state explicit assumptions. If the assumption source is incomplete or
    stale, say what the user must verify before acting.

    @planning_checkpoint name: "Define the finish line" purpose: "Translate the goal into observable success criteria." done_when: "The plan has one measurable target, one date or horizon, and one review trigger."

    @planning_checkpoint name: "Map the current state" purpose: "Separate facts, estimates, unknowns, and constraints before recommending action." done_when: "The plan lists the user's current resources, gaps, and unknowns without pretending missing data is known."

    @planning_checkpoint name: "Build the milestone ladder" purpose: "Turn a distant goal into near, middle, and long-horizon milestones." done_when: "The plan has first-week, first-month, quarterly, and horizon-level milestones."

    @planning_checkpoint name: "Choose the next action set" purpose: "Make the first move concrete enough to do without another planning session." done_when: "The plan names 3-5 first-month actions, their order, and why each comes first."

    @planning_checkpoint name: "Install the review loop" purpose: "Keep the plan alive as conditions change." done_when: "The plan includes a lightweight cadence, metrics to check, and conditions for revising the strategy."

    ## Required output

    @output enforce: strict
      Return exactly these sections:
      1. Goal profile
      2. Assumptions to verify
      3. Milestone ladder
      4. First-month actions
      5. Review cadence
      6. Failure modes and safeguards

    @assert contains: "First-month actions"
    @assert contains: "Assumptions to verify"

Exact source: goals.weavemark.md.

2. Apply the macro to financial independence

Now use the macro as if it were a new WeaveMark directive. The user only supplies a goal, horizon, current starting point, and constraints.

@promplet version: 0.7

@use weavemark.std.planning.goals exposing goal_plan
@refine module:weavemark.domains.finance.finance_safety mingle: true

# Financial Independence Goal-to-Plan Prompt

@goal_plan goal: "@{goal}" domain: "personal finance" horizon: "@{horizon}" starting_point: "@{starting_point}" constraints: "@{constraints}" assumption_source: "@{public_assumptions}"

Apply the resulting plan specifically to financial independence. Treat the
result as planning support, not financial, tax, legal, or investment advice.
Keep the first actions simple enough for someone with no transaction upload,
portfolio upload, or spreadsheet model.

Exact source: financial-independence-goal-plan-prompt.weavemark.md. Save a scratch copy as outputs/tutorial-goal/financial-independence-goal-plan-prompt.weavemark.md before running the next command.

weavemark outputs/tutorial-goal/financial-independence-goal-plan-prompt.weavemark.md \
  --batch-only \
  --var goal="Reach financial independence while keeping work optional" \
  --var horizon="15 years" \
  --var starting_point="I save irregularly and want a monthly reviewable plan" \
  --var constraints="No extreme frugality, no private-data uploads" \
  --var public_assumptions="Use current public sources; verify rates and thresholds before acting." \
  --output outputs/tutorial-goal/compiled-prompt.md

3. Add a semantic function with a real runtime effect

A semantic function is different from the macro. It is not merely a prettier template. It declares a runtime capability: in this example, a read-only public web/reference lookup. The WeaveMark Processor validates the executable graph. With --run, the built-in FunctionalEngine loads the authorized Python @bind, executes each validated node, records evidence, substitutes its result, and renders the final document. Composition alone never runs the companion.

@define lookup_public_goal_assumptions
  @phase execute
  @scope self
  @returns value

  @param goal
    Plain-language user goal.

  @param domain
    Domain where the goal lives.

  @param country
    Country or jurisdiction for public reference lookup.

  @param horizon
    Desired time horizon.

  @effect web_search read

  @body
    Search public reference sources for current, non-private assumptions that
    help plan @{goal} in @{domain} for @{country} over @{horizon}. Return source
    titles, URLs, query terms, assumptions to verify, and caveats. Do not read
    private accounts, transactions, portfolios, or identity data.

@promplet version: 0.7

@use weavemark.std.planning.goals exposing goal_plan lookup_public_goal_assumptions

@include weavemark.domains.finance.finance_safety

@bind web_search language: python from: "./companions/public_finance_reference.py" symbol: lookup_public_goal_assumptions

@execute functional
  scheduler: graph-strict
  allow_effects: [web_search]

# Executable Financial Independence Goal Planner

@lookup_public_goal_assumptions goal: "@{goal}" domain: "personal finance" country: "@{country}" horizon: "@{horizon}" as: public_assumptions

@goal_plan goal: "@{goal}" domain: "personal finance" horizon: "@{horizon}" starting_point: "@{starting_point}" constraints: "@{constraints}" assumption_source: "@{public_assumptions}"

Use the public assumptions only as planning context. Ask the user to verify any
current limits, rates, tax rules, or benefits before acting. Do not request
private account uploads.

Exact sources: goals.weavemark.md and financial-independence-goal-plan.weavemark.md.

4. Run the checked-in example

The repository includes the full version and a small Python runtime integration. It executes the validated functional plan through the public WeaveMark API, which loads the declared companion, passes its result into final synthesis, and records every artifact. By default the companion uses a deterministic public-source pack so the tutorial works offline. Set WEAVEMARK_LIVE_WEB_SEARCH=1 to ask the companion to use the optional live Ellements web-search tools.

python3 examples/python-runtime-integrations/financial-independence-goal-plan/run.py

The runner writes:

• examples/python-runtime-integrations/financial-independence-goal-plan/outputs/compiled-prompt.md - the compiled executable prompt.
• examples/python-runtime-integrations/financial-independence-goal-plan/outputs/compiled-plan.json - WeaveMark's functional plan and bindings.
• examples/python-runtime-integrations/financial-independence-goal-plan/outputs/public-assumptions.json - the runtime lookup result.
• examples/python-runtime-integrations/financial-independence-goal-plan/outputs/execution-output.md - the final synthesized financial-independence plan.
• examples/python-runtime-integrations/financial-independence-goal-plan/outputs/execution-trace.md - the real functional-engine trace, including runtime plan and grounded result.

5. Reuse it for another goal

The reusable component is not the financial-independence prompt. It is the weavemark.std.planning.goals module. For a different goal, keep the macro and change the application spec.

@promplet version: 0.7
@use weavemark.std.planning.goals exposing goal_plan

# Language-learning plan

@goal_plan goal: "Reach conversational Spanish" domain: "learning" horizon: "9 months" starting_point: "I know basic phrases" constraints: "20 minutes per weekday" assumption_source: "No external lookup needed"

Exact source: language-learning-goal-plan.weavemark.md.

Final step: Use the output

This tutorial has both runtime artifacts and a completed financial plan. The example runner executes the public-reference lookup and then asks its configured model to synthesize the final six-section plan.

What you learned

• @define without effects creates reusable semantic macros.
• Macros can call smaller macros, so reusable prompt structure can be factored cleanly.
• @define with @phase, @returns, and @effect creates semantic functions.
• Runtime effects are explicit: this example declares web_search read and binds it to a Python companion.
• The final output is practical: a pastable financial-independence planning prompt built from simple inputs.