goalbuddy 0.2.10

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "goalbuddy",
+  "version": "0.2.10",
+  "description": "Turn open-ended Codex goals into a GoalBuddy Scout/Judge/Worker board with receipts, verification, and optional extensions.",
+  "type": "module",
+  "bin": {
+    "goalbuddy": "internal/cli/goal-maker.mjs",
+    "goal-maker": "internal/cli/goal-maker.mjs"
+  },
+  "files": [
+    "README.md",
+    "CONTRIBUTING.md",
+    "examples",
+    "plugins/goalbuddy",
+    "internal/assets",
+    "internal/cli",
+    "goalbuddy/SKILL.md",
+    "goalbuddy/agents",
+    "goalbuddy/scripts",
+    "goalbuddy/templates",
+    "goal-maker/SKILL.md",
+    "goal-maker/agents",
+    "goal-maker/scripts",
+    "goal-maker/templates"
+  ],
+  "scripts": {
+    "check": "node --check internal/cli/goal-maker.mjs goal-maker/scripts/*.mjs goalbuddy/scripts/*.mjs && node --test internal/test/*.test.mjs",
+    "test": "node --test internal/test/*.test.mjs",
+    "pack:dry-run": "npm pack --dry-run",
+    "publish:check": "node internal/cli/check-publish-version.mjs && npm run pack:dry-run",
+    "prepublishOnly": "node internal/cli/check-publish-version.mjs"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tolibear/goalbuddy.git"
+  },
+  "keywords": [
+    "codex",
+    "codex-skill",
+    "openai-codex",
+    "goalbuddy",
+    "goal",
+    "task-board",
+    "receipts",
+    "project-management",
+    "automation",
+    "cli",
+    "workflow",
+    "agent",
+    "extensions",
+    "verification"
+  ],
+  "author": "tolibear",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/tolibear/goalbuddy/issues"
+  },
+  "homepage": "https://github.com/tolibear/goalbuddy#readme",
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/plugins/goalbuddy/.codex-plugin/plugin.json

@@ -0,0 +1,48 @@
+{
+  "name": "goalbuddy",
+  "version": "0.2.10",
+  "description": "Turn broad Codex work into verified GoalBuddy boards with Scout, Judge, Worker, receipts, and optional extensions.",
+  "author": {
+    "name": "tolibear",
+    "email": "support@tolibear.com",
+    "url": "https://github.com/tolibear"
+  },
+  "homepage": "https://github.com/tolibear/goalbuddy#readme",
+  "repository": "https://github.com/tolibear/goalbuddy",
+  "license": "MIT",
+  "keywords": [
+    "goalbuddy",
+    "codex",
+    "skills",
+    "goal",
+    "task-board",
+    "receipts",
+    "workflow",
+    "extensions"
+  ],
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "GoalBuddy",
+    "shortDescription": "Turn broad Codex work into verified Scout/Judge/Worker boards",
+    "longDescription": "GoalBuddy packages a structured Codex goal workflow for broad, long-running, or ambiguous engineering work. It creates durable goal charters, task boards, receipts, verification gates, extension handoffs, and compatibility guidance for teams moving from goal-maker.",
+    "developerName": "tolibear",
+    "category": "Coding",
+    "capabilities": [
+      "Interactive",
+      "Read",
+      "Write"
+    ],
+    "websiteURL": "https://github.com/tolibear/goalbuddy",
+    "privacyPolicyURL": "https://github.com/tolibear/goalbuddy#privacy",
+    "termsOfServiceURL": "https://github.com/tolibear/goalbuddy#license",
+    "defaultPrompt": [
+      "Prepare a GoalBuddy board for this goal",
+      "Audit this GoalBuddy board and continue safely",
+      "Install GoalBuddy extensions and verify setup"
+    ],
+    "brandColor": "#2563EB",
+    "composerIcon": "./assets/goalbuddy-icon.svg",
+    "logo": "./assets/goalbuddy-icon.svg",
+    "screenshots": []
+  }
+}

package/plugins/goalbuddy/README.md

