feat: interactive onboarding wizard (openclaw-style clack UI)

Author: codejunkie99

Formula/agentic-stack.rb

@@ -8,7 +8,9 @@ class AgenticStack < Formula
 
   def install
     # install the brain + adapters alongside install.sh so relative paths hold
-    pkgshare.install ".agent", "adapters", "install.sh"
+    pkgshare.install ".agent", "adapters", "install.sh",
+                     "onboard.py", "onboard_ui.py", "onboard_widgets.py",
+                     "onboard_render.py", "onboard_write.py"
 
     # wrapper so `agentic-stack cursor` works from anywhere
     (bin/"agentic-stack").write <<~EOS
@@ -20,5 +22,9 @@ def install
   test do
     output = shell_output("#{bin}/agentic-stack 2>&1", 2)
     assert_match "usage", output
+    # Wizard --yes must write PREFERENCES.md into a temp project dir
+    (testpath/".agent/memory/personal").mkpath
+    system "#{bin}/agentic-stack", "claude-code", testpath.to_s, "--yes"
+    assert_predicate testpath/".agent/memory/personal/PREFERENCES.md", :exist?
   end
 end

install.sh

@@ -1,8 +1,10 @@
 #!/usr/bin/env bash
-# install.sh — copy an adapter into the consuming project
-# Usage: ./install.sh <adapter-name> [target-dir]
-#   adapter-name: claude-code | cursor | windsurf | opencode | openclient | hermes | standalone-python
-#   target-dir:   where your consuming project lives (default: current dir)
+# install.sh — copy an adapter into the consuming project, then run the onboarding wizard
+# Usage: ./install.sh <adapter-name> [target-dir] [--yes] [--reconfigure]
+#   adapter-name:  claude-code | cursor | windsurf | opencode | openclient | hermes | standalone-python
+#   target-dir:    where your project lives (default: current dir)
+#   --yes          accept all wizard defaults without prompting (safe for CI)
+#   --reconfigure  re-run the wizard even if PREFERENCES.md is already filled
 set -euo pipefail
 
 ADAPTER="${1:-}"
@@ -15,6 +17,16 @@ if [[ -z "$ADAPTER" ]]; then
   exit 2
 fi
 
+# Collect wizard flags from any position in $@
+WIZARD_FLAGS=""
+for arg in "$@"; do
+  case "$arg" in
+    --yes|-y)        WIZARD_FLAGS="$WIZARD_FLAGS --yes" ;;
+    --reconfigure)   WIZARD_FLAGS="$WIZARD_FLAGS --reconfigure" ;;
+    --force)         WIZARD_FLAGS="$WIZARD_FLAGS --force" ;;
+  esac
+done
+
 SRC="$HERE/adapters/$ADAPTER"
 if [[ ! -d "$SRC" ]]; then
   echo "error: adapter '$ADAPTER' not found at $SRC" >&2
@@ -23,7 +35,7 @@ fi
 
 echo "installing '$ADAPTER' into $TARGET"
 
-# copy .agent/ brain if the target doesn't have one yet
+# Copy .agent/ brain only if the target does not already have one
 if [[ ! -d "$TARGET/.agent" ]]; then
   cp -R "$HERE/.agent" "$TARGET/.agent"
   echo "  + .agent/ (portable brain)"
@@ -61,4 +73,18 @@ case "$ADAPTER" in
     ;;
 esac
 
-echo "done. see adapters/$ADAPTER/README.md for next steps."
+echo "done."
+
+# ── Onboarding wizard ──────────────────────────────────────────────────────
+ONBOARD_PY="$HERE/onboard.py"
+if [[ ! -f "$ONBOARD_PY" ]]; then
+  echo "tip: customize $TARGET/$( echo '.agent/memory/personal/PREFERENCES.md' ) with your conventions."
+  exit 0
+fi
+if ! command -v python3 &>/dev/null; then
+  echo "tip: python3 not found — edit .agent/memory/personal/PREFERENCES.md manually."
+  exit 0
+fi
+
+# exec replaces this shell; no return needed
+exec python3 "$ONBOARD_PY" "$TARGET" $WIZARD_FLAGS

onboard.py

@@ -0,0 +1,95 @@
+#!/usr/bin/env python3
+"""agentic-stack onboarding wizard — populates .agent/memory/personal/PREFERENCES.md."""
+import sys, os
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+from onboard_ui      import print_banner, intro, note, outro, step_done, BAR, R, MUTED, GREEN, PURPLE, WHITE, B
+from onboard_widgets import ask_text, ask_select, ask_confirm
+from onboard_render  import render
+from onboard_write   import write_prefs, is_customized, REL
+
+_CI_VARS = ("CI", "GITHUB_ACTIONS", "CIRCLECI", "BUILDKITE", "JENKINS_URL", "TRAVIS")
+
+
+def _is_ci():
+    if not sys.stdin.isatty(): return True
+    return any(os.environ.get(v) for v in _CI_VARS)
+
+
+def _parse_args():
+    args  = sys.argv[1:]
+    flags = {a for a in args if a.startswith("-")}
+    pos   = [a for a in args if not a.startswith("-")]
+    return (
+        pos[0] if pos else os.getcwd(),
+        "--yes" in flags or "-y" in flags,
+        "--force" in flags,
+        "--reconfigure" in flags,
+    )
+
+
+def _wizard(target, force):
+    """Run the interactive Q&A. Returns answers dict, or None to abort."""
+    if is_customized(target) and not force:
+        note("Already configured",
+             ["PREFERENCES.md already has custom content.",
+              "Pass --reconfigure to update it."])
+        return None
+
+    intro("agentic-stack setup")
+    note("What this does", [
+        "Fills .agent/memory/personal/PREFERENCES.md —",
+        "the FIRST file your AI reads every session.",
+        "Takes about 30 seconds.",
+    ])
+
+    a = {}
+    a["name"]      = ask_text("What should I call you?",
+                               hint="press Enter to skip")
+    a["languages"] = ask_text("Primary language(s)?",
+                               default="unspecified",
+                               hint="e.g. TypeScript, Python, Rust")
+    a["style"]     = ask_select("Explanation style?",
+                                 ["concise", "detailed"])
+    a["tests"]     = ask_select("Test strategy?",
+                                 ["test-after", "tdd", "minimal"])
+    a["commits"]   = ask_select("Commit message style?",
+                                 ["conventional commits", "free-form", "emoji"])
+    a["review"]    = ask_select("Code review depth?",
+                                 ["critical issues only", "everything"])
+    return a
+
+
+def main():
+    target, yes, force, reconf = _parse_args()
+
+    if _is_ci() and not yes:
+        print(f"[onboard] non-interactive — skipping wizard (edit {REL} manually)")
+        sys.exit(0)
+
+    print_banner()
+
+    if yes:
+        path = write_prefs(target, render({}), force=True)
+        print(f"{GREEN}◆{R}  {WHITE}{B}PREFERENCES.md{R} written with defaults")
+        print(f"{MUTED}   {path}{R}\n")
+        sys.exit(0)
+
+    try:
+        answers = _wizard(target, force=reconf)
+        if answers is None:
+            sys.exit(0)
+        path = write_prefs(target, render(answers), force=reconf)
+        outro([
+            f"PREFERENCES.md written",
+            f"{path}",
+            "Edit it any time — your AI re-reads it every session.",
+            "Tip: git add .agent/memory/ to track your brain.",
+        ])
+    except KeyboardInterrupt:
+        print(f"\n\n{MUTED}  Setup cancelled.{R}\n")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

onboard_render.py

@@ -0,0 +1,65 @@
+"""Turn collected answers into a PREFERENCES.md string. Pure function, no I/O."""
+import datetime
+
+VERSION = "0.4.0"
+
+_DEFAULTS = {
+    "name":      "",
+    "languages": "unspecified",
+    "style":     "concise",
+    "tests":     "test-after",
+    "commits":   "conventional commits",
+    "review":    "critical issues only",
+}
+
+
+def _section(title, bullets):
+    """Return a markdown section string, omitting any blank bullets."""
+    kept = [f"- {b}" for b in bullets if b and b != "unspecified"]
+    if not kept:
+        kept = ["- _(edit me)_"]
+    return f"## {title}\n" + "\n".join(kept)
+
+
+def render(raw: dict) -> str:
+    a = {**_DEFAULTS, **{k: v for k, v in raw.items() if v}}
+    now = datetime.datetime.now().isoformat(timespec="seconds")
+
+    identity = _section("Identity", [
+        f"Name: {a['name']}" if a["name"] else "",
+    ])
+
+    code = _section("Code style", [
+        f"Language(s): {a['languages']}",
+        f"Explanations: {a['style']}",
+    ])
+
+    workflow = _section("Workflow", [
+        f"Test strategy: {a['tests']}",
+        f"Commit style: {a['commits']}",
+    ])
+
+    comms = _section("Communication", [
+        f"Review depth: {a['review']}",
+        "Tone: direct, skip pleasantries",
+        "Surface tradeoffs: always",
+    ])
+
+    constraints = _section("Constraints", [
+        "_(edit me: primary stack, deployment targets, off-limits patterns)_",
+    ])
+
+    # Only include Identity if a name was given
+    sections = ([identity] if a["name"] else []) + [code, workflow, comms, constraints]
+    body = "\n\n".join(sections)
+
+    return f"""\
+# Personal Preferences
+<!-- generated by agentic-stack onboard v{VERSION} on {now} -->
+<!-- re-run:  agentic-stack <harness> --reconfigure  to update -->
+
+> **This file is yours.** Edit it any time — it's the first thing your AI
+> reads at the start of every session.
+
+{body}
+"""

