# AWKit — All-in-one Workflow Kit > **AWKit Core** · Single Source of Truth · Symphony-first · Context Pruning AWKit is a professional AI-agent orchestration framework. This repository is the single source of truth for workflows, skills, core rules (`core/GEMINI.md`), and installation tooling. --- ## Multi-Agent Symphony Model AWKit operates through hierarchical collaboration. The Main Agent acts as the central Orchestrator while specialized Sub-agents execute narrow-scope tasks. ### 1. Symphony Flow ```text [User Request] │ ▼ ┌──────────────┐ │ Orchestrator │ (Gemini Flash) │ (Triage) │ Create sub-tasks in task.md └──────┬───────┘ ├─────────────────────────┐ ▼ ▼ ┌──────────────┐ ┌──────────────┐ │ Designer │ (Luna) │ Reasoning │ (Fable/Sol) │ (UI Assets) │ Mockups │ (SystemPlan) │ implementation_plan.md └──────┬───────┘ └──────┬───────┘ │ │ └──────────┬──────────────┘ ▼ ┌──────────────┐ │ Runner │ (Qwen/Spark) │ (Write Code) │ Edit file contents / Write logic └──────┬───────┘ │ ▼ ┌──────────────┐ │ Audit │ (Fable/Sol) │ (CodeReview) │ Lint check, run unit tests & commit └──────────────┘ ``` ### 2. Logical Role Bindings Roles are resolved dynamically based on priority lists in `.project-identity` or global configurations: - **orchestrator**: Central dispatcher and triage (Gemini 3.5 Flash via `agy`). - **reasoning**: System plans and structural reviews (Claude Fable via `claude` / GPT Sol via `codex`). - **runner**: File editing and coding tasks (Qwen Coder via `qwen` / Codex Spark via `codex`). - **designer**: Graphic designs, visual mockups, and spritesheets (GPT Luna via `codex`). - **audit**: Code review, type checks, and verification (Claude Fable / GPT Sol). --- ## Setup & Installation ### 1. Global Package Installation Install the AWKit CLI utility globally on your local environment: **Via HTTPS:** ```bash npm install -g @leejungkiin/awkit && awkit install ``` --- ### 2. Initial Setup & Basic Usage (`awkit install`) AWKit coordinates sync states between your local **Project Directory (Source of Truth)** and the active **AI Runtime Directory** (`~/.gemini/antigravity-ide/`) where the AI actually reads configurations. To deploy all local rules, workflows, and templates from your project directory directly to the active AI runtime environment: ```bash awkit install ``` _Note: You must run `awkit install` whenever you modify configuration files or rules in your project workspace so that active AI agents can read the latest policies._ To deploy to all active platform profiles (Codex, Claude Code, Qwen, Cursor AI) at once: ```bash awkit install --all ``` --- ### 3. Overwriting & Force-Reinstalling If you need to force-reinstall AWKit or overwrite current runtime files over older cached global scripts, run the global npm installer with the `--force` flag: ```bash # Force reinstall the CLI utility globally npm install -g @leejungkiin/awkit --force # Or target a specific tagged release or commit hash npm install -g @leejungkiin/awkit --force # Re-link runtime directories after reinstallation awkit install --all ``` --- ### 4. Clean Uninstall To completely remove the AWKit CLI and purge all local cached configurations, runtime profiles, and temporary drafts from your local system: ```bash # 1) Uninstall the global CLI package npm uninstall -g @leejungkiin/awkit # or if installed via fork link alias npm uninstall -g awkit # 2) Purge local configuration registries and active model settings rm -rf ~/.awkit ``` --- ## 🚀 Beginner's Quickstart Guide AWKit uses a bi-directional synchronization model to keep project codebases clean. ### 1. The Daily Workflow Loop ```text main-awf/ (Project Directory) ── awkit install ──> ~/.gemini/antigravity-ide/ (AI Runtime) <── awkit harvest ── <── awkit sync ──> ``` - **Golden Rule**: - Any edits to AI rules (`core/GEMINI.md`, `AGENTS.md`) or custom workflows must be done inside the **Project Directory (main-awf/)**. - After making changes, you must run `awkit install` to push them to the AI's active Runtime profiles. ### 2. Step-by-Step CLI Examples #### Example 1: Verify Sync Status Compare your local project codebase directories against the runtime profile to inspect file drifts: ```bash awkit status ``` _Purpose:_ Informs you if local changes are fully deployed to the AI runtime, or if the AI has edited files in the runtime that need harvesting. #### Example 2: Initialize a New Project Inject standard AWKit workspace files and skeletons into a newly initialized project: ```bash awkit init ``` _Purpose:_ Automatically bootstraps critical files such as `.project-identity`, `CODEBASE.md`, and default workspace templates. #### Example 3: Deploy Changes to AI Runtime Suppose you just updated some AI behavioral rules in `core/GEMINI.md`. Deploy them to the active runtime profile: ```bash awkit install ``` _Purpose:_ Installs the updated rules, symlinks skills, and registers templates for Codex, Claude Code, Qwen Code, and Cursor AI. #### Example 4: Sync Changes Back (Harvest) If the AI has created brainstorm drafts or modified files directly in its runtime directory, pull those changes back to the project repository: ```bash awkit harvest ``` _Purpose:_ Synchronizes runtime files back to the project root for safety checks and git commits. > **Tip:** Use `awkit sync` to execute both `harvest` and `install` in a single command. #### Example 5: Gated Git Commit Avoid calling `git commit` directly. Execute AWKit's automation gate to run syntax sanity checks and tests before committing: ```bash awkit gate git auto "feat(docs): translate readme to english and update v13.0 specs" ``` --- ## Core Principles AWKit enforces a set of non-negotiable principles to ensure safe and effective AI pairing: 1. **Anti-sycophancy**: AI must push back when an approach contains structural bugs; do not agree blindly. 2. **Search Before Building (3-layer)**: Verify NeuralMemory/codebase first → then standard libraries/SDKs → only write new code as a last resort. 3. **Completion Status Protocol**: Label exits using `DONE`, `DONE_WITH_CONCERNS`, `BLOCKED`, or `NEEDS_CONTEXT`. 4. **Decision Principles**: Complete > Shortcuts, Evidence > Assumptions, Standard > Custom, Explicit > Implicit, Test > Trust, Small > Big. 5. **3-Strike Escalation**: Stop and report context to the developer if an issue persists after 3 unsuccessful bug-fixing attempts. 6. **Scope Freeze for Debugging**: Avoid refactoring unrelated systems while addressing bug fixes. 7. **"Boil-the-lake" Verification Checklist**: Verify error handling, boundary constraints, logging, and performance before exiting. 8. **Safety Guardrails**: Block dangerous commands by default; require developer authorization. --- ## Context Compression Engine (CCE) To prevent model amnesia, bugs, and API token waste, AWKit applies an advanced **Context Compression Engine** to optimize context sizes: ```text [Raw Chat History (60k tokens)] ────► [Caveman Compressor] ──► [Condensed History (3k tokens)] │ [Raw Source Code (400k tokens)] ────► [AST Signature Filter] ─► [Code Signatures (5k tokens)] ──► [Optimized Prompt] │ [System Guidelines] ────────────────► [RTK AST Compressor] ──► [Clean Rules (2k tokens)] ``` ### 1. Token Compression Levels - **RTK (Rust Token Killer)**: A built-in Rust AST pre-processor. It automatically cleans excess whitespaces, comments, formats brackets, and compresses JSON payloads before API requests, saving **20% - 30%** of input tokens. - **Caveman Mode**: Triggered when chat histories exceed 50% of the model's context window. It condenses conversational logs, explanations, and warnings into strict technical bullet points, saving up to **75%** of context. - **ContextPack Isolation**: Using flags with `awkit exec`: - `--no-context`: Drops conversational history entirely, keeping prompt context clean. - `--files `: Instructs AWKit to extract only AST class signatures/definitions of the target file rather than loading raw text. - `--context-summary`: Forces the compiler to summarize chat histories prior to invocation. ### 2. Memory Preservation - **Spec Digest Boundary**: Main Agents are **forbidden** from reading design specs, API documentation, or log files exceeding **200 lines** directly. Loading large raw documents causes reasoning degradation. - _Mechanism:_ The Orchestrator delegates a light agent (Gemini Flash via `agy`) to read raw specs and output a compressed summary to `scratch/digest-.md` (< 80 lines). The Main Agent references only this digest. - **Brain Artifact Cleanup**: Session-specific plans and critiques are isolated in `brain//` folders rather than cluttering workspaces, preventing file indexers from recurse-loading temporary drafts. --- ## CLI Command Reference | Command | Description | | ---------------------------------------- | ----------------------------------------------------------------------------- | | `awkit env` | Inspect runtime environments, binary paths, and constitution bindings | | `awkit doctor` | Scans system health (workflows, schemas, active configurations) | | `awkit model list` | Lists registered models in the registry and their connectivity status | | `awkit model ping ` | Tests response latencies for a specific model endpoint | | `awkit config set ""` | Sets logical runner priorities, audio notifications, or proxy parameters | | `awkit exec -m -t ""` | Summons a dedicated sub-agent (supports ContextPack flags) | | `awkit install` | Installs AWKit core runtime profiles to the active IDE profile | | `awkit install --all` | Installs runtime profiles to all supported IDE profiles (Claude, Codex, etc.) | | `awkit sync` | Runs full sync cycle: harvests runtime changes, then installs | | `awkit status` | Compares the local repository against the installed runtime (drifts view) | | `awkit harvest` | Pulls files from `~/.gemini/antigravity-ide/` back into this repository | | `awkit gate git auto ""` | Performs verification gate checks, commits, and pushes changes | --- ## Repository Layout ```text main-awf/ (Source of Truth) ├── bin/ # CLI entry points ├── core/ # Core rules/routing for agents ├── workflows/ # Workflow library ├── skills/ # Source skill library ├── schemas/ # JSON schemas ├── templates/ # Project templates ├── scripts/ # Tools, harvest and automation gates └── package.json # @leejungkiin/awkit ``` --- ## License MIT --- ## Troubleshooting: `npm warn allow-scripts` If you encounter a warning like: ```text npm warn allow-scripts 21 packages have install scripts not yet covered by allowScripts ... Run `npm approve-scripts --allow-scripts-pending` to review, or `npm approve-scripts ` to allow. ``` ### Why this happens The project utilizes a security mechanism (such as `allow-scripts` or npm auto-run script blocking configurations) to protect your development environment from supply chain attacks. Third-party packages containing lifecycle scripts (such as `preinstall`, `install`, or `postinstall` scripts in packages like `better-sqlite3`, `sharp`, and `tree-sitter`) are temporarily blocked until you review and approve them. ### Quick Fixes You can quickly approve all trusted packages for the project by running the following loop in your Terminal: ```bash for pkg in @ladybugdb/core @duytransipher/gitnexus @google/genai @leejungkiin/awkit-symphony better-sqlite3 onnxruntime-node protobufjs sharp tree-sitter tree-sitter-c tree-sitter-c-sharp tree-sitter-cpp tree-sitter-go tree-sitter-java tree-sitter-javascript tree-sitter-kotlin tree-sitter-php tree-sitter-python tree-sitter-ruby tree-sitter-rust tree-sitter-typescript; do npm approve-scripts $pkg; done ```