Merge pull request #5 from udx/development

feat: Thin Empowerment Layer & AI Grounding Unification

Author: fqjony

.gitignore

@@ -1,4 +1,28 @@
+# Workspace
 .udx/
 .dev.kit/
+.codex/
+.tmp/
+tasks/
 
-.codex/
+# OS
+.DS_Store
+Thumbs.db
+
+# Shell / History
+*.log
+.bash_history
+.zsh_history
+
+# Editor
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Project specific
+node_modules/
+dist/
+build/
+.venv/
+__pycache__/

README.md

@@ -1,172 +1,63 @@
-<img src="assets/logo.svg" alt="dev.kit logo">
+<img src="assets/logo.svg" alt="dev.kit logo" width="200">
 
-# dev.kit
+# dev.kit — Resolve the Development Drift
 
-Deterministic developer workflow kit for humans + AI. One CLI entrypoint, shared prompts/templates under `src/`, and a stable contract for iteration.
+**Experienced engineering flow with no-bullshit results.**
 
-## Install
+`dev.kit` resolves the **Drift** (intent divergence) by **Normalizing** it into a deterministic path and **Iterating** to the result. It acts as a **Thin Empowerment Layer** (Grounding) that bridges chaotic intent with repository-based skills.
 
-Quick start (one-liner):
+## How it Works: The Grounding Bridge
 
-```bash
-curl -fsSL https://raw.githubusercontent.com/udx/dev.kit/main/bin/scripts/install.sh | bash
+`dev.kit` empowers AI agents (Gemini, Antigravity) with repository-centric grounding:
 
-# If the installer doesn't prompt for shell updates:
-source "$HOME/.udx/dev.kit/source/env.sh"
-```
+1.  **Grounding & Normalization**: Intent is mapped to repo-specific logic and normalized into a deterministic execution plan.
+2.  **Skill Discovery**: `dev.kit` exposes "Experienced Skills" directly to your AI agent's toolbelt (native skill discovery).
+3.  **Waterfall Progression**: AI iterates through instruction steps with deterministic validation and real-time feedback.
 
-```mermaid
-flowchart TD
-  A["Start"] --> B["Run installer"]
-  B --> C{"Shell update prompt?"}
-  C -->|"Yes"| D["Shell updates applied"]
-  C -->|"No"| E["Source env.sh"]
-  D --> F["Installed"]
-  E --> F
-```
+![Intent-to-Action Flow](assets/diagrams/intent-to-action.svg)
 
-## Configure (First Run)
+## Core Interface
 
-See current config:
+`dev.kit` focuses on repository health and agent empowerment, leaving high-level reasoning to your preferred agent.
 
-```bash
-dev.kit config show
-```
+- **`dev.kit status`**: (Default) Engineering brief and system diagnostic.
+- **`dev.kit ai`**: Unified agent integration management (Sync, Skills, Status).
+- **`dev.kit task`**: Manage the lifecycle of active workflows and sessions.
+- **`dev.kit config`**: Environment and repository orchestration settings.
 
-Defaults (out of the box):
+## Managed AI Skills
 
-- AI disabled (`ai.enabled = false`)
-- Minimal prompt (`exec.prompt = ai.codex.min`)
-- Non-streaming logs (`exec.stream = false`)
-- Repo-scoped context (`context.enabled = true`, `context.max_bytes = 4000`)
+`dev.kit` provides a suite of deterministic engineering skills that are grounded in your repository's truth:
 
-Optional: set explicit state path
+- **`visualizer`**: Generate and export high-fidelity Mermaid diagrams (SVG).
+- **`git-sync`**: Resolve repository drift with logical, atomic commits.
+- **`core`**: Maintain environment health and synchronize agent context.
 
-```bash
-dev.kit config set --key state_path --value "~/.udx/dev.kit/state"
-```
+> **Execution**: Run any skill with `dev.kit skills run <name>`.
 
-Enable AI (Codex):
+## AI Integration
 
-```bash
-dev.kit config set --key ai.enabled --value true
-dev.kit codex apply
-```
-
-```mermaid
-flowchart TD
-  A["Config show"] --> B{"Enable AI?"}
-  B -->|"Yes"| C["Set ai.enabled=true"]
-  C --> D["dev.kit codex apply"]
-  B -->|"No"| E["Keep AI disabled"]
-  D --> F["Configured"]
-  E --> F
-```
-
-## Use (Incremental)
-
-1. **Prompt-only (no AI installed)**  
-   Generate a deterministic prompt and run it in any tool:
-
-```bash
-dev.kit prompt --request "Summarize repo structure"
-```
-
-2. **AI-enabled (Codex installed)**  
-   Run `dev.kit exec` to generate + execute the prompt:
+`dev.kit` integrates natively with your AI agent to enforce standardization and repository truth.
 
 ```bash
-dev.kit exec "Summarize repo structure"
+# Sync skills and engineering context to your agent (Gemini/Codex)
+dev.kit ai sync
 ```
 