onboard_ui.py

@@ -0,0 +1,79 @@
+"""ANSI palette, block-char banner, and clack-style layout atoms (stdlib only)."""
+import sys, os, shutil, tty, termios
+
+# ── Palette ───────────────────────────────────────────────────────────────
+def _e(*c): return f"\x1b[{';'.join(map(str,c))}m"
+def _hex(h, bg=False):
+    h = h.lstrip("#"); r,g,b = int(h[:2],16), int(h[2:4],16), int(h[4:6],16)
+    return f"\x1b[{'48' if bg else '38'};2;{r};{g};{b}m"
+
+R  = _e(0);  B  = _e(1);  D  = _e(2)
+PURPLE = _hex("#BF5AF2"); BLUE   = _hex("#0A84FF")
+GREEN  = _hex("#30D158"); ORANGE = _hex("#FF9F0A")
+MUTED  = _hex("#636366"); WHITE  = _hex("#F5F5F7")
+
+HIDE = "\x1b[?25l"; SHOW = "\x1b[?25h"
+CLR  = "\x1b[2K\r"; UP   = "\x1b[1A"
+
+# ── Banner ────────────────────────────────────────────────────────────────
+# 2-row pixel font spells "AGENTIC STACK"
+_L1 = "  ▄▀█ █▀▀ █▀▀ █▄░█ ▀█▀ █ █▀▀  █▀ ▀█▀ ▄▀█ █▀▀ █▄▀ "
+_L2 = "  █▀█ █▄█ ██▄ █░▀█ ░█░ █ █▄▄  ▄█ ░█░ █▀█ █▄▄ █░█ "
+_T  = "  your portable brain  ·  harness-agnostic AI memory  ·  v0.4.0"
+
+def _cc(c):
+    if c == "█": return f"{PURPLE}{B}{c}{R}"
+    if c in "▀▄": return f"{BLUE}{c}{R}"
+    return f"{MUTED}{c}{R}"
+
+def print_banner():
+    w = shutil.get_terminal_size((80, 24)).columns
+    print()
+    print("".join(_cc(c) for c in _L1))
+    print("".join(_cc(c) for c in _L2))
+    print(f"\n{MUTED}{'':>{(w - len(_T.strip()))//2}}{_T.strip()}{R}\n")
+
+# ── Layout atoms ──────────────────────────────────────────────────────────
+BAR = f"{MUTED}│{R}"
+
+def intro(title):
+    print(f"\n{PURPLE}◇{R}  {B}{WHITE}{title}{R}")
+    print(BAR)
+
+def note(title, lines):
+    print(f"{BAR}\n{BAR}  {B}{ORANGE}{title}{R}")
+    for ln in lines:
+        print(f"{BAR}  {MUTED}{ln}{R}")
+    print(BAR)
+
+def step_done(label, value):
+    v = f"{WHITE}{B}{value}{R}" if value else f"{MUTED}(skipped){R}"
+    print(f"{PURPLE}◆{R}  {D}{label}{R}  {MUTED}…{R}  {v}")
+
+def outro(lines):
+    print(BAR)
+    for i, ln in enumerate(lines):
+        icon = f"{GREEN}◆{R}" if i == 0 else f"{MUTED}│{R}"
+        print(f"{icon}  {WHITE}{ln}{R}")
+    print(f"{MUTED}└{R}\n")
+
+# ── Raw key reader ────────────────────────────────────────────────────────
+def _getch():
+    fd = sys.stdin.fileno()
+    old = termios.tcgetattr(fd)
+    try:
+        tty.setraw(fd)
+        return sys.stdin.buffer.read(1).decode("utf-8", errors="replace")
+    finally:
+        termios.tcsetattr(fd, termios.TCSADRAIN, old)
+
+def get_key():
+    ch = _getch()
+    if ch == "\x1b":
+        _getch()                          # consume '['
+        c2 = _getch()
+        return {"A": "UP", "B": "DOWN", "C": "RIGHT", "D": "LEFT"}.get(c2, "ESC")
+    if ch in "\r\n":  return "ENTER"
+    if ch == "\x03":  raise KeyboardInterrupt
+    if ch == "\x7f":  return "BACKSPACE"
+    return ch