@jenga-ai/agent 1.0.0

package/scripts/measurement-real.json

@@ -0,0 +1,50 @@
+{
+  "results": [
+    {
+      "command": "python3 scripts/e25_s01_extract_board_graph.py project >/dev/null",
+      "mean": 0.13581702562,
+      "stddev": 0.01795068160628955,
+      "median": 0.12633394632,
+      "user": 0.0488429,
+      "system": 0.02490142,
+      "min": 0.12153511332000001,
+      "max": 0.16625157132,
+      "times": [
+        0.12962952932000002,
+        0.12303836332,
+        0.16625157132,
+        0.15362957132000002,
+        0.12211615531999999,
+        0.12262336332,
+        0.12190103032,
+        0.16218352932000002,
+        0.13526202932,
+        0.12153511332000001
+      ],
+      "memory_usage_byte": [
+        20250624,
+        20250624,
+        20267008,
+        20267008,
+        20267008,
+        20267008,
+        20267008,
+        20267008,
+        20430848,
+        20430848
+      ],
+      "exit_codes": [
+        0,
+        0,
+        0,
+        0,
+        0,
+        0,
+        0,
+        0,
+        0,
+        0
+      ]
+    }
+  ]
+}

package/scripts/measurement-real.txt

@@ -0,0 +1,4 @@
+Benchmark 1: python3 scripts/e25_s01_extract_board_graph.py project >/dev/null
+  Time (mean ± σ):     135.8 ms ±  18.0 ms    [User: 48.8 ms, System: 24.9 ms]
+  Range (min … max):   121.5 ms … 166.3 ms    10 runs
+ 

package/scripts/postinstall.js

