eforge-build/eforge/eforge-profile-new

Note: In Pi, the native /eforge:profile:new command provides a richer interactive experience with a guided TUI wizard and panel previews. This skill serves as a fallback for non-interactive contexts and as model-readable documentation.

/eforge:profile-new

Interactively create a new named agent runtime profile (e.g. pi-anthropic, pi-openrouter, local-qwen, mixed). The profile can live at project scope (eforge/profiles/<name>.yaml) or user scope (~/.config/eforge/profiles/<name>.yaml). It configures a harness, model, and effort level per build tier (planning → implementation → review → evaluation), then optionally activates itself.

Pi is the recommended eforge execution harness for new profiles because it is provider-flexible. Claude Code or Pi can still be the host surface; the active profile chooses the execution harness. The claude-sdk harness remains supported as an optional Anthropic-specific path. Starting June 15, 2026, Anthropic says Claude Agent SDK and claude -p usage no longer count toward Claude plan limits; eligible plans may receive a separate monthly Agent SDK credit, usage beyond that credit is billed at standard API rates when extra usage is enabled, otherwise requests stop, and API-key users remain pay-as-you-go.

Workflow

Step 0: Ask scope

Ask: "Where should this profile live? Project-local scope (.eforge/profiles/), project scope (eforge/profiles/), or user scope (~/.config/eforge/profiles/)?"

• Project-local scope - profile lives in .eforge/profiles/, gitignored and dev-personal. Takes highest precedence but is never committed.
• Project scope (default) - profile is committed with the project, shared with the team.
• User scope - profile lives in ~/.config/eforge/profiles/, reusable across all projects on this machine.

If the user does not specify, default to project scope. Remember the chosen scope for Step 4 (pass it as scope to the create action) and Step 5 (pass it to use if activating).

Step 1: Determine the profile name

• If $ARGUMENTS is non-empty, treat the first token as the profile name.
• Otherwise ask the user: "What should this profile be called? (e.g. pi-anthropic, pi-openrouter, local-qwen, mixed)"

The name will be used as the filename (local: .eforge/profiles/<name>.yaml, project: eforge/profiles/<name>.yaml, user: ~/.config/eforge/profiles/<name>.yaml).

Step 2: Configure each tier

Walk the four built-in tiers in fixed order: planning → implementation → review → evaluation.

For each tier, present the following options:

Copy from a previously configured tier (available from implementation onward): From the second tier onward, present one Copy from <tierName> (<modelId>) entry per tier already configured in this session (e.g. on review: Copy from planning and Copy from implementation, in TIER_ORDER order). The default selection is copy-from-immediately-previous when the user just presses enter.

Custom: walk the sub-flow:

1. Harness: ask pi (recommended/provider-flexible) or claude-sdk (optional Anthropic-specific Agent SDK with credit/API-priced usage).
2. Provider (pi only): call eforge_models with { action: "providers", harness: "pi" }, show the list, confirm.
3. Model: call eforge_models with { action: "list", harness: "<harness>", provider: "<provider>" } (omit provider for claude-sdk). Show top 10 (id + releasedAt when available); add a "see all" affordance if the list is longer. Default to the newest model. Confirm.
4. Effort: ask from low | medium | high | xhigh | max. Default: high for planning/review/evaluation, medium for implementation.

For the planning tier present only Custom, since no prior tier exists yet. Start that first custom tier with pi selected first unless the user explicitly asks for claude-sdk.

Record each tier's harness, optional pi.provider, model, and effort.

Step 2b: Configure project MCP toolbelts (optional)

After tier configuration, ask: "Would you like to configure project MCP toolbelts for this profile?"

Present three options:

• Skip / default — leave toolbelt fields omitted; all project MCP servers from .mcp.json pass through to each tier.
• No project MCP access — set all four tiers to toolbelt: none; no project MCP servers reach agents in any tier.
• Choose a preset — configure a named toolbelt bundle with least-privilege tier assignments.

If skipped: Leave all tier toolbelt fields omitted. Proceed to Step 3.

If no project MCP access: Add toolbelt: none to all four tiers. Proceed to Step 3.

If a preset is selected: Present the preset gallery:

For each required MCP server in the chosen preset:

1. Check whether the server name is present in .mcp.json under mcpServers.
2. Check whether tools.toolbelts.<preset> is declared in eforge/config.yaml.

Before assigning tier fields, ensure both checks pass. If the required server names are present but tools.toolbelts.<preset> is missing, add the tools.toolbelts.<preset> entry with the preset description and mcpServers list before assigning any tier toolbelt fields.

For `browser-ui` with missing Playwright: Show the following snippet and ask before adding:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    }
  }
}

If the user confirms, add the entry to .mcp.json (merge if the file exists) and declare the toolbelt in eforge/config.yaml:

tools:
  toolbelts:
    browser-ui:
      description: Browser automation for UI implementation and review.
      mcpServers:
        - playwright

Then assign toolbelt: browser-ui to implementation and review, and toolbelt: none to planning and evaluation.

