Clean up workBenches base and devBench tooling #1
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,154 @@ | ||
| # Asynchronous Clarify Protocol | ||
|
|
||
| A custom clarify step for [GitHub Spec Kit](https://github.com/github/spec-kit) + | ||
| Claude Code. It fans question generation out across reviewer angles, logs the questions | ||
| to a file, and finishes clarify **automatically** once they are answered — no manual | ||
| re-running. | ||
|
|
||
| ## Why | ||
|
|
||
| Spec Kit's stock `/speckit.clarify` is synchronous: it asks, you answer, all in one | ||
| sitting. Real clarification has human latency — a domain expert may take a day to answer | ||
| a compliance question. This protocol decouples **question generation** (cheap, parallel, | ||
| done by AI) from **answering** (slow, human) from **application** (one edit to `spec.md`), | ||
| and uses a polling loop so the loop, not you, watches for completion. | ||
|
|
||
| ## The four files | ||
|
|
||
| | File | Role | | ||
| |------|------| | ||
| | `.claude/commands/openClarify.md` | Orchestrator. Resolves the feature dir, initializes the log, triggers the generation fan-out, registers the poll loop. Never answers questions. | | ||
| | `.claude/commands/openClarify-resume.md` | Poll tick. Reads the log and branches cheaply; only the all-answered tick edits `spec.md`. Enforces the critical-class human gate. | | ||
| | `templates/clarify-log.template.md` | The log schema: two top-of-file sentinels + per-question blocks. | | ||
| | `PROTOCOL.md` | This document. | | ||
|
|
||
| ## Data flow | ||
|
|
||
| ``` | ||
| /openClarify [feature-dir] | ||
| ├─ verify spec.md exists | ||
| ├─ init clarify-log.md from template (GENERATION: PENDING, CLARIFY: IN_PROGRESS) | ||
| ├─ workflow: fan out reviewer angles ──┐ | ||
| │ data-model ┐ │ each appends OPEN question blocks | ||
| │ edge-cases ┤ │ merge + dedupe, cap 25 | ||
| │ security-compliance ┤ │ then flip GENERATION: COMPLETE | ||
| │ testability ┤ │ | ||
| │ integration ┘ │ | ||
| └─ register /loop 10m /openClarify-resume <dir> | ||
|
|
||
| ... humans answer blocks in clarify-log.md over time ... | ||
|
|
||
| /openClarify-resume <dir> (every 10 min) | ||
| ├─ log missing? → no-op | ||
| ├─ CLARIFY: COMPLETE? → no-op, stop loop | ||
| ├─ GENERATION != COMPLETE → no-op (sentinel guard: no early firing) | ||
| ├─ any status: OPEN? → no-op (still waiting) | ||
| ├─ critical answered by architect-ai? → no-op (human escalation) | ||
| └─ all answered, criticals human-signed → edit spec.md, CLARIFY: COMPLETE, stop loop | ||
| ``` | ||
|
|
||
| ## The log schema | ||
|
|
||
| Two **sentinels** at the top of `clarify-log.md` are the entire coordination contract: | ||
|
|
||
| - `GENERATION: PENDING | COMPLETE` — set `COMPLETE` only when the fan-out has written | ||
| every question. Until then the poller refuses to act. | ||
| - `CLARIFY: IN_PROGRESS | COMPLETE` — set `COMPLETE` only after answers are applied to | ||
| `spec.md`. | ||
|
|
||
| Each question is a block: | ||
|
|
||
| ``` | ||
| ## Q3 | ||
| - id: q3 | ||
| - status: OPEN # OPEN | ANSWERED | ||
| - class: normal # normal | critical | ||
| - agent: security-compliance # which reviewer angle raised it | ||
| - question: How long is PHI retained after account deletion? | ||
| - answer: | ||
| - answered_by: # human | architect-ai | ||
| - ts: | ||
| ``` | ||
|
|
||
| ## Three design guarantees | ||
|
|
||
| 1. **Sentinel guard against early firing.** The poller treats `GENERATION: COMPLETE` as a | ||
| precondition. A log that is mid-generation can momentarily show "zero OPEN questions" | ||
| simply because no questions have been written yet — the guard stops the poller from | ||
| misreading that as "all answered" and prematurely editing `spec.md`. | ||
|
|
||
| 2. **Critical-class human escalation.** A `class: critical` question (clinical / regulated / | ||
| safety-impacting) answered by `architect-ai` does **not** clear. Completion blocks until | ||
| a human re-answers or confirms it. The AI can draft; only a human signature releases the | ||
| gate. | ||
|
|
||
| 3. **Cheap read-and-branch ticks.** Nearly every poll tick just greps the sentinels and a | ||
| handful of `status:` lines, then exits. Exactly one tick — the one that sees everything | ||
| answered and all criticals human-signed — does the expensive `spec.md` edit. Polling | ||
| every 10 minutes is therefore nearly free. | ||
|
|
||
| ## Relationship to stock `/speckit.clarify` — audit pass | ||
|
|
||
| This protocol **does the clarification work**, then stock `/speckit.clarify` runs **after** | ||
| as an **audit**, not as the primary clarifier. | ||
|
|
||
| Because `/openClarify-resume` writes answers in stock's canonical shape — a | ||
| `## Clarifications` section with `### Session YYYY-MM-DD` and `- Q: … → A: …` bullets, plus | ||
| the answer folded into the relevant spec section — a subsequent stock run sees those points | ||
| as already resolved. Stock decides what to ask by scanning **spec sections** against its | ||
| coverage taxonomy (Clear / Partial / Missing), so the folding in §3b is what actually makes | ||
| the audit quiet, not the log bullets. | ||
|
|
||
| **How to use the audit:** after our protocol marks `CLARIFY: COMPLETE`, run stock | ||
| `/speckit.clarify` (the `speckit-clarify` skill) a few times. | ||
|
|
||
| - **No new questions** → our five reviewer angles covered the spec to stock's standard. Proceed to `/speckit.plan`. | ||
| - **New questions** → a real coverage gap. Most will land in taxonomy categories our angles | ||
| don't target: **functional scope & behavior, interaction/UX flow, non-functional | ||
| (performance, scalability, reliability, observability), constraints & tradeoffs, and | ||
| terminology consistency**. Our angles cover data-model, edge-cases, security/compliance, | ||
| testability, and integration — so those five categories are the expected blind spots. | ||
|
|
||
| Treat stock's output as a **regression check on our generation coverage**. If a category | ||
| keeps surfacing, add a reviewer angle for it to the fan-out in `/openClarify`. | ||
|
|
||
| > Note: in this environment stock clarify is overridden (see `~/.claude` global config) to | ||
| > ask up to **25** questions in **block form**, written to `<FEATURE_DIR>/clarify-questions.md` | ||
| > — so the audit produces a diffable file rather than a one-at-a-time interactive loop. | ||
|
|
||
| ``` | ||
| /openClarify → (async answers) → resume applies + canonical format → CLARIFY: COMPLETE | ||
| │ | ||
| /speckit.clarify ×N (audit) | ||
| │ | ||
| new questions? → new clarify cycle ; else → /speckit.plan | ||
| ``` | ||
|
|
||
| ## Known gaps / operational notes | ||
|
|
||
| - **Generation script is authored on first run.** The `workflow` keyword lets the Claude | ||
| Code runtime author the fan-out's internal script the first time `/openClarify` | ||
| runs. **Save that run as `/openClarify-generate`** so subsequent features reuse it | ||
| instead of re-authoring the fan-out each time. | ||
|
|
||
| - **`/loop` is session-scoped with a 3-day cap.** It only survives while the session is | ||
| alive and stops after ~3 days. For human turnaround longer than that, swap the in-session | ||
| loop for an external scheduler: | ||
|
|
||
| ``` | ||
| cron + claude -p /openClarify-resume <dir> | ||
| ``` | ||
|
|
||
| e.g. a crontab entry running `claude -p "/openClarify-resume specs/my-feature/"` every | ||
| 15 minutes, which survives restarts and arbitrary human latency. | ||
|
|
||
| ## Usage | ||
|
|
||
| ``` | ||
| # 1. start (defaults to specs/<current-branch>/) | ||
| /openClarify | ||
|
|
||
| # 2. humans edit clarify-log.md, filling answer / answered_by / status: ANSWERED | ||
|
|
||
| # 3. nothing else to do — the loop applies answers to spec.md and stops itself | ||
| ``` |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -11,10 +11,11 @@ A layered Docker-based development environment system. Each "bench" is a self-co | |
| This single command: | ||
| 1. Configures your shell (zsh + Oh My Zsh + Powerlevel10k) | ||
| 2. Checks workstation VPN clients and patches 0dcloud TUN MTU for large Git/Docker transfers | ||
| 3. Installs or updates Wave Terminal widgets for workBenches | ||
| 4. Ensures Docker is running and Layer 0 base image exists | ||
| 5. Opens an interactive TUI to select benches, AI tools, and workstation tools | ||
| 6. Builds Docker images for selected benches | ||
| 7. Installs AI coding CLIs and workstation tools (Claude, Copilot, Codex, Pi, etc.) | ||
|
|
||
| After setup, open any bench in VS Code → "Reopen in Container" to start developing. | ||
|
|
||
|
|
@@ -25,13 +26,14 @@ Safe to run repeatedly. Installed benches show `✓ up to date` and are skipped. | |
| ## Docker Image Layers | ||
|
|
||
| ``` | ||
| Layer 0: workbench-base:latest — Ubuntu 24.04 + git, zsh, curl, shared AI CLIs, bun | ||
| ├─ Layer 1a: dev-bench-base:latest — Python, Node.js LTS, npm, dev tools, OpenSpec, spec-kit, testing tools, Playwright Chromium | ||
| │ ├─ Layer 2: cpp-bench:latest — GCC, CMake, vcpkg | ||
| │ ├─ Layer 2: dotnet-bench:latest — .NET SDK 8/9 | ||
| │ ├─ Layer 2: flutter-bench:latest — Flutter SDK, Dart, Android tools | ||
| │ ├─ Layer 2: frappe-bench:latest — MariaDB client, Redis, Nginx, bench CLI (Node.js 20) | ||
| │ ├─ Layer 2: java-bench:latest — OpenJDK 25, Maven, Gradle, Spring CLI | ||
| │ ├─ Layer 2: php-bench:latest — PHP 8.3, Composer, PHPUnit, Xdebug | ||
| │ ├─ Layer 2: py-bench:latest — Python dev tools (thin layer on 1a) | ||
| │ └─ Layer 2: go-bench:latest — Go toolchain | ||
| ├─ Layer 1b: sys-bench-base:latest — Kubernetes, Terraform, cloud CLIs | ||
|
|
@@ -67,6 +69,7 @@ bash scripts/ensure-layer3.sh --base java-bench:latest | |
| setup.sh | ||
| ├── Shell setup (zsh + Oh My Zsh + Powerlevel10k) | ||
| ├── VPN setup (AmneziaVPN + 0dcloud checks, 0dcloud MTU patch) | ||
| ├── Wave Terminal widgets (terminal, projects, and workBench containers) | ||
| ├── Docker check (is daemon running?) | ||
| ├── Layer 0 check (build workbench-base:latest if missing) | ||
| ├── Interactive TUI (scripts/interactive-setup.sh) | ||
|
|
@@ -79,6 +82,39 @@ setup.sh | |
| └── Summary + log file path | ||
| ``` | ||
|
|
||
| ## Wave Terminal Widgets | ||
|
|
||
| `setup.sh` runs the Wave Terminal installer as a best-effort host setup step so | ||
| all workBenches checkouts get the same desktop shortcuts. The installer comes | ||
| from `opensoft/Install-Wave-Terminal`; setup prefers a sibling | ||
| `../Install-Wave-Terminal` checkout when present, then falls back to cloning it | ||
| into `~/.cache/workbenches/Install-Wave-Terminal`. | ||
|
|
||
| Installed widgets include: | ||
|
|
||
| | Widget | Behavior | | ||
| |--------|----------| | ||
| | `terminal` | Overrides Wave's built-in terminal to open `wsl://Ubuntu-24.04` instead of PowerShell | | ||
| | `projects` | Opens the Wave files view at `$HOME/projects` on the WSL connection | | ||
| | `pyBench` | Starts or repairs `py-bench`, then opens an interactive shell | | ||
| | `flutterBench` | Starts or repairs `flutter-bench`, then opens an interactive shell | | ||
| | `C++Bench` | Starts or repairs `cpp-bench`, then opens an interactive shell | | ||
| | `cloudBench` | Starts or repairs `cloud-bench`, then opens an interactive shell | | ||
|
|
||
| First-run setup offers consent-based work and personal AI profile onboarding, | ||
| including GitHub credential-registry discovery and a local manual fallback. | ||
| See [Shared AI provider profiles](docs/multi-provider-profiles.md). | ||
| Multi-account Claude details remain in | ||
| [Claude multi-account profiles](docs/claude-multi-account-profiles.md). | ||
| The cross-provider ownership and composition model is documented in | ||
| [AI credential ownership and profile composition](docs/ai-credential-ownership.md). | ||
|
|
||
| The WSL connection defaults to `wsl://Ubuntu-24.04` and the projects widget | ||
| defaults to `$HOME/projects`. Override them with `WAVE_WSL_CONNECTION` and | ||
| `WAVE_PROJECTS_ROOT`. Widget font size defaults to `16`; override it with | ||
| `WAVE_WIDGET_FONT_SIZE`. Set `WORKBENCHES_SKIP_WAVE_WIDGETS=1` to skip this | ||
| step. | ||
|
|
||
| ### Bench Processing Logic | ||
|
|
||
| | State | Action | | ||
|
|
@@ -112,6 +148,7 @@ workBenches/ | |
| │ ├── frappeBench/ ← Frappe/ERPNext bench (opensoft/frappeBench) | ||
| │ ├── goBench/ ← Go bench (opensoft/goBench) | ||
| │ ├── javaBench/ ← Java bench (opensoft/javaBench) | ||
| │ ├── phpBench/ ← PHP bench (opensoft/phpBench) | ||
| │ └── pyBench/ ← Python bench (opensoft/pyBench) | ||
| ├── sysBenches/ | ||
| │ ├── base-image/ ← Layer 1b: sys-bench-base Dockerfile | ||
|
|
@@ -180,9 +217,10 @@ Installed and updated via the setup TUI: | |
| |------|---------------|------| | ||
| | Claude Code CLI | Native installer | `claude login` | | ||
| | GitHub Copilot CLI | npm | `copilot auth login` | | ||
| | OpenAI Codex CLI | npm | `OPENAI_API_KEY`, `codex login`, or isolated `pcodex PROFILE` logins | | ||
| | Google Gemini CLI | npm | Google login or isolated `pgemini PROFILE` login | | ||
| | Grok Build | Native installer | Isolated `pgrok PROFILE` login | | ||
| | OpenCode CLI with Z.AI GLM | Manual | Isolated `pglm PROFILE` Z.AI Coding Plan key | | ||
| | spec-kit | uv (pip) | None | | ||
| | OpenSpec | npm | None | | ||
|
|
||
|
|
@@ -256,6 +294,7 @@ sysBenches/cloudBench/docs/amnezia-server-runbook.md | |
| | frappeBench | [opensoft/frappeBench](https://github.com/opensoft/frappeBench) | | ||
| | goBench | [opensoft/goBench](https://github.com/opensoft/goBench) | | ||
| | javaBench | [opensoft/javaBench](https://github.com/opensoft/javaBench) | | ||
| | phpBench | [opensoft/phpBench](https://github.com/opensoft/phpBench) | | ||
| | pyBench | [opensoft/pyBench](https://github.com/opensoft/pyBench) | | ||
| | gentecBench | [opensoft/gentecBench](https://github.com/opensoft/gentecBench) | | ||
| | simBench | [opensoft/simBench](https://github.com/opensoft/simBench) | | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,58 @@ | ||
| # Multiple AI Harness Account Manager | ||
|
|
||
| This local-only dashboard manages account inventory and supported login flows | ||
| for Claude Code, ChatGPT/Codex CLI, Grok Build, Google Antigravity, and Abacus | ||
| AI. It is generic public tooling: real account names and email addresses belong | ||
| in a separate private source-of-truth repository. | ||
|
|
||
| Create a private manifest from the example: | ||
|
|
||
| ```bash | ||
| mkdir -p ~/account-registry/config | ||
| cp config/ai-harness-accounts.example.json \ | ||
| ~/account-registry/config/ai-harness-accounts.json | ||
| $EDITOR ~/account-registry/config/ai-harness-accounts.json | ||
| ``` | ||
|
|
||
| Run the dashboard: | ||
|
|
||
| ```bash | ||
| python3 apps/credential-manager/credential_manager.py \ | ||
| --source-repo ~/account-registry | ||
| ``` | ||
|
|
||
| Profiles created by `setup.sh` need no separate registry argument: | ||
|
|
||
| ```bash | ||
| ./scripts/check-ai-credentials.sh | ||
| ``` | ||
|
|
||
| This reads supported manifests in `~/.config/workbenches` by default, including | ||
| the Claude, OpenAI, Gemini, Grok, and GLM profile manifests. | ||
|
|
||
| Open `http://127.0.0.1:8765`. The server binds only to loopback. It reads | ||
| non-secret account metadata, derives the source clone's Git remote, verifies | ||
| supported profiles, and starts supported vendor login commands. | ||
|
|
||
| Automated adapters: | ||
|
|
||
| - Claude Code: `CLAUDE_CONFIG_DIR`, `claude auth login`, and | ||
| `claude auth status`. | ||
| - ChatGPT/Codex CLI: `CODEX_HOME`, `codex login`, and | ||
| `codex login status`. | ||
| - Grok Build: `GROK_HOME`, `grok login`, and `grok models`. | ||
|
|
||
| Inventory/manual adapters: | ||
|
|
||
| - Google Antigravity: the vendor stores sessions in the operating-system | ||
| keyring and does not document a profile-home override. | ||
| - Abacus AI: the vendor documents `/login [email]` and `ABACUS_API_KEY`, but | ||
| not a profile-home override. | ||
|
|
||
| The dashboard never reads, returns, copies, or stores credential contents. | ||
| Authentication logs are local, mode `0600`, and may contain short-lived login | ||
| URLs, so they must not be committed. | ||
|
|
||
| See [Multiple AI harness account management](../../docs/ai-harness-account-management.md) | ||
| for the manifest schema, provider commands, security model, and official | ||
| documentation links. |
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
🟡 *[MEDIUM] .gitignore adds pycache/claude rules but still has no .env / .backup / secret patterns
This PR touches .gitignore (adding pycache/, .py[cod], .claude/dashboard.md, .claude/speckit-history.md) but does not add any ignore rule for environment/secret files even though the same PR introduces a SonarQube workflow that reads tokens from ~/.config/sonarqube/sonar.env (see devBenches/base-image/files/sonarqube/sonar-env) and leaves a tracked bench-config.json.backup. With no '.env', '.env', 'sonar.env', '*.backup', or 'secrets' pattern, a developer who drops a sonar.env or a *.backup containing a SONAR_TOKEN into the tree will have it committed silently. Since the PR is already editing this file and adding a token-consuming feature, the env/secret ignores belong here.
Suggested fix: Add patterns such as '.env', '.env', 'sonar.env', '.backup', '*.bak', and 'secrets/' to .gitignore in this same change.