@kienha/anti-chaotic 1.0.7 → 1.0.9

package/.agent/rules/tests.md

@@ -0,0 +1,55 @@
+---
+trigger: model_decision
+description: Always run tests to ensure no regressions when implementing new features or fixing bugs
+---
+
+# Testing and Regression Rule
+
+> [!IMPORTANT]
+> This rule is **MANDATORY** when implementing new features, fixing bugs, or performing major refactors. Ensuring system stability is a top priority.
+
+## Critical Rules (MUST Follow)
+
+1. **MUST** run existing tests before starting any work to establish a baseline.
+2. **MUST** run tests after completing changes to ensure no regressions were introduced.
+3. **MUST** add new tests for any new features implemented.
+4. **MUST** add reproduction tests for any bug fixes to ensure the bug does not return.
+5. **MUST** report test results (pass/fail) in the task summary and walkthrough.
+6. **MUST NOT** proceed to finalize a task if tests are failing, unless explicitly instructed by the user after explaining the failure and its impact.
+
+## Decision Flow
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ WHEN implementing a feature or fixing a bug:                │
+├─────────────────────────────────────────────────────────────┤
+│ 1. Run baseline tests.                                      │
+│    Are they passing?                                        │
+│    NO  → Notify user of existing failures before proceeding. │
+│    YES → Continue.                                          │
+├─────────────────────────────────────────────────────────────┤
+│ 2. Implement changes (Feature/Fix/Refactor).                │
+├─────────────────────────────────────────────────────────────┤
+│ 3. Add/Update tests for the new code.                       │
+├─────────────────────────────────────────────────────────────┤
+│ 4. Run ALL relevant tests.                                  │
+│    Are they passing?                                        │
+│    NO  → Analyze failures, fix code/tests, repeat step 4.   │
+│    YES → Continue.                                          │
+├─────────────────────────────────────────────────────────────┤
+│ 5. Document test results in Walkthrough/Task Summary.       │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Running Tests
+
+- Use `npm test` to run the test suite.
+- For specific tests, use `npm test -- <path_to_test_file>`.
+- If the project uses a different test runner (e.g., `pytest`, `jest`, `vitest`), adapt the command accordingly based on `package.json` or project documentation.
+
+## What to do on Failure
+
+1. **Analyze logs**: Look for the specific assertion failure or error message.
+2. **Determine Root Cause**: Is it a bug in the code, a bug in the test, or a change in requirements?
+3. **Fix and Re-run**: Apply the necessary fix and run the tests again.
+4. **Communicate**: If a failure is expected or cannot be fixed easily, notify the user with a detailed explanation.

package/.agent/skills/ai-engineer/SKILL.md

@@ -1,23 +1,28 @@
 ---
 name: ai-engineer
-description: AI Engineer role. Focuses on integrating AI models, building RAG pipelines, and optimizing prompts. Loads specific AI modality guides.
+description: Expert AI Engineer role (10+ Years Exp). Focuses on production-grade GenAI, Agentic Systems, Advanced RAG, and rigorous Evaluation.
 license: MIT
 metadata:
   role: AI Engineer
-  version: "1.0"
+  version: "2.0"
 ---
 
-# AI Engineer
+# Senior AI Engineer
 
-You build intelligence into the application.
+You are a Senior Staff AI Engineer with experience at top-tier tech companies (Google, OpenAI, Anthropic). You build robust, scalable, and intelligent systems. You do not just "call APIs"; you engineer reliability, observability, and performance into stochastic systems.
 
 ## Core Responsibilities
 
-1.  **Model Integration**: Connecting LLMs to Logic.
-2.  **Context Management**: RAG, Vector Search, Memory.
-3.  **Evaluation**: Testing AI quality.
+1.  **Agentic Systems & Architecture**: Designing multi-agent workflows, planning capabilities, and reliable tool-use patterns.
+2.  **Advanced RAG & Retrieval**: Implementing hybrid search, query expansion, re-ranking, and knowledge graphs.
+3.  **Evaluation & Reliability (Evals)**: Setting up rigorous evaluation pipelines (LLM-as-a-judge), regression testing, and guardrails.
+4.  **Model Integration & Optimization**: Function calling, structured outputs, prompt engineering, and choosing the right model for the task (latency vs. intelligence trade-offs).
+5.  **MLOps & Serving**: Observability, tracing, caching, and cost management.
 
 ## Dynamic Stack Loading
 
-- **LLMs & RAG**: [Read specific guide](references/llm.md)
-- **MLOps**: (Create `references/mlops.md` if needed)
+- **Agentic Patterns**: [Principles for reliable agents](references/agentic-patterns.md)
+- **Advanced RAG**: [Techniques for high-recall retrieval](references/rag-advanced.md)
+- **Evaluation Frameworks**: [Testing & Metrics](references/evaluation.md)
+- **Serving & Optimization**: [Performance & MLOps](references/serving-optimization.md)
+- **LLM Fundamentals**: [Prompting & SDKs](references/llm.md)

package/.agent/skills/ai-engineer/references/agentic-patterns.md

@@ -0,0 +1,47 @@
+# Agentic Patterns & Architectures
+
+Building agents is about engineering reliability into stochastic systems.
+
+## Core Patterns
+
+### 1. The ReAct Loop (Reason + Act)
+
+The fundamental loop of an agent:
+
+1.  **Thought**: Analyze the current state and goal.
+2.  **Act**: Decide on a tool to call.
+3.  **Obs**: Observe the output of the tool.
+4.  **Repeat**.
+
+### 2. Planning & Reflection
+
+- **Planning**: Break complex tasks into steps _before_ execution. (e.g., "First I will search for X, then I will calculate Y").
+- **Reflection**: After an output, ask the model "Does this answer the user's question? Is it accurate?". Use a separate "Critic" prompt.
+
+### 3. Memory Architectures
+
+- **Short-term**: Current context window (conversation history).
+- **Long-term**: Vector database (semantic search over past interactions).
+- **Procedural**: Storing successful "recipes" or tool sequences for future use.
+
+## Multi-Agent Architectures
+
+### 1. Orchestrator-Workers (Router)
+
+A central "Manager" LLM analyzes the request and delegates to specific "Worker" agents (e.g., Coder, Researcher, Reviewer).
+
+- **Pros**: Clear separation of concerns, easy to eval workers independently.
+- **Cons**: Latency (multiple hops).
+
+### 2. Autonomous Teams (CrewAI / AutoGen)
+
+Agents converse with each other to solve a problem.
+
+- **Role-Playing**: "You represent the User", "You are the QA Tester".
+- **Dynamic**: Can handle ambiguous tasks but harder to control.
+
+## Best Practices
+
+- **Deterministic Tools**: Tools should be as reliable as possible (APIs, Code execution).
+- **Human-in-the-Loop**: Always pause for confirmation before destructive actions (Write DB, Deploy).
+- **Fail Gracefully**: If a tool fails, the agent should catch the error and retry or ask for help, not crash.

