@nockdev/awf 6.2.0 → 6.2.1

package/.agent/skills/tooling/mcp/SKILL.md

@@ -0,0 +1,114 @@
+# MCP — Model Context Protocol Server Development
+
+> Skill cho phát triển MCP servers & clients  
+> JSON-RPC 2.0 • Tool/Resource/Prompt primitives • OAuth 2.1
+
+---
+
+## Khi Nào Dùng
+
+- Xây dựng MCP server kết nối AI agents với tools/data
+- Phát triển custom tools, resources, prompts cho Claude/Gemini/ChatGPT
+- Thiết kế transport layer (stdio local, Streamable HTTP production)
+- Implement OAuth 2.1 cho MCP servers remote
+
+## Architecture
+
+```
+┌─────────────────────────────────────────┐
+│           HOST APPLICATION              │
+│  (Claude Desktop, VS Code, IDE...)      │
+│                                         │
+│  ┌──────────┐  ┌──────────┐             │
+│  │ Client A │  │ Client B │  ← 1:1 map  │
+│  └────┬─────┘  └────┬─────┘             │
+└───────│──────────────│──────────────────┘
+        │              │
+  ┌─────▼─────┐  ┌─────▼─────┐
+  │ Server A  │  │ Server B  │  ← Bounded context
+  │ (Files)   │  │ (GitHub)  │  ← Single responsibility
+  └───────────┘  └───────────┘
+```
+
+## Core Patterns
+
+### Transport Selection
+
+| Transport           | Use Case                           | Auth               |
+| ------------------- | ---------------------------------- | ------------------ |
+| **stdio**           | Local dev, CLI tools, same-machine | Not required       |
+| **Streamable HTTP** | Remote, production, multi-user     | OAuth 2.1 required |
+
+### Tool Design (CRITICAL)
+
+```typescript
+// ✅ GOOD: Stateless, idempotent, bounded
+server.tool(
+  "search_files",
+  {
+    query: z.string(),
+    maxResults: z.number().default(10),
+  },
+  async ({ query, maxResults }) => {
+    const results = await search(query, maxResults);
+    return { content: [{ type: "text", text: JSON.stringify(results) }] };
+  },
+);
+
+// ❌ BAD: Stateful, unbounded results
+server.tool("get_all_data", {}, async () => {
+  return { content: [{ type: "text", text: entireDatabase }] }; // OOM!
+});
+```
+
+### Tool Rules
+
+1. **Stateless** — No side effects between calls
+2. **Idempotent** — Same input → same output
+3. **Bounded** — Use `maxResults` + pagination tokens
+4. **Validated** — JSON Schema cho tất cả inputs
+5. **Documented** — Clear description cho AI model
+
+### Resource Design
+
+```typescript
+// Static resource
+server.resource("config", "config://app", async () => ({
+  contents: [{ uri: "config://app", text: configData }],
+}));
+
+// Dynamic resource template
+server.resourceTemplate("user/{id}", async (uri) => ({
+  contents: [{ uri, text: await getUser(uri.params.id) }],
+}));
+```
+
+## Security Checklist
+
+- ✅ OAuth 2.1 cho HTTP transport
+- ✅ Input validation (JSON Schema)
+- ✅ Response size limits
+- ✅ Rate limiting per client
+- ✅ No secrets in tool outputs
+- ✅ Sanitize file paths (prevent traversal)
+
+## Common Traps
+
+| Trap                 | Giải pháp                                    |
+| -------------------- | -------------------------------------------- |
+| Response quá lớn     | Pagination tokens, `maxResults`              |
+| Timeout              | Set timeout per tool, return partial results |
+| Error classification | Use JSON-RPC error codes (-32600 to -32603)  |
+| Concurrent requests  | Stateless design, no shared mutable state    |
+| Transport mismatch   | stdio=dev only, HTTP=prod with OAuth         |
+
+## SDK Quick Reference
+
+| Language   | Package                     | Docs                    |
+| ---------- | --------------------------- | ----------------------- |
+| TypeScript | `@modelcontextprotocol/sdk` | modelcontextprotocol.io |
+| Python     | `mcp`                       | modelcontextprotocol.io |
+
+---
+
+_DOMYH Awesome Code • MCP Skill v1.0.0_