@@ -0,0 +1,165 @@
+#!/usr/bin/env node
+/**
+ * postinstall.js — JengaAgent consumer installation hook
+ *
+ * Runs automatically when a consumer project installs jenga-agent via npm.
+ * Copies the discovery-bound dirs — `skills/` and `agents/` — into BOTH
+ * `<consumer>/.claude/` (where Claude Code looks) and `<consumer>/.agents/`
+ * (where non-Claude agents like Copilot / custom look, per the framework's
+ * agent-target convention). This duplication is required because each agent
+ * ecosystem has its own fixed discovery path.
+ *
+ * Everything else (`hooks/`, `scripts/`, `templates/`, `mcp/`, `lib/`) stays
+ * in the installed package and is sourced from `node_modules/jenga-agent/…`
+ * at runtime — no duplication.
+ *
+ * The consumer's `project/` directory (if present) is left untouched.
+ *
+ * Safe upgrade behaviour:
+ *   - First-time installs: always copy all files.
+ *   - Subsequent installs: only overwrite if the new package version is strictly
+ *     newer (semver) than the version recorded in <consumer-root>/.jenga-version.
+ *
+ * After a successful copy, writes .jenga-version with the current package version.
+ *
+ * The actual filesystem mirror is delegated to `lib/mirror.js`, which is the
+ * single source of truth shared with the in-repo `/self-sync` skill. Consumer
+ * install always uses `reconcileDeletes: false` (additive-only).
+ */
+
+import fs   from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { mirror } from '../lib/mirror.js';
+
+// ESM equivalent of __dirname
+const __filename = fileURLToPath(import.meta.url);
+const __dirname  = path.dirname(__filename);
+
+// ── helpers ──────────────────────────────────────────────────────────────────
+
+/**
+ * Very small semver comparator.
+ * Returns 1 if a > b, -1 if a < b, 0 if equal.
+ */
+function semverCompare(a, b) {
+  const clean  = (v) => String(v || '0.0.0').replace(/[^0-9.]/g, '');
+  const parts  = (v) => clean(v).split('.').map(Number);
+  const [aMaj, aMin, aPat] = parts(a);
+  const [bMaj, bMin, bPat] = parts(b);
+  if (aMaj !== bMaj) return aMaj > bMaj ? 1 : -1;
+  if (aMin !== bMin) return aMin > bMin ? 1 : -1;
+  if (aPat !== bPat) return aPat > bPat ? 1 : -1;
+  return 0;
+}
+
+// ── main ─────────────────────────────────────────────────────────────────────
+
+function main() {
+  // __dirname is scripts/ inside the package; package root is one level up
+  const packageRoot = path.resolve(__dirname, '..');
+
+  // npm sets INIT_CWD to the directory where the user ran `npm install`
+  const consumerRoot = process.env.INIT_CWD || process.cwd();
+
+  // Avoid running during development (when INIT_CWD === packageRoot itself)
+  if (path.resolve(consumerRoot) === path.resolve(packageRoot)) {
+    console.log('\n  ℹ  JengaAgent postinstall: running inside the package itself — skipping copy.\n');
+    return;
+  }
+
+  // Read this package's version
+  let packageVersion = '0.0.0';
+  try {
+    const pkgPath = path.join(packageRoot, 'package.json');
+    const pkg     = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+    packageVersion = pkg.version || '0.0.0';
+  } catch (_) {
+    // non-fatal — proceed with default
+  }
+
+  // Read the installed version at the consumer root (if any)
+  const versionFile    = path.join(consumerRoot, '.jenga-version');
+  let installedVersion = null;
+  try {
+    installedVersion = fs.readFileSync(versionFile, 'utf8').trim();
+  } catch (_) {
+    // file doesn't exist yet — first-time install
+  }
+
+  const isFirstInstall = installedVersion === null;
+  const isUpgrade      = !isFirstInstall && semverCompare(packageVersion, installedVersion) > 0;
+  const shouldCopy     = isFirstInstall || isUpgrade;
+
+  console.log('\n╔══════════════════════════════════════════════════════╗');
+  console.log('║            JengaAgent — postinstall hook             ║');
+  console.log('╚══════════════════════════════════════════════════════╝\n');
+  console.log(`  Package version  : ${packageVersion}`);
+  console.log(`  Installed version: ${installedVersion ?? '(none — first install)'}`);
+  console.log(`  Consumer root    : ${consumerRoot}`);
+  console.log(`  Action           : ${
+    isFirstInstall ? 'First install — copying all framework files' :
+    isUpgrade      ? `Upgrade ${installedVersion} → ${packageVersion} — copying all framework files` :
+                     'Same or newer version already installed — skipping overwrite'
+  }\n`);
+
+  if (!shouldCopy) {
+    console.log('  ✓ Nothing to do. Your framework files are already up to date.\n');
+    return;
+  }
+
+  // Discovery-bound dirs get mirrored to both .claude/ (Claude Code) and
+  // .agents/ (Copilot / custom). Everything else is sourced from
+  // node_modules/jenga-agent/… at runtime — no duplication.
+  const copySet    = ['skills', 'agents'];
+  const targetRoots = ['.claude', '.agents'];
+
+  // Warn about any copySet entries that are missing from the package — the
+  // helper silently skips missing sources, so we surface it here for parity
+  // with the previous UX.
+  for (const entry of copySet) {
+    if (!fs.existsSync(path.join(packageRoot, entry))) {
+      console.log(`  ⚠  ${entry}/ not found in package — skipped`);
+    }
+  }
+
+  let totalCopied  = 0;
+  let totalSkipped = 0;
+
+  for (const targetRoot of targetRoots) {
+    const destRoot = path.join(consumerRoot, targetRoot);
+
+    // Consumer install is additive-only: never delete files from the mirror.
+    const result = mirror({
+      sourceRoot:       packageRoot,
+      destRoot,
+      copySet,
+      dryRun:           false,
+      reconcileDeletes: false,
+    });
+
+    // For the per-directory line we report the aggregate write count
+    // (added + overwritten) so the message matches the pre-refactor UX
+    // ("N file(s) copied") even though we now distinguish the two.
+    for (const entry of copySet) {
+      const wrote =
+        result.added.filter((p) => p.startsWith(path.join(destRoot, entry))).length +
+        result.overwritten.filter((p) => p.startsWith(path.join(destRoot, entry))).length;
+      console.log(`  ✓ ${targetRoot}/${entry}/ — ${wrote} file(s) copied`);
+    }
+
+    totalCopied  += result.added.length + result.overwritten.length;
+    totalSkipped += result.skipped.length;
+  }
+
+  // Write .jenga-version to record the installed version at consumer root
+  fs.writeFileSync(versionFile, packageVersion + '\n', 'utf8');
+
+  console.log('\n──────────────────────────────────────────────────────');
+  console.log(`  Summary: ${totalCopied} file(s) copied, ${totalSkipped} skipped`);
+  console.log(`  .jenga-version written: ${packageVersion}`);
+  console.log('──────────────────────────────────────────────────────\n');
+}
+
+main();

