diff --git a/docs/SKILLS_FOR_HOST_AGENTS.md b/docs/SKILLS_FOR_HOST_AGENTS.md index 8f2ff72..565b10f 100644 --- a/docs/SKILLS_FOR_HOST_AGENTS.md +++ b/docs/SKILLS_FOR_HOST_AGENTS.md @@ -127,6 +127,19 @@ Before guessing about Coast behavior, explore the docs: coast docs --path concepts_and_terminology/BUILDS.md coast search-docs "your question here" # semantic search +## Troubleshooting + +If you run into issues with harness configuration (e.g. worktrees not being +found, `coast lookup` not matching), read the troubleshooting section of the +relevant harness doc: + + coast docs --path harnesses/CLAUDE_CODE.md + coast docs --path harnesses/CODEX.md + coast docs --path harnesses/CONDUCTOR.md + coast docs --path harnesses/CURSOR.md + coast docs --path harnesses/T3_CODE.md + coast docs --path harnesses/SHEP.md + ## Rules - Always run `coast lookup` before your first runtime command in a session. diff --git a/docs/harnesses/CLAUDE_CODE.md b/docs/harnesses/CLAUDE_CODE.md index 4ac44c8..2a7ebf5 100644 --- a/docs/harnesses/CLAUDE_CODE.md +++ b/docs/harnesses/CLAUDE_CODE.md @@ -131,6 +131,13 @@ api = "hot" - `.claude/worktrees/` — Claude Code worktrees - `~/.codex/worktrees/` — Codex worktrees if you also use Codex in this repo +## Troubleshooting + +- **Worktree not found** — If Coasts expects a worktree to exist but cannot + find it, verify that the Coastfile's `worktree_dir` includes + `.claude/worktrees`. See [Worktree Directories](../coastfiles/WORKTREE_DIR.md) + for syntax and path types. + ## Limitations - If you duplicate the same `/coasts` workflow across `CLAUDE.md`, diff --git a/docs/harnesses/CODEX.md b/docs/harnesses/CODEX.md index abdab5f..cbecb65 100644 --- a/docs/harnesses/CODEX.md +++ b/docs/harnesses/CODEX.md @@ -121,6 +121,13 @@ api = "hot" - `.claude/worktrees/` -- Claude Code (local, no special handling) - `~/.codex/worktrees/` -- Codex (external, bind-mounted) +## Troubleshooting + +- **Worktree not found** — If Coasts expects a worktree to exist but cannot + find it, verify that the Coastfile's `worktree_dir` includes + `~/.codex/worktrees`. See [Worktree Directories](../coastfiles/WORKTREE_DIR.md) + for syntax and path types. + ## Limitations - Codex may clean up worktrees at any time. The orphan detection in Coasts diff --git a/docs/harnesses/CONDUCTOR.md b/docs/harnesses/CONDUCTOR.md index 8e74f25..cd407f0 100644 --- a/docs/harnesses/CONDUCTOR.md +++ b/docs/harnesses/CONDUCTOR.md @@ -31,6 +31,8 @@ worktree_dir = [".worktrees", "~/conductor/workspaces/my-app"] Conductor allows you to configure the workspaces path per-repository, so the default `~/conductor/workspaces` may not match your setup. Check your Conductor repository settings to find the actual path and adjust accordingly — the principle is the same regardless of where the directory lives. +If you have more than one Conductor project configured for the same repository, each project creates workspaces under its own subdirectory (e.g. `~/conductor/workspaces/my-app-frontend`, `~/conductor/workspaces/my-app-backend`). The `worktree_dir` entry must match the directory name Conductor actually creates, so you may need multiple entries or need to update the path when switching between projects. + Coasts expands `~` at runtime and treats any path starting with `~/` or `/` as external. See [Worktree Directories](../coastfiles/WORKTREE_DIR.md) for details. @@ -99,6 +101,21 @@ api = "hot" - `~/conductor/workspaces/my-app/` — Conductor (external, bind-mounted; replace `my-app` with your repo folder name) +## Troubleshooting + +- **Worktree not found** — If Coasts expects a worktree to exist but cannot + find it, verify that the Coastfile's `worktree_dir` includes the correct + `~/conductor/workspaces/` path. The `` segment + must match the actual folder name Conductor creates under + `~/conductor/workspaces/`. See + [Worktree Directories](../coastfiles/WORKTREE_DIR.md) for syntax and path + types. +- **Multiple projects for the same repo** — If more than one Conductor project + is configured for the same repository, each project creates workspaces under + a different subdirectory. The `worktree_dir` must be updated to match the + directory Conductor dynamically creates for the active project. If you switch + between projects, the path changes and the Coastfile needs to reflect that. + ## Conductor Env Vars - Avoid relying on Conductor-specific environment variables (e.g., diff --git a/docs/harnesses/CURSOR.md b/docs/harnesses/CURSOR.md index 41395df..2120333 100644 --- a/docs/harnesses/CURSOR.md +++ b/docs/harnesses/CURSOR.md @@ -170,6 +170,15 @@ api = "hot" - `~/.codex/worktrees/` — Codex worktrees - `~/.cursor/worktrees/my-app/` — Cursor Parallel Agent worktrees +## Troubleshooting + +- **Worktree not found** — If Coasts expects a worktree to exist but cannot + find it, verify that the Coastfile's `worktree_dir` includes + `~/.cursor/worktrees/` and that `` matches the + actual folder name under `~/.cursor/worktrees/`. See + [Worktree Directories](../coastfiles/WORKTREE_DIR.md) for syntax and path + types. + ## Limitations - If you are not using Cursor Parallel Agents, do not add diff --git a/docs/harnesses/SHEP.md b/docs/harnesses/SHEP.md index 6cfc330..a40e126 100644 --- a/docs/harnesses/SHEP.md +++ b/docs/harnesses/SHEP.md @@ -115,3 +115,11 @@ Key points: - Different repos = different hashes - Path separators are normalized to `/` before hashing - The hash can be found via `shep feat show ` or `ls ~/.shep/repos` + +## Troubleshooting + +- **Worktree not found** — If Coasts expects a worktree to exist but cannot + find it, verify that the Coastfile's `worktree_dir` includes + `~/.shep/repos/*/wt`. The glob pattern must match Shep's directory structure. + See [Worktree Directories](../coastfiles/WORKTREE_DIR.md) for syntax and + path types. diff --git a/docs/harnesses/T3_CODE.md b/docs/harnesses/T3_CODE.md index 1b82953..725540a 100644 --- a/docs/harnesses/T3_CODE.md +++ b/docs/harnesses/T3_CODE.md @@ -106,6 +106,15 @@ api = "hot" - `~/.codex/worktrees/` — Codex (external, bind-mounted) - `~/.t3/worktrees/my-app/` — T3 Code (external, bind-mounted; replace `my-app` with your repo folder name) +## Troubleshooting + +- **Worktree not found** — If Coasts expects a worktree to exist but cannot + find it, verify that the Coastfile's `worktree_dir` includes + `~/.t3/worktrees/` and that `` matches the + actual folder name under `~/.t3/worktrees/`. See + [Worktree Directories](../coastfiles/WORKTREE_DIR.md) for syntax and path + types. + ## Limitations - Avoid relying on T3 Code-specific environment variables for runtime diff --git a/docs/skills_prompt.txt b/docs/skills_prompt.txt index 3f30328..dd06fe3 100644 --- a/docs/skills_prompt.txt +++ b/docs/skills_prompt.txt @@ -81,6 +81,19 @@ Before guessing about Coast behavior, explore the docs: coast docs --path concepts_and_terminology/BUILDS.md coast search-docs "your question here" # semantic search +## Troubleshooting + +If you run into issues with harness configuration (e.g. worktrees not being +found, `coast lookup` not matching), read the troubleshooting section of the +relevant harness doc: + + coast docs --path harnesses/CLAUDE_CODE.md + coast docs --path harnesses/CODEX.md + coast docs --path harnesses/CONDUCTOR.md + coast docs --path harnesses/CURSOR.md + coast docs --path harnesses/T3_CODE.md + coast docs --path harnesses/SHEP.md + ## Rules - Always run `coast lookup` before your first runtime command in a session.