vibe-forge 0.3.6 → 0.3.10

package/context/modern-conventions.md

@@ -0,0 +1,129 @@
+# Modern Development Conventions
+
+Reference for up-to-date tooling and naming conventions. Knowledge cutoffs can cause outdated suggestions - prefer these modern approaches.
+
+## Docker & Containers
+
+### Compose (V2+, 2021)
+
+- **File name:** `compose.yml` or `compose.yaml` (NOT `docker-compose.yml`)
+- **Command:** `docker compose` (NOT `docker-compose`)
+- Compose V2 is built into Docker CLI, no separate install needed
+- `docker-compose` (hyphenated) is legacy V1
+
+```yaml
+# compose.yml (modern)
+services:
+  app:
+    build: .
+    ports:
+      - "3000:3000"
+```
+
+### Docker Best Practices
+
+- Use multi-stage builds for smaller images
+- Prefer `COPY` over `ADD` unless extracting archives
+- Use `.dockerignore` to exclude node_modules, .git, etc.
+- Pin base image versions (e.g., `node:20-alpine`, not `node:latest`)
+
+## Package Managers
+
+### Node.js
+
+- **npm:** v7+ supports workspaces, lockfile v2
+- **pnpm:** Preferred for monorepos, faster, stricter
+- **Bun:** Fast runtime + package manager, growing adoption
+
+### Python
+
+- **uv:** Modern, fast replacement for pip/pip-tools (2024+)
+- **poetry:** Dependency management + packaging
+- **pipx:** For CLI tools (don't pip install globally)
+
+## TypeScript
+
+- **Config:** `tsconfig.json` with `"moduleResolution": "bundler"` for modern bundlers
+- **Strict mode:** Always enable `"strict": true`
+- **Node types:** `@types/node` version should match Node.js version
+
+## Testing
+
+### JavaScript/TypeScript
+
+- **Vitest:** Modern, fast, Vite-native (preferred for new projects)
+- **Jest:** Still widely used, v30+ reduces deprecated deps
+- **Playwright:** E2E testing, cross-browser
+
+### Python
+
+- **pytest:** Standard, use over unittest
+- **pytest-cov:** Coverage reporting
+
+## CI/CD
+
+### GitHub Actions
+
+- Use `actions/checkout@v4`, `actions/setup-node@v4` (latest major versions)
+- Prefer `npm ci` over `npm install` in CI
+- Use job matrices for cross-platform testing
+
+## Linting & Formatting
+
+### JavaScript/TypeScript
+
+- **ESLint v9+:** Flat config (`eslint.config.js`, not `.eslintrc`)
+- **Prettier:** Code formatting (or use ESLint with stylistic rules)
+- **Biome:** Fast all-in-one linter + formatter (Rust-based)
+
+### Python
+
+- **Ruff:** Fast linter + formatter (replaces flake8, black, isort)
+- **mypy:** Type checking
+
+## API Design
+
+### REST
+
+- Use plural nouns for collections (`/users`, not `/user`)
+- HTTP methods: GET (read), POST (create), PUT/PATCH (update), DELETE
+- Status codes: 200 OK, 201 Created, 400 Bad Request, 404 Not Found, 500 Server Error
+
+### Authentication
+
+- **JWTs:** Short expiry + refresh tokens, store in httpOnly cookies (not localStorage)
+- **OAuth 2.0 / OIDC:** For third-party auth
+- **Passkeys/WebAuthn:** Modern passwordless option
+
+## Database
+
+### ORMs
+
+- **Prisma:** Type-safe, great DX for Node.js/TypeScript
+- **Drizzle:** Lightweight, SQL-like syntax
+- **SQLAlchemy 2.0:** Python standard (note: 2.0 syntax differs from 1.x)
+
+### Migrations
+
+- Always use migrations, never manual schema changes in production
+- Version control migration files
+
+## Frontend
+
+### React
+
+- **React 18+:** Concurrent features, Suspense
+- Prefer function components + hooks over class components
+- Use React Server Components where appropriate (Next.js 13+)
+
+### State Management
+
+- Start with React Context + useReducer
+- **Zustand:** Simple, minimal boilerplate
+- **TanStack Query:** For server state (caching, refetching)
+
+## Monorepos
+
+- **Turborepo:** Fast builds, caching
+- **Nx:** Full-featured, good for enterprise
+- **pnpm workspaces:** Native package manager support

package/docs/TODO.md

@@ -5,61 +5,172 @@ This document tracks issues identified during code reviews that are deferred for
 ## Security (From Aegis Review - Round 2)
 
 ### Medium Priority
+
 - **M-1: eval() of external data in load_agents_from_json()**
   - File: `bin/lib/config.sh` line 95
   - Issue: If agents.json is compromised, malicious agent names could execute shell commands via `eval "$agent_data"`
   - Fix: Add input validation in Node.js script to reject agent names containing shell metacharacters
 
 ### Low Priority
+
 - **L-1: Windows Terminal command escaping**
   - File: `bin/forge-spawn.sh` lines 55-57
   - Issue: `$display_name` and `$FORGE_ROOT` not escaped for nested shell invocation
   - Fix: Use `printf %q` for proper escaping
 
-- **L-2: Terminal escape sequences in task parsing**
+- ~~**L-2: Terminal escape sequences in task parsing**~~ ✅ Fixed in 0.3.7
   - File: `bin/forge-daemon.sh` lines 147-149
   - Issue: ANSI escape sequences in task files could affect terminal
-  - Fix: Add `| tr -d '\033'` to strip escape sequences
+  - Fix: Added `| tr -d '\033' | sed 's/\[[0-9;]*m//g'` to strip escape sequences
 
-- **L-3: Workflow version injection**
+- ~~**L-3: Workflow version injection**~~ ✅ Fixed in 0.3.7
   - File: `.github/workflows/publish.yml` lines 32-33
   - Issue: Version input not validated before use in npm command
-  - Fix: Add semver regex validation
+  - Fix: Added semver regex validation step
 
 ## Architecture (From Sage Review - Round 2)
 
 ### P1 Priority
+
 - **sed -i incompatibility in forge-setup.sh**
   - Lines: 205, 249, 291, 380, 381, 384, 388
   - Issue: macOS/BSD sed requires `sed -i ''` but script uses `sed -i`
   - Fix: Add platform detection or create `sed_inplace()` helper
 
-- **Silent error suppression for JSON loading**
+- ~~**Silent error suppression for JSON loading**~~ ✅ Fixed in 0.3.7
   - Files: `bin/forge.sh` line 44, `bin/forge-spawn.sh` line 34
   - Issue: `2>/dev/null || true` silently ignores JSON parsing errors
-  - Fix: Log warning when fallback is used
+  - Fix: Now logs warning when fallback is used
 
 - **Inconsistent exit codes**
   - Issue: All errors exit with code 1, no differentiation
   - Fix: Define exit code constants in `constants.sh`
 
 ### P2 Priority
-- **Hardcoded agent list in cmd_help()**
+
+- ~~**Hardcoded agent list in cmd_help()**~~ ✅ Fixed in 0.3.7
   - File: `bin/forge.sh` lines 253-260
-  - Fix: Generate dynamically using `show_available_agents()`
+  - Fix: Now uses `show_available_agents()` dynamically
 
 - **Raw echo -e instead of log_* functions**
   - File: `bin/forge-setup.sh` (multiple lines)
   - Fix: Replace with appropriate `log_*` calls
 
-- **Duplicate color definitions in cli.js**
+- ~~**Duplicate color definitions in cli.js**~~ ✅ Fixed in 0.3.7
   - File: `bin/cli.js` lines 24-31
-  - Fix: Document as intentional or extract to shared config
+  - Fix: Documented as intentional (cli.js runs standalone via npx)
 
 ## Testing (From Crucible Review - Round 2)
 
 ### Low Priority Gaps
+
 - `show_available_agents()` not tested
 - `setup_windows_env()` not tested (hard to test in CI)
 - `colors.sh` log functions not tested (display-only)
 - CLI `init`/`update` commands not tested (side effects)
+
+## UX Improvements
+
+### Consider Re-adding
+
+- **Auto status on /forge startup**
+  - Removed in 0.3.6 to reduce 45s→~15s startup time
+  - Could re-add if startup is fast enough after optimization
+  - Alternative: Add "show status on startup" config option
+
+### Shell Tests
+
+- BATS tests disabled in CI due to bash associative array limitations
+- Need to refactor tests to avoid `declare -A` in subshell contexts
+
+## Feature Ideas
+
+### Worker Loop (Ralph-style Persistent Workers) - Added in 0.3.9
+
+Implemented in `.claude/hooks/worker-loop.sh` and `.claude/commands/worker-loop.md`.
+
+Workers can now run in persistent loop mode:
+
+- `/worker-loop anvil` - Start Anvil in persistent mode
+- Worker checks for tasks, works on them, loops back
+- Only exits after N idle checks with no tasks found
+- Based on the Ralph Loop technique from Anthropic's plugins
+
+### LSP/Tooling Selection During Init
+
+- Add multi-select during `vibe-forge init` for tech stack
+- Options could include:
+  - **Languages:** TypeScript, Python, Rust, Go, Java, C#
+  - **Frameworks:** React, Vue, Next.js, FastAPI, Django, Express
+  - **Infrastructure:** Docker, Kubernetes, Terraform, AWS, GCP
+  - **Databases:** PostgreSQL, MongoDB, Redis, SQLite
+- Generate customized `context/project-stack.md` based on selections
+- Include relevant LSP configs, linter recommendations, modern conventions
+- Auto-detect from existing files (package.json, pyproject.toml, Cargo.toml, etc.)
+- Store selections in `.forge/config.json` for future reference
+
+---
+
+## V2 Architecture (Major Refactor)
+
+### Problem
+
+Current design clones the entire vibe-forge repo into each project as `_vibe-forge/`. This has issues:
+
+- Commits 50+ tool files into user's repo that aren't their code
+- Updates are awkward (re-run init? git pull?)
+- Pollutes git history with tool internals
+- Merge conflicts when updating
+
+### Proposed Solution: Tool vs Data Separation
+
+**Tool** (from npm, NOT committed):
+
+```text
+npx vibe-forge ...           # Runs from npm cache
+~/.vibe-forge/               # Or global install location
+├── bin/                     # Scripts
+├── agents/                  # Agent personalities
+└── config/                  # Default configs
+```
+
+**Project Data** (committed, project-specific):
+
+```text
+your-project/
+├── .forge/                  # Local config (gitignored)
+│   ├── config.json         # Terminal type, paths, preferences
+│   └── state.yaml          # Current session state
+└── .vibe-forge/            # Project data (committed)
+    ├── tasks/              # Task files
+    │   ├── pending/
+    │   ├── in-progress/
+    │   └── completed/
+    ├── context/            # Project context
+    │   └── project-context.md
+    └── overrides/          # Optional: project-specific agent tweaks
+        └── agents.json     # Override default agent config
+```
+
+### Benefits
+
+1. **Clean git history** - Only project data committed, not tool code
+2. **Easy updates** - `npm update -g vibe-forge` or `npx vibe-forge@latest`
+3. **Single source of truth** - Tool version consistent across projects
+4. **Smaller footprint** - ~10 files vs 50+
+5. **No vendoring** - Don't commit dependencies into your repo
+
+### Migration Path
+
+1. **v0.4.x (current)**: Add `.gitignore` entries for tool internals (stopgap)
+2. **v1.0**: Refactor to proper tool/data separation
+   - Tool runs from npm package directly
+   - Only `.vibe-forge/` folder in project
+   - Backward compat: detect old `_vibe-forge/` and migrate
+
+### Implementation Notes
+
+- `npx vibe-forge` already works - just need to make scripts runnable from npm location
+- Agent personalities loaded from npm package by default, with project overrides
+- Tasks/context remain project-local
+- `.forge/config.json` stays gitignored (machine-specific)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vibe-forge",
-  "version": "0.3.6",
+  "version": "0.3.10",
   "description": "Multi-agent development orchestration system for terminal-native vibe coding",
   "keywords": [
     "vibe-coding",