package/scripts/todo_cleanup.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+
+TODO_FILE="project/todo.md"
+
+[ ! -f "$TODO_FILE" ] && exit 0
+
+# Check if file is effectively empty (only blank lines, "# Todo", or single-line HTML comments)
+while IFS= read -r line; do
+  # Skip blank/whitespace-only lines
+  [[ -z "${line// }" ]] && continue
+  # Skip "# Todo" header
+  [[ "$line" == "# Todo" ]] && continue
+  # Skip single-line HTML comments
+  [[ "$line" == \<\!--*--\> ]] && continue
+  # Found a real entry — exit silently
+  exit 0
+done < "$TODO_FILE"
+
+# File is effectively empty — delete it
+rm "$TODO_FILE"
+echo "[todo_cleanup] project/todo.md was empty — deleted."
+exit 0

package/scripts/todo_manager.sh

@@ -0,0 +1,86 @@
+#!/usr/bin/env bash
+# scripts/todo_manager.sh — canonical owner of all project/todo.md operations.
+# Run from the repository root.
+
+TODO_FILE="project/todo.md"
+TEMPLATE="skills/todo/assets/todo_template.md"
+
+usage() {
+  cat >&2 <<EOF
+Usage: $0 <subcommand> [args]
+
+Subcommands:
+  add "<entry>"    Append entry to project/todo.md (auto-creates from template if missing)
+  remove "<title>" Remove first line containing <title> (exits non-zero if not found)
+  list             Print all non-comment, non-blank entries (silent if file missing/empty)
+  exists           Exit 0 if at least one real entry exists; exit 1 otherwise
+  teardown         Delete project/todo.md if effectively empty; no-op if absent or has real entries
+EOF
+  exit 1
+}
+
+# Filters out blank lines, lines starting with #, and HTML comments
+real_entries() {
+  grep -v '^\s*$' "$1" 2>/dev/null \
+    | grep -v '^\s*#' \
+    | grep -v '^\s*<!--'
+}
+
+case "${1:-}" in
+  add)
+    [ -z "${2:-}" ] && { echo "Error: add requires an entry argument" >&2; exit 1; }
+    if [ ! -f "$TODO_FILE" ]; then
+      if [ ! -f "$TEMPLATE" ]; then
+        echo "Error: template not found at $TEMPLATE" >&2; exit 1
+      fi
+      cp "$TEMPLATE" "$TODO_FILE"
+    fi
+    printf '%s\n' "$2" >> "$TODO_FILE"
+    ;;
+
+  remove)
+    [ -z "${2:-}" ] && { echo "Error: remove requires a title argument" >&2; exit 1; }
+    if [ ! -f "$TODO_FILE" ]; then
+      echo "Error: $TODO_FILE does not exist" >&2; exit 1
+    fi
+    # Check for at least one match
+    if ! grep -qF "$2" "$TODO_FILE"; then
+      echo "Error: no line matching \"$2\" found in $TODO_FILE" >&2; exit 1
+    fi
+    # Remove only the FIRST matching line atomically
+    awk -v title="$2" 'found || !index($0, title) { print; next } { found=1 }' \
+      "$TODO_FILE" > "${TODO_FILE}.tmp" && mv "${TODO_FILE}.tmp" "$TODO_FILE"
+    ;;
+
+  list)
+    [ ! -f "$TODO_FILE" ] && exit 0
+    real_entries "$TODO_FILE"
+    exit 0
+    ;;
+
+  exists)
+    if [ ! -f "$TODO_FILE" ]; then
+      echo "todo.md is missing" >&2; exit 1
+    fi
+    if [ -z "$(real_entries "$TODO_FILE")" ]; then
+      echo "todo.md exists but has no real entries" >&2; exit 1
+    fi
+    exit 0
+    ;;
+
+  teardown)
+    [ ! -f "$TODO_FILE" ] && exit 0
+    # "Effectively empty" = only blank lines, "# Todo", or HTML comments
+    non_trivial=$(grep -v '^\s*$' "$TODO_FILE" \
+      | grep -v '^\s*# Todo\s*$' \
+      | grep -v '^\s*<!--')
+    if [ -z "$non_trivial" ]; then
+      rm -f "$TODO_FILE"
+    fi
+    exit 0
+    ;;
+
+  *)
+    usage
+    ;;
+esac

package/scripts/validate-board.sh

