ensemble-fold-prompt

name	ensemble-fold-prompt
description	Optimize CLAUDE.md for token efficiency, standards discovery, and progressive context loading (Codex skill for /ensemble:fold-prompt)
user-invocable	true

Ensemble Command: /ensemble:fold-prompt

This Codex skill mirrors the Ensemble slash command /ensemble:fold-prompt. Follow the workflow below, adapt to the current repository, and keep outputs structured.

Analyze a project's codebase to extract coding conventions, optimize CLAUDE.md for minimal token cost and maximum AI productivity, and organize context with progressive disclosure. Every token in CLAUDE.md is loaded every session -- this command ensures none are wasted.

Workflow

Phase 1: Codebase Standards Discovery

1. Detect Technology Stack Identify languages, frameworks, package managers, and build tools

• Read package.json, Gemfile, requirements.txt, go.mod, mix.exs, *.csproj, or equivalent
• Identify primary language(s) and framework(s) (e.g., Next.js 14, Rails 7, Phoenix 1.7)
• Detect test framework(s) and runner commands
• Detect linter/formatter config (.eslintrc, .prettierrc, rustfmt.toml, .rubocop.yml)
• Note monorepo structure if present (workspaces, packages/, apps/)

2. Extract Coding Conventions Mine the codebase for patterns that an AI assistant must follow

• Sample 5-10 representative source files to detect naming conventions (camelCase vs snake_case, file naming)
• Check for barrel exports, path aliases, import ordering conventions
• Identify error handling patterns (Result types, try/catch style, custom error classes)
• Detect API patterns (REST routes, GraphQL resolvers, RPC definitions)
• Read existing CONTRIBUTING.md, .editorconfig, or style guides if present
• Check commit history for conventional commit usage and scope patterns

3. Build Standards Index Create a compact index of discovered standards for token-efficient reference

• Compile findings into a standards index -- one line per standard, format "standard-name: brief description"
• Group standards by category (naming, testing, imports, error-handling, git)
• Keep each entry under 80 characters -- the index is a lookup table, not documentation
• If the project already has a .ensemble/standards.yml or similar, merge rather than replace

Phase 2: CLAUDE.md Structure Optimization

1. Audit Current CLAUDE.md Measure token cost and identify bloat in the existing file

• Read the current CLAUDE.md (or note its absence)
• Identify prose paragraphs that can be converted to bullet points (3:1 compression typical)
• Flag duplicated information (same command listed in multiple places)
• Flag inlined reference material that belongs in separate files (long API docs, full schema definitions)
• Estimate token count -- target under 2000 tokens for the core file

2. Write Quick Reference Header Put the most-used information in the first 20 lines

• Create a Quick Reference section at the very top with: essential commands (build, test, lint, run), key paths (src/, tests/, config), and branch/deploy conventions
• Use a markdown table for commands (columns: command, what it does) -- scannable and compact
• Include the tech stack one-liner (e.g., "Next.js 14 + Prisma + PostgreSQL + Jest")
• Add test run command prominently -- this is the single most-used command by AI assistants

3. Write Standards Section Inject the discovered coding conventions

• Add a "## Coding Standards" section with the standards index from Phase 1
• Use bullet points, not paragraphs -- each standard is one line
• Include concrete examples only for non-obvious conventions (e.g., "Error classes extend AppError, not Error")
• Omit standards that match language defaults (don't document that Python uses snake_case)

4. Organize with Progressive Disclosure Move detailed reference material out of CLAUDE.md into pointed-to files

• Keep in CLAUDE.md only what applies to every session (commands, standards, architecture overview)
• Move framework-specific patterns to .claude/patterns/.md and add a one-line pointer
• Move agent delegation details to .claude/agents.md if they exceed 10 lines
• Move API documentation references to .claude/api-guide.md
• Use this pointer format: '> See .claude/patterns/react.md for component patterns'
• Verify all pointed-to files exist after reorganization

Phase 3: Context Budget and Freshness

1. Add Context Budget Guidance Help future sessions manage context consumption

• Add a "## Context Notes" section at the bottom of CLAUDE.md
• Include rule: 'For tasks touching >5 files, use Task tool to delegate to a subagent with scoped context'
• Include rule: 'Prefer reading specific file sections (offset/limit) over full files for files >200 lines'
• Include rule: 'When context exceeds 60%, suggest splitting into a new session with a handoff summary'
• Keep this section under 5 bullet points -- it's guidance, not a manual

2. Remove Context Rot Strip outdated or low-value content

• Remove TODO items older than 30 days that are still in CLAUDE.md
• Remove references to deleted files, removed dependencies, or deprecated APIs
• Remove "nice to know" information that doesn't change AI behavior (project history, team bios)
• Verify all file paths mentioned in CLAUDE.md still exist on disk
• Check that all listed commands actually work (run them if possible)

Phase 4: Validation and Report

1. Validate Output Verify the optimized CLAUDE.md meets quality gates

• Confirm Quick Reference section is in the first 20 lines
• Confirm no prose paragraphs longer than 3 lines (convert to bullets)
• Confirm all file path references resolve to existing files
• Confirm standards section exists and has at least 3 entries
• Run project's lint/test command to verify documented commands work

2. Report Changes Summarize what was done and the token impact

• Print a summary: files modified, standards discovered, estimated token savings
• List any files created in .claude/ for progressive disclosure
• Flag any conventions that were ambiguous or need human confirmation
• Suggest next steps (e.g., "Review .claude/patterns/react.md for accuracy")

Expected Output

Format: Optimized CLAUDE.md with supporting reference files

Structure:

• CLAUDE.md: Token-optimized with quick reference header, standards index, progressive disclosure pointers, and context budget guidance
• .claude/patterns/*.md: Framework-specific patterns extracted from CLAUDE.md for selective loading
• .claude/standards-index.yml: Machine-readable standards index (standard-name, one-line description, category)
• Change Report: Summary of modifications, token savings estimate, and items needing human review

Usage

/ensemble:fold-prompt