From 7ed1d5e7ad5f593784696d23845e484e5e0a3b99 Mon Sep 17 00:00:00 2001 From: M Waleed Kadous Date: Wed, 25 Feb 2026 03:22:12 -0800 Subject: [PATCH 1/8] [Spec 558] Initial specification draft --- .../558-comprehensive-documentation-up.md | 132 ++++++++++++++++++ 1 file changed, 132 insertions(+) create mode 100644 codev/specs/558-comprehensive-documentation-up.md 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 | From b77932a078a59b99d5d0750246d49b5d1b8bb901 Mon Sep 17 00:00:00 2001 From: M Waleed Kadous Date: Wed, 25 Feb 2026 03:22:39 -0800 Subject: [PATCH 2/8] [Spec 558] Initial plan draft --- .../558-comprehensive-documentation-up.md | 68 +++++++++++++++++++ 1 file changed, 68 insertions(+) create mode 100644 codev/plans/558-comprehensive-documentation-up.md 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. From 1c18063f343b4a20147ea50684f1f3358f0d9a7f Mon Sep 17 00:00:00 2001 From: M Waleed Kadous Date: Wed, 25 Feb 2026 03:25:01 -0800 Subject: [PATCH 3/8] [Spec 558][Phase: fix-deprecated-commands] fix: Replace deprecated af dash with af workspace across all docs --- AGENTS.md | 4 ++-- CLAUDE.md | 4 ++-- INSTALL.md | 14 +++++++------- MANIFESTO.md | 4 ++-- README.md | 37 ++++++++++++------------------------- docs/tips.md | 14 +++++++------- 6 files changed, 32 insertions(+), 45 deletions(-) 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..6698812e 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,47 +349,34 @@ 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 another device (iPad, laptop, etc.) with a single command: ```bash -# Step 1: Start Agent Farm -af dash start +# Start workspace on remote machine (sets up SSH tunnel automatically) +af workspace start --remote user@remote-host -# 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 +# Or with explicit project path +af workspace start --remote user@remote-host:/path/to/project ``` -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 -``` +This command SSHs into the remote machine, starts Agent Farm there, sets up an SSH tunnel back to your local machine, and opens the workspace in your browser. Requires passwordless SSH (`ssh-copy-id user@host`). See [CLI Reference](codev/resources/commands/agent-farm.md#remote-access) for full details. diff --git a/docs/tips.md b/docs/tips.md index 4a1406e9..b728fe51 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. @@ -113,11 +113,11 @@ Builders work in isolated git worktrees. Their changes don't affect your main br ## 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 +125,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 From 690d3e01f115ad256e6dd6ad1ad1c342351d28f7 Mon Sep 17 00:00:00 2001 From: M Waleed Kadous Date: Wed, 25 Feb 2026 03:25:21 -0800 Subject: [PATCH 4/8] [Spec 558][Phase: version-refs] fix: Update stale version references and remote access in README --- README.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 6698812e..3487587e 100644 --- a/README.md +++ b/README.md @@ -418,7 +418,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. @@ -427,11 +427,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. From b24cf80758c9bd8efe98f5f77f80a89f82584b46 Mon Sep 17 00:00:00 2001 From: M Waleed Kadous Date: Wed, 25 Feb 2026 03:26:26 -0800 Subject: [PATCH 5/8] [Spec 558][Phase: expand-docs] feat: Add missing protocols and porch to FAQ, cheatsheet, and CLI overview --- codev/resources/cheatsheet.md | 18 +++++++++++-- codev/resources/commands/overview.md | 16 +++++++++-- docs/faq.md | 40 +++++++++++++++++++++++++++- 3 files changed, 69 insertions(+), 5 deletions(-) diff --git a/codev/resources/cheatsheet.md b/codev/resources/cheatsheet.md index 2ab660ec..55903d33 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 register` | Register tower with 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/docs/faq.md b/docs/faq.md index b4b0bd47..ab228f88 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. Use `af workspace start --remote user@host` to start Agent Farm on a remote machine and access it from your local browser via SSH tunnel. One command handles everything: SSH connection, Agent Farm startup, tunnel setup, and browser launch. Requires passwordless SSH. + ## 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). From c68b19d13daa4ad82584c15ae6719ce894b0c9cb Mon Sep 17 00:00:00 2001 From: M Waleed Kadous Date: Wed, 25 Feb 2026 03:27:05 -0800 Subject: [PATCH 6/8] [Spec 558][Phase: tips-why-update] feat: Add remote access, cross-workspace, and porch tips; fix stale why.md references --- docs/tips.md | 40 ++++++++++++++++++++++++++++++++++++++++ docs/why.md | 2 +- 2 files changed, 41 insertions(+), 1 deletion(-) diff --git a/docs/tips.md b/docs/tips.md index b728fe51..e4c4eaea 100644 --- a/docs/tips.md +++ b/docs/tips.md @@ -107,6 +107,46 @@ For example, to customize the consultant role: vim codev/roles/consultant.md ``` +## Remote Access + +Access Agent Farm from any device with a single command: + +```bash +af workspace start --remote user@remote-host +``` + +This sets up SSH tunneling automatically. Requires passwordless SSH (`ssh-copy-id user@host` first). + +## Cross-Workspace Messaging + +Send messages between different project workspaces: + +```bash +# Send to another project's architect +af send marketmaker:architect "R4 report is ready" + +# Send to a builder in another workspace +af send codev:0042 "Check the shared library changes" +``` + +## 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. 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 From 496d266f14b789c6dae6b6b0055a52ff4207bd67 Mon Sep 17 00:00:00 2001 From: M Waleed Kadous Date: Wed, 25 Feb 2026 03:27:50 -0800 Subject: [PATCH 7/8] [Spec 558][Phase: review] docs: Add post-implementation review --- .../558-comprehensive-documentation-up.md | 50 +++++++++++++++++++ 1 file changed, 50 insertions(+) create mode 100644 codev/reviews/558-comprehensive-documentation-up.md 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 From 648f2eddaa73538c668a4ee10caff8234f2edb53 Mon Sep 17 00:00:00 2001 From: M Waleed Kadous Date: Wed, 25 Feb 2026 04:04:20 -0800 Subject: [PATCH 8/8] =?UTF-8?q?[Spec=20558]=20fix:=20Address=20PR=20review?= =?UTF-8?q?=20=E2=80=94=20remote=20access=20via=20cloud,=20remove=20cross-?= =?UTF-8?q?workspace=20syntax,=20fix=20tower=20connect?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 12 +++--------- codev/resources/cheatsheet.md | 2 +- docs/faq.md | 2 +- docs/tips.md | 18 +++--------------- 4 files changed, 8 insertions(+), 26 deletions(-) diff --git a/README.md b/README.md index 3487587e..486828e9 100644 --- a/README.md +++ b/README.md @@ -366,19 +366,13 @@ The `af` command is globally available after installing `@cluesmith/codev`. ### Remote Access -Access Agent Farm from another device (iPad, laptop, etc.) with a single command: +Access Agent Farm from any device via cloud connectivity: ```bash -# Start workspace on remote machine (sets up SSH tunnel automatically) -af workspace start --remote user@remote-host - -# Or with explicit project path -af workspace start --remote user@remote-host:/path/to/project +af tower connect ``` -This command SSHs into the remote machine, starts Agent Farm there, sets up an SSH tunnel back to your local machine, and opens the workspace in your browser. Requires passwordless SSH (`ssh-copy-id user@host`). - -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 diff --git a/codev/resources/cheatsheet.md b/codev/resources/cheatsheet.md index 55903d33..e9922b5f 100644 --- a/codev/resources/cheatsheet.md +++ b/codev/resources/cheatsheet.md @@ -125,7 +125,7 @@ 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 register` | Register tower with codevos.ai for cloud access | +| `af tower connect` | Connect tower to codevos.ai for cloud access | ### porch diff --git a/docs/faq.md b/docs/faq.md index ab228f88..938f5a76 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -106,7 +106,7 @@ Agent Farm adds parallel builder orchestration, a web dashboard, and automated p ## Can I access Agent Farm remotely? -Yes. Use `af workspace start --remote user@host` to start Agent Farm on a remote machine and access it from your local browser via SSH tunnel. One command handles everything: SSH connection, Agent Farm startup, tunnel setup, and browser launch. Requires passwordless SSH. +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? diff --git a/docs/tips.md b/docs/tips.md index e4c4eaea..bdbffbe4 100644 --- a/docs/tips.md +++ b/docs/tips.md @@ -109,25 +109,13 @@ vim codev/roles/consultant.md ## Remote Access -Access Agent Farm from any device with a single command: +Access Agent Farm from any device via cloud connectivity: ```bash -af workspace start --remote user@remote-host +af tower connect ``` -This sets up SSH tunneling automatically. Requires passwordless SSH (`ssh-copy-id user@host` first). - -## Cross-Workspace Messaging - -Send messages between different project workspaces: - -```bash -# Send to another project's architect -af send marketmaker:architect "R4 report is ready" - -# Send to a builder in another workspace -af send codev:0042 "Check the shared library changes" -``` +Register your tower with [codevos.ai](https://codevos.ai) for secure remote access from any browser. ## Non-Node.js Projects