GoalBuddy

Live Updates

The server automatically pushes fresh payloads to the browser over /events when any of the following files change:

• docs/goals/<slug>/state.yaml
• docs/goals/<slug>/notes/
• Linked sub-goal state: docs/goals/<slug>/subgoals/**/state.yaml
• Linked sub-goal notes: docs/goals/<slug>/subgoals/**/notes/

Board Mapping

Tasks are categorized into columns based on their status:

• Todo: queued tasks
• In Progress: active tasks
• Blocked: blocked tasks
• Completed: done tasks (right-most column)

Card Details

Clicking a card opens a modal containing:

• Task objective, status, assignee, inputs, constraints, expected output, verify commands, allowed files, stop conditions, and receipt details.
• Sub-goals: If the task links a sub-goal, a read-only child board is displayed.
• Notes: If a receipt points to a note, the content is rendered as plain text.

When you provide vague, strategic, or improvement-oriented input, $goal-prep triggers a diagnostic intake instead of immediately creating a board. This process asks questions one at a time to resolve ambiguity.

The Diagnostic Ladder:

1. Goal surface: Decides whether to use a local GoalBuddy board.
2. Intent target: Identifies the primary improvement or outcome.
3. Success proof: Determines what evidence proves the goal was met.
4. Scope and non-goals: Defines what is explicitly out of scope.
5. Goal handling: Decides whether to reuse, create, or inspect an existing goal.

Interaction Pattern: The skill will present a single interpreted outcome, a potential blind spot, and one material question. It will then offer recommended directions. It stops after each question and will not create files or run /goal until the intake is complete.

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].

Agent roles (Scout, Judge, Worker) can suggest new sub-goals by including a proposed_subgoals list within a task's receipt.

Important: Proposals are advisory only. They do not automatically create a subgoal block in the parent task or change the execution state. The Project Manager (PM) must manually review the proposal and decide whether to:

1. Reject it.
2. Convert it into normal parent tasks.
3. Promote it by creating the child state.yaml file and adding the subgoal block to the parent task.

receipt:
  result: done
  summary: "The implementation split exposes a separate board-rendering loop."
  proposed_subgoals:
    - title: "Build sub-goal board rendering"
      reason: "Parser, modal rendering, and tests form a bounded loop."
      suggested_owner: Worker
      suggested_path: subgoals/T004-board-view/state.yaml
      scope:
        allowed_files:
          - extend/local-goal-board/scripts/lib/goal-board.mjs
          - extend/local-goal-board/test/local-goal-board.test.mjs
        verify:
          - node --test extend/local-goal-board/test/*.test.mjs
        stop_if:
          - "Need broader state-schema changes."

When a goal is vague, strategic, or improvement-oriented, $goal-prep uses a Diagnostic Intake to prevent creating poorly defined boards. The tool follows a 'minimum diagnostic ladder' to gather material answers:

1. Goal surface: Determining if a local GoalBuddy board should be used.
2. Intent target: Identifying the specific type of improvement or outcome desired.
3. Success proof: Defining what evidence would convince the user the goal was met.
4. Scope and non-goals: Defining what should remain untouched or be explicitly out of scope.
5. Goal handling: Deciding whether to reuse, create, or inspect an existing goal.

Interaction Pattern: The tool asks these questions one at a time. It will not create files, repair boards, or print the /goal command until the intake is complete. It presents a structured response for each turn:

I read this as: [one-sentence interpreted outcome].

One possible blind spot: [a risk, unstated choice, or success dimension].

[One material question?]

1. [Recommended direction] (Recommended) - [when it wins]
2. [Second direction] - [when it wins]
3. [Third direction] - [when it wins]

My default would be [option] because [short reason].

To maintain momentum, follow these rules for task completion and activation:

1. Immediate Transition: After a task completes, write its receipt and immediately select the next active task unless a final audit proves the original outcome is complete.
2. Avoid Premature Stopping: Do not stop at "ready for implementation" if a safe Worker task exists. Do not stop after one verified package if broader follow-up work is available.
3. Judge Task Usage: Do not create a Judge task after every Worker by default. Use Judge only for phase boundaries, high-risk changes, unclear scope, rejected verification, or final completion.
4. Handling Blockers: If a slice needs user input or credentials, mark it blocked, spawn the smallest safe local task that can proceed, and continue.
5. Completion Integrity: Do not mark a goal or tranche done while queued or active Worker tasks are still required for the user's outcome. Never end a session with an active task marked done.