Original Reddit post

Hey folks, I made a Claude Code skill called /boot that tries to solve the “every project starts as a documentation wasteland” problem. The idea is simple: Run /boot It creates CLAUDE.md , CONTEXT.md , MEMORY.md , and PLAN.md Gives Claude a structured place to store project instructions, context, memory, and plans Makes future sessions less like AI amnesia and more like an actual teammate Here’s the SKILL.md: — name: boot description: Use when starting a new project or setting up project documentation - bootstrap CLAUDE.md, CONTEXT.md, MEMORY.md, PLAN.md with proper structure in one step — # /boot ## Overview One command to set up project documentation and memory. Bootstrap initializes four core files for project context, memory, planning, and instructions—ensuring consistency across sessions and team members. Create with: /boot ## When to Use - New project started — Before any coding - New codebase clone — Documentation files missing - Setting up collaborative project — Ensure all devs have same structure - Starting fresh session — Want consistent documentation baseline Files Created: - CLAUDE.md — Project instructions & architecture (main reference for Claude) - CONTEXT.md — Live project context (maintained autonomously by Claude) - MEMORY.md — Session memory index (maintained autonomously by Claude) - PLAN.md — Implementation plans (auto-written after plan mode) ## Quick Usage Option 1: Run bootstrap script bash bash ~/.claude/skills/boot/bootstrap.sh Option 2: Manual invocation (if slash command available) bash /boot What happens: 1. Creates 4 documentation files if they don’t exist 2. Populates CLAUDE.md with template structure 3. Creates templates for CONTEXT.md, MEMORY.md, PLAN.md 4. Reports which files were created and next steps 5. Next session, Claude automatically references these files Files already exist? Script skips existing files, shows which were created vs. skipped. ## File Purposes ### CLAUDE.md (Main Instructions) Stores: - Project overview & architecture - Common commands - Key conventions & patterns - TypeScript/ESLint configuration - Important caveats Role: Developer-maintained. Claude reads this before every conversation to understand the project. Update it as architecture or conventions change. ### CONTEXT.md (Live Project State) Stores: - Current focus areas - Active issues/tickets - Recent changes - Dependencies & constraints - Upcoming deadlines Role: Claude-maintained. Claude updates this automatically after each significant task completes, keeping the project state fresh. Developer reviews periodically but doesn’t manually edit during active development. ### MEMORY.md (Session Memory Index) Stores: - User preferences & role - Feedback on coding approach - Project-specific decisions - Lessons learned - References to external resources Role: Claude-maintained. Claude writes entries here when you explicitly ask to remember something, or when debugging reveals patterns worth capturing for future sessions. Developer reviews periodically but doesn’t manually edit during active development. ### PLAN.md (Implementation Plans) Stores: - Final plans from plan mode - Multi-step task breakdowns - Architecture decisions - Progress tracking Role: Claude-managed. Claude writes plans to PLAN.md after exiting plan mode (via ExitPlanMode), and clears old content before writing new plans. Links to superpowers:writing-plans skill workflow. ## Core Principle Single source of truth for project knowledge. All context — instructions, state, memory, plans — lives in version-controlled files that persist across sessions and survive context window resets. This is why: 1. Consistency — Every session starts with same foundation 2. Collaboration — New team members see full project context instantly 3. Recovery — Context never lost to session resets or context window limits 4. Autonomy — Claude maintains files automatically without being asked ## How Automation Works ### File Discovery After /boot creates the four files, Claude automatically loads them into system context at the start of each conversation. No explicit invocation needed—the files are discovered by filename. - CLAUDE.md → Loaded first, governs all session behavior - CONTEXT.md → Loaded second, provides live project state - MEMORY.md → Loaded third, enables cross-session learning - PLAN.md → Loaded on-demand when user references “the plan” ### Maintenance Triggers CONTEXT.md updates when: - Task completed (after major feature/bugfix) - User explicitly asks “update context” or “remember this about the project” - Session ends (Claude summarizes progress made) MEMORY.md updates when: - User explicitly says “remember X” or “I want to remember that Y” - Claude encounters a pattern worth capturing (e.g., debugging technique that worked) - Project-specific lessons emerge during work PLAN.md updates when: - User exits plan mode via ExitPlanMode (skill: superpowers:writing-plans) - New plan is written, old content cleared first - User explicitly asks to view or update the plan ### User Role vs Claude Role | File | Developer | Claude | |------|-----------|--------| | CLAUDE.md | Writes & updates | Reads at start of session | | CONTEXT.md | Reviews periodically | Writes after task completion | | MEMORY.md | Reviews periodically | Writes when you say “remember” or learns patterns | | PLAN.md | Reviews progress | Writes after plan mode, clears before new plan | Key: Don’t manually edit CONTEXT/MEMORY while Claude is working—let Claude maintain them. Edit CLAUDE.md as architecture/conventions change. Edit Conflict Prevention: - If you manually edit CONTEXT.md or MEMORY.md, Claude’s next automatic update may overwrite your edits. - Save manual edits for session breaks or disable auto-updates by asking Claude first. - CLAUDE.md is safe to edit anytime—Claude only reads it, never writes. ### Integration with Plan Mode When you use /plan or superpowers:writing-plans skill: 1. Claude enters plan mode, designs the approach 2. User reviews and approves the plan 3. Claude exits plan mode via ExitPlanMode 4. Plan automatically written to PLAN.md (old content cleared) 5. PLAN.md persists for next session, session review, or team alignment Accessing plans: - Current session: Mention “the plan” in your request—Claude loads PLAN.md automatically - Cross-session: Claude loads PLAN.md at session start if it exists - Manual review: Open PLAN.md directly to read implementation details, progress, or architecture decisions - Sharing: Share PLAN.md with team members for alignment on approach Implementation plans remain discoverable across sessions. ## If Files Already Exist /boot skips existing files. If CLAUDE.md exists but CONTEXT.md doesn’t, /boot creates only CONTEXT.md. Conflict handling: - CLAUDE.md exists → Skipped (preserve your customizations) - CONTEXT.md exists → Skipped (preserve project state) - MEMORY.md exists → Skipped (preserve learned patterns) - PLAN.md exists → Skipped (preserve current plan) Refreshing stale files: If any file is older than 2 weeks (or appears outdated), manually delete it and run /boot again: bash rm CONTEXT.md # Delete stale CONTEXT /boot # Recreate with fresh template # Then manually seed with current project state Only delete files you want to refresh—skipped files preserve their content. ## Post-Bootstrap Workflow ### Step 1: Customize CLAUDE.md (Required) After /boot creates files, edit CLAUDE.md with real project details: - Replace generic “Project Overview” with actual architecture - Add real commands (npm run dev, cargo build, etc.) - Document key conventions specific to your project - List actual dependencies and configuration details - Add “Important Notes” relevant to your codebase Without this: Claude doesn’t understand your specific project. ### Step 2: Initial CONTEXT.md (Optional but Recommended) CONTEXT.md is auto-maintained, but you can optionally seed it: - Describe current focus areas - List active issues or tickets - Note critical dependencies - Flag any constraints or deadlines Claude will build on this foundation. ### Step 3: Commit to Git bash git add CLAUDE.md CONTEXT.md MEMORY.md PLAN.md git commit -m "Initialize project documentation with /boot" Why: Files must be version-controlled so all team members and future sessions access the same knowledge base. ### Step 4: Start Working Now every Claude session automatically: - Loads CLAUDE.md → understands your project - Loads CONTEXT.md → knows current state - References MEMORY.md → remembers past learnings - Can access PLAN.md → knows current implementation plans ## Common Mistakes ❌ Not running /boot on new projects Creates friction later when CONTEXT, MEMORY, PLAN are missing. → Run /boot first, always. ❌ Skipping CLAUDE.md customization Default content is generic—leaves Claude without real project knowledge. → After /boot, spend 5 min updating CLAUDE.md with actual details. ❌ Manually editing CONTEXT.md or MEMORY.md during active work Conflicts with Claude’s automatic maintenance. → Let Claude maintain these; review periodically, don’t edit while working. ❌ Not committing files to git Files lost if not version-controlled. → Commit all four files after creation. ❌ Treating PLAN.md as persistent across project lifecycle It’s cleared before each new plan. → Archive important plans elsewhere if they need long-term reference; PLAN.md is transient per task cycle. ## Example Before: my-project/ ├── src/ ├── package.json └── (no documentation) After /boot: my-project/ ├── CLAUDE.md ← Project instructions ├── CONTEXT.md ← Live project state ├── MEMORY.md ← Session memory index ├── PLAN.md ← Implementation plans ├── src/ └── package.json Now every Claude session starts with full project context automatically. ## What Happens After /boot 1. Files created — CLAUDE.md, CONTEXT.md, MEMORY.md, PLAN.md appear in project root 2. Customize CLAUDE.md — 5-10 minutes to add real project details (required) 3. Optional: Seed CONTEXT.md — Describe current focus (optional but recommended) 4. Commit to git — Version-control all four files 5. Next session — Files auto-load, Claude has full project context See “Post-Bootstrap Workflow” section for detailed steps. ## Bootstrap Content Reference What CLAUDE.md includes by default: - Project overview section (customize) - Commands section (customize) - Architecture section (customize) - TypeScript configuration (reference) - Key notes (customize) Customize each section—default content is a starting template. ## Implementation Details (Advanced) File discovery (Session Start): - Claude Code harness scans project root for CLAUDE.md, CONTEXT.md, MEMORY.md, PLAN.md - Files discovered by filename (no file registry needed) - Load order: CLAUDE.md first → CONTEXT.md → MEMORY.md → PLAN.md (on-demand) - If files don’t exist, session continues without them (graceful degradation) Auto-update mechanism: - CONTEXT.md updates triggered by: task completion signals, explicit “update context” requests, session-end summaries - MEMORY.md updates triggered by: “remember” requests, pattern discoveries during debugging/implementation - PLAN.md updates triggered by: ExitPlanMode skill action, explicit plan modifications - Updates are appended or replaced depending on file content structure File conflicts: - If CONTEXT.md or MEMORY.md are manually edited during active Claude session, next auto-update will overwrite changes - Recommendation: Coordinate manual edits with Claude—request “don’t update CONTEXT this session” if you’re making manual changes - CLAUDE.md is never auto-updated (read-only from Claude’s perspective) — Invoke with: /boot Files created: CLAUDE.md, CONTEXT.md, MEMORY.md, PLAN.md Maintenance: Claude handles CONTEXT, MEMORY, PLAN automatically. Keep CLAUDE.md updated as project evolves. Before I convince myself I’ve built something useful, I’d like the community to tear it apart. Questions: What assumptions am I making that are completely wrong? Which parts feel over-engineered? Which parts would annoy you enough to immediately delete the skill? Are there existing Claude Code workflows that already solve this better? If you had to use this daily, what would you change first? My own concerns: It might be trying too hard to recreate a database using markdown files. The automatic memory/context maintenance sounds nice in theory but might become noise. Four files might be three files too many. I may have accidentally invented Jira for a solo developer. Looking for brutal feedback, not compliments. If your reaction is “this is stupid because…” that’s exactly what I want to hear. Thanks. I’ll be in the comments defending my poor life choices. 😅 submitted by /u/Mission-Dentist-5971

Originally posted by u/Mission-Dentist-5971 on r/ClaudeCode