package/.agent/skills/tooling/mcp/data/security.yaml

@@ -0,0 +1,116 @@
+# MCP Security Patterns - HSA MCP Skill
+# Updated: 2026-02-12
+
+metadata:
+  skill: mcp
+  domain: security
+  version: "1.0.0"
+  updated: "2026-02-12"
+  patterns_count: 8
+
+patterns:
+  - id: sec001
+    name: oauth21
+    category: security
+    description: OAuth 2.1 authentication for HTTP transport
+    text: oauth 2.1 authentication http transport authorization bearer token
+    example: |
+      // Server: validate OAuth token
+      app.use("/mcp", async (req, res, next) => {
+        const token = req.headers.authorization?.split("Bearer ")[1];
+        if (!token || !await validateToken(token)) {
+          return res.status(401).json({ error: "Unauthorized" });
+        }
+        next();
+      });
+    severity: CRITICAL
+    rule: "OAuth 2.1 is MANDATORY for HTTP transport"
+
+  - id: sec002
+    name: input_sanitization
+    category: security
+    description: Sanitize all user inputs to prevent injection
+    text: input sanitization injection prevention path traversal command injection
+    example: |
+      // Prevent path traversal
+      const safePath = path.resolve(baseDir, userPath);
+      if (!safePath.startsWith(baseDir)) throw new Error("Path traversal!");
+      // Prevent command injection
+      const safeArg = shellEscape(userInput);
+    severity: CRITICAL
+
+  - id: sec003
+    name: rate_limiting
+    category: security
+    description: Rate limiting per client to prevent abuse
+    text: rate limit throttle abuse prevention per client request limit
+    example: |
+      const limiter = new RateLimiter({ windowMs: 60000, max: 100 });
+      app.use("/mcp", limiter.middleware());
+    severity: HIGH
+
+  - id: sec004
+    name: response_size_limit
+    category: security
+    description: Limit response sizes to prevent OOM
+    text: response size limit out of memory prevent large payload
+    example: |
+      const MAX_RESPONSE_SIZE = 1024 * 1024; // 1MB
+      if (result.length > MAX_RESPONSE_SIZE) {
+        return { content: [{ type: "text",
+          text: `Result too large (${result.length} bytes). Use pagination.` }],
+          isError: true };
+      }
+    severity: HIGH
+
+  - id: sec005
+    name: secrets_protection
+    category: security
+    description: Never expose secrets in tool outputs
+    text: secrets protection api keys passwords environment variables
+    rule: "NEVER include API keys, passwords, or tokens in tool responses"
+    example: |
+      // ✅ Redact secrets
+      const safeConfig = { ...config, apiKey: "***REDACTED***" };
+      // ❌ NEVER do this
+      return { content: [{ type: "text", text: process.env.API_KEY }] };
+    severity: CRITICAL
+
+  - id: sec006
+    name: scope_limitation
+    category: security
+    description: Limit server capabilities to minimal required scope
+    text: scope limitation minimal permissions principle of least privilege
+    rule: "Each server should only access what it needs"
+    example: |
+      // ✅ Read-only database server
+      server.tool("query", schema, async (input) => {
+        return db.query(input.sql); // SELECT only, no mutations
+      });
+
+  - id: sec007
+    name: timeout_handling
+    category: security
+    description: Set timeouts for all tool operations
+    text: timeout handling abort signal cancel long running operation
+    example: |
+      server.tool("fetch_data", schema, async (input) => {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), 30000);
+        try {
+          return await fetchData(input, { signal: controller.signal });
+        } finally { clearTimeout(timeout); }
+      });
+    severity: HIGH
+
+  - id: sec008
+    name: logging_audit
+    category: security
+    description: Audit logging for all tool invocations
+    text: logging audit trail tool invocation tracking
+    example: |
+      server.tool("write_file", schema, async (input) => {
+        logger.info({ tool: "write_file", input: sanitize(input), timestamp: Date.now() });
+        return await writeFile(input);
+      });
+    severity: MEDIUM