package/.agent/skills/ai-engineer/references/evaluation.md

@@ -0,0 +1,42 @@
+# Evaluation & Reliability
+
+If you can't measure it, you can't improve it.
+
+## The Evaluation Hierarchy
+
+### 1. Unit Tests (Deterministic)
+
+- Does the output JSON parse?
+- Does the code compile?
+- Are forbidden words present?
+
+### 2. LLM-as-a-Judge (Semantic)
+
+Use a stronger model (GPT-4o) to evaluate the output of your application model.
+
+- **Frameworks**: Ragas, DeepEval, Promptfoo.
+- **Metrics**:
+  - **Faithfulness**: Is the answer derived _only_ from the retrieved context?
+  - **Answer Relevance**: Does the answer address the user's query?
+  - **Context Precision**: Was the relevant chunk ranked at the top?
+
+### 3. Human Review (Ground Truth)
+
+- Create a "Golden Dataset" of 50-100 Q&A pairs verified by experts.
+- Run regression tests against this dataset on every prompt change.
+
+## Techniques
+
+### Regression Testing
+
+Treat prompts like code.
+
+1. Change strictness in system prompt.
+2. Run `promptfoo eval` against 50 test cases.
+3. Compare pass rate (98% -> 92%? **Revert**).
+
+### Guardrails
+
+- **Input Rails**: PII detection, Jailbreak attempts.
+- **Output Rails**: Hallucination check, Tone check.
+- **Tools**: NeMo Guardrails, Llama Guard.

package/.agent/skills/ai-engineer/references/llm.md

@@ -1,13 +1,45 @@
-# Tech: LLMs & RAG
+# Tech: LLMs & Integration Patterns
 
-## Stack
+## Stack Selection
 
-- **SDK**: Vercel AI SDK or LangChain.
-- **Model**: GPT-4o, Claude 3.5 Sonnet.
-- **Vector DB**: Supabase `pgvector`.
+- **Inference Engine**:
+  - **Complex Reasoning**: GPT-4o, Claude 3.5 Sonnet.
+  - **Fast/Cheap**: Gemini Flash, Haiku, Llama 3 (Groq/Together).
+- **Orchestration**:
+  - **Production**: Vercel AI SDK (Type-safe, streaming first).
+  - **Prototyping**: LangChain (Use with caution in production due to abstraction overhead).
+- **Gateway**: Portkey or Helicone for observability and fallback.
 
-## Best Practices
+## Advanced Patterns
 
-- **Streaming**: Always stream responses using `AIStream`.
-- **Prompts**: Version control your system prompts.
-- **Embeddings**: Normalize text before embedding.
+### 1. Structured Outputs
+
+Stop parsing regex. Use native JSON mode or tool definitions to enforce strict schemas (Zod).
+
+```typescript
+// Example using Vercel AI SDK
+const { object } = await generateObject({
+  model: openai("gpt-4o"),
+  schema: z.object({
+    sentiment: z.enum(["positive", "negative"]),
+    reasoning: z.string(),
+  }),
+  prompt: "Analyze this customer feedback...",
+});
+```
+
+### 2. Reliable Prompt Engineering
+
+- **Chain of Thought (CoT)**: Force the model to "think" before answering. `Let's think step by step.`
+- **Few-Shot Prompting**: Provide 3-5 high-quality examples of input -> output.
+- **System Prompts**: strict role definition, output constraints, and "tone of voice" instructions. Version control these!
+
+### 3. Streaming & UI Integration
+
+- **Optimistic UI**: Show skeleton loaders or predicted text while waiting.
+- **Generative UI**: Stream React components directly from the LLM (Vercel AI SDK RSC).
+
+### 4. Cost Management
+
+- **Token Counting**: Always estimate tokens before sending requests.
+- **Caching**: Cache identical prompts at the edge/gateway layer.

package/.agent/skills/ai-engineer/references/rag-advanced.md

@@ -0,0 +1,42 @@
+# Advanced RAG Patterns
+
+Move beyond naive "chunk & retrieve".
+
+## Retrieval Optimization
+
+### 1. Hybrid Search (Keyword + Semantic)
+
+Dense vectors (semantic) miss exact matches (IDs, acronyms). Sparse vectors (BM25/Splade) miss intent.
+**Solution**: Combine both with Reciprocal Rank Fusion (RRF).
+
+- **Stack**: Pinecone (Hybrid), Weaviate, Supabase (pgvector + pg_search).
+
+### 2. Re-Ranking (Cross-Encoders)
+
+Retrieving 50 docs with a bi-encoder is fast but inaccurate.
+**Solution**: Retrieve 50 -> Re-rank top 5 with a Cross-Encoder (Cohere Rerank, bge-reranker). This dramatically improves precision.
+
+### 3. Query Transformations
+
+Users write bad queries.
+
+- **Expansion**: Generate synonyms or related questions.
+- **Decomposition**: Break complex questions into sub-queries.
+- **HyDE (Hypothetical Document Embeddings)**: Generate a fake answer, embed _that_, and search for similar real chunks.
+
+### 4. Contextual Compression
+
+Don't shove 10 full documents into the context.
+
+- Summarize retrieved docs relative to the query before passing to the LLM.
+
+## Knowledge Graphs (GraphRAG)
+
+For questions requiring global reasoning ("How do the themes in book A relate to book B?").
+
+- Extract entities and relationships -> Store in Graph DB (Neo4j) -> Traverse during retrieval.
+
+## Indexing Strategy
+
+- **Parent-Child Chunking**: Retrieve small chunks (better matching), but return the parent large chunk (better context).
+- **Multi-Vector Retrieval**: Embed summaries for search, but return full raw text for generation.

package/.agent/skills/ai-engineer/references/serving-optimization.md

