feat: add goal-brief launch flow with server-owned prompt and goal-authoring tools

AGENTS.md

@@ -21,15 +21,20 @@
 - The build does not clean `dist/`; remove stale output when deleting or renaming source modules before validating package contents.
 - Bundled prompts live in `src/prompts/`; bundled skills live in `skills/`. They sync on every plugin load, preserving user edits and never deleting files. The standalone installer handles conflicts and orphan pruning.
 - Keep the section-summary markers in `src/prompts/agents/auditor-loop-addendum.md` synchronized with the constants in `src/utils/section-summary.ts`.
+- Keep the four required headings in `src/prompts/agents/goal.md` synchronized with `GOAL_BRIEF_REQUIRED_HEADINGS` in `src/utils/goal-brief.ts`.
+- Goal launches from the TUI must set `initialPromptOwner: 'server'` so `attachLoopToSession` builds the prompt from `buildGoalCodingPrompt`. `buildTuiLoopInitialPrompt` is plan-only because it decomposes and sends section 1; it must not be reused for goal loops.
 - `MAX_TOTAL_SECTIONS` in `src/constants/loop.ts` is the single section cap; the decomposer, section bootstrap, plan structure summary, TUI inline plan preview and `plan-adjust` all read it, and the architect system reminder in `src/index.ts` interpolates it. `src/prompts/agents/architect.md` is prose and repeats the number literally — update it when the cap changes.
-- `PLAN_AUTHORING_TOOL_NAMES` in `src/constants/loop.ts` is the single list of plan-authoring tools; the `code`, `auditor`, and `feature-splitter` tool-exclude lists and both permission rulesets derive their deny entries from it.
+- `PLAN_AUTHORING_TOOL_NAMES` in `src/constants/loop.ts` is the single list of plan-authoring tools; the `code`, `auditor`, and `feature-splitter` tool-exclude lists derive their deny entries from it. `GOAL_AUTHORING_TOOL_NAMES` is the single list of goal-authoring tools (`goal-write` only). `SPEC_AUTHORING_TOOL_NAMES` (the plan list plus the goal list) is what `code`, `auditor`, and `feature-splitter` spread into their tool-exclude lists AND what both permission rulesets (`buildLoopPermissionRuleset`, `buildAuditSessionPermissionRuleset`) derive their deny entries from, so `goal-write` is denied in any running or audit session. The `architect` and `architect-auto` agents append `GOAL_AUTHORING_TOOL_NAMES` only (they keep `plan-write`/`plan-edit`). The `goal` agent spreads only `PLAN_AUTHORING_TOOL_NAMES` and is the **only** agent that may call `goal-write`. `assertWritableSession` in `src/tools/session-write-guard.ts` is the single shared guard both `plan-authoring.ts` and `goal-authoring.ts` call to reject writes from an active loop session.
 - `LoopService.resolveActiveLoopForSession` is the only correct "is this session inside a running loop" check. `resolveLoopName` matches terminated loops too, so using it as an activity guard blocks a session forever after its loop ends.
 - `resolveForgeDbPath` in `src/utils/opencode-paths.ts` is the only place `<dataDir>/forge.db` is built; every entry point must route through it so a configured `dataDir` is honoured uniformly.
+- `resolveLoopLaunchPolicy` in `src/utils/loop-helpers.ts` is the single resolution point for the loop launch policy (`loop.enabled` and `loop.defaultMaxIterations`). The `execute-plan`/`execute-goal` handlers in `src/services/execution.ts`, the TUI launch path in `src/utils/tui-client.ts`, the remote launch path in `src/utils/tui-remote-launch.ts`, and the attach hook fallback in `src/hooks/forge-session-attach.ts` all read it. The TUI/remote launch path stamps the resolved `maxIterations` onto the `forgeLoop` envelope (`ForgeLoopExtra.maxIterations`) so the attach hook honours the launcher's promise first and only falls back to the server-side policy when the stamp is absent. Local TUI launches set `awaitAttachAck` so `launchTuiLoop` polls the shared forge database for the running loop row before reporting success; remote launches cannot observe the remote database and remain fire-and-forget. `connectForgeProject` is the only TUI entry point that receives `pluginConfig`/`awaitAttachAck` (population from `src/tui.tsx`).
 
 ## Dashboard and storage gotchas
 
 - The dashboard browser app uses `solid-js/html`, not JSX. Do not use `<${Show}>` or `<${For}>`; use reactive thunks/memos and `.map()`. Every template needs a real root element, reactive regions must be functions such as `${() => ...}`, and the root component returns one wrapper element. `test/dashboard/app-dom.test.ts` enforces these constraints.
 - Storage migrations are registered explicitly, in execution order, in the lowercase `migrations` array in `src/storage/migrations/index.ts`; they are not discovered from filenames. Inline migrations are valid, so not every migration needs a SQL file.