@@ -0,0 +1,29 @@
+# GoalBuddy Codex Plugin
+
+GoalBuddy packages the canonical `$goalbuddy` skill as a Codex plugin so teams can install the reusable workflow as a plugin while keeping the npm CLI for local setup, doctor checks, and extension management.
+
+## What It Contains
+
+- `.codex-plugin/plugin.json`: plugin metadata and Codex UI copy.
+- `skills/goalbuddy/`: the installable GoalBuddy skill payload.
+- `assets/goalbuddy-icon.svg`: lightweight plugin icon.
+
+## Local Testing
+
+From the repo root:
+
+```bash
+npm run check
+npx goalbuddy doctor
+```
+
+For local CLI testing before npm publish:
+
+```bash
+node internal/cli/goal-maker.mjs install --catalog-url extend/catalog.json
+node internal/cli/goal-maker.mjs doctor
+```
+
+## Release Notes
+
+The plugin is prepared for the `tolibear/goalbuddy` repo and `goalbuddy` npm package. Do not publish this plugin until the owner completes the GitHub and npm handoff steps in `docs/goals/goalbuddy-rebrand-plugin/state.yaml`.

package/plugins/goalbuddy/assets/goalbuddy-icon.svg

@@ -0,0 +1,8 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" role="img" aria-labelledby="title desc">
+  <title id="title">GoalBuddy icon</title>
+  <desc id="desc">A blue rounded square with a white checkmark and board columns.</desc>
+  <rect width="64" height="64" rx="14" fill="#2563EB"/>
+  <path d="M18 18h28a4 4 0 0 1 4 4v20a4 4 0 0 1-4 4H18a4 4 0 0 1-4-4V22a4 4 0 0 1 4-4Z" fill="#FFFFFF" opacity=".16"/>
+  <path d="M24 24v16M34 24v16M44 24v16" stroke="#FFFFFF" stroke-width="3" stroke-linecap="round" opacity=".65"/>
+  <path d="m22 35 7 7 14-18" fill="none" stroke="#FFFFFF" stroke-width="5" stroke-linecap="round" stroke-linejoin="round"/>
+</svg>

package/plugins/goalbuddy/skills/goalbuddy/SKILL.md

