docs(claude-isolated-test): enhance skill with packnplay best practices - #295
Conversation
This empty commit triggers a new release to properly include the auto-updater fix from the previous release. Co-Authored-By: Claude <noreply@anthropic.com>
- Rename plugin directory: strategic-compact → auto-compact - Update all internal references: - State directory: ~/.claude/strategic-compact → ~/.claude/auto-compact - Environment variable: STRATEGIC_COMPACT_SESSION_ID → AUTO_COMPACT_SESSION_ID - Message prefix: [StrategicCompact] → [AutoCompact] - Refine terminology to clarify plugin behavior: - "Automatically suggests when to manually compact" - Core principle: "Auto Compact suggests; you decide when to compact" - Distinguish from forced auto-compaction - Update marketplace.json and plugin.json descriptions - All tests passing (32/32) Co-Authored-By: Claude <noreply@anthropic.com>
Add comprehensive documentation improvements based on testing: - Fix YAML name to match directory (claude-isolated-test) - Add Overview section with core principles - Add Core Concepts section (Container Isolation, Worktree Management, Credential Mounting) - Add Docker verification commands - Add Common Pitfalls table with 7 typical mistakes - Add Security Considerations section - Expand Quick Reference with attach, configure, env config commands - Improve description to focus on triggering conditions Co-Authored-By: Claude <noreply@anthropic.com>
📝 WalkthroughWalkthroughThis PR renames the strategic-compact plugin to auto-compact, updating its manifest entry, hooks, session management scripts, tests, and documentation. A new settings.local.json file grants PR creation permissions. State tracking timestamps and iteration counters are updated. The claude-isolated-test SKILL.md documentation is significantly expanded with operational guidance, configuration examples, and troubleshooting details. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 1 | ❌ 2❌ Failed checks (2 warnings)
✅ Passed checks (1 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing touches
🧪 Generate unit tests (beta)
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. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 Fix all issues with AI agents
In `@plugins/auto-compact/skills/auto-compact/SKILL.md`:
- Around line 35-120: The markdown has lint errors (MD022/MD031/MD060): add
blank lines before and after headings like "Messages You'll See", "Best
Practices", "When to Compact", and before/after fenced code blocks (the ```
blocks showing log messages and the bash snippet) and fix table pipe style to
match project rules (use leading and trailing pipes with single-space padding
around cell content) throughout SKILL.md (also apply same fixes to the other
affected section around lines 152-169); after making these spacing and pipe
adjustments, run markdownlint via the repository's pre-commit hook to validate
and commit the fixes.
In `@plugins/me/skills/claude-isolated-test/SKILL.md`:
- Around line 52-59: The file SKILL.md contains duplicate headings "Container
Isolation" and "Worktree Management" which trigger MD024; rename the later
occurrences to unique titles (e.g., "Container Isolation (per-session)" and
"Worktree Management (per-test)" or similar) so anchor links differ, then update
any internal links or references that pointed to the old anchors and run the
markdown linter to confirm MD024 is resolved; look for the headings named
"Container Isolation" and "Worktree Management" in the document and change the
later instances to unique labels.
- Around line 88-90: Fix the Markdown table spacing to satisfy markdownlint
MD060 by ensuring there is a single space on both sides of each pipe in the
tables (e.g., change "| Task | Command |" cells to have spaces around every "|"
so the header and all rows follow the compact style). Update the table block
shown (the header row and its following row entries) and apply the same spacing
fix to the other table blocks in this file that follow the same pattern so every
table has consistent " | " spacing between cells.
- Around line 50-60: Add blank lines before and after the Markdown headings
"Container Isolation" and "Worktree Management" and around the fenced code block
(the ```bash block showing worktree path) to satisfy markdownlint rules
MD022/MD031; ensure there is an empty line above each heading and both an empty
line before the opening ```bash and after the closing ``` (also apply the same
fixes for the similar section referenced later around the other fenced block).
🧹 Nitpick comments (2)
plugins/auto-compact/README.md (1)
40-43: Add language specifier to fenced code block.The code block showing example messages should have a language specifier to satisfy markdownlint (MD040). Since these are plain text messages, use
textorplaintext.📝 Proposed fix
-``` +```text [AutoCompact] 50 tool calls reached - consider /compact if transitioning phases [AutoCompact] 75 tool calls - good checkpoint for /compact if context is stale</details> </blockquote></details> <details> <summary>plugins/auto-compact/hooks/auto-compact.sh (1)</summary><blockquote> `19-27`: **Consider sourcing shared library instead of duplicating `validate_session_id`.** This function is duplicated from `lib/state.sh` (noted "local copy for now" in comment). Since `session-start-hook.sh` already sources this library successfully, consider doing the same here for maintainability. <details> <summary>♻️ Proposed fix</summary> ```diff set -euo pipefail -# Validate session_id format (local copy for now) -validate_session_id() { - local session_id="$1" - if [[ ! "$session_id" =~ ^[a-zA-Z0-9_-]+$ ]]; then - echo "Warning: Invalid session_id format: '$session_id'" >&2 - return 1 - fi - return 0 -} +# Source state library for validate_session_id +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +source "$SCRIPT_DIR/lib/state.sh"
| ### Messages You'll See | ||
|
|
||
| At threshold (default: 50): | ||
| ``` | ||
| [AutoCompact] 50 tool calls reached - consider /compact if transitioning phases | ||
| ``` | ||
|
|
||
| Every 25 calls after threshold: | ||
| ``` | ||
| [AutoCompact] 75 tool calls - good checkpoint for /compact if context is stale | ||
| ``` | ||
|
|
||
| ## Best Practices | ||
|
|
||
| ### When to Compact | ||
|
|
||
| **Good timing:** | ||
| - After exploration phase, before implementation | ||
| - After completing a milestone (feature, bugfix, refactor) | ||
| - Before starting new unrelated task | ||
| - When context feels stale or repetitive | ||
| - After debugging, before writing fix | ||
|
|
||
| **Bad timing:** | ||
| - Mid-implementation of current task | ||
| - Before understanding the problem | ||
| - When actively debugging | ||
| - During code review feedback | ||
|
|
||
| ### Compaction Strategy | ||
|
|
||
| **What to keep:** | ||
| - Current task context and requirements | ||
| - Relevant architectural decisions | ||
| - Recent test results | ||
| - Current debugging findings | ||
|
|
||
| **What to summarize:** | ||
| - Completed implementation details | ||
| - Historical conversation not relevant to current task | ||
| - Explored alternatives not chosen | ||
| - Past debugging attempts | ||
|
|
||
| ### Workflow Integration | ||
|
|
||
| 1. **Exploration phase**: Read code, understand problem | ||
| 2. **Compact**: `/compact` - summarize findings, preserve context | ||
| 3. **Implementation phase**: Write code, test | ||
| 4. **Compact**: `/compact` - preserve implementation context | ||
| 5. **Next phase**: Repeat as needed | ||
|
|
||
| ## Configuration | ||
|
|
||
| ### Custom Threshold | ||
|
|
||
| Set `COMPACT_THRESHOLD` to customize when suggestions appear: | ||
|
|
||
| ```bash | ||
| # In your shell profile or session | ||
| export COMPACT_THRESHOLD=100 # Suggest after 100 tool calls | ||
| ``` | ||
|
|
||
| Default: 50 tool calls | ||
|
|
||
| ### State Directory | ||
|
|
||
| Session counters stored in: | ||
| ``` | ||
| ~/.claude/auto-compact/tool-count-{session_id}.txt | ||
| ``` | ||
|
|
||
| Session ID extracted from SessionStart hook and stored in: | ||
| ``` | ||
| ~/.claude/auto-compact/session-env.sh | ||
| ``` | ||
|
|
||
| ## Why Suggestions Over Forced Auto-Compaction? | ||
|
|
||
| **Forced auto-compaction problems:** | ||
| - Happens at arbitrary points, often mid-task | ||
| - Loses critical context during active work | ||
| - Interrupts thought processes | ||
| - Difficult to resume after compaction | ||
|
|
||
| **Auto Compact benefits:** | ||
| - You control when compaction occurs |
There was a problem hiding this comment.
Fix markdownlint spacing and table pipe style.
markdownlint reports MD022/MD031/MD060 here; add blank lines around headings and fenced code blocks, and adjust table pipe spacing to match the configured style. As per coding guidelines: Run markdownlint on all Markdown files using pre-commit hooks.
Also applies to: 152-169
🧰 Tools
🪛 markdownlint-cli2 (0.20.0)
[warning] 52-52: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 58-58: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 59-59: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 77-77: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 89-89: Table column style
Table pipe is missing space to the right for style "compact"
(MD060, table-column-style)
[warning] 89-89: Table column style
Table pipe is missing space to the left for style "compact"
(MD060, table-column-style)
[warning] 89-89: Table column style
Table pipe is missing space to the right for style "compact"
(MD060, table-column-style)
[warning] 89-89: Table column style
Table pipe is missing space to the left for style "compact"
(MD060, table-column-style)
[warning] 106-106: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 111-111: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 120-120: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
🤖 Prompt for AI Agents
In `@plugins/auto-compact/skills/auto-compact/SKILL.md` around lines 35 - 120, The
markdown has lint errors (MD022/MD031/MD060): add blank lines before and after
headings like "Messages You'll See", "Best Practices", "When to Compact", and
before/after fenced code blocks (the ``` blocks showing log messages and the
bash snippet) and fix table pipe style to match project rules (use leading and
trailing pipes with single-space padding around cell content) throughout
SKILL.md (also apply same fixes to the other affected section around lines
152-169); after making these spacing and pipe adjustments, run markdownlint via
the repository's pre-commit hook to validate and commit the fixes.
| ## Core Concepts | ||
|
|
||
| ### Container Isolation | ||
| Each Claude session runs in a separate Docker container with: | ||
| - **Independent filesystem** - changes don't affect host | ||
| - **Isolated environment** - clean state for each test | ||
| - **Host path preservation** - project mounted at same path as host | ||
|
|
||
| ### Worktree Management | ||
| ```bash | ||
| # Worktrees stored at: ~/.local/share/packnplay/worktrees/<project>/<worktree> |
There was a problem hiding this comment.
Add blank lines around headings and fenced blocks to satisfy markdownlint.
MD022/MD031 are triggered in this area. Add a blank line before/after headings and fenced code blocks.
🔧 Proposed fix (example for this section)
## Core Concepts
-
### Container Isolation
Each Claude session runs in a separate Docker container with:
@@
-### Worktree Management
-```bash
+### Worktree Management
+
+```bash
# Worktrees stored at: ~/.local/share/packnplay/worktrees/<project>/<worktree>Also applies to: 72-79
🧰 Tools
🪛 markdownlint-cli2 (0.20.0)
[warning] 52-52: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 58-58: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 59-59: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
🤖 Prompt for AI Agents
In `@plugins/me/skills/claude-isolated-test/SKILL.md` around lines 50 - 60, Add
blank lines before and after the Markdown headings "Container Isolation" and
"Worktree Management" and around the fenced code block (the ```bash block
showing worktree path) to satisfy markdownlint rules MD022/MD031; ensure there
is an empty line above each heading and both an empty line before the opening
```bash and after the closing ``` (also apply the same fixes for the similar
section referenced later around the other fenced block).
| ### Container Isolation | ||
| Each Claude session runs in a separate Docker container with: | ||
| - **Independent filesystem** - changes don't affect host | ||
| - **Isolated environment** - clean state for each test | ||
| - **Host path preservation** - project mounted at same path as host | ||
|
|
||
| ### Worktree Management | ||
| ```bash |
There was a problem hiding this comment.
Avoid duplicate headings (“Container Isolation”, “Worktree Management”).
MD024 is flagged; duplicate headings can confuse anchor links. Consider renaming the later ones to make anchors unique.
✏️ Example rename to make anchors unique
-### Container Isolation
+### Container Isolation (Security)
@@
-## Worktree Management
+## Worktree Management (Advanced)Also applies to: 339-345, 367-373
🧰 Tools
🪛 markdownlint-cli2 (0.20.0)
[warning] 52-52: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 58-58: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 59-59: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
🤖 Prompt for AI Agents
In `@plugins/me/skills/claude-isolated-test/SKILL.md` around lines 52 - 59, The
file SKILL.md contains duplicate headings "Container Isolation" and "Worktree
Management" which trigger MD024; rename the later occurrences to unique titles
(e.g., "Container Isolation (per-session)" and "Worktree Management (per-test)"
or similar) so anchor links differ, then update any internal links or references
that pointed to the old anchors and run the markdown linter to confirm MD024 is
resolved; look for the headings named "Container Isolation" and "Worktree
Management" in the document and change the later instances to unique labels.
| | Task | Command | | ||
| |------|---------| | ||
| | Install | `go install github.com/obra/packnplay@latest` | | ||
| | Run | `packnplay run claude` | | ||
| | Install (Homebrew) | `brew install obra/tap/packnplay` | |
There was a problem hiding this comment.
Fix table pipe spacing to match markdownlint “compact” style.
MD060 flags missing spaces around table pipes.
🧩 Proposed fix (apply similarly to all tables)
-| Task | Command |
-|------|---------|
+| Task | Command |
+| --- | --- |Also applies to: 295-297, 327-329, 357-359
🧰 Tools
🪛 markdownlint-cli2 (0.20.0)
[warning] 89-89: Table column style
Table pipe is missing space to the right for style "compact"
(MD060, table-column-style)
[warning] 89-89: Table column style
Table pipe is missing space to the left for style "compact"
(MD060, table-column-style)
[warning] 89-89: Table column style
Table pipe is missing space to the right for style "compact"
(MD060, table-column-style)
[warning] 89-89: Table column style
Table pipe is missing space to the left for style "compact"
(MD060, table-column-style)
🤖 Prompt for AI Agents
In `@plugins/me/skills/claude-isolated-test/SKILL.md` around lines 88 - 90, Fix
the Markdown table spacing to satisfy markdownlint MD060 by ensuring there is a
single space on both sides of each pipe in the tables (e.g., change "| Task |
Command |" cells to have spaces around every "|" so the header and all rows
follow the compact style). Update the table block shown (the header row and its
following row entries) and apply the same spacing fix to the other table blocks
in this file that follow the same pattern so every table has consistent " | "
spacing between cells.
Resolve marketplace.json conflict by including new plugins from main: - auto-compact - auto-updater - lsp-support - memory-persistence Co-Authored-By: Claude <noreply@anthropic.com>
1 participant
Summary
claude-isolated-test)Test plan
🤖 Generated with Claude Code
Summary by CodeRabbit
New Features
Documentation
✏️ Tip: You can customize this high-level summary in your review settings.