package/.agent/skills/tooling/mcp/data/tool-design.yaml

@@ -0,0 +1,124 @@
+# MCP Tool Design Patterns - HSA MCP Skill
+# Updated: 2026-02-12
+
+metadata:
+  skill: mcp
+  domain: tool-design
+  version: "1.0.0"
+  updated: "2026-02-12"
+  patterns_count: 8
+
+patterns:
+  - id: td001
+    name: stateless_tool
+    category: design
+    description: Stateless tool that produces same output for same input
+    text: stateless tool idempotent pure function no side effects
+    example: |
+      server.tool("search", { query: z.string(), limit: z.number().default(10) },
+        async ({ query, limit }) => {
+          const results = await db.search(query, limit);
+          return { content: [{ type: "text", text: JSON.stringify(results) }] };
+        });
+    severity: CRITICAL
+    rule: "Tools MUST be stateless and idempotent"
+
+  - id: td002
+    name: pagination
+    category: design
+    description: Pagination pattern for large result sets
+    text: pagination cursor token next page large results bounded
+    example: |
+      server.tool("list_items", {
+        cursor: z.string().optional(),
+        pageSize: z.number().default(20).max(100)
+      }, async ({ cursor, pageSize }) => {
+        const { items, nextCursor } = await db.paginate(cursor, pageSize);
+        return {
+          content: [{ type: "text", text: JSON.stringify(items) }],
+          _meta: { nextCursor }
+        };
+      });
+    rule: "NEVER return unbounded results"
+
+  - id: td003
+    name: input_validation
+    category: design
+    description: JSON Schema validation for all tool inputs
+    text: input validation json schema zod type safety
+    example: |
+      const schema = z.object({
+        path: z.string().refine(p => !p.includes(".."), "No path traversal"),
+        content: z.string().max(100000, "Content too large")
+      });
+    severity: CRITICAL
+
+  - id: td004
+    name: error_handling
+    category: design
+    description: Structured error responses using JSON-RPC error codes
+    text: error handling json-rpc error codes recoverable fatal
+    example: |
+      // Return error as content (recoverable)
+      return { content: [{ type: "text", text: "Error: File not found" }], isError: true };
+      // Throw for fatal errors
+      throw new McpError(ErrorCode.InvalidParams, "Invalid file path");
+    error_codes:
+      -32600: "Invalid Request"
+      -32601: "Method not found"
+      -32602: "Invalid params"
+      -32603: "Internal error"
+
+  - id: td005
+    name: resource_design
+    category: design
+    description: Resource primitives for exposing data
+    text: resource uri template static dynamic data exposure
+    example: |
+      // Static resource
+      server.resource("readme", "file:///README.md", async () => ({
+        contents: [{ uri: "file:///README.md", text: readmeContent }]
+      }));
+      // Dynamic resource template
+      server.resourceTemplate("user/{id}", async (uri) => ({
+        contents: [{ uri: uri.href, text: await getUser(uri.params.id) }]
+      }));
+
+  - id: td006
+    name: prompt_design
+    category: design
+    description: Prompt primitives for reusable prompt templates
+    text: prompt template reusable parameterized prompt primitive
+    example: |
+      server.prompt("code_review", { language: z.string(), code: z.string() },
+        ({ language, code }) => ({
+          messages: [{
+            role: "user",
+            content: { type: "text", text: `Review this ${language} code:\n${code}` }
+          }]
+        }));
+
+  - id: td007
+    name: bounded_context
+    category: design
+    description: Single responsibility per server
+    text: bounded context single responsibility server separation concerns
+    example: "// ✅ Separate servers: file-server, git-server, db-server"
+    rule: "Each MCP server should have ONE bounded context"
+    anti_pattern: "// ❌ One server doing files + git + database + email"
+
+  - id: td008
+    name: response_format
+    category: design
+    description: Content types and response formatting
+    text: response content type text image resource embedded
+    example: |
+      // Text content
+      { content: [{ type: "text", text: "Hello" }] }
+      // Image content
+      { content: [{ type: "image", data: base64Data, mimeType: "image/png" }] }
+      // Multiple content blocks
+      { content: [
+        { type: "text", text: "Found 3 results:" },
+        { type: "text", text: JSON.stringify(results) }
+      ]}

