docs(03): capture phase context
This commit is contained in:
parent
a15d4b11d8
commit
8e900862f9
2 changed files with 171 additions and 0 deletions
97
.planning/phases/03-sandbox-aware-prompting/03-CONTEXT.md
Normal file
97
.planning/phases/03-sandbox-aware-prompting/03-CONTEXT.md
Normal file
|
|
@ -0,0 +1,97 @@
|
||||||
|
# Phase 3: Sandbox-Aware Prompting - Context
|
||||||
|
|
||||||
|
**Gathered:** 2026-04-09
|
||||||
|
**Status:** Ready for planning
|
||||||
|
|
||||||
|
<domain>
|
||||||
|
## Phase Boundary
|
||||||
|
|
||||||
|
Inject sandbox context into Claude Code sessions so Claude knows its capabilities and constraints automatically on session start. Two files: a managed SANDBOX.md with sandbox context, and a reference line in CLAUDE.md that imports it via `@` syntax. Zero tool-use overhead.
|
||||||
|
|
||||||
|
</domain>
|
||||||
|
|
||||||
|
<decisions>
|
||||||
|
## Implementation Decisions
|
||||||
|
|
||||||
|
### File architecture
|
||||||
|
- **D-01:** Two-file approach. claudebox manages `~/.claudebox/SANDBOX.md` (sandbox context) and ensures `~/.claudebox/CLAUDE.md` has an `@SANDBOX.md` import at the top. Since `~/.claudebox` is bind-mounted as `~/.claude` inside the sandbox, Claude Code auto-loads both files at session start.
|
||||||
|
- **D-02:** `SANDBOX.md` is fully owned by claudebox — overwritten on every launch. User should not edit this file; changes are lost on next run.
|
||||||
|
- **D-03:** `CLAUDE.md` is user-owned. claudebox only ensures the `@SANDBOX.md` import line exists at the top. If missing, it's re-added. All other content is untouched.
|
||||||
|
|
||||||
|
### SANDBOX.md content
|
||||||
|
- **D-04:** Friendly guide tone — short prose paragraphs, not terse bullets. Sections: sandbox overview, installing tools (comma + nix shell with examples), default restrictions (phrased as "by default, not mounted" to avoid contradicting user customizations), git setup.
|
||||||
|
- **D-05:** Default restrictions use "by default" phrasing: "By default, the following are not mounted into the sandbox: SSH keys, GPG/age keys, cloud credentials, Tailscale." Includes note: "If your setup has been customized, some of these may be available."
|
||||||
|
- **D-06:** Git section notes identity is pre-configured (name/email) and suggests HTTPS for remotes by default. Mentions safe.directory is set.
|
||||||
|
|
||||||
|
### Import mechanism
|
||||||
|
- **D-07:** Uses Claude Code's `@path` import syntax in CLAUDE.md. `@SANDBOX.md` at the first line. This is auto-expanded at session start — no Read tool call needed.
|
||||||
|
|
||||||
|
### Launch-time behavior
|
||||||
|
- **D-08:** On every launch, claudebox: (1) writes/overwrites `~/.claudebox/SANDBOX.md` with current content, (2) checks if `~/.claudebox/CLAUDE.md` exists — creates it with just the import line if not, (3) if CLAUDE.md exists, checks first line for the `@SANDBOX.md` import — prepends it if missing.
|
||||||
|
|
||||||
|
### Claude's Discretion
|
||||||
|
- Exact prose wording and section ordering in SANDBOX.md
|
||||||
|
- How the first-line check works in shell (grep, head, etc.)
|
||||||
|
- Whether to use a comment marker around the import line for robustness
|
||||||
|
|
||||||
|
</decisions>
|
||||||
|
|
||||||
|
<canonical_refs>
|
||||||
|
## Canonical References
|
||||||
|
|
||||||
|
**Downstream agents MUST read these before planning or implementing.**
|
||||||
|
|
||||||
|
### Project Docs
|
||||||
|
- `.planning/PROJECT.md` -- Core value, constraints, key decisions
|
||||||
|
- `.planning/REQUIREMENTS.md` -- AWARE-01, AWARE-02 requirement definitions
|
||||||
|
- `.planning/ROADMAP.md` -- Phase 3 success criteria
|
||||||
|
|
||||||
|
### Prior Phase Context
|
||||||
|
- `.planning/phases/01-minimal-viable-sandbox/01-CONTEXT.md` -- D-02 (comma-with-db), D-05 (git identity generation), sandbox mount structure
|
||||||
|
- `.planning/phases/02-env-audit-and-cli-polish/02-CONTEXT.md` -- D-08 (--yes flag), existing flag parsing pattern
|
||||||
|
|
||||||
|
### Implementation
|
||||||
|
- `claudebox.sh` -- Current script, `mkdir -p ~/.claudebox` already runs at launch (line 102), bind-mount of `~/.claudebox` as `~/.claude` (line 294)
|
||||||
|
- `flake.nix` -- Nix derivation structure
|
||||||
|
|
||||||
|
</canonical_refs>
|
||||||
|
|
||||||
|
<code_context>
|
||||||
|
## Existing Code Insights
|
||||||
|
|
||||||
|
### Reusable Assets
|
||||||
|
- `mkdir -p "$HOME/.claudebox"` (line 102) -- already ensures the directory exists before any file operations
|
||||||
|
- Existing ANSI color variables (BOLD, RESET, etc.) -- available if any output is needed during SANDBOX.md generation
|
||||||
|
|
||||||
|
### Established Patterns
|
||||||
|
- `writeShellApplication` with shellcheck and `set -euo pipefail`
|
||||||
|
- Temp file pattern with trap cleanup (used for .gitconfig)
|
||||||
|
- Flag parsing via while/case/esac
|
||||||
|
|
||||||
|
### Integration Points
|
||||||
|
- SANDBOX.md generation goes after `mkdir -p "$HOME/.claudebox"` and before the bwrap exec
|
||||||
|
- CLAUDE.md import check runs alongside SANDBOX.md generation
|
||||||
|
- No new flags needed -- this is automatic on every launch
|
||||||
|
|
||||||
|
</code_context>
|
||||||
|
|
||||||
|
<specifics>
|
||||||
|
## Specific Ideas
|
||||||
|
|
||||||
|
- `@SANDBOX.md` import resolves inside the sandbox because `~/.claudebox` becomes `~/.claude` -- the path is relative to CLAUDE.md's location
|
||||||
|
- SANDBOX.md is a heredoc in claudebox.sh (simplest, no extra files in the derivation)
|
||||||
|
- First-line check: if `head -1 ~/.claudebox/CLAUDE.md` doesn't contain `@SANDBOX.md`, prepend it
|
||||||
|
|
||||||
|
</specifics>
|
||||||
|
|
||||||
|
<deferred>
|
||||||
|
## Deferred Ideas
|
||||||
|
|
||||||
|
None -- discussion stayed within phase scope
|
||||||
|
|
||||||
|
</deferred>
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
*Phase: 03-sandbox-aware-prompting*
|
||||||
|
*Context gathered: 2026-04-09*
|
||||||
|
|
@ -0,0 +1,74 @@
|
||||||
|
# Phase 3: Sandbox-Aware Prompting - Discussion Log
|
||||||
|
|
||||||
|
> **Audit trail only.** Do not use as input to planning, research, or execution agents.
|
||||||
|
> Decisions are captured in CONTEXT.md -- this log preserves the alternatives considered.
|
||||||
|
|
||||||
|
**Date:** 2026-04-09
|
||||||
|
**Phase:** 03-sandbox-aware-prompting
|
||||||
|
**Areas discussed:** CLAUDE.md content, Generation behavior, Template storage
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## CLAUDE.md Content
|
||||||
|
|
||||||
|
### Tone
|
||||||
|
|
||||||
|
| Option | Description | Selected |
|
||||||
|
|--------|-------------|----------|
|
||||||
|
| Terse reference | Bullet points, no prose. Minimal, scannable. | |
|
||||||
|
| Friendly guide | Short prose paragraphs explaining the sandbox, restrictions, and tools. | ✓ |
|
||||||
|
| Minimal one-liner | Single paragraph, bare minimum. | |
|
||||||
|
|
||||||
|
**User's choice:** Friendly guide
|
||||||
|
**Notes:** User noted that users might inject certain secrets themselves (e.g., personal git SSH keys), so the CLAUDE.md shouldn't confuse Claude with absolute "no SSH keys" claims.
|
||||||
|
|
||||||
|
### Unavailable Section Phrasing
|
||||||
|
|
||||||
|
| Option | Description | Selected |
|
||||||
|
|--------|-------------|----------|
|
||||||
|
| Default-aware phrasing | "By default, these are not mounted: ..." -- accurate without contradicting customizations. | ✓ |
|
||||||
|
| Omit unavailable section | Don't list restrictions at all. | |
|
||||||
|
| Dynamic generation | Inspect mounts at launch and generate restrictions dynamically. | |
|
||||||
|
|
||||||
|
**User's choice:** Default-aware phrasing
|
||||||
|
**Notes:** None
|
||||||
|
|
||||||
|
### Git Section
|
||||||
|
|
||||||
|
| Option | Description | Selected |
|
||||||
|
|--------|-------------|----------|
|
||||||
|
| Yes, brief note | Mention git identity is pre-configured, suggest HTTPS for remotes. | ✓ |
|
||||||
|
| Skip it | Git just works, let Claude figure it out. | |
|
||||||
|
|
||||||
|
**User's choice:** Yes, brief note
|
||||||
|
**Notes:** None
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Generation Behavior
|
||||||
|
|
||||||
|
### Context Injection Mechanism
|
||||||
|
|
||||||
|
User redirected the discussion: instead of managing CLAUDE.md directly, use a separate SANDBOX.md file with Claude Code's `@path` import syntax. This avoids touching user content and eliminates tool-use token overhead.
|
||||||
|
|
||||||
|
**Final approach:** claudebox writes SANDBOX.md (managed, overwritten each launch) and ensures CLAUDE.md has `@SANDBOX.md` import at top line (checked/re-added each launch).
|
||||||
|
|
||||||
|
**User's insight:** "We don't need to write CLAUDE.md like that at all. We can just write a separate file and add a quick reference at the top."
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Template Storage
|
||||||
|
|
||||||
|
Folded into Generation behavior -- SANDBOX.md content lives as a heredoc in claudebox.sh. No separate template file needed since the two-file architecture resolved the storage question.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Claude's Discretion
|
||||||
|
|
||||||
|
- Exact prose wording in SANDBOX.md
|
||||||
|
- Shell implementation of first-line check
|
||||||
|
- Comment markers around import line
|
||||||
|
|
||||||
|
## Deferred Ideas
|
||||||
|
|
||||||
|
None
|
||||||
Loading…
Add table
Reference in a new issue