savepoint 1.0.2 → 1.0.3

package/agent-skills/savepoint-audit/SKILL.md

@@ -1,35 +1,87 @@
-# Savepoint Skill: Audit (`audit`)
-
-## Objective
-At the end of an epic, review the implemented code against the Epic objectives and Task Acceptance Criteria, and reconcile any documentation "Drift".
-
-## Context
-The Audit Gate is Savepoint's wedge. It prevents projects from degrading into chaos. The `audit` agent acts as the Quality Assurance and Documentation Lead. It reviews the work of the `build-task` agent with "fresh eyes," ensuring that the `Design.md` and the `AGENTS.md` Codebase Map reflect the actual reality of the codebase before the next Epic begins.
-
-## Trigger
-This skill is activated when the `.savepoint/router.md` state is `audit-pending`.
-
-## Input
-- `.savepoint/audit/{release}/{E##-slug}/snapshot.md` (what changed).
+---
+name: savepoint-audit
+description: Performs Savepoint audit-pending work for a completed epic, reviewing implementation against task acceptance criteria and writing the required E##-Audit.md handoff file.
+---
+
+# Savepoint Skill: Audit (`audit`)
+
+## Objective
+At the end of an epic, review the implemented code against the Epic objectives and Task Acceptance Criteria, and reconcile any documentation "Drift".
+
+## Context
+The Audit Gate is Savepoint's wedge. It prevents projects from degrading into chaos. The `audit` agent acts as the Quality Assurance and Documentation Lead. It reviews the work of the `build-task` agent with "fresh eyes," ensuring that the `Design.md` and the `AGENTS.md` Codebase Map reflect the actual reality of the codebase before the next Epic begins.
+
+## Trigger
+This skill is activated when the `.savepoint/router.md` state is `audit-pending`.
+
+## Input
 - `.savepoint/releases/{release}/epics/{E##-slug}/E##-Detail.md` (the epic design).