@@ -0,0 +1,190 @@
+#!/usr/bin/env bash
+# validate-board.sh — validate scrum board frontmatter for epic, story, and task files
+#
+# Usage: ./scripts/validate-board.sh <path-to-board-file> [more-files...]
+
+set -euo pipefail
+
+if [[ "$#" -lt 1 ]]; then
+  echo "❌ Usage: $(basename "$0") <path-to-board-file> [more-files...]"
+  exit 1
+fi
+
+python3 - "$@" <<'PY'
+import re
+import sys
+from pathlib import Path
+
+STATUS_VALUES = {
+    "Pending",
+    "In Progress",
+    "Passed",
+    "Passed with remarks",
+    "Failed",
+    "Rejected",
+    "Blocked",
+    "Backlog",
+    "Done",
+}
+
+ALLOWED_KEYS = {
+    "epic": {
+        "id", "title", "status", "date_created", "date_started", "date_completed",
+        "dates_previously_completed", "reopened_on", "reopened_reason", "stories", "docs",
+    },
+    "story": {
+        "id", "epic_id", "title", "status", "date_created", "date_started", "date_completed",
+        "dates_previously_completed", "reopened_on", "reopened_reason", "tasks", "docs",
+    },
+    "task": {
+        "id", "story_id", "epic_id", "title", "status", "date_created", "date_started", "date_completed",
+        "dates_previously_completed", "reopened_on", "reopened_reason", "assigned_to", "docs",
+    },
+}
+
+ID_PATTERNS = {
+    "epic": re.compile(r"^E\d{2}$"),
+    "story": re.compile(r"^E\d{2}_S\d{2}$"),
+    "task": re.compile(r"^E\d{2}_S\d{2}_T\d{2}$"),
+}
+
+ASSIGNEES = {"developer", "tester", "scrum-master"}
+
+def split_comment(value: str) -> str:
+    if "#" in value:
+        return value.split("#", 1)[0].rstrip()
+    return value.rstrip()
+
+def extract_frontmatter(text: str, source: Path) -> list[str]:
+    lines = text.splitlines()
+    if not lines or lines[0].strip() != "---":
+        raise ValueError(f"{source}: missing opening frontmatter delimiter")
+    try:
+        end_index = next(i for i in range(1, len(lines)) if lines[i].strip() == "---")
+    except StopIteration:
+        raise ValueError(f"{source}: missing closing frontmatter delimiter")
+    return lines[1:end_index]
+
+def classify_item(item_id: str) -> str:
+    for item_type, pattern in ID_PATTERNS.items():
+        if pattern.match(item_id):
+            return item_type
+    raise ValueError(f"unrecognised board item id format: {item_id}")
+
+def parse_frontmatter(lines: list[str], source: Path) -> dict:
+    data = {}
+    i = 0
+    while i < len(lines):
+        raw = lines[i]
+        if not raw.strip():
+            i += 1
+            continue
+        if raw.startswith("  - "):
+            raise ValueError(f"{source}: list item without a parent key: {raw.strip()}")
+        if ":" not in raw:
+            raise ValueError(f"{source}: invalid frontmatter line: {raw.strip()}")
+
+        key, value = raw.split(":", 1)
+        key = key.strip()
+        value = split_comment(value.strip())
+
+        if value == "":
+            items = []
+            j = i + 1
+            while j < len(lines) and lines[j].startswith("  - "):
+                items.append(split_comment(lines[j][4:].strip()))
+                j += 1
+            data[key] = items if items else ""
+            i = j
+            continue
+
+        if value.startswith("[") and value.endswith("]"):
+            inner = value[1:-1].strip()
+            if inner == "":
+                data[key] = []
+            else:
+                parts = [part.strip() for part in inner.split(",")]
+                parsed = []
+                for part in parts:
+                    parsed.append(part.strip().strip('"').strip("'"))
+                data[key] = parsed
+        else:
+            data[key] = value.strip().strip('"').strip("'")
+        i += 1
+    return data
+
+def validate_docs(source: Path, docs):
+    if docs == "":
+        raise ValueError(f"{source}: docs must be a YAML list when present")
+    if not isinstance(docs, list):
+        raise ValueError(f"{source}: docs must be a YAML list")
+    for entry in docs:
+        if not isinstance(entry, str) or not entry.strip():
+            raise ValueError(f"{source}: docs entries must be non-empty strings")
+        cleaned = entry.strip()
+        if (
+            cleaned.startswith("/")
+            or cleaned.startswith("./")
+            or cleaned.startswith("../")
+            or "/./" in cleaned
+            or cleaned.endswith("/.")
+            or "/../" in cleaned
+            or cleaned == ".."
+        ):
+            raise ValueError(f"{source}: docs entry must be repo-relative without leading './' or '/' ({entry})")
+
+def validate_file(source: Path):
+    text = source.read_text(encoding="utf-8")
+    frontmatter_lines = extract_frontmatter(text, source)
+    data = parse_frontmatter(frontmatter_lines, source)
+
+    item_id = data.get("id")
+    if not item_id:
+        raise ValueError(f"{source}: missing required 'id' frontmatter field")
+
+    item_type = classify_item(item_id)
+    allowed_keys = ALLOWED_KEYS[item_type]
+    unknown_keys = sorted(set(data.keys()) - allowed_keys)
+    if unknown_keys:
+        raise ValueError(f"{source}: unknown frontmatter field(s) for {item_type}: {', '.join(unknown_keys)}")
+
+    status = data.get("status")
+    if status and status not in STATUS_VALUES:
+        raise ValueError(f"{source}: invalid status '{status}'")
+
+    docs = data.get("docs", None)
+    if docs is not None:
+        validate_docs(source, docs)
+
+    if item_type == "epic":
+        if "stories" in data and data["stories"] != "" and not isinstance(data["stories"], list):
+            raise ValueError(f"{source}: stories must be a YAML list when present")
+    elif item_type == "story":
+        if not data.get("epic_id"):
+            raise ValueError(f"{source}: story files require epic_id")
+        if "tasks" in data and data["tasks"] != "" and not isinstance(data["tasks"], list):
+            raise ValueError(f"{source}: tasks must be a YAML list when present")
+    elif item_type == "task":
+        if not data.get("epic_id") or not data.get("story_id"):
+            raise ValueError(f"{source}: task files require both epic_id and story_id")
+        assigned_to = data.get("assigned_to", "")
+        if assigned_to and assigned_to not in ASSIGNEES:
+            raise ValueError(f"{source}: assigned_to must be one of: developer, tester, scrum-master")
+
+    print(f"✅ {source}: board frontmatter valid ({item_type})")
+
+exit_code = 0
+for raw_path in sys.argv[1:]:
+    path = Path(raw_path)
+    if not path.is_file():
+        print(f"❌ {path}: file not found or not readable", file=sys.stderr)
+        exit_code = 1
+        continue
+    try:
+        validate_file(path)
+    except Exception as exc:
+        print(f"❌ {exc}", file=sys.stderr)
+        exit_code = 1
+
+sys.exit(exit_code)
+PY

package/scripts/validate-story-format.sh

@@ -0,0 +1,53 @@
+#!/usr/bin/env bash
+# validate-story-format.sh — validate a story markdown file against required format rules
+#
+# Usage: ./scripts/validate-story-format.sh <path-to-story-file>
+#
+# Exit codes:
+#   0  Story format is valid
+#   1  File not found or not readable
+#   2  Missing "## Acceptance Criteria" section
+#   3  Missing "## Definition of Done" section
+#   4  Definition of Done has no checkbox items
+
+set -euo pipefail
+
+FILE="${1:-}"
+
+if [[ -z "$FILE" ]]; then
+  echo "❌ Usage: $(basename "$0") <path-to-story-file>"
+  exit 1
+fi
+
+if [[ ! -f "$FILE" ]] || [[ ! -r "$FILE" ]]; then
+  echo "❌ File not found or not readable: $FILE"
+  exit 1
+fi
+
+STORY_ID=$(basename "$FILE" .md)
+
+# Check 2: ## Acceptance Criteria section present
+if ! grep -q "^## Acceptance Criteria" "$FILE"; then
+  echo "❌ $STORY_ID: missing '## Acceptance Criteria' section — $FILE"
+  exit 2
+fi
+
+# Check 3: ## Definition of Done section present
+if ! grep -q "^## Definition of Done" "$FILE"; then
+  echo "❌ $STORY_ID: missing '## Definition of Done' section — $FILE"
+  exit 3
+fi
+
+# Check 4: DoD section contains at least one checkbox item.
+# Allow unchecked boxes in planned stories and checked boxes after tester verification.
+# Extract content of the DoD section (lines after ## Definition of Done up to the next ## heading or EOF)
+DOD_CONTENT=$(awk '/^## Definition of Done/{found=1; next} found && /^## /{found=0} found{print}' "$FILE")
+
+if ! echo "$DOD_CONTENT" | grep -Eq "^- \[( |x)\]"; then
+  echo "❌ $STORY_ID: '## Definition of Done' has no checkbox items — $FILE"
+  echo "   Each DoD item must use '- [ ] <criterion>' or '- [x] <criterion>', not plain bullets"
+  exit 4
+fi
+
+echo "✅ $STORY_ID: story format valid"
+exit 0

