@ngockhoale/ukit 2.2.14 → 2.3.0

package/templates/docs/INSTALL.md

@@ -1,115 +0,0 @@
-# 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/AI_HANDOFF/`
-- `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/AI_HANDOFF/`
-- `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/STATUS.md

@@ -1,81 +0,0 @@
-# Project Status — {{project.name}}
-
-> Living project state for AI sessions.
-> Keep this compact: current state only, not a session transcript.
-> Source code, tests, and the UKit index remain ground truth.
-
-## Freshness
-
-- Last meaningful update: TODO YYYY-MM-DD HH:mm
-- Updated by: TODO
-- Status confidence: low
-- Stale after: 72h
-
-If this file is stale, AI must treat it as orientation only and verify against source/index before recommending or editing.
-
-## Snapshot
-
-- Current focus: TODO
-- Health: unknown
-- Branch/state: TODO
-- Release/version: TODO
-
-## Active Work
-
-<!-- Keep only live work. Move finished work to Recently Completed or WORKLOG.md. -->
-
-### TODO work item
-
-- Status: planned / in-progress / blocked / done
-- Goal: TODO
-- Done: TODO
-- Remaining: TODO
-- Files involved: TODO
-- Verification: TODO
-- Next action: TODO
-
-## Current Debug Threads
-
-<!-- Detailed bug context belongs in docs/context/<task>.md when that exists. STATUS should only link/summarize. -->
-
-### TODO debug thread
-
-- Status: investigating / root cause found / fixed / blocked
-- Symptom: TODO
-- Root cause: unknown
-- Evidence: TODO
-- Changed files: TODO
-- Verification: TODO
-- Remaining risk: TODO
-- Next action: TODO
-
-## Decisions Pending
-
-- [ ] TODO decision
-  - Context: TODO
-  - Options: TODO
-  - Recommended: TODO
-
-## Next Candidates
-
-1. TODO candidate
-   - Why now: TODO
-   - Expected files: TODO
-   - Verification: TODO
-   - Risk: TODO
-
-## Recently Completed
-
-<!-- Max 10 compact lines. Use docs/WORKLOG.md for session history. -->
-
-- TODO YYYY-MM-DD — summary — verification
-
-## Notes for Next AI Session
-
-- Read first: docs/STATUS.md, then docs/CODE_MAP.md only if navigation is needed.
-- Avoid: treating this file as source truth when it is stale or contradicted by code/tests.
-- Known traps: keep concrete debug/implementation prompts on their specific workflow; do not turn them into global roadmap suggestions.
-
-## Future Candidate: Task Context Files
-
-v1.2 candidate: task-scoped `docs/context/<slug>.md` files for granular bug/feature context. Keep this out of default scope unless a project already uses that folder.

package/templates/docs/TASKS.md

@@ -1,79 +0,0 @@
-# AI Task Queue — {{project.name}}
-
-> Local AI task queue.
-> Use this for work the human wants an AI/agent to pick up later.
-> Keep tasks actionable; source code, tests, and project docs remain ground truth.
-
-## How to Use
-
-- Human or AI can add tasks here when work is deferred.
-- AI should read this for open-ended “what next?” / “continue” prompts, or when the user asks to work from the task queue.
-- AI/agents may implement tasks from `Ready for AI`; do not dispatch from `Inbox` until the task has acceptance and verification notes.
-- This file is local working state, not project history and not a full roadmap.
-- Completed work belongs in `docs/WORKLOG.md`; current state belongs in `docs/STATUS.md`.
-
-## Auto-Cleanup Rules
-
-AI should keep this file compact by default whenever it reads or updates the queue:
-
-- Auto-remove exact duplicate tasks.
-- Auto-prune `Done Recently` to max 10 compact lines.
-- Auto-remove tasks from active sections after all are true:
-  - the task is done,
-  - verification is recorded,
-  - completion is summarized in `docs/WORKLOG.md` or `Done Recently`.
-- Auto-move stale, vague, or blocked tasks to `Deferred / Needs Human Review` instead of deleting them.
-- Do not delete non-completed human-authored tasks unless the user explicitly asks for cleanup and the task is clearly obsolete or duplicated.
-- If the user says “clean tasks” / “dọn tasks”, perform the cleanup pass and report what changed.
-
-## Inbox
-
-<!-- Raw ideas go here first. Refine before moving to Ready for AI. -->
-
-- [ ] TODO task title
-  - Why: TODO
-  - Context: TODO
-  - Expected files: TODO
-  - Acceptance: TODO
-  - Verification: TODO
-  - Risk: low / medium / high
-
-## Ready for AI
-
-<!-- Tasks here should be specific enough for an AI/agent to start without scanning the whole repo. -->
-
-- [ ] TODO ready task
-  - Goal: TODO
-  - Files likely involved: TODO
-  - Constraints: TODO
-  - Acceptance: TODO
-  - Verification: TODO
-  - Notes: TODO
-
-## In Progress
-
-- [ ] TODO active task
-  - Owner: human / Claude / Codex / OpenCode / agent
-  - Started: TODO YYYY-MM-DD
-  - Current state: TODO
-  - Next action: TODO
-
-## Blocked / Waiting
-
-- [ ] TODO blocked task
-  - Blocker: TODO
-  - Needed from human: TODO
-
-## Deferred / Needs Human Review
-
-<!-- AI should move stale/vague/blocked tasks here instead of deleting uncertain human intent. -->
-
-- [ ] TODO deferred task
-  - Reason deferred: TODO
-  - Last touched: TODO YYYY-MM-DD
-
-## Done Recently
-
-<!-- Keep max 10. Older completed work belongs in docs/WORKLOG.md. -->
-
-- TODO YYYY-MM-DD — task — verification

package/templates/docs/UKIT_USAGE_GUIDE.md

@@ -1,163 +0,0 @@
-# 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
-- living project status for open-ended continuation prompts
-- 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
-
-### F) Continue / what next
-
-User says:
-
-```text
-Project đang ở đâu, làm gì tiếp?
-```
-
-Expected UKit behavior:
-1. auto-load the hidden next-step lane
-2. read `docs/AI_HANDOFF/ACTIVE.md` when the team is passing planning, task breakdown, or implementation context between AIs
-3. verify the handoff against source/index before treating it as authoritative
-4. suggest only a few actionable next candidates
-5. if the prompt names a concrete bug/feature/review target, keep the concrete workflow primary instead of producing a global roadmap
-
----
-
-## 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.