@ngockhoale/ukit 1.1.6

package/templates/docs/CODE_MAP.md

@@ -0,0 +1,35 @@
+# Code Map — {{project.name}}
+
+> Navigation aid for AI sessions. Source code is ground truth.
+> If this conflicts with source → source wins. Update this file to match source.
+> AI: when you discover new structure, fill this in. Do not wait to be asked.
+
+## Module Map
+
+<!-- path/ — what it is responsible for — entry point if non-obvious -->
+<!-- AI: scan the repo structure and fill this in during your first session. -->
+
+## Key Files
+
+<!-- file — what it does — when to read it -->
+<!-- AI: add files here as you discover their purpose during implementation. -->
+
+## Data Flow
+
+<!-- End-to-end: request/trigger → processing steps → output/side effects -->
+<!-- AI: infer from reading controllers, services, middleware. Fill in what you find. -->
+
+## External Integrations
+
+<!-- Service name — purpose — which module calls it -->
+<!-- AI: grep for fetch/axios/http calls, env vars for external URLs. -->
+
+## Test Coverage
+
+<!-- Test directory — what's covered — known gaps -->
+<!-- AI: scan test files, note what's missing. -->
+
+## Dangerous Areas
+
+<!-- Areas that are complex, fragile, or caused past bugs. -->
+<!-- AI: flag areas with deep conditionals, many side effects, or noted in WORKLOG. -->

package/templates/docs/INSTALL.md

@@ -0,0 +1,113 @@
+# Installation Guide
+
+## Team Rule
+
+**For this project, the only UKit command teammates should need to remember is `ukit install`.**
+
+After it runs, the normal workflow is:
+1. fill the docs baseline
+2. open the AI tool
+3. work in natural language
+
+Do not turn normal onboarding into a list of UKit subcommands.
+How the CLI binary itself gets installed or updated can stay a maintainer/platform concern; inside projects, the human-facing workflow still centers on `ukit install`.
+
+---
+
+## Initial Installation
+
+### 1) Install the UKit CLI
+
+```bash
+npm install -g @ngockhoale/ukit
+```
+
+### 2) Install UKit into this project
+
+Run from the project root:
+
+```bash
+ukit install
+```
+
+This creates or refreshes the UKit workspace (`.claude/`, adapters, metadata, and `docs/`).
+
+It also provisions the shared runtime in `.ukit/storage/`, including:
+- memory state
+- prompt/output caches
+- compact history
+- threshold-based compact pressure tracking
+
+If the repo still has a legacy visible `ukit/` runtime from older installs, rerunning `ukit install` now migrates that shared runtime into hidden `.ukit/` when it is safe to do so.
+
+End users do not need to manage any of that manually.
+
+### 3) Fill in the docs baseline
+
+Complete these files before first serious use:
+- `docs/PROJECT.md`
+- `docs/MEMORY.md`
+- `docs/WORKLOG.md`
+
+### 4) Open your AI tool
+
+After install, give natural-language requests such as:
+- review this change
+- fix this bug
+- implement this feature
+- follow the existing pattern
+
+No slash command is required.
+Teammates also should not need to know skill names — Claude Code / Codex should auto-detect and use the right project-local skill from the prompt plus the files/tools involved.
+The workspace should also lean on indexed source code to find files/tests fast and prefer targeted verification before broad blanket checks.
+When long sessions grow large, the shared runtime should compact old safe-zone context automatically near its configured threshold without changing the human workflow.
+By default, the soft threshold comes from the configured compact token threshold and the hard threshold is about 20% above that; UKit should compact logs/history first while preserving the active task, rules, decisions, and current code focus.
+
+---
+
+## Updating
+
+To refresh the workspace after UKit changes, rerun the same command:
+
+```bash
+ukit install
+```
+
+UKit is designed so first install and later refreshes use the same command.
+
+---
+
+## Troubleshooting
+
+### `ukit` command not found
+
+```bash
+npm install -g @ngockhoale/ukit
+```
+
+### Workspace files seem stale
+
+```bash
+ukit install
+```
+
+### The AI lacks project context
+
+Check that the docs baseline files exist and are filled in:
+- `docs/PROJECT.md`
+- `docs/MEMORY.md`
+- `docs/WORKLOG.md`
+
+---
+
+## Maintainer / Debug Note
+
+UKit may expose additional subcommands for maintainers and debugging. Upstream skill catalogs, GitHub skill repos, and awesome lists are also maintainer inputs — not the default team workflow.
+
+If maintainers pull ideas from official skill ecosystems or curated lists, they should package those improvements into UKit and have teammates rerun the same install command.
+
+Those sources should not become a new onboarding burden.
+
+When in doubt, keep the guidance simple:
+
+> rerun `ukit install`, then work in natural language inside the AI tool.

