crashlabs/huskies
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 26 Wiki Activity

chore: feed CONTEXT and STACK specs to all agents, update STACK with source map

Browse Source 
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) <noreply@anthropic.com>
This commit is contained in:
dave
2026-04-15 18:08:16 +00:00
parent beb84ade9f
commit a4480fa067
3 changed files with 120 additions and 397 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.huskies/agents.toml
+7 -7
View File
@@ -5,7 +5,7 @@ role = "Full-stack engineer. Implements features across all components."
model = "sonnet" model = "sonnet"
max_turns = 50 max_turns = 50
max_budget_usd = 5.00 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." 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]] [[agent]]
@@ -15,7 +15,7 @@ role = "Full-stack engineer. Implements features across all components."
model = "sonnet" model = "sonnet"
max_turns = 50 max_turns = 50
max_budget_usd = 5.00 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." 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]] [[agent]]
@@ -25,7 +25,7 @@ role = "Full-stack engineer. Implements features across all components."
model = "sonnet" model = "sonnet"
max_turns = 50 max_turns = 50
max_budget_usd = 5.00 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." 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]] [[agent]]
@@ -37,7 +37,7 @@ max_turns = 40
max_budget_usd = 4.00 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. 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 ## Your Workflow
@@ -126,7 +126,7 @@ role = "Senior full-stack engineer for complex tasks. Implements features across
model = "opus" model = "opus"
max_turns = 80 max_turns = 80
max_budget_usd = 20.00 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." 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]] [[agent]]
@@ -138,7 +138,7 @@ max_turns = 40
max_budget_usd = 4.00 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. 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 ## Your Workflow
@@ -229,7 +229,7 @@ max_turns = 30
max_budget_usd = 5.00 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. 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 ## Your Workflow
1. Call merge_agent_work(story_id='{{story_id}}'). It blocks until the merge completes and returns the full result. 1. Call merge_agent_work(story_id='{{story_id}}'). It blocks until the merge completes and returns the full result.
.huskies/specs/tech/STACK.md
+112 -112
View File
@@ -1,130 +1,130 @@
# Tech Stack & Constraints # Tech Stack
## Overview ## Backend
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. - **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 ## Frontend
* **Backend:** Rust (Web Server) - **Language:** TypeScript + React
* **MSRV:** Stable (latest) - **Build:** Vite
* **Framework:** Poem HTTP server with WebSocket support for streaming; HTTP APIs should use Poem OpenAPI (Swagger) for non-streaming endpoints. - **Package manager:** npm
* **Frontend:** TypeScript + React - **Testing:** Vitest (unit), Playwright (e2e)
* **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.
## Agent Architecture ## Deployment
The application follows a **Tool-Use (Function Calling)** architecture: - Single Rust binary with embedded React frontend (rust-embed)
1. **Frontend:** Collects user input and sends it to the LLM. - Three modes: standard server, headless build agent (`--rendezvous`), multi-project gateway (`--gateway`)
2. **LLM:** Decides to generate text OR request a **Tool Call** (e.g., `execute_shell`, `read_file`). - Docker container with OrbStack recommended on macOS
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.
## LLM Provider Abstraction ## Project Layout
To support both Remote and Local models, the system implements a `ModelProvider` abstraction layer. ```
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:** ## Source Map
* 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)
## Tooling Capabilities ### Core
### 1. Filesystem (Native) | File | Description |
* **Scope:** Strictly limited to the user-selected `project_root`. |------|-------------|
* **Operations:** Read, Write, List, Delete. | `server/src/main.rs` | Entry point, CLI argument parsing, and server startup |
* **Constraint:** Modifications to `.git/` are strictly forbidden via file APIs (use Git tools instead). | `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 ### Agents
* **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`
### 3. Search & Navigation | File | Description |
* **Library:** `ignore` (by BurntSushi) + `grep` logic. |------|-------------|
* **Behavior:** | `server/src/agents/mod.rs` | Types, configuration, and orchestration for coding agents |
* Must respect `.gitignore` files automatically. | `server/src/agents/gates.rs` | Runs test suites and validation scripts in agent worktrees |
* Must be performant (parallel traversal). | `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 | File | Description |
* **Style:** `rustfmt` standard. |------|-------------|
* **Linter:** `clippy` - Must pass with 0 warnings before merging. | `server/src/agents/pool/mod.rs` | Manages the set of active agents across all pipeline stages |
* **Error Handling:** Custom `AppError` type deriving `thiserror`. All Commands return `Result<T, AppError>`. | `server/src/agents/pool/start.rs` | Spawns a new agent process in a worktree for a story |
* **Concurrency:** Heavy tools (Search, Shell) must run on `tokio` threads to avoid blocking the UI. | `server/src/agents/pool/stop.rs` | Terminates a running agent while preserving its worktree |
* **Quality Gates:** | `server/src/agents/pool/pipeline/advance.rs` | Moves stories forward through pipeline stages |
* `cargo clippy --all-targets --all-features` must show 0 errors, 0 warnings | `server/src/agents/pool/pipeline/completion.rs` | Processes exit results and triggers pipeline advancement |
* `cargo check` must succeed | `server/src/agents/pool/pipeline/merge.rs` | Orchestrates the merge-to-master flow for completed stories |
* `cargo nextest run` must pass all tests | `server/src/agents/pool/auto_assign/auto_assign.rs` | Scans pipeline stages and dispatches agents to unassigned stories |
* **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)
### TypeScript / React ### CRDT & Database
* **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
## Libraries (Approved) | File | Description |
* **Rust:** |------|-------------|
* `serde`, `serde_json`: Serialization. | `server/src/crdt_state.rs` | Pipeline state as a conflict-free replicated document backed by SQLite |
* `ignore`: Fast recursive directory iteration respecting gitignore. | `server/src/crdt_sync.rs` | WebSocket-based replication of pipeline state between nodes |
* `walkdir`: Simple directory traversal. | `server/src/pipeline_state.rs` | Typed pipeline state machine |
* `tokio`: Async runtime. | `server/src/db/mod.rs` | Content store, shadow writes, and CRDT op persistence |
* `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.
## 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` ### Chat — Bot Commands
- **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`
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 ### Chat — Transports
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:** | File | Description |
* Shell commands that modify state (non-readonly) should ideally require a UI confirmation (configurable). |------|-------------|
* File writes must be confirmed or revertible. | `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`)
README.md
+1 -278
View File
@@ -220,283 +220,6 @@ Both return a JSON document with:
## Source Map ## Source Map
### Core See `.huskies/specs/tech/STACK.md` for the full source map.
| 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
GPL-3.0. See [LICENSE](LICENSE). GPL-3.0. See [LICENSE](LICENSE).