---
name: eforge-extend
description: Author eforge TypeScript extensions from a natural-language request using the existing extension tooling and docs/examples
---

# /eforge:extend

Author eforge TypeScript extensions from a natural-language request using the existing extension tooling, docs, and examples. The workflow is conversational: classify the requested behavior, scaffold with `eforge_extension`, edit the returned file with normal file tools, validate, optionally replay-test, reload, and summarize trust/security notes.

## Workflow

### Step 1: Argument intake

- If `$ARGUMENTS` is missing or empty, ask what eforge behavior the user wants to add and stop until they answer.
- Generate a kebab-case extension name from the request.
- Ask for a name only when the generated name is ambiguous or conflicts with an existing extension.

### Step 2: Required context read

Before scaffolding or editing, read these required eforge docs. Prefer the repository-local paths below when they exist; in an installed consumer project where they are not present, use the same documents from https://eforge.build/docs/extensions, https://eforge.build/docs/extensions-api, and https://github.com/eforge-build/eforge/tree/main/examples/extensions.

- `docs/extensions.md`
- `docs/extensions-api.md`
- `examples/extensions/README.md`

Then read relevant examples based on the classified capability:

- `examples/extensions/minimal-event-logger.ts` for event hooks.
- `examples/extensions/slack-webhook-notifier.ts` for webhook/notification hooks.
- `examples/extensions/agent-context.ts` for prompt context.
- `examples/extensions/agent-tools.ts` for custom agent tools.
- `examples/extensions/profile-router.ts` for profile selection.
- `examples/extensions/protected-paths.ts` for runtime-supported plan/final merge policy gates.
- `examples/extensions/issue-tracker.ts` for runtime-supported input source adapters (GitHub, Linear, Jira).
- `examples/extensions/reviewer-perspective.ts` for runtime-supported reviewer perspectives with declarative file-pattern applicability.

### Step 3: Capability classification

Classify the requested behavior before choosing a template or editing code.

Runtime-supported capability families:

- `onEvent` event subscriptions and event replay.
- `onAgentRun` prompt context, per-run tools, and per-run allowed/disallowed tuning.
- `defineExtensionTool` + `registerTool` + returning `tools` from `onAgentRun` for runtime custom tool injection. `registerTool` alone is provenance capture; runtime tool injection requires returning the tool from `onAgentRun`.
- `registerProfileRouter` pre-build profile selection.
- `registerRuntimeChoiceRouter` per-invocation tier-local runtime choice selection after declarative `agents.tiers.<tier>.routing.rules` decline to match.
- `beforeQueueDispatch`, `beforePlanMerge`, and `beforeFinalMerge` blocking policy gates. `require-approval` currently blocks because no approval workflow/UI/state exists, and policy gate contexts are read-only snapshots. These helpers do not sandbox extension code; extensions are trusted unsandboxed code.
- `registerInputSource` input source adapters — supply PRD/build-source artifacts from external systems via `eforge://input/<adapter>/<id>` URIs. Adapter selection is by `name` match. Input-source failures (null return or throw) are fatal to enqueue; design adapters to return instructional content when credentials are absent.
- `registerPrdEnricher` PRD enrichers — mutate or augment PRD content before queue write. Enrichers run in registration order for every preprocessed source; failures are fail-open (`extension:prd-enricher:failed`). Gate behavior inside `enrich` using `ctx.sourceKind`, `ctx.adapterId`, or `ctx.sourcePath`.
- `registerReviewerPerspective` reviewer perspectives — inject custom prompt context into the reviewer agent during parallel review-cycle perspective dispatch (`review.strategy: parallel`, or `auto` once the diff crosses the parallel-review thresholds). Applicability is declared via `appliesTo.fileGlobs`, `paths`, `extensions`, `categories`, or `minChanged*` thresholds; a function-form `appliesTo.fn(changedFiles, changedLines)` escape hatch is also available. Applicability inputs are read-only snapshots; perspectives cannot mutate orchestration state. Failures are fail-open (`extension:reviewer-perspective:skipped` with reason `applicability-error` or `applicability-timeout`). See `examples/extensions/reviewer-perspective.ts` for an accessibility example.
- `registerValidationProvider` validation providers — run during the per-plan `validate` build stage when `validate` is included in the pipeline. Normal structured failures and command-form non-zero exits enter bounded recovery; thrown errors, non-empty string returns, timeouts, and unexpected shapes are hard failures.
- `registerAction`, `registerAgentTask`, `registerConsoleContribution`, `registerConsoleWorkstation`, `registerIntegrationCommand`, and `registerDeepLink` are platform seams for extension-authored actions, prompt-backed task contribution declarations, and host-facing contributions. Actions, integration commands, and action-backed deep links are discoverable, inspectable, and invokable by host integrations through `eforge_extension_contribution`; declarative Console contributions render in the Console System route (`/console/system`). Console workstations render under `/console/workstations` as sandboxed iframes from either inline `srcDoc` or `frameBundle` assets under `workstation-assets/`. `srcDoc` workstations use `window.eforge.invokeAction`; bundle workstation code imports the browser-safe `@eforge-build/extension-sdk/browser` helpers and runs inside the iframe/action bridge boundary, not the parent Console. Contribution registrations may declare dependency/capability `requirements`; manifest entries include `availability`, and unavailable actions are rejected with error code `unavailable`. `registerAgentTask` records trusted prompt sources (`asset` or `export`) and projects only safe metadata; task-start callers reference contributions and do not provide prompt paths, raw prompt text, or resolver functions. Contribution-reference task starts execute for registered planner-compatible task contributions; unsupported or non-compatible starts fail without prompt-path fallback. Action handlers receive immutable `ctx.dependencies`/`ctx.capabilities` availability lookups, daemon-owned `ctx.agentTasks` for supported single-shot read-only planner tasks, `ctx.buildQueue.enqueue` for trusted queue handoffs, including generic `postMerge` command arrays, and `ctx.profiles.list` for read-only shared agent runtime profile listing. Actions that enqueue should declare the `build-queue` side effect. Actions may declare `outputProfile` (`agent-compact`, `agent-paginated`, `markdown`, `ui-rich`, or `debug-rich`); id-shaped broad list/search/board read actions with array-shaped outputs produce warning diagnostics when they lack limit or cursor/page controls, or when array-shaped output schemas omit an explicit profile, but still register. `agent-paginated` actions with limit and cursor/page controls are considered bounded for agent use without separate projection controls. Host tools render compact contribution lists by default with whole-entry returned/total/next-offset continuation metadata, expose focused detail/show modes for schemas and diagnostics, render exact `{ markdown }` outputs as Markdown/plain text, and summarize oversized JSON with warnings, identity fields, counts, omitted counts, and cursor/offset hints; `ui-rich` and `debug-rich` also warn in coding-agent hosts even when they fit. Pi tool text uses a 12,000-character host-output budget, and `eforge_extension` returns compact extension-management projections by default instead of raw discovery objects. MCP/Pi agents should page through `eforge_extension_contribution` list results, then call show for selected contribution details; reserve raw HTTP/CLI `--json` style reads as a fallback for intentional rich/debug inspection when list/show is insufficient. Extension dependency/capability lookup reports availability only and does not invoke other extensions. Extensions do not import provider SDKs or `AgentHarness`, cannot send arbitrary raw prompt templates through task starts, and cannot implement multi-turn chat through that API. Raw extension-owned HTTP routes, parent-Console plugins, direct React loading into the parent Console, private Console imports/CSS/context, extension-owned AI planning/chat APIs outside `ctx.agentTasks`, and arbitrary frontend bundles outside the workstation frame/asset contract remain unsupported.
- First-party workflow extensions and built-in session-planning surfaces remain separate from user-authored native extension registration points.

