🌱 every-env

Tools for AI-powered development that get smarter with every use. Make each unit of engineering work easier than the last.

Philosophy: Compounding Engineering

Compounding engineering: Each unit of engineering work should make subsequent units of work easier—not harder.

Every-Env embodies this principle through a simple, repeatable process that ensures your development workflow continuously improves.

The Compounding Engineering Process

┌─────────────┐     ┌──────────────┐     ┌─────────────┐     ┌─────────────┐
│    Plan     │────▶│   Delegate   │────▶│   Assess    │────▶│   Codify    │
│ Plan it out │     │ Do the work  │     │ Make sure   │     │   Record    │
│ in detail   │     │              │     │ it works    │     │ learnings   │
└─────────────┘     └──────────────┘     └─────────────┘     └─────────────┘
       ▲                                                              │
       └──────────────────────────────────────────────────────────────┘

The Four Steps

1. Plan → Plan out a feature or bug fix in detail

   • Break down complex tasks into clear steps
   • Think through edge cases and dependencies
   • Create a roadmap that AI and humans can follow

2. Delegate → Do the work

   • Execute the plan with AI assistance
   • Leverage automation for repetitive tasks
   • Focus human effort on high-value decisions

3. Assess → Make sure it works as expected

   • Test thoroughly against requirements
   • Verify edge cases are handled
   • Ensure code quality standards are met

4. Codify → Record learnings for next time

   • Capture what worked and what didn't
   • Update project knowledge (CLAUDE.md)
   • Ensure mistakes never happen twice

Why This Works

• Knowledge compounds: Every completed task adds to your project's collective intelligence
• Mistakes become strengths: Issues encountered today become safeguards tomorrow
• Automation grows naturally: Repeated patterns automatically become reusable workflows
• Teams scale efficiently: New team members inherit all accumulated knowledge

Use Your Own Tools

Every-Env is opinionated about the process (Plan → Delegate → Assess → Codify) but works with whatever tools you already use:

• AI Tools: Claude, GPT, Copilot, or any command-line AI
• Project Management: GitHub Issues, Linear, Jira, or markdown files
• Documentation: Store it wherever - repo, Notion, Confluence
• Development: Any IDE, terminal, or environment you prefer

The four-step process works regardless of your toolchain. Every-Env provides the structure; you bring the tools.

Prerequisites

Before using every-env, you need to have Claude Code installed:

npm install -g @anthropic-ai/claude-code

Verify installation:

claude --version

Installation

Global Installation (Recommended)

npm install -g every-env

Project Installation

For project-specific installation:

npm install --save-dev every-env

CLI Commands

Every-Env provides a comprehensive CLI that directly implements the four-step compounding engineering process.

Command Overview

# Core initialization
every-env init                    # Initialize every-env in your project

# The Four Steps of Compounding Engineering
every-env plan <task>             # Step 1: PLAN - Create detailed implementation plans
every-env work [plan]             # Step 2: DELEGATE - Execute with AI assistance
every-env review [target]         # Step 3: ASSESS - Verify work meets requirements
every-env codify                  # Step 4: CODIFY - Record learnings permanently

# Supporting commands
every-env request-review          # Get team feedback during assessment
every-env revise [target]         # Iterate on plans based on feedback

# Documentation workflow
every-env docs update             # Update documentation
every-env docs run <pattern>      # Run specific documentation patterns
every-env docs list               # List available patterns
every-env docs status             # Check documentation status

Global Options

Available for all commands:

• -c, --config <path> - Configuration file path (default: .docs-config.json)
• -p, --parallel <number> - Max parallel agents
• --dry-run - Preview without executing
• -v, --verbose - Verbose output
• --debug - Debug output

The init Command

Initialize every-env in your project. This is your starting point for all workflows.

every-env init                    # Interactive setup
every-env init --template rails   # Use Rails template
every-env init --template node    # Use Node.js template
every-env init --force           # Force regeneration
every-env init --dry-run         # Preview what would be created

What it does

1. Creates project structure:

   • .docs-config.json - Main configuration
   • prompts/ - Prompt templates directory
   • .every-env/ - State and metadata directory
   • .gitignore entries for generated files

2. Detects project type and suggests appropriate templates

