chore(board): remove example-task.json; document schema in board README

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: MertCapkin

.github/workflows/ci.yml

@@ -76,7 +76,6 @@ jobs:
               "handoff/BOOTSTRAP.md",
               "handoff/STATE.md",
               "handoff/board/README.md",
-              "handoff/board/todo/example-task.json",
               "handoff/board/doing/.gitkeep",
               "handoff/board/done/.gitkeep",
               "docs/CURSOR_PROMPTS.md",
@@ -108,18 +107,25 @@ jobs:
               print(f"\n{len(missing)} file(s) missing.", file=sys.stderr)
               sys.exit(1)
 
-      - name: Validate example task JSON
+      - name: Validate GNAP task schema (board new)
         shell: python
         run: |
-          import json, sys
-          with open("handoff/board/todo/example-task.json", encoding="utf-8") as f:
-              data = json.load(f)
-          required = ["id", "title", "status", "assigned_to", "created_at"]
+          import json, subprocess, sys
+          from pathlib import Path
+
+          subprocess.run(
+              [sys.executable, "-m", "graphstack", "board", "new", "schema-check", "CI schema probe"],
+              check=True,
+          )
+          path = Path("handoff/board/todo/schema-check.json")
+          data = json.loads(path.read_text(encoding="utf-8"))
+          required = ["id", "title", "status", "created_at"]
           missing = [k for k in required if k not in data]
+          path.unlink(missing_ok=True)
           if missing:
-              print(f"Missing keys: {missing}", file=sys.stderr)
+              print(f"board new() missing keys: {missing}", file=sys.stderr)
               sys.exit(1)
-          print("example-task.json schema OK")
+          print("GNAP task schema OK")
 
       - name: Run graphstack pytest suite
         run: python -m pytest scripts/graphstack/tests -v

handoff/board/README.md

@@ -26,4 +26,30 @@ board/
 
 ## Task File Format
 
-See `board/todo/example-task.json` for the schema.
+Create `board/todo/<task-id>.json` (filename must match `id`):
+
+```json
+{
+  "id": "add-rate-limiting",
+  "title": "Add rate limiting to login endpoint",
+  "created_at": "2026-05-04T10:00:00Z",
+  "created_by": "architect",
+  "brief": "handoff/BRIEF.md",
+  "graph_nodes": [],
+  "criteria_count": 0,
+  "priority": "normal",
+  "status": "todo",
+  "assigned_to": null,
+  "started_at": null,
+  "completed_at": null,
+  "notes": ""
+}
+```
+
+Or use the CLI:
+
+```bash
+python -m graphstack board new <task-id> "Task title here"
+```
+
+Required fields: `id`, `title`, `status`, `created_at`.

orchestrator/ORCHESTRATOR.md

@@ -26,7 +26,7 @@ Execute this sequence exactly on every session start. Each step has a fallback 
    → If directory empty or missing: no tasks in progress — skip silently
    → If 1+ files found: note which tasks are in progress
 
-5. Read handoff/board/todo/*.json (exclude example-task.json)
+5. Read handoff/board/todo/*.json
    → If empty: no pending tasks — skip silently
    → If 1+ files found: note how many tasks are waiting
 

scripts/graphstack/board.py

@@ -11,7 +11,7 @@
 import sys
 from pathlib import Path
 
-from .constants import BOARD_DIR, DOING_DIR, DONE_DIR, EXAMPLE_TASK_NAME, TODO_DIR
+from .constants import BOARD_DIR, DOING_DIR, DONE_DIR, TODO_DIR
 from .platform_utils import echo, run_git, utc_now_iso
 
 VALID_ROLES = ("architect", "builder", "reviewer", "qa", "ship", "bootstrapper")
@@ -47,13 +47,10 @@ def _print_task(path: Path) -> None:
     )
 
 
-def _iter_tasks(directory: Path, exclude_example: bool = False) -> list[Path]:
+def _iter_tasks(directory: Path) -> list[Path]:
     if not directory.is_dir():
         return []
-    files = sorted(directory.glob("*.json"))
-    if exclude_example:
-        files = [f for f in files if f.name != EXAMPLE_TASK_NAME]
-    return files
+    return sorted(directory.glob("*.json"))
 
 
 def _git_commit_board(message: str) -> None:
@@ -69,7 +66,7 @@ def cmd_status(_args: argparse.Namespace) -> int:
     echo(f"  {'TASK ID':<32} {'STATUS':<10} {'ASSIGNED':<12} TITLE")
     echo("  " + "-" * 54)
 
-    todo = _iter_tasks(TODO_DIR, exclude_example=True)
+    todo = _iter_tasks(TODO_DIR)
     doing = _iter_tasks(DOING_DIR)
     done = _iter_tasks(DONE_DIR)
 

scripts/graphstack/constants.py

@@ -20,6 +20,7 @@
 GRAPH_JSON = GRAPHIFY_OUT / "graph.json"
 GRAPH_HTML = GRAPHIFY_OUT / "graph.html"
 
-EXAMPLE_TASK_NAME = "example-task.json"
-
 STALE_GRAPH_HOURS = 24
+
+# Required keys for GNAP board task JSON files (see handoff/board/README.md).
+TASK_REQUIRED_KEYS = ("id", "title", "status", "created_at")

scripts/graphstack/installer.py

@@ -52,7 +52,6 @@
     (".cursor/skills/ship/SHIP.md", ".cursor/skills/ship/SHIP.md"),
     (".cursor/skills/bootstrapper/BOOTSTRAPPER.md", ".cursor/skills/bootstrapper/BOOTSTRAPPER.md"),
     ("handoff/board/README.md", "handoff/board/README.md"),
-    ("handoff/board/todo/example-task.json", "handoff/board/todo/example-task.json"),
     ("docs/CURSOR_PROMPTS.md", "docs/CURSOR_PROMPTS.md"),
     ("scripts/board.sh", "scripts/board.sh"),
     ("scripts/board.ps1", "scripts/board.ps1"),

scripts/graphstack/tests/test_installer.py

@@ -39,7 +39,6 @@ def test_install_creates_full_layout(tmp_path: Path, monkeypatch: pytest.MonkeyP
         "orchestrator/TOKEN_OPTIMIZER.md",
         ".cursor/skills/builder/BUILDER.md",
         "handoff/board/README.md",
-        "handoff/board/todo/example-task.json",
         "handoff/STATE.md",
         "scripts/board.sh",
         "scripts/board.ps1",

scripts/graphstack/validate.py

@@ -17,14 +17,13 @@
     BOARD_DIR,
     DOING_DIR,
     DONE_DIR,
-    EXAMPLE_TASK_NAME,
     GRAPH_REPORT,
     HANDOFF_DIR,
+    TASK_REQUIRED_KEYS,
     TODO_DIR,
 )
 from .platform_utils import echo, git_available, graphify_available, run_git
 
-TASK_REQUIRED_KEYS = ("id", "title", "status", "created_at")
 BRIEF_TEMPLATE_MARKERS = (
     "[Feature/Change Name]",
     "YYYY-MM-DD",
@@ -77,10 +76,7 @@ def _iter_board_tasks() -> list[Path]:
     for directory in (TODO_DIR, DOING_DIR, DONE_DIR):
         if not directory.is_dir():
             continue
-        for path in sorted(directory.glob("*.json")):
-            if path.name == EXAMPLE_TASK_NAME:
-                continue
-            paths.append(path)
+        paths.extend(sorted(directory.glob("*.json")))
     return paths