package/.agent/skills/tooling/mcp/data/transport-patterns.yaml

@@ -0,0 +1,95 @@
+# MCP Transport Patterns - HSA MCP Skill
+# Version: MCP SDK 2025-2026
+# Updated: 2026-02-12
+
+metadata:
+  skill: mcp
+  domain: transport
+  version: "1.0.0"
+  updated: "2026-02-12"
+  patterns_count: 8
+
+patterns:
+  - id: tp001
+    name: stdio_transport
+    category: transport
+    description: Local stdio transport for development and CLI tools
+    text: stdio transport local development cli pipe subprocess
+    example: "new StdioServerTransport(); // stdin/stdout"
+    use_case: Local MCP servers, IDE integrations, same-machine
+    severity: INFO
+
+  - id: tp002
+    name: streamable_http
+    category: transport
+    description: Streamable HTTP transport for production remote servers
+    text: streamable http transport production remote sse server-sent events
+    example: "new StreamableHTTPServerTransport({ sessionId })"
+    use_case: Remote servers, multi-user, cloud deployment
+    severity: INFO
+    requires_auth: true
+
+  - id: tp003
+    name: server_setup_stdio
+    category: transport
+    description: Basic MCP server setup with stdio transport
+    text: server create stdio setup basic initialize
+    example: |
+      const server = new McpServer({ name: "my-server", version: "1.0.0" });
+      const transport = new StdioServerTransport();
+      await server.connect(transport);
+
+  - id: tp004
+    name: server_setup_http
+    category: transport
+    description: MCP server with Streamable HTTP + Express
+    text: server http express setup production oauth
+    example: |
+      app.post("/mcp", async (req, res) => {
+        const transport = new StreamableHTTPServerTransport({ sessionId: req.sessionId });
+        await server.connect(transport);
+        await transport.handleRequest(req, res);
+      });
+
+  - id: tp005
+    name: transport_selection
+    category: transport
+    description: Decision matrix for choosing transport
+    text: transport selection guide choose stdio http decision
+    decision_matrix:
+      stdio:
+        when: "Local dev, CLI, same machine, no auth needed"
+        pros: "Simple, no network, fast"
+        cons: "Local only, single client"
+      streamable_http:
+        when: "Production, remote, multi-user, cloud"
+        pros: "Scalable, auth support, firewall friendly"
+        cons: "Complex setup, requires OAuth 2.1"
+
+  - id: tp006
+    name: connection_lifecycle
+    category: transport
+    description: MCP connection lifecycle management
+    text: connection lifecycle initialize shutdown cleanup graceful
+    example: |
+      server.onclose = async () => { await cleanup(); };
+      process.on("SIGTERM", async () => { await server.close(); });
+
+  - id: tp007
+    name: session_management
+    category: transport
+    description: Session management for HTTP transport
+    text: session management http stateless reconnect resume
+    example: "transport = new StreamableHTTPServerTransport({ sessionId: uuid() });"
+    note: "Sessions are optional; prefer stateless design"
+
+  - id: tp008
+    name: error_transport
+    category: transport
+    description: Transport-level error handling
+    text: transport error handling reconnect retry timeout
+    example: |
+      server.onerror = (error) => {
+        console.error("[MCP Error]", error);
+        // Don't crash - log and continue
+      };