3. Runs initial generation of all configured patterns

Templates

Templates provide pre-configured setups for common project types:

• rails: Ruby on Rails projects with models, controllers, views
• node: Node.js projects with package analysis
• basic: Minimal setup for custom configuration

Documentation Commands (docs)

The documentation workflow automates the creation and maintenance of project documentation using AI.

every-env docs update

Update existing documentation based on code changes.

every-env docs update                    # Update all patterns
every-env docs update --pattern api      # Update specific pattern
every-env docs update --force           # Force regeneration
every-env docs update --since HEAD~3    # Update based on git changes

every-env docs run <pattern>

Run a specific documentation pattern.

every-env docs run api-docs              # Run single pattern
every-env docs run models controllers    # Run multiple patterns
every-env docs run dependencies --only axios  # Process specific matches

every-env docs list

List all available documentation patterns.

every-env docs list                      # Show all patterns
every-env docs list --verbose            # Include pattern details

Output example:

Available patterns:
  api         - API endpoint documentation
  models      - Database model documentation
  deps        - Dependency analysis

every-env docs status

Show the status of documentation generation.

every-env docs status                    # Current status
every-env docs status --detailed         # Include file-level details

Planning Workflow Commands

The planning workflow represents the full development lifecycle, from ideation to implementation to learning.

every-env plan [patterns...]

Generate AI-powered implementation plans, work breakdowns, and technical designs using pattern-based workflows.

# List available planning patterns
every-env plan --list

# Generate an implementation plan
every-env plan implementation-plan

# Create multiple planning documents
every-env plan implementation-plan work-breakdown technical-design

# Use custom output directory
every-env plan implementation-plan --output plans/sprint-1

# Preview what would be created
every-env plan technical-design --dry-run

Built-in Planning Patterns

1. implementation-plan - Comprehensive implementation plan from requirements

   • Executive summary and objectives
   • Technical approach and architecture
   • Implementation phases with deliverables
   • Timeline and resource estimates (optional)
   • Risk analysis and mitigation

2. work-breakdown - Work Breakdown Structure (WBS)

   • Hierarchical task decomposition
   • Effort estimates per task
   • Dependencies and critical path
   • Resource allocation

3. technical-design - Detailed technical design document

   • System architecture and components
   • Data models and API specifications
   • Security and performance considerations
   • Deployment architecture

What it creates

Plans are generated in the specified output directory (default: plans/):

• plans/implementation-plan-analysis.md
• plans/work-breakdown-wbs.md
• plans/technical-design-design.md

Options

• -o, --output <path> - Output directory for plan files (default: "plans")
• -t, --template <name> - Specific plan template to use
• --timeline - Include timeline in plans (default: true)
• --resources - Include resource estimates (default: true)
• --tasks - Break down into detailed tasks (default: true)
• -l, --list - List available patterns

every-env review [target]

Review plans, pull requests, or GitHub issues to provide constructive feedback.

# Review the latest plan
every-env review

# Review a specific plan
every-env review plans/2024-01-15-signup-button.md

# Review a GitHub issue
every-env review --github 1234

# Review a pull request
every-env review --github 444

What it does

• Analyzes the target comprehensively
• Adds comments with specific, actionable feedback
• Highlights both strengths and areas for improvement
• Tracks review history for learning
• Updates status in .every-env/state.json

Review output

Reviews are added as markdown comments in the plan file:

<!-- REVIEW: 2024-01-15T14:30:00Z
Strengths:
- Clear user story definition
- Good consideration of edge cases

Suggestions:
- Consider accessibility requirements for the button
- Add performance metrics for form submission
-->

every-env request-review <target> --from <reviewer>

Request feedback from team members on plans or pull requests.

# Request review on a plan
every-env request-review plans/2024-01-15-signup.md --from @kieranklaassen

# Request review on a GitHub PR
every-env request-review --github 444 --from @teammate

# Request review from multiple reviewers
every-env request-review plans/api-refactor.md --from @alice,@bob

Integration options

• GitHub: Creates review requests on PRs/issues
• Slack: Sends notification with link (requires integration)
• Email: Sends review request email (requires SMTP config)
• Local: Updates state file for local tracking

