{"id":50515905,"url":"https://github.com/sdsrss/sgc","last_synced_at":"2026-06-03T00:02:35.233Z","repository":{"id":351718506,"uuid":"1205655460","full_name":"sdsrss/sgc","owner":"sdsrss","description":"All-in-one engineering workflow \u0026 knowledge engine for Claude Code. One-command install, runs standalone (Node \u003e=18, no bun). L0-L3 task classification, 13 runtime invariants, code review, browser QA, security audit, and a deduplicated knowledge base that compounds across tasks.","archived":false,"fork":false,"pushed_at":"2026-06-02T07:28:12.000Z","size":2833,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-02T08:24:11.278Z","etag":null,"topics":["ai-agents","ai-coding","ai-tools","anthropic","claude-code","claude-code-plugin","cli","code-review","coding-agent","compound-engineering","developer-tools","devtools","engineering-workflow","knowledge-management","llm","qa-automation","security-audit","tdd","typescript","workflow-automation"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@sdsrs/sgc","language":"TypeScript","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/sdsrss.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"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-04-09T06:52:19.000Z","updated_at":"2026-06-02T07:28:16.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/sdsrss/sgc","commit_stats":null,"previous_names":["sdsrss/sgc"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/sdsrss/sgc","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sdsrss%2Fsgc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sdsrss%2Fsgc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sdsrss%2Fsgc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sdsrss%2Fsgc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sdsrss","download_url":"https://codeload.github.com/sdsrss/sgc/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sdsrss%2Fsgc/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33841996,"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-02T02:00:07.132Z","response_time":109,"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":["ai-agents","ai-coding","ai-tools","anthropic","claude-code","claude-code-plugin","cli","code-review","coding-agent","compound-engineering","developer-tools","devtools","engineering-workflow","knowledge-management","llm","qa-automation","security-audit","tdd","typescript","workflow-automation"],"created_at":"2026-06-03T00:02:33.108Z","updated_at":"2026-06-03T00:02:35.228Z","avatar_url":"https://github.com/sdsrss.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# sgc — All-in-One Engineering Workflow \u0026 Knowledge Engine for Claude Code\n\n[![npm version](https://img.shields.io/npm/v/@sdsrs/sgc?logo=npm)](https://www.npmjs.com/package/@sdsrs/sgc)\n[![install size](https://img.shields.io/badge/runtime-node%20%E2%89%A518-339933?logo=node.js\u0026logoColor=white)](#install)\n[![Claude Code plugin](https://img.shields.io/badge/Claude%20Code-plugin-d97757)](https://docs.claude.com/en/docs/claude-code)\n[![license](https://img.shields.io/npm/l/@sdsrs/sgc)](LICENSE)\n\n**sgc is a self-contained [Claude Code](https://docs.claude.com/en/docs/claude-code) plugin that runs your entire engineering loop — plan → implement → review → QA → ship → compound — from one install.** It adds L0–L3 task classification, 13 runtime invariants, and a deduplicated knowledge engine that *compounds* what every task teaches you. One command to install, node-only, no extra runtime, no other plugins required.\n\n\u003e **In one sentence:** sgc turns Claude Code into a disciplined engineering agent that classifies each task, enforces the right process for its risk level, runs review/QA/security gates, ships it, and records reusable knowledge so the same mistake is never made twice.\n\nsgc consolidates — natively, in-process — the engineering capabilities you'd otherwise install separately: gstack-style **canary / security review / browser QA / ship orchestration**, Superpowers-style **systematic debugging and verification gates**, and the **Compound Engineering** capture→promote→reuse loop. You don't need to install or wire up those plugins; sgc owns the whole workflow and runs standalone. (It will still interoperate with `superpowers` / `gstack` if you have them.)\n\n## Why sgc?\n\n- **One-command install, zero runtime hassle.** `/plugin install sgc` ships a self-contained Node bundle — works on any machine that runs Claude Code (Node ≥ 18). No `bun`, no second install step, no global setup.\n- **Right-sized process per task.** Every task is classified **L0–L3** (typo → architecture) and gets exactly the planning, review depth, and human gates its risk warrants — no ceremony on a typo, full adversarial review + human signature on a migration.\n- **13 runtime invariants, enforced — not suggested.** Generator/evaluator separation, immutable decisions, dedup-gated knowledge writes, scope tokens pinned at spawn, two-tier event audit. The protocol is machine-checked at every write.\n- **A knowledge engine that compounds.** Every shipped task can promote a reusable solution/prevention into a deduplicated corpus; future plans surface prior art automatically, so lessons accumulate instead of evaporating.\n- **Full loop in one tool.** `plan · work · review · qa · ship · compound · debug · cso · canary · land · reflect · loop` — the complete plan-to-prod pipeline plus security review, systematic debugging, post-publish canary, and knowledge reflection.\n\n## Install\n\n```bash\n/plugin marketplace add sdsrss/sgc\n/plugin install sgc\n```\n\nThat's it. The plugin ships a self-contained Node CLI bundle (`plugins/sgc/bin/sgc.mjs`), so every `/sgc:*` slash command works immediately on any machine that runs Claude Code — **no `bun`, no separate `npm install`, no PATH setup.**\n\n**Also available on npm** (for `npx`, CI, or use outside Claude Code):\n\n```bash\nnpm install -g @sdsrs/sgc\nsgc --version\n```\n\nThe npm package runs on Node ≥ 18 (no `bun` runtime required). Both channels ship the **same bundle**; when both are present, the plugin-bundled CLI wins for version determinism.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eFrom source\u003c/strong\u003e (to hack on sgc itself)\u003c/summary\u003e\n\n```bash\ngit clone https://github.com/sdsrss/sgc \u0026\u0026 cd sgc\nPLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 npm install   # bun client ignores HTTP_PROXY; use npm\nbun --version    # ≥1.3 — dev/build/test runtime only (not needed by end users)\nnpm run build:cli                                 # rebuild plugins/sgc/bin/sgc.mjs\n```\n\nIn source mode the slash commands fall back to `bun src/sgc.ts` when no bundle/global CLI is found.\n\u003c/details\u003e\n\n### Update\n\n```bash\n/plugin marketplace update sgc   # refresh marketplace metadata first\n/plugin update sgc               # then pull the new version\nnpm update -g @sdsrs/sgc         # if you also use the npm channel\n```\n\nBoth plugin steps are needed — `/plugin update` alone uses cached marketplace metadata. Your project `.sgc/` state is untouched by updates.\n\n### Uninstall\n\n```bash\n/plugin uninstall sgc\n/plugin marketplace remove sgc\n```\n\nNo global footprint is left behind. Project-level `.sgc/` directories are **not** removed — that's your data, not plugin data (`rm -rf .sgc` per project to wipe state).\n\n## Quick start\n\n```bash\n# 1. Plan a task — classifier picks L0–L3, runs the planner cluster, writes immutable intent\n#    (L1+ requires --motivation ≥20 words; L0 typos skip intent entirely)\nsgc plan \"add an Example section to the plan skill\" \\\n  --motivation \"Newcomers can't verify the skill end-to-end without sample input/output, so add a runnable Example block matching the repo's format.\"\n\n# 2. Track implementation progress (you write code; sgc tracks features + gates 'done')\nsgc work                                   # list features, highlight active\nsgc work --add \"verify empty-input path\"\nsgc work --done f1 --verify-command \"bun test tests/foo.test.ts\"\n\n# 3. Independent review of your diff\nsgc review                                 # reviewer.correctness vs git diff (or --base \u003cref\u003e)\n\n# 4. Ship + compound knowledge\nsgc ship                                   # 8-gate ship; auto-runs the compound janitor\nsgc status                                 # dashboard: active task, level, last activity\n```\n\nState lives under `.sgc/` in the project (override via `SGC_STATE_ROOT`); it's `.gitignore`d — runtime state, not source.\n\n## Commands\n\n| Command | Purpose |\n|---------|---------|\n| `sgc discover \u003ctopic\u003e` | Forcing-question clarifier; feeds `sgc plan --motivation` |\n| `sgc plan \u003ctask\u003e [--motivation\\|--signed-by\\|--level\\|--async]` | Classify L0–L3; run the planner cluster (L2 adds ceo+researcher, L3 adds adversarial + human signature); write immutable `decisions/{id}/intent.md` |\n| `sgc work [--add\\|--done \u003cid\u003e --verify-command \u003cs\u003e [--evidence \u003cs\u003e]]` | Track `feature-list.md`; `--done` **requires** a verify command (verification close-gate) |\n| `sgc review [--base \u003cref\u003e]` | Independent `reviewer.correctness` on your git diff → append-only report |\n| `sgc qa [\u003ctarget\u003e] [--flows a,b,c]` | Real-browser end-to-end QA; required before an L2+ ship |\n| `sgc ship [--auto\\|--pr\\|--no-janitor\\|--force-compound]` | 8-gate ship; optional `gh pr create`; auto-invokes the compound janitor |\n| `sgc compound [--from-ship-failure\\|--from-canary\\|--force\\|--slug …]` | Extract + dedup-gate (0.85) + write reusable `solutions/{cat}/{slug}.md` |\n| `sgc reflect [--task\\|--since\\|--save\\|--json]` | Audit which stored solutions/preventions actually surfaced in your decisions |\n| `sgc loop \u003ctask\u003e [--resume\\|--runs\\|--status]` | End-to-end orchestrator: plan → work → review → qa → ship → compound with manual gates |\n| `sgc debug \u003cstart\\|close\u003e […]` | 4-phase systematic debugging (investigate → analyze → hypothesize → implement); `close` is a hard-gate |\n| `sgc cso [--mode daily\\|comprehensive]` | Pre-ship security review — secret scan + dependency audit + event-stream anomaly detection |\n| `sgc canary [--package\\|--version\\|--phases\\|--health-url …]` | Post-publish health check (npm propagation → smoke install → optional health URL) |\n| `sgc land` | Post-publish ship chain (`watch-ci-failure` + `canary`, fail-fast) |\n| `sgc watch-ci-failure [--run-id\\|--workflow]` | Poll publish CI; capture a templated ship-failure record for promotion |\n| `sgc handoff [--auto]` | Session-state checkpoint → `tasks/\u003cslug\u003e-paused.md` for post-compaction recovery |\n| `sgc status` / `sgc tail […]` | Dashboard / live `.sgc/progress/events.ndjson` audit stream |\n| `sgc doctor` | Self-check: contracts ↔ prompts ↔ command parity ↔ bundle freshness |\n\n19 commands total — 16 are also exposed as `/sgc:*` slash commands inside Claude Code; `canary`, `watch-ci-failure`, and `land` are CLI-only. A vendored `browse` headless-browser binary backs `sgc qa`.\n\n## Task levels (L0–L3)\n\n| Level | Scope | Planning | Review | Human gate |\n|-------|-------|----------|--------|------------|\n| **L0** | Trivial (typo, format, config) | Skip — direct to work | None | No |\n| **L1** | Single file, \u003c 50 lines, no behavior change | Light planner.eng | reviewer.correctness | No |\n| **L2** | Multi-file / behavior change / new tests | + planner.ceo + researcher.history | Reviewer cluster | No |\n| **L3** | Architecture, schema, prod, infra | + planner.adversarial | + conditional specialists (security/migration/perf/infra) | **Signature required; `--auto` refused** |\n\n## Knowledge engine — the compounding loop\n\nsgc's differentiator is that work **compounds**. The loop: a shipped task → the compound janitor decides if it's worth keeping → a 4-agent cluster extracts a solution/prevention → it passes a deduplication gate (Jaccard ≥ 0.85, non-tunable) → it's written to an append-only `solutions/` corpus. On the next plan, `researcher.history` mines that corpus and `planner.adversarial` is injected with relevant preventions — so prior lessons actively shape new decisions. `sgc reflect` audits how often stored knowledge actually surfaces.\n\n## Invariants (enforced at runtime)\n\n| § | Rule |\n|---|------|\n| 1 | Reviewers/QA cannot read `solutions/` (generator–evaluator separation) |\n| 2 | Decisions are immutable once written (changed intent → new task) |\n| 3 | No write to `solutions/` without a dedup stamp from a prior `compound.related` run |\n| 4 | L3 requires a human signature + interactive confirm; `--auto` refused |\n| 5 | A reviewer-fail override needs a human signature + reason (≥ 40 chars) |\n| 6 | Every janitor/review/QA decision is logged (no silent skips) |\n| 7 | Schema validation precedes every `.sgc/` write |\n| 8 | Subagent scope tokens are pinned at spawn (no runtime elevation) |\n| 9 | Subagents may only emit their declared output shape |\n| 10 | The compound cluster is all-or-nothing (transactional) |\n| 11 | The classifier must justify its level with a concrete task feature |\n| 12 | The eval framework is authoritative; a new invariant ships with its regression test |\n| 13 | Every spawn + LLM call emits paired audit events (two-tier) |\n\n§1 and §8 are fully enforced in `inline` mode; under real-LLM modes (`claude-cli` / `anthropic-sdk`) they are advisory unless you sandbox the spawned process. See [docs/POSITIONING.md](docs/POSITIONING.md) for the full trust model.\n\n## Agent dispatch modes\n\nsgc auto-detects an LLM backend per priority: `ANTHROPIC_API_KEY` → **anthropic-sdk** (direct API + prompt caching) · `claude` binary in PATH → **claude-cli** (subscription-friendly) · otherwise **file-poll** (you fulfill prompts manually via `sgc agent-loop`). Force a mode with `SGC_AGENT_MODE=\u003cmode\u003e`.\n\n## Architecture\n\n```\ncontracts/        spec source-of-truth — capabilities.yaml, state.schema.yaml, invariants.md\nsrc/\n  sgc.ts          citty CLI (19 subcommands)\n  commands/       one implementation per subcommand\n  dispatcher/     spawn protocol, scope tokens, dedup, embedded contracts/prompts, state I/O\nplugins/sgc/\n  bin/sgc.mjs     self-contained Node bundle shipped to /plugin install (contracts+prompts inlined)\n  {skills,commands,hooks}/   markdown prompt layer + slash commands + SessionStart hook\n  browse/         vendored headless-browser source (compiles to a single binary)\ntests/dispatcher/ deterministic unit + integration suite (bun test)\ntests/eval/       end-to-end LLM scenarios (Invariant §12)\n```\n\nThe Node bundle inlines `contracts/` + `prompts/`, so the shipped CLI is fully self-contained. `sgc doctor` verifies the committed bundle matches a fresh rebuild (`scripts/build-cli.mjs`), and CI fails on a stale bundle.\n\n## Test\n\n```bash\nnpm test              # deterministic dispatcher suite (1051 tests, 0 flake)\nnpm run test:eval     # real-LLM evaluation lane (gated on API keys)\nnpm run typecheck     # tsc --noEmit (strict)\n```\n\nCI (`.github/workflows/test.yml`) runs the dispatcher suite + typecheck + a bundle-freshness gate on every push/PR.\n\n## FAQ\n\n**Do I need bun, Superpowers, or gstack to use sgc?**\nNo. As of v1.24.0 the CLI ships as a self-contained Node bundle — `/plugin install sgc` gives you a working CLI on any machine with Node ≥ 18. sgc runs the full loop standalone; if `superpowers` / `gstack` are installed it can interoperate, but neither is required.\n\n**How does sgc install in one command?**\n`/plugin marketplace add sdsrss/sgc` then `/plugin install sgc`. The plugin payload contains the compiled Node bundle plus the slash-command prompt layer, so there is no separate CLI install step.\n\n**What makes sgc different from a generic AI coding assistant?**\nIt enforces a level-appropriate process (L0–L3), 13 machine-checked invariants, and a deduplicated knowledge corpus that compounds across tasks — so review rigor scales with risk and lessons are reused, not relearned.\n\n**Where is my data stored?**\nPer-project, per-machine, under a `.gitignore`d `.sgc/` directory. There is no telemetry and no built-in cloud sync (cross-machine knowledge sharing is on the roadmap).\n\n## Links\n\n- npm: [@sdsrs/sgc](https://www.npmjs.com/package/@sdsrs/sgc)\n- Changelog: [CHANGELOG.md](CHANGELOG.md)\n- Positioning \u0026 trust model: [docs/POSITIONING.md](docs/POSITIONING.md)\n- Curated solutions/preventions: [docs/SOLUTIONS.md](docs/SOLUTIONS.md)\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsdsrss%2Fsgc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsdsrss%2Fsgc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsdsrss%2Fsgc/lists"}