From 3d252b6d3c5cd84e7f1f0b2976a775dfe7b56e3c Mon Sep 17 00:00:00 2001 From: kagura-agent Date: Sat, 9 May 2026 19:28:56 +0800 Subject: [PATCH 1/2] docs: update getting-started to reflect brew install + CLI workflow The getting-started guide still referenced the old git-clone + cp -R workflow and ./install.sh directly. Update it to match the current README quickstart: - Lead with brew tap/install as the recommended path - Use 'agentic-stack ' CLI commands instead of ./install.sh - Add 'Managing your project' section with dashboard, doctor, upgrade, sync-manifest, add/remove subcommands - Add 'Keeping up to date' section covering brew upgrade + safe project upgrade flow - Note that onboarding wizard pre-populates PREFERENCES.md - Keep clone-based install as an alternative for non-Homebrew users - Keep Windows PowerShell instructions unchanged --- docs/getting-started.md | 77 +++++++++++++++++++++++++++++++++++------ 1 file changed, 66 insertions(+), 11 deletions(-) diff --git a/docs/getting-started.md b/docs/getting-started.md index bdde340..d854de6 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -1,32 +1,50 @@ # Getting Started -## 1. Clone or drop `.agent/` into your project +## 1. Install agentic-stack + +### macOS / Linux (recommended) ```bash -# new project -git clone https://github.com//agentic-stack.git my-project -cd my-project +brew tap codejunkie99/agentic-stack https://github.com/codejunkie99/agentic-stack +brew install agentic-stack +``` + +### Windows (PowerShell) + +```powershell +git clone https://github.com/codejunkie99/agentic-stack.git +cd agentic-stack +.\install.ps1 claude-code C:\path\to\your-project +``` + +### Clone install (any platform) -# or add to an existing project -cp -R /path/to/agentic-stack/.agent ./ -cp /path/to/agentic-stack/install.sh ./ +If you prefer not to use Homebrew: + +```bash +git clone https://github.com/codejunkie99/agentic-stack.git +cd agentic-stack && ./install.sh claude-code ``` ## 2. Pick your harness ```bash -./install.sh claude-code # or cursor, windsurf, opencode, - # openclaw, hermes, pi, codex, - # standalone-python, antigravity +cd your-project +agentic-stack claude-code +# or: cursor | windsurf | opencode | openclaw | hermes | pi | codex | standalone-python | antigravity ``` +The onboarding wizard runs automatically, populating +`.agent/memory/personal/PREFERENCES.md` and `.agent/memory/.features.json`. + Each adapter has its own `README.md` under `adapters//`. ## 3. Customize `PREFERENCES.md` Open `.agent/memory/personal/PREFERENCES.md` and fill in 5–10 lines about your code style, workflow, and constraints. This is the one file every -user should customize on day one. +user should customize on day one. The onboarding wizard pre-populates it, +but you can always edit it later. ## 4. Run the dream cycle on a schedule @@ -42,6 +60,27 @@ Open your harness and ask it anything. The first few days it will feel stateless. After ~2 weeks you'll notice it checking past lessons, logging failures with reflection, and (if you let it) proposing skill rewrites. +## Managing your project + +After the initial setup, use verb-style subcommands: + +```bash +agentic-stack dashboard # TUI dashboard: health, verify, memory, team, skills +agentic-stack status # one-screen view: which adapters, brain stats +agentic-stack doctor # read-only audit; green / yellow / red per adapter +agentic-stack upgrade --dry-run # preview safe .agent infrastructure refresh +agentic-stack upgrade --yes # apply latest harness/memory/tools + new skills +agentic-stack sync-manifest # rebuild .agent/skills/_manifest.jsonl from SKILL.md +``` + +Adding or removing adapters: + +```bash +agentic-stack add cursor # add a second adapter alongside Claude Code +agentic-stack remove cursor # confirm prompt + delete +agentic-stack manage # interactive TUI for add/remove/audit +``` + ## Optional: add a visual system with `DESIGN.md` If your project has UI, drop a Google Stitch-style `DESIGN.md` file in the @@ -55,7 +94,23 @@ When Node tooling is available, agents can validate the file with: npx @google/design.md lint DESIGN.md ``` +## Keeping up to date + +```bash +brew update && brew upgrade agentic-stack +cd your-project +agentic-stack upgrade --dry-run # preview changes +agentic-stack upgrade --yes # apply (safe — won't overwrite your memory or config) +``` + +The upgrade command refreshes skeleton-owned `.agent` infrastructure +(harness scripts, top-level memory/tools Python files, skill index, and new +skill directories) but never overwrites `CLAUDE.md`, `.claude/settings.json`, +personal/semantic/episodic/working memory, candidates, or existing skill +directories. + ## Verify the wiring + ```bash python3 .agent/tools/budget_tracker.py "commit and push" # tokens_used, chars, budget, headroom From ec3ecf9ee78e6ab3486f9aa503d9af8950faedd8 Mon Sep 17 00:00:00 2001 From: codejunkie99 Date: Sat, 9 May 2026 23:48:22 +0530 Subject: [PATCH 2/2] docs: harden getting started install flow --- docs/getting-started.md | 66 ++++++++++++++++++++++++++++++++++------- onboard_ui.py | 7 ++++- test_onboard_ui.py | 7 +++++ 3 files changed, 68 insertions(+), 12 deletions(-) create mode 100644 test_onboard_ui.py diff --git a/docs/getting-started.md b/docs/getting-started.md index d854de6..4e5fc33 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -2,38 +2,51 @@ ## 1. Install agentic-stack -### macOS / Linux (recommended) +### macOS / Linux with Homebrew (recommended) ```bash brew tap codejunkie99/agentic-stack https://github.com/codejunkie99/agentic-stack brew install agentic-stack ``` -### Windows (PowerShell) +This installs the `agentic-stack` command. -```powershell +### Source checkout (no Homebrew) + +If you prefer not to use Homebrew, clone the repo and run `install.sh` +against the project you want to wire: + +```bash git clone https://github.com/codejunkie99/agentic-stack.git cd agentic-stack -.\install.ps1 claude-code C:\path\to\your-project +./install.sh claude-code /path/to/your-project ``` -### Clone install (any platform) +This path does not install a global `agentic-stack` command. Keep the clone +around and run future management commands through `./install.sh`. -If you prefer not to use Homebrew: +### Windows (PowerShell) -```bash +```powershell git clone https://github.com/codejunkie99/agentic-stack.git -cd agentic-stack && ./install.sh claude-code +cd agentic-stack +.\install.ps1 claude-code C:\path\to\your-project ``` ## 2. Pick your harness +If you installed with Homebrew, run the CLI from your project root: + ```bash cd your-project agentic-stack claude-code # or: cursor | windsurf | opencode | openclaw | hermes | pi | codex | standalone-python | antigravity ``` +If you are using a source checkout, the install command above already picked +the harness. To add another adapter later, run +`./install.sh add /path/to/your-project` from the clone. + The onboarding wizard runs automatically, populating `.agent/memory/personal/PREFERENCES.md` and `.agent/memory/.features.json`. @@ -62,7 +75,8 @@ failures with reflection, and (if you let it) proposing skill rewrites. ## Managing your project -After the initial setup, use verb-style subcommands: +After the initial setup, Homebrew users can run verb-style subcommands from +the project root: ```bash agentic-stack dashboard # TUI dashboard: health, verify, memory, team, skills @@ -73,7 +87,20 @@ agentic-stack upgrade --yes # apply latest harness/memory/tools + new skil agentic-stack sync-manifest # rebuild .agent/skills/_manifest.jsonl from SKILL.md ``` -Adding or removing adapters: +Source checkout users can run the same verbs through the clone: + +```bash +./install.sh dashboard /path/to/your-project +./install.sh status /path/to/your-project +./install.sh doctor /path/to/your-project +./install.sh upgrade /path/to/your-project --dry-run +./install.sh upgrade /path/to/your-project --yes +./install.sh sync-manifest /path/to/your-project +``` + +PowerShell users can run the same verbs through `.\install.ps1`. + +Adding or removing adapters with Homebrew: ```bash agentic-stack add cursor # add a second adapter alongside Claude Code @@ -81,6 +108,14 @@ agentic-stack remove cursor # confirm prompt + delete agentic-stack manage # interactive TUI for add/remove/audit ``` +Source checkout equivalents: + +```bash +./install.sh add cursor /path/to/your-project +./install.sh remove cursor /path/to/your-project +./install.sh manage /path/to/your-project +``` + ## Optional: add a visual system with `DESIGN.md` If your project has UI, drop a Google Stitch-style `DESIGN.md` file in the @@ -100,7 +135,16 @@ npx @google/design.md lint DESIGN.md brew update && brew upgrade agentic-stack cd your-project agentic-stack upgrade --dry-run # preview changes -agentic-stack upgrade --yes # apply (safe — won't overwrite your memory or config) +agentic-stack upgrade --yes # apply; won't overwrite your memory or config +``` + +Source checkout users should update the clone first: + +```bash +cd /path/to/agentic-stack +git pull --ff-only +./install.sh upgrade /path/to/your-project --dry-run +./install.sh upgrade /path/to/your-project --yes ``` The upgrade command refreshes skeleton-owned `.agent` infrastructure diff --git a/onboard_ui.py b/onboard_ui.py index b123f33..6e8f388 100644 --- a/onboard_ui.py +++ b/onboard_ui.py @@ -1,6 +1,11 @@ """ANSI palette, block-char banner, and clack-style layout atoms (stdlib only).""" import sys, os, shutil +try: + from harness_manager import __version__ as _AGENTIC_STACK_VERSION +except Exception: + _AGENTIC_STACK_VERSION = "unknown" + _WIN = sys.platform == "win32" if _WIN: import msvcrt @@ -25,7 +30,7 @@ def _hex(h, bg=False): # 2-row pixel font spells "AGENTIC STACK" _L1 = " ▄▀█ █▀▀ █▀▀ █▄░█ ▀█▀ █ █▀▀ █▀ ▀█▀ ▄▀█ █▀▀ █▄▀ " _L2 = " █▀█ █▄█ ██▄ █░▀█ ░█░ █ █▄▄ ▄█ ░█░ █▀█ █▄▄ █░█ " -_T = " your portable brain · harness-agnostic AI memory · v0.8.0" +_T = f" your portable brain · harness-agnostic AI memory · v{_AGENTIC_STACK_VERSION}" def _cc(c): if c == "█": return f"{PURPLE}{B}{c}{R}" diff --git a/test_onboard_ui.py b/test_onboard_ui.py new file mode 100644 index 0000000..dd1fa2f --- /dev/null +++ b/test_onboard_ui.py @@ -0,0 +1,7 @@ +from harness_manager import __version__ +import onboard_ui + + +def test_onboarding_banner_uses_package_version(): + assert f"v{__version__}" in onboard_ui._T + assert "v0.8.0" not in onboard_ui._T