+- `goal_briefs` is the pre-launch authoring store for goal briefs; `loop_large_fields.goal` remains the launched loop's copy. Goal loops still never write `plans` rows (`src/loop/service.ts:183-194`).
+- `fetchStoredSessionLaunchSpec` in `src/utils/tui-loop-store.ts` is the only place the dialog resolves a launchable artifact; it reads both stores (plans and goal briefs) in one DB open and the newest wins with plans breaking ties.
 - `resolveDashboardConfig` in `src/dashboard/config.ts` is the only place the dashboard bind host/port is resolved, and `DEFAULT_DASHBOARD_PORT`/`DEFAULT_DASHBOARD_HOST` are the only copies of the *bind* defaults. The literal `localhost` in `buildDashboardUrls` is deliberately separate: it is the loopback display URL and must not follow the configured bind host. Every launch surface (`scripts/dashboard.ts`, the TUI `forge.dashboard` command) must pass its overrides plus the loaded `PluginConfig` into `startDashboardServer` rather than resolving them itself, and must render `DashboardServerHandle.warnings` so an unusable value is never dropped silently on one surface only. The dashboard has no auth; `DASHBOARD_EXPOSED_WARNING` is the single warning string.
 
 ## Diagnostics

README.md

@@ -104,22 +104,23 @@ Execution flow dialog with mode and model selection:
 ## Features
 
 - **Plans** — architect authors plans directly into SQL storage with `plan-write`/`plan-edit`; marked plans emitted in chat are still auto-captured