package/.agent/templates/README.md

@@ -1,4 +1,4 @@
-# 📄 DOMYH Awesome Code Templates v6.2.0
+# 📄 DOMYH Awesome Code Templates v6.2.1
 
 > Output templates for agent-generated reports and plans
 
@@ -22,7 +22,7 @@
 ```yaml
 ---
 name: template-name
-version: "6.1.2"
+version: "6.2.1"
 type: report|plan|format|wizard
 triggers: ["/command"]
 ---

package/.agent/templates/debug-report.md

@@ -1,6 +1,6 @@
 ---
 name: debug-report
-version: "6.1.2"
+version: "6.2.1"
 type: report
 triggers: ["/debug"]
 ---

package/.agent/templates/deploy-plan.md

@@ -1,6 +1,6 @@
 ---
 name: deploy-plan
-version: "6.1.2"
+version: "6.2.1"
 type: plan
 triggers: ["/deploy"]
 ---

package/.agent/templates/doc-template.md

@@ -1,6 +1,6 @@
 ---
 name: doc-template
-version: "6.1.2"
+version: "6.2.1"
 type: wizard
 triggers: ["/doc", "/generate"]
 ---

package/.agent/templates/index.yaml

@@ -2,7 +2,7 @@
 # Template Index — HSA Semantic Template Matching
 # =============================================================================
 # DOMYH Awesome Code Agent — Template Registry for HSA
-# Version: 6.1.2
+# Version: 6.2.1
 # =============================================================================
 
 templates:
@@ -236,4 +236,4 @@ search:
 # =============================================================================
 # Footer
 # =============================================================================
-# _DOMYH Awesome Code • Template Index v6.2.0 • HSA Integration_
+# _DOMYH Awesome Code • Template Index v6.2.1 • HSA Integration_

package/.agent/templates/migrate-plan.md

@@ -1,6 +1,6 @@
 ---
 name: migrate-plan
-version: "6.1.2"
+version: "6.2.1"
 type: plan
 triggers: ["/migrate"]
 ---

package/.agent/templates/phase-template.md

@@ -1,4 +1,4 @@
-# 📋 Phase Template — DOMYH v6.2.0
+# 📋 Phase Template — DOMYH v6.2.1
 
 > **Mục đích**: Template chuẩn cho phase files khi sử dụng `/plan full`
 > **Tạo bởi**: Agent tự động tạo theo complexity detection

package/.agent/templates/tasks/audit.yaml

@@ -8,7 +8,7 @@
 
 ```yaml
 task_type: audit
-version: "6.1.2"
+version: "6.2.1"
 
 # Required fields
 scope: string              # What to audit

package/.agent/templates/tasks/bug_fix.yaml

@@ -8,7 +8,7 @@
 
 ```yaml
 task_type: bug_fix
-version: "6.1.2"
+version: "6.2.1"
 
 # Required fields
 symptom: string              # What's the visible problem

package/.agent/templates/tasks/code_implementation.yaml

@@ -8,7 +8,7 @@
 
 ```yaml
 task_type: code_implementation
-version: "6.1.2"
+version: "6.2.1"
 
 # Required fields
 description: string       # What to build

package/.agent/templates/tasks/refactor.yaml

