{"id":50102557,"url":"https://github.com/ganyuanran/aegis","last_synced_at":"2026-06-28T07:01:22.249Z","repository":{"id":355905614,"uuid":"1225840521","full_name":"GanyuanRan/Aegis","owner":"GanyuanRan","description":"Make AI coding agents architecture-aware: baseline-first, evidence-verified, drift-checked, and safe across long tasks.","archived":false,"fork":false,"pushed_at":"2026-06-24T05:34:10.000Z","size":3795,"stargazers_count":571,"open_issues_count":0,"forks_count":30,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-24T07:26:28.847Z","etag":null,"topics":["add","agent-skills","ai-agents","ai-coding","architecture-driven-development","baseline-first","claude-code","codex","coding-agents","evidence-driven","first-principles","opencode","software-architecture","superpowers","tdd"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/GanyuanRan.png","metadata":{"files":{"readme":"README.en.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":"SECURITY.md","support":"SUPPORT.md","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null},"funding":null},"created_at":"2026-04-30T17:40:49.000Z","updated_at":"2026-06-24T05:34:14.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/GanyuanRan/Aegis","commit_stats":null,"previous_names":["ganyuanran/aegis"],"tags_count":61,"template":false,"template_full_name":null,"purl":"pkg:github/GanyuanRan/Aegis","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GanyuanRan%2FAegis","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GanyuanRan%2FAegis/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GanyuanRan%2FAegis/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GanyuanRan%2FAegis/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/GanyuanRan","download_url":"https://codeload.github.com/GanyuanRan/Aegis/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GanyuanRan%2FAegis/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34880189,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-28T02:00:05.809Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["add","agent-skills","ai-agents","ai-coding","architecture-driven-development","baseline-first","claude-code","codex","coding-agents","evidence-driven","first-principles","opencode","software-architecture","superpowers","tdd"],"created_at":"2026-05-23T08:05:36.471Z","updated_at":"2026-06-28T07:01:22.241Z","avatar_url":"https://github.com/GanyuanRan.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n    \u003ca href=\"https://linux.do/t/topic/2108966/20\" alt=\"LINUX DO\"\u003e\n        \u003cimg\n            src=\"https://img.shields.io/badge/LINUX-DO-FFB003.svg?logo=data:image/svg%2bxml;base64,DQo8c3ZnIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAiIHdpZHRoPSIxMDAiIGhlaWdodD0iMTAwIj48cGF0aCBkPSJNNjguMi0uMDU1aDYuMjVxMjMuOTY5IDIuMDYyIDM4IDIxLjQyNmM1LjI1OCA3LjY3NiA4LjIxNSAxNi4xNTYgOC44NzUgMjUuNDV2Ni4yNXEtMi4wNjQtMjMuOTY4LTIxLjQzIDM4LTExLjUxMiA3Ljg4NS0yNS40NDUgOC44NzRoLTYuMjVxLTIzLjk3LTIuMDY0LTM4LjAwNC0yMS40M1EuOTcxIDY3LjA1Ni0uMDU0IDUzLjE4di02LjQ3M0MxLjM2MiAzMC43ODEgOC41MDMgMTguMTQ4IDIxLjM3IDguODE3IDI5LjA0NyAzLjU2MiAzNy41MjcuNjA0IDQ2LjgyMS0uMDU2IiBzdHlsZT0ic3Ryb2tlOm5vbmU7ZmlsbC1ydWxlOmV2ZW5vZGQ7ZmlsbDojZWNlY2VjO2ZpbGwtb3BhY2l0eToxIi8+PHBhdGggZD0iTTQ3LjI2NiAyLjk1N3EyMi41My0uNjUgMzcuNzc3IDE1LjczOGE0OS43IDQ5LjcgMCAwIDEgNi44NjcgMTAuMTU3cS00MS45NjQuMjIyLTgzLjkzIDAgOS43NS0xOC42MTYgMzAuMDI0LTI0LjM4N2E2MSA2MSAwIDAgMSA5LjI2Mi0xLjUwOCIgc3R5bGU9InN0cm9rZTpub25lO2ZpbGwtcnVsZTpldmVub2RkO2ZpbGw6IzE5MTkxOTtmaWxsLW9wYWNpdHk6MSIvPjxwYXRoIGQ9Ik03Ljk4IDcwLjkyNmMyNy45NzctLjAzNSA1NS45NTQgMCA4My45My4xMTNRODMuNDI2IDg3LjQ3MyA2Ni4xMyA5NC4wODZxLTE4LjgxIDYuNTQ0LTM2LjgzMi0xLjg5OC0xNC4yMDMtNy4wOS0yMS4zMTctMjEuMjYyIiBzdHlsZT0ic3Ryb2tlOm5vbmU7ZmlsbC1ydWxlOmV2ZW5vZGQ7ZmlsbDojZjlhZjAwO2ZpbGwtb3BhY2l0eToxIi8+PC9zdmc+\" /\u003e\u003c/a\u003e\n    \u003ca href=\"https://dev.to/_879c5a0279451d52e43c3/aegis-a-method-pack-for-more-reliable-ai-coding-agents-1gfm\" alt=\"DEV.to\"\u003e\n        \u003cimg src=\"https://img.shields.io/badge/DEV.to-Article-0A0A0A?logo=devdotto\u0026logoColor=white\" /\u003e\u003c/a\u003e\n    \u003ca href=\"https://github.com/GanyuanRan/Aegis/actions/workflows/ci.yml\" alt=\"CI\"\u003e\n        \u003cimg src=\"https://img.shields.io/github/actions/workflow/status/GanyuanRan/Aegis/ci.yml?branch=main\u0026label=CI\" /\u003e\u003c/a\u003e\n    \u003ca href=\"https://github.com/GanyuanRan/Aegis/releases/latest\" alt=\"Latest Release\"\u003e\n        \u003cimg src=\"https://badgen.net/github/release/GanyuanRan/Aegis?label=Latest%20Release\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n    \u003cimg src=\"assets/aegis-hero.png\" alt=\"Aegis architecture-driven AI coding agent hero banner\" /\u003e\n\u003c/p\u003e\n\n# Aegis\n\n\u003cp align=\"center\"\u003e\n    \u003cstrong\u003eAegis Method Pack\u003c/strong\u003e\u003cbr/\u003e\n    Baseline-first, evidence-driven workflow discipline for AI coding agents.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n    \u003ca href=\"README.en.md\"\u003e\u003cstrong\u003eEnglish\u003c/strong\u003e\u003c/a\u003e\n    ·\n    \u003ca href=\"README.md\"\u003e\u003cstrong\u003e中文\u003c/strong\u003e\u003c/a\u003e\n    ·\n    \u003ca href=\"docs/current/AEGIS_WORKFLOW_GUIDE.md\"\u003eWorkflow Guide\u003c/a\u003e\n    ·\n    \u003ca href=\"docs/current/AEGIS_WORKFLOW_GUIDE_ZH.md\"\u003e工作流程说明\u003c/a\u003e\n\u003c/p\u003e\n\n## Why Aegis\n\nAegis is a **Superpowers upgrade** for teams using AI coding agents on real\nsoftware work. It keeps the useful idea of composable skills, then adds:\n\n- baseline-first planning before risky changes\n- evidence before completion claims\n- repair track plus retirement track for bugs, fallbacks, and compatibility paths\n- workflow quality guardrails so simple tasks stay cheap\n- portable method-pack skills across skill-aware hosts\n\nAegis is useful when agents otherwise start coding before the goal, owner,\narchitecture boundary, or verification path is clear.\n\n## Quick Install\n\nGive this prompt to your AI coding agent:\n\n```text\nRead https://github.com/GanyuanRan/Aegis, identify my current AI coding host, and install Aegis globally using the correct host guide. Restart or reload the host if needed, then run complete-install verification from the installed Aegis method-pack root. Do not run the doctor command from the target project directory. First locate `\u003caegis-method-pack-root\u003e`, then run `cd \u003caegis-method-pack-root\u003e \u0026\u0026 python scripts/aegis-doctor.py --write-config --json`. Treat the install as complete only if the JSON includes `\"ok\": true`, `\"workspaceSupport\": \"available\"`, and `\"configStatus\": \"configured\"`; if the host uses a separate skill discovery directory, also verify it with `--discovery-root \u003cpath\u003e`; if the host guide declares a skill directory name prefix, also pass `--discovery-name-prefix \u003cprefix\u003e`.\n```\n\n## Updating Aegis\n\nAfter a complete install has registered the current host, later updates can use\nnatural language such as `update Aegis` or the explicit skill request\n`aegis:update`. The agent can route either form through the local update path:\nlocate the installed method-pack root, use the host-scoped registry, and call\n`scripts/aegis-update.py` for the current host by default. Updating every\nregistered host requires an explicit `--all` request. Aegis does not run\nbackground automatic updates by default.\n\n## Before You Use It\n\nAegis is currently:\n\n\u003e `Aegis Method Pack (runtime-ready)`\n\nIt is **not** the full Aegis Platform, a daemon, a background runner, a runtime\ncore, an authoritative `GateDecision`, an authoritative `PolicySnapshot`, or\nfinal completion authority. User instructions and target-project rules outrank\nAegis guidance.\n\nFor smoother host-level behavior, use:\n\n- [Lite global rules](GLOBAL_USER_RULES_LITE.md)\n- [Advanced global rules template](GLOBAL_USER_RULES_TEMPLATE.md)\n\nActivation mode defaults to automatic. To switch to explicit mode, run this\nfrom the installed method-pack root:\n\n```bash\ncd \u003caegis-method-pack-root\u003e\npython scripts/aegis-doctor.py activation-mode explicit\n```\n\nRestart the host after changing activation mode. Details and host caveats live\nin [docs/current/AEGIS_ACTIVATION_MODE.md](docs/current/AEGIS_ACTIVATION_MODE.md).\n\nTDD mode defaults to `auto`: Aegis chooses strict TDD only when risk warrants,\nuses light verification for tiny edits, and skips TDD where it does not fit. To\ndisable automatic TDD routing without disabling completion verification:\n\n```bash\ncd \u003caegis-method-pack-root\u003e\npython scripts/aegis-doctor.py tdd-mode off\n```\n\nDetails live in [docs/current/AEGIS_TDD_MODE.md](docs/current/AEGIS_TDD_MODE.md).\n\n## Supported Hosts\n\nAegis keeps a multi-host, plugin-installable distribution goal.\n\n| Host group | Current status | Start here |\n| --- | --- | --- |\n| `Codex`, `OpenCode` | Fresh evidence exists for the current method-pack scope | [Codex](docs/README.codex.md), [OpenCode](docs/README.opencode.md) |\n| `Claude Code`, `CodeBuddy`, `DeepSeek-TUI`, `Trae`, `GitHub Copilot`, `Qoder`, `ZCode` | Install guides exist; release-level fresh host smoke is still pending | [Claude Code](docs/README.claude-code.md), [CodeBuddy](docs/README.codebuddy.md), [DeepSeek-TUI](docs/README.deepseek-tui.md), [Trae](docs/README.trae.md), [GitHub Copilot](docs/README.copilot.md), [Qoder](docs/README.qoder.md), [ZCode](docs/README.zcode.md) |\n| `CC GUI (JetBrains IDEA)` | Structural IDE plugin layer support for Claude Code / OpenAI-GPT provider paths; release-level fresh host smoke is still pending | [CC GUI](docs/README.cc-gui.md) |\n| `Antigravity CLI`, `Antigravity IDE`, `Antigravity App` | `Antigravity CLI` is the current active closeout target; `IDE/App` remain structural targets and release-level fresh host smoke is still pending | [Antigravity](docs/README.antigravity.md) |\n| `Pi CLI`, `OpenClaw`, `Hermes Agent` | Structural Agent Skills / `SKILL.md` skill-host adaptations; release-level fresh host smoke is still pending | [Pi CLI](docs/README.pi.md), [OpenClaw](docs/README.openclaw.md), [Hermes Agent](docs/README.hermes-agent.md) |\n| `Gemini CLI` | Transitional compatibility surface while Antigravity support matures | [Compatibility Matrix](docs/current/AEGIS_HOST_COMPATIBILITY_MATRIX_SNAPSHOT.md) |\n\nRead the current host verdict before making support claims:\n\n- [Host compatibility matrix](docs/current/AEGIS_HOST_COMPATIBILITY_MATRIX_SNAPSHOT.md)\n- [Known limitations](docs/current/AEGIS_KNOWN_LIMITATIONS.md)\n\n## How To Use\n\nAfter installation and host restart, use normal development requests. Aegis\nskills should be selected when the task matches the method.\n\nUse a portable goal frame before risky work. It frames the goal, then continues\ninto the routed workflow by default:\n\n```text\nAegis goal: Fix the auth refresh bug without rewriting the auth system.\n```\n\nUse explicit skills when you want a specific method:\n\n- `aegis:brainstorming`\n- `aegis:systematic-debugging`\n- `aegis:writing-plans`\n- `aegis:first-principles-review`\n- `aegis:requesting-code-review`\n- `aegis:verification-before-completion`\n\nIf an expected skill does not trigger, treat it as trigger-chain diagnosis:\nverify install/version visibility, host skill discovery, activation mode,\n`using-aegis` routing, task-to-skill routing, and context pressure. Read\n[docs/current/AEGIS_TRIGGER_HEALTH_BASELINE.md](docs/current/AEGIS_TRIGGER_HEALTH_BASELINE.md).\n\n## Workflow Shape\n\nAegis routes work by complexity:\n\n- Low-complexity: concise intent, baseline check, TDD Route, verification.\n- Medium-complexity: baseline read set, Spec Brief or stable requirements,\n  writing plan, atomic tasks, verification.\n- High-complexity: Design Spec, plan, user review when required, then execution.\n\nThe core discipline is:\n\n- **Baseline first**: read current project authority before substantial changes.\n- **Evidence before claims**: no completion claim without fresh verification.\n- **Repair plus retirement**: fix the owner and state what old path remains or retires.\n- **Workflow Quality**: keep simple tasks cheap and expand only when risk demands it.\n\nFor the full workflow, read:\n\n- [Workflow Guide](docs/current/AEGIS_WORKFLOW_GUIDE.md)\n- [Workflow Quality Baseline](docs/current/AEGIS_WORKFLOW_QUALITY_BASELINE.md)\n- [Runtime-ready boundary](docs/current/AEGIS_RUNTIME_READY_BOUNDARY.md)\n- [Artifact schema baseline](docs/current/AEGIS_ARTIFACT_SCHEMA_BASELINE.md)\n\n## For Maintainers\n\nPrimary verification entry:\n\n```bash\nbash tests/e2e/run-all.sh --full --host-profile fast\n```\n\nFocused docs / method-pack checks:\n\n```bash\nbash tests/e2e/boundary-compliance-check.sh\nbash tests/e2e/workflow-quality-check.sh\nbash tests/e2e/install-verification-policy-check.sh\nbash tests/e2e/layer1-fast-check.sh --host-profile none\n```\n\nRead:\n\n- [docs/testing.md](docs/testing.md)\n- [Release checklist](docs/current/AEGIS_METHOD_PACK_RELEASE_CHECKLIST.md)\n- [Current authority map](docs/current/README.md)\n- [Contributing](CONTRIBUTING.md)\n\n## Relationship To Superpowers\n\nAegis is derived from **[Superpowers](https://github.com/obra/superpowers)**,\ncreated by [Jesse Vincent](https://github.com/obra). Superpowers pioneered\ncomposable, multi-harness agent skills. Aegis keeps that foundation and adds an\narchitecture- and evidence-focused method layer for real software projects.\n\nAdditional inspiration comes from\n[mattpocock/skills](https://github.com/mattpocock/skills), especially concise\ncommunication, shared language, and disciplined debugging patterns. These ideas\nwere re-implemented in Aegis format rather than copied verbatim.\n\n## License\n\nMIT License. See [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fganyuanran%2Faegis","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fganyuanran%2Faegis","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fganyuanran%2Faegis/lists"}