From a4480fa0675cee890599219e0936f598dbb6a88d Mon Sep 17 00:00:00 2001 From: dave Date: Wed, 15 Apr 2026 18:08:16 +0000 Subject: [PATCH] chore: feed CONTEXT and STACK specs to all agents, update STACK with source map MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Agents now read specs/00_CONTEXT.md (what the project does) and specs/tech/STACK.md (tech stack + source map) in addition to the README. STACK.md rewritten to reflect current state — removes stale references to biome, tauri-specta, .story_kit. Co-Authored-By: Claude Opus 4.6 (1M context) --- .huskies/agents.toml | 14 +- .huskies/specs/tech/STACK.md | 224 ++++++++++++++-------------- README.md | 279 +---------------------------------- 3 files changed, 120 insertions(+), 397 deletions(-) diff --git a/.huskies/agents.toml b/.huskies/agents.toml index 6537df1c..eea31bde 100644 --- a/.huskies/agents.toml +++ b/.huskies/agents.toml @@ -5,7 +5,7 @@ role = "Full-stack engineer. Implements features across all components." model = "sonnet" max_turns = 50 max_budget_usd = 5.00 -prompt = "You are working in a git worktree on story {{story_id}}. Read CLAUDE.md first, then .huskies/README.md to understand the dev process. The story details are in your prompt above. The worktree and feature branch already exist - do not create them.\n\n## Your workflow\n1. Read the story and understand the acceptance criteria.\n2. Implement the changes.\n3. As you complete each acceptance criterion, call check_criterion MCP tool to mark it done.\n4. Run the run_tests MCP tool. It blocks until tests complete and returns the results.\n5. If tests fail, fix the failures and run run_tests again. Do not commit until tests pass.\n6. Once tests pass, commit your work with a descriptive message and exit.\n\nDo NOT accept stories, move them between stages, or merge to master. The server handles all of that after you exit.\n\n## Bug Workflow: Trust the Story, Act Fast\nWhen working on bugs:\n1. READ THE STORY DESCRIPTION FIRST. If it specifies exact files, functions, and line numbers — go directly there and make the fix.\n2. If the story does NOT specify the exact location, investigate with targeted grep.\n3. Fix with a surgical, minimal change.\n4. Run tests, fix failures, commit and exit.\n5. Write commit messages that explain what broke and why." +prompt = "You are working in a git worktree on story {{story_id}}. Read CLAUDE.md first, then .huskies/README.md for the dev process, .huskies/specs/00_CONTEXT.md for what this project does, and .huskies/specs/tech/STACK.md for the tech stack and source map. The story details are in your prompt above. The worktree and feature branch already exist - do not create them.\n\n## Your workflow\n1. Read the story and understand the acceptance criteria.\n2. Implement the changes.\n3. As you complete each acceptance criterion, call check_criterion MCP tool to mark it done.\n4. Run the run_tests MCP tool. It blocks until tests complete and returns the results.\n5. If tests fail, fix the failures and run run_tests again. Do not commit until tests pass.\n6. Once tests pass, commit your work with a descriptive message and exit.\n\nDo NOT accept stories, move them between stages, or merge to master. The server handles all of that after you exit.\n\n## Bug Workflow: Trust the Story, Act Fast\nWhen working on bugs:\n1. READ THE STORY DESCRIPTION FIRST. If it specifies exact files, functions, and line numbers — go directly there and make the fix.\n2. If the story does NOT specify the exact location, investigate with targeted grep.\n3. Fix with a surgical, minimal change.\n4. Run tests, fix failures, commit and exit.\n5. Write commit messages that explain what broke and why." system_prompt = "You are a full-stack engineer working autonomously in a git worktree. Always run the run_tests MCP tool before committing — do not commit until tests pass. As you complete each acceptance criterion, call check_criterion MCP tool to mark it done. Add //! module-level doc comments to any new modules and /// doc comments to any new public functions, structs, or enums. Do not accept stories, move them between stages, or merge to master — the server handles that. For bugs, trust the story description and make surgical fixes." [[agent]] @@ -15,7 +15,7 @@ role = "Full-stack engineer. Implements features across all components." model = "sonnet" max_turns = 50 max_budget_usd = 5.00 -prompt = "You are working in a git worktree on story {{story_id}}. Read CLAUDE.md first, then .huskies/README.md to understand the dev process. The story details are in your prompt above. The worktree and feature branch already exist - do not create them.\n\n## Your workflow\n1. Read the story and understand the acceptance criteria.\n2. Implement the changes.\n3. As you complete each acceptance criterion, call check_criterion MCP tool to mark it done.\n4. Run the run_tests MCP tool. It blocks until tests complete and returns the results.\n5. If tests fail, fix the failures and run run_tests again. Do not commit until tests pass.\n6. Once tests pass, commit your work with a descriptive message and exit.\n\nDo NOT accept stories, move them between stages, or merge to master. The server handles all of that after you exit.\n\n## Bug Workflow: Trust the Story, Act Fast\nWhen working on bugs:\n1. READ THE STORY DESCRIPTION FIRST. If it specifies exact files, functions, and line numbers — go directly there and make the fix.\n2. If the story does NOT specify the exact location, investigate with targeted grep.\n3. Fix with a surgical, minimal change.\n4. Run tests, fix failures, commit and exit.\n5. Write commit messages that explain what broke and why." +prompt = "You are working in a git worktree on story {{story_id}}. Read CLAUDE.md first, then .huskies/README.md for the dev process, .huskies/specs/00_CONTEXT.md for what this project does, and .huskies/specs/tech/STACK.md for the tech stack and source map. The story details are in your prompt above. The worktree and feature branch already exist - do not create them.\n\n## Your workflow\n1. Read the story and understand the acceptance criteria.\n2. Implement the changes.\n3. As you complete each acceptance criterion, call check_criterion MCP tool to mark it done.\n4. Run the run_tests MCP tool. It blocks until tests complete and returns the results.\n5. If tests fail, fix the failures and run run_tests again. Do not commit until tests pass.\n6. Once tests pass, commit your work with a descriptive message and exit.\n\nDo NOT accept stories, move them between stages, or merge to master. The server handles all of that after you exit.\n\n## Bug Workflow: Trust the Story, Act Fast\nWhen working on bugs:\n1. READ THE STORY DESCRIPTION FIRST. If it specifies exact files, functions, and line numbers — go directly there and make the fix.\n2. If the story does NOT specify the exact location, investigate with targeted grep.\n3. Fix with a surgical, minimal change.\n4. Run tests, fix failures, commit and exit.\n5. Write commit messages that explain what broke and why." system_prompt = "You are a full-stack engineer working autonomously in a git worktree. Always run the run_tests MCP tool before committing — do not commit until tests pass. As you complete each acceptance criterion, call check_criterion MCP tool to mark it done. Add //! module-level doc comments to any new modules and /// doc comments to any new public functions, structs, or enums. Do not accept stories, move them between stages, or merge to master — the server handles that. For bugs, trust the story description and make surgical fixes." [[agent]] @@ -25,7 +25,7 @@ role = "Full-stack engineer. Implements features across all components." model = "sonnet" max_turns = 50 max_budget_usd = 5.00 -prompt = "You are working in a git worktree on story {{story_id}}. Read CLAUDE.md first, then .huskies/README.md to understand the dev process. The story details are in your prompt above. The worktree and feature branch already exist - do not create them.\n\n## Your workflow\n1. Read the story and understand the acceptance criteria.\n2. Implement the changes.\n3. As you complete each acceptance criterion, call check_criterion MCP tool to mark it done.\n4. Run the run_tests MCP tool. It blocks until tests complete and returns the results.\n5. If tests fail, fix the failures and run run_tests again. Do not commit until tests pass.\n6. Once tests pass, commit your work with a descriptive message and exit.\n\nDo NOT accept stories, move them between stages, or merge to master. The server handles all of that after you exit.\n\n## Bug Workflow: Trust the Story, Act Fast\nWhen working on bugs:\n1. READ THE STORY DESCRIPTION FIRST. If it specifies exact files, functions, and line numbers — go directly there and make the fix.\n2. If the story does NOT specify the exact location, investigate with targeted grep.\n3. Fix with a surgical, minimal change.\n4. Run tests, fix failures, commit and exit.\n5. Write commit messages that explain what broke and why." +prompt = "You are working in a git worktree on story {{story_id}}. Read CLAUDE.md first, then .huskies/README.md for the dev process, .huskies/specs/00_CONTEXT.md for what this project does, and .huskies/specs/tech/STACK.md for the tech stack and source map. The story details are in your prompt above. The worktree and feature branch already exist - do not create them.\n\n## Your workflow\n1. Read the story and understand the acceptance criteria.\n2. Implement the changes.\n3. As you complete each acceptance criterion, call check_criterion MCP tool to mark it done.\n4. Run the run_tests MCP tool. It blocks until tests complete and returns the results.\n5. If tests fail, fix the failures and run run_tests again. Do not commit until tests pass.\n6. Once tests pass, commit your work with a descriptive message and exit.\n\nDo NOT accept stories, move them between stages, or merge to master. The server handles all of that after you exit.\n\n## Bug Workflow: Trust the Story, Act Fast\nWhen working on bugs:\n1. READ THE STORY DESCRIPTION FIRST. If it specifies exact files, functions, and line numbers — go directly there and make the fix.\n2. If the story does NOT specify the exact location, investigate with targeted grep.\n3. Fix with a surgical, minimal change.\n4. Run tests, fix failures, commit and exit.\n5. Write commit messages that explain what broke and why." system_prompt = "You are a full-stack engineer working autonomously in a git worktree. Always run the run_tests MCP tool before committing — do not commit until tests pass. As you complete each acceptance criterion, call check_criterion MCP tool to mark it done. Add //! module-level doc comments to any new modules and /// doc comments to any new public functions, structs, or enums. Do not accept stories, move them between stages, or merge to master — the server handles that. For bugs, trust the story description and make surgical fixes." [[agent]] @@ -37,7 +37,7 @@ max_turns = 40 max_budget_usd = 4.00 prompt = """You are the QA agent for story {{story_id}}. Your job is to verify the coder's work satisfies the story's acceptance criteria and produce a structured QA report. -Read CLAUDE.md first, then .huskies/README.md to understand the dev process. +Read CLAUDE.md first, then .huskies/README.md for the dev process, .huskies/specs/00_CONTEXT.md for what this project does, and .huskies/specs/tech/STACK.md for the tech stack and source map. ## Your Workflow @@ -126,7 +126,7 @@ role = "Senior full-stack engineer for complex tasks. Implements features across model = "opus" max_turns = 80 max_budget_usd = 20.00 -prompt = "You are working in a git worktree on story {{story_id}}. Read CLAUDE.md first, then .huskies/README.md to understand the dev process. The story details are in your prompt above. The worktree and feature branch already exist - do not create them.\n\n## Your workflow\n1. Read the story and understand the acceptance criteria.\n2. Implement the changes.\n3. As you complete each acceptance criterion, call check_criterion MCP tool to mark it done.\n4. Run the run_tests MCP tool. It blocks until tests complete and returns the results.\n5. If tests fail, fix the failures and run run_tests again. Do not commit until tests pass.\n6. Once tests pass, commit your work with a descriptive message and exit.\n\nDo NOT accept stories, move them between stages, or merge to master. The server handles all of that after you exit.\n\n## Bug Workflow: Trust the Story, Act Fast\nWhen working on bugs:\n1. READ THE STORY DESCRIPTION FIRST. If it specifies exact files, functions, and line numbers — go directly there and make the fix.\n2. If the story does NOT specify the exact location, investigate with targeted grep.\n3. Fix with a surgical, minimal change.\n4. Run tests, fix failures, commit and exit.\n5. Write commit messages that explain what broke and why." +prompt = "You are working in a git worktree on story {{story_id}}. Read CLAUDE.md first, then .huskies/README.md for the dev process, .huskies/specs/00_CONTEXT.md for what this project does, and .huskies/specs/tech/STACK.md for the tech stack and source map. The story details are in your prompt above. The worktree and feature branch already exist - do not create them.\n\n## Your workflow\n1. Read the story and understand the acceptance criteria.\n2. Implement the changes.\n3. As you complete each acceptance criterion, call check_criterion MCP tool to mark it done.\n4. Run the run_tests MCP tool. It blocks until tests complete and returns the results.\n5. If tests fail, fix the failures and run run_tests again. Do not commit until tests pass.\n6. Once tests pass, commit your work with a descriptive message and exit.\n\nDo NOT accept stories, move them between stages, or merge to master. The server handles all of that after you exit.\n\n## Bug Workflow: Trust the Story, Act Fast\nWhen working on bugs:\n1. READ THE STORY DESCRIPTION FIRST. If it specifies exact files, functions, and line numbers — go directly there and make the fix.\n2. If the story does NOT specify the exact location, investigate with targeted grep.\n3. Fix with a surgical, minimal change.\n4. Run tests, fix failures, commit and exit.\n5. Write commit messages that explain what broke and why." system_prompt = "You are a senior full-stack engineer working autonomously in a git worktree. You handle complex tasks requiring deep architectural understanding. Always run the run_tests MCP tool before committing — do not commit until tests pass. As you complete each acceptance criterion, call check_criterion MCP tool to mark it done. Add //! module-level doc comments to any new modules and /// doc comments to any new public functions, structs, or enums. Do not accept stories, move them between stages, or merge to master — the server handles that. For bugs, trust the story description and make surgical fixes." [[agent]] @@ -138,7 +138,7 @@ max_turns = 40 max_budget_usd = 4.00 prompt = """You are the QA agent for story {{story_id}}. Your job is to verify the coder's work satisfies the story's acceptance criteria and produce a structured QA report. -Read CLAUDE.md first, then .huskies/README.md to understand the dev process. +Read CLAUDE.md first, then .huskies/README.md for the dev process, .huskies/specs/00_CONTEXT.md for what this project does, and .huskies/specs/tech/STACK.md for the tech stack and source map. ## Your Workflow @@ -229,7 +229,7 @@ max_turns = 30 max_budget_usd = 5.00 prompt = """You are the mergemaster agent for story {{story_id}}. Your job is to merge the completed coder work into master. -Read CLAUDE.md first, then .huskies/README.md to understand the project. +Read CLAUDE.md first, then .huskies/README.md for the dev process, .huskies/specs/00_CONTEXT.md for what this project does, and .huskies/specs/tech/STACK.md for the tech stack and source map. ## Your Workflow 1. Call merge_agent_work(story_id='{{story_id}}'). It blocks until the merge completes and returns the full result. diff --git a/.huskies/specs/tech/STACK.md b/.huskies/specs/tech/STACK.md index 8ffea2ed..7ce64f15 100644 --- a/.huskies/specs/tech/STACK.md +++ b/.huskies/specs/tech/STACK.md @@ -1,130 +1,130 @@ -# Tech Stack & Constraints +# Tech Stack -## Overview -This project is a standalone Rust **web server binary** that serves a Vite/React frontend and exposes a **WebSocket API**. The built frontend assets are packaged with the binary (in a `frontend` directory) and served as static files. It functions as an **Agentic Code Assistant** capable of safely executing tools on the host system. +## Backend +- **Language:** Rust +- **Framework:** Poem (HTTP + WebSocket + OpenAPI) +- **Database:** SQLite via sqlx + rusqlite +- **State:** BFT CRDT replicated document backed by SQLite +- **Agents:** Claude Code CLI spawned in PTY pseudo-terminals +- **Package manager:** cargo -## Core Stack -* **Backend:** Rust (Web Server) - * **MSRV:** Stable (latest) - * **Framework:** Poem HTTP server with WebSocket support for streaming; HTTP APIs should use Poem OpenAPI (Swagger) for non-streaming endpoints. -* **Frontend:** TypeScript + React - * **Build Tool:** Vite - * **Package Manager:** npm - * **Styling:** CSS Modules or Tailwind (TBD - Defaulting to CSS Modules) - * **State Management:** React Context / Hooks - * **Chat UI:** Rendered Markdown with syntax highlighting. +## Frontend +- **Language:** TypeScript + React +- **Build:** Vite +- **Package manager:** npm +- **Testing:** Vitest (unit), Playwright (e2e) -## Agent Architecture -The application follows a **Tool-Use (Function Calling)** architecture: -1. **Frontend:** Collects user input and sends it to the LLM. -2. **LLM:** Decides to generate text OR request a **Tool Call** (e.g., `execute_shell`, `read_file`). -3. **Web Server Backend (The "Hand"):** - * Intercepts Tool Calls. - * Validates the request against the **Safety Policy**. - * Executes the native code (File I/O, Shell Process, Search). - * Returns the output (stdout/stderr/file content) to the LLM. - * **Streaming:** The backend sends real-time updates over WebSocket to keep the UI responsive during long-running Agent tasks. +## Deployment +- Single Rust binary with embedded React frontend (rust-embed) +- Three modes: standard server, headless build agent (`--rendezvous`), multi-project gateway (`--gateway`) +- Docker container with OrbStack recommended on macOS -## LLM Provider Abstraction -To support both Remote and Local models, the system implements a `ModelProvider` abstraction layer. +## Project Layout +``` +server/src/ — Rust backend +frontend/src/ — React frontend +crates/bft-json-crdt/ — CRDT library +.huskies/ — Pipeline config, agent config, specs +script/ — test, build, lint scripts +docker/ — Dockerfile and docker-compose +website/ — Static marketing/docs site +``` -* **Strategy:** - * Abstract the differences between API formats (OpenAI-compatible vs Anthropic vs Gemini). - * Normalize "Tool Use" definitions, as each provider handles function calling schemas differently. -* **Supported Providers:** - * **Ollama:** Local inference (e.g., Llama 3, DeepSeek Coder) for privacy and offline usage. - * **Anthropic:** Claude 3.5 models (Sonnet, Haiku) via API for coding tasks (Story 12). -* **Provider Selection:** - * Automatic detection based on model name prefix: - * `claude-` → Anthropic API - * Otherwise → Ollama - * Single unified model dropdown with section headers ("Anthropic", "Ollama") -* **API Key Management:** - * Anthropic API key stored server-side and persisted securely - * On first use of Claude model, user prompted to enter API key - * Key persists across sessions (no re-entry needed) +## Source Map -## Tooling Capabilities +### Core -### 1. Filesystem (Native) -* **Scope:** Strictly limited to the user-selected `project_root`. -* **Operations:** Read, Write, List, Delete. -* **Constraint:** Modifications to `.git/` are strictly forbidden via file APIs (use Git tools instead). +| File | Description | +|------|-------------| +| `server/src/main.rs` | Entry point, CLI argument parsing, and server startup | +| `server/src/config.rs` | Parses `project.toml` for agents, components, and server settings | +| `server/src/state.rs` | Global mutable session state (project root, cancellation) | +| `server/src/store.rs` | JSON-backed persistent key-value store for settings | +| `server/src/gateway.rs` | Multi-project gateway mode (MCP proxy, project switching, agent registration) | -### 2. Shell Execution -* **Library:** `tokio::process` for async execution. -* **Constraint:** We do **not** run an interactive shell (repl). We run discrete, stateless commands. -* **Allowlist:** The agent may only execute specific binaries: - * `git` - * `cargo`, `rustc`, `rustfmt`, `clippy` - * `npm`, `node`, `yarn`, `pnpm`, `bun` - * `ls`, `find`, `grep` (if not using internal search) - * `mkdir`, `rm`, `touch`, `mv`, `cp` +### Agents -### 3. Search & Navigation -* **Library:** `ignore` (by BurntSushi) + `grep` logic. -* **Behavior:** - * Must respect `.gitignore` files automatically. - * Must be performant (parallel traversal). +| File | Description | +|------|-------------| +| `server/src/agents/mod.rs` | Types, configuration, and orchestration for coding agents | +| `server/src/agents/gates.rs` | Runs test suites and validation scripts in agent worktrees | +| `server/src/agents/lifecycle.rs` | File creation, archival, and stage transitions for pipeline items | +| `server/src/agents/merge.rs` | Rebases agent work onto master and runs post-merge validation | +| `server/src/agents/pty.rs` | Spawns agent processes in pseudo-terminals and streams output | +| `server/src/agents/token_usage.rs` | Persists per-agent token consumption records to disk | +| `server/src/agent_log.rs` | Reads and writes JSONL agent event logs to disk | +| `server/src/agent_mode.rs` | Headless build-agent mode for distributed story processing | -## Coding Standards +### Agent Pool -### Rust -* **Style:** `rustfmt` standard. -* **Linter:** `clippy` - Must pass with 0 warnings before merging. -* **Error Handling:** Custom `AppError` type deriving `thiserror`. All Commands return `Result`. -* **Concurrency:** Heavy tools (Search, Shell) must run on `tokio` threads to avoid blocking the UI. -* **Quality Gates:** - * `cargo clippy --all-targets --all-features` must show 0 errors, 0 warnings - * `cargo check` must succeed - * `cargo nextest run` must pass all tests -* **Test Coverage:** - * Generate JSON report: `cargo llvm-cov nextest --no-clean --json --output-path .story_kit/coverage/server.json` - * Generate lcov report: `cargo llvm-cov report --lcov --output-path .story_kit/coverage/server.lcov` - * Reports are written to `.story_kit/coverage/` (excluded from git) +| File | Description | +|------|-------------| +| `server/src/agents/pool/mod.rs` | Manages the set of active agents across all pipeline stages | +| `server/src/agents/pool/start.rs` | Spawns a new agent process in a worktree for a story | +| `server/src/agents/pool/stop.rs` | Terminates a running agent while preserving its worktree | +| `server/src/agents/pool/pipeline/advance.rs` | Moves stories forward through pipeline stages | +| `server/src/agents/pool/pipeline/completion.rs` | Processes exit results and triggers pipeline advancement | +| `server/src/agents/pool/pipeline/merge.rs` | Orchestrates the merge-to-master flow for completed stories | +| `server/src/agents/pool/auto_assign/auto_assign.rs` | Scans pipeline stages and dispatches agents to unassigned stories | -### TypeScript / React -* **Style:** Biome formatter (replaces Prettier/ESLint). -* **Linter:** Biome - Must pass with 0 errors, 0 warnings before merging. -* **Types:** Shared types with Rust (via `tauri-specta` or manual interface matching) are preferred to ensure type safety across the bridge. -* **Testing:** Vitest for unit/component tests; Playwright for end-to-end tests. -* **Quality Gates:** - * `npx @biomejs/biome check src/` must show 0 errors, 0 warnings - * `npm run build` must succeed - * `npm test` must pass - * `npm run test:e2e` must pass - * No `any` types allowed (use proper types or `unknown`) - * React keys must use stable IDs, not array indices - * All buttons must have explicit `type` attribute +### CRDT & Database -## Libraries (Approved) -* **Rust:** - * `serde`, `serde_json`: Serialization. - * `ignore`: Fast recursive directory iteration respecting gitignore. - * `walkdir`: Simple directory traversal. - * `tokio`: Async runtime. - * `reqwest`: For LLM API calls (Anthropic, Ollama). - * `eventsource-stream`: For Server-Sent Events (Anthropic streaming). - * `uuid`: For unique message IDs. - * `chrono`: For timestamps. - * `poem`: HTTP server framework. - * `poem-openapi`: OpenAPI (Swagger) for non-streaming HTTP APIs. -* **JavaScript:** - * `react-markdown`: For rendering chat responses. - * `vitest`: Unit/component testing. - * `playwright`: End-to-end testing. +| File | Description | +|------|-------------| +| `server/src/crdt_state.rs` | Pipeline state as a conflict-free replicated document backed by SQLite | +| `server/src/crdt_sync.rs` | WebSocket-based replication of pipeline state between nodes | +| `server/src/pipeline_state.rs` | Typed pipeline state machine | +| `server/src/db/mod.rs` | Content store, shadow writes, and CRDT op persistence | -## Running the App (Worktrees & Ports) +### HTTP — MCP Tools (the tools agents call) -Multiple instances can run simultaneously in different worktrees. To avoid port conflicts: +| File | Description | +|------|-------------| +| `server/src/http/mcp/mod.rs` | MCP endpoint dispatching tool calls | +| `server/src/http/mcp/agent_tools.rs` | Start, stop, wait, list, and inspect agents | +| `server/src/http/mcp/git_tools.rs` | Status, diff, add, commit, and log on agent worktrees | +| `server/src/http/mcp/merge_tools.rs` | Merge agent work to master and report failures | +| `server/src/http/mcp/shell_tools.rs` | Run commands, execute tests, and stream output | +| `server/src/http/mcp/story_tools.rs` | Create, update, move, and manage stories/bugs/refactors | +| `server/src/http/mcp/diagnostics.rs` | Server logs, CRDT dump, version, and story movement helpers | -- **Backend:** Set `HUSKIES_PORT` to a unique port (default is 3001). Example: `HUSKIES_PORT=3002 cargo run` -- **Frontend:** Run `npm run dev` from `frontend/`. It auto-selects the next unused port. It reads `HUSKIES_PORT` to know which backend to talk to, so export it before running: `export HUSKIES_PORT=3002 && cd frontend && npm run dev` +### Chat — Bot Commands -When running in a worktree, use a port that won't conflict with the main instance (3001). Ports 3002+ are good choices. +| File | Description | +|------|-------------| +| `server/src/chat/commands/mod.rs` | Bot-level command registry shared by all transports | +| `server/src/chat/commands/status.rs` | `status` command and pipeline status helpers | +| `server/src/chat/commands/backlog.rs` | `backlog` command — shows only backlog-stage items | +| `server/src/chat/commands/run_tests.rs` | `run_tests` command — run the project's test suite | -## Safety & Sandbox -1. **Project Scope:** The application must strictly enforce that it does not read/write outside the `project_root` selected by the user. -2. **Human in the Loop:** - * Shell commands that modify state (non-readonly) should ideally require a UI confirmation (configurable). - * File writes must be confirmed or revertible. +### Chat — Transports + +| File | Description | +|------|-------------| +| `server/src/chat/transport/matrix/` | Matrix bot integration | +| `server/src/chat/transport/slack/` | Slack bot integration | +| `server/src/chat/transport/whatsapp/` | WhatsApp Business API integration | +| `server/src/chat/transport/discord/` | Discord bot integration | + +### Frontend + +| Directory | Description | +|-----------|-------------| +| `frontend/src/components/` | React UI components | +| `frontend/src/api/` | API client code (gateway, agents, etc.) | + +### Utilities + +| File | Description | +|------|-------------| +| `server/src/rebuild.rs` | Server rebuild and restart logic | +| `server/src/worktree.rs` | Creates, lists, and removes git worktrees for agent isolation | +| `server/src/io/watcher.rs` | Filesystem watcher for `.huskies/work/` and `project.toml` | + +## Quality Gates +All enforced by `script/test`: +1. Frontend build (`npm run build`) +2. Rust formatting (`cargo fmt --all --check`) +3. Rust linting (`cargo clippy -- -D warnings`) +4. Rust tests (`cargo test`) +5. Frontend tests (`npm test`) diff --git a/README.md b/README.md index 78e873ba..6fe09162 100644 --- a/README.md +++ b/README.md @@ -220,283 +220,6 @@ Both return a JSON document with: ## Source Map -### Core - -| File | Description | -|------|-------------| -| `server/src/main.rs` | Entry point, CLI argument parsing, and server startup | -| `server/src/config.rs` | Parses `project.toml` for agents, components, and server settings | -| `server/src/state.rs` | Global mutable session state (project root, cancellation) | -| `server/src/store.rs` | JSON-backed persistent key-value store for settings | - -### Agents - -| File | Description | -|------|-------------| -| `server/src/agents/mod.rs` | Types, configuration, and orchestration for coding agents | -| `server/src/agents/gates.rs` | Runs test suites and validation scripts in agent worktrees | -| `server/src/agents/lifecycle.rs` | File creation, archival, and stage transitions for pipeline items | -| `server/src/agents/merge.rs` | Rebases agent work onto master and runs post-merge validation | -| `server/src/agents/pty.rs` | Spawns agent processes in pseudo-terminals and streams output | -| `server/src/agents/token_usage.rs` | Persists per-agent token consumption records to disk | -| `server/src/agent_log.rs` | Reads and writes JSONL agent event logs to disk | -| `server/src/agent_mode.rs` | Headless build-agent mode for distributed story processing | - -### Agent Pool - -| File | Description | -|------|-------------| -| `server/src/agents/pool/mod.rs` | Manages the set of active agents across all pipeline stages | -| `server/src/agents/pool/types.rs` | `AgentPool`, `StoryAgent`, and related data structures | -| `server/src/agents/pool/start.rs` | Spawns a new agent process in a worktree for a story | -| `server/src/agents/pool/stop.rs` | Terminates a running agent while preserving its worktree | -| `server/src/agents/pool/wait.rs` | Blocks until an agent reaches a terminal state | -| `server/src/agents/pool/query.rs` | Lists available/active agents and info lookups | -| `server/src/agents/pool/process.rs` | Kills orphaned PTY child processes on shutdown | -| `server/src/agents/pool/worktree.rs` | Creates and configures git worktrees for agents | -| `server/src/agents/pool/test_helpers.rs` | In-memory pool construction and test assertions | - -### Agent Pool — Auto-assign - -| File | Description | -|------|-------------| -| `server/src/agents/pool/auto_assign/mod.rs` | Wires sub-files and re-exports public items | -| `server/src/agents/pool/auto_assign/auto_assign.rs` | Scans pipeline stages and dispatches agents to unassigned stories | -| `server/src/agents/pool/auto_assign/reconcile.rs` | Startup reconciliation: detects committed work and advances pipeline | -| `server/src/agents/pool/auto_assign/scan.rs` | Scans pipeline stages for work items and queries pool state | -| `server/src/agents/pool/auto_assign/story_checks.rs` | Front-matter checks: review holds, blocked state, merge failures | -| `server/src/agents/pool/auto_assign/watchdog.rs` | Detects orphaned agents and triggers auto-assign | - -### Agent Pool — Pipeline - -| File | Description | -|------|-------------| -| `server/src/agents/pool/pipeline/mod.rs` | Stage advancement, completion handling, and merge orchestration | -| `server/src/agents/pool/pipeline/advance.rs` | Moves stories forward through pipeline stages | -| `server/src/agents/pool/pipeline/completion.rs` | Processes exit results and triggers pipeline advancement | -| `server/src/agents/pool/pipeline/merge.rs` | Orchestrates the merge-to-master flow for completed stories | - -### Agent Runtimes - -| File | Description | -|------|-------------| -| `server/src/agents/runtime/mod.rs` | Pluggable backends (Claude Code, Gemini, OpenAI) for running agents | -| `server/src/agents/runtime/claude_code.rs` | Launches Claude Code CLI sessions as agent backends | -| `server/src/agents/runtime/gemini.rs` | Drives Google Gemini API sessions as agent backends | -| `server/src/agents/runtime/openai.rs` | Drives OpenAI API sessions as agent backends | - -### CRDT - -| File | Description | -|------|-------------| -| `server/src/crdt_state.rs` | Pipeline state as a conflict-free replicated document backed by SQLite | -| `server/src/crdt_sync.rs` | WebSocket-based replication of pipeline state between nodes | -| `server/src/crdt_wire.rs` | Serialization format for `SignedOp` sync messages | -| `server/src/pipeline_state.rs` | Typed pipeline state machine | - -### Database - -| File | Description | -|------|-------------| -| `server/src/db/mod.rs` | Content store, shadow writes, and CRDT op persistence | - -### HTTP Server - -| File | Description | -|------|-------------| -| `server/src/http/mod.rs` | Module declarations for all REST, MCP, WebSocket, and SSE endpoints | -| `server/src/http/context.rs` | Shared `AppContext` threaded through all HTTP handlers | -| `server/src/http/agents.rs` | REST API for listing, starting, stopping, and inspecting agents | -| `server/src/http/agents_sse.rs` | Server-Sent Events endpoint for real-time agent output | -| `server/src/http/anthropic.rs` | Proxy for model listing and key-validation to Anthropic | -| `server/src/http/assets.rs` | Serves the embedded React frontend via `rust-embed` | -| `server/src/http/bot_command.rs` | Bot command HTTP endpoint | -| `server/src/http/chat.rs` | REST API for the LLM-powered chat interface | -| `server/src/http/health.rs` | Returns a static "ok" response | -| `server/src/http/io.rs` | REST API for file and directory operations | -| `server/src/http/model.rs` | REST API for model selection and LLM provider management | -| `server/src/http/oauth.rs` | Anthropic OAuth callback and token exchange flow | -| `server/src/http/project.rs` | REST API for project initialization and context management | -| `server/src/http/settings.rs` | REST API for user preferences and editor configuration | -| `server/src/http/wizard.rs` | REST API for the project setup wizard | -| `server/src/http/ws.rs` | Real-time pipeline updates, chat, and permission prompts | -| `server/src/http/test_helpers.rs` | Shared test utilities for HTTP handler tests | - -### HTTP — MCP Tools - -| File | Description | -|------|-------------| -| `server/src/http/mcp/mod.rs` | Model Context Protocol endpoint dispatching tool calls | -| `server/src/http/mcp/agent_tools.rs` | Start, stop, wait, list, and inspect agents via MCP | -| `server/src/http/mcp/diagnostics.rs` | Server logs, CRDT dump, and story movement helpers | -| `server/src/http/mcp/git_tools.rs` | Status, diff, add, commit, and log on agent worktrees | -| `server/src/http/mcp/merge_tools.rs` | Merge agent work to master and report failures | -| `server/src/http/mcp/qa_tools.rs` | Request, approve, and reject QA reviews | -| `server/src/http/mcp/shell_tools.rs` | Run commands, execute tests, and stream output | -| `server/src/http/mcp/status_tools.rs` | Pipeline status, story triage, and AC inspection | -| `server/src/http/mcp/story_tools.rs` | Create, update, move, and manage stories/bugs/refactors | -| `server/src/http/mcp/wizard_tools.rs` | Interactive setup wizard tool implementations | - -### HTTP — Workflow - -| File | Description | -|------|-------------| -| `server/src/http/workflow/mod.rs` | Shared story/bug file operations for HTTP and MCP handlers | -| `server/src/http/workflow/bug_ops.rs` | Creates bug, refactor, and spike files in the pipeline | -| `server/src/http/workflow/story_ops.rs` | Creates, updates, and manages acceptance criteria in stories | -| `server/src/http/workflow/test_results.rs` | Writes structured test results into story markdown | - -### I/O - -| File | Description | -|------|-------------| -| `server/src/io/mod.rs` | Filesystem, shell, search, onboarding, and story metadata operations | -| `server/src/io/fs/mod.rs` | Module declarations and re-exports for file operations | -| `server/src/io/fs/files.rs` | Read, write, list, and create files and directories | -| `server/src/io/fs/paths.rs` | Resolves CLI and session-relative paths to absolute paths | -| `server/src/io/fs/preferences.rs` | Reads and writes model selection and user settings | -| `server/src/io/fs/project.rs` | Tracks known projects and resolves the active project root | -| `server/src/io/fs/scaffold.rs` | Creates the `.huskies/` directory structure and default files | -| `server/src/io/onboarding.rs` | Checks whether scaffold templates have been customized | -| `server/src/io/search.rs` | Full-text search across project files | -| `server/src/io/shell.rs` | Runs commands in the project directory and captures output | -| `server/src/io/story_metadata.rs` | Parses and modifies YAML front matter in story markdown | -| `server/src/io/watcher.rs` | Filesystem watcher for `.huskies/work/` and `project.toml` | -| `server/src/io/wizard.rs` | Multi-step project onboarding flow with per-step status | -| `server/src/io/test_helpers.rs` | Shared test utilities for I/O module tests | - -### Chat - -| File | Description | -|------|-------------| -| `server/src/chat/mod.rs` | Transport abstraction for chat platforms | -| `server/src/chat/lookup.rs` | Shared story-lookup helper for chat commands | -| `server/src/chat/timer.rs` | Deferred agent start via one-shot timers | -| `server/src/chat/util.rs` | Shared text utilities used by all transports | -| `server/src/chat/test_helpers.rs` | Shared test utilities for chat handler tests | - -### Chat — Commands - -| File | Description | -|------|-------------| -| `server/src/chat/commands/mod.rs` | Bot-level command registry shared by all transports | -| `server/src/chat/commands/ambient.rs` | `ambient` command handler | -| `server/src/chat/commands/assign.rs` | `assign` command handler | -| `server/src/chat/commands/backlog.rs` | `backlog` command — shows only backlog-stage items | -| `server/src/chat/commands/cost.rs` | `cost` command handler | -| `server/src/chat/commands/coverage.rs` | `coverage` command — show or refresh test coverage | -| `server/src/chat/commands/depends.rs` | `depends` command handler | -| `server/src/chat/commands/git.rs` | `git` command handler | -| `server/src/chat/commands/help.rs` | `help` command handler | -| `server/src/chat/commands/loc.rs` | `loc` command — top source files by line count | -| `server/src/chat/commands/move_story.rs` | `move` command handler | -| `server/src/chat/commands/overview.rs` | `overview` command handler | -| `server/src/chat/commands/run_tests.rs` | `test` command — run the project's test suite | -| `server/src/chat/commands/setup.rs` | `setup` command handler | -| `server/src/chat/commands/show.rs` | `show` command handler | -| `server/src/chat/commands/status.rs` | `status` command and pipeline status helpers | -| `server/src/chat/commands/timer.rs` | `timer` command handler | -| `server/src/chat/commands/triage.rs` | Story triage dump subcommand of `status` | -| `server/src/chat/commands/unblock.rs` | `unblock` command handler | -| `server/src/chat/commands/unreleased.rs` | `unreleased` command handler | - -### Chat — Matrix Transport - -| File | Description | -|------|-------------| -| `server/src/chat/transport/matrix/mod.rs` | Matrix bot integration | -| `server/src/chat/transport/matrix/config.rs` | Deserialization of `bot.toml` Matrix settings | -| `server/src/chat/transport/matrix/commands.rs` | Re-exports from `crate::chat::commands` | -| `server/src/chat/transport/matrix/transport_impl.rs` | Matrix `ChatTransport` implementation | -| `server/src/chat/transport/matrix/assign.rs` | Assign/re-assign a coder model to a story | -| `server/src/chat/transport/matrix/delete.rs` | Delete a story/bug/spike from the pipeline | -| `server/src/chat/transport/matrix/htop.rs` | Live-updating system and agent process dashboard | -| `server/src/chat/transport/matrix/notifications.rs` | Stage transition notifications for Matrix rooms | -| `server/src/chat/transport/matrix/rebuild.rs` | Trigger a server rebuild and restart | -| `server/src/chat/transport/matrix/reset.rs` | Clear the current Claude Code session for a room | -| `server/src/chat/transport/matrix/rmtree.rs` | Delete the worktree for a story | -| `server/src/chat/transport/matrix/start.rs` | Start a coder agent on a story | - -### Chat — Matrix Bot - -| File | Description | -|------|-------------| -| `server/src/chat/transport/matrix/bot/mod.rs` | Sub-modules for the Matrix chat bot | -| `server/src/chat/transport/matrix/bot/context.rs` | Shared state (rooms, history, permissions) | -| `server/src/chat/transport/matrix/bot/format.rs` | Markdown-to-HTML conversion and startup announcements | -| `server/src/chat/transport/matrix/bot/history.rs` | Per-room message history for LLM context | -| `server/src/chat/transport/matrix/bot/mentions.rs` | Checks whether a message mentions the bot | -| `server/src/chat/transport/matrix/bot/messages.rs` | Processes incoming messages and dispatches commands | -| `server/src/chat/transport/matrix/bot/run.rs` | Connects to homeserver and processes sync events | -| `server/src/chat/transport/matrix/bot/verification.rs` | Interactive emoji verification flow for E2EE | - -### Chat — Slack Transport - -| File | Description | -|------|-------------| -| `server/src/chat/transport/slack/mod.rs` | Slack Bot API integration | -| `server/src/chat/transport/slack/commands.rs` | Incoming message dispatch and slash command handling | -| `server/src/chat/transport/slack/format.rs` | Markdown to Slack mrkdwn conversion | -| `server/src/chat/transport/slack/history.rs` | Conversation history persistence | -| `server/src/chat/transport/slack/meta.rs` | `ChatTransport` implementation for Slack | -| `server/src/chat/transport/slack/verify.rs` | Request signature verification | - -### Chat — Discord Transport - -| File | Description | -|------|-------------| -| `server/src/chat/transport/discord/mod.rs` | Discord Bot integration | -| `server/src/chat/transport/discord/commands.rs` | Incoming message dispatch and command handling | -| `server/src/chat/transport/discord/format.rs` | Markdown to Discord format conversion | -| `server/src/chat/transport/discord/gateway.rs` | Minimal Discord Gateway WebSocket client | -| `server/src/chat/transport/discord/history.rs` | Conversation history persistence | -| `server/src/chat/transport/discord/meta.rs` | `ChatTransport` implementation for Discord | - -### Chat — WhatsApp Transport - -| File | Description | -|------|-------------| -| `server/src/chat/transport/whatsapp/mod.rs` | WhatsApp Business API integration | -| `server/src/chat/transport/whatsapp/commands.rs` | Processes incoming messages as bot commands | -| `server/src/chat/transport/whatsapp/format.rs` | Markdown-to-WhatsApp conversion and message chunking | -| `server/src/chat/transport/whatsapp/history.rs` | Per-number history and messaging window tracking | -| `server/src/chat/transport/whatsapp/meta.rs` | Meta Cloud API transport via Graph API | -| `server/src/chat/transport/whatsapp/twilio.rs` | Twilio transport for sending/receiving messages | - -### Chat — Transport Abstraction - -| File | Description | -|------|-------------| -| `server/src/chat/transport/mod.rs` | Pluggable backends (Matrix, Slack, WhatsApp, Discord) | - -### LLM - -| File | Description | -|------|-------------| -| `server/src/llm/mod.rs` | Chat orchestration, prompts, OAuth, and provider integrations | -| `server/src/llm/chat.rs` | Multi-turn conversations with tool-calling LLM providers | -| `server/src/llm/oauth.rs` | Token refresh and credential management for Claude API | -| `server/src/llm/prompts.rs` | Static prompt templates for chat and onboarding | -| `server/src/llm/types.rs` | `Message`, `Role`, `ToolCall`, `ModelProvider` types | - -### LLM — Providers - -| File | Description | -|------|-------------| -| `server/src/llm/providers/mod.rs` | Module declarations for Anthropic, Claude Code, and Ollama | -| `server/src/llm/providers/anthropic.rs` | Streaming completion client for Claude Messages API | -| `server/src/llm/providers/claude_code.rs` | Runs Claude Code CLI in a PTY and parses output | -| `server/src/llm/providers/ollama.rs` | Streaming completion client for Ollama models | - -### Utilities - -| File | Description | -|------|-------------| -| `server/src/log_buffer.rs` | Bounded in-memory ring buffer for server log output | -| `server/src/rebuild.rs` | Server rebuild and restart logic | -| `server/src/workflow.rs` | Test result tracking and acceptance evaluation | -| `server/src/worktree.rs` | Creates, lists, and removes git worktrees for agent isolation | - -## License +See `.huskies/specs/tech/STACK.md` for the full source map. GPL-3.0. See [LICENSE](LICENSE).