# branch-workspace

Pi extension that gives each git branch its own workspace and a read-only / edit mode guard.

## Install

```bash
pi install npm:@po.dev/pi-branch-workspace
```

Or load locally:

```bash
pi -e ./branch-workspace/index.ts
```

## Features

- Each git branch gets `.pi/<branch>/workspace.md` injected as context every session
- **read-only mode** — reads and traces the codebase before answering; blocks direct writes outside `.pi/**` while allowing reads, `chmod`, and operations outside the project
- **edit mode** — full access; commits only when you explicitly run `/ws commit`
- Switching to edit mode automatically kicks off whatever was agreed on in the conversation
- `AGENTS.md` (or `.pi/agents.md`) injected as shared repo instructions

## Commands

```
/mode                  show current mode
/mode read-only, /mode r  switch to read-only
/mode edit, /mode e       switch to edit and start implementing
/r                       shortcut for read-only mode
/e                       shortcut for edit mode
/ws                    pick a workspace section to update from conversation
/ws plan               update the Plan section
/ws <section>          update or create any section
/ws commit             commit all uncommitted changes as "wip: <agent summary>"
```

## Workspace layout

```
.pi/
  agents.md                   shared repo instructions
  <branch>/
    workspace.md              plan, discussion, progress notes
    .mode                     current mode (read-only | edit)
```

## Mode rules

- Every session start / `/reload` resets `.mode` to `read-only` — `/mode edit` only lasts the current session
- Missing `.mode` → defaults to `read-only`
- Invalid value → resets to `read-only` with a warning
- In read-only mode, direct `write` and `edit` calls can change only `.pi/**`; `.mode` itself can still be changed only through `/mode`, `/r`, or `/e`