@@ -8,7 +8,7 @@
 
 ```yaml
 task_type: refactor
-version: "6.1.2"
+version: "6.2.1"
 
 # Required fields
 target: string            # What to refactor

package/.agent/templates/test-report.md

@@ -1,6 +1,6 @@
 ---
 name: test-report
-version: "6.1.2"
+version: "6.2.1"
 type: report
 triggers: ["/test"]
 ---

package/.agent/workflows/code.md

@@ -1,6 +1,6 @@
 ---
 description: "💻 Write production-ready code, fix/improve existing projects, with proper error handling, types, and documentation"
-skills: { required: [], contextual: [auto] }
+skills: { required: [], contextual: [auto, domyh-design, tailwind] }
 ---
 
 # 💻 /code — Code Pro
@@ -13,6 +13,13 @@ skills: { required: [], contextual: [auto] }
 ## CODE FLOW
 
 1. **DETECT** (Auto) — Parse intent (feature/bugfix/refactor), detect stack via HSA (`hsa_detect_stack`), load language skill via HSA (`hsa_get_context`)
+   - **UI INTENT CHECK** (→ See FLOW.md §18.1):
+     Classify intent into T1 (Create) / T2 (Modify) / T3 (Design):
+     T1 (new UI, no existing ref) → Follow FLOW.md §18.2 Create Pipeline (12 steps)
+     T2 (modify existing UI) → Follow FLOW.md §18.3 Modify Pipeline (9 steps)
+     T3 (design-only, no code) → Route to /visualize (§18.4)
+     Auto-load: `domyh-design` + `tailwind` skills
+     Auto-run: design system search → inject design tokens + platform guidelines
 2. **PLAN** — Break down into steps, identify dependencies → `hsa_prefetch` planned files → ⛔ STOP if major change (>50 lines). Show step count: `Plan: 4 steps, ~85 lines`
 3. **EXECUTE** — Write code following skill patterns, error handling + types, add tests (auto test loop). Show progress: `[Step 2/4] Creating auth middleware...`
 4. **VERIFY** — Run tests → Fix → Repeat (max 3), lint check. Agent re-reads ALL generated code:
@@ -23,6 +30,20 @@ skills: { required: [], contextual: [auto] }
    - [ ] Names follow language conventions?
    - [ ] No security anti-patterns (hardcoded secrets, raw SQL)?
    - → If issues found: fix silently before output
+   - **UI QUALITY GATE** (if UI intent detected → FLOW.md §18.2 A9):
+     Apply Visual QA Pipeline (score /100):
+     L1. Accessibility (30pts): WCAG 2.2 AA, contrast ≥ 4.5:1, keyboard nav, focus visible
+     L2. Visual Consistency (25pts): design tokens (no magic values), spacing rhythm, typography scale
+     L3. Responsiveness (20pts): 375px / 768px / 1024px / 1440px breakpoints pass
+     L4. Interaction Quality (15pts): hover/focus/active states, loading/error states
+     L5. Performance (10pts): CLS < 0.1, images optimized, CSS < 50KB
+     Apply Nielsen Heuristic Check (§18.2 A10): 10 items, score ≥8/10
+     Result: ≥90/100 → SHIP ✅ | 70-89 → FIX MINOR ⚠️ | <70 → REDESIGN ❌
+     - [ ] Design tokens used (no magic color/spacing values)
+     - [ ] Responsive: tested 375px, 768px, 1024px, 1440px
+     - [ ] Dark mode: no pure black/white, CSS variables, prefers-color-scheme
+     - [ ] SVG icons only (no emoji as icons)
+     - [ ] Focus states visible, transitions 150-300ms
 5. **SYNC** — `hsa_check_changes` to update index, output summary of changes, confidence score (1-10), next steps. Persist key decisions to `memory/state.json`
 
 ---

package/.agent/workflows/deploy.md

@@ -1,6 +1,10 @@
 ---
 description: "🚀 Deploy to production with pre-checks, rollback plan, and post-verification"
-skills: { required: [ci-cd], contextual: [docker, kubernetes, aws] }
+skills:
+  {
+    required: [ci-cd],
+    contextual: [docker, kubernetes, aws, terraform, gcp, azure],
+  }
 ---
 
 # 🚀 /deploy — Deploy Pro