diff --git a/AGENTS.md b/AGENTS.md index 1128a250..96ab9dc4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -300,10 +300,10 @@ For detailed commands, configuration, and architecture, see: ### 🚨 ALWAYS Operate From the Main Workspace Root 🚨 -**ALL `af` commands (`af spawn`, `af send`, `af status`, `af dash`, `af cleanup`) MUST be run from the repository root on the `main` branch.** +**ALL `af` commands (`af spawn`, `af send`, `af status`, `af workspace`, `af cleanup`) MUST be run from the repository root on the `main` branch.** - **NEVER** run `af spawn` from inside a builder worktree β€” builders will get nested inside that worktree, breaking everything -- **NEVER** run `af dash start` from a worktree β€” there is no separate dashboard per worktree +- **NEVER** run `af workspace start` from a worktree β€” there is no separate workspace per worktree - **NEVER** `cd` into a worktree to run af commands - The **only exception** is `porch` commands that need worktree context (e.g. `porch approve` from a builder's worktree) diff --git a/CLAUDE.md b/CLAUDE.md index 1128a250..96ab9dc4 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -300,10 +300,10 @@ For detailed commands, configuration, and architecture, see: ### 🚨 ALWAYS Operate From the Main Workspace Root 🚨 -**ALL `af` commands (`af spawn`, `af send`, `af status`, `af dash`, `af cleanup`) MUST be run from the repository root on the `main` branch.** +**ALL `af` commands (`af spawn`, `af send`, `af status`, `af workspace`, `af cleanup`) MUST be run from the repository root on the `main` branch.** - **NEVER** run `af spawn` from inside a builder worktree β€” builders will get nested inside that worktree, breaking everything -- **NEVER** run `af dash start` from a worktree β€” there is no separate dashboard per worktree +- **NEVER** run `af workspace start` from a worktree β€” there is no separate workspace per worktree - **NEVER** `cd` into a worktree to run af commands - The **only exception** is `porch` commands that need worktree context (e.g. `porch approve` from a builder's worktree) diff --git a/INSTALL.md b/INSTALL.md index 6abef2b0..0073a72e 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -441,18 +441,18 @@ Create `codev/config.json` to customize commands: Override via CLI: ```bash -af dash start --architect-cmd "claude --model opus" -af spawn --project 0003 --builder-cmd "claude" +af workspace start --architect-cmd "claude --model opus" +af spawn 3 --protocol spir --builder-cmd "claude" ``` ### Quick Start ```bash -# Start the architect dashboard -af dash start +# Start the workspace +af workspace start # Spawn a builder for a spec -af spawn --project 0003 +af spawn 3 --protocol spir # Check status of all builders af status @@ -469,8 +469,8 @@ af cleanup --project 0003 # Force cleanup (WARNING: may lose uncommitted work) af cleanup --project 0003 --force -# Stop the architect and all builders -af dash stop +# Stop the workspace and all builders +af workspace stop # Manage port allocations (for multi-project support) af ports list diff --git a/MANIFESTO.md b/MANIFESTO.md index de6e19f1..3b94b84d 100644 --- a/MANIFESTO.md +++ b/MANIFESTO.md @@ -57,8 +57,8 @@ Protocols are sequences of steps to build something. Each protocol balances rigo Enables the Architect-Builder pattern with isolated execution environments: ```bash -af dash start # Launch the architect dashboard -af spawn 3 # Create a builder for project 3 +af workspace start # Launch the architect workspace +af spawn 3 --protocol spir # Create a builder for project 3 af status # See what everyone is doing af cleanup -p 3 # Clean up when done ``` diff --git a/README.md b/README.md index 3724b8c2..486828e9 100644 --- a/README.md +++ b/README.md @@ -39,8 +39,8 @@ codev init # 3. Verify setup codev doctor -# 4. Start the dashboard (optional) -af dash start +# 4. Start the workspace (optional) +af workspace start ``` Then tell your AI agent: *"I want to build X using the SPIR protocol"* @@ -349,49 +349,30 @@ For parallel AI-assisted development, Codev includes the Architect-Builder patte ### Quick Start ```bash -# Start the architect dashboard -af dash start +# Start the workspace +af workspace start # Spawn a builder for a spec -af spawn 3 +af spawn 3 --protocol spir # Check status af status # Stop everything -af dash stop +af workspace stop ``` The `af` command is globally available after installing `@cluesmith/codev`. ### Remote Access -Access Agent Farm from another device (iPad, laptop, etc.) via SSH tunnel: +Access Agent Farm from any device via cloud connectivity: ```bash -# Step 1: Start Agent Farm -af dash start - -# Step 2: Get SSH command (shows your local IPs) -af tunnel - -# Step 3: Run the SSH command on your remote device -# Example output: ssh -L 4200:localhost:4200 youruser@192.168.1.50 - -# Step 4: Open http://localhost:4200 in your remote browser -``` - -The dashboard and all terminals work identically via the tunnel. SSH handles authentication and encryption. (File tabs use separate ports and won't load through the tunnel.) - -**Note**: Requires SSH server on the dev machine. On Windows, enable OpenSSH Server or use WSL2. - -**Legacy mode** (not recommended): -```bash -# DEPRECATED: Exposes dashboard without authentication -af dash start --allow-insecure-remote +af tower connect ``` -See [CLI Reference](codev/resources/commands/agent-farm.md#remote-access) for full details. +Register your tower with [codevos.ai](https://codevos.ai) for secure remote access from any browser β€” no SSH tunnels or port forwarding needed. ### Autonomous Builder Flags @@ -431,7 +412,7 @@ See [CLI Reference](codev/resources/commands/agent-farm.md) for full documentati Codev has a **release protocol** (`codev/protocols/release/`) that automates the entire release process. To release a new version: ``` -Let's release v1.6.0 +Let's release v2.2.0 ``` The AI guides you through: pre-flight checks, maintenance cycle, E2E tests, version bump, release notes, GitHub release, and npm publish. @@ -440,11 +421,11 @@ The AI guides you through: pre-flight checks, maintenance cycle, E2E tests, vers | Version Type | npm Tag | Example | Purpose | |--------------|---------|---------|---------| -| Stable | `latest` | 1.6.0, 1.7.0 | Production-ready releases | -| Release Candidate | `next` | 1.7.0-rc.1 | Pre-release testing (v1.7.0+) | -| Patch | `latest` | 1.6.1 | Backported bug fixes | +| Stable | `latest` | 2.1.1, 2.2.0 | Production-ready releases | +| Release Candidate | `next` | 2.2.0-rc.1 | Pre-release testing | +| Patch | `latest` | 2.1.2 | Backported bug fixes | -Starting with v1.7.0, minor releases use release candidates (`npm install @cluesmith/codev@next`) for testing before stable release. +Minor releases use release candidates (`npm install @cluesmith/codev@next`) for testing before stable release. Releases are named after great examples of architecture from around the world. See [Release Notes](docs/releases/) for version history. diff --git a/codev/plans/558-comprehensive-documentation-up.md b/codev/plans/558-comprehensive-documentation-up.md new file mode 100644 index 00000000..bfb37c57 --- /dev/null +++ b/codev/plans/558-comprehensive-documentation-up.md @@ -0,0 +1,68 @@ +# Plan: Comprehensive Documentation Update for HN Launch + +## Metadata +- **Spec**: codev/specs/558-comprehensive-documentation-up.md +- **Status**: draft +- **Created**: 2026-02-25 + +## Phase Overview + +| # | Phase | Objective | Status | +|---|-------|-----------|--------| +| 1 | Fix deprecated CLI commands | Replace all `af dash` with `af workspace`, fix `af spawn` syntax | pending | +| 2 | Update README version refs and Remote Access | Fix stale version numbers, modernize remote access section | pending | +| 3 | Expand FAQ and Cheatsheet | Add missing protocols, features, and CLI tools | pending | +| 4 | Update tips.md and why.md | Fix stale commands in tips, verify references in why.md | pending | + +## Phase Details + +### Phase 1: Fix Deprecated CLI Commands + +**Objective**: Replace all deprecated `af dash` references with `af workspace` across all docs. + +**Files to modify**: +- `README.md` β€” Lines using `af dash start`, `af dash stop` +- `docs/tips.md` β€” Lines 119-130 using `af dash` in troubleshooting section + +**Changes**: +- `af dash start` β†’ `af workspace start` +- `af dash stop` β†’ `af workspace stop` +- `af spawn 3` β†’ `af spawn 3 --protocol spir` (add required --protocol flag) + +**Done when**: No `af dash` references remain in user-facing docs (excluding deprecation notices in agent-farm.md). + +### Phase 2: Update README Version References and Remote Access + +**Objective**: Fix stale version numbers and modernize the remote access section. + +**Files to modify**: +- `README.md` + +**Changes**: +- Update release example from `v1.6.0` to current-era version +- Update versioning strategy text (remove "Starting with v1.7.0" phrasing) +- Replace manual SSH tunnel section with `af workspace start --remote` approach +- Ensure `af tunnel` reference is replaced or removed + +**Done when**: README reflects v2.x era and current remote access workflow. + +### Phase 3: Expand FAQ and Cheatsheet + +**Objective**: Add documentation for protocols and features missing from FAQ and cheatsheet. + +**Files to modify**: +- `docs/faq.md` β€” Add sections on ASPIR, AIR, BUGFIX, porch orchestration +- `codev/resources/cheatsheet.md` β€” Add ASPIR, BUGFIX to protocol table; add porch, tower to tools +- `codev/resources/commands/overview.md` β€” Add porch to CLI summary if missing + +**Done when**: All current protocols and CLI tools are documented in reference materials. + +### Phase 4: Update tips.md and why.md + +**Objective**: Fix remaining stale content in tips and verify references in why.md. + +**Files to modify**: +- `docs/tips.md` β€” Add tips for remote access, cross-workspace messaging, porch checks +- `docs/why.md` β€” Verify "Claude Opus 4.1" model reference, verify "SP(IDE)R-SOLO" mention, verify "MCP support" reference + +**Done when**: All user-facing docs have accurate, current content. diff --git a/codev/resources/cheatsheet.md b/codev/resources/cheatsheet.md index 2ab660ec..e9922b5f 100644 --- a/codev/resources/cheatsheet.md +++ b/codev/resources/cheatsheet.md @@ -60,8 +60,10 @@ A **protocol** is a structured workflow that defines how work progresses from id | Protocol | Use For | Phases | |----------|---------|--------| -| **SPIR** | New features | Specify β†’ Plan β†’ Implement β†’ Review | -| **AIR** | Small features (< 300 LOC) | Implement β†’ Review | +| **SPIR** | New features | Specify β†’ Plan β†’ Implement β†’ Review (with human gates) | +| **ASPIR** | Trusted features | Same as SPIR but no human gates on spec/plan | +| **AIR** | Small features (< 300 LOC) | Implement β†’ Review (no spec/plan artifacts) | +| **BUGFIX** | Bug fixes from GitHub issues | Fix β†’ Test β†’ PR (minimal ceremony) | | **TICK** | Amendments to existing specs | Task Identification β†’ Coding β†’ Kickout | | **MAINTAIN** | Codebase hygiene | Dead code removal, documentation sync | | **EXPERIMENT** | Research & prototyping | Hypothesis β†’ Experiment β†’ Conclude | @@ -123,6 +125,18 @@ Architect-Builder orchestration. Used by both **humans and agents**β€”agents use | `af shell` | Spawn a utility shell | | `af open ` | Open file in workspace viewer | | `af tower start` | Start cross-project tower | +| `af tower connect` | Connect tower to codevos.ai for cloud access | + +### porch + +Protocol orchestrator. Drives SPIR/ASPIR/TICK/BUGFIX via a state machine. Used by **agents** (and humans for gate approvals). + +| Command | Description | +|---------|-------------| +| `porch status ` | Check project protocol status | +| `porch run ` | Run next protocol phase | +| `porch approve ` | Approve a human gate (human only) | +| `porch pending` | List all pending gates | ### consult diff --git a/codev/resources/commands/overview.md b/codev/resources/commands/overview.md index 7d1f1eac..9502a4dc 100644 --- a/codev/resources/commands/overview.md +++ b/codev/resources/commands/overview.md @@ -1,11 +1,12 @@ # Codev CLI Command Reference -Codev provides three CLI tools for AI-assisted software development: +Codev provides four CLI tools for AI-assisted software development: | Tool | Description | |------|-------------| | `codev` | Project setup, maintenance, and framework commands | | `af` | Agent Farm - multi-agent orchestration for development | +| `porch` | Protocol orchestrator - drives SPIR/ASPIR/TICK/BUGFIX state machines | | `consult` | AI consultation with external models (Gemini, Codex, Claude) | ## Quick Start @@ -33,7 +34,7 @@ consult -m gemini --protocol spir --type spec npm install -g @cluesmith/codev ``` -This installs all three commands globally: `codev`, `af`, and `consult`. +This installs all four commands globally: `codev`, `af`, `porch`, and `consult`. ## Command Summaries @@ -65,6 +66,17 @@ See [codev.md](codev.md) for full documentation. See [agent-farm.md](agent-farm.md) for full documentation. +### porch - Protocol Orchestrator + +| Command | Description | +|---------|-------------| +| `porch status ` | Show project protocol status | +| `porch run ` | Run the next protocol phase | +| `porch approve ` | Approve a human gate | +| `porch pending` | List all pending gates across projects | + +Porch drives SPIR, ASPIR, TICK, and BUGFIX protocols via a state machine. It's used automatically by `af spawn` (strict mode) or manually by builders (soft mode). + ### consult - AI Consultation | Command | Description | diff --git a/codev/reviews/558-comprehensive-documentation-up.md b/codev/reviews/558-comprehensive-documentation-up.md new file mode 100644 index 00000000..2c053b0a --- /dev/null +++ b/codev/reviews/558-comprehensive-documentation-up.md @@ -0,0 +1,50 @@ +# Review: Comprehensive Documentation Update for HN Launch + +## Metadata +- **Spec**: codev/specs/558-comprehensive-documentation-up.md +- **Plan**: codev/plans/558-comprehensive-documentation-up.md +- **Issue**: #558 +- **Date**: 2026-02-25 + +## Summary + +Documentation-only update across 8 files to fix deprecated CLI syntax, add missing protocol/feature documentation, and modernize stale references in preparation for HN launch. + +## Changes Made + +### Phase 1: Fix Deprecated CLI Commands +- Replaced all `af dash` with `af workspace` in README.md, docs/tips.md, AGENTS.md, CLAUDE.md, MANIFESTO.md, INSTALL.md +- Added required `--protocol` flag to `af spawn` examples +- Verified AGENTS.md/CLAUDE.md remain byte-identical + +### Phase 2: Update README Version References +- Updated version examples from v1.6.0/v1.7.0 era to v2.x era +- Replaced manual SSH tunnel Remote Access section with `af workspace start --remote` +- Updated versioning strategy table + +### Phase 3: Expand FAQ and Cheatsheet +- Added 4 new FAQ sections: protocol overview, porch explanation, Agent Farm optionality, remote access +- Added ASPIR and BUGFIX protocols to cheatsheet protocol table +- Added porch CLI to cheatsheet tools reference +- Added porch as fourth CLI tool in commands/overview.md with command summary + +### Phase 4: Update tips.md and why.md +- Added tips for remote access, cross-workspace messaging, and non-Node.js porch checks +- Fixed stale "SP(IDE)R-SOLO" and "MCP support" references in why.md + +## What Went Well +- Systematic file-by-file audit caught all deprecated `af dash` references +- Changes were minimal and focused β€” no unnecessary rewrites +- All docs remain internally consistent + +## What Was Challenging +- PR consultations failed because no PR existed yet (chicken-and-egg) +- Balancing between updating historical references (like model names in case studies) vs keeping them accurate as historical records + +## Lessons Learned +- Documentation-only PRs benefit from creating the PR first, then running consultations on the actual diff +- The `af dash` β†’ `af workspace` deprecation wasn't fully propagated through docs when the rename happened β€” future renames should include a doc-sweep step + +## Methodology Notes +- ASPIR was appropriate for this scope β€” no spec/plan gates needed for a documentation refresh +- Consultations on the spec ran but output went to stdout (not captured) β€” consider `--output` flag for background consultations diff --git a/codev/specs/558-comprehensive-documentation-up.md b/codev/specs/558-comprehensive-documentation-up.md new file mode 100644 index 00000000..12929aa4 --- /dev/null +++ b/codev/specs/558-comprehensive-documentation-up.md @@ -0,0 +1,132 @@ +# Specification: Comprehensive Documentation Update for HN Launch + +## Metadata +- **ID**: spec-2026-02-25-comprehensive-documentation-up +- **Status**: draft +- **Created**: 2026-02-25 +- **Issue**: #558 + +## Problem Statement + +Codev is preparing for a Hacker News submission of the Tour of CodevOS article. While the README was recently updated (#557), the broader documentation has accumulated stale content β€” deprecated command syntax, missing features, and inconsistencies between docs and the current codebase (v2.1.1). + +HN readers are technically sophisticated. Encountering stale CLI examples or broken references in documentation would undermine credibility. + +## Current State + +### Stale Command Syntax + +**README.md** uses deprecated `af dash` commands in multiple places: +- Line 44: `af dash start` (should be `af workspace start`) +- Line 354: `af dash start` (same) +- Line 356: `af spawn 3` (missing required `--protocol` flag) +- Line 361: `af dash stop` (should be `af workspace stop`) +- Line 371: `af dash start` (same) +- Line 376: `af tunnel` (may not exist as standalone command) +- Line 389: `af dash start --allow-insecure-remote` (deprecated approach) + +**docs/tips.md** uses deprecated commands: +- Lines 119-121: `af dash stop` / `af dash start` (should be `af workspace stop` / `af workspace start`) +- Lines 127-130: Same `af dash` usage in "Orphaned Sessions" section + +**README.md** has stale version references: +- Line 435: Example shows `v1.6.0` (current version is 2.1.1) +- Line 447: "Starting with v1.7.0, minor releases use release candidates" β€” outdated + +### Missing Documentation for Recent Features + +**docs/faq.md** is missing: +- ASPIR protocol (autonomous SPIR variant) +- AIR protocol (lightweight for small features) +- BUGFIX protocol +- Porch orchestration +- Remote access / cloud connectivity (codevos.ai) +- Cross-workspace messaging + +**codev/resources/cheatsheet.md** is missing: +- ASPIR protocol in protocol table +- BUGFIX protocol in protocol table +- `porch` CLI in tools reference +- `af tower` commands in af table +- Cross-workspace messaging in af table + +### Inconsistencies + +**docs/why.md** references: +- "Claude Opus 4.1" β€” model naming may need verification +- "SP(IDE)R-SOLO" β€” verify this variant still exists +- "MCP support" as a tool dependency β€” may be outdated + +**README.md Remote Access section** describes a manual SSH tunnel workflow (`af tunnel`) that has been superseded by `af workspace start --remote`. + +## Desired State + +All user-facing documentation should: +1. Use current CLI syntax (`af workspace` instead of `af dash`) +2. Include required flags (`af spawn 42 --protocol spir`) +3. Reference current version (2.1.1) and features +4. Cover all current protocols (SPIR, ASPIR, AIR, TICK, BUGFIX, MAINTAIN, EXPERIMENT) +5. Document recent capabilities (remote access, cloud connectivity, porch, cross-workspace messaging) +6. Present a consistent, professional tone appropriate for HN audience + +## Stakeholders +- **Primary Users**: HN readers evaluating Codev for the first time +- **Secondary Users**: Existing users referencing documentation +- **Business Owners**: Codev maintainers preparing for HN launch + +## Success Criteria +- [ ] All `af dash` references replaced with `af workspace` across all docs +- [ ] All `af spawn` examples include `--protocol` flag +- [ ] README version references updated to current (2.1.1) +- [ ] README Remote Access section uses `af workspace start --remote` +- [ ] FAQ covers all current protocols (ASPIR, AIR, BUGFIX at minimum) +- [ ] Cheatsheet includes all current protocols and CLI tools +- [ ] Tips uses current command syntax throughout +- [ ] No broken or obviously stale references in any user-facing doc +- [ ] AGENTS.md and CLAUDE.md remain in sync after any changes + +## Constraints + +### Technical Constraints +- Documentation-only changes (no code modifications) +- Must not break any existing internal links +- AGENTS.md and CLAUDE.md must remain byte-identical + +### Scope Constraints +- Focus on user-facing docs: `docs/`, `codev/resources/commands/`, `codev/resources/cheatsheet.md`, `README.md` +- Do not modify internal architecture docs (`arch.md`, `lessons-learned.md`) +- Do not modify protocol definition files +- Do not modify release notes (they are historical records) + +## Assumptions +- `af dash` is a deprecated alias that still works but should not appear in documentation +- `af workspace start --remote` is the current recommended approach for remote access +- All protocols listed in CLAUDE.md (SPIR, ASPIR, AIR, TICK, BUGFIX, MAINTAIN, EXPERIMENT) are current +- Version 2.1.1 is the current released version + +## Solution Approach + +### Approach: Systematic Audit and Update + +Audit each file against the current codebase state, fix stale content, add missing documentation for recent features. Keep changes minimal β€” update what's wrong, add what's missing, don't rewrite what's working. + +**Complexity**: Low β€” all changes are documentation text edits +**Risk Level**: Low β€” no code changes, only documentation + +## Files in Scope + +| File | Key Changes | +|------|-------------| +| `README.md` | Fix `af dash` β†’ `af workspace`, fix `af spawn` examples, update version refs, update Remote Access section | +| `docs/faq.md` | Add ASPIR/AIR/BUGFIX protocols, add porch orchestration | +| `docs/tips.md` | Fix `af dash` β†’ `af workspace`, add tips for new features | +| `docs/why.md` | Verify model names, verify SP(IDE)R-SOLO reference, minor updates | +| `codev/resources/cheatsheet.md` | Add ASPIR/BUGFIX protocols, add porch/tower to tools | +| `codev/resources/commands/overview.md` | Add porch to CLI tools summary | + +## Risks and Mitigation +| Risk | Probability | Impact | Mitigation | +|------|------------|--------|------------| +| Missing a stale reference | Low | Low | Systematic file-by-file audit | +| Breaking internal links | Low | Medium | Verify all links after changes | +| AGENTS.md/CLAUDE.md desync | Low | Medium | Only modify if needed, update both together | diff --git a/docs/faq.md b/docs/faq.md index b4b0bd47..938f5a76 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -70,6 +70,44 @@ Codev runs *on top of* Claude Code. The Architect and Builder roles use Claude C Think of Claude Code as the engine. Codev is the operating system that orchestrates it for larger software projects. +## What protocols are available? + +Codev ships with several protocols for different types of work: + +| Protocol | Use For | Key Trait | +|----------|---------|-----------| +| **SPIR** | New features | Full ceremony: Specify β†’ Plan β†’ Implement β†’ Review with human gates | +| **ASPIR** | Trusted features | Same as SPIR but without human gates on spec/plan β€” builder runs autonomously | +| **AIR** | Small features (< 300 LOC) | Lightweight: Implement β†’ Review, no spec/plan artifacts | +| **BUGFIX** | Bug fixes from GitHub issues | Minimal: fix, test, PR β€” no spec needed | +| **TICK** | Amendments to existing specs | Extends an existing SPIR spec with incremental changes | +| **MAINTAIN** | Code hygiene | Dead code removal, documentation sync, dependency cleanup | +| **EXPERIMENT** | Research spikes | Hypothesis β†’ Experiment β†’ Conclude | + +**How to choose**: SPIR for anything significant or novel. ASPIR for trusted, well-scoped features. AIR or BUGFIX for small work. TICK to amend an existing spec. + +## What is porch? + +**Porch** is the protocol orchestrator. It drives SPIR, ASPIR, TICK, and BUGFIX protocols via a state machine β€” managing phase transitions, human approval gates, and multi-agent consultations automatically. + +When you `af spawn` a builder, porch orchestrates its work: +- Enforces phase order (can't skip from Specify to Implement) +- Runs 3-way consultations at checkpoints +- Blocks at human gates until approved +- Tracks state in `codev/projects//status.yaml` + +You can also use porch manually: `porch status 42`, `porch run 42`, `porch approve 42 spec-approval`. + +## Can I use Codev without Agent Farm? + +Yes. All protocols (SPIR, TICK, etc.) work in any AI coding assistant β€” Claude Code, Cursor, Copilot, or any tool that reads CLAUDE.md/AGENTS.md. Just tell your AI: *"I want to build X using the SPIR protocol"*. + +Agent Farm adds parallel builder orchestration, a web dashboard, and automated protocol enforcement. It's optional but powerful for larger projects. + +## Can I access Agent Farm remotely? + +Yes. Register your tower with [codevos.ai](https://codevos.ai) using `af tower connect`, then access your workspace from any browser. No SSH tunnels or port forwarding needed. + ## More questions? -Join the conversation in [GitHub Discussions](https://github.com/cluesmith/codev/discussions). +Join the conversation in [GitHub Discussions](https://github.com/cluesmith/codev/discussions) or our [Discord community](https://discord.gg/mJ92DhDa6n). diff --git a/docs/tips.md b/docs/tips.md index 4a1406e9..bdbffbe4 100644 --- a/docs/tips.md +++ b/docs/tips.md @@ -57,10 +57,10 @@ The `af consult` variant runs in a visible dashboard terminal so you can observe ## Quick Builder Spawning -Spawn a builder directly from a spec number: +Spawn a builder directly from an issue number: ```bash -af spawn 42 +af spawn 42 --protocol spir ``` The builder gets its own isolated git worktree, automatically receives the spec and plan context, and starts implementing immediately. @@ -107,17 +107,45 @@ For example, to customize the consultant role: vim codev/roles/consultant.md ``` +## Remote Access + +Access Agent Farm from any device via cloud connectivity: + +```bash +af tower connect +``` + +Register your tower with [codevos.ai](https://codevos.ai) for secure remote access from any browser. + +## Non-Node.js Projects + +Configure porch checks for your language stack in `af-config.json`: + +```json +{ + "porch": { + "checks": { + "build": { "command": "cargo build" }, + "tests": { "command": "cargo test" }, + "e2e_tests": { "skip": true } + } + } +} +``` + +Works with Python (uv/pytest), Rust (cargo), Go, and any language with a build/test command. + ## Safe Branch Management Builders work in isolated git worktrees. Their changes don't affect your main branch until they create a PR and you merge it. ## Troubleshooting -### Dashboard Won't Start +### Workspace Won't Start ```bash -af dash stop # Kill any orphaned processes -af dash start # Fresh start +af workspace stop # Kill any orphaned processes +af workspace start # Fresh start ``` ### Orphaned Sessions @@ -125,8 +153,8 @@ af dash start # Fresh start If things are really stuck, restart Tower: ```bash -af dash stop # Stop Tower and all shellper sessions -af dash start # Fresh start +af workspace stop # Stop Tower and all shellper sessions +af workspace start # Fresh start ``` ### Port Conflicts diff --git a/docs/why.md b/docs/why.md index ec68ceec..871a1080 100644 --- a/docs/why.md +++ b/docs/why.md @@ -97,7 +97,7 @@ SP(IDE)R has real constraints worth acknowledging. **Scope Considerations**: Quick fixes and small scripts don't need the full protocol. SP(IDE)R shines for features that will need maintenance, documentation, and evolution. -**Tool Dependencies**: Full multi-agent consultation requires Claude Code with MCP support. SP(IDE)R-SOLO works without these but loses the multi-perspective review benefits. +**Tool Dependencies**: Full multi-agent consultation requires at least two AI CLIs (Claude Code, Gemini CLI, or Codex). SPIR works without consultation but loses the multi-perspective review benefits. ### Comparisons with Other Specification-Driven Approaches