@@ -0,0 +1,39 @@
+# Serving & Optimization (MLOps)
+
+Moving from "it works on my laptop" to "production scale".
+
+## Observability & Tracing
+
+You cannot debug a stochastic system with `console.log`.
+
+- **Tracing**: Visualize the entire chain (User -> RAG -> Tool -> LLM).
+- **Tools**: LangSmith, Arize Phoenix, Helicone.
+- **Key Metrics**:
+  - **Latency**: Time to First Token (TTFT), Total Latency.
+  - **Cost**: Cost per request, Token usage.
+  - **Quality**: User feedback (Thumbs up/down).
+
+## Optimization Techniques
+
+### 1. Caching (The Semantic Cache)
+
+Don't pay for the same answer twice.
+
+- **Exact Match**: Redis check on prompt string.
+- **Semantic Match**: Check vector distance of prompt embeddings (e.g., "How do I reset password" ~= "modify password steps").
+
+### 2. Latency Reduction
+
+- **Streaming**: Non-negotiable for UX.
+- **Speculative Decoding**: Use a small model to draft, large model to verify.
+- **Quantization**: Run int8/int4 models if self-hosting (vLLM).
+
+### 3. Cost Control
+
+- **Model Cascading**: Try a cheap model (Flash/Haiku) first. If confidence < X, retry with GPT-4.
+- **Fine-tuning**: Fine-tune a small model (Llama 3 8B) on your specific task to match GPT-4 performance at 1/10th the cost.
+
+## Deployment Stack
+
+- **Managed**: Vercel, AWS Bedrock.
+- **Self-Hosted**: vLLM, TGI (Text Generation Inference), Ray Serve.

package/.agent/skills/blockchain-engineer/SKILL.md

@@ -1,23 +1,53 @@
 ---
 name: blockchain-engineer
-description: Blockchain Engineer role. Focuses on smart contracts, web3 integration, and decentralized protocols. Loads specific chain guides.
+description: Expert Blockchain Engineer (10+ Years). Master of Protocol Architecture, Advanced Smart Contract Development, and Security.
 license: MIT
 metadata:
   role: Blockchain Engineer
-  version: "1.0"
+  version: "2.0"
 ---
 
 # Blockchain Engineer
 
-You build the decentralized layer.
+You are an expert Blockchain Engineer with 10+ years of experience at top tech firms. You build the decentralized layer with a focus on security, scalability, and economic robustness.
 
 ## Core Responsibilities
 
-1.  **Smart Contracts**: Immutable code on chain.
-2.  **Web3**: Connecting the frontend to the wallet.
-3.  **Security**: Protecting value.
+1.  **Protocol Architecture**: Design tokenomics, governance structures, and ensuring incentive alignment across the network.
+2.  **Smart Contract Mastery**: End-to-end lifecycle management of smart contracts on EVM (Solidity/Yul) and SVM (Rust/Anchor).
+3.  **Advanced Security**: Protect value through formal verification, fuzzing, and rigorous audit preparation.
+4.  **Scaling Solutions**: Architect solutions using L2s, Optimistic/ZK Rollups, and AppChains.
+
+## Technical Standards & Best Practices
+
+### Development Lifecycle
+
+- **Environment**: Master usage of Hardhat and Foundry (Forge/Cast/Anvil) for EVM; Anchor for Solana.
+- **Testing**: Beyond unit tests—implement invariant testing, fuzzing (Echo/Medusa), and fork testing.
+- **CI/CD**: Automated pipelines for linting, testing, and deterministic deployments.
+
+### Optimization & Quality
+
+- **Gas Golfing**: Optimize for gas efficiency using Yul/Assembly, storage layout packing, and calldata mastery.
+- **Code Quality**: Enforce NatSpec documentation, strict linting (Solhint/Clippy), and clean code patterns.
+
+### Deployment & Ops
+
+- **Patterns**: Use deterministic deployment (Create2) and manage upgrades via standard proxies (Transparent, UUPS, Diamond/EIP-2535).
+- **Security**: Manage keys via Multi-sig (Gnosis Safe) and Timelocks. Automate ops with scripting.
+
+## Architecture Patterns
+
+- **Upgradeability**: Future-proof contracts using Transparent, UUPS, or Diamond patterns.
+- **Interoperability**: Connect chains using Bridges, Atomic Swaps, and CCIP.
+- **Data Integration**: Index data with Subgraphs (The Graph) and secure external feeds via Oracles (Chainlink, Pyth).
 
 ## Dynamic Stack Loading
 
-- **EVM (Ethereum/Polygon)**: [Read specific guide](references/evm.md)
+- **EVM (Ethereum/Polygon/Arbitrum)**:
+  - [EVM Overview](references/evm.md)
+  - [Solidity Development](references/solidity.md)
+  - [Deployment & Ops](references/deployment.md)
+  - [Mechanisms & Internals](references/mechanisms.md)
 - **Solana**: (Create `references/solana.md` if needed)
+- **ZK & Privacy**: Focus on ZK-SNARKs/STARKs for privacy and scaling.

package/.agent/skills/blockchain-engineer/references/deployment.md

@@ -0,0 +1,28 @@
+# Tech: Smart Contract Deployment
+
+## Strategies
+
+- **Immutable**: Simple deployment. Code cannot be changed. High trust, low flexibility.
+- **Upgradeable Proxies**:
+  - **Transparent Upgradeable Proxy**: Admin logic separated. High gas overhead.
+  - **UUPS (Universal Upgradeable Proxy Standard)**: Upgrade logic in implementation. Cheaper gas.
+  - **Diamond (EIP-2535)**: Modular system, unlimited size, complex management.
+
+## Automation & Tooling
+
+- **Hardhat Ignition**: Declarative deployment modules. Handles dependency management and recovery.
+- **Foundry Script**: Solidity-based scripting (`forge script`). Fast and integrated with Forge tests.
+- **Deterministic Deployment**:
+  - Use `CREATE2` to deploy to the same address across multiple chains.
+  - Tool: `Nick's Method` factory / `Arachnid/deterministic-deployment-proxy`.
+
+## Verification
+
+- **Etherscan/Block Explorers**: ALWAYs verify source code.
+- **Sourcify**: Decentralized verification based on metadata hash.
+
+## Operational Safety
+
+- **Multisig (Gnosis Safe)**: Never deploy or manage admin keys with a single EOA (Externally Owned Account).
+- **Timelocks**: Enforce a delay (e.g., 48h) between proposing and executing sensitive admin actions.
+- **Access Control Rotation**: Plan for key rotation procedures.

package/.agent/skills/blockchain-engineer/references/mechanisms.md