every-env revise [target] [feedback]

Improve plans based on review feedback.

# Revise latest plan using embedded review comments
every-env revise

# Revise specific plan
every-env revise plans/2024-01-15-signup.md

# Revise with feedback file
every-env revise plans/2024-01-15-signup.md feedback.md

# Revise with inline feedback
every-env revise plans/2024-01-15-signup.md "make it more user-friendly"

# Revise based on GitHub PR comments
every-env revise --github 444

Revision process

1. Reads all review comments and feedback
2. Analyzes suggestions and concerns
3. Updates the plan incorporating improvements
4. Preserves revision history with git
5. Maintains comment threads for traceability

every-env work [plan]

Start development with AI assistance, using a plan as context.

# Work on the latest plan
every-env work

# Work on a specific plan
every-env work plans/2024-01-15-signup.md

# Work from a GitHub issue
every-env work --github 1234

# Work with additional context
every-env work --context architecture.md

What it does

1. Launches Claude Code (or configured AI tool)
2. Injects the plan as initial context
3. Includes relevant project information
4. Sets up the development environment
5. Provides implementation guidance

Working session

The AI assistant receives:

• The complete plan with all revisions
• Project structure and key files
• Relevant documentation
• Previous implementation patterns

every-env codify

Capture learnings from completed work and update project knowledge.

# Codify learnings from recent work
every-env codify

# Codify specific plans
every-env codify plans/2024-01-15-signup.md

# Codify with specific insights
every-env codify --insight "always validate email format client-side"

# Dry run to preview changes
every-env codify --dry-run

Codification process

1. Analyzes completed work and outcomes
2. Extracts patterns, best practices, and pitfalls
3. Updates CLAUDE.md with new knowledge
4. Creates a migration record (like Rails migrations)
5. Ensures future work benefits from these learnings

Migration tracking

Each codification creates a migration in .every-env/migrations/:

2024-01-15-signup-patterns.md
2024-01-14-auth-improvements.md
2024-01-13-api-structure.md

Workflow State Management

Every-Env automatically tracks your development workflow in .every-env/state.json:

{
  "activePlans": [
    {
      "id": "2024-01-15-signup-button",
      "path": "plans/2024-01-15-signup-button.md",
      "created": "2024-01-15T10:30:00Z",
      "status": "in-review",
      "revisions": 2,
      "lastModified": "2024-01-15T14:30:00Z"
    }
  ],
  "latestPlan": "2024-01-15-signup-button",
  "reviewRequests": [
    {
      "plan": "2024-01-15-signup-button",
      "reviewer": "@kieranklaassen",
      "requested": "2024-01-15T11:00:00Z",
      "status": "pending"
    }
  ],
  "codification": {
    "lastCodified": "2024-01-14T18:30:00Z",
    "migrations": [
      "2024-01-14-auth-patterns",
      "2024-01-13-api-structure"
    ]
  }
}

This enables:

• Smart defaults: Commands work on the latest/most relevant target
• Progress tracking: See where each plan is in the workflow
• Team coordination: Track review requests and responses
• Knowledge building: Maintain codification history

Configuration

Every-Env uses a flexible JSON-based configuration system.

Basic Configuration

The configuration file (.docs-config.json) defines patterns and agents:

{
  "defaultCommand": "claude",
  "parallelism": {
    "maxAgents": 5
  },
  "patterns": [
    {
      "name": "api",
      "description": "API endpoint documentation",
      "match": {
        "files": ["app/controllers/**/*.rb"],
        "exclude": ["**/*_test.rb"]
      },
      "agents": [
        {
          "id": "api-docs",
          "promptFile": "prompts/api.md",
          "output": "docs/api.md"
        }
      ]
    }
  ]
}

AllowedTools Configuration

🎉 Good news: Essential file operation tools are now automatically included for all agents:

• Read, Write, Edit, MultiEdit - File operations
• Glob, Grep, LS - File discovery and search

You can add additional tools as needed:

{
  "defaultAllowedTools": [
    // Additional tools beyond the essentials
    "WebSearch",
    "WebFetch", // For research
    "Bash(git log:*)",
    "Bash(git diff:*)", // Git integration
    "Bash(npm list:*)",
    "Bash(bundle show:*)" // Package info
  ]
}