package/templates/docs/MEMORY.md

@@ -0,0 +1,49 @@
+# Project Memory
+
+## Protocol
+
+- **This is the most critical doc in the project.** Future AI sessions read this first to understand the system.
+- **Source code is ground truth.** If this file contradicts source → source wins, update this file immediately.
+- **After every non-trivial task**, ask: "What did I learn about this system?" → write it here if durable.
+- Keep entries concise and actionable — future sessions must be able to act on this in seconds.
+- Do NOT record temporary session notes here. Only durable knowledge.
+
+## AI Filling Guide
+
+<!-- When to write each section: -->
+<!-- Architecture Decisions → any time a "why" is settled (tech choice, pattern, approach) -->
+<!-- Active Constraints → any non-obvious rule AI must follow (security, layer boundaries, invariants) -->
+<!-- Known Bugs → any bug investigated: root cause + pattern to watch, even if not yet fixed -->
+<!-- Open Risks → deferred decisions, fragile areas, unresolved questions -->
+<!-- Session Handoff → always update "Last worked on" before ending a session -->
+
+## Architecture Decisions
+
+<!-- WHY choices were made. Prevents future sessions from re-debating settled questions. -->
+<!-- Format: [YYYY-MM-DD] Decision: X. Reason: Y. Do NOT change because: Z. -->
+
+## Active Constraints
+
+<!-- Rules AI must respect during implementation. Non-obvious limits not visible in the code. -->
+<!-- Example: Never bypass validate() in users/ — it's a security boundary, not optional. -->
+<!-- Example: Do not add direct DB calls in controllers — always go through service layer. -->
+
+## Known Bugs & Root Causes
+
+<!-- Prevents re-investigating the same issues across sessions. -->
+<!-- Format: [YYYY-MM-DD] Bug: X. Root cause: Y. Fix applied: Z. Watch for: W. -->
+
+## Open Risks
+
+<!-- Unresolved questions, known fragile areas, or deferred decisions. -->
+<!-- Clear this entry once the risk is resolved. -->
+
+## Session Handoff
+
+- Last worked on: —
+- Next step: —
+
+## Completed Milestones
+
+<!-- Significant shipped work. For historical context. One line per milestone. -->
+<!-- Format: [YYYY-MM-DD] Milestone: X. Verified by: Y. -->

package/templates/docs/PROJECT.md

@@ -0,0 +1,50 @@
+# {{project.name}} — Project Context
+
+## Stack
+
+- Runtime: Node {{runtime.nodeVersion}} | OS: {{runtime.os}} | PM: {{runtime.packageManager}}
+- Frontend: {{stack.frontend}} | Backend API: {{stack.backendApi}} | PostgreSQL: {{stack.postgres}}
+- Provider: {{providers.unic}}
+
+## Architecture
+
+<!-- 3-5 sentences describing what this system does, its main components, and how they connect. -->
+<!-- Fill in after initial setup. If empty, AI must read source carefully — no shortcuts. -->
+
+## Key Modules
+
+<!-- path/ — what it is responsible for — entry point if non-obvious -->
+<!-- Example: src/auth/    — JWT + session management        — auth.service.ts -->
+<!-- Example: src/orders/  — core business logic             — orders.service.ts -->
+
+## Data Flow
+
+<!-- How data moves through the system end-to-end. -->
+<!-- Example: HTTP request → auth.guard → controller → service → repository → PostgreSQL -->
+<!-- Include: external APIs called, message queues, background jobs, key middleware. -->
+
+## Business Rules & Domain Constraints
+
+<!-- Rules that CANNOT be violated. Non-obvious logic that isn't clear from the code. -->
+<!-- Example: "Orders cannot be deleted — only cancelled. Status machine: draft→confirmed→cancelled." -->
+<!-- If this section is empty, AI must not assume business rules from code patterns alone. -->
+
+## Known Dangerous Areas
+
+<!-- Complex, fragile, or bug-prone code. Flag before AI touches these areas. -->
+<!-- Example: src/pricing.ts — complex discounting logic, 2 past bugs, always run full test suite. -->
+
+## Delivery Profile
+
+- Primary workflow: natural-language AI tooling installed by UKit
+- Shared adapters: Claude Code, OpenAI Codex, Antigravity
+- Change policy: smallest correct change with clear verification
+
+## Session Start Routine
+
+1. Run `ukit memory recall "<current task>"` for non-trivial work; reuse relevant `## Previous Context` before asking the user to restate prior decisions
+2. Read `docs/MEMORY.md` — architecture decisions, active constraints, known bugs
+3. Read `docs/CODE_MAP.md` if it exists — structural navigation index
+4. Use the installed source-code index / routed helpers to localize the smallest relevant file + test set first
+5. Scan recent `docs/WORKLOG.md` entries if continuing prior work
+6. Verify understanding against source before acting — **docs orient, source is truth; keep the index-first workflow intact**