-- **Execution** — approved-plan launch paths plus direct `/execute-goal` loops in dedicated worktree sessions; plan loops can also target a configured remote opencode server (see [Configuration](docs/configuration.md#remotes))
+- **Execution** — approved-plan launch paths plus `/goal` brief-backed goal loops in dedicated worktree sessions (launched by the `goal` agent via `execute-goal` or from the Forge execution dialog); plan loops can also target a configured remote opencode server (see [Configuration](docs/configuration.md#remotes))
 - **Loops** — iterative coding/auditing with isolated git worktree and optional Docker sandbox
 - **Review Findings** — persistent, loop-scoped review findings across loop sessions
 - **TUI** — sidebar and execution dialog
 - **Sandbox** — Optional Docker worktree loop isolation with bind-mounted project files
 
 ## Agents
 
-The plugin bundles three user-facing agents plus a hidden `auditor-loop` variant used by loop audit sessions. See [Agents and slash commands](docs/agents-and-commands.md) for the full reference.
+The plugin bundles three user-facing agents plus a hidden `auditor-loop` variant used by loop audit sessions, plus a `goal` agent for authoring goal briefs. See [Agents and slash commands](docs/agents-and-commands.md) for the full reference.
 
 | Agent | Mode | Description |
 |-------|------|-------------|
 | **code** | all | Primary coding agent. |
 | **architect** | primary | Read-only planning agent. Researches the codebase, designs implementation plans, and caches them for user approval before execution. |
 | **auditor** | subagent | Read-only code auditor for convention-aware reviews. Invoked via Task tool to review diffs, commits, branches, or PRs against stored conventions and decisions. |
 | **auditor-loop** | primary, hidden | Internal audit agent used for loop-runner audit sessions. |
+| **goal** | primary | Read-only brief-authoring agent. Reconnoiters the codebase, clarifies scope inline, and writes the session-scoped goal brief with `goal-write` for approval and execution via the Forge execution dialog. |
 
 The auditor agent is a read-only subagent that cannot edit source files or execute plans. It is invoked by other agents via the Task tool to review code changes against stored project conventions and decisions.
 
@@ -135,6 +136,7 @@ See [Tools reference](docs/tools.md) for full arguments, section-scoping behavio
 Forge provides these tool groups:
 
 - **Plan tools** — `plan-write`, `plan-edit`, `plan-read`, `section-read`, `plan-adjust`
+- **Goal brief tools** — `goal-write`, `execute-goal`
 - **Review tools** — `review-write`, `review-read`, `review-delete`
 - **Loop tools** — `execute-plan`, `execute-goal`, `loop-cancel`, `loop-status`
 - **Sandbox shell** — `sh` when a sandbox manager is available
@@ -144,7 +146,7 @@ Loops always run in an isolated git worktree; Docker sandbox is used automatical
 | Tool | Description |
 |------|-------------|
 | `execute-plan` | Execute a plan using an iterative development loop in an isolated git worktree, or `mode: new-session` to launch it in a fresh standalone session. Args: `title` required; `plan`, `loopName`, `mode` optional. |
-| `execute-goal` | Execute a free-text goal in rotating dedicated code and auditor sessions inside an isolated git worktree. Args: `goal` required; `title`, `loopName`, `maxIterations` optional. |
+| `execute-goal` | Launch a goal loop from the goal brief stored for the current session (authored with `goal-write`). Args: `title`, `loopName`, `maxIterations` optional. |
 | `loop-cancel` | Cancel an active loop by worktree name |
 | `loop-status` | List active/recent loops or get detailed status by worktree name, including cumulative token usage when available. Supports `restart=true` to restart any non-completed loop (`running`, `cancelled`, `errored`, `stalled`). Completed loops are history-only and cannot be restarted. |
 
@@ -157,7 +159,7 @@ Loops always run in an isolated git worktree; Docker sandbox is used automatical
 | `/review` | Run a code review on current changes | auditor (subtask) |
 | `/review-plan` | Review a completed implementation against its original plan | auditor (subtask) |
 | `/execute-plan` | Start an iterative development loop in a worktree (or a fresh session with `mode: new-session`) | code |
-| `/execute-goal` | Execute a free-text goal in dedicated worktree sessions until an audit leaves no findings | code |
+| `/goal` | Reconnoiter, author a goal brief (`goal-write`), and launch a goal loop — either directly via `execute-goal` or from the Forge execution dialog | goal |
 | `/loop-status` | Check status of all active loops | code |
 | `/loop-cancel` | Cancel the active loop | code |
 

docs/agents-and-commands.md

@@ -12,6 +12,7 @@ See also: [Tools](tools.md), [Configuration](configuration.md), [Loop System](lo
 | `architect` | `primary` | Read-only planning agent. Authors the stored plan with `plan-write`/`plan-edit` for approval and execution; marked plans in chat are still captured. |
 | `auditor` | `subagent` | Read-only code review agent for convention-aware reviews. |
 | `auditor-loop` | `primary`, hidden | Internal auditor used by loop audit sessions. |
+| `goal` | `primary` | Read-only brief-authoring agent. Reconnoiters the codebase, clarifies scope inline, and writes the session-scoped goal brief with `goal-write` for approval and execution. |
 
 Source: [`src/agents/index.ts`](../src/agents/index.ts), [`src/agents/auditor.ts`](../src/agents/auditor.ts).
 
@@ -29,21 +30,30 @@ Excluded tools:
 - `plan_exit`
 - `plan-write`
 - `plan-edit`
+- `goal-write`
 - `execute-plan`
 - `execute-goal`
 - `loop-cancel`
 - `loop-status`
 
 Source: [`AUDITOR_TOOL_EXCLUDES`](../src/agents/auditor.ts).
 
+## Goal agent restrictions
+
+The `goal` agent is a read-only brief author and launcher. It can reconnoiter with read tools, ask the user clarifying questions, author the session-scoped goal brief with `goal-write`, and launch a goal loop from that brief with `execute-goal`. It cannot edit source files, run plan loops, author plans, or manage other loops.
+
+Excluded tools: every filesystem-mutating tool, every plan/loop/group management tool, and every plan-authoring tool (`plan-write`, `plan-edit`, `plan-adjust`). `execute-plan` is excluded (plan loops are not launched from the goal agent). The `goal` agent is the only agent allowed to call `goal-write`.
+
+Source: [`src/agents/goal.ts`](../src/agents/goal.ts), [`src/constants/loop.ts`](../src/constants/loop.ts).
+
 ## Slash Commands
 
 | Command | Description | Agent | Subtask |
 |---|---|---|---|
 | `/review` | Run a code review. | `auditor` | yes |
 | `/review-plan` | Review a completed implementation against its original plan. | `auditor` | yes |
 | `/execute-plan` | Start an iterative development loop in a worktree (or launch the plan in a fresh standalone session with `mode: new-session`). | `code` | no |
-| `/execute-goal` | Execute a goal in rotating dedicated code and auditor sessions inside an isolated worktree. | `code` | no |
+| `/goal` | Reconnoiter, author a goal brief (`goal-write`), and launch a goal loop — either directly via `execute-goal` or from the Forge execution dialog. | `goal` | no |
 | `/loop-status` | Check status of all active loops. | `code` | no |
 | `/loop-cancel` | Cancel the active loop. | `code` | no |
 

docs/api/README.md

@@ -107,22 +107,23 @@ Execution flow dialog with mode and model selection:
 ## Features
 
 - **Plans** — architect authors plans directly into SQL storage with `plan-write`/`plan-edit`; marked plans emitted in chat are still auto-captured
-- **Execution** — approved-plan launch paths plus direct `/execute-goal` loops in dedicated worktree sessions; plan loops can also target a configured remote opencode server (see [Configuration](_media/configuration.md#remotes))
+- **Execution** — approved-plan launch paths plus `/goal` brief-backed goal loops in dedicated worktree sessions (launched by the `goal` agent via `execute-goal` or from the Forge execution dialog); plan loops can also target a configured remote opencode server (see [Configuration](_media/configuration.md#remotes))
 - **Loops** — iterative coding/auditing with isolated git worktree and optional Docker sandbox
 - **Review Findings** — persistent, loop-scoped review findings across loop sessions
 - **TUI** — sidebar and execution dialog
 - **Sandbox** — Optional Docker worktree loop isolation with bind-mounted project files
 
 ## Agents
 
-The plugin bundles three user-facing agents plus a hidden `auditor-loop` variant used by loop audit sessions. See [Agents and slash commands](_media/agents-and-commands.md) for the full reference.
+The plugin bundles three user-facing agents plus a hidden `auditor-loop` variant used by loop audit sessions, plus a `goal` agent for authoring goal briefs. See [Agents and slash commands](_media/agents-and-commands.md) for the full reference.
 
 | Agent | Mode | Description |
 |-------|------|-------------|
 | **code** | all | Primary coding agent. |
 | **architect** | primary | Read-only planning agent. Researches the codebase, designs implementation plans, and caches them for user approval before execution. |
 | **auditor** | subagent | Read-only code auditor for convention-aware reviews. Invoked via Task tool to review diffs, commits, branches, or PRs against stored conventions and decisions. |
 | **auditor-loop** | primary, hidden | Internal audit agent used for loop-runner audit sessions. |
+| **goal** | primary | Read-only brief-authoring agent. Reconnoiters the codebase, clarifies scope inline, and writes the session-scoped goal brief with `goal-write` for approval and execution via the Forge execution dialog. |
 
 The auditor agent is a read-only subagent that cannot edit source files or execute plans. It is invoked by other agents via the Task tool to review code changes against stored project conventions and decisions.
 
@@ -137,6 +138,7 @@ See [Tools reference](_media/tools.md) for full arguments, section-scoping behav
 Forge provides these tool groups:
 
 - **Plan tools** — `plan-write`, `plan-edit`, `plan-read`, `section-read`, `plan-adjust`
+- **Goal brief tools** — `goal-write`, `execute-goal`
 - **Review tools** — `review-write`, `review-read`, `review-delete`
 - **Loop tools** — `execute-plan`, `execute-goal`, `loop-cancel`, `loop-status`
 - **Sandbox shell** — `sh` when a sandbox manager is available
@@ -146,7 +148,7 @@ Loops always run in an isolated git worktree; Docker sandbox is used automatical
 | Tool | Description |
 |------|-------------|
 | `execute-plan` | Execute a plan using an iterative development loop in an isolated git worktree, or `mode: new-session` to launch it in a fresh standalone session. Args: `title` required; `plan`, `loopName`, `mode` optional. |
-| `execute-goal` | Execute a free-text goal in rotating dedicated code and auditor sessions inside an isolated git worktree. Args: `goal` required; `title`, `loopName`, `maxIterations` optional. |
+| `execute-goal` | Launch a goal loop from the goal brief stored for the current session (authored with `goal-write`). Args: `title`, `loopName`, `maxIterations` optional. |
 | `loop-cancel` | Cancel an active loop by worktree name |
 | `loop-status` | List active/recent loops or get detailed status by worktree name, including cumulative token usage when available. Supports `restart=true` to restart any non-completed loop (`running`, `cancelled`, `errored`, `stalled`). Completed loops are history-only and cannot be restarted. |
 
@@ -159,7 +161,7 @@ Loops always run in an isolated git worktree; Docker sandbox is used automatical
 | `/review` | Run a code review on current changes | auditor (subtask) |
 | `/review-plan` | Review a completed implementation against its original plan | auditor (subtask) |
 | `/execute-plan` | Start an iterative development loop in a worktree (or a fresh session with `mode: new-session`) | code |
-| `/execute-goal` | Execute a free-text goal in dedicated worktree sessions until an audit leaves no findings | code |
+| `/goal` | Reconnoiter, author a goal brief (`goal-write`), and launch a goal loop — either directly via `execute-goal` or from the Forge execution dialog | goal |
 | `/loop-status` | Check status of all active loops | code |
 | `/loop-cancel` | Cancel the active loop | code |