-- `.savepoint/Design.md` (project architecture).
-- `AGENTS.md` (agent guide and codebase map).
-- The source and test files modified during the Epic.
-
-## Workflow
-
-1.  **Fresh Eyes Check:** If you are the exact same agent session that just built the `build-task` code for this Epic, you MUST STOP. Tell the user: "Epic complete. Start a new agent session for the audit."
-2.  **Verify ACs:** Review the completed tasks for the Epic. Ensure the Acceptance Criteria were actually met by the committed code.
-3.  **Process Drift Notes (Reconciliation):** Read every task file in the Epic and look for `## Drift Notes`.
-4.  **Draft Proposals:** Based on the code changes and the Drift Notes, write exactly ONE file: `.savepoint/audit/{release}/{E##-slug}/proposals.md`. It must contain:
-    *   **Design.md section:** Propose updates to merge the epic's architectural changes into the project-level `Design.md`.
-    *   **AGENTS.md section:** Propose updates to refresh the Codebase Map table with new or changed modules.
-    *   **Epic-E##-Detail.md section:** Add "Implemented as:" notes showing where reality deviated from the original plan.
-    *   **Quality Review section:** List any minor code-style infractions that must be fixed before the next Epic.
-5.  **Review Format:** Use `## Target File`, `## Replace`, and `## With` formatting in the proposals document so it is easy for a human (or an agent) to apply later.
-6.  **Handoff:** Do not apply the proposals yourself. Do not mark the epic audited. Stop and prompt the user to review `.savepoint/audit/{release}/{E##-slug}/proposals.md` (often via the TUI). Once the user approves, the proposals are applied, and the router moves to the next Epic.
-
-## Constraints
-- **Do not write product code.** You are an auditor.
-- **Do not apply the changes immediately.** Write the proposals document first.
-- **One proposals file.** Do not create multiple proposal files.
+- `.savepoint/Design.md` (project architecture).
+- `AGENTS.md` (agent guide and codebase map).
+- The source and test files modified during the Epic.
+
+## Workflow
+
+1.  **Fresh Eyes Check:** If you are the exact same agent session that just built the `build-task` code for this Epic, you MUST STOP. Tell the user: "Epic complete. Start a new agent session for the audit."
+2.  **Verify ACs:** Review the completed tasks for the Epic. Ensure the Acceptance Criteria were actually met by the committed code. Also confirm each task file has a `## Context Files` section — flag any missing ones under `## Main Findings` as a process gap.
+3.  **Process Drift Notes (Reconciliation):** Read every task file in the Epic and look for `## Drift Notes`.
+4.  **Draft Audit File:** Based on the code changes and the Drift Notes, write exactly ONE file: `.savepoint/releases/{release}/epics/{E##-slug}/E##-Audit.md`. It must use this format:
+    ````md
+    ---
+    type: audit-findings
+    audited: YYYY-MM-DD
+    ---
+    # Audit Findings: E## {Epic Name}
+
+    ## Main Findings
+    [human-readable audit summary only: AC verification, important drift, and notable risks. Do not include per-file replacement blocks here.]
+
+    ## Code Style Review
+    - [ ] One job per file
+    - [ ] One-sentence functions
+    - [ ] Test branches
+    - [ ] Types are documentation
+    - [ ] Build, don't speculate
+    - [ ] Errors at boundaries
+    - [ ] One source of truth
+    - [ ] Comments explain WHY
+    - [ ] Content in data files
+    - [ ] Small diffs
+
+    ## Proposed Changes
+    ### Target File
+    path/to/file.md
+
+    ### Replace
+    ```
+    exact old text
+    ```
+
+    ### With
+    ```
+    replacement text
+    ```
+    ````
+    The TUI Audit tab renders only `## Main Findings` and `## Code Style Review`. Keep `## Proposed Changes` as admin/apply metadata so the Epic Detail panel does not show stale file-change blocks.
+5.  **Review Format:** Use `### Target File`, `### Replace`, and `### With` formatting only inside `## Proposed Changes`. Include proposals for:
+    *   **Design.md:** Merge the epic's architectural changes into the project-level `Design.md`.
+    *   **AGENTS.md:** Refresh the Codebase Map table with new or changed modules.
+    *   **Epic E##-Detail.md:** Add "Implemented as:" notes showing where reality deviated from the original plan.
+    *   **Implementation fixes:** Include any must-fix code or test changes found during audit.
+6.  **Handoff:** Do not apply the proposals yourself. Do not mark the epic audited. Stop and prompt the user to review `.savepoint/releases/{release}/epics/{E##-slug}/E##-Audit.md` (via the TUI Audit tab). Tell them: "Review the audit tab. When ready, say 'apply audit' to apply proposals and close the epic."
+7.  **Apply + Close** (only when the user approves by saying "apply audit" or equivalent):
+    1.  Read `E##-Audit.md` — extract every `### Target File` / `### Replace` / `### With` block from `## Proposed Changes`.
+    2.  For each pair, apply the replacement to the target file named in the preceding `### Target File` line.
+    3.  Update `E##-Audit.md` visible sections: rewrite `## Main Findings` and `## Code Style Review` so the TUI Audit tab reflects the applied outcome, resolved findings, remaining risks if any, and final code-style status. Keep `## Proposed Changes` intact as admin/apply trace unless the user asks to remove it.
+    4.  Update `E##-Detail.md` frontmatter: set `status: audited`.
+    5.  Update `.savepoint/Design.md` frontmatter: set `last_audited: {release}/{E##-slug}`.
+    6.  Read `.savepoint/router.md` current state. Advance:
+        - If more epics remain in the release: set `state: epic-design`, `epic: {next-epic-slug}`, `task: ""`, `next_action: "Draft epic design"`.
+        - If no more epics: set `state: epic-design`, `epic: ""`, `next_action: "Plan next epic"`.
+    7.  Print apply summary: "Applied X proposals. Updated audit findings. Epic {E##} closed as audited. Router → {new state}."
+
+## Constraints
+- **Do not write product code.** You are an auditor.
+- **Do not apply the changes immediately.** Write the proposals document first.
+- **One proposals file.** Do not create multiple proposal files.
+- **No CLI audit pipeline.** Savepoint audit is agent-led and skill-driven; do not invoke or design around a `savepoint audit` command.