Runtime-deferred capability families:

- `beforeEnqueue` and `beforeValidation` policy gates.
- Approval workflow/UI/state and `modify` policy decisions.
- User-authored custom workflow extraction, raw extension-owned HTTP routes, parent-Console plugins, direct parent Console React/private import loading, extension-owned AI planning/chat APIs outside `ctx.agentTasks`, caller-supplied arbitrary raw prompt templates, multi-turn chat, and arbitrary frontend plugin bundles outside registered workstation iframes.

If user intent maps to the supported policy-gate, reviewer-perspective, validation-provider, extension-action, or agent-task-contribution declaration subset, explain that the capability executes or projects at runtime as described above, and note the parallel-review condition for reviewer perspectives, validate-stage/recovery behavior for validation providers, daemon invocation boundary for actions, or manifest-only status for task contributions. If user intent maps to deferred APIs, state whether the current SDK provides only a type contract or a captured registration, and that it will not execute at runtime yet. Ask whether to omit that portion or include it as a clearly labeled future-facing registration. Avoid promising that deferred capability families will enqueue, approve, mutate, provide raw HTTP/frontend surfaces, extract workflows, or run unsupported validation phases at runtime.

### Step 4: Scope selection

- Default to `scope: "local"` for experiments and project-local personal behavior; this targets `.eforge/extensions/`.
- Use `scope: "user"` only for explicit cross-project personal extensions.
- Use `scope: "project"` only for explicit team-shared extensions. Project/team extensions (`eforge/extensions/`) are unsandboxed arbitrary code committed to the repository; they require an explicit per-extension local trust record in `.eforge/extension-trust.json` — created by `eforge extension trust <name>` — before loading. Any subsequent code change invalidates the stored hash and blocks the extension until re-trusted. Warn the user of these implications before proceeding.

### Step 4b: Package install workflow (when user requests installing a packaged extension)

If the user asks to install an extension from an npm package, local package directory, or tarball rather than authoring one from scratch, use the following workflow instead of Steps 5-6:

1. Clarify the install source (npm package name, local package directory, or tarball path/URL) and desired scope.
2. Warn the user that installed extensions are unsandboxed arbitrary code and installing from npm, tarballs, or local package directories introduces supply-chain risk.
3. Call `eforge_extension` with `action: "install"`, `source` set to the package name, local package directory, or tarball path/URL, and the selected `scope`. Pass `trust: true`, and optionally `trustedBy`, only when the user explicitly opts in after the warning.
4. On install success, call `eforge_extension` with `action: "list"` and confirm the installed entry appears.
5. **If the entry has `trustState: "untrusted"` or `"changed"` and the returned entry's `scope` is `project-team`:**
   - Read the installed extension files in full.
   - Summarize all side effects (filesystem, network, environment, subprocess). Show the summary.
   - Ask for explicit user confirmation before trusting. Do not proceed if they decline.
   - After confirmation, call `eforge_extension` with `action: "trust"` and the extension `name`.
6. After trust, call validate and then reload (with the same confirmation warnings as Steps 7-9 below).

**Promote and demote:**

If the user asks to promote a project-local extension to project/team scope or demote it back:

1. Call `eforge_extension` with `action: "promote"` or `"demote"` and the extension `name`.
2. After promotion to project-team scope: warn that team members will be required to trust this extension, read the extension files, summarize side effects, and ask for explicit confirmation before trusting. Call `action: "trust"` after confirmation.
3. After demotion to project-local scope: no trust step is required.

**Update and remove:**

For updating or removing an installed extension, call `eforge_extension` with `action: "update"` or `action: "remove"` and the extension `name`. After update, verify trust state (a changed source file invalidates the stored hash) and re-trust if needed. Pass `force: true` only when the user explicitly requests forced removal.

### Step 5: Scaffold

- Optionally call `eforge_extension` with `action: "list"` first to inspect existing extensions and shadowing.
- Call `eforge_extension` with `action: "new"`, the generated `name`, selected `scope`, and selected `template`:
  - `event-logger` for event-driven requests.
  - `blank` for non-event or complex mixed requests.
- Use the returned `path` for file reads and edits; do not hard-code scope paths when the tool returns a path.

### Step 6: Edit

- Read the scaffolded file at the returned `path`.
- Apply TypeScript edits using the required docs and examples as the source of truth.
- Use environment variables for secrets, tokens, webhook URLs, and other credentials; do not commit secrets into source.
- Preserve deferred-runtime caveats in code comments when including future-facing registrations.
- For policy gates, prefer `beforeQueueDispatch`, `beforePlanMerge`, and `beforeFinalMerge`; document that `require-approval` blocks in the current MVP and that extensions remain unsandboxed trusted code.

### Step 7: Validate

**Project/team scope: inspect and trust first.** If the extension is in project/team scope (`eforge/extensions/`):

- Read the extension file(s) in full before trust, validate, test, or reload.
- Summarize all side effects (filesystem, network, environment, subprocess). Show the summary and ask for explicit user confirmation before proceeding. Do not proceed if they decline.
- After confirmation, record the current content hash by calling `eforge_extension` with `action: "trust"` and the extension `name` or `path`. This writes a trust record to `.eforge/extension-trust.json`. If the code changed since the last trust, the extension is blocked (status `changed`) until re-trusted — confirm with the user before overwriting an existing trust record.
- The hash covers the entrypoint for file-layout extensions and, for directory-layout extensions, `package.json` plus `.ts`, `.mts`, `.js`, and `.mjs` files under the extension directory. Files imported from outside the extension directory and non-source/data files inside it are not hashed; keep implementation code inside the extension directory and in hashed source files to ensure relevant code changes are captured.
- Proceed to validate only after trust succeeds and the user has confirmed.

- Before validation, warn that extension loading is unsandboxed in the daemon process; review the code first and do not validate code with unexpected top-level filesystem, network, or environment side effects.
- Show the user a brief side-effect review and ask for explicit confirmation before calling validate; do not proceed if they decline.
- After editing and confirmation, call `eforge_extension` with `action: "validate"` by `name` or returned `path`.
- If validation returns `valid: false`, summarize diagnostics, fix the file, and validate again.
- Do not call `reload` after failed validation.

### Step 8: Optional test

- Offer event replay testing after validation.
- Use `eforge_extension` with `action: "test"` by `name` or `path`, plus `fixture`, `run`, or `event` when the user supplies an event source.
- Warn that replay executes matching `onEvent` handlers in the daemon process and can trigger filesystem, network, or environment side effects.
- Ask for explicit confirmation before running the replay test, even after validation succeeds.
- If no safe event source exists, the user declines confirmation, or the extension has side effects, skip testing and record the reason in the final summary.

### Step 9: Reload

- Before reload, warn that reload activates unsandboxed extension code in the daemon process.
- Ask for explicit confirmation before reload.
- Call `eforge_extension` with `action: "reload"` only after validation succeeds and after the user confirms that warning.
- Summarize watcher fields from the response when present: `wasRunning`, `restarted`, `running`, and `message`.

### Step 10: Final summary

Report:

- Extension name, scope, returned path, selected template, and capability families used.
- Validation result, optional test result or skipped-test reason, and reload result.
- Any deferred-runtime caveats that apply to the generated extension.
- Security/trust notes: extensions are unsandboxed code execution, project/team scope requires explicit trust, and secrets belong in environment variables rather than committed source.
- Follow-up commands: validate, test with fixture/run, reload, and where to edit the file.