@@ -0,0 +1,484 @@
+---
+name: goalbuddy
+description: Use for broad, long-running, stalled, vague, detailed, planned, or unhealthy Codex work that needs a structured /goal intake, autonomous task discovery, role-tagged Scout/Judge/Worker delegation, one active task, durable receipts, and a PM-owned rolling board that maximizes the chance of a successful goal run.
+---
+
+# GoalBuddy
+
+`$goalbuddy` prepares a GoalBuddy board. It does not start `/goal` automatically, but the board and starter `/goal` command must be shaped so the next run continues into safe execution by default.
+
+GoalBuddy is for autonomous, long-running Codex work where the PM thread may need to discover the work, define tasks, sequence them, delegate them, execute them, verify them, and keep going without the human decomposing every step.
+
+The loop is:
+
+```text
+raw user intent -> intake compiler -> discovery/plan validation/execution board -> one active task -> receipt -> board update -> repeat
+```
+
+## Intake Compiler
+
+Before creating, repairing, or running a board, privately translate the user's input into a Goal Intake. The input may be vague, specific, or detailed with an existing plan. Do not dump the intake to the user unless they ask for it.
+
+Extract:
+
+- original request: the shortest faithful user wording;
+- interpreted outcome: what must become true;
+- input shape: `vague | specific | existing_plan | recovery | audit`;
+- audience or beneficiary;
+- non-goals and hard constraints;
+- authority: `requested | approved | inferred | needs_approval | blocked`;
+- proof type: `test | demo | artifact | metric | review | source_backed_answer | decision`;
+- completion proof: the observable signal for full outcome completion;
+- likely misfire: how `/goal` could succeed at the wrong thing;
+- blind spots: important risks, choices, or success dimensions the user may not have named yet;
+- existing plan facts: user-provided steps, files, constraints, or sequencing that must be preserved but still validated.
+
+Ask before board creation when the request is vague, strategic, improvement-oriented, or open-ended and the user has not explicitly said to use defaults. Ask one guided question at a time with 2-3 options and a recommended default, then wait. Continue the diagnostic intake until the user's answers are sufficient to choose the board shape. Do not create or repair `docs/goals/<slug>/` until the diagnostic intake is complete or the user explicitly accepts defaults.
+
+For vague or strategic goals, one answer is rarely enough. After each answer, reflect what it implies, name one likely blind spot, and ask the next material question. The goal is to help the user discover what they mean, not merely collect a form value.
+
+Proceed with labeled assumptions and seed a safe board only when at least one is true:
+
+- the user provides a specific outcome and enough completion proof to choose the first phase;
+- the user provides an existing plan or concrete artifact to validate;
+- the request is clearly recovery or audit with a target path, error, failing command, or stale board;
+- the user says to proceed, use defaults, or prepare the board now.
+
+If a missing answer materially changes outcome, authority, scope, risk, owner, completion proof, or board-handling choice, ask even if the user provided details.
+
+Examples:
+
+- Vague input: start with Scout, then Judge, bounded Worker, final audit.
+- Specific input with incomplete evidence: start with Scout or Judge before Worker.
+- Existing plan: preserve the plan as facts, start with PM or Judge plan validation, then queue bounded Worker slices from the validated plan.
+- Recovery: start with Scout evidence mapping or Judge triage before writes.
+- Audit: keep the board read-only unless the user approves follow-up execution.
+
+The intake compiler is an internal strut for `/goal`: it exists to make the first board correct, not to create process theater.
+
+## Guided Intake Surface
+
+For interactive vague or improvement-oriented input, run a diagnostic intake. Show only the current turn of the diagnostic, not the private intake:
+
+```markdown
+I read this as: [one-sentence interpreted outcome].
+
+One possible blind spot: [a risk, unstated choice, or success dimension the user may not have named].
+
+[One material question?]
+
+1. [Recommended direction] (Recommended) - [when it wins]
+2. [Second direction] - [when it wins]
+3. [Third direction, only if genuinely useful] - [when it wins]
+
+My default would be [option] because [short reason].
+```
+
+Stop after each question. Do not create files, repair an existing board, run checks, or print `/goal` until the diagnostic intake is complete. Do not dump the private intake.
+
+Minimum diagnostic ladder for vague, strategic, or improvement-oriented goals:
+
+1. Intent target: what kind of improvement or outcome matters most?
+2. Success proof: what evidence would convince the user this worked?
+3. Scope and non-goals: what should remain untouched or explicitly out of scope?
+4. Board handling: reuse an existing board, create a fresh board, or inspect first?
+
+Ask these one at a time. Skip a step only when the user's words already answer it clearly. After the user answers one step, do not assume the remaining steps; ask the next unresolved material question.
+
+For "make GoalBuddy better", a good first question is which improvement target matters most: intake clarity, board/execution reliability, completion proof/eval coverage, or user experience during long-running goals. A good second question asks what proof would convince the user it improved. A good third question asks whether to reuse an existing board, create a fresh board, or inspect first.
+
+## Direct `/goal` Entry
+
+When `/goal` is invoked with raw user intent instead of an existing `docs/goals/<slug>/goal.md` path, run the Intake Compiler before doing implementation work. The PM should not treat raw `/goal` text as an execution plan until it has:
+
+- classified the input shape;
+- preserved any existing plan facts;
+- identified the likely misfire and at least one blind spot;
+- recorded authority and proof;
+- answered or explicitly defaulted the diagnostic ladder for vague/strategic input;
+- selected the safest first active task;
+- either asked the required guided intake question or written `goal.md` and `state.yaml` from a sufficiently clear intake.
+
+If the raw input is detailed and already contains a plan, the first board task should validate and operationalize that plan rather than rediscovering from scratch. If the raw input is vague, run the diagnostic intake before creating the board unless the user explicitly says to use defaults. If the raw input is blocked by authority, policy, destructive action, credentials, or ambiguous completion proof, ask one guided question with options or create the smallest safe read-only task only after the user chooses to proceed.
+
+The target is not literal certainty. It is the highest practical likelihood of a successful goal run: preserve the user's intent, avoid the likely misfire, pick the earliest responsible phase, require proof, and keep advancing safe work until a final audit proves the full outcome.
+
+## What `$goalbuddy` Does
+
+When invoked directly, run intake first. For vague, strategic, improvement-oriented, or open-ended input, run the diagnostic intake and stop before creating or repairing the board until enough material answers are known. For sufficiently clear, planned, recovery, audit, or explicitly-defaulted input, prepare or repair the board and stop for user choice.
+
+Do:
+
+- clarify or infer the goal title and slug;
+- run the Intake Compiler;
+- ask diagnostic intake questions when clarity would materially improve the board;
+- classify the goal as `specific`, `open_ended`, `existing_plan`, `recovery`, or `audit`;
+- create or repair `docs/goals/<slug>/`;
+- create `goal.md`, `state.yaml`, and `notes/`;
+- seed a role-tagged task board that matches the input shape;
+- make the first active task safe;
+- verify Scout, Worker, and Judge agents are installed or explain what is missing;
+- print the exact command `/goal Follow docs/goals/<slug>/goal.md.`;
+- ask whether to start now, refine `goal.md`, or stop.
+
+Do not:
+
+- start `/goal` automatically;
+- create or repair a board from vague/open-ended input before diagnostic intake is complete;
+- create `evidence.jsonl`, `units/`, or `artifacts/` for new v2 goals;
+- edit implementation files before the board exists;
+- invent implementation tasks from vibes when the intake requires Scout, Judge, or plan validation first;
+- discard a user-provided plan; preserve it as facts and validate it before execution;
+- treat `goal.md` as board truth when it conflicts with `state.yaml`.
+
+## Default Bias: Users Want Work Done
+
+Unless the user explicitly asks for planning only, treat a GoalBuddy request as a request for work to happen.
+
+Planning, Scout findings, Judge decisions, and a queued Worker task are not terminal outcomes when the user's original ask is for a working capability, automation, fix, cleanup, or backend/frontend behavior. They are setup for execution.
+
+For execution goals, the default run is continuous:
+
+```text
+Discover enough evidence, choose a safe implementation slice, implement it, verify it, audit it, then immediately choose and execute the next safe slice until the full original outcome is complete.
+```
+
+If the first `/goal` run reaches a Judge decision that names a safe Worker task with `allowed_files`, `verify`, and `stop_if`, the PM should activate that Worker and continue in the same run unless a stop condition applies.
+
+After a verified Worker slice and audit, do not mark the thread goal complete merely because that slice passed. A slice audit is a checkpoint. For broad automation or product goals, continue by reopening or advancing the board to the next safe Worker task until the full owner outcome is complete.
+
+Missing owner input, credentials, production access, destructive-operation permission, or policy decisions are blockers for specific tasks, not stopping conditions for the whole goal. When a slice hits one of those blockers, mark that exact task blocked with a receipt, create a safe follow-up or workaround task, and keep doing local, non-destructive work that advances the full outcome.
+
+## When To Use
+
+Use this skill for goals that are broad, multi-hour, ambiguous, high-risk, already planned, already stale, already red, or likely to need Scout/Judge/Worker delegation.
+
+For a one-change task, do not create a GoalBuddy board.
+
+Scout and Judge tasks may identify optional extension, plugin, publishing, reporting, or channel opportunities as improvement candidates. Treat those as normal board tasks. Extensions are supporting surfaces; `state.yaml` remains board truth.
+
+## The Four Primitives
+
+1. **Charter**: `goal.md` says what the current tranche is trying to accomplish and what constraints matter.
+2. **Board**: `state.yaml` is the rolling task list and machine truth.
+3. **Task**: exactly one active task may be worked at a time.
+4. **Receipt**: every completed, blocked, or escalated task leaves a compact durable result on the task card.
+
+Agents are not a separate primitive. They are the assignee type on a task.
+
+## Control Files
+
+For a v2 goal, create only:
+
+```text
+docs/goals/<slug>/
+  goal.md
+  state.yaml
+  notes/
+```
+
+The goal root may contain only `goal.md`, `state.yaml`, and `notes/`.
+
+Most results live inline as task receipts in `state.yaml`. Only create `notes/<task-id>-<slug>.md` when Scout, Judge, or PM output is too large to fit on the task card.
+
+Use:
+
+- `templates/goal.md`
+- `templates/state.yaml`
+- `templates/note.md`
+
+## Charter
+
+The charter answers:
+
+```text
+What did the user originally ask for?
+What are we trying to improve?
+What input shape did the intake identify?
+What constraints are non-negotiable?
+Is this goal specific, open-ended, existing-plan, recovery, or audit?
+What likely misfire must the PM avoid?
+What counts as enough for the current tranche?
+```
+
+Avoid forever goals. A broad goal should define an execution tranche, for example:
+
+```text
+Discover the highest-leverage local improvements, complete successive safe verified implementation slices, audit each slice against the original user outcome, and keep advancing until the full outcome is complete.
+```
+
+## Board
+
+`state.yaml` is the board and machine truth. A task card has:
+
+```yaml
+id: T001
+type: scout | judge | worker | pm
+assignee: Scout | Judge | Worker | PM
+status: queued | active | blocked | done
+objective: "<one sentence>"
+inputs: []
+constraints: []
+expected_output: []
+receipt: null
+```
+
+Worker tasks additionally require:
+
+```yaml
+allowed_files: []
+verify: []
+stop_if: []
+```
+
+The PM owns the board. Scout, Judge, and Worker return receipts; they do not select the next active task or mark the goal complete.
+
+## Seed Boards
+
+If the goal is vague, the first active task is Scout, but the seeded board should still lead toward execution. Queue Judge selection, a bounded Worker slot, and a final audit.
+
+If the user provides an existing plan, do not ignore it and do not execute it blindly. Preserve the plan in `goal.intake.existing_plan_facts`, make the first active task PM or Judge validation, and queue Worker slices only after the plan is checked for evidence, risk, allowed files, verification, and stop conditions.
+
+Example open-ended seed:
+
+```yaml
+tasks:
+  - id: T001
+    type: scout
+    assignee: Scout
+    status: active
+    objective: "Map repo health and identify improvement candidates."
+    receipt: null
+  - id: T002
+    type: scout
+    assignee: Scout
+    status: queued
+    objective: "Find verification commands, flaky tests, stale docs, dependency risks, and easy safety wins."
+    receipt: null
+  - id: T003
+    type: judge
+    assignee: Judge
+    status: queued
+    objective: "Choose the first safe implementation task by impact, confidence, reversibility, and verification strength."
+    expected_output:
+      - "Decision"
+      - "Exact Worker objective"
+      - "allowed_files"
+      - "verify"
+      - "stop_if"
+    receipt: null
+  - id: T004
+    type: worker
+    assignee: Worker
+    status: queued
+    objective: "Execute the first safe implementation task selected by Judge."
+    allowed_files: []
+    verify: []
+    stop_if:
+      - "Need files outside allowed_files."
+      - "Behavior is ambiguous."
+      - "Verification fails twice."
+    receipt: null
+  - id: T999
+    type: judge
+    assignee: Judge
+    status: queued
+    objective: "Audit whether the implemented slice satisfies the original user outcome for this tranche."
+    receipt: null
+```
+
+If the goal is specific but evidence is incomplete, start with Scout. If risk or priority is unclear, queue Judge before Worker. If evidence is adequate and implementation is bounded, the first active task may be Worker.
+
+If the goal is audit, keep the active task read-only. Queue execution only if the user asks for fixes or approves follow-up implementation.
+
+## Task Rules
+
+A task is the only work that may happen.
+
+- Scout tasks are read-only and produce findings.
+- Judge tasks are read-only and produce decisions or constraints.
+- Worker tasks may write only inside `allowed_files`.
+- PM tasks may update control files and board state.
+
+No implementation without an active Worker or PM task that explicitly allows it.
+
+At most one write-capable Worker may be active. Do not run parallel Workers unless `state.yaml` proves disjoint write scopes and the user explicitly asked for parallel agent work.
+
+## Receipts
+
+A receipt is compact proof that the task happened and what it changed, learned, decided, blocked, or spawned.
+
+Scout receipt:
+
+```yaml
+receipt:
+  result: done
+  summary: "Found three high-leverage candidates: flaky auth tests, missing router coverage, stale build docs."
+  evidence:
+    - test/auth/session.test.ts
+    - src/router/index.ts
+    - README.md
+  spawned_tasks:
+    - T004
+```
+
+Judge receipt:
+
+```yaml
+receipt:
+  result: done
+  decision: "Do router coverage first; defer auth flake because it is not reproducible locally."
+  next_allowed_task: T004
+  blocked_tasks:
+    - T005
+```
+
+Worker receipt:
+
+```yaml
+receipt:
+  result: done
+  changed_files:
+    - src/billing/router.ts
+    - test/billing/router.test.ts
+  commands:
+    - cmd: git diff --check
+      status: pass
+    - cmd: npm test -- test/billing/router.test.ts
+      status: pass
+  summary: "invoice.paid now routes through eventRouter.dispatch; regression test added."
+```
+
+For long findings or decisions, write `notes/<task-id>-<slug>.md` and point to it:
+
+```yaml
+receipt:
+  result: done
+  note: notes/T001-repo-map.md
+  summary: "Repo map completed; three candidate tranches found."
+```
+
+## Computed Gate
+
+Do not store manual gate booleans.
+
+The gate is computed from the active task:
+
+- active Scout: edits are not allowed; receipt must include findings or a note.
+- active Judge: edits are not allowed; receipt must include a decision.
+- active Worker: edits are allowed only inside `allowed_files`; receipt must include changed files and commands.
+- active PM: edits are limited to control files unless the task explicitly allows otherwise.
+
+If verification is red, stale, blocked, or unknown, choose recovery, Scout, Judge, or PM board work before feature work.
+
+## Blocked Does Not Mean Stop
+
+Blocked tasks do not necessarily block the goal. The PM should keep doing safe local board work when possible:
+
+- create a Scout task to improve evidence;
+- create a Judge task to resolve ambiguity;
+- create a Worker task for a smaller safe slice;
+- write or update a note for handoff;
+- update receipts and verification freshness.
+
+Avoid setting `goal.status: blocked` for missing input, credentials, production access, destructive-operation permission, or policy decisions. Block the specific task instead, record the missing requirement, and continue with every safe local workaround or adjacent slice.
+
+## Continuation Rule
+
+After a task completes, immediately write its receipt and select the next active task unless:
+
+- a final audit proves the full original owner outcome is complete.
+
+Do not stop at "ready for implementation" when a safe Worker task exists. Activate the Worker, execute it, verify it, and then run the audit task.
+
+Do not stop after one verified implementation slice when the broader owner outcome still has safe local follow-up slices. Treat a slice audit as permission to advance the board, not as permission to finish, unless the audit explicitly proves the full original outcome is complete.
+
+Do not stop because the current slice needs owner input, credentials, production access, destructive operations, or policy decisions. Mark that slice blocked, spawn or activate the smallest safe local task that can proceed around the blocker, and continue.
+
+Do not mark a goal or tranche done while any queued or active Worker task is still required for the user's original outcome. Complete it, block it with a receipt, or replace it with a smaller safe Worker task.
+
+Do not end with an active task marked done.
+
+Run the checker when available:
+
+```bash
+node <skill-path>/scripts/check-goal-state.mjs docs/goals/<slug>/state.yaml
+```
+
+If the checker and your judgment disagree, choose the more conservative state.
+
+## Agents
+
+Scout, Worker, and Judge are default-installed roles.
+
+| Agent | Thinking level | Write access | Use for |
+|---|---:|---:|---|
+| Scout | medium | no | source/spec/repo evidence mapping |
+| Worker | low | yes, bounded | one exact implementation or recovery task |
+| Judge | high | no | strategic review, ambiguity, scope, completion skepticism |
+
+A task's `assignee` determines the agent. The task card is the order. The receipt is the return format.
+
+Only the main `/goal` PM may choose the active task, update the board, mark tasks done, or mark the goal complete.
+
+## PM Thinking Policy
+
+The main `/goal` thread is the PM. It owns board truth, chooses active tasks, decides when Scout/Judge/Worker receipts are sufficient, and records completion.
+
+Recommended PM thinking:
+
+| Goal mode | PM thinking |
+|---|---:|
+| specific, bounded | medium |
+| open-ended | high |
+| recovery | high |
+| audit | high |
+| high-risk or multi-day final audit | xhigh optional |
+
+Do not use `xhigh` by default. Use it only when a wrong board, scope, or completion decision would be materially more expensive than latency and cost.
+
+Tasks may include an optional `reasoning_hint` field:
+
+```yaml
+reasoning_hint: default # default | low | medium | high | xhigh
+```
+
+Treat `reasoning_hint` as PM guidance. It does not override task scope, write permissions, stop conditions, or the one-active-task rule.
+
+## Completion
+
+Never complete because work looks substantial.
+
+Completion is a Judge or PM audit task. The goal is done only when a final done Judge or PM receipt says the full original outcome is complete and maps completion to current receipts, verification, and the user's original outcome.
+
+For execution goals, completion also requires implementation evidence. A final audit cannot call the goal done if the only completed work is planning, discovery, or task selection.
+
+For continuous execution goals, the final audit receipt must include `full_outcome_complete: true`. If the receipt only proves that the current slice or tranche is complete, keep the goal active and queue or activate the next safe Worker/Judge/PM task.
+
+Queued or active Worker tasks block `goal.status: done`. If a Worker is no longer required, mark it blocked with a receipt explaining why, remove it during PM board maintenance, or replace it with the actual required Worker task before completion.
+
+Default final task:
+
+```yaml
+- id: T999
+  type: judge
+  assignee: Judge
+  status: queued
+  objective: "Audit whether the current tranche is complete."
+  inputs:
+    - "All done task receipts"
+    - "Last verification"
+    - "Current dirty diff"
+  expected_output:
+    - "complete | not_complete"
+    - "full_outcome_complete: true | false"
+    - "missing evidence"
+    - "next task if not complete"
+  receipt: null
+```
+
+## Default `/goal` Shape
+
+```text
+/goal Follow docs/goals/<slug>/goal.md.
+```

package/plugins/goalbuddy/skills/goalbuddy/agents/README.md

@@ -0,0 +1,23 @@
+# GoalBuddy Agents
+
+This directory contains both skill metadata and bundled agent definitions.
+
+- `openai.yaml` stays with the skill as metadata.
+- `goal_*.toml` files can be copied into `.codex/agents/` for project-scoped agents or `~/.codex/agents/` for personal agents.
+
+| Agent | File | Reasoning effort | Sandbox |
+|---|---|---:|---|
+| Scout | `goal_scout.toml` | medium | read-only |
+| Worker | `goal_worker.toml` | low | workspace-write |
+| Judge | `goal_judge.toml` | high | read-only |
+
+Recommended config:
+
+```toml
+[agents]
+max_threads = 4
+max_depth = 1
+job_max_runtime_seconds = 1800
+```
+
+Only the main `/goal` PM loop may select the active task, mark tasks done, update board truth, or mark the goal complete.

package/plugins/goalbuddy/skills/goalbuddy/agents/config-snippet.toml

@@ -0,0 +1,5 @@
+# Optional Codex config snippet for GoalBuddy subagent runs.
+[agents]
+max_threads = 4
+max_depth = 1
+job_max_runtime_seconds = 1800