package/agent-skills/savepoint-build-task/SKILL.md

@@ -1,4 +1,9 @@
-# Savepoint Skill: Build Task (`build-task`)
+---
+name: savepoint-build-task
+description: Executes Savepoint task-building work when .savepoint/router.md state is task-building, including implementing one active task, checking acceptance criteria, running quality gates, and stopping for user review.
+---
+
+# Savepoint Skill: Build Task (`build-task`)
 
 ## Objective
 Act as a disciplined coding agent that strictly follows Savepoint's implementation loop.
@@ -36,4 +41,4 @@ This skill is activated when the `.savepoint/router.md` state is `task-building`
 
 ## Constraints
 - **Stay in scope:** Do not touch files outside of what is required for the Acceptance Criteria.
-- **Do not edit architecture documents.** If you must deviate from the plan, write the code and log a "Drift Note" in the task file.
+- **Do not edit architecture documents.** If you must deviate from the plan, write the code and log a "Drift Note" in the task file.

package/agent-skills/savepoint-create-plan/SKILL.md

@@ -1,4 +1,9 @@
-# Savepoint Skill: Create Plan (`create-plan`)
+---
+name: savepoint-create-plan
+description: Creates Savepoint release epics from the PRD and Design documents when the router is in pre-implementation planning.
+---
+
+# Savepoint Skill: Create Plan (`create-plan`)
 
 ## Objective
 Turn the Product Requirements Document (PRD) and the architectural `Design.md` into Epics (logical slices of work) and high-level tasks that can be implemented independently.
