env-coach 🔧

Your local LLM project assistant for Rust development. Transform natural language requirements into structured development workflows with AI assistance.

Overview

env-coach is a standalone CLI tool that integrates Large Language Models (LLMs) into your development workflow. It helps you:

• 📝 Convert natural language requirements into user stories
• 📋 Manage project backlogs and sprints
• 🤖 Get LLM assistance during development
• 📊 Track progress and velocity
• 🏗️ Maintain project documentation

Installation

From Source

git clone https://github.com/yourusername/env-coach.git
cd env-coach
cargo install --path .

Development

cargo build --release
export PATH="$PATH:$(pwd)/target/release"

Quick Start

1. Initialize a Project

# In any Rust project directory
cd my-rust-project
# Basic initialization
env-coach init

# Initialization with PRD information
env-coach init --problem "Users need a way to track their book reading progress." --metric "Increase user engagement by 15%" --metric "Users log reading activity at least 3 times a week"

# Initialization with description from a file
env-coach init --description-file ./path/to/project_description.md

2. Configure LLM Connection

Edit LLM connection settings. env-coach uses a hierarchical configuration:

1. Project-specific (project.json): Settings here override global and default values.
2. Global (~/.config/env-coach/config.json on Linux/macOS, or equivalent user config directory on Windows): Sets default LLM parameters for all your projects.
3. Built-in defaults: If a setting is not found in project or global configs, a sensible default is used (e.g., localhost:11434 for Ollama).

Global Configuration (Optional):