package/templates/docs/UKIT_USAGE_GUIDE.md

@@ -0,0 +1,147 @@
+# UKit Usage Guide
+
+## Core Product Promise
+
+**Teammates should only need to remember one UKit command:**
+
+```bash
+ukit install
+```
+
+After that, the expected workflow is natural language.
+
+UKit should handle:
+- hidden skill selection
+- source-code indexing
+- compact context selection
+- targeted verification
+- optional internal delegation when it is actually useful
+
+The user should **not** need to know skill names, router names, or agent names.
+
+---
+
+## How UKit should behave
+
+### 1) Prompt first
+The user asks naturally:
+- `review this PR for regressions`
+- `fix login bug in src/api/auth/login.js`
+- `clone this screen following the existing pattern`
+- `containerize this app with Docker and docker compose`
+- `làm theo kiểu duraone cho flow này`
+
+### 2) Skill auto-detection
+UKit should infer the right lane from:
+- prompt wording
+- target file path
+- tools already used (`Read`, `Grep`, `Glob`, `Edit`, `Write`, `Bash`)
+
+### 3) Index-first localization
+For real code work, UKit should use the **source-code index first** to find:
+- primary targets
+- analog/reference files
+- shared abstractions
+- related tests
+
+This is extremely important: the index is what keeps file discovery fast and token-efficient.
+
+### 4) Minimal useful verification
+After the lane is clear, UKit should verify in scope order:
+1. related tests
+2. then lint/typecheck if the scope warrants it
+3. then broader checks only when risk/shared scope justifies it
+
+### 5) Internal delegation only when it helps
+Subagents/internal delegation are optional implementation details.
+They are useful when they:
+- reduce context pollution
+- allow parallel side work
+- isolate noisy debug/research lanes
+
+They are **not** part of the end-user mental model.
+
+---
+
+## Common workflows
+
+### A) Fix a bug
+User says:
+
+```text
+Fix the failing order summary total in src/cart/summary.ts and add the right test coverage.
+```
+
+Expected UKit behavior:
+1. activate debug/testing lane if relevant
+2. use the index to find the target + related test files
+3. patch the smallest relevant area
+4. run targeted verification first
+
+### B) Review code
+User says:
+
+```text
+Review this auth permission change for regressions.
+```
+
+Expected UKit behavior:
+1. activate review/security lane if relevant
+2. localize files with the index
+3. inspect risky shared abstractions and related tests
+4. avoid unrelated broad reads
+
+### C) Clone/follow pattern
+User says:
+
+```text
+Create supplier detail page similar to customer detail page.
+```
+
+Expected UKit behavior:
+1. use the index to find the closest analog page
+2. open shared abstractions and related tests
+3. follow existing project structure instead of generating generic code
+
+### D) Docker / packaging
+User says:
+
+```text
+Package this app into Docker with a Dockerfile and docker compose setup.
+```
+
+Expected UKit behavior:
+1. auto-load the hidden Docker packaging lane
+2. still use the source-code index first to identify entrypoints, env, ports, services
+3. generate packaging assets that match the real app
+
+### E) DuraOne style
+User says:
+
+```text
+Làm theo kiểu duraone cho màn agreement này.
+```
+
+Expected UKit behavior:
+1. if the DuraOne skill is installed, auto-load it
+2. use DuraOne references only when the repo actually matches that domain/shape
+3. keep the user away from manual skill selection
+
+---
+
+## What users should NOT need to do
+
+Users should not need to:
+- remember `/ukit`-style slash commands
+- remember skill names
+- choose subagents manually
+- know router/helper filenames
+- manually orchestrate verification order
+
+If UKit requires that, the UX is drifting away from the product goal.
+
+---
+
+## One-line summary
+
+> `ukit install`, then ask naturally. UKit should auto-pick the right hidden skill, use the source-code index to find files fast, and verify only as broadly as needed.

