{"id":50008553,"url":"https://github.com/kostiantyn-matsebora/ginee","last_synced_at":"2026-05-26T22:01:42.540Z","repository":{"id":358680749,"uuid":"1241339760","full_name":"kostiantyn-matsebora/ginee","owner":"kostiantyn-matsebora","description":"An AI software engineering team that behaves like a real one. Drops into your project, self-onboards, and gets to work.","archived":false,"fork":false,"pushed_at":"2026-05-18T16:09:11.000Z","size":537,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-18T16:19:22.329Z","etag":null,"topics":["agent-skills","agents-md","ai-agent","claude","claude-code","codex","copilot","copilot-cli","cursor","engineering-process","framework","ginee","llm","multi-agent","prompt-engineering"],"latest_commit_sha":null,"homepage":"https://kostiantyn-matsebora.github.io/ginee/","language":"PowerShell","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/kostiantyn-matsebora.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"docs/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-17T09:02:23.000Z","updated_at":"2026-05-18T16:09:15.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/kostiantyn-matsebora/ginee","commit_stats":null,"previous_names":["kostiantyn-matsebora/ginee"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/kostiantyn-matsebora/ginee","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kostiantyn-matsebora%2Fginee","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kostiantyn-matsebora%2Fginee/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kostiantyn-matsebora%2Fginee/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kostiantyn-matsebora%2Fginee/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kostiantyn-matsebora","download_url":"https://codeload.github.com/kostiantyn-matsebora/ginee/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kostiantyn-matsebora%2Fginee/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33406444,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-23T04:15:53.637Z","status":"ssl_error","status_checked_at":"2026-05-23T04:15:53.242Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["agent-skills","agents-md","ai-agent","claude","claude-code","codex","copilot","copilot-cli","cursor","engineering-process","framework","ginee","llm","multi-agent","prompt-engineering"],"created_at":"2026-05-19T20:00:36.633Z","updated_at":"2026-05-23T18:01:36.933Z","avatar_url":"https://github.com/kostiantyn-matsebora.png","language":"PowerShell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ginee\n\n**An AI software engineering team that behaves like a real one. Drops into your project, self-onboards, and gets to work.**\n\n[![Latest Release](https://img.shields.io/github/v/release/kostiantyn-matsebora/ginee?label=release\u0026color=0969da)](https://github.com/kostiantyn-matsebora/ginee/releases/latest)\n[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)\n\n[![Claude Code](https://img.shields.io/badge/Claude%20Code-tier--1-D97757?logo=anthropic\u0026logoColor=white)](adapters/claude/README.md)\n[![GitHub Copilot CLI](https://img.shields.io/badge/Copilot%20CLI-tier--1-000?logo=githubcopilot\u0026logoColor=white)](adapters/copilot-cli/README.md)\n[![AGENTS.md](https://img.shields.io/badge/AGENTS.md-tier--2-0969da)](adapters/agents-md/README.md)\n[![Generic](https://img.shields.io/badge/Generic-tier--3-lightgrey)](adapters/generic/README.md)\n\nYou're running AI coding agents across projects. Each tool has its own quirks, prompts,\nagent files, slash commands. The team works differently in every repo. Phases get\nskipped. Roles overlap. Long tasks crash with nothing to resume from. You re-explain\nthe same governance every single time.\n\n**ginee makes the team portable, the process deterministic, and your project the source of truth.**\n\n\u003e Drop the framework into a repo, prompt `@team-lead run initial discovery`,\n\u003e and you have a 7-role engineering team that works the same way on Claude Code,\n\u003e Copilot CLI, Cursor, Codex, Windsurf, and anything that reads `AGENTS.md`.\n\n---\n\n## Why ginee?\n\n```\nginee\n├── 📐 PROCESS IS THE FRAMEWORK\n│   ├── the phased lifecycle, dispatch rules, and iteration protocol are the spine\n│   ├── agents, the knowledge index, self-onboarding, the adapters — all optimisations\n│   │   on top; each makes the process cheaper to run on a real project\n│   └── strip the optimisations away and the process still holds; you can run it by hand\n│\n├── 👥 WORKS LIKE A REAL TEAM\n│   ├── roles dispatch each other, hand off, and review each other's work\n│   ├── strict-domain rule — no role works outside its lane; mockup edits go to frontend,\n│   │   architecture to SA, infra to devops, even when \"while I'm in the area\" is tempting\n│   ├── cross-domain bugs use a propose → implement → verify cycle, not single-agent guessing\n│   └── doc co-ownership pattern — solution-architect owns semantics, ai-engineer owns shape\n│\n├── 📥 THREE TASK SOURCES\n│   ├── freeform requests (\"Use ginee to add a /api/health endpoint\")\n│   ├── TODO files (root + nested per-component) — flips ☐ → ☒ only on user approval; never auto-adds\n│   ├── GitHub issues — file / pick up / triage / promote; PRs auto-close via `Closes #N`\n│   └── post-acceptance hook — if docs changed, ai-engineer proposes optimization automatically\n│\n├── 🎯 DETERMINISTIC\n│   ├── same phased lifecycle, same dispatch rules, same gates\n│   └── from one project to the next — no re-teaching the process\n│\n├── 🤖 CLIENT-AGNOSTIC\n│   ├── Claude Code (tier-1) · Copilot CLI (tier-1) · AGENTS.md (tier-2) · generic (tier-3)\n│   └── one set of role definitions; per-client renderings are pointer files only\n│\n├── 🔎 SELF-LEARNING\n│   ├── zero stack/domain opinions baked in — team-lead learns your project on first run\n│   ├── discovers tech stack, architecture, SDLC artefacts, TODO conventions\n│   └── scans external catalogs (awesome-copilot) for additional specialist agents\n│\n├── 📚 REFERENCE-NOT-COPY\n│   ├── project docs (architecture, mockups, diagrams) stay where they are\n│   └── doc changes propagate instantly — framework never duplicates content\n│\n├── ⏱️ ITERATION PROTOCOL\n│   ├── work \u003e 15 min runs in 3–5 min stoppable batches with visible intermediate results\n│   └── interrupt anytime; resume next day with zero rework\n│\n├── 🧱 EXTENSIBLE\n│   ├── 5 pre-built specialists (security · ml · mobile · sre · data)\n│   ├── plus author your own under local/roles/\n│   └── plus auto-discover + translate agents from awesome-copilot catalog\n│\n├── 🔄 UPDATE-SAFE\n│   ├── core/, adapters/, extras/ replaced on update\n│   └── local/ (your bindings, custom roles) survives every upgrade\n│\n└── 📦 ZERO TOOLING\n    ├── markdown only — copy-paste install always works\n    └── shell installer + GitHub Releases for convenience\n```\n\n---\n\n## Quick Start\n\n### 1. Install\n\n\u003e **Project-level install.** The framework lives inside your project. Run the installer **from the root of the project / git repo you want to set up** — the current working directory becomes the install target. No GitHub auth required. No `git` required for tagged-release installs (default) — the installer downloads + verifies the release tarball over HTTPS.\n\n**One-liner** (recommended):\n\n```bash\ncd /path/to/your-project \u0026\u0026 curl -fsSL https://raw.githubusercontent.com/kostiantyn-matsebora/ginee/main/install.sh | bash -s -- --adapter claude\n```\n\n```powershell\ncd C:\\path\\to\\your-project; $env:GINEE_ADAPTER='claude'; iwr -useb https://raw.githubusercontent.com/kostiantyn-matsebora/ginee/main/install.ps1 | iex\n```\n\nAdapters: `claude` · `copilot-cli` · `agents-md` · `generic`.\n\n**Download, inspect, then run** (when you want to read the installer first):\n\n```bash\ncurl -fsSLO https://raw.githubusercontent.com/kostiantyn-matsebora/ginee/main/install.sh\nchmod +x install.sh\n./install.sh --adapter claude\n```\n\n```powershell\niwr -useb https://raw.githubusercontent.com/kostiantyn-matsebora/ginee/main/install.ps1 -OutFile install.ps1\n.\\install.ps1 -Adapter claude\n```\n\n`--ref` defaults to `latest` (resolves to the most recent published release). Pin to a specific release with `--ref v0.1.0` / `$env:GINEE_REF='v0.1.0'`. Track a branch / commit with `--ref main` or `--ref \u003csha\u003e` (falls back to `git clone` — requires `git` on PATH).\n\n### 2. Run discovery\n\nOpen your client in the project, then prompt:\n\n```\n/ginee-discovery                                # tier-1 slash command (Claude Code, Copilot CLI)\nRun initial discovery                           # natural-language equivalent\nact as team-lead and run initial discovery      # tier-2/3 fallback\n```\n\nGinee scans the repo and writes `local/project-profile.md`, `local/bindings.md`, `local/framework.config.yaml`, then reports recommended specialists for your approval.\n\n### 3. Give it work\n\nGinee is a team — once installed, you talk to *ginee*, not to a specific role. The team routes work internally per `local/bindings.md`. Two invocation paths:\n\n- **Freeform** (works on any tier): `Use ginee to ...` — catch-all; the team self-dispatches.\n- **Skill** (tier-1, Claude Code + Copilot CLI): `/ginee-\u003cskill\u003e [args]` — slash-command on the 10 framework skills. Natural-language phrasings like `Pick up #42` also match the skill description.\n\nThree task sources:\n\n**Freeform work** — describe what you want:\n\n```\nUse ginee to add a dark-mode toggle to the header\nUse ginee to add a /api/health endpoint returning { status, version }\n```\n\n**TODO files** — flips `☐` → `☒` on Phase 8 approval; never auto-adds:\n\n```\nUse ginee to pick up the next TODO                                  # freeform\n/ginee-pick-up                                                      # next unchecked TODO\n/ginee-pick-up the dark-mode TODO in components/header/TODO.md\n```\n\n**GitHub issues** — file, pick up, or triage:\n\n```\nUse ginee to pick up issue #42                                      # freeform\n/ginee-pick-up #42\n/ginee-file-bug dashboard renders blank on Safari 17\n/ginee-file-feature dark-mode toggle in header\n/ginee-triage\n/ginee-promote-discussion #17\n```\n\nPRs auto-close issues via `Closes #N`. Full 10-skill list + natural-language cheat sheet in [adapters/claude/install.md § How to invoke](adapters/claude/install.md). For tasks above ~15 minutes, the iteration protocol kicks in: 3–5 min stoppable batches with visible intermediate results. Interrupt anytime; resume next day with zero rework.\n\n### 4. Update later\n\nRe-run the installer with the update flag — `core/` + `adapters/` + `extras/` re-fetch from upstream; `local/` (your bindings, custom roles, discovered index) is preserved untouched.\n\n```bash\n./install.sh --update-only --adapter claude\n```\n\n```powershell\n.\\install.ps1 -UpdateOnly -Adapter claude\n```\n\nPiped (no local checkout):\n\n```bash\nGINEE_UPDATE_ONLY=1 GINEE_ADAPTER=claude bash -c \"$(curl -fsSL https://raw.githubusercontent.com/kostiantyn-matsebora/ginee/main/install.sh)\"\n```\n\n```powershell\n$env:GINEE_UPDATE_ONLY='1'; $env:GINEE_ADAPTER='claude'; iwr -useb https://raw.githubusercontent.com/kostiantyn-matsebora/ginee/main/install.ps1 | iex\n```\n\nCheck `core/MIGRATIONS/` after each update for breaking-change notes.\n\n---\n\n## How it works\n\n\u003e The framework ships **process**; your project ships **everything else**.\n\nEvery adopter project has:\n\n```\nyour-project/\n├── .agents/ginee/   ← framework (replaced on update; local/ survives)\n│   ├── core/                   ← process spec + 7 cardinal role definitions + templates\n│   ├── adapters/\u003cclient\u003e/      ← per-client renderings (pointer files only)\n│   ├── extras/roles/           ← pre-built specialists (opt-in)\n│   └── local/                  ← YOUR bindings + custom roles (never replaced)\n│       ├── project-profile.md\n│       ├── bindings.md\n│       ├── framework.config.yaml\n│       └── roles/              ← your custom roles\n│\n├── .claude/agents/             ← (Claude adopters) thin pointers to .agents/ginee/core/roles/\n├── AGENTS.md                   ← (AGENTS.md adopters) one pointer file\n└── ... (your code, docs, mockups, tests — untouched)\n```\n\nThe 7 cardinals:\n\n| Role | Owns | Generic alias |\n|---|---|---|\n| `team-lead` | Dispatch routing, lifecycle gates, discovery, post-acceptance hook | orchestrator, project-manager |\n| `solution-architect` | Architecture doc semantics, SAD freeze + CR/ADR governance | architect |\n| `ai-engineer` | AI-asset + doc context economy, file-splitting, load topology | context-engineer |\n| `frontend-engineer` | Client / UI engineering | client-engineer |\n| `backend-engineer` | Server / API engineering | service-engineer |\n| `devops-engineer` | Infra, CI/CD, containers, cloud, secrets | platform-engineer |\n| `qa-engineer` | Functional / e2e / visual / scenario testing + thin runners | quality-engineer |\n\nPlus 5 opt-in specialists in `extras/roles/` (security · ml · mobile · sre · data) and unlimited custom roles in `local/roles/`.\n\n---\n\n## Where to next\n\n- **[PLAN.md](PLAN.md)** — design document + 11 locked decisions + verification plan.\n- **[CLAUDE.md](CLAUDE.md)** — orientation for working ON the framework itself (the project dogfoods its own process).\n- **[core/process.md](core/process.md)** — vendor-neutral team process spec (lifecycle, dispatch, iteration, coordination).\n- **[core/roles/](core/roles/)** — 7 cardinal role definitions.\n- **[adapters/](adapters/)** — per-client installation guides:\n  - [Claude Code](adapters/claude/install.md) — tier-1, native subagents\n  - [Copilot CLI](adapters/copilot-cli/install.md) — tier-1, native subagents + `/fleet` parallel\n  - [AGENTS.md cross-tool](adapters/agents-md/install.md) — tier-2, persona model\n  - [Generic fallback](adapters/generic/install.md) — tier-3, manual instructions\n- **[extras/roles/](extras/roles/)** — pre-built specialist library.\n- **[core/templates/role-authoring-template.md](core/templates/role-authoring-template.md)** — author your own custom role.\n\n---\n\n## License\n\n[MIT](LICENSE) © 2026 Kostiantyn Matsebora.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkostiantyn-matsebora%2Fginee","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkostiantyn-matsebora%2Fginee","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkostiantyn-matsebora%2Fginee/lists"}