@@ -25,4 +30,4 @@ This skill is activated when the `.savepoint/router.md` state is `pre-implementa
 
 ## Constraints
 - **Do not write code.**
-- **Do not write detailed implementation steps.** That is the job of the `create-task` skill. Keep the task outlines high-level at this stage.
+- **Do not write detailed implementation steps.** That is the job of the `create-task` skill. Keep the task outlines high-level at this stage.

package/agent-skills/savepoint-create-task/SKILL.md

@@ -1,31 +1,44 @@
-# Savepoint Skill: Create Task (`create-task`)
-
-## Objective
-Take high-level tasks identified during the planning phase and build detailed, actionable task plans with strict Acceptance Criteria.
-
-## Context
-A task plan is a contract between the planner and the builder. If the task plan is vague, the resulting code will be buggy. The `create-task` skill acts as a Senior Engineer writing tickets for a Junior Developer (the `build-task` agent). It must define exactly *what* constitutes success and *how* to achieve it, without actually writing the code.
-
-## Trigger
-This skill is activated when the `.savepoint/router.md` state is `epic-task-breakdown` and the router points to a specific epic.
-
-## Input
-- `.savepoint/releases/v1/epics/{E##-epic}/E##-Detail.md` (The active Epic's design).
-- The high-level task markdown file (e.g., `.savepoint/releases/v1/epics/{E##-epic}/tasks/T001-slug.md`).
-
-## Workflow
-
-1.  **Read Context:** Understand the goal of the specific task within the context of its parent Epic.
-2.  **Define Acceptance Criteria (ACs):** This is the most critical step. Write explicit, observable outcomes. (e.g., "Running `npm test` passes 5 tests for the auth module" or "The `/login` route returns a 200 OK with a valid JWT"). Do not use subjective language like "looks good."
-3.  **Draft Implementation Plan:** Create a step-by-step checklist for the `build-task` agent to follow.
-    *   List which files need to be created or modified.
-    *   Specify which functions or components need to be written.
-    *   Include instructions to write tests *first* if applicable.
-4.  **Add Context Log Shell:** Ensure the bottom of the task file includes a `## Context Log` section with placeholders for `Files read:`, `Estimated input tokens:`, and `Notes:`.
-5.  **Define Dependencies:** If this task relies on another task being completed first, explicitly declare it in the YAML frontmatter (e.g., `depends_on: [T001-setup]`).
-6.  **Status Update:** Change the task frontmatter to `status: planned`.
-7.  **Handoff:** Update `.savepoint/router.md` to `state: in-progress` and ensure it points to the newly planned task. Prompt the user to approve the task plan before building begins.
-
-## Constraints
-- **Do not write code.** Your job is to plan the work, not execute it.
-- **Keep it isolated:** The task plan should touch as few files as possible. If a task plan requires modifying 15 files, it is too large and should be broken down further.
+---
+name: savepoint-create-task
+description: Plans Savepoint task files during epic-task-breakdown by writing acceptance criteria, implementation checklists, dependencies, and context-log shells.
+---
+
+# Savepoint Skill: Create Task (`create-task`)
+
+## Objective
+Take high-level tasks identified during the planning phase and build detailed, actionable task plans with strict Acceptance Criteria.
+
+## Context
+A task plan is a contract between the planner and the builder. If the task plan is vague, the resulting code will be buggy. The `create-task` skill acts as a Senior Engineer writing tickets for a Junior Developer (the `build-task` agent). It must define exactly *what* constitutes success and *how* to achieve it, without actually writing the code.
+
+## Trigger
+This skill is activated when the `.savepoint/router.md` state is `epic-task-breakdown` and the router points to a specific epic.
+
+## Input
+- `.savepoint/releases/v1/epics/{E##-epic}/E##-Detail.md` (The active Epic's design).
+- The high-level task markdown file (e.g., `.savepoint/releases/v1/epics/{E##-epic}/tasks/T001-slug.md`).
+
+## Workflow
+
+1.  **Read Context:** Understand the goal of the specific task within the context of its parent Epic.
+2.  **Define Acceptance Criteria (ACs):** This is the most critical step. Write explicit, observable outcomes. (e.g., "Running `npm test` passes 5 tests for the auth module" or "The `/login` route returns a 200 OK with a valid JWT"). Do not use subjective language like "looks good."
+3.  **Draft Implementation Plan:** Create a step-by-step checklist for the `build-task` agent to follow.
+    *   List which files need to be created or modified.
+    *   Specify which functions or components need to be written.
+    *   Include instructions to write tests *first* if applicable.
+4.  **Populate Context Files:** Add a `## Context Files` section listing the exact file paths the build agent must read before coding. Pull these from the epic's Components table — only the files this task actually touches or depends on. Example:
+    ```markdown
+    ## Context Files
+    - `internal/board/board.go`
+    - `internal/board/model.go`
+    - `internal/data/config.go`
+    ```
+    No globs. No directories. Exact paths only.
+5.  **Add Context Log Shell:** Ensure the bottom of the task file includes a `## Context Log` section with placeholders for `Files read:`, `Estimated input tokens:`, and `Notes:`.
+5.  **Define Dependencies:** If this task relies on another task being completed first, explicitly declare it in the YAML frontmatter (e.g., `depends_on: [T001-setup]`).
+6.  **Status Update:** Change the task frontmatter to `status: planned`.
+7.  **Handoff:** Update `.savepoint/router.md` to `state: in-progress` and ensure it points to the newly planned task. Prompt the user to approve the task plan before building begins.
+
+## Constraints
+- **Do not write code.** Your job is to plan the work, not execute it.
+- **Keep it isolated:** The task plan should touch as few files as possible. If a task plan requires modifying 15 files, it is too large and should be broken down further.

package/agent-skills/savepoint-draft-prd/SKILL.md

@@ -1,4 +1,9 @@
-# Savepoint Skill: Draft PRD (`draft-prd`)
+---
+name: savepoint-draft-prd
+description: Guides Savepoint PRD drafting and refinement before implementation, interviewing the user until the product scope is clear enough for design.
+---
+
+# Savepoint Skill: Draft PRD (`draft-prd`)
 
 ## Objective
 Help the user write a structured, sufficiently detailed Product Requirements Document (PRD) before any design or planning occurs.
@@ -29,4 +34,4 @@ This skill is activated when the `.savepoint/router.md` state is `pre-implementa
 ## Constraints
 - **Do not write code.**
 - **Do not plan Epics.** That is the job of the `create-plan` skill.
-- **Do not make technical architectural decisions.** That is the job of the `system-design` skill. Your focus is strictly on *what* and *why*, not *how*.
+- **Do not make technical architectural decisions.** That is the job of the `system-design` skill. Your focus is strictly on *what* and *why*, not *how*.

package/agent-skills/savepoint-system-design/SKILL.md

@@ -1,4 +1,9 @@
-# Savepoint Skill: System Design (`system-design`)
+---
+name: savepoint-system-design
+description: Produces Savepoint system or epic design documents from the PRD when the router is in epic-design or the user asks for architectural design.
+---
+
+# Savepoint Skill: System Design (`system-design`)
 
 ## Objective
 Translate the Product Requirements Document (PRD) into the initial architectural blueprint (`Design.md`) before the planning phase breaks the work down into Epics.
@@ -30,4 +35,4 @@ This skill is activated when the `.savepoint/router.md` state is `epic-design` o
 ## Constraints
 - **Do not write code.**
 - **Do not break down tasks.** That is the job of the `create-plan` skill.
-- **Maintain Token Discipline:** Keep the `Design.md` concise. It is meant to be read by AI agents on every turn. Rambling design docs destroy context windows.
+- **Maintain Token Discipline:** Keep the `Design.md` concise. It is meant to be read by AI agents on every turn. Rambling design docs destroy context windows.

package/agent_skills_test.go

@@ -0,0 +1,91 @@
+package main
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestBundledSavepointSkillsHaveDiscoveryFrontmatter(t *testing.T) {
+	assertSavepointSkillsHaveFrontmatter(t, filepath.Join("agent-skills"))
+	assertSavepointSkillsHaveFrontmatter(t, filepath.Join("templates", "project", "agent-skills"))
+}
+
+func TestProjectAgentGuideIncludesLocalSkillFallback(t *testing.T) {
+	path := filepath.Join("templates", "project", "AGENTS.md")
+	content, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatalf("ReadFile(%q) error = %v", path, err)
+	}
+
+	want := "If the agent says the skill is not found, read `agent-skills/{skill}/SKILL.md` directly"
+	if !strings.Contains(string(content), want) {
+		t.Fatalf("%s missing local skill fallback instruction", path)
+	}
+}
+
+func TestScaffoldedSavepointSkillsMatchBundledSkills(t *testing.T) {
+	root := filepath.Join("agent-skills")
+	entries, err := os.ReadDir(root)
+	if err != nil {
+		t.Fatalf("ReadDir(%q) error = %v", root, err)
+	}
+
+	for _, entry := range entries {
+		if !entry.IsDir() || !strings.HasPrefix(entry.Name(), "savepoint-") {
+			continue
+		}
+
+		sourcePath := filepath.Join(root, entry.Name(), "SKILL.md")
+		scaffoldPath := filepath.Join("templates", "project", "agent-skills", entry.Name(), "SKILL.md")
+		source, err := os.ReadFile(sourcePath)
+		if err != nil {
+			t.Fatalf("ReadFile(%q) error = %v", sourcePath, err)
+		}
+		scaffold, err := os.ReadFile(scaffoldPath)
+		if err != nil {
+			t.Fatalf("ReadFile(%q) error = %v", scaffoldPath, err)
+		}
+		if string(scaffold) != string(source) {
+			t.Fatalf("%s does not match %s", scaffoldPath, sourcePath)
+		}
+	}
+}
+
+func assertSavepointSkillsHaveFrontmatter(t *testing.T, root string) {
+	t.Helper()
+
+	entries, err := os.ReadDir(root)
+	if err != nil {
+		t.Fatalf("ReadDir(%q) error = %v", root, err)
+	}
+
+	var found int
+	for _, entry := range entries {
+		if !entry.IsDir() || !strings.HasPrefix(entry.Name(), "savepoint-") {
+			continue
+		}
+		found++
+		path := filepath.Join(root, entry.Name(), "SKILL.md")
+		content, err := os.ReadFile(path)
+		if err != nil {
+			t.Fatalf("ReadFile(%q) error = %v", path, err)
+		}
+
+		text := string(content)
+		if !strings.HasPrefix(text, "---\n") {
+			t.Fatalf("%s missing YAML frontmatter", path)
+		}
+		if !strings.Contains(text, "name: "+entry.Name()) {
+			t.Fatalf("%s frontmatter name does not match directory", path)
+		}
+		if !strings.Contains(text, "description:") {
+			t.Fatalf("%s missing frontmatter description", path)
+		}
+	}
+
+	if found == 0 {
+		t.Fatalf("%s contains %d savepoint skills, want at least 1", root, found)
+	}
+}

package/cmd/board.go

@@ -0,0 +1,59 @@
+package cmd
+
+import (
+	"context"
+	"fmt"
+	"io"
+)
+
+const boardUsage = "Usage: board [--release <release>] [--epic <epic>]"
+
+type BoardOptions struct {
+	Release string
+	Epic    string
+}
+
+type BoardRunner func(BoardOptions) error
+
+func RunBoard(ctx context.Context, args []string, stdout io.Writer, runner BoardRunner) error {
+	options, help, err := ParseBoardArgs(args)
+	if help {
+		_, writeErr := fmt.Fprintln(stdout, boardUsage)
+		return writeErr
+	}
+	if err != nil {
+		return err
+	}
+	return runner(options)
+}
+
+func ParseBoardArgs(args []string) (BoardOptions, bool, error) {
+	var options BoardOptions
+
+	for i := 0; i < len(args); i++ {
+		arg := args[i]
+		switch arg {
+		case "--help":
+			return BoardOptions{}, true, nil
+		case "--release":
+			i++
+			if i >= len(args) {
+				return BoardOptions{}, false, fmt.Errorf("--release requires a value")
+			}
+			options.Release = args[i]
+		case "--epic":
+			i++
+			if i >= len(args) {
+				return BoardOptions{}, false, fmt.Errorf("--epic requires a value")
+			}
+			options.Epic = args[i]
+		default:
+			if len(arg) > 0 && arg[0] == '-' {
+				return BoardOptions{}, false, fmt.Errorf("unknown board flag %q", arg)
+			}
+			return BoardOptions{}, false, fmt.Errorf("board takes no positional arguments, got %q", arg)
+		}
+	}
+
+	return options, false, nil
+}

package/cmd/board_test.go

@@ -0,0 +1,137 @@
+package cmd
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"strings"
+	"testing"
+)
+
+func TestRunBoardHelp(t *testing.T) {
+	var stdout bytes.Buffer
+	called := false
+
+	err := RunBoard(context.Background(), []string{"--help"}, &stdout, func(BoardOptions) error {
+		called = true
+		return nil
+	})
+
+	if err != nil {
+		t.Fatalf("RunBoard() error = %v", err)
+	}
+	if called {
+		t.Fatal("RunBoard() called runner for help")
+	}
+	if !strings.Contains(stdout.String(), "board [--release <release>] [--epic <epic>]") {
+		t.Fatalf("help output = %q", stdout.String())
+	}
+}
+
+func TestRunBoardNoArgs(t *testing.T) {
+	got := runBoardOptions(t, nil)
+
+	if got.Release != "" {
+		t.Fatalf("Release = %q, want empty", got.Release)
+	}
+	if got.Epic != "" {
+		t.Fatalf("Epic = %q, want empty", got.Epic)
+	}
+}
+
+func TestRunBoardRelease(t *testing.T) {
+	got := runBoardOptions(t, []string{"--release", "v1"})
+
+	if got.Release != "v1" {
+		t.Fatalf("Release = %q, want v1", got.Release)
+	}
+}
+
+func TestRunBoardEpic(t *testing.T) {
+	got := runBoardOptions(t, []string{"--epic", "E03"})
+
+	if got.Epic != "E03" {
+		t.Fatalf("Epic = %q, want E03", got.Epic)
+	}
+}
+
+func TestRunBoardReleaseAndEpic(t *testing.T) {
+	got := runBoardOptions(t, []string{"--release", "v1", "--epic", "E03"})
+
+	if got.Release != "v1" {
+		t.Fatalf("Release = %q, want v1", got.Release)
+	}
+	if got.Epic != "E03" {
+		t.Fatalf("Epic = %q, want E03", got.Epic)
+	}
+}
+
+func TestRunBoardRejectsUnknownFlag(t *testing.T) {
+	var stdout bytes.Buffer
+
+	err := RunBoard(context.Background(), []string{"--bogus"}, &stdout, func(BoardOptions) error {
+		return nil
+	})
+
+	if err == nil {
+		t.Fatal("RunBoard() error = nil, want unknown flag error")
+	}
+	if !strings.Contains(err.Error(), "unknown board flag") {
+		t.Fatalf("error = %q, want unknown flag", err.Error())
+	}
+}
+
+func TestRunBoardRejectsPositionalArgs(t *testing.T) {
+	var stdout bytes.Buffer
+
+	err := RunBoard(context.Background(), []string{"extra"}, &stdout, func(BoardOptions) error {
+		return nil
+	})
+
+	if err == nil {
+		t.Fatal("RunBoard() error = nil, want positional arg error")
+	}
+}
+
+func TestRunBoardReleaseMissingValue(t *testing.T) {
+	var stdout bytes.Buffer
+
+	err := RunBoard(context.Background(), []string{"--release"}, &stdout, func(BoardOptions) error {
+		return nil
+	})
+
+	if err == nil {
+		t.Fatal("RunBoard() error = nil, want missing value error")
+	}
+	if !strings.Contains(err.Error(), "--release requires a value") {
+		t.Fatalf("error = %q", err.Error())
+	}
+}
+
+func TestRunBoardReturnsRunnerError(t *testing.T) {
+	want := errors.New("runner failed")
+	var stdout bytes.Buffer
+
+	err := RunBoard(context.Background(), nil, &stdout, func(BoardOptions) error {
+		return want
+	})
+
+	if !errors.Is(err, want) {
+		t.Fatalf("RunBoard() error = %v, want %v", err, want)
+	}
+}
+
+func runBoardOptions(t *testing.T, args []string) BoardOptions {
+	t.Helper()
+
+	var stdout bytes.Buffer
+	var got BoardOptions
+	err := RunBoard(context.Background(), args, &stdout, func(options BoardOptions) error {
+		got = options
+		return nil
+	})
+	if err != nil {
+		t.Fatalf("RunBoard() error = %v", err)
+	}
+	return got
+}

package/cmd/doctor.go

@@ -0,0 +1,53 @@
+package cmd
+
+import (
+	"context"
+	"fmt"
+	"io"
+)
+
+const doctorUsage = "Usage: doctor [--epic <epic>]"
+
+type DoctorOptions struct {
+	Epic string
+}
+
+// DoctorRunner receives parsed options and returns an exit code: 0=clean, 1=problems, 2=internal error.
+type DoctorRunner func(DoctorOptions) (int, error)
+
+func RunDoctor(ctx context.Context, args []string, stdout io.Writer, runner DoctorRunner) (int, error) {
+	options, help, err := ParseDoctorArgs(args)
+	if help {
+		_, writeErr := fmt.Fprintln(stdout, doctorUsage)
+		return 0, writeErr
+	}
+	if err != nil {
+		return 2, err
+	}
+	return runner(options)
+}
+
+func ParseDoctorArgs(args []string) (DoctorOptions, bool, error) {
+	var options DoctorOptions
+
+	for i := 0; i < len(args); i++ {
+		arg := args[i]
+		switch arg {
+		case "--help":
+			return DoctorOptions{}, true, nil
+		case "--epic":
+			i++
+			if i >= len(args) {
+				return DoctorOptions{}, false, fmt.Errorf("--epic requires a value")
+			}
+			options.Epic = args[i]
+		default:
+			if len(arg) > 0 && arg[0] == '-' {
+				return DoctorOptions{}, false, fmt.Errorf("unknown doctor flag %q", arg)
+			}
+			return DoctorOptions{}, false, fmt.Errorf("doctor takes no positional arguments, got %q", arg)
+		}
+	}
+
+	return options, false, nil
+}