@@ -0,0 +1,32 @@
+# Tech: Blockchain Mechanisms & Internals
+
+## Consensus
+
+- **PoS (Proof of Stake)**: Validators stake tokens to propose/attest blocks. (Ethereum, Solana).
+- **PoW (Proof of Work)**: Miners solve cryptographic puzzles. (Bitcoin).
+- **Finality**:
+  - **Probabilistic**: Bitcoin (wait ~6 blocks).
+  - **Deterministic**: Ethereum (after finalized epoch), Tendermint (instant).
+
+## State Management
+
+- **Account Model (Ethereum/Solana)**: Global state tracks account balances and nonce.
+- **UTXO (Bitcoin/Cardano)**: Unspent Transaction Outputs. State is the set of all unspent outputs.
+- **Data Structures**:
+  - **Merkle Patricia Trie (Ethereum)**: Storage, State, Transactions, Receipts.
+  - **Verkle Trees**: Future upgrade for stateless clients.
+
+## Transaction Lifecycle
+
+1.  **Creation**: User signs tx with private key.
+2.  **Propagation**: Gossip protocol sends tx to Mempool.
+3.  **Ordering**: Block Builders/Proposers select and order txs (MEV opportunity here).
+4.  **Execution**: EVM executes logic, updates state trie.
+5.  **Finalization**: Block is added to chain and finalized by consensus.
+
+## EVM Internals
+
+- **Stack**: 1024 depth, 256-bit words. Most gas efficient.
+- **Memory**: Linear, byte-addressable. Expanded in 32-byte chunks.
+- **Storage**: Key-value store (256-bit -> 256-bit). Most expensive. SLOAD/SSTORE.
+- **Logs**: Bloom filters used for event indexing. Cheaper than storage but not accessible by contracts.

package/.agent/skills/blockchain-engineer/references/solidity.md

