{"id":48891309,"url":"https://github.com/unknown-studio-dev/hoangsa","last_synced_at":"2026-04-16T08:04:44.303Z","repository":{"id":344516190,"uuid":"1177935235","full_name":"unknown-studio-dev/hoangsa","owner":"unknown-studio-dev","description":"HOANGSA is a context engineering system for Claude Code. It solves a fundamental problem: Claude's output quality degrades as the context window fills up.","archived":false,"fork":false,"pushed_at":"2026-03-15T16:17:28.000Z","size":441,"stargazers_count":16,"open_issues_count":2,"forks_count":1,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-04-14T16:32:35.868Z","etag":null,"topics":["claude","claude-code","context-engineering","meta-prompting","spec-driven-development"],"latest_commit_sha":null,"homepage":"","language":"Rust","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/unknown-studio-dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"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-03-10T14:20:33.000Z","updated_at":"2026-04-07T03:48:44.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/unknown-studio-dev/hoangsa","commit_stats":null,"previous_names":["pirumu/hoangsa","unknown-studio-dev/hoangsa"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/unknown-studio-dev/hoangsa","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unknown-studio-dev%2Fhoangsa","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unknown-studio-dev%2Fhoangsa/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unknown-studio-dev%2Fhoangsa/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unknown-studio-dev%2Fhoangsa/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/unknown-studio-dev","download_url":"https://codeload.github.com/unknown-studio-dev/hoangsa/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unknown-studio-dev%2Fhoangsa/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31876860,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-16T07:36:03.521Z","status":"ssl_error","status_checked_at":"2026-04-16T07:35:53.576Z","response_time":69,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: 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":["claude","claude-code","context-engineering","meta-prompting","spec-driven-development"],"created_at":"2026-04-16T08:04:08.405Z","updated_at":"2026-04-16T08:04:44.297Z","avatar_url":"https://github.com/unknown-studio-dev.png","language":"Rust","readme":"# HOANGSA\n\n\u003e A context engineering system for Claude Code — split work into bounded tasks, each with a fresh context window.\n\n![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)\n![npm version](https://img.shields.io/npm/v/hoangsa-cc.svg)\n![Claude Code](https://img.shields.io/badge/Claude_Code-compatible-blueviolet.svg)\n![Built with Rust](https://img.shields.io/badge/Built_with-Rust-orange.svg)\n![Node.js](https://img.shields.io/badge/Node.js-18+-green.svg)\n\n---\n\n## What is HOANGSA?\n\nHOANGSA is a context engineering system for [Claude Code](https://docs.anthropic.com/en/docs/claude-code). It solves a fundamental problem: **Claude's output quality degrades as the context window fills up.**\n\nThe fix is structural. HOANGSA splits work into discrete tasks. Each task runs in a fresh context window with only the files it actually needs. The result is consistent, high-quality output across arbitrarily large projects.\n\nThe core pipeline:\n\n| Phase | Command | Output |\n|-------|---------|--------|\n| Design | `/hoangsa:menu` | DESIGN-SPEC + TEST-SPEC |\n| Plan | `/hoangsa:prepare` | Executable task DAG (`plan.json`) |\n| Execute | `/hoangsa:cook` | Working code, wave by wave |\n| Test | `/hoangsa:taste` | Acceptance test results |\n| Commit | `/hoangsa:plate` | Conventional commit |\n| Review | `/hoangsa:ship` | Code + security review, push/PR |\n\nThe orchestrator never writes code. It dispatches workers, each with a bounded context, and assembles results.\n\n---\n\n## Features\n\n**Context Engineering** — Each worker task runs in a fresh context window (200k tokens). The plan's `context_pointers` tell each worker exactly which files to read — no more, no less.\n\n**Spec-Driven Development** — Every feature starts with a DESIGN-SPEC and TEST-SPEC. Workers implement against specs, not vague instructions. Adaptive spec format for different task types (code, ops, infra, docs).\n\n**DAG-Based Execution** — Tasks organized as a directed acyclic graph. Independent tasks execute in parallel waves, dependent tasks execute sequentially. No unnecessary serialization.\n\n**3-Tier Verification** — Each task goes through static analysis, behavioral tests (x3), and semantic review against spec before proceeding.\n\n**Cross-Layer Bug Tracing** — `/hoangsa:fix` traces bugs across FE/BE/API/DB boundaries to find the real root cause before touching any code.\n\n**Pre-Ship Review Gates** — `/hoangsa:ship` runs code quality and security reviews in parallel, blocks on critical issues, and handles push or PR creation.\n\n**8-Dimension Codebase Audit** — `/hoangsa:audit` scans for code smells, security vulnerabilities, performance bottlenecks, tech debt, test coverage gaps, dependency risks, architectural violations, and documentation gaps.\n\n**Task Manager Integration** — Bidirectional sync with ClickUp and Asana. Pull task details as context, push status/comments/reports back after work completes.\n\n**GitNexus Code Intelligence** — Built-in call graph analysis. Impact analysis before edits, safe renames across the codebase, and full execution flow tracing.\n\n**Visual Debugging** — Analyze screenshots and screen recordings. Extract frames from video, generate montages, and overlay diffs to spot visual regressions.\n\n**Git Flow Management** — Built-in skill for task branching: start, switch, park, resume, finish, cleanup, sync. Auto-detects branching strategy and naming conventions.\n\n**Framework-Specific Worker Rules** — 15 framework addons (React, Next.js, Vue, Svelte, Angular, Express, NestJS, Go, Rust, Python, Java, Swift, Flutter, TypeScript, JavaScript) tune worker behavior per tech stack.\n\n**Multi-Profile Model Selection** — Switch between quality, balanced, and budget model profiles to match task requirements and cost constraints.\n\n---\n\n## Quick Start\n\n```bash\nnpx hoangsa-cc          # Install HOANGSA into your Claude Code environment\n/hoangsa:init           # Initialize project — detect codebase, set preferences\n/hoangsa:menu           # Design your first task\n```\n\nAfter `/hoangsa:menu` completes, follow with `/hoangsa:prepare` to generate a plan, then `/hoangsa:cook` to execute it.\n\n---\n\n## Installation\n\nPrerequisites: **Node.js 18+** and the **[Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code)**\n\n```bash\n# Interactive — asks whether to install globally or locally\nnpx hoangsa-cc\n\n# Install to ~/.claude/ — available in all projects\nnpx hoangsa-cc --global\n\n# Install to .claude/ — this project only\nnpx hoangsa-cc --local\n\n# Remove HOANGSA\nnpx hoangsa-cc --uninstall\n```\n\n| Flag | Short | Description |\n|------|-------|-------------|\n| `--global` | `-g` | Install to `~/.claude/` (all projects) |\n| `--local` | `-l` | Install to `.claude/` (this project only) |\n| `--uninstall` | `-u` | Remove HOANGSA |\n\nThe installer also sets up:\n- Lifecycle hooks (statusline, context monitor, update checker, GitNexus tracker)\n- GitNexus MCP server for code intelligence\n- Task manager MCP integration (if configured)\n- Quality gate skills (silent-failure-hunter, pr-test-analyzer, comment-analyzer, type-design-analyzer)\n\n---\n\n## Workflow\n\n```\nidea  →  /menu      Design    →  DESIGN-SPEC + TEST-SPEC\n      →  /prepare   Plan      →  Executable task DAG (plan.json)\n      →  /cook      Execute   →  Wave-by-wave, fresh context per task\n      →  /taste     Test      →  Acceptance tests per task\n      →  /plate     Commit    →  Conventional commit message\n      →  /ship      Review    →  Code + security gates, push/PR\n      →  /serve     Sync      →  Bidirectional task manager sync\n```\n\n**Design (`/menu`)** — Interview the user about requirements. Produce a structured DESIGN-SPEC with interfaces and acceptance criteria, plus a TEST-SPEC with test cases and coverage targets.\n\n**Plan (`/prepare`)** — Parse the specs and generate `plan.json`: a DAG of tasks, each with an assigned worker, bounded file list (`context_pointers`), and explicit dependency edges.\n\n**Execute (`/cook`)** — Walk the DAG wave by wave. Dispatch each worker with its context. Independent tasks in the same wave run in parallel. Each completed task goes through an auto-simplify pass before advancing.\n\n**Test (`/taste`)** — Run the acceptance tests defined in TEST-SPEC. Report pass/fail per task. Block the pipeline on failures, delegate fixes to `/hoangsa:fix`.\n\n**Commit (`/plate`)** — Stage changes and generate a conventional commit message from the completed work.\n\n**Review (`/ship`)** — Launch parallel code quality and security review agents. Block on critical/high issues. User decides: fix, override, or cancel. On pass, push and/or create PR with review summary.\n\n**Sync (`/serve`)** — Push status updates, comments, and artifacts back to the linked task manager.\n\n---\n\n## Commands\n\n### Core Workflow\n\n| Command | Description |\n|---------|-------------|\n| `/hoangsa:menu` | Design — from idea to DESIGN-SPEC + TEST-SPEC |\n| `/hoangsa:prepare` | Plan — convert specs to an executable task DAG |\n| `/hoangsa:cook` | Execute — wave-by-wave with fresh context per task |\n| `/hoangsa:taste` | Test — run acceptance tests per task |\n| `/hoangsa:plate` | Commit — generate and apply a conventional commit message |\n| `/hoangsa:ship` | Ship — code + security review, then push or create PR |\n| `/hoangsa:serve` | Sync — bidirectional sync with connected task manager |\n\n### Specialized\n\n| Command | Description |\n|---------|-------------|\n| `/hoangsa:fix` | Hotfix — cross-layer root cause tracing + minimal targeted fix |\n| `/hoangsa:audit` | Audit — 8-dimension codebase scan (security, debt, coverage, etc.) |\n| `/hoangsa:research` | Research — codebase analysis combined with external research |\n\n### Utility\n\n| Command | Description |\n|---------|-------------|\n| `/hoangsa:init` | Initialize — detect codebase, configure preferences, first-time setup |\n| `/hoangsa:check` | Status — show current session progress and pending tasks |\n| `/hoangsa:index` | Index — rebuild GitNexus code intelligence graph |\n| `/hoangsa:update` | Update — upgrade HOANGSA to the latest version |\n| `/hoangsa:help` | Help — show all available commands |\n\n---\n\n## Skills\n\nHOANGSA includes built-in skills that extend Claude Code's capabilities:\n\n### Git Flow\n\nTask-oriented git workflow management. Start a task branch, park work-in-progress, switch between tasks, and finish with push + PR — all with dirty-state guards and auto-detection of your branching strategy.\n\nFlows: `start` | `switch` | `park` | `resume` | `finish` | `cleanup` | `sync`\n\n### Visual Debug\n\nAnalyze screenshots and screen recordings to debug visual issues. Extracts frames from video files, generates montage grids for overview, and creates diff overlays to highlight changes between frames.\n\nSupports: `.png`, `.jpg`, `.webp`, `.gif`, `.mp4`, `.mov`, `.webm`, `.avi`, `.mkv`\n\n---\n\n## Configuration\n\nHOANGSA stores project configuration in `.hoangsa/config.json`.\n\n```json\n{\n  \"lang\": \"en\",\n  \"spec_lang\": \"en\",\n  \"tech_stack\": [\"typescript\", \"react\", \"postgres\"],\n  \"review_style\": \"strict\",\n  \"model_profile\": \"balanced\",\n  \"task_manager\": {\n    \"provider\": \"clickup\",\n    \"token\": \"\u003cyour-token\u003e\"\n  }\n}\n```\n\n### Preferences\n\n| Key | Values | Description |\n|-----|--------|-------------|\n| `lang` | `en`, `vi` | Language for orchestrator output |\n| `spec_lang` | `en`, `vi` | Language for generated specs |\n| `tech_stack` | array | Project technology stack (used to select worker rule addons) |\n| `review_style` | `strict`, `balanced`, `light` | Code review thoroughness |\n| `interaction_level` | `minimal`, `standard`, `detailed` | How much the orchestrator asks |\n\n### Model Profiles\n\nSelect a profile to control the model used at each role:\n\n| Profile | Worker | Designer | Reviewer |\n|---------|--------|----------|----------|\n| `quality` | claude-opus | claude-opus | claude-opus |\n| `balanced` | claude-sonnet | claude-opus | claude-sonnet |\n| `budget` | claude-haiku | claude-sonnet | claude-haiku |\n\nSwitch profiles with `/hoangsa:init` or by editing `model_profile` in `config.json`.\n\n### Task Manager Integration\n\n| Provider | How to connect |\n|----------|---------------|\n| ClickUp | Paste a ClickUp task URL |\n| Asana | Paste an Asana task URL |\n\nHOANGSA fetches task details as additional context and writes results back on `/hoangsa:serve`.\n\n---\n\n## Architecture\n\n### Project Structure\n\n```\nhoangsa/\n├── cli/                        # Rust CLI (hoangsa-cli)\n│   └── src/\n│       ├── cmd/                # Command modules\n│       │   ├── commit.rs       # Atomic commit\n│       │   ├── config.rs       # Config read/write\n│       │   ├── context.rs      # Context pointer resolution\n│       │   ├── dag.rs          # DAG traversal and wave scheduling\n│       │   ├── hook.rs         # Lifecycle hooks (statusline, context-monitor, tracker)\n│       │   ├── media.rs        # Video/image probing, frame extraction, montage\n│       │   ├── memory.rs       # Session memory\n│       │   ├── model.rs        # Model profile \u0026 role resolution\n│       │   ├── pref.rs         # User preferences\n│       │   ├── session.rs      # Session create/resume/list\n│       │   ├── state.rs        # Task state machine\n│       │   ├── validate.rs     # Plan/spec validation\n│       │   └── verify.rs       # Installation verification\n│       ├── helpers.rs          # Shared utilities\n│       └── main.rs\n├── templates/\n│   ├── commands/hoangsa/       # 15 slash command definitions\n│   ├── workflows/              # Workflow implementations\n│   │   ├── menu.md             # Design workflow\n│   │   ├── prepare.md          # Planning workflow\n│   │   ├── cook.md             # Execution workflow\n│   │   ├── taste.md            # Test workflow\n│   │   ├── plate.md            # Commit workflow\n│   │   ├── ship.md             # Review \u0026 ship workflow\n│   │   ├── fix.md              # Hotfix workflow\n│   │   ├── audit.md            # Audit workflow\n│   │   ├── research.md         # Research workflow\n│   │   ├── serve.md            # Task manager sync\n│   │   ├── init.md             # Project setup\n│   │   ├── update.md           # Update workflow\n│   │   ├── git-context.md      # Shared: git state detection\n│   │   ├── task-link.md        # Shared: task URL parsing\n│   │   └── worker-rules/       # Worker behavior rules\n│   │       ├── base.md         # Common patterns\n│   │       └── addons/         # 15 framework-specific addons\n│   └── skills/                 # Skill definitions\n│       └── hoangsa/\n│           ├── git-flow/       # Git workflow management\n│           └── visual-debug/   # Screenshot \u0026 video analysis\n├── bin/\n│   └── install                 # Node.js installer script\n├── npm/                        # Platform-specific binary packages\n│   ├── cli-darwin-arm64/\n│   ├── cli-darwin-x64/\n│   ├── cli-linux-arm64/\n│   ├── cli-linux-x64/\n│   ├── cli-linux-x64-musl/\n│   └── cli-windows-x64/\n├── package.json\n└── .hoangsa/                   # Project-local config and sessions\n    ├── config.json\n    └── sessions/               # Session artifacts (plan.json, specs, logs)\n```\n\n### Tech Stack\n\n| Layer | Technology | Purpose |\n|-------|-----------|---------|\n| CLI | Rust | Session management, DAG traversal, state machine, validation, media analysis, hooks |\n| Installer | Node.js | Package distribution, slash command registration, hook setup |\n| Code Intelligence | GitNexus MCP | Call graph, impact analysis, safe rename, execution flow tracing |\n| AI Runtime | Claude Code | Orchestrator + worker execution |\n\n### Hooks\n\nHOANGSA installs lifecycle hooks into Claude Code:\n\n| Hook | Event | Purpose |\n|------|-------|---------|\n| Statusline | `SessionStart` | Display session info, token usage, project context |\n| Context Monitor | `PostToolUse` | Track context window usage, warn on high utilization |\n| GitNexus Tracker | `PostToolUse` | Track file modifications for index freshness |\n| Update Checker | `SessionStart` | Notify when a new HOANGSA version is available |\n\n### Worker Rules \u0026 Framework Addons\n\nWorkers receive framework-specific guidance based on your `tech_stack` configuration. Available addons:\n\nAngular, Express.js, Flutter, Go, Java, JavaScript, NestJS, Next.js, Python, React, Rust, Svelte, Swift, TypeScript, Vue\n\n### How to Contribute\n\n1. Fork the repository at https://github.com/pirumu/hoangsa\n2. Run `pnpm run build` to compile the Rust CLI (`cargo build --release` inside `cli/`)\n3. Run `pnpm test` to verify the installation\n4. Slash command definitions live in `templates/commands/hoangsa/` — each is a Markdown file with YAML frontmatter\n5. Workflow logic lives in `templates/workflows/` — plain Markdown instructions for the AI\n6. Worker rule addons live in `templates/workflows/worker-rules/addons/`\n\n---\n\n## Supported Integrations\n\n### Task Managers\n\n- ClickUp\n- Asana\n\n### Code Intelligence\n\n- GitNexus MCP (call graphs, impact analysis, execution flow tracing, safe rename)\n\n### Quality Gate Skills\n\nOptionally installed during setup:\n\n- **silent-failure-hunter** — Identifies swallowed errors and inadequate error handling\n- **pr-test-analyzer** — Analyzes test coverage quality and completeness\n- **comment-analyzer** — Checks comment accuracy and documentation gaps\n- **type-design-analyzer** — Reviews type design for encapsulation and invariants\n\n### Language \u0026 Framework Support\n\nHOANGSA is language-agnostic. The worker-rules system has addons for:\n\n- JavaScript / TypeScript (React, Next.js, Vue, Svelte, Angular, Express, NestJS)\n- Rust\n- Python (FastAPI, Django)\n- Go\n- Java / Kotlin (Spring)\n- Swift / Flutter\n- And more via the base rules\n\n---\n\n## License\n\n[MIT](LICENSE) — Copyright (c) 2026 Zan\n\n---\n\n## Author\n\n**Zan** — [@pirumu](https://github.com/pirumu)\n\n---\n\n[Tiếng Việt](README.vi.md)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funknown-studio-dev%2Fhoangsa","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Funknown-studio-dev%2Fhoangsa","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funknown-studio-dev%2Fhoangsa/lists"}