diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..435be09 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,73 @@ +# Contributing to Cortex + +First off, thank you for considering contributing to Cortex! It's people like you that make Cortex such a great tool. + +## 🚀 How It Works: The AI-Corporation Workflow + +Cortex is not just a repository; it's an AI-orchestrated corporation. We follow a unique workflow: + +1. **Council Planning**: We use the `/council` command to analyze the project status and generate strategic tasks. +2. **Dispatching**: Tasks are converted into GitHub Issues using the `/dispatch` command. +3. **Agent Execution**: Specialized AI agents like **Jules** or **Codex** pick up these issues based on labels (`jules` or `codex`), implement solutions, and create Pull Requests. +4. **Human Review**: As the CEO of your instance, you (or the maintainers) review the PRs, run `/verify`, and merge them. + +## 🛠 Getting Started + +### Prerequisites + +- [Python 3.12+](https://www.python.org/downloads/) +- [uv](https://github.com/astral-sh/uv) (Fast Python package installer and resolver) +- [Claude Code](https://claude.ai/code) (The primary orchestration interface) + +### Setup + +1. **Clone the repository**: + ```bash + git clone https://github.com/your-username/cortex.git + cd cortex + ``` +2. **Install dependencies**: + Cortex uses a modular structure. Dependencies are managed per tool: + ```bash + cd tools/heartbeat && uv sync + cd ../metrics && uv sync + ``` +3. **Initialize Claude Code**: + Launch `claude` in the project root to access custom slash commands. + +## 📜 Code Style & Rules + +To maintain high quality and agent compatibility, we enforce strict rules: + +### Python Rules +- **Modern Syntax**: Use `from __future__ import annotations`. +- **Type Safety**: Strict type hinting is mandatory. Use `list[str]` instead of `List[str]` and `X | None` instead of `Optional[X]`. +- **Runtime Checking**: All public functions must be decorated with `@beartype`. +- **Complexity**: + - Maximum **700 lines** per file. + - Maximum **70 lines** per function. + - Maximum **4 levels** of nesting. +- **Tools**: Use `uv run pyright` for type checking and `uv run pytest` for testing within tool directories. + +See [docs/python-rules.md](docs/python-rules.md) for more details. + +### Git Workflow +- **Conventional Commits**: We use the `(): ` format (e.g., `feat(heartbeat): add Reddit source`). +- **Branching**: Never commit directly to `main`. Create a feature branch (`feat/your-feature`) and submit a PR. + +See [docs/git-flow.md](docs/git-flow.md) for more details. + +### Verification +Before submitting a PR, ensure your changes pass the verification suite: +```bash +/verify +``` +Or manually run the steps outlined in [docs/verify.md](docs/verify.md). + +## 🤝 Community + +If you have questions or want to discuss ideas, feel free to open an Issue or start a Discussion! + +--- + +*Cortex — Your Personal AI-Corporation* diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..2994ebf --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Cortex + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md index b501fed..4773381 100644 --- a/README.md +++ b/README.md @@ -111,5 +111,6 @@ Set-and-forget automation via GitHub Actions: --- -## 📝 License -This project is open-source. See individual file headers for specific licensing terms where applicable. +## 📝 License & Contributing +- [LICENSE](LICENSE) (MIT) +- [CONTRIBUTING.md](CONTRIBUTING.md)