slaguru666/AIPass
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(system): devpulse docs restructure: lean README (209→35 lines) + new SETUP.md with install/uninstall/troubleshooting for Linux/macOS/Windows (WSL), env vars reference, Windows native support tracking via issue #261

Browse Source 
Co-Authored-By: @devpulse <devpulse@aipass>
This commit is contained in:
AIOSAI
2026-04-14 02:20:11 -07:00
co-authored by @devpulse
parent c27cc4ab11
commit 2fd70c4902
2 changed files with 242 additions and 191 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/aipass/devpulse/README.md
+17 -191
View File
@@ -2,208 +2,34 @@
# DevPulse
**Purpose:** Orchestration hub for the AIPass ecosystem
**Module:** `aipass.devpulse`
**Status:** Active
**Last Updated:** 2026-04-10
> Orchestration hub for AIPass. Plans, coordinates, dispatches. Never the builder.
---
DevPulse is the central coordination branch. It does not ship features of its own — it works with the user on design, dispatches real work to branch specialists, tracks plans and memory, and keeps the system moving. If a task belongs to another branch, DevPulse emails that branch and waits for the reply.
## Overview
## Start here
DevPulse is the central coordination branch for AIPass. It plans, delegates, and tracks work across all 11 branches in the ecosystem. Think of it as the project manager — it doesn't build modules itself, but dispatches work to branch agents, monitors results, and maintains system-wide visibility.
| You want to | Read |
|---|---|
| Install, update, uninstall, or troubleshoot | [SETUP.md](SETUP.md) |
| What's happening right now | [STATUS.local.md](STATUS.local.md) |
| Identity, memory, session history | [`.trinity/`](.trinity/) |
| Diagnostic scanners | [`tools/`](tools/) |
| Branch health audits | [`branch_audits _only/`](branch_audits%20_only/) |
| Active plans | `drone @flow list open` |
### What DevPulse Does
- **Cross-branch orchestration** — Dispatch tasks to branches via AI Mail + wake
- **System-wide planning** — Create and manage DPLANs (design) and FPLANs (execution)
- **Diagnostic tooling** — 20 standalone scanners for code quality, security, and compliance
- **Status tracking** — Session history, branch audits, system health
- **Architecture discussions** — Work with the user on design decisions
- **Agent coordination** — Deploy sub-agents in parallel for research and builds
---
## Managed Directory — `src/aipass/`
DevPulse orchestrates all branches under `src/aipass/`:
```
src/aipass/
├── drone/ # Command routing — @ resolution, branch dispatch
├── seedgo/ # Standards & compliance — audits, checkers, packs
├── prax/ # Logging system — stack introspection, dual routing
├── cli/ # CLI framework — argument parsing, command registry
├── flow/ # Plan management — FPLANs, DPLANs, templates, tracking
├── ai_mail/ # Inter-branch comms — inbox, dispatch, wake
├── api/ # LLM access layer — OpenRouter, multi-provider, usage tracking
├── trigger/ # Event system — log watchers, event handlers
├── spawn/ # Branch lifecycle — create, update, delete, passport
├── memory/ # Memory bank — ChromaDB vectors, rollover, search
├── devpulse/ # Orchestration hub (you are here)
└── __init__.py
```
**11 registered branches:** drone, seedgo, prax, cli, flow, ai_mail, api, trigger, spawn, memory, devpulse
## DevPulse Architecture
```
devpulse/
├── .trinity/ # Identity + memory
│ ├── passport.json # Branch identity
│ ├── local.json # Session history + key learnings
│ └── observations.json # Collaboration patterns
├── .aipass/ # AI context
│ └── aipass_local_prompt.md
├── .spawn/ # Spawn metadata
├── apps/ # Entry point scaffold (minimal — devpulse.py + stubs)
├── tools/ # Diagnostic scanner suite (26 tools)
├── branch_audits _only/ # Living audit plans for all 11 branches + patrick
├── dropbox/ # Incoming files from other branches/users
├── docs/ # Tracked documentation
├── docs.local/ # Working files (gitignored)
├── DPLAN-*.md # Active design plans (8-10 at any time)
├── CLOSED_PLANS.local.json # Archive of completed plans
├── STATUS.local.md # Current work, issues, todos
└── README.md
```
DevPulse has a minimal `apps/` scaffold but is primarily a **manager** branch, not a builder. It coordinates via dispatch and sub-agents rather than implementing code.
---
## Diagnostic Tools
DevPulse maintains a suite of 26 standalone diagnostic scanners in `tools/`. Each follows the `{concern}_scanner_v1.py` naming convention and supports `@branch`, `--all`, and `--summary` flags.
### Code Quality
| Tool | What it checks |
|------|---------------|
| `silent_catch_scanner_v1.py` | Except blocks with no logging or raise |
| `silent_catch_scanner_v2.py` | Same + tier-aware grouping (entry/module/handler) |
| `commented_logger_scanner_v1.py` | Commented-out `# logger.*()` calls |
| `debug_print_scanner_v1.py` | Raw `print()` that should use Rich console |
| `deep_nesting_scanner_v1.py` | Functions with nesting depth > 3 |
| `long_function_scanner_v1.py` | Top N longest functions (informational) |
| `unused_function_scanner_v1.py` | Functions defined but never called |
| `dead_code_scanner_v1.py` | Module/handler files with zero references |
| `todo_scanner_v1.py` | TODO/FIXME/HACK/XXX comments |
| `fallback_scanner_v1.py` | Intentional silent fallback patterns |
### Security
| Tool | What it checks |
|------|---------------|
| `hardcoded_key_scanner_v1.py` | API key patterns in source (0 findings = good) |
| `partial_key_scanner_v1.py` | `key[:N]` partial display patterns |
| `url_injection_scanner_v1.py` | Unencoded URL params in f-strings |
### Documentation & Consistency
| Tool | What it checks |
|------|---------------|
| `help_text_scanner_v1.py` | `python3` refs that should be `drone @branch` |
| `readme_freshness_scanner_v1.py` | README date vs newest code file |
| `prompt_scanner_v1.py` | Local prompt quality (RICH/BASIC/STUB/MISSING) |
| `test_scanner_v1.py` | Pytest coverage per branch + module |
| `command_scanner_v1.py` | Verifies drone commands are routable |
| `magic_number_scanner_v1.py` | Hardcoded numbers (cross-file consistency) |
| `stale_scanner_v1.py` | Outdated terminology (17 tracked keywords) |
### Infrastructure
| Tool | What it checks |
|------|---------------|
| `log_scanner_v1.py` | Prax log files for errors/warnings |
| `key_exposure_scanner_v1.py` | API key exposure patterns in code |
| `meta_header_scanner_v1.py` | Module metadata headers compliance |
| `scanner_v1.py` | Base scanner framework |
### Utilities
| Tool | What it does |
|------|-------------|
| `dev_central_to_devpulse.py` | Rename stale terms across files |
| `verify_branch.py` | Verify branch structure compliance |
| `git_lock_tool.py` | Manage git lock state for PRs |
**Tool classification:** Hard checks (pass/fail) vs Advisory (flag for investigation). See DPLAN-0030 for full details.
---
## Branch Audits
DevPulse maintains living audit plans for every branch in `branch_audits _only/`. These are comprehensive health assessments created during adversarial audit sessions (S83 Wave 1-3) and continuously updated.
Each audit tracks:
- **CRITICAL** — Must-fix issues (security, data loss, broken core features)
- **BUG** — Functional defects
- **STALE/DEAD** — Outdated references, dead code
- **QUALITY** — Performance, thread safety, architectural debt
- **DOCS** — Documentation gaps and inaccuracies
| Branch | Audit File | Health |
|--------|-----------|--------|
| drone | DPLAN-0053 | YELLOW (23 BUG) |
| seedgo | DPLAN-0084 | GREEN |
| prax | DPLAN-0039 | GREEN |
| cli | DPLAN-0074 | YELLOW (2 CRITICAL) |
| flow | DPLAN-0082 | YELLOW (5 CRITICAL) |
| ai_mail | DPLAN-0036 | GREEN |
| api | DPLAN-0029 | YELLOW (3 CRITICAL) |
| trigger | DPLAN-0075 | YELLOW (1 CRITICAL) |
| spawn | DPLAN-0035 | YELLOW (12 BUG) |
| memory | DPLAN-0038 | GREEN |
| devpulse | DPLAN-0037 | RED |
| patrick | DPLAN-0086 | N/A |
---
## Commands
## Invoke
```bash
# System status
drone systems # List all registered branches
drone @seedgo audit aipass # Run full standards audit
# Flow plans
drone @flow create . "Subject" # Create FPLAN (execution plan)
drone @flow create . "Subject" dplan # Create DPLAN (design/planning)
drone @flow create . "Subject" master # Create master plan (multi-phase)
drone @flow list open # List active plans
# Dispatch work
drone @ai_mail dispatch @target "Subject" "Body" # Send + wake (one command)
drone @ai_mail email @target "Subject" "Body" # Just mail, no wake
drone @ai_mail dispatch wake @target # Wake only
drone @ai_mail dispatch wake --fresh @target # Fresh session wake
# Branch management
drone @spawn create <path> # Create new branch from template
drone @spawn update @branch # Update branch scaffold
drone @spawn delete @branch # Archive + deregister branch
cd src/aipass/devpulse
claude
```
---
Say "hi" and DevPulse picks up where the last session left off.
## Integration Points
## Role in one line
### Depends On
- `aipass.prax` — Logging (all logging goes through prax)
- `aipass.ai_mail` — Inter-branch communication + dispatch
- `aipass.flow` — Plan creation and tracking (DPLANs + FPLANs)
- `aipass.drone` — Command routing to all branches
- `aipass.spawn` — Branch lifecycle management
- `aipass.seedgo` — Standards verification + audit
### Coordinates
- All 11 branches: drone, seedgo, prax, cli, flow, ai_mail, api, trigger, spawn, memory, devpulse
Manager, not builder. Coordinates via dispatch + sub-agents. Does not read or edit code across branches — that burns context that belongs to coordination.
---
## Role
DevPulse is a **manager** branch, not a builder. It delegates code tasks to sub-agents and branch agents. Its context window is reserved for coordination, planning, and architecture — not for reading and editing files across the codebase.
The `tools/` directory is DevPulse's "tool shed" — 26 standalone diagnostic scripts for investigating code quality across all branches. These tools surface patterns and create conversations. They're built for AI consumption: run a scanner, get instant visibility, decide what matters.
The `branch_audits _only/` directory is DevPulse's health dashboard — living audit documents for every branch, updated during adversarial audit sessions and fix sweeps. Each audit tracks CRITICALs, BUGs, quality debt, and documentation gaps with current health ratings.
---
[← Back to AIPass](../../../README.md)
src/aipass/devpulse/SETUP.md
+225
View File
@@ -0,0 +1,225 @@
[← Back to DevPulse](README.md)
# DevPulse Setup, Uninstall, Troubleshooting
Everything you need to install, run, maintain, or remove DevPulse (and AIPass as a whole). Kept here so the DevPulse README can stay lean and loads quickly on every session startup.
---
## Platform support at a glance
| Platform | Install status | Notes |
|---|---|---|
| **Linux** (Ubuntu, Debian, Fedora, Arch) | Supported | Primary development target. `setup.sh` works out of the box. |
| **macOS** (Intel and Apple Silicon) | Supported | `setup.sh` works with minor caveats (see macOS section). |
| **Windows 10 / 11** | **In progress** | Native Windows support is actively being built. Track progress in [issue #261](https://github.com/AIOSAI/AIPass/issues/261). For now: use WSL2 (Ubuntu), or wait for the cross-platform `setup.py` landing in a PR soon. |
---
## Linux install
### Requirements
- Python 3.10 or newer (`python3 --version`)
- `git`, `bash`, `sudo`
- Claude Code CLI installed and authenticated (`claude --version`)
- ~500 MB disk for the venv and dependencies
### Install
```bash
git clone https://github.com/AIOSAI/AIPass.git ~/Projects/AIPass
cd ~/Projects/AIPass
bash setup.sh
```
`setup.sh` will:
1. Create a Python venv at `.venv/`
2. Install AIPass in editable mode (`pip install -e .`)
3. Verify the `drone` and `aipass` CLI entry points
4. Create `~/.secrets/aipass/` with `chmod 700` and seed an `.env.example`
5. Generate the AIPass branch registry
6. Bootstrap branch identity files (`.trinity/passport.json` per branch)
7. Wire Claude Code hooks into `~/.claude/settings.json`
8. Create a global symlink at `/usr/local/bin/drone` (asks for `sudo`)
### Post-install
```bash
# Verify
drone systems
# Enter the DevPulse branch
cd ~/Projects/AIPass/src/aipass/devpulse
claude
```
You should see DevPulse greet you, read its memory, and be ready.
### Optional
- Add API keys to `~/.secrets/aipass/.env` if you want LLM routing beyond Claude Code
- Set `AIPASS_HOME=~/Projects/AIPass` in your shell rc if you plan to use AIPass from other projects
- Add `export AIPASS_HOME=~/Projects/AIPass` to `~/.bashrc` **and** `~/.claude/settings.json` (the `env` section) — both are needed for full cross-project access
---
## macOS install
Same as Linux. `setup.sh` uses bash and runs on macOS out of the box.
**Caveats**:
- `chmod 700` and `chown` work correctly on macOS's HFS+ and APFS
- `sudo ln -sf /usr/local/bin/drone` works but may prompt for your admin password
- Homebrew users: if you have multiple Python installs, make sure `python3` points to Python 3.10+ before running `setup.sh`
---
## Windows install
**Short version**: use [WSL2](https://learn.microsoft.com/en-us/windows/wsl/install) (Ubuntu) and follow the Linux instructions. Full native Windows support is landing in a PR soon — follow [issue #261](https://github.com/AIOSAI/AIPass/issues/261) for status.
**Why it's in progress**: the current `setup.sh` uses bash, `sudo`, and `ln -sf /usr/local/bin/drone`, none of which translate to Windows. The `aipass init` command also writes a shell loop into `.claude/settings.json` that assumes Unix root `/`. Fixes are in flight:
- A cross-platform `setup.py` that replaces `setup.sh` on Windows
- A Python-based directory traversal replacing the bash loop in `aipass init`
- OS detection in `setup.sh` to skip the symlink step on Windows and print PATH instructions instead
**Interim workaround**: install WSL2 with an Ubuntu distribution, then clone and run `setup.sh` inside WSL. Claude Code also runs well inside WSL.
---
## Uninstall
### Full removal (Linux / macOS)
```bash
# 1. Remove the venv and repo
rm -rf ~/Projects/AIPass
# 2. Remove the global drone symlink
sudo rm /usr/local/bin/drone
# 3. Remove secrets (if you won't reinstall)
rm -rf ~/.secrets/aipass
# 4. Clean Claude Code hooks
# Edit ~/.claude/settings.json and remove any "hooks" sections that reference AIPass paths.
# Safer: back up the file first.
cp ~/.claude/settings.json ~/.claude/settings.json.bak
nano ~/.claude/settings.json # or your editor of choice
# 5. Clean your shell rc
# Remove any AIPASS_HOME export from ~/.bashrc, ~/.zshrc, etc.
```
### Partial removal (keeping secrets for reinstall)
Skip step 3 above. Your `~/.secrets/aipass/.env` will persist and be reused on next install.
### Windows (WSL2)
Same as Linux, inside the WSL distribution. To also remove the WSL distribution itself: `wsl --unregister Ubuntu` from PowerShell.
---
## Troubleshooting
### `drone: command not found`
Your venv is not activated or the `/usr/local/bin/drone` symlink is missing.
```bash
# Option A: activate the venv
source ~/Projects/AIPass/.venv/bin/activate
drone systems
# Option B: run via full path
~/Projects/AIPass/.venv/bin/drone systems
# Option C: reinstall the symlink
sudo ln -sf ~/Projects/AIPass/.venv/bin/drone /usr/local/bin/drone
```
### `AIPASS_HOME not set` warnings
```bash
# In your shell rc (~/.bashrc or ~/.zshrc)
export AIPASS_HOME=~/Projects/AIPass
# Then restart the shell or:
source ~/.bashrc
```
Also add it to `~/.claude/settings.json` under the `env` block for Claude Code sessions to pick it up.
### DevPulse greets you but doesn't read its memory
Check that `.trinity/passport.json`, `.trinity/local.json`, and `.trinity/observations.json` exist in `src/aipass/devpulse/`. If they don't, run `bash setup.sh` again to re-bootstrap the identity files.
### `drone @git system-pr` fails with a lock error
```bash
drone @git lock # check the lock state
drone @git fix # attempt to fix broken git state
```
Do NOT use raw `git reset --hard` — merge conflicts are easier to resolve than lost work.
### Branch mail not arriving
```bash
drone @ai_mail inbox # check your inbox
drone @prax watch # watch the monitoring dashboard
```
A known issue at the end of S90 affected wake delivery; see the wake investigation in DPLAN-0125 Track E if you're running a recent build.
### Tests fail on a fresh clone
```bash
cd ~/Projects/AIPass
source .venv/bin/activate
python -m pytest src/aipass/<branch>/tests/
```
If tests fail because `AIPASS_HOME` leaks the real registry into test results, that's a known pattern — the tests need `monkeypatch.delenv("AIPASS_HOME")`. See S90 notes for the fixture pattern.
### `.claude/settings.json` has `/home/patrick/` paths
You pulled an old clone. The hardcoded paths were removed in commit `867dad0` (April 5, 2026). Pull the latest main and re-run `setup.sh`, which generates the settings dynamically from your local repo root.
---
## Environment variables
| Variable | Purpose | Set where |
|---|---|---|
| `AIPASS_HOME` | Lets external projects find the AIPass registry | `~/.bashrc` + `~/.claude/settings.json` env block |
| `AIPASS_CALLER_BRANCH` | Auto-set by dispatch; identifies the sending branch for feedback/mail | Runtime only, do not set manually |
| `AIPASS_CALLER_CWD` | Auto-set by dispatch; identifies the caller's project directory | Runtime only, do not set manually |
Sensitive values (API keys, tokens, recovery codes) belong in `~/.secrets/aipass/.env`, not in shell rc or repo files.
---
## Reporting bugs
File issues at https://github.com/AIOSAI/AIPass/issues.
Helpful info to include:
- OS and version
- Python version (`python3 --version`)
- Claude Code version (`claude --version`)
- The exact command you ran and the full error output
- Whether you cloned recently or have been on the same checkout for a while (clone age helps us distinguish current bugs from fixed-but-stale-clone issues)
The first external bug report was [#261 by Gavin Rooney](https://github.com/AIOSAI/AIPass/issues/261) — that template is a good example of a useful report.
---
## See also
- [DevPulse README](README.md) — the lean entry point
- [AIPass root README](../../../README.md) — the whole framework
- [STATUS.local.md](STATUS.local.md) — current work and loose ends
- [issue #261](https://github.com/AIOSAI/AIPass/issues/261) — Windows compat tracking