See allowed-tools-guide.md for comprehensive tool reference.

Pattern Matching

Target specific files and extract content:

{
  "patterns": [
    {
      "name": "dependencies",
      "match": {
        "files": ["package.json"],
        "content": {
          "regex": "\"([^\"]+)\": \"[^\"]+\"",
          "captureGroup": 1,
          "exclude": ["@types/*"]
        }
      },
      "agents": [
        {
          "id": "dep-docs",
          "promptFile": "prompts/dependency.md",
          "outputPattern": "docs/deps/{name}.md",
          "forEach": "match"
        }
      ]
    }
  ]
}

Variables

Use variables in your prompts:

{
  "variables": {
    "company": "Acme Corp",
    "framework": "Rails"
  },
  "patterns": [...]
}

Access in prompts:

# {{ company }} - {{ framework }} Application

Generated on {{ date }} from branch {{ gitBranch }}

Available Variables

• projectName - Derived from package.json or directory name
• timestamp - ISO timestamp
• date - Formatted date
• gitBranch - Current git branch
• gitCommit - Current commit hash
• gitAuthor - Git user name
• output - Output file path
• outputDir - Output directory
• outputName - Output filename
• name - Current match value (when using forEach)
• index - Current match index
• total - Total matches

Examples

Complete Development Workflow

Here's how the four steps of compounding engineering work in practice:

# Step 1: PLAN - Create a detailed implementation plan
every-env plan "add user authentication with OAuth"
# Creates: plans/2024-01-15-oauth-auth.md

# Step 2: DELEGATE - Execute the plan with AI assistance
every-env work
# Launches Claude Code with the plan as context

# Step 3: ASSESS - Verify everything works correctly
every-env review
# Reviews the implementation against the plan
# Optional: Get team feedback
every-env request-review --from @teammate

# Step 4: CODIFY - Record what you learned
every-env codify
# Updates CLAUDE.md with new patterns and learnings
# Ensures this knowledge helps future work

Each cycle through these four steps makes the next cycle easier and more efficient.

Quick Start Examples

Rails Project

# Initialize with Rails template
every-env init --template rails

# Generate all documentation
every-env docs update

# Plan a new feature
every-env plan "add admin dashboard"

# Start working
every-env work

Node.js Project

# Initialize with Node template
every-env init --template node

# Document dependencies
every-env docs run dependencies

# Plan API improvements
every-env plan "add rate limiting to API endpoints"

Custom Project

{
  "patterns": [
    {
      "name": "architecture",
      "match": {
        "files": ["src/**/*.ts", "src/**/*.js"]
      },
      "agents": [
        {
          "id": "arch-docs",
          "promptFile": "prompts/architecture.md",
          "output": "docs/ARCHITECTURE.md"
        }
      ]
    }
  ]
}

Features

• 🚀 Fast: Run multiple AI agents at the same time
• 🎯 Smart targeting: Find and process exactly the files you need
• 🔧 Use any AI: Works with Claude, GPT, Copilot, or any CLI tool
• 📝 Dynamic prompts: Templates that adapt to your project
• 🔄 Efficient: Only update what's changed
• 🎨 Simple config: Just JSON files, no complex setup
• 📊 Progress tracking: Always know where you are in the workflow
• 🧠 Gets smarter: Every use makes future work easier

Environment Variables

• DOCS_MAX_AGENTS - Override maximum parallel agents
• CLAUDE_SKIP_PERMISSIONS - Skip Claude permission checks
• EVERY_ENV_STATE_DIR - Custom state directory location
• EVERY_ENV_CONFIG - Default config file path

Development

# Clone the repository
git clone https://github.com/every-env/every-env.git
cd every-env

# Install dependencies
npm install

# Run in development mode
npm run dev

# Run tests
npm test

# Build for production
npm run build

Ideas & TODOs (from dogfooding)

Workflow Improvements

• [ ] Better plan exploration: Need a simpler way to explore a plan and understand which parts of the codebase it's touching. Moreover, needs to help me understand the codebase.

Contributing

Contributions are welcome! Please read our Contributing Guide for details.

License

MIT © Every Env