@@ -0,0 +1,32 @@
+# Tech: Solidity Development
+
+## Best Practices
+
+- **Layout**: Follow [Solidty Style Guide](https://docs.soliditylang.org/en/latest/style-guide.html).
+  - Order: Pragma -> Import -> Interfaces -> Libraries -> Contracts.
+  - Inside Contract: Type declarations -> State vars -> Events -> Modifiers -> Functions.
+- **Naming**: `camelCase` for variables/functions, `CapWords` for contracts/structs/events, `UPPER_CASE` for constants.
+- **Error Handling**: Use custom errors (`error InsufficientFunds()`) instead of strings for gas efficiency.
+
+## Advanced Concepts
+
+- **Storage Layout**: Understand slot packing to minimize storage costs.
+  - Pack `uint128`, `address`, `bool` into single 256-bit slots where possible.
+- **Delegatecall**: Execution in the context of the caller (crucial for proxies).
+- **Assembly (Yul)**: Use `assembly { ... }` for low-level memory manipulation and gas optimization.
+- **EIP Standards**:
+  - **ERC-20/721/1155**: Token standards.
+  - **ERC-4626**: Tokenized Vaults.
+  - **ERC-2535**: Diamond Standard.
+
+## Security Patterns
+
+- **Checks-Effects-Interactions**: Update state _before_ making external calls to prevent reentrancy.
+- **Pull over Push**: Let users withdraw funds rather than pushing them to arrays of addresses (avoids DoS).
+- **Access Control**: Use `OwnableTwoStep` or `AccessControl` (RBAC).
+
+## Gas Optimization
+
+- **Calldata**: Use `calldata` instead of `memory` for read-only function arguments.
+- **Unchecked Math**: Use `unchecked { ... }` when overflow/underflow is impossible (Solidity 0.8+ default checks cost gas).
+- **Constants/Immutable**: Use `constant` for literal values and `immutable` for constructor-set values.

package/.agent/workflows/break-tasks.md

@@ -0,0 +1,82 @@
+---
+description: Orchestrates breaking down requirements into actionable tasks for implementation.
+---
+
+# Break Tasks Workflow
+
+> [!IMPORTANT]
+> **MANDATORY**: Follow `.agent/rules/documents.md` for all task-related documentation.
+
+---
+
+## MCP Usage Guidelines
+
+| MCP Tool                                     | When to Use                                               |
+| :------------------------------------------- | :-------------------------------------------------------- |
+| `mcp_sequential-thinking_sequentialthinking` | **REQUIRED** to break down requirements into atomic tasks |
+| `mcp_context7_query-docs`                    | To check best practices for specific technologies         |
+
+---
+
+## Step 1: Identify Source Document
+
+1. Locate the source document (PRD, User Story, Feature Spec, or SDD).
+2. If multiple versions exist, ask the user for clarification.
+3. Relevant folders to check:
+   - `docs/020-Requirements/`
+   - `docs/022-User-Stories/`
+   - `docs/030-Specs/`
+
+---
+
+## Step 2: Analyze Requirements
+
+// turbo
+
+1. **Invoke `[business-analysis]` skill** to extract key features and acceptance criteria.
+2. Use `sequential-thinking` to:
+   - Identify technical dependencies.
+   - Separate backend, frontend, and QA requirements.
+   - Spot ambiguous or missing details.
+3. List any clarifying questions for the user.
+4. **WAIT** for user clarification if needed.
+
+---
+
+## Step 3: Atomic Task Breakdown
+
+// turbo
+
+> 💡 **MCP**: **MUST** use `sequential-thinking` here to ensure tasks are atomic and manageable.
+
+1. **Invoke `[lead-architect]` skill** to create a structured task list.
+2. Group tasks by component or phase (e.g., Database, API, Logic, UI, Testing).
+3. For each task, include:
+   - Goal/Description.
+   - Acceptance Criteria.
+   - Estimated complexity (if applicable).
+4. Create a `task-breakdown.md` artifact representing the proposed sequence.
+
+---
+
+## Step 4: Finalize Task Documentation
+
+// turbo
+
+1. After user approves the `task-breakdown.md` artifact:
+2. Update the `task.md` of the current session or create a new task file in `docs/050-Tasks/`.
+3. If creating a new file, follow standard naming: `docs/050-Tasks/Task-{FeatureName}.md`.
+4. Update `docs/050-Tasks/Tasks-MOC.md`.
+5. Present the finalized task list to the user.
+
+---
+
+## Quick Reference
+
+| Role               | Skill                | Responsibility                          |
+| :----------------- | :------------------- | :-------------------------------------- |
+| Product Manager    | `product-manager`    | Requirement validation & prioritization |
+| Lead Architect     | `lead-architect`     | Technical breakdown & dependencies      |
+| Developer          | `backend-developer`  | Backend/API specific tasks              |
+| Frontend Developer | `frontend-developer` | UI/UX specific tasks                    |
+| QA Tester          | `qa-tester`          | Verification & Edge case tasks          |

package/.agent/workflows/debug.md

@@ -0,0 +1,71 @@
+---
+description: Scientific debugging workflow: Hypothesize, Instrument, Reproduce, Analyze, Fix.
+---
+
+# Scientific Debug & Fix Workflow
+
+> [!IMPORTANT]
+> **GOAL**: Follow a scientific process to identify root causes with EVIDENCE before applying fixes.
+> **Best for**: Hard-to-reproduce bugs, race conditions, performance issues, and regressions.
+
+---
+
+## Step 1: Hypothesis Generation
+
+1. **Analyze the Issue**: Review the bug report and available context.
+2. **Generate Hypotheses**: Brainstorm multiple potential causes (e.g., "Race condition in data fetching", "Incorrect state update logic", "Edge case in input validation").
+3. **Select Top Candidates**: Prioritize the most likely hypotheses to investigate first.
+
+---
+
+## Step 2: Instrumentation
+
+1. **Plan Logging**: Decide WHERE key information is missing to validate your hypotheses.
+2. **Add Logging**: Instrument the code with targetted `console.log`, specific logger calls, or performance markers.
+   - _Goal_: Capture runtime state, variable values, and execution flow relevant to the hypotheses.
+   - _Tip_: Add unique prefixes to logs (e.g., `[DEBUG-HYPOTHESIS-1]`) for easy filtering.
+
+---
+
+## Step 3: Reproduction & Data Collection
+
+1. **Execution**: Run the application or test case to reproduce the bug.
+   - If a reproduction script doesn't exist, create one now if possible.
+2. **Collect Data**: Capture the output from your instrumentation.
+
+---
+
+## Step 4: Analysis & Root Cause
+
+1. **Analyze Evidence**: Look at the collected logs/data.
+   - Does the data confirm a hypothesis?
+   - Does it rule one out?
+2. **Pinpoint Root Cause**: Identify exactly _why_ the bug is happening based on the evidence.
+3. **Iterate (if needed)**: If inconclusive, return to Step 1 or 2 with new knowledge.
+
+---
+
+## Step 5: Targeted Implementation
+
+1. **Apply Fix**: Implement a targeted fix based _only_ on the confirmed root cause. Avoid "shotgun debugging" (changing things randomly).
+2. **Cleanup**: Remove the temporary debugging instrumentation.
+
+---
+
+## Step 6: Verification
+
+// turbo
+
+1. **Run Reproduction Test**: Verify that the bug is gone.
+2. **Run Regression Tests**: Run related unit tests to ensure no side effects.
+3. **Lint & Type Check**: Ensure code quality standards are met.
+
+---
+
+## Step 7: Finalize
+
+1. **Draft Commit**: Create a concise commit message (e.g., `fix(module): description of fix`).
+2. **Report**: Summarize the process:
+   - What was the hypothesis?
+   - What evidence confirmed it?
+   - How was it fixed?

package/.agent/workflows/development.md

@@ -0,0 +1,54 @@
+---
+description: General coding workflow for implementing changes, bug fixes, or minor features.
+---
+
+# Development Workflow
+
+> [!IMPORTANT]
+> **MANDATORY**: Always read `.agent/rules/documents.md` before creating or modifying any documentation related to development.
+
+---
+
+## Step 1: Analyze & Plan
+
+// turbo
+
+1. Understand the requirement or bug report.
+2. **MUST** use `mcp_sequential-thinking_sequentialthinking` to:
+   - Analyze the existing code structure.
+   - Design the solution.
+   - Identify potential edge cases and impacts.
+3. If the task is complex, create an `implementation_plan.md` artifact.
+4. **WAIT** for user confirmation if the plan involves major architectural changes.
+
+---
+
+## Step 2: Execute Code Changes
+
+// turbo
+
+1. Implement the planned changes iteratively.
+2. **Backend**: Update models, logic, and APIs as needed.
+3. **Frontend**: Update UI components and state management.
+4. Ensure code follows project standards and linting rules.
+
+---
+
+## Step 3: Verify & Test
+
+// turbo
+
+1. Run existing tests to ensure no regressions.
+2. Add new unit or integration tests for the changes.
+3. Perform manual verification (e.g., using the browser tool for UI changes).
+4. **MUST** document proof of work in a `walkthrough.md` artifact if the change is significant.
+
+---
+
+## Step 4: Finalize
+
+// turbo
+
+1. Update related documentation (MOCs, API specs, etc.).
+2. Clean up any temporary files or comments.
+3. Present a summary of changes and verification results.

package/.agent/workflows/documentation.md

@@ -37,24 +37,81 @@ description: Generate comprehensive documentation (Architecture, API, Specs) fro
 
 1. **Invoke `[lead-architect]` skill** to analyze codebase structure
 2. Identify: tech stack, entry points, API routes, DB schemas
-3. **WAIT** for user to confirm understanding
+3. **Clarify & Confirm**:
+   - **CRITICAL**: If the codebase structure is unclear or ambiguous, **ASK** the user for clarification.
+   - Summarize findings and **WAIT** for user to confirm understanding
 
 ---
 
-## Step A2: Legacy Docs Generation (Architecture, API, Schema)
+## Step A2: Technical Documentation (Architecture, API, Schema)
 
 // turbo
 
 1. **Invoke `[lead-architect]` skill** to create:
    - System Context (C4 Context Diagram)
    - Component View (C4 Component Diagram)
+   - **Sequence Diagrams** for critical business flows
 2. **Invoke `[backend-developer]` skill** to:
-   - Document API endpoints
+   - Document API endpoints (OpenAPI/Swagger styled)
    - Generate Entity Relationship Diagram (ERD)
+   - Document key algorithms or data processing pipelines
 3. Save to `docs/030-Specs/` and `docs/030-Specs/Architecture/`
 
 ---
 
+## Step A3: Functional Documentation (Reverse Engineering)
+
+// turbo
+
+**Objective**: Derive business logic and requirements from the existing implementation.
+
+1. **Invoke `[business-analysis]` skill** to:
+   - Analyze the codebase (controllers, services, frontend views) to understand user flows.
+   - **Reverse Engineer** the PRD/Functional Specs:
+     - Identify high-level Epics.
+     - Document implied User Stories & Acceptance Criteria.
+     - Create Use Case definitions for main features.
+2. **Draft Artifacts**:
+   - `docs/020-Requirements/Reverse-Engineered-Specs.md`
+   - `docs/022-User-Stories/Implied-User-Stories.md`
+3. **Review**: Present these findings to the user to confirm they align with business reality.
+
+---
+
+## Step A4: Operational & Quality Documentation
+
+// turbo
+
+**Objective**: Document how to run, test, and deploy the system.
+
+1. **Invoke `[devops-engineer]` skill** to create:
+   - **Infrastructure**: Document cloud resources, Docker setup (`docs/030-Specs/Architecture/Infrastructure.md`).
+   - **Deployment**: CI/CD pipelines and release process (`docs/030-Specs/Architecture/Deployment.md`).
+   - **Configuration**: Environment variables reference (`docs/030-Specs/Configuration.md`).
+2. **Invoke `[qa-tester]` skill** to create:
+   - **Test Strategy**: Overview of testing tools and approach (`docs/035-QA/Test-Plans/Strategy.md`).
+   - **Coverage Report**: Summary of current test coverage and gaps (`docs/035-QA/Reports/Coverage.md`).
+3. **Invoke `[backend-developer]` skill** to create/update:
+   - **Onboarding**: `docs/060-Manuals/Admin-Guide/Setup-Guide.md` (Prerequisites, installation, running locally).
+   - **Scripts**: Document usage of `package.json` scripts (`docs/060-Manuals/Admin-Guide/Scripts.md`).
+
+---
+
+## Step A5: Project Planning & Strategy
+
+// turbo
+
+**Objective**: Establish high-level strategy and roadmap based on current state.
+
+1. **Invoke `[product-manager]` skill** to:
+   - **Analyze Maturity**: Assess current feature set against typical market standards.
+   - **Reverse Engineer Roadmap**: Draft `docs/010-Planning/Roadmap.md` based on implemented vs. missing features.
+   - **Define Objectives**: Draft `docs/010-Planning/OKRs.md` (Objectives and Key Results) aligned with the project's apparent direction.
+   - **Status Report**: Create a snapshot of current progress (`docs/010-Planning/Sprints/Current-Status.md`).
+2. **Review**: Present these strategic documents to the user for alignment.
+
+---
+
 # MODE B: From Requirements
 
 **Prerequisite**: Existing PRD (from `/brainstorm`).
@@ -68,13 +125,14 @@ description: Generate comprehensive documentation (Architecture, API, Specs) fro
 > - **MUST** use `sequential-thinking` for architectural decisions
 > - Use `context7` with `/vercel/next.js`, `/supabase/supabase` for tech stack research
 
-1. **Invoke `[lead-architect]` skill** to draft:
+1. **Analyze Requirements**: Review the PRD/Roadmap. If there are ambiguities, **ASK** the user to clarify.
+2. **Invoke `[lead-architect]` skill** to draft:
    - High-level system architecture
    - Technology stack decisions
    - Component diagram
    - Data flow overview
-2. Create `draft-sdd.md` artifact
-3. After approval → Save to `docs/030-Specs/Architecture/SDD-{ProjectName}.md`
+3. Create `draft-sdd.md` artifact
+4. After approval → Save to `docs/030-Specs/Architecture/SDD-{ProjectName}.md`
 
 ---
 
@@ -85,6 +143,7 @@ description: Generate comprehensive documentation (Architecture, API, Specs) fro
 1. **Invoke `[business-analysis]` skill** to:
    - Break PRD features into Epics (`docs/022-User-Stories/Epics/`)
    - Define Use Cases with Mermaid diagrams (`docs/020-Requirements/Use-Cases/`)
+   - **Note**: If requirements are vague, ask for clarification.
 2. Create artifacts for review before saving
 
 ---

package/.agent/workflows/gen-tests.md

@@ -0,0 +1,58 @@
+---
+description: Generate unit, E2E, security, and performance tests using the qa-tester skill.
+---
+
+# Generate Tests Workflow
+
+> [!IMPORTANT]
+> **MANDATORY**: Apply `.agent/rules/documents.md` for all document creation and directory structure. All QA documents MUST be stored under `docs/035-QA/`.
+
+---
+
+## Step 1: Discovery & Strategy
+
+// turbo
+
+1. **Invoke `[qa-tester]` skill** to analyze the `docs/` folder and current codebase structure.
+2. Ask the user which type of tests they want to generate:
+   - **Unit Tests**: For specific functions or utilities (e.g., `tests/unit/`).
+   - **E2E Tests**: For user flows (e.g., `tests/e2e/`).
+   - **Security Tests**: For vulnerability assessments.
+   - **Performance Tests**: For load and responsiveness checks.
+3. Identify the specific files or features that need testing based on user input.
+
+---
+
+## Step 2: Test Plan & Case Generation
+
+// turbo
+
+1. **Invoke `[qa-tester]` skill** to create/update the Test Plan and Test Cases:
+   - For **Unit Tests**: Identify edge cases, boundary conditions, and happy paths.
+   - For **E2E Tests**: valid/invalid user flows.
+   - For **Security**: potential injection points, auth flaws.
+2. Generate the test documentation in `docs/035-QA/Test-Cases/` following the naming convention `TC-{Feature}-{NNN}.md`.
+3. Create a `draft-test-docs.md` artifact with the proposed test cases for review.
+
+---
+
+## Step 3: Test Code Generation
+
+1. **Wait** for user approval of the test cases.
+2. **Invoke `[qa-tester]` skill** to generate the actual test code.
+   - Use the project's existing testing framework (e.g., Jest, Playwright, Vitest).
+   - Ensure mocks and stubs are correctly implemented for unit tests.
+   - Ensure selectors and interaction steps are robust for E2E tests.
+3. Save the generated test code to the appropriate directories (e.g., `tests/unit/`, `tests/e2e/`).
+
+---
+
+## Step 4: Verification & Reporting
+
+1. Run the generated tests using the project's test runner.
+2. If tests fail:
+   - Analyze the failure.
+   - **Invoke `[qa-tester]` skill** to fix the test code or report the bug if it's a real issue.
+3. **Mandatory**:
+   - Update `docs/035-QA/QA-MOC.md`.
+   - Update `docs/000-Index.md` if needed.

package/.agent/workflows/qa.md

@@ -0,0 +1,59 @@
+---
+description: Create comprehensive test case documents and test plans based on project requirements.
+---
+
+# QA Workflow
+
+> [!IMPORTANT]
+> **MANDATORY**: Apply `.agent/rules/documents.md` for all document creation and directory structure. All QA documents MUST be stored under `docs/035-QA/`.
+
+---
+
+## MCP Usage Guidelines
+
+| MCP Tool                                     | When to Use                                      |
+| :------------------------------------------- | :----------------------------------------------- |
+| `mcp_sequential-thinking_sequentialthinking` | Analyze complex application logic and edge cases |
+| `mcp_context7_query-docs`                    | Research testing frameworks or best practices    |
+
+---
+
+## Step 1: Requirement Discovery
+
+// turbo
+
+1. **Invoke `[qa-tester]` skill** to analyze the `docs/` folder.
+2. Identify features, constraints, and business logic that require testing.
+3. Map out:
+   - Happy Paths (Golden Flows)
+   - Negative Paths (Error handling)
+   - Boundary Cases
+   - Security/Performance considerations
+4. **WAIT** for user to confirm the list of scenarios to be documented.
+
+---
+
+## Step 2: Draft Test Documentation
+
+// turbo
+
+1. **Invoke `[qa-tester]` skill** to create:
+   - **Test Plan**: High-level strategy for the current release/feature (`docs/035-QA/Test-Plans/`).
+   - **Test Cases**: Detailed step-by-step cases (`docs/035-QA/Test-Cases/`).
+2. Follow the standard mapping in `.agent/rules/documents.md`:
+   - Test Plan naming: `MTP-{Name}.md`
+   - Test Case naming: `TC-{Feature}-{NNN}.md`
+3. Create a `draft-qa-docs.md` artifact for review.
+
+---
+
+## Step 3: Finalize and Organize
+
+// turbo
+
+1. After approval, save all files to their respective folders in `docs/035-QA/`.
+2. **Mandatory**:
+   - Update `docs/035-QA/QA-MOC.md`.
+   - Update `docs/000-Index.md` if needed.
+   - Ensure all frontmatter (id, type, status, created) is correctly populated according to `.agent/rules/documents.md`.
+3. Present summary of created tests.

package/README.md

@@ -25,7 +25,7 @@ _We encourage teams to customize these skills and define their own rules & workf
 ### 📦 Components
 
 - 🧠 **12+ Multi-domain AI Skills** - From Product Manager, Business Analyst to Lead Architect.
-- 🔄 **6 Automated Workflows** - Pre-defined, reusable work processes.
+- 🔄 **11 Automated Workflows** - Pre-defined, reusable work processes.
 - 📜 **Rules Engine** - A rule system that ensures AI Agents follow project standards.
 - 📚 **References Library** - Documentation references for various technologies.
 
@@ -139,14 +139,19 @@ Read and execute the workflow at .agent/workflows/brainstorm.md
 
 ## 🔄 Automated Workflows
 
-| Workflow                 | Description                                                                                                | Use Case                                                            |
-| :----------------------- | :--------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------ |
-| **`/bootstrap`**         | Sets up project structure, installs dependencies, and configures environment based on architectural specs. | Start of Implementation Phase.                                      |
-| **`/brainstorm`**        | Analyze ideas with the user and create preliminary high-level documents (Roadmap, PRD).                    | Start of a new project or feature when you only have a rough idea.  |
-| **`/custom-behavior`**   | Safely customize Agent rules and workflows with impact analysis and user confirmation.                     | As needed to adjust Agent behavior or fix recurring mistakes.       |
-| **`/documentation`**     | Generate comprehensive documentation (Architecture, API, Specs) from either Codebase or Requirements.      | Onboarding to a legacy project OR creating detailed specs from PRD. |
-| **`/implement-feature`** | Orchestrates feature implementation from specification to deployment.                                      | After design and specs are ready, for actual coding and deployment. |
-| **`/ui-ux-design`**      | Transform requirements into comprehensive UI/UX design deliverables.                                       | After requirements are finalized, before coding.                    |
+| Workflow                 | Description                                                                                                | Use Case                                                           |
+| :----------------------- | :--------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------- |
+| **`/bootstrap`**         | Sets up project structure, installs dependencies, and configures environment based on architectural specs. | Start of Implementation Phase.                                     |
+| **`/brainstorm`**        | Analyze ideas with the user and create preliminary high-level documents (Roadmap, PRD).                    | Start of a new project or feature when you only have a rough idea. |
+| **`/break-tasks`**       | Orchestrates breaking down requirements into actionable tasks for implementation.                          | When you have a PRD and need a task list.                          |
+| **`/custom-behavior`**   | Safely customize Agent rules and workflows with impact analysis and user confirmation.                     | Adjust Agent behavior or fix recurring mistakes.                   |
+| **`/debug`**             | Scientific debugging workflow: Hypothesize, Instrument, Reproduce, Analyze, Fix.                           | When facing complex bugs that need systematic analysis.            |
+| **`/development`**       | General coding workflow for implementing changes, bug fixes, or minor features.                            | Day-to-day coding tasks.                                           |
+| **`/documentation`**     | Generate comprehensive documentation (Architecture, API, Specs) from either Codebase or Requirements.      | Onboarding or creating detailed specs.                             |
+| **`/gen-tests`**         | Generate unit, E2E, security, and performance tests using the qa-tester skill.                             | Improving test coverage for new or existing code.                  |
+| **`/implement-feature`** | Orchestrates feature implementation from specification to deployment.                                      | End-to-end feature development.                                    |
+| **`/qa`**                | Create comprehensive test case documents and test plans based on project requirements.                     | Planning testing strategy for a feature.                           |
+| **`/ui-ux-design`**      | Transform requirements into comprehensive UI/UX design deliverables.                                       | After requirements are finalized, before coding.                   |
 
 ---
 

package/bin/anti-chaotic.js

@@ -4,11 +4,39 @@ const { program } = require("commander");
 const fs = require("fs-extra");
 const path = require("path");
 const chalk = require("chalk");
+const crypto = require("crypto");
+const os = require("os");
 
 program.version("0.0.1").description("Anti-Chaotic Agent Kit CLI");
 
 const REPO_URI = "kienhaminh/anti-chaotic/.agent";
 
+/**
+ * Calculates SHA-256 hash of a file
+ */
+async function getFileHash(filePath) {
+  const buffer = await fs.readFile(filePath);
+  return crypto.createHash("sha256").update(buffer).digest("hex");
+}
+
+/**
+ * Recursively gets all files in a directory
+ */
+async function getAllFiles(dirPath, baseDir = dirPath) {
+  let results = [];
+  const list = await fs.readdir(dirPath, { withFileTypes: true });
+
+  for (const item of list) {
+    const fullPath = path.join(dirPath, item.name);
+    if (item.isDirectory()) {
+      results = results.concat(await getAllFiles(fullPath, baseDir));
+    } else {
+      results.push(path.relative(baseDir, fullPath));
+    }
+  }
+  return results;
+}
+
 program
   .command("init")
   .description("Initialize the Anti-Chaotic Agent Kit (download from GitHub)")
@@ -26,22 +54,6 @@ program
         force: true,
       });
 
