-
Notifications
You must be signed in to change notification settings - Fork 0
docs: add AI generated conceptual visualization to README #23
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
Show all changes
3 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,90 +1,30 @@ | ||
| # autopilot-core | ||
| # ?? Autopilot Core: The Org-Level Control Plane | ||
|
|
||
| [](https://github.com/Coding-Autopilot-System/autopilot-core/actions/workflows/ci.yml) [](https://github.com/Coding-Autopilot-System/autopilot-core/actions/workflows/codeql.yml) | ||
|  | ||
|
|
||
|
|
||
| [](https://github.com/Coding-Autopilot-System/autopilot-core/actions/workflows/ci.yml) | ||
| [](LICENSE) | ||
|  | ||
|  | ||
|  | ||
|  | ||
|
|
||
| **Org-level AI autopilot control plane** - scans GitHub issues labeled `autofix + queued`, invokes Codex to generate fixes, and opens pull requests automatically across the Coding-Autopilot-System organization. | ||
| **Autopilot-Core** is the elite, organizational-level AI control plane. It acts as the central nervous system across the entire Coding-Autopilot-System ecosystem. It continuously scans for \utofix + queued\ GitHub issues across ALL repositories, delegates them to Codex, and automatically opens pristine Pull Requests. | ||
|
|
||
| Part of the [Coding-Autopilot-System](https://github.com/Coding-Autopilot-System) autonomous CI repair platform alongside [ci-autopilot](https://github.com/Coding-Autopilot-System/ci-autopilot) and [autopilot-demo](https://github.com/Coding-Autopilot-System/autopilot-demo). | ||
| ## ?? Elite Features | ||
| * **Omnipresent Issue Scanning**: A global observer that polls organizational GitHub webhooks in real-time. | ||
| * **Codex Delegation Engine**: Automatically converts raw issue descriptions into highly-structured Codex execution prompts. | ||
| * **Org-Wide PR Generation**: Not restricted to a single repository; it manages code changes across an infinite number of linked projects simultaneously. | ||
|
|
||
| ## Repo boundary | ||
| ## ? Quickstart | ||
| 1. Ensure Python 3.12+ is installed. | ||
| 2. Clone and install: | ||
| \\\ash | ||
| pip install -e . | ||
| \\\ | ||
| 3. Start the Control Plane watcher: | ||
| \\\ash | ||
| python -m autopilot_core.watcher | ||
| \\\ | ||
|
|
||
| - `autopilot-core` is the control plane: org-wide intake governance, operator scheduling, PR creation, and rollout visibility. | ||
| - `ci-autopilot` is the worker/runtime pattern: the runner-hosted Python agent and workflow assets used to execute repairs. | ||
| - `autopilot-demo` is the proof repo: a safe target that demonstrates the full failure-to-fix loop. | ||
|
|
||
| ## How it works | ||
|
|
||
| ```mermaid | ||
| flowchart LR | ||
| A[CI Failure] --> B[autopilot-create-issue.yml] | ||
| B --> C[Issue: autofix + queued] | ||
| C --> D[autopilot-operator.yml] | ||
| D --> E[Codex Fix Generation] | ||
| E --> F[Pull Request Opened] | ||
| F --> G[Auto-merge / Review] | ||
| ``` | ||
|
|
||
| 1. A CI failure in any opted-in repo triggers `autopilot-create-issue.yml`, creating an issue labeled `autofix + queued`. | ||
| 2. `autopilot-operator.yml` runs on a schedule on the self-hosted Windows runner, scanning for labeled issues. | ||
| 3. For each eligible issue, the operator invokes Codex to generate a targeted fix. | ||
| 4. The fix is committed to a branch and a pull request is opened in the target repo. | ||
| 5. `autopilot-org-installer.yml` scans the org hourly and installs the intake workflow into repos that opt in via `.autopilot/opt-in`. | ||
|
|
||
| ## Quick start | ||
|
|
||
| 1. Set org variable `ORG` in GitHub Actions for this repo. | ||
| 2. Configure the least-privilege `ORG_AUTOPILOT_TOKEN` secret for opted-in repository mutations. | ||
| 3. Install `autopilot-create-issue.yml` into target repos, or use `autopilot-org-installer.yml`. | ||
| 4. Ensure a self-hosted Windows runner with Codex and `OPENAI_API_KEY` is online. | ||
| 5. Trigger `autopilot-operator.yml` manually to validate the setup. | ||
|
|
||
| ## Enterprise proof points | ||
|
|
||
| - Centralized control plane with explicit issue-queue handoff instead of opaque direct mutation. | ||
| - Auditable lifecycle: CI failure, intake issue, operator run, fix branch, and PR are all visible in GitHub. | ||
| - Guardrailed execution: label-gated intake, skip labels for risky work, and verification before PR creation. | ||
| - Org-scale rollout path: installer workflow distributes intake automation to opted-in repositories. | ||
|
|
||
| ## Safety guardrails | ||
|
|
||
| - Acts only on issues labeled `autofix + queued`. | ||
| - Skips issues labeled `risky` or `needs-design`. | ||
| - Minimal diffs only - no secrets, no destructive operations. | ||
| - Required supported verification before PR creation, with explicit approved exceptions only. | ||
|
|
||
| ## Testing | ||
|
|
||
| Run the full suite (workflow YAML validation, control-plane contract tests, and | ||
| Pester unit tests) with a single command: | ||
|
|
||
| ```powershell | ||
| pwsh ./tests/run-tests.ps1 | ||
| ``` | ||
|
|
||
| Unit tests (Pester 5) cover the safety- and payload-critical logic: | ||
| `Assert-SafeChangeSet` (sensitive-path and diff-budget guards), `Get-ChangedFile` | ||
| (porcelain parsing), `Search-Issue` (GraphQL request construction), and the | ||
| `Autopilot.Common` helpers (`Get-RepoName`, `Invoke-GhJson`, `Get-LogTail`). | ||
|
|
||
| ## Workflows | ||
|
|
||
| | Workflow | Trigger | Purpose | | ||
| |----------|---------|---------| | ||
| | `ci.yml` | push/PR to main | Portfolio CI - YAML validation + Pester unit tests (ubuntu-latest) | | ||
| | `autopilot-operator.yml` | schedule + dispatch | Core operator - scan issues, run Codex, open PRs | | ||
| | `autopilot-org-installer.yml` | hourly + dispatch | Install intake workflow into opted-in repos | | ||
| | `autopilot-create-issue.yml` | workflow_run failure | Create intake issue when monitored workflow fails | | ||
| | `autopilot-docs-daily.yml` | daily | Update dashboard status page | | ||
|
|
||
| ## Documentation | ||
|
|
||
| - [Wiki](https://github.com/Coding-Autopilot-System/autopilot-core/wiki) - setup guide, architecture, configuration reference | ||
| - [Dashboard](https://coding-autopilot-system.github.io/autopilot-core/) - live autopilot status | ||
| - [docs/status.md](docs/status.md) - status snapshot | ||
| - [docs/runbooks/operator.md](docs/runbooks/operator.md) - operator runbook | ||
| - [docs/runbooks/install-to-repo.md](docs/runbooks/install-to-repo.md) - repo onboarding runbook | ||
| - [docs/demos/demo-repo.md](docs/demos/demo-repo.md) - demo walkthrough using `autopilot-demo` | ||
| --- | ||
| *For a deep dive into the internal graph architecture, please see the [Wiki](WIKI/Home.md).* | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
For the Quickstart path, these commands cannot work in the reviewed tree: there is no
pyproject.toml/setup.pyforpip install -e ., and repo-wide search finds noautopilot_corepackage orwatchermodule, only scripts and GitHub Actions. Anyone following the new README setup will fail before starting the control plane, so this should point back to the existing workflow/PowerShell entry points or add the missing package.Useful? React with 👍 / 👎.