feat(keystone): add keystone-workflows package and devcontainer integration (#5)

Add BMAD keystone workflow orchestration to the devcontainer image:

- Create @zookanalytics/keystone-workflows package with:
  - bmad-story.yaml: Single story workflow (dev → review → verify → commit)
  - bmad-epic.yaml: Epic iterator using sprint-status.yaml
  - bmad-epic-status.yaml: Epic iterator using BMAD workflow-status
  - Default keystone config with providers and engine allowlist
  - Postinstall script for symlinks to ~/.keystone/workflows/

- Update Dockerfile to:
  - Install bun runtime (required for keystone-cli)
  - Install keystone-cli from ZookAnalytics fork
  - Copy and run keystone-workflows postinstall

- Add container scripts:
  - update-keystone.sh: Auto-update packages with graceful fallback
  - devcontainer-sanity-check.sh: Extensible health check

- Update post-create.sh with new steps (6/11 and 10/11)

- Include tech specs for implementation reference

Author: johnzook

docs/implementation/tech-spec-keystone-bmad-workflows.md

@@ -112,6 +112,19 @@ RUN sh -c "$(wget -O- https://github.com/deluan/zsh-in-docker/releases/download/
 # Setup pnpm
 RUN pnpm setup
 
+# Install bun (required for keystone-cli)
+# Must run as node user to install to ~/.bun
+RUN curl -fsSL https://bun.sh/install | bash
+ENV BUN_INSTALL="/home/node/.bun"
+ENV PATH="$BUN_INSTALL/bin:$PATH"
+
+# Install keystone-cli globally via bun (must run as node user for PATH)
+RUN bun install -g github:ZookAnalytics/keystone-cli
+
+# Copy keystone-workflows package and run postinstall to set up symlinks and config
+COPY --chown=node:node packages/keystone-workflows /home/node/.local/lib/keystone-workflows
+RUN /home/node/.local/lib/keystone-workflows/scripts/postinstall.sh
+
 USER root
 
 # Copy configuration files
@@ -136,6 +149,8 @@ COPY image/scripts/setup-instance-isolation.sh /usr/local/bin/
 COPY image/scripts/setup-claude-auth-sharing.sh /usr/local/bin/
 COPY image/scripts/search-history.sh /usr/local/bin/
 COPY image/scripts/fix-shared-data-permissions.sh /usr/local/bin/
+COPY image/scripts/update-keystone.sh /usr/local/bin/
+COPY image/scripts/devcontainer-sanity-check.sh /usr/local/bin/
 
 # Make scripts executable and configure sudo
 RUN chmod 755 /usr/local/bin/init-firewall.sh && \
@@ -154,6 +169,8 @@ RUN chmod 755 /usr/local/bin/init-firewall.sh && \
   chmod 755 /usr/local/bin/setup-claude-auth-sharing.sh && \
   chmod 755 /usr/local/bin/search-history.sh && \
   chmod 755 /usr/local/bin/fix-shared-data-permissions.sh && \
+  chmod 755 /usr/local/bin/update-keystone.sh && \
+  chmod 755 /usr/local/bin/devcontainer-sanity-check.sh && \
   echo "node ALL=(root) NOPASSWD: /usr/local/bin/init-firewall.sh" > /etc/sudoers.d/node-commands && \
   echo "node ALL=(root) NOPASSWD: /usr/local/bin/assemble-managed-settings.sh" >> /etc/sudoers.d/node-commands && \
   echo "node ALL=(root) NOPASSWD: /usr/local/bin/fix-node-modules-ownership.sh" >> /etc/sudoers.d/node-commands && \

docs/implementation/tech-spec-keystone-devcontainer-integration.md

@@ -0,0 +1,43 @@
+#!/bin/bash
+# DevContainer sanity check - extensible script verifying container expectations
+# Add checks as container capabilities grow
+set -u  # Fail on undefined variables
+
+PASS=0
+FAIL=0
+
+check() {
+  if eval "$2" > /dev/null 2>&1; then
+    echo "✓ $1"
+    PASS=$((PASS + 1))
+  else
+    echo "✗ $1"
+    FAIL=$((FAIL + 1))
+  fi
+}
+
+echo "Running DevContainer sanity checks..."
+echo "---"
+
+# Core runtimes
+check "bun runtime" "bun --version"
+check "node runtime" "node --version"
+check "pnpm runtime" "pnpm --version"
+
+# Keystone
+check "keystone binary" "keystone --version"
+check "keystone workflows exist" "ls ~/.keystone/workflows/bmad-*.yaml"
+check "keystone workflow discovery" "keystone run --list 2>/dev/null | grep -q bmad"
+check "keystone config exists" "test -f ~/.config/keystone/config.yaml"
+
+# AI CLIs
+check "claude cli" "command -v claude"
+check "gemini cli" "command -v gemini"
+
+# DevContainer tools
+check "git available" "git --version"
+check "gh cli available" "gh --version"
+
+echo "---"
+echo "Passed: $PASS, Failed: $FAIL"
+[ $FAIL -eq 0 ]

image/Dockerfile

@@ -17,13 +17,13 @@ echo "==============================================="
 
 # Step 1: Assemble Claude Code managed settings
 echo ""
-echo "[1/9] Assembling Claude Code managed settings..."
+echo "[1/11] Assembling Claude Code managed settings..."
 sudo /usr/local/bin/assemble-managed-settings.sh
 echo "✓ Managed settings assembled"
 
 # Step 2: DevPod instance isolation (if applicable)
 echo ""
-echo "[2/9] Checking for DevPod instance isolation..."
+echo "[2/11] Checking for DevPod instance isolation..."
 
 # Fix shared-data volume permissions if needed (Docker creates volumes as root)
 if [ -n "${SHARED_DATA_DIR:-}" ] && [ -d "$SHARED_DATA_DIR" ] && [ ! -w "$SHARED_DATA_DIR" ]; then
@@ -59,19 +59,19 @@ fi
 
 # Step 3: Check for package updates (daily)
 echo ""
-echo "[3/9] Checking for package updates..."
+echo "[3/11] Checking for package updates..."
 /usr/local/bin/check-daily-updates.sh
 echo "✓ Package update check complete"
 
 # Step 4: Fix node_modules ownership
 echo ""
-echo "[4/9] Fixing node_modules ownership..."
+echo "[4/11] Fixing node_modules ownership..."
 sudo /usr/local/bin/fix-node-modules-ownership.sh
 echo "✓ Node modules ownership fixed"
 
 # Step 5: Install CLI tools
 echo ""
-echo "[5/9] Installing CLI tools..."
+echo "[5/11] Installing CLI tools..."
 
 # Install Claude Code via official installer (https://claude.ai/install.sh)
 # Security note: Piping to bash is the official install method. The script is served
@@ -106,26 +106,41 @@ pnpm install -g "@google/gemini-cli@${GEMINI_CLI_VERSION}"
 
 echo "✓ CLI tools installed"
 
-# Step 6: Start dnsmasq for DNS logging
+# Step 6: Update keystone packages
 echo ""
-echo "[6/9] Starting dnsmasq DNS forwarder..."
+echo "[6/11] Updating keystone packages..."
+/usr/local/bin/update-keystone.sh
+echo "✓ Keystone packages updated"
+
+# Step 7: Start dnsmasq for DNS logging
+echo ""
+echo "[7/11] Starting dnsmasq DNS forwarder..."
 sudo /usr/local/bin/start-dnsmasq.sh
 
-# Step 7: Start ulogd for firewall logging
+# Step 8: Start ulogd for firewall logging
 echo ""
-echo "[7/9] Starting ulogd firewall logger..."
+echo "[8/11] Starting ulogd firewall logger..."
 sudo /usr/local/bin/start-ulogd.sh
 echo "✓ ulogd started"
 
-# Step 8: Initialize firewall
+# Step 9: Initialize firewall
 echo ""
-echo "[8/9] Initializing firewall rules..."
+echo "[9/11] Initializing firewall rules..."
 sudo /usr/local/bin/init-firewall.sh
 echo "✓ Firewall initialized"
 
-# Step 9: Run project-specific post-create if it exists
+# Step 10: Run sanity check
+echo ""
+echo "[10/11] Running sanity check..."
+if /usr/local/bin/devcontainer-sanity-check.sh; then
+  echo "✓ Sanity check passed"
+else
+  echo "⚠ Sanity check reported failures (see above) - container continues"
+fi
+
+# Step 11: Run project-specific post-create if it exists
 echo ""
-echo "[9/9] Running project-specific setup..."
+echo "[11/11] Running project-specific setup..."
 PROJECT_POST_CREATE="$WORKSPACE_ROOT/.devcontainer/post-create-project.sh"
 if [ -f "$PROJECT_POST_CREATE" ]; then
     echo "Running $PROJECT_POST_CREATE..."

image/scripts/devcontainer-sanity-check.sh

@@ -0,0 +1,36 @@
+#!/bin/bash
+set -euo pipefail
+
+# Track update failures (non-fatal - container continues with existing versions)
+UPDATE_FAILURES=0
+
+echo "Updating keystone packages..."
+# Note: bun global installs may change symlink targets from ~/.local/lib to ~/.bun/install/global
+# This is acceptable - postinstall.sh uses ln -sf to cleanly overwrite existing symlinks
+
+if ! bun install -g github:ZookAnalytics/keystone-cli; then
+  echo "⚠ keystone-cli update failed, using existing version"
+  UPDATE_FAILURES=$((UPDATE_FAILURES + 1))
+fi
+
+if ! bun install -g github:ZookAnalytics/claude-devcontainer#packages/keystone-workflows; then
+  echo "⚠ keystone-workflows update failed, using existing version"
+  UPDATE_FAILURES=$((UPDATE_FAILURES + 1))
+fi
+
+# Log versions for debugging
+echo "---"
+echo "keystone-cli: $(keystone --version 2>/dev/null || echo 'not installed')"
+# Workflows version from package.json (if installed locally) or symlink target
+WORKFLOWS_PKG="$HOME/.local/lib/keystone-workflows/package.json"
+if [ -f "$WORKFLOWS_PKG" ]; then
+  echo "keystone-workflows: $(grep '"version"' "$WORKFLOWS_PKG" | head -1 | sed 's/.*: *"\([^"]*\)".*/\1/')"
+else
+  echo "keystone-workflows: (installed via bun global)"
+fi
+echo "workflows path: $(ls -la ~/.keystone/workflows/*.yaml 2>/dev/null | head -1 || echo 'not found')"
+
+# Report update status (exit 0 for graceful degradation per AC5)
+if [ "$UPDATE_FAILURES" -gt 0 ]; then
+  echo "⚠ $UPDATE_FAILURES update(s) failed - using existing versions"
+fi

image/scripts/post-create.sh

@@ -0,0 +1,51 @@
+# Keystone Configuration
+# Default configuration for BMAD workflows in claude-devcontainer
+default_provider: openai
+
+providers:
+  # Install with: npm install @ai-sdk/openai @ai-sdk/anthropic
+  openai:
+    package: "@ai-sdk/openai"
+    api_key_env: OPENAI_API_KEY
+    default_model: gpt-4o
+  anthropic:
+    package: "@ai-sdk/anthropic"
+    api_key_env: ANTHROPIC_API_KEY
+    default_model: claude-sonnet-4-20250514
+
+  # Example: OpenAI-compatible provider (Groq)
+  # groq:
+  #   package: "@ai-sdk/openai"
+  #   base_url: https://api.groq.com/openai/v1
+  #   api_key_env: GROQ_API_KEY
+  #   default_model: llama-3.3-70b-versatile
+
+model_mappings:
+  "gpt-*": openai
+  "claude-*": anthropic
+  "o1-*": openai
+
+# mcp_servers:
+#   filesystem:
+#     command: npx
+#     args: ["-y", "@modelcontextprotocol/server-filesystem", "."]
+
+engines:
+  allowlist:
+    claude:
+      command: claude
+      version: "*"
+      versionArgs: ["--version"]
+    gemini:
+      command: gemini
+      version: "*"
+      versionArgs: ["--version"]
+
+defaults:
+  timeout: 900000  # 15 minutes for long CLI operations
+
+storage:
+  retention_days: 30
+
+expression:
+  strict: false

image/scripts/update-keystone.sh

@@ -0,0 +1,25 @@
+{
+  "name": "@zookanalytics/keystone-workflows",
+  "version": "0.1.0",
+  "description": "BMAD keystone workflows for claude-devcontainer",
+  "files": [
+    "workflows/",
+    "config/",
+    "scripts/"
+  ],
+  "scripts": {
+    "postinstall": "./scripts/postinstall.sh"
+  },
+  "keywords": [
+    "keystone",
+    "bmad",
+    "workflows",
+    "claude-devcontainer"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/zookanalytics/claude-devcontainer.git",
+    "directory": "packages/keystone-workflows"
+  }
+}

packages/keystone-workflows/config/keystone-config.yaml

@@ -0,0 +1,46 @@
+#!/bin/bash
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PACKAGE_DIR="$SCRIPT_DIR/.."
+WORKFLOWS_DIR="$PACKAGE_DIR/workflows"
+CONFIG_DIR="$PACKAGE_DIR/config"
+
+# Validate package structure
+if [ ! -d "$WORKFLOWS_DIR" ]; then
+  echo "ERROR: Workflows directory not found at $WORKFLOWS_DIR" >&2
+  exit 1
+fi
+if [ ! -d "$CONFIG_DIR" ]; then
+  echo "ERROR: Config directory not found at $CONFIG_DIR" >&2
+  exit 1
+fi
+
+# 1. Install workflows to ~/.keystone/workflows/
+# Uses ln -sf to force-overwrite existing symlinks (handles updates cleanly)
+WORKFLOW_TARGET="$HOME/.keystone/workflows"
+mkdir -p "$WORKFLOW_TARGET"
+WORKFLOW_COUNT=0
+for f in "$WORKFLOWS_DIR"/*.yaml; do
+  [ -e "$f" ] || continue  # Handle no matches
+  ln -sf "$f" "$WORKFLOW_TARGET/$(basename "$f")"  # -f overwrites existing
+  WORKFLOW_COUNT=$((WORKFLOW_COUNT + 1))
+done
+if [ "$WORKFLOW_COUNT" -eq 0 ]; then
+  echo "WARNING: No workflow files found in $WORKFLOWS_DIR" >&2
+else
+  echo "Keystone workflows installed to $WORKFLOW_TARGET ($WORKFLOW_COUNT files)"
+fi
+
+# 2. Install default config to ~/.config/keystone/ (only if not exists)
+CONFIG_TARGET="$HOME/.config/keystone"
+if [ ! -f "$CONFIG_TARGET/config.yaml" ]; then
+  mkdir -p "$CONFIG_TARGET"
+  if [ -f "$CONFIG_DIR/keystone-config.yaml" ]; then
+    cp "$CONFIG_DIR/keystone-config.yaml" "$CONFIG_TARGET/config.yaml"
+    echo "Default keystone config installed to $CONFIG_TARGET/config.yaml"
+  else
+    echo "WARNING: Default config not found at $CONFIG_DIR/keystone-config.yaml" >&2
+  fi
+else
+  echo "Keystone config already exists at $CONFIG_TARGET/config.yaml (skipped)"
+fi