package/skills/brainstorm/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: brainstorm
+description: Engage the scrum-master agent in a focused planning session to define, refine, or challenge features, improvements, tasks, stories, and epics. The agent asks probing questions, challenges assumptions, and helps shape ideas into actionable backlog items.
+keywords:
+  - brainstorm
+  - plan
+  - ideate
+  - feature planning
+  - requirements
+examples:
+  - "let's brainstorm ideas for X"
+  - "I need to plan a new feature"
+metadata: 
+  prefered_agent: scrum-master
+---
+
+# Brainstorm — Collaborative Planning with the Scrum Master
+
+## Instructions
+
+1. **Invoke the `scrum-master` agent** — Pass the user's input directly to it as the opening prompt for the brainstorm session.
+
+2. **Session framing** — Tell the `scrum-master` agent:
+   - This is a **brainstorm session**, not a direct backlog-write session
+   - The goal is to explore, challenge, and refine ideas **before** committing anything to the board
+   - The agent should be especially frank, inquisitive, and suggestive during this session
+   - No board items should be created until the user explicitly says they are ready to commit
+
+3. **The `scrum-master` agent should:**
+   - Ask focused, pointed questions to uncover goals, constraints, edge cases, and unknowns
+   - Actively challenge assumptions — if something sounds vague, under-scoped, over-scoped, or contradicts existing work, say so plainly
+   - Suggest alternative framings, decompositions, or approaches when the current one seems weak
+   - Propose how the idea maps to epics, stories, or tasks — but hold off on writing anything until agreed
+   - Keep the dialogue moving: after each exchange, either surface the next open question or propose a next step
+
+4. **End of brainstorm** — Once the user is satisfied with the shape of the work, ask:
+   - "Are you ready to commit these items to the board?"
+   - If **yes** — proceed to create the relevant board items using `/todo` or the appropriate scrum board commands
+   - If **no** — continue refining or close the session
+
+### Session End
+
+When the brainstorming session concludes (whether items were committed or the user chose to close), emit the following signal on its own line so the Jenga Router clears the active session:
+
+```
+[JENGA:SESSION_END:brainstorm]
+```

package/skills/btw/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: btw
+description: Capture a new mission (feature, change, or addition) and fit it into the project's Epic/Story structure, then choose to implement now or defer.
+keywords:
+  - btw
+  - capture
+  - mission
+  - new idea
+  - side task
+examples:
+  - "btw I also need to add X"
+  - "capture this as a new task"
+metadata: 
+  prefered_agent: scrum-master
+---
+
+# BTW — Capture a Mission
+
+## Instructions
+
+1. **Gather mission details** — Ask the user:
+   - Where do you want to do this?
+   - What would you like to do?
+   - What is the goal?
+
+2. **Classify the mission** — Based on the description, determine if it fits into:
+   - An existing story
+   - A new story inside an existing Epic
+   - A new story inside a new Epic
+
+3. **Update project documentation** — Add the mission to the appropriate board files:
+   - **New story**: create a file in `project/board/stories/` using `../pi-plan/assets/story_template.md` as the structure.
+   - **New epic**: append a new Epic object to `project/PROJECT_SUMMARY.md` using the schema in `../pi-plan/assets/epic.json`.
+   - **Existing story**: append the new task or acceptance criterion to the matching file in `project/board/stories/`.
+
+4. **Ask the user: "now" or "later"?**
+   - If **"now"** — Produce a plan for the first story related to the mission and begin implementation.
+   - If **"later"** — Confirm the mission has been recorded and resume the previous workflow.
+
+## Examples
+- `/btw` — Start the interactive mission capture flow
+- `/btw add a dark mode toggle to the settings page` — Pre-fill the "what" and jump into classification