docs: generalize worktree project examples (#299)

Remove maintainer-specific repo examples from `.worktrees/README.md` while keeping the structural boundary: agent-owned harness work lives under `agent/`, durable standalone repos live under `project/<owner>/<repo>/`.

Docs-only; tests not run.

Closes #298
This commit is contained in:
Ryan Eggleston authored and GitHub committed 2026-05-15 13:33:54 -06:00
1 parent d3f747b849
commit fedb23b3ad
2 files changed
+11 -12

No files matched your search

+10 -11
View File
@@ -23,11 +23,11 @@ or a legacy agent-owned clone that has not yet graduated to the project
layout. Do **not** put new long-lived external repos here just because an
agent will work on them.
Why this needed clarification: the first Mifune extraction clone went to
`.worktrees/agent/mifune` because this README previously allowed
"standalone agent-repo clones" under `agent/`. Mifune is a standalone
`ryaneggz/mifune` project repo, so its durable home is now
`.worktrees/project/ryaneggz/mifune/`.
Why this needed clarification: this README previously allowed
"standalone agent-repo clones" under `agent/`, which blurred the line
between agent identity and project ownership. New standalone repos should
use `project/<owner>/<repo>/` so the path reflects the remote project, not
which agent happened to clone it first.
See `.claude/rules/git.md` § Worktrees for the canonical workflow,
including the stale-worktree policy.
@@ -46,12 +46,11 @@ Example layout:
```
project/
ryaneggz/
mifune/ # https://github.com/ryaneggz/mifune.git
portfolio-advisor/ # https://github.com/ryaneggz/portfolio-advisor.git
acme/
web/ # https://github.com/acme/web.git
api/ # https://github.com/acme/api.git
<owner>/
<repo>/ # https://github.com/<owner>/<repo>.git
<other-repo>/ # https://github.com/<owner>/<other-repo>.git
<org>/
<repo>/ # https://github.com/<org>/<repo>.git
```
Create on demand:
+1 -1
View File
@@ -18,7 +18,7 @@ Update policy and release automation live in [`.claude/rules/git.md`](.claude/ru
- `.pi/overlays/docker-compose.slack.yml` and all references to it. The in-tree Pi extension at `.pi/extensions/slack/` reads `SLACK_APP_TOKEN` / `SLACK_BOT_TOKEN` directly from `process.env` at `session_start`, so the compose-time wiring overlay is redundant. `docs/integrations/slack.md`, `README.md`, `docs/architecture/container-runtime.md`, `docs/guide/bring-your-own-harness.md`, `.devcontainer/docker-compose.yml`, and `.devcontainer/.example.env` no longer reference the overlay; `.pi/overlays/` directory removed. Source of truth for Slack env wiring is `.pi/extensions/slack/README.md`.
### Changed
- `.worktrees/README.md` now reserves `.worktrees/project/<owner>/<repo>/` for durable standalone repo clones (e.g. `ryaneggz/mifune`) and narrows `.worktrees/agent/` to harness agent branches / legacy agent-owned clones, documenting why the Mifune extraction first landed in the wrong folder. ([#295](https://github.com/ryaneggz/open-harness/issues/295))
- `.worktrees/README.md` now reserves `.worktrees/project/<owner>/<repo>/` for durable standalone repo clones and narrows `.worktrees/agent/` to harness agent branches / legacy agent-owned clones, using generic examples so the layout applies cleanly to new users. ([#295](https://github.com/ryaneggz/open-harness/issues/295), [#298](https://github.com/ryaneggz/open-harness/issues/298))
- `oh config slack` wizard UX overhaul. Token prompts now echo `●` per keystroke (was: silent — looked frozen) via a TTY-aware raw-mode `askSecret` that handles backspace, Ctrl-U, and Ctrl-C; piped/non-TTY stdin still uses the legacy readline fallback as `askSecretPiped` so `echo "" | oh config slack` keeps working. Flow is reframed into four numbered steps `[1/4] … [4/4]` with inline "Where:" hints and clickable URLs (OSC 8 hyperlinks; fall back to `label (url)` on legacy terminals). Each input shows `✓ valid prefix` / `✓ N user(s) accepted` after validation. A final summary screen lists the keys (tokens redacted, IDs visible) and gates the env-file write behind a `Proceed? [Y/n]` confirmation. New helpers exported from `apps/oh/src/lib/prompt.ts`: `step()`, `link()`, `bold()`. Zero new runtime dependencies. ([#290](https://github.com/ryaneggz/open-harness/issues/290))
- Migrate `.pi/extensions/slack/{index,tools}.ts` from the deprecated `@mariozechner/pi-coding-agent` (and `@mariozechner/pi-agent-core`) to the upstream-recommended successors `@earendil-works/pi-coding-agent` (and `@earendil-works/pi-agent-core`). Per `npm view @mariozechner/pi-coding-agent`'s deprecation notice, the old package is no longer maintained. The other two in-tree extensions (`path-guard.ts`, `plan-mode/index.ts`) had already migrated; slack was the laggard. `.devcontainer/Dockerfile`'s `[pi-coding-agent]` mapping in the `PKG` array, `docs/agents/pi.md`'s upstream link, `docs/installation.md`'s Pi row, and `.pi/UPSTREAM.md`'s lineage label all updated to match. ([#281](https://github.com/ryaneggz/open-harness/issues/281))
- `docs/integrations/slack.md` § 5 leads with the new `oh config slack` wizard; the manual `set -a; source ...; tmux new-session` ritual is demoted to a `<details>` "Manual fallback" collapsible. Sections renumbered (8→7, 9→8). The wizard explicitly **starts the Slack bridge for you** at the end — kills any existing `agent-pi` tmux session, launches a fresh one running `pi` with the new env sourced, and polls `tmux capture-pane` for the `connected and listening` log line. ([#281](https://github.com/ryaneggz/open-harness/issues/281))