Create ~/.config/env-coach/config.json (or your OS's equivalent config path) with your preferred default LLM settings. Example:

{
  "llm": {
    "host": "192.168.1.100",
    "port": 11434,
    "model": "mistral:latest",
    "timeout_ms": 60000
  }
}

All fields within "llm" are optional. If this file or any field is omitted, built-in defaults will be used.

Project-Specific Configuration (project.json):

When you run env-coach init, a project.json file is created. It will include a default LLM configuration block within the "meta" section. You can edit this block to specify a different model, host, port, or timeout for this particular project, overriding any global or built-in defaults.

Example project.json snippet (what env-coach init might create):

{
  "meta": {
    "name": "my-new-project",
    "description": "AI-assisted development project for my-new-project",
    "created": "YYYY-MM-DDTHH:MM:SSZ", // Actual creation timestamp
    "tech_stack": ["rust"], // Example, detected or default
    "tags": [],
    // Optional PRD (Product Requirements Document) section
    // Populated if --problem or --metric flags are used with `env-coach init`
    "prd": {
      "problem": "The core problem this project aims to solve.",
      "success_metrics": [
        "A measurable success metric.",
        "Another key performance indicator."
      ]
    },
    // Default LLM configuration written by `env-coach init`
    "llm": {
      "host": "localhost",
      "port": 11434,
      "model": "deepseek-coder:6.7b",
      "timeout_ms": 60000
    }
  },
  "backlog": [
    // Example of a user story item (generated by 'add-requirement')
    {
      "id": "US-001",
      "item_type": "UserStory",
      "title": "Add New Book to Collection",
      "story": "As a user, I want to add a new book to my collection by providing its title, author, and ISBN so that I can keep track of all my books.",
      "acceptance_criteria": [
        "User can input title, author, and ISBN for a new book.",
        "The new book is saved to the collection.",
        "The book appears in the list of all books."
      ],
      "priority": "High",
      "effort": 3,
      "status": "Todo",
      "created": "2024-07-29T10:00:00Z",
      "sprint": null,
      "dependencies": []
    }
  ],
  "sprints": [],
  "current_sprint": null
}

If the "llm" object or any of its fields are absent in project.json, env-coach will look at the global configuration, and then fall back to built-in defaults.

Use env-coach status to see the resolved LLM configuration and the source of each setting (Default, Global, or Project).

3. Add Requirements

The add-requirement command processes your natural language input using an LLM to generate structured user stories, which are then added to the project's backlog in project.json.

env-coach add-requirement "I want a CLI tool that manages my book collection with CRUD operations and search functionality"

This will populate the backlog array in project.json with user story objects (see example in project.json snippet above).

4. Plan & Execute

# View generated backlog
env-coach list-backlog

# Plan a sprint
env-coach plan-sprint --goal "MVP book management" --days 7

# Start working
env-coach start-task US-001
env-coach assist-task US-001  # Get LLM coding help
env-coach complete-task US-001

# Track progress
env-coach show-sprint

Commands

Project Management

• init [OPTIONS] - Initialize LLM workflow in current project.
  • Options include: --name <name>, --description <text>, --description-file <path>, --problem <text>, --metric <text>
• status - Check LLM connectivity
• add-requirement <text> - Process natural language requirements
• list-backlog - Show current backlog
• add-story --title <title> --description <desc> - Manually add user story

Sprint Management

• plan-sprint --goal <goal> --days <days> - Plan development sprint (uses LLM to suggest stories based on goal and backlog).
• start-sprint <id> - Activate a sprint
• show-sprint - Show current sprint status
• list-stories - List all user stories

Development Workflow

• start-task <id> - Begin working on a task
• assist-task <id> [--prompt <user_query>] - Get LLM assistance with implementation. The LLM will provide structured suggestions (e.g., for code changes, Cargo.toml dependencies, or general advice) based on the task details and your optional query. env-coach can automatically add suggested dependencies to Cargo.toml after your confirmation.
• complete-task <id> - Mark task complete and update metrics

LLM Interaction

• llm-cycle --prompt <text> - Send custom prompt to LLM

Example Workflows

This section provides a few common scenarios demonstrating how env-coach can be used throughout a project lifecycle.

1. New Project Initialization

Scenario: You have an idea for a new software application and want to use env-coach from the very beginning to manage its development with LLM assistance.

Steps:

1. Create Project Directory & Basic Setup: Open your terminal and create a directory for your new project. If it's a Rust project, you might run cargo init.

   mkdir my_new_application
   cd my_new_application
   # For Rust projects:
   # cargo init
   # For other languages, create basic project files (e.g., main.py, package.json)

2. Initialize env-coach: Run env-coach init inside your project directory. You can define the core problem your project solves and key success metrics right from the start using the optional flags.

   env-coach init --problem "Users struggle to manage their daily tasks effectively across multiple platforms." \
                  --metric "Users report a 25% increase in task completion rate." \
                  --metric "Consolidate tasks from 3 external platforms into one view."

   This creates a project.json file containing your project's metadata, including the PRD (Problem Statement, Success Metrics) section, and an .env-coach/ directory for tool-specific files like LLM prompts.

3. Verify Project Setup (Optional): Inspect project.json to see the initialized structure, including the prd section if you provided that information.

4. Add Initial High-Level Requirements: Describe the core functionality of your application. env-coach will use an LLM to break this down into user stories.

   env-coach add-requirement "The application needs a way for users to input tasks, categorize them, set deadlines, and view them on a dashboard."

5. Review Generated Backlog: Check the backlog to see the user stories generated by the LLM.

   env-coach list-backlog

Expected Outcome: Your new project is set up with env-coach, including a project.json with PRD info and an initial backlog of user stories. Default LLM prompts are in .env-coach/prompts/.

2. Existing Project Initialization

Scenario: You have an existing codebase and want to integrate env-coach to manage ongoing development.

Steps:

1. Navigate to Your Project Directory:

   cd path/to/my_existing_application

2. Initialize env-coach:

   env-coach init
   # Optionally, add PRD info:
   # env-coach init --problem "The current auth system is outdated." --metric "Implement MFA in 2 sprints."

   env-coach creates project.json and .env-coach/ without altering your existing code.

3. Start Managing Development: Add requirements for new features or refactoring tasks.

   env-coach add-requirement "Refactor the legacy payment module for maintainability."

4. Review and Plan: Use env-coach list-backlog to see generated stories and then plan your sprints.

Expected Outcome: env-coach is integrated, ready to manage new development efforts within your existing project.

3. Feature Request Workflow

Scenario: A new feature is requested for an ongoing project.

Steps:

1. Define Requirement:

   env-coach add-requirement "Users need to export reports as PDF files, including title, date, and all data sections. Add an export button to the report page."

   LLM generates user stories into the backlog.

2. Review & Refine Stories:

   env-coach list-backlog
   # Optionally, manually add or adjust stories if needed (e.g. using `env-coach add-story` or by editing `project.json`).

3. Plan Sprint:

   env-coach plan-sprint --goal "Implement PDF Export Functionality" --days 10

   • env-coach helps select stories aligning with the sprint goal.

4. Develop Task by Task:

   env-coach start-task <task_id_for_pdf_logic>
   env-coach assist-task <task_id_for_pdf_logic> --prompt "Best Rust crates for PDF generation? Example for simple PDF."
   # User implements code...
   env-coach complete-task <task_id_for_pdf_logic>

5. Track Progress:

   env-coach show-sprint

Expected Outcome: The new feature is implemented with LLM assistance, and project status is updated.

4. Issue/Bug Solving Workflow

Scenario: A bug is reported in the project.

Steps:

1. Document Bug:

   env-coach add-requirement "Bug Report: Profile page crashes if bio is empty. Steps: 1. Create user, no bio. 2. View profile. Expected: Page loads. Actual: 500 error, NPE at UserProfileService:73."

   LLM generates a bug task/story. The LLM should infer the context implies a bug.

2. Review Bug Task:

   env-coach list-backlog

   Verify details and priority (e.g., the LLM should ideally set a high priority for critical bugs).

3. Prioritize and Start Bug Fix: The team decides when to address the bug (e.g., pull into current sprint or address immediately).

   env-coach start-task <bug_task_id>

4. Get LLM Assistance:

   env-coach assist-task <bug_task_id> --prompt "NPE at UserProfileService.java:73 with empty bio. Code: [snippet]. How to fix?"

   LLM suggests code changes.

5. Implement & Test Fix: Apply the fix and write unit/integration tests.

6. Complete Task:

   env-coach complete-task <bug_task_id>

Expected Outcome: Bug is documented, fixed with LLM help, and project status updated.

Examples

Complete Workflow Example

# 1. Initialize project
mkdir book-manager && cd book-manager
cargo init --name book-manager
env-coach init

# 2. Add requirements
env-coach add-requirement "A REST API for managing a personal book collection with authentication, CRUD operations, search by title/author, and reading progress tracking"

# 3. Add manual stories (until auto-generation is implemented)
env-coach add-story --title "User Authentication" --description "As a user, I want to register and login securely so that I can access my personal book collection"

env-coach add-story --title "Book CRUD Operations" --description "As a user, I want to add, edit, delete, and view books so that I can manage my collection"

# 4. Plan sprint
env-coach plan-sprint --goal "Authentication and basic CRUD" --days 7

# 5. Start development
env-coach start-task US-001
env-coach assist-task US-001

# 6. Complete and continue
env-coach complete-task US-001
env-coach show-sprint

Project Structure After Init

my-project/
├── project.json              # Project configuration and backlog
├── .env-coach/               # Tool-specific files
│   ├── prompts/              # Customizable LLM prompts
│   └── templates/            # Project templates
├── docs/
│   └── adr/                  # Architecture Decision Records
└── src/                      # Your application code

Configuration

LLM Models

Tested with:

• deepseek-coder:6.7b (recommended for code tasks)
• llama2:7b (general purpose)
• codellama:7b (code-focused)

Customizing Prompts

Edit files in .env-coach/prompts/ to customize LLM behavior. These files are created with defaults when you run env-coach init:

• requirements_analyst.md - Used by add-requirement to process natural language requirements into user stories.
• sprint_planner.md - Used by plan-sprint to analyze the backlog and suggest stories for a sprint goal.
• task_assistant.md - Used by assist-task. Instructs the LLM to provide structured suggestions (JSON format) for code changes, dependency additions (Cargo.toml), and general advice related to a task.
• code_reviewer.md - (Planned) For code review assistance.

Development Phases

Phase 1 (Current) ✅

• Basic project management
• Manual story creation
• LLM integration for assistance
• Sprint planning and tracking

Phase 2 (Planned)

• Automatic JSON parsing from LLM responses
• Auto-population of backlog from requirements
• Enhanced code generation and review

Phase 3 (Planned)

• Git integration
• Automated testing assistance
• Advanced metrics and reporting

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Links

• Documentation
• Examples
• Issues
• Releases