# Development Documentation

This directory contains technical documentation for developers working on the Quber project.

## Setup Guides

### [GitHub Setup](./GITHUB_SETUP.md)
Complete guide for GitHub integration including:
- Repository secrets configuration
- API keys management
- Project management system setup
- Issue templates and labels
- Claude GitHub App integration (optional)
- Troubleshooting common issues

**Start here if you're setting up the development environment!**

## Technical Documentation

### [Table Header Consolidation Algorithm](../table_header_consolidation_algorithm.md)
Details about the core table extraction algorithm and header consolidation logic.

## Project Management

Workflow is specified in two documents, which are the authority for issue and
pull request work:

### [Issues Spec](../ISSUES_SPEC.md)
Jira issue types, templates, title conventions, status workflow, and the
evidence each issue must carry.

### [GitHub Workflow Spec](../GITHUB_WORKFLOW_SPEC.md)
Branch naming, pull request title and body structure, functional evidence
requirements, merge strategy, and the Jira integration.

## Quick Reference

### Essential Commands
```bash
# Check GitHub authentication
gh auth status

# View repository secrets
gh secret list
```

### Environment Setup
1. Copy `.env.example` to `.env` and add your API keys
2. Install dependencies: `uv sync --all-extras`
3. Install pre-commit hooks: `pre-commit install`
4. Set up GitHub secrets: See [GitHub Setup Guide](./GITHUB_SETUP.md)

## Contributing

Before contributing, please:
1. Read the [GitHub Setup Guide](./GITHUB_SETUP.md)
2. Review the [GitHub Workflow Spec](../GITHUB_WORKFLOW_SPEC.md)
3. Follow the title conventions in the [Issues Spec](../ISSUES_SPEC.md)
4. Check [CLAUDE.md](../../CLAUDE.md) for AI collaboration guidelines

## Documentation Index

| Document | Purpose | When to Use |
|----------|---------|-------------|
| [GITHUB_SETUP.md](./GITHUB_SETUP.md) | GitHub integration setup | Initial setup, adding team members |
| [ISSUES_SPEC.md](../ISSUES_SPEC.md) | Jira issue types, templates, status workflow | Creating or updating an issue |
| [GITHUB_WORKFLOW_SPEC.md](../GITHUB_WORKFLOW_SPEC.md) | Branches, pull requests, evidence, merges | Opening or reviewing a pull request |
| [CLAUDE.md](../../CLAUDE.md) | AI assistant guidelines | Working with Claude Code |
| [ENGINEERING_STANDARDS.md](../ENGINEERING_STANDARDS.md) | Functional evidence, definition of done | Deciding whether work is finished |