For other presets with missing servers: Show the preset's setup hint and do not create tier toolbelt references. Ask the user to add the required MCP server to .mcp.json first, then re-run /eforge:profile-new.

When toolbelt fields are set, include them in agents.tiers in the Step 3 preview and in the Step 4 create payload.

Step 2c: Configure implementation runtime choices (optional)

Ask: "Would you like this profile to add per-invocation runtime choices for implementation work?"

• Skip / default — every implementation invocation uses the implementation tier default.
• Add UI/backend choices — create implementation.ui and implementation.backend choices with ordered declarative routing rules.

Use runtime choices when the same built-in tier needs tier-local overlays. The four built-in tiers remain the role-routing axis; choices are selected only after a role resolves to its tier. The existing tier recipe is the implicit default choice (implementation.default), and named choices inherit from that tier default.

For the UI/backend preset, first ensure browser-ui is a declared project toolbelt using the same checks from Step 2b (required MCP server present or auto-added, then tools.toolbelts.browser-ui written to config). If it cannot be declared, omit toolbelt: browser-ui from the ui choice or reuse an already-declared implementation toolbelt instead of creating an invalid reference.

Then add:

agents:
  tiers:
    implementation:
      harness: pi
      model: anthropic/claude-sonnet-4-6
      effort: medium
      pi:
        provider: openrouter
      choices:
        backend:
          model: qwen3-coder
          pi:
            provider: local
          toolbelt: none
        ui:
          effort: high
          toolbelt: browser-ui
      routing:
        rules:
          - name: ui-paths
            choice: ui
            when:
              pathGlobs: ["packages/console-ui/**", "web/**", "**/*.{tsx,jsx,css}"]
              keywords: ["ui", "frontend", "browser", "component"]
          - name: backend-paths
            choice: backend
            when:
              pathGlobs: ["packages/engine/**", "packages/client/**", "packages/monitor/**"]

Declarative rules run before extension runtime-choice routers. Extension router failures fall back to default and do not fail the build. registerProfileRouter still selects the active profile before build dispatch; it is separate from per-invocation runtime-choice routing. onAgentRun can observe selected choice metadata, but cannot change the selected harness, model, provider, effort, or toolbelt. Events expose non-secret runtime-choice metadata.

Step 3: Preview the profile

Show the user a rendered preview of the YAML that will land in the chosen scope directory. Example Pi-first profile:

agents:
  tiers:
    planning:
      harness: pi
      model: anthropic/claude-opus-4-6
      effort: high
      pi:
        provider: openrouter
    implementation:
      harness: pi
      model: anthropic/claude-sonnet-4-6
      effort: medium
      pi:
        provider: openrouter
    review:
      harness: pi
      model: anthropic/claude-opus-4-6
      effort: high
      pi:
        provider: openrouter
    evaluation:
      harness: pi
      model: anthropic/claude-opus-4-6
      effort: high
      pi:
        provider: openrouter

Example with mixed Pi providers:

agents:
  tiers:
    planning:
      harness: pi
      model: anthropic/claude-opus-4-6
      effort: high
      pi:
        provider: openrouter
    implementation:
      harness: pi
      model: qwen3-coder
      effort: medium
      pi:
        provider: local
    review:
      harness: pi
      model: anthropic/claude-opus-4-6
      effort: high
      pi:
        provider: openrouter
    evaluation:
      harness: pi
      model: gemini-flash
      effort: high
      pi:
        provider: google

Optional claude-sdk tiers omit the pi block and use Anthropic model IDs:

agents:
  tiers:
    review:
      harness: claude-sdk
      model: claude-opus-4-7
      effort: high

Ask for confirmation or corrections before writing.

Step 4: Create the profile

Call eforge_profile with:

{
  action: "create",
  name: "<name>",
  scope: "<local|project|user>",
  agents: {
    tiers: {
      planning:       { harness, model, effort, pi?: { provider }, toolbelt?: "none" | "<preset>" },
      implementation: {
        harness, model, effort, pi?: { provider }, toolbelt?: "none" | "<preset>",
        choices?: {
          backend?: { harness?, model?, effort?, pi?: { provider }, toolbelt?: "none" | "<preset>" },
          ui?: { harness?, model?, effort?, pi?: { provider }, toolbelt?: "none" | "<preset>" },
        },
        routing?: { rules: [{ name, choice, when: { pathGlobs?, keywords?, roles?, phase?, stage?, shardIds?, shardRoots? } }] },
      },
      review:         { harness, model, effort, pi?: { provider }, toolbelt?: "none" | "<preset>" },
      evaluation:     { harness, model, effort, pi?: { provider }, toolbelt?: "none" | "<preset>" },
    }
  },
  metadata: {          // optional — descriptive only, does not affect runtime behavior
    description: "<human-readable description of what this profile is for>",
    whenToUse: ["<scenario 1>", "<scenario 2>"],
    tags: ["<tag1>", "<tag2>"],
  },
  overwrite: false,
}

Omit pi for the claude-sdk harness. Include pi: { provider: "..." } for the pi harness.