-      // Cleanup deprecated files
-      const deprecatedFiles = [
-        "rules/documentation.md",
-        "workflows/docs-from-codebase.md",
-        "workflows/requirement-analysis.md",
-        "workflows/setup-codebase.md",
-      ];
-
-      for (const file of deprecatedFiles) {
-        const filePath = path.join(targetAgentDir, file);
-        if (await fs.pathExists(filePath)) {
-          await fs.remove(filePath);
-          console.log(chalk.dim(`  Removed legacy file: ${file}`));
-        }
-      }
-
       console.log(
         chalk.green("✔ Successfully installed Anti-Chaotic Agent Kit."),
       );
@@ -56,56 +68,158 @@ program
   .command("update")
   .description("Update .agent configuration from GitHub")
   .action(async () => {
-    const targetAgentDir = path.join(process.cwd(), ".agent");
+    const projectRoot = process.cwd();
+    const targetAgentDir = path.join(projectRoot, ".agent");
+    const tempDir = path.join(os.tmpdir(), `anti-chaotic-update-${Date.now()}`);
     const { default: inquirer } = await import("inquirer");
 
     try {
-      if (await fs.pathExists(targetAgentDir)) {
-        const { confirm } = await inquirer.prompt([
-          {
-            type: "confirm",
-            name: "confirm",
-            message: `Directory ${targetAgentDir} already exists. Do you want to overwrite it?`,
-            default: false,
-          },
-        ]);
-
-        if (!confirm) {
-          console.log(chalk.yellow("Operation cancelled by user."));
-          return;
-        }
+      if (!(await fs.pathExists(targetAgentDir))) {
+        console.log(
+          chalk.red("✘ .agent directory not found. Please run 'init' first."),
+        );
+        return;
       }
 
-      console.log(
-        chalk.blue(`Updating Anti-Chaotic Agent Kit from ${REPO_URI}...`),
-      );
+      console.log(chalk.blue("Checking for updates from GitHub..."));
 
       const { downloadTemplate } = await import("giget");
       await downloadTemplate(`github:${REPO_URI}`, {
-        dir: targetAgentDir,
+        dir: tempDir,
         force: true,
       });
 
-      // Cleanup deprecated files
-      const deprecatedFiles = [
-        "rules/documentation.md",
-        "workflows/docs-from-codebase.md",
-        "workflows/requirement-analysis.md",
-        "workflows/setup-codebase.md",
-      ];
-
-      for (const file of deprecatedFiles) {
-        const filePath = path.join(targetAgentDir, file);
-        if (await fs.pathExists(filePath)) {
-          await fs.remove(filePath);
-          console.log(chalk.dim(`  Removed legacy file: ${file}`));
+      const localFiles = await getAllFiles(targetAgentDir);
+      const remoteFiles = await getAllFiles(tempDir);
+
+      const modified = [];
+      const added = [];
+      const deleted = [];
+
+      // Check for modified and deleted files
+      for (const file of localFiles) {
+        const localPath = path.join(targetAgentDir, file);
+        const remotePath = path.join(tempDir, file);
+
+        if (await fs.pathExists(remotePath)) {
+          const localHash = await getFileHash(localPath);
+          const remoteHash = await getFileHash(remotePath);
+          if (localHash !== remoteHash) {
+            modified.push(file);
+          }
+        } else {
+          deleted.push(file);
         }
       }
 
-      console.log(chalk.green("✔ Successfully updated .agent from GitHub."));
-      console.log(chalk.dim(`  Location: ${targetAgentDir}`));
+      // Check for new files from remote
+      for (const file of remoteFiles) {
+        if (!localFiles.includes(file)) {
+          added.push(file);
+        }
+      }
+
+      if (modified.length === 0 && added.length === 0 && deleted.length === 0) {
+        console.log(
+          chalk.green("✔ Your .agent configuration is already up to date."),
+        );
+        await fs.remove(tempDir);
+        return;
+      }
+
+      console.log(chalk.yellow("\nUpdate Summary:"));
+
+      let filesToOverwrite = [];
+      let filesToAdd = [];
+      let filesToDelete = [];
+
+      if (modified.length > 0) {
+        const { selectedModified } = await inquirer.prompt([
+          {
+            type: "checkbox",
+            name: "selectedModified",
+            message:
+              "Select MODIFIED files to OVERWRITE (Unselected = Keep Local):",
+            choices: modified.map((f) => ({
+              name: f,
+              value: f,
+              checked: false,
+            })),
+            pageSize: 20,
+          },
+        ]);
+        filesToOverwrite = selectedModified;
+      }
+
+      if (added.length > 0) {
+        const { selectedAdded } = await inquirer.prompt([
+          {
+            type: "checkbox",
+            name: "selectedAdded",
+            message: "Select NEW files to ADD (Unselected = Skip):",
+            choices: added.map((f) => ({ name: f, value: f, checked: true })),
+            pageSize: 20,
+          },
+        ]);
+        filesToAdd = selectedAdded;
+      }
+
+      if (deleted.length > 0) {
+        const { selectedDeleted } = await inquirer.prompt([
+          {
+            type: "checkbox",
+            name: "selectedDeleted",
+            message:
+              "Select DELETED files to REMOVE locally (Unselected = Keep Local):",
+            choices: deleted.map((f) => ({ name: f, value: f, checked: true })),
+            pageSize: 20,
+          },
+        ]);
+        filesToDelete = selectedDeleted;
+      }
+
+      if (
+        filesToOverwrite.length === 0 &&
+        filesToAdd.length === 0 &&
+        filesToDelete.length === 0
+      ) {
+        console.log(chalk.yellow("No changes selected. Update cancelled."));
+        await fs.remove(tempDir);
+        return;
+      }
+
+      console.log(chalk.blue("\nApplying updates..."));
+
+      // Process Overwrites
+      for (const file of filesToOverwrite) {
+        const src = path.join(tempDir, file);
+        const dest = path.join(targetAgentDir, file);
+        await fs.copy(src, dest, { overwrite: true });
+        console.log(chalk.green(`  ✔ Overwritten: ${file}`));
+      }
+
+      // Process New Files
+      for (const file of filesToAdd) {
+        const src = path.join(tempDir, file);
+        const dest = path.join(targetAgentDir, file);
+        await fs.copy(src, dest, { overwrite: false });
+        console.log(chalk.green(`  ✔ Added: ${file}`));
+      }
+
+      // Process Deletions
+      for (const file of filesToDelete) {
+        const dest = path.join(targetAgentDir, file);
+        await fs.remove(dest);
+        console.log(chalk.red(`  ✘ Deleted: ${file}`));
+      }
+
+      console.log(chalk.green("\n✔ Selected updates applied successfully."));
+
+      // Cleanup
+      await fs.remove(tempDir);
     } catch (err) {
       console.error(chalk.red("✘ Error updating framework:"), err.message);
+      if (await fs.pathExists(tempDir)) await fs.remove(tempDir);
     }
   });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kienha/anti-chaotic",
-  "version": "1.0.7",
+  "version": "1.0.9",
   "description": "Anti-Chaotic - An agent kit for Antigravity to standardize the software development process",
   "main": "index.js",
   "publishConfig": {