Timmy-time-dashboard/CONTRIBUTING.md

CONTRIBUTING.md

How to contribute to Timmy Time Mission Control.

Philosophy

Read SOUL.md first. Timmy is a sovereignty project — every contribution should strengthen the user's control over their own AI, never weaken it.

Key values:

• Useful first, philosophical second
• Honesty over confidence
• Sovereignty over convenience
• Lines of code are a liability — delete as much as you create

Getting Started

1. Fork the repo
2. Clone your fork
3. Set up the dev environment:

make install              # creates .venv + installs deps
source .venv/bin/activate

See INSTALLATION.md for full prerequisites.

Development Workflow

Branch Naming

fix/<description>      — bug fixes
feat/<description>     — new features
refactor/<description> — refactors
docs/<description>     — documentation

Running Tests

tox -e unit       # fast unit tests (~17s)
tox -e lint       # code quality gate
tox -e format     # auto-format code
tox -e pre-push   # full CI mirror before pushing

See TESTING.md for the full test matrix.

Code Style

• Python 3.11+
• Formatting: ruff (auto-enforced via tox -e format)
• No inline CSS in HTML templates
• Type hints encouraged but not required
• Docstrings for public functions

Commit Messages

Use conventional commits:

fix: correct dashboard loading state (#123)
feat: add crisis detection module (#456)
refactor: simplify memory store queries (#789)
docs: update installation guide (#101)
test: add unit tests for sovereignty module (#102)
chore: update dependencies

Always reference the issue number when applicable.

Pull Request Process

1. Create a feature branch from main
2. Make your changes
3. Run tox -e pre-push — must pass before you push
4. Push your branch and open a PR
5. PR title: tag with description and issue number
6. Wait for CI to pass
7. Squash merge only — no merge commits

Never:

• Push directly to main
• Use --no-verify on git commands
• Merge without CI passing
• Include credentials or secrets in code

Reporting Bugs

1. Check existing issues first
2. File a new issue with:
   • Clear title
   • Steps to reproduce
   • Expected vs actual behavior
   • Environment info (OS, Python version)
   • Relevant logs or screenshots

Label with [bug].

Proposing Features

1. Check existing issues and SOUL.md
2. File an issue with:
   • Problem statement
   • Proposed solution
   • How it aligns with SOUL.md values
   • Acceptance criteria

Label with [feature] or [timmy-capability].

AI Agent Contributions

This repo includes multi-agent development (see AGENTS.md):

• Human contributors: follow this guide
• AI agents (Claude, Kimi, etc.): follow AGENTS.md
• All code must pass the same test gate regardless of author

Questions?

• Read SOUL.md for philosophy
• Read IMPLEMENTATION.md for architecture
• Read AGENTS.md for AI agent standards
• File an issue for anything unclear

License

By contributing, you agree your contributions will be licensed under the same license as the project (see LICENSE).