Metadata-Version: 2.4
Name: devco
Version: 0.1.0
Summary: A CLI tool that helps AI assistants understand projects through persistent documentation and RAG search
Home-page: https://github.com/yourusername/devco
Author: Claude Code
Author-email: Claude Code <noreply@anthropic.com>
License: MIT
Project-URL: Homepage, https://github.com/yourusername/devco
Project-URL: Repository, https://github.com/yourusername/devco
Project-URL: Bug Reports, https://github.com/yourusername/devco/issues
Project-URL: Documentation, https://github.com/yourusername/devco/wiki
Keywords: documentation,ai,assistant,rag,vector,search,embeddings,cli,development
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: llm>=0.13.0
Requires-Dist: llm-gemini
Requires-Dist: sqlite-utils>=3.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: numpy>=1.20.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-mock>=3.0.0; extra == "dev"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# devco

> A CLI tool that helps AI assistants understand projects by managing persistent documentation, principles, and context through embeddings and RAG querying.

## 🎯 Problem

AI assistants lose context when working on projects across sessions. They waste time re-exploring codebases, re-learning project structure, and rediscovering development practices with every new conversation.

## ✨ Solution

devco creates persistent, searchable project knowledge that survives context resets:

- **Development Principles** - Your team's coding standards and practices
- **Project Summary** - High-level project description and purpose  
- **Technical Sections** - Detailed implementation guides with function names, file paths, and examples
- **RAG Search** - Semantic search across all documentation using vector embeddings

## 🚀 Quick Start

### Installation

```bash
pip install devco
```

### Initialize in your project

```bash
devco init
```

### Add your development principles

```bash
devco principles add --text "Follow Test-Driven Development"
devco principles add --text "Keep functions under 20 lines"
```

### Document your project

```bash
devco summary replace --text "FastAPI web service for user authentication with PostgreSQL backend"

devco section add architecture \
  --summary "Clean architecture with dependency injection" \
  --detail "Entry point: main.py:create_app() line 15. Uses FastAPI with dependency injection via Depends(). Database models in models/ directory. Business logic in services/ with UserService.create_user() method."
```

### Generate embeddings for semantic search

```bash
devco embed
```

### Query your documentation

```bash
devco query "how does authentication work"
devco query "testing approach"
devco query "database schema"
```

## 📚 Full Documentation

### View all content

```bash
devco summary          # Show project summary and all sections
devco principles       # List development principles
devco section show testing  # Show specific section
```

### Manage principles

```bash
devco principles                              # List all
devco principles add --text "New principle"   # Add with flag
devco principles add                          # Add interactively  
devco principles rm 2                         # Remove by number
devco principles clear                        # Remove all
```

### Manage summary

```bash
devco summary                                # Show current
devco summary replace --text "New summary"   # Replace with flag
devco summary replace                        # Replace interactively
```

### Manage sections

```bash
devco section show architecture              # Show specific section
devco section add testing \
  --summary "TDD with pytest" \
  --detail "Tests in tests/ directory. Run: pytest -v"
devco section replace api --summary "..." --detail "..."
devco section rm outdated-section
```

### Search and embeddings

```bash
devco embed                    # Generate embeddings for all content
devco query "database setup"   # Semantic search
devco query "testing framework" 
```

## 🏗️ Why This Works

### For AI Assistants

Instead of this inefficient pattern:
```
AI: Let me search through your files to understand the project...
AI: *uses grep, find, reads multiple files*
AI: *tries to infer patterns and practices*
AI: OK, I think I understand how this works...
```

You get this efficient pattern:
```
AI: devco query "testing approach"
AI: Perfect! I can see you use pytest with TDD methodology, 
    tests are in tests/ directory, and I should follow the 
    pattern in tests/test_user.py:test_create_user() line 25.
```

### For Development Teams

- **Onboarding**: New developers get instant project context
- **Consistency**: Shared principles ensure consistent code
- **Documentation**: Implementation details with specific examples
- **Knowledge Retention**: Project knowledge survives team changes

## 🔧 Technical Details

### Architecture

- **CLI Framework**: argparse with subcommands
- **Storage**: JSON files + SQLite for vector embeddings  
- **Embeddings**: Gemini via `llm` package for consistent results
- **Search**: Cosine similarity with chunked content and overlap

### File Structure

```
.devco/
├── config.json      # Settings and embedding model
├── principles.json  # Development principles  
├── summary.json     # Project summary and sections
├── devco.db       # SQLite database with embeddings
└── .env           # API keys (git-ignored)
```

### Requirements

- Python 3.8+
- `llm` package with Gemini plugin
- Google API key for embeddings

## ⚙️ Configuration

### Set up embeddings

1. Install the llm package: `pip install llm llm-gemini`
2. Add your Google API key to `.devco/.env`:
   ```
   GOOGLE_API_KEY=your_key_here
   ```
3. Generate embeddings: `devco embed`

### Embedding Models

Configure in `.devco/config.json`:
```json
{
  "embedding_model": "gemini-embedding-exp-03-07-2048",
  "chunk_size": 500,
  "chunk_overlap": 50
}
```

## 📖 Best Practices

### Documentation Content

✅ **Include specific details:**
- Function names: `UserService.authenticate()` 
- File paths: `src/auth/service.py:45`
- Command examples: `pytest tests/test_auth.py -v`
- Code snippets and patterns

✅ **Write for AI assistants:**
- Assume no prior context
- Include implementation details
- Specify exact locations and examples

❌ **Avoid vague descriptions:**
- "We use good practices" → Specify what practices
- "Tests are important" → Specify testing framework and patterns
- "Code is modular" → Specify module structure and key classes

### Principles

Good principles are specific and actionable:
- ✅ "Use pytest fixtures for database setup in tests/conftest.py"
- ✅ "API endpoints follow REST patterns with serializers in api/serializers.py"
- ❌ "Write good code"
- ❌ "Be consistent"

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Follow TDD: write tests first
4. Ensure all tests pass: `pytest -v`
5. Update documentation with specific implementation details
6. Submit a pull request

## 📄 License

MIT License - see LICENSE file for details.

## 🔗 Links

- [Documentation](https://github.com/yourusername/devco/wiki)
- [Issues](https://github.com/yourusername/devco/issues)
- [Changelog](https://github.com/yourusername/devco/releases)
