From 8b3d4d59d4391b60487ebccb91a0dfe82cffa0dc Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Tue, 24 Feb 2026 20:14:40 +0000 Subject: [PATCH] docs: rewrite README as landing page - Added badges for Python 3.12, License, PRs, and Claude Code. - Created a Hero section with a one-sentence description. - Detailed the features inventory (11 commands, 4 agents, 8 hooks, 3 workflows). - Added a 5-step Quick Start guide. - Included an ASCII architecture diagram. - Added a comparison table with alternatives (claude-forge). Closes: # (no specific issue number mentioned in prompt) Co-authored-by: NickStr11 <37849063+NickStr11@users.noreply.github.com> --- README.md | 125 +++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 110 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 60b4639..b501fed 100644 --- a/README.md +++ b/README.md @@ -1,20 +1,115 @@ -# Cortex — AI Orchestration System +# 🧠 Cortex -## What is Cortex? -Cortex is a personal AI corporation system that orchestrates AI agents (Jules, Codex, Claude) via GitHub Issues to complete development tasks. The human acts as CEO — setting goals, reviewing PRs, and merging, while agents perform the actual work. +[![Python 3.12](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/release/python-3120/) +[![License: Open Source](https://img.shields.io/badge/License-Open%20Source-brightgreen.svg)](https://opensource.org/) +[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](http://makeapullrequest.com) +[![Powered by Claude Code](https://img.shields.io/badge/powered%20by-Claude%20Code-6b4fbb.svg)](https://claude.ai/) -## How it Works -Cortex follows a command-based orchestration flow to automate development: -1. **Plan**: `/council` generates tasks based on project roles (CPO, CTO, CMO, Growth). -2. **Assign**: `/dispatch` creates GitHub Issues from these tasks with appropriate agent labels. -3. **Queue**: GitHub Issues act as a task queue for the agents. -4. **Execute**: Agents like **Jules** and **Codex** pick up tasks, implement solutions, and submit Pull Requests. -5. **Review**: The human CEO reviews and merges the Pull Requests. +### Your Personal AI-Corporation +**Orchestrate a team of AI agents via GitHub Issues.** -## Usage +Cortex turns your GitHub repository into a self-evolving AI corporation. You act as the CEO—setting goals and reviewing results—while a specialized team of AI agents handles the implementation, testing, and security. -### /council -The `/council` command generates a set of tasks based on the current project context and defined roles. It analyzes the project's goals and breaks them down into actionable items for the AI agents. It also supports a **Forge Port Sprint** mode to benchmark against claude-forge and produce 3-5 concrete feature-port tasks for Cortex. +--- -### /dispatch -The `/dispatch` command takes the generated tasks and creates corresponding GitHub Issues. It automatically assigns the correct labels (e.g., `jules`) so the AI agents know which tasks to pick up and work on. +## 🚀 Quick Start + +Get your AI corporation up and running in less than 5 minutes: + +1. **Clone the brain**: + ```bash + git clone https://github.com/your-username/cortex.git + cd cortex + ``` +2. **Start the engine**: + Launch [Claude Code](https://claude.ai/code) in the project root. +3. **Run your first Council**: + ```bash + /council + ``` + *The AI council (CPO, CTO, CMO) analyzes your project and suggests actionable tasks.* +4. **Dispatch tasks**: + ```bash + /dispatch + ``` + *Cortex creates GitHub Issues and assigns them to specialized agents like **Jules** or **Codex**.* +5. **Review and Merge**: + Watch as PRs arrive. Review the code, run `/verify`, and merge! + +--- + +## 🛠 Features + +### 💻 11 Specialized Commands +Power up your CLI with custom slash commands: +- `/council`: Strategic planning and task generation. +- `/dispatch`: Automatic issue creation and agent assignment. +- `/heartbeat`: Automated tech trend scanning (HN, GitHub, Reddit). +- `/status`: Real-time health check of your agent pipeline. +- `/verify`: Automated verification of task completion. +- *And more: /handoff, /new-project, /screenshot, /tdd, /build-fix, /learn.* + +### 🤖 4 AI Agents +Your dedicated workforce, ready for any task: +- **Architect**: High-level system design and tech stack decisions. +- **Code Reviewer**: Automated PR analysis and quality enforcement. +- **Security Auditor**: Scanning for vulnerabilities and secret leaks. +- **Verify Agent**: Ensuring every task meets the Definition of Done. + +### ⚓ 8 Hardened Git Hooks +Built-in safety and quality checks: +- `check-secrets`: Prevent accidental leaks of API keys. +- `protect-main`: Enforce branch protection and PR workflows. +- `mcp-usage-tracker`: Monitor and optimize MCP tool usage. +- *Plus: check-filesize, pre-commit-check, grab-screenshot, output-secret-filter, expensive-tool-warning.* + +### 🔄 3 Automated Workflows +Set-and-forget automation via GitHub Actions: +- **Heartbeat Cron**: Keeps your project updated with the latest AI trends. +- **Auto-Review**: Instant feedback on every Pull Request. +- **Jules Trigger**: Seamless handoff from Issue to Implementation. + +--- + +## 🏗 Architecture + +```text + [ YOU: CEO ] + | + | /council (Planning) + v + [ AI CONCILIUM ] <--- (CPO, CTO, CMO, Growth) + | + | /dispatch (Execution) + v + [ GITHUB ISSUES ] <--- (The Task Queue) + | + +------+------+ + | | + [ JULES ] [ CODEX ] <--- (AI Workers) + | | + +------+------+ + | + v + [ PULL REQUESTS ] + | + | (Human Review) + v + [ PRODUCTION ] +``` + +--- + +## ⚖️ Comparison + +| Feature | Cortex | claude-forge | Aider / Cursor | +| :--- | :---: | :---: | :---: | +| **Orchestration** | Multi-agent via Issues | Single CLI | IDE-based | +| **Workflow** | CEO-centric (Reviewer) | Developer-centric | Developer-centric | +| **Automation** | Cron + Hooks + Actions | Hooks only | Manual | +| **Context** | Project-wide AI Roles | File-based | Session-based | + +--- + +## 📝 License +This project is open-source. See individual file headers for specific licensing terms where applicable.