-If Codex is not installed, `dev.kit exec` prints the prompt so you can run it manually.
-
-3. **Dry-run (print only)**
+> **Grounding Layer**: `dev.kit` does not replace your agent; it hydrates it with the repository's source of truth.
 
-```bash
-dev.kit exec --print "Summarize repo structure"
-```
-
-```mermaid
-flowchart TD
-  A["Pick mode"] --> B["Prompt-only: dev.kit prompt"]
-  A --> C["AI-enabled: dev.kit exec"]
-  A --> D["Dry-run: dev.kit exec --print"]
-  B --> E["Run prompt manually"]
-  C --> F["Run via Codex"]
-  D --> E
-```
-
-## Auto-Detection + Suggestions
-
-- `dev.kit exec` uses the same prompt generator as `dev.kit prompt`.
-- If AI is disabled or Codex is missing, `dev.kit exec` prints the prompt and exits.
-- Context history is automatically included (repo-scoped).
-
-```mermaid
-flowchart TD
-  A["dev.kit exec"] --> B{"AI enabled?"}
-  B -->|"No"| C["Print prompt and exit"]
-  B -->|"Yes"| D{"Codex installed?"}
-  D -->|"No"| C
-  D -->|"Yes"| E["Include repo context history"]
-  E --> F["Generate prompt from templates"]
-  F --> G["Execute via Codex"]
-  G --> H["Output result"]
-```
-
-## What You Can Do (Core)
-
-```bash
-dev.kit prompt --request "Summarize repo structure"
-dev.kit exec "Summarize repo structure"
-dev.kit exec --print "Summarize repo structure"
-```
-
-Context controls:
-
-```bash
-dev.kit exec --reset "remember: 1234"
-dev.kit exec --no-context "one-off question"
-dev.kit context show
-```
-
-## With AI Integration (Empower)
-
-Apply repo skills to Codex:
+## Install
 
 ```bash
-dev.kit codex apply
-dev.kit ai skills
+curl -fsSL https://udx.dev/dev.kit/install.sh | bash
 ```
 
-Tips:
-
-- Streaming logs are off by default; pass `--stream` for full runner output.
-- Simple requests answer directly; complex requests route to workflow.
-
-## Docs
-
-Start here: `docs/README.md`
-
-Doc map (by topic):
-
-- CLI and execution model: `docs/cli/overview.md`, `docs/cli/execution/index.md`
-- AI integration: `docs/ai/README.md`
-- Concepts and contracts: `docs/concepts/index.md`, `docs/concepts/specs.md`
-- References and standards: `docs/reference/udx-reference-index.md`
+## Documentation
 
-## Repo Map (Core)
+- **Managed AI Skills**: `docs/ai/skills.md`
+- **Scenarios & Workflows**: `docs/scenarios/README.md`
+- **CLI Overview**: `docs/cli/overview.md`
+- **AI Orchestration**: `docs/ai/README.md`
 
-- `bin/` CLI entrypoints
-- `lib/` runtime library code
-- `src/` runtime source + templates
-- `config/` runtime configuration
-- `docs/` specs and contracts
-- `src/ai/` shared AI integration assets
-- `src/ai/data/` shared AI data (JSON)
-- `src/ai/integrations/` integration-specific schemas/templates (codex, claude, gemini)
-- `src/ai/data/prompts.json` iteration prompts
-- `src/mermaid/` mermaid templates
-- `src/docker/` docker assets
-- `scripts/` helpers
+---
+_UDX DevSecOps Team_

assets/dev-kit-diagram-generator-ux.mmd

@@ -0,0 +1,9 @@
+flowchart TD
+  A[User submits source] --> B[Validate input and apply defaults]
+  B --> C{Source usable?}
+  C -->|No| D[Return correction prompt]
+  C -->|Yes| E[Generate Mermaid diagram]
+  E --> F{Output mode}
+  F -->|chat| G[Return Mermaid in chat]
+  F -->|file export| H[Write files and attempt SVG export]
+  H --> I[Return paths or recovery hint]

assets/diagrams/adaptation-flow.mmd

@@ -0,0 +1,5 @@
+flowchart LR
+    Source[Canonical Source] --> Project[Adaptation / Projection]
+    Project --> ToolA[Tool A Format]
+    Project --> ToolB[Tool B Format]
+    Project --> Fallback[Fail-Open Fallback]

assets/diagrams/adaptation-flow.svg

@@ -0,0 +1,12 @@
+flowchart TD
+    User["User Intent / Drift"] --> Agent["AI Agent (Gemini/Antigravity)"]
+    Agent --> Skills["dev.kit skills (Grounding)"]
+    Skills --> Repo["Repository Truth"]
+    Repo --> Agent
+    Agent --> Iterate["Iterative Resolution Cycle"]
+    Iterate --> Result["Drift Resolved"]
+    
+    subgraph dev.kit Empowerment
+        Skills
+        Repo
+    end