package/templates/docs/WORKLOG.md

@@ -0,0 +1,10 @@
+# Worklog
+
+Track session-level execution details.
+
+For each significant action, append:
+- Date/time
+- Action taken
+- Files changed
+- Verification run
+- Outcome

package/templates/ukit/README.md

@@ -0,0 +1,14 @@
+# UKit Shared Runtime
+
+This folder stores shared UKit runtime state for v1.1.6 features.
+
+- `storage/config.json` — runtime feature flags and defaults
+- `storage/cache/` — prompt-cache, compact history, compact pressure state, output summaries, and preserved raw tool outputs under `storage/cache/tee/`
+- `storage/memory/` — shared file-based memory across agents
+
+The compact-pressure state is used to trigger conservative auto-compact behavior near the configured session threshold:
+- soft threshold = configured compact token threshold
+- hard threshold = about 20% above soft
+- preserve active task, rules, decisions, and current code focus first
+
+This folder is generated by `ukit install` and is safe to keep local-only.

package/templates/ukit/storage/cache/compact-history.json

@@ -0,0 +1,3 @@
+{
+  "entries": []
+}

package/templates/ukit/storage/cache/compact-pressure.json

@@ -0,0 +1 @@
+{"updatedAt":0,"softThreshold":100000,"hardThreshold":120000,"baselineTokens":18000,"estimatedContextTokens":0,"estimatedTotalTokens":0,"phase":"monitor","taskMode":"chat","routingContext":{},"recentPrompts":[],"recentOutputs":[],"latestPlan":null,"historyLayers":[],"stats":{"thresholdHits":0,"softHits":0,"hardHits":0}}

package/templates/ukit/storage/cache/output-history.json

@@ -0,0 +1,3 @@
+{
+  "entries": []
+}

package/templates/ukit/storage/cache/prompt-cache.json

@@ -0,0 +1,3 @@
+{
+  "entries": []
+}

package/templates/ukit/storage/config.json

@@ -0,0 +1,37 @@
+{
+  "version": "1.1.6",
+  "agent": "claude-code",
+  "compact": {
+    "enabled": true,
+    "tokenThreshold": 100000,
+    "contextRotDetection": true,
+    "askBeforeDrop": true
+  },
+  "tokenPipeline": {
+    "inputCompression": true,
+    "outputCompression": true,
+    "promptCache": true
+  },
+  "router": {
+    "enabled": true,
+    "defaultModel": "claude-sonnet-4-6",
+    "advisorModel": "claude-opus-4-6",
+    "advisorEnabled": true,
+    "maxAdvisorCalls": 3
+  },
+  "memory": {
+    "enabled": true,
+    "autoCapture": true,
+    "progressiveRetrieval": true,
+    "maxInjectionTokens": 1000,
+    "archiveAfterDays": 30,
+    "maxSessions": 20,
+    "redactSecrets": true
+  },
+  "validation": {
+    "enabled": true,
+    "autoRetry": true,
+    "maxRetries": 1,
+    "confidenceThreshold": 50
+  }
+}

package/templates/ukit/storage/memory/projects/.gitkeep

@@ -0,0 +1,2 @@
+,
+    'templates/ukit/storage/memory/sessions/.gitkeep': 

package/templates/ukit/storage/memory/user.json

@@ -0,0 +1,5 @@
+{
+  "preferences": {},
+  "rules": [],
+  "updatedAt": 0
+}