Skip to content

Add workspace isolation directive - #17

Merged
pertrai1 merged 3 commits into
mainfrom
feat/workspace-isolation-directive
May 9, 2026
Merged

pertrai1 merged 3 commits into
mainfrom
feat/workspace-isolation-directive

Conversation

@pertrai1

@pertrai1 pertrai1 commented May 9, 2026 •

Copy link
Copy Markdown
Owner

Summary

  • add a native-first workspace isolation directive with git worktree fallback
  • teach adaptive routing when to add the Workspace Isolation path
  • update repo inventories/templates and add eval coverage plus a decision log

Verification

Functional

  • Hit: routing can now add directives/workspace-isolation.md when repo edits start from a shared/default checkout.
  • Clean: review/docs-only routing remains separate; the new path is conditional rather than loaded by default.

Documentation

  • README updated with the new directive and directive count
  • Root AGENTS and templates updated to list the new directive
  • Eval scenario added for workspace-isolation routing behavior
  • Decision log added for the directive-vs-skill and native-first tradeoff

Integration

  • Adaptive routing references the new directive and path
  • User-facing inventories point to the new directive file
  • The new directive frontmatter is routable for implementation/debugging work
  • No unrelated repo surfaces were changed

Scope Control

Planned scope budget: touch directives/workspace-isolation.md, directives/adaptive-routing.md, README.md, AGENTS.md, templates/*.md, and one evals/scenarios/*.md file; do not change unrelated directives, skills, or the eval runner unless evidence shows they are required.
Scope control: changed only the planned directive/router/docs/template/eval/decision-log surfaces; no unrelated cleanup, new dependency, or eval-runner change was included.

Checks

  • git diff --check
  • targeted Python validation for directive wiring, frontmatter, and decision-log metadata

Summary by CodeRabbit

  • New Features

    • Introduced Workspace Isolation directive to protect mutable work using native workspace tooling with git fallback.
  • Documentation

    • Updated workflow documentation and agent instructions to include Workspace Isolation guidance.
    • Added evaluation scenario and decision documentation for workspace isolation routing.
    • Enhanced adaptive routing directive to support workspace isolation for shared checkouts.

Review Change Stack

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@coderabbitai

coderabbitai Bot commented May 9, 2026 •

Copy link
Copy Markdown

Warning

Rate limit exceeded

@pertrai1 has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 45 minutes and 19 seconds before requesting another review.

You’ve run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 4d067e0b-a9b4-4bc1-93fc-cfab539e8cba

📥 Commits

Reviewing files that changed from the base of the PR and between 6555348 and be7a9e2.

📒 Files selected for processing (7)
  • AGENTS.md
  • README.md
  • directives/adaptive-routing.md
  • directives/workspace-isolation.md
  • templates/AGENTS.md
  • templates/CLAUDE.md
  • templates/copilot-instructions.md
📝 Walkthrough

Walkthrough

This PR introduces a new Workspace Isolation directive to the agent-directives repository. The directive enables agents to protect mutable, git-backed work by detecting existing isolation, preferring native workspace mechanisms, falling back to git worktree when needed, and performing baseline verification before editing. The directive is routed conditionally through adaptive routing and documented across templates and evaluation scenarios.

Changes

Workspace Isolation Directive & Routing

Layer / File(s) Summary
Decision & Specification
docs/decisions/2026-05-09-workspace-isolation-routing.md
Establishes workspace isolation as a routed, tool-agnostic directive using native-tool-first behavior with git worktree fallback; documents decision context, rejected alternatives, and consequences.
Directive Implementation
directives/workspace-isolation.md
Defines isolation workflow: Step 0 detects linked worktrees, Step 1 selects native mechanisms or falls back to git, Step 2 runs project setup, Step 3 requires baseline proof, Step 4 constrains fallback conditions. Includes forbidden patterns and quick reference table.
Routing Integration
directives/adaptive-routing.md
Adds Workspace Isolation Path option for tasks mutating shared/protected checkouts with unrelated local changes; updates risk escalation and quick reference tables to route isolation requests.
Documentation & Summary
AGENTS.md, README.md
Clarifies that directives/*.md define workflow rules; adds Workspace Isolation section describing isolation detection, tooling preference, fallback behavior, and setup/baseline requirements.
Template Synchronization
templates/AGENTS.md, templates/CLAUDE.md, templates/copilot-instructions.md
Updates agent instruction templates to include Workspace Isolation directive in routed directive lists after Adaptive Routing.
Evaluation & Testing
evals/scenarios/workspace-isolation-routing.md
Defines scenario for testing routing expectations, including agent behavior (selecting isolation path, detecting existing isolation, preferring native tools, requesting consent), anti-patterns, and quality criteria.

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly Related PRs

  • pertrai1/agent-directives#5: Extends adaptive-routing workflow by adding the Workspace Isolation directive and routing path integration.
  • pertrai1/agent-directives#16: Modifies directives/adaptive-routing.md in earlier work on routing output and manifest guidance that this PR builds upon.
  • pertrai1/agent-directives#6: Follows the same pattern of adding a new routed directive with adaptive-routing and template wiring.
🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title 'Add workspace isolation directive' is clear, concise, and directly summarizes the main change—introducing a new workspace isolation directive to the codebase.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch feat/workspace-isolation-directive

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 6555348b0d

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread directives/workspace-isolation.md Outdated
Comment on lines +120 to +122
If the chosen directory is not ignored, add that directory to `.gitignore`
before creating the worktree. Do not leave project-local worktree contents
visible to `git status`.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Avoid dirtying the protected checkout before isolation

When isolation is needed because the current checkout is main/shared or already has unrelated local changes, this instruction makes the agent edit the tracked .gitignore in that same checkout before the worktree exists. That is a repo mutation in the workspace the directive is meant to protect, can conflict with the user's unrelated changes, and can be accidentally swept into the task commit; prefer an already-ignored location, .git/info/exclude, or an outside-repo worktree unless the user explicitly consents to changing .gitignore.

Useful? React with 👍 / 👎.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 2

🧹 Nitpick comments (2)
evals/scenarios/workspace-isolation-routing.md (2)

22-35: ⚡ Quick win

Consider adding explicit git worktree fallback test.

The expected behaviors comprehensively cover the workflow, but item 5 states "Agent prefers a native workspace/worktree tool if one exists" without an explicit checkpoint for the fallback case. Consider adding:

- [ ] Agent falls back to `git worktree` when no native workspace tool is available.

This would explicitly test both branches of the "native-first with git worktree fallback" design mentioned in the PR objectives.

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@evals/scenarios/workspace-isolation-routing.md` around lines 22 - 35, Add an
explicit checklist item to the "Expected Behaviors" section to test the git
worktree fallback path: update the list near the existing item "Agent prefers a
native workspace/worktree tool if one exists" (in the Expected Behaviors block)
to include a new entry like "Agent falls back to `git worktree` when no native
workspace tool is available" so both native-first and fallback branches are
asserted.

1-64: ⚡ Quick win

Consider adding execution instructions.

The scenario provides comprehensive test criteria but doesn't explain how to execute it. Based on learnings, scenarios can be exercised using evals/run-scenario.sh <scenario-name>. Consider adding an "Execution" section that references the execution method:

## Execution

Run this scenario using:

./evals/run-scenario.sh workspace-isolation-routing


This would improve usability for reviewers or contributors running the scenario. As per coding guidelines, eval scenarios serve as behavioral tests and should be executable.

<details>
<summary>🤖 Prompt for AI Agents</summary>

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @evals/scenarios/workspace-isolation-routing.md around lines 1 - 64, Add an
"Execution" section to the workspace-isolation-routing scenario
(evals/scenarios/workspace-isolation-routing.md) that instructs reviewers how to
run the test, e.g., tell them to run the scenario with the existing runner
script by invoking evals/run-scenario.sh workspace-isolation-routing; place this
section near the top or bottom of the file so it's visible to contributors and
clearly labeled "Execution" and include the exact command to execute the
scenario.


</details>

</blockquote></details>

</blockquote></details>

<details>
<summary>🤖 Prompt for all review comments with AI agents</summary>

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @directives/workspace-isolation.md:

  • Around line 53-57: Add a pre-check using "git rev-parse --is-inside-work-tree"
    before computing GIT_DIR, GIT_COMMON and BRANCH so the script exits early to the
    "directive does not apply" path when not in a git repo; specifically, in the
    block that sets GIT_DIR, GIT_COMMON and BRANCH add a guard that runs git
    rev-parse --is-inside-work-tree >/dev/null 2>&1 and on failure echoes
    "Repository is not git-backed; workspace-isolation directive does not apply."
    and exits 0 (matching the behavior used at the directive does not apply path
    referenced around the existing lines handling non-applicability).
  • Around line 120-122: Update the workspace-isolation guidance to remove the
    directive that automatically edits .gitignore during worktree creation; instead
    instruct the operator to choose a directory already ignored by git or to prompt
    for explicit consent before modifying tracked files, referencing the actions
    "add that directory to .gitignore" and "creating the worktree" so readers know
    which steps to change.

Nitpick comments:
In @evals/scenarios/workspace-isolation-routing.md:

  • Around line 22-35: Add an explicit checklist item to the "Expected Behaviors"
    section to test the git worktree fallback path: update the list near the
    existing item "Agent prefers a native workspace/worktree tool if one exists" (in
    the Expected Behaviors block) to include a new entry like "Agent falls back to
    git worktree when no native workspace tool is available" so both native-first
    and fallback branches are asserted.
  • Around line 1-64: Add an "Execution" section to the
    workspace-isolation-routing scenario
    (evals/scenarios/workspace-isolation-routing.md) that instructs reviewers how to
    run the test, e.g., tell them to run the scenario with the existing runner
    script by invoking evals/run-scenario.sh workspace-isolation-routing; place this
    section near the top or bottom of the file so it's visible to contributors and
    clearly labeled "Execution" and include the exact command to execute the
    scenario.

</details>

<details>
<summary>🪄 Autofix (Beta)</summary>

Fix all unresolved CodeRabbit comments on this PR:

- [ ] <!-- {"checkboxId": "4b0d0e0a-96d7-4f10-b296-3a18ea78f0b9"} --> Push a commit to this branch (recommended)
- [ ] <!-- {"checkboxId": "ff5b1114-7d8c-49e6-8ac1-43f82af23a33"} --> Create a new PR with the fixes

</details>

---

<details>
<summary>ℹ️ Review info</summary>

<details>
<summary>⚙️ Run configuration</summary>

**Configuration used**: Organization UI

**Review profile**: CHILL

**Plan**: Pro

**Run ID**: `5e71ce91-5bd7-41eb-9b2c-0b860b95377e`

</details>

<details>
<summary>📥 Commits</summary>

Reviewing files that changed from the base of the PR and between c5ab9ba3032a580879fc48d91478aa412ea32268 and 6555348b0d334634f1207e9182ed24602a05772e.

</details>

<details>
<summary>📒 Files selected for processing (9)</summary>

* `AGENTS.md`
* `README.md`
* `directives/adaptive-routing.md`
* `directives/workspace-isolation.md`
* `docs/decisions/2026-05-09-workspace-isolation-routing.md`
* `evals/scenarios/workspace-isolation-routing.md`
* `templates/AGENTS.md`
* `templates/CLAUDE.md`
* `templates/copilot-instructions.md`

</details>

</details>

<!-- This is an auto-generated comment by CodeRabbit for review status -->

Comment thread directives/workspace-isolation.md
Comment thread directives/workspace-isolation.md Outdated
pertrai1 and others added 2 commits May 9, 2026 13:46
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@pertrai1
pertrai1 merged commit 2f067d3 into main May 9, 2026
1 check passed
@pertrai1
pertrai1 deleted the feat/workspace-isolation-directive branch May 9, 2026 17:53
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant