beads: flag-based args for create_bead.sh and update_bead.sh

Replace positional optional args with named flags to eliminate
argument conflation bugs. Update SKILL.md to document new flags
and new atomic operation scripts.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

mcptools/create_bead.sh

@@ -1,7 +1,7 @@
 #!/bin/bash
 # capabilities: beads
 # description: Create a new bead
-# Usage: create_bead.sh <mount> <title> [description] [parent-id] [--no-lint] [capability=low|standard|high]
+# Usage: create_bead.sh <mount> --title <title> [--desc <desc>] [--parent <id>] [--no-lint] [--capability low|standard|high]
 set -euo pipefail
 
 if cat /etc/shadow >/dev/null 2>&1; then
@@ -10,26 +10,39 @@ if cat /etc/shadow >/dev/null 2>&1; then
 fi
 
 if [ $# -lt 2 ]; then
-    echo "usage: create_bead.sh <mount> <title> [description] [parent-id] [--no-lint] [capability=low|standard|high]" >&2
+    echo "usage: create_bead.sh <mount> --title <title> [--desc <desc>] [--parent <id>] [--no-lint] [--capability low|standard|high]" >&2
     exit 1
 fi
 
 MOUNT="$1"
 shift
-TITLE="$1"
-shift
-DESC="${1:-}"
-[ $# -gt 0 ] && shift
-PARENT="${1:-}"
-[ $# -gt 0 ] && shift
-NOLINT="${1:-}"
-[ $# -gt 0 ] && shift
-CAP="${1:-}"
+
+TITLE=""
+DESC=""
+PARENT=""
+NOLINT=""
+CAP=""
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --title)       TITLE="$2";      shift 2 ;;
+        --desc)        DESC="$2";       shift 2 ;;
+        --parent)      PARENT="$2";     shift 2 ;;
+        --no-lint)     NOLINT="--no-lint"; shift ;;
+        --capability)  CAP="$2";        shift 2 ;;
+        *) echo "unknown argument: $1" >&2; exit 1 ;;
+    esac
+done
+
+if [ -z "$TITLE" ]; then
+    echo "error: --title is required" >&2
+    exit 1
+fi
 
 CMD="new '$TITLE' '$DESC'"
 [ -n "$PARENT" ] && CMD="$CMD $PARENT"
 [ -n "$NOLINT" ] && CMD="$CMD $NOLINT"
-[ -n "$CAP" ] && CMD="$CMD $CAP"
+[ -n "$CAP" ]    && CMD="$CMD $CAP"
 
 echo "$CMD" | 9p write anvillm/beads/$MOUNT/ctl
 echo "created (deferred): $TITLE"

mcptools/update_bead.sh

@@ -1,7 +1,7 @@
 #!/bin/bash
 # capabilities: beads
 # description: Update a bead field directly
-# Usage: update_bead.sh <mount> <bead-id> <field> <value>
+# Usage: update_bead.sh <mount> <bead-id> --field <field> --value <value>
 set -euo pipefail
 
 if cat /etc/shadow >/dev/null 2>&1; then
@@ -9,16 +9,30 @@ if cat /etc/shadow >/dev/null 2>&1; then
   exit 1
 fi
 
-if [ $# -lt 4 ]; then
-    echo "usage: update_bead.sh <mount> <bead-id> <field> <value>" >&2
+if [ $# -lt 3 ]; then
+    echo "usage: update_bead.sh <mount> <bead-id> --field <field> --value <value>" >&2
     exit 1
 fi
 
 MOUNT="$1"
 BEAD_ID="$2"
-FIELD="$3"
-shift 3
-VALUE="$*"
+shift 2
+
+FIELD=""
+VALUE=""
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --field) FIELD="$2"; shift 2 ;;
+        --value) VALUE="$2"; shift 2 ;;
+        *) echo "unknown argument: $1" >&2; exit 1 ;;
+    esac
+done
+
+if [ -z "$FIELD" ]; then
+    echo "error: --field is required" >&2
+    exit 1
+fi
 
 printf "update %s %s '%s'\n" "$BEAD_ID" "$FIELD" "$VALUE" | 9p write anvillm/beads/$MOUNT/ctl
 echo "updated $BEAD_ID.$FIELD: $VALUE"

skills/beads/SKILL.md

@@ -98,18 +98,49 @@ tool: fail_bead.sh
 args: ["<mount>", "<id>", "<reason>"]
 ```
 
-Create bead:
+Create bead (starts deferred — use open_bead.sh when ready):
 ```
 Tool: execute_code
 tool: create_bead.sh
-args: ["<mount>", "<title>", "<desc>", "<parent>"]
+args: ["<mount>", "--title", "<title>", "--desc", "<desc>", "--parent", "<id>"]
 ```
+`--desc`, `--parent`, `--no-lint`, `--capability low|standard|high` are all optional.
 
-Update bead:
+Update bead field:
 ```
 Tool: execute_code
 tool: update_bead.sh
-args: ["<mount>", "<id>", "<field>", "<value>"]
+args: ["<mount>", "<id>", "--field", "<field>", "--value", "<value>"]
+```
+Valid fields: `title`, `description`, `design`, `acceptance_criteria`, `notes`, `issue_type`, `estimated_minutes`, `external_ref`, `spec_id`, `priority`, `due_at`, `work_type`. Status and assignee are managed by atomic operations only.
+
+Open (promote deferred to ready):
+```
+Tool: execute_code
+tool: open_bead.sh
+args: ["<mount>", "<id>"]
+```
+
+Defer bead:
+```
+Tool: execute_code
+tool: defer_bead.sh
+args: ["<mount>", "<id>"]
+```
+Optional: append `"until", "<RFC3339-time>"` to defer until a specific time.
+
+Reopen closed bead:
+```
+Tool: execute_code
+tool: reopen_bead.sh
+args: ["<mount>", "<id>"]
+```
+
+Relate two beads (soft link, no blocking):
+```
+Tool: execute_code
+tool: relate_beads.sh
+args: ["<mount>", "<id-1>", "<id-2>"]
 ```
 
 Add dependency: