@ai-content-space/loopx 0.1.2 → 0.1.4

package/plugins/loopx/skills/debug/root-cause-tracing.md

@@ -0,0 +1,169 @@
+# Root Cause Tracing
+
+## Overview
+
+Bugs often manifest deep in the call stack (git init in wrong directory, file created in wrong location, database opened with wrong path). Your instinct is to fix where the error appears, but that's treating a symptom.
+
+**Core principle:** Trace backward through the call chain until you find the original trigger, then fix at the source.
+
+## When to Use
+
+```dot
+digraph when_to_use {
+    "Bug appears deep in stack?" [shape=diamond];
+    "Can trace backwards?" [shape=diamond];
+    "Fix at symptom point" [shape=box];
+    "Trace to original trigger" [shape=box];
+    "BETTER: Also add defense-in-depth" [shape=box];
+
+    "Bug appears deep in stack?" -> "Can trace backwards?" [label="yes"];
+    "Can trace backwards?" -> "Trace to original trigger" [label="yes"];
+    "Can trace backwards?" -> "Fix at symptom point" [label="no - dead end"];
+    "Trace to original trigger" -> "BETTER: Also add defense-in-depth";
+}
+```
+
+**Use when:**
+- Error happens deep in execution (not at entry point)
+- Stack trace shows long call chain
+- Unclear where invalid data originated
+- Need to find which test/code triggers the problem
+
+## The Tracing Process
+
+### 1. Observe the Symptom
+```
+Error: git init failed in ~/project/packages/core
+```
+
+### 2. Find Immediate Cause
+**What code directly causes this?**
+```typescript
+await execFileAsync('git', ['init'], { cwd: projectDir });
+```
+
+### 3. Ask: What Called This?
+```typescript
+WorktreeManager.createSessionWorktree(projectDir, sessionId)
+  → called by Session.initializeWorkspace()
+  → called by Session.create()
+  → called by test at Project.create()
+```
+
+### 4. Keep Tracing Up
+**What value was passed?**
+- `projectDir = ''` (empty string!)
+- Empty string as `cwd` resolves to `process.cwd()`
+- That's the source code directory!
+
+### 5. Find Original Trigger
+**Where did empty string come from?**
+```typescript
+const context = setupCoreTest(); // Returns { tempDir: '' }
+Project.create('name', context.tempDir); // Accessed before beforeEach!
+```
+
+## Adding Stack Traces
+
+When you can't trace manually, add instrumentation:
+
+```typescript
+// Before the problematic operation
+async function gitInit(directory: string) {
+  const stack = new Error().stack;
+  console.error('DEBUG git init:', {
+    directory,
+    cwd: process.cwd(),
+    nodeEnv: process.env.NODE_ENV,
+    stack,
+  });
+
+  await execFileAsync('git', ['init'], { cwd: directory });
+}
+```
+
+**Critical:** Use `console.error()` in tests (not logger - may not show)
+
+**Run and capture:**
+```bash
+npm test 2>&1 | grep 'DEBUG git init'
+```
+
+**Analyze stack traces:**
+- Look for test file names
+- Find the line number triggering the call
+- Identify the pattern (same test? same parameter?)
+
+## Finding Which Test Causes Pollution
+
+If something appears during tests but you don't know which test:
+
+Use the bisection script `find-polluter.sh` in this directory:
+
+```bash
+./find-polluter.sh '.git' 'src/**/*.test.ts'
+```
+
+Runs tests one-by-one, stops at first polluter. See script for usage.
+
+## Real Example: Empty projectDir
+
+**Symptom:** `.git` created in `packages/core/` (source code)
+
+**Trace chain:**
+1. `git init` runs in `process.cwd()` ← empty cwd parameter
+2. WorktreeManager called with empty projectDir
+3. Session.create() passed empty string
+4. Test accessed `context.tempDir` before beforeEach
+5. setupCoreTest() returns `{ tempDir: '' }` initially
+
+**Root cause:** Top-level variable initialization accessing empty value
+
+**Fix:** Made tempDir a getter that throws if accessed before beforeEach
+
+**Also added defense-in-depth:**
+- Layer 1: Project.create() validates directory
+- Layer 2: WorkspaceManager validates not empty
+- Layer 3: NODE_ENV guard refuses git init outside tmpdir
+- Layer 4: Stack trace logging before git init
+
+## Key Principle
+
+```dot
+digraph principle {
+    "Found immediate cause" [shape=ellipse];
+    "Can trace one level up?" [shape=diamond];
+    "Trace backwards" [shape=box];
+    "Is this the source?" [shape=diamond];
+    "Fix at source" [shape=box];
+    "Add validation at each layer" [shape=box];
+    "Bug impossible" [shape=doublecircle];
+    "NEVER fix just the symptom" [shape=octagon, style=filled, fillcolor=red, fontcolor=white];
+
+    "Found immediate cause" -> "Can trace one level up?";
+    "Can trace one level up?" -> "Trace backwards" [label="yes"];
+    "Can trace one level up?" -> "NEVER fix just the symptom" [label="no"];
+    "Trace backwards" -> "Is this the source?";
+    "Is this the source?" -> "Trace backwards" [label="no - keeps going"];
+    "Is this the source?" -> "Fix at source" [label="yes"];
+    "Fix at source" -> "Add validation at each layer";
+    "Add validation at each layer" -> "Bug impossible";
+}
+```
+
+**NEVER fix just where the error appears.** Trace back to find the original trigger.
+
+## Stack Trace Tips
+
+**In tests:** Use `console.error()` not logger - logger may be suppressed
+**Before operation:** Log before the dangerous operation, not after it fails
+**Include context:** Directory, cwd, environment variables, timestamps
+**Capture stack:** `new Error().stack` shows complete call chain
+
+## Real-World Impact
+
+From debugging session (2025-10-03):
+- Found root cause through 5-level trace
+- Fixed at source (getter validation)
+- Added 4 layers of defense
+- 1847 tests passed, zero pollution

package/plugins/loopx/skills/go-style/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: go-style
+description: Go language style support for loopx. Use before creating or editing Go (.go) files, especially inside build execution lanes.
+---
+
+# Go Style
+
+## Purpose
+
+`go-style` is a lightweight Go coding discipline skill. It should guide edits to `.go` files without overriding the repository's established conventions.
+
+Use it as a support skill from `build` when Go files are created or modified, and directly when the user asks for Go style, idiomatic Go, or Go code cleanup.
+
+## Core Rules
+
+- Preserve local project style first. If nearby code conflicts with this skill, follow the local pattern unless it is clearly broken.
+- Keep the happy path straight down. Return early for errors and guard clauses.
+- Put `context.Context` first in functions that accept a context.
+- Wrap propagated errors with operation context using `%w` when the caller benefits from the cause.
+- Do not wrap errors when returning framework/status errors that must preserve exact type or code semantics.
+- Use sentinel errors, typed errors, or framework errors according to the existing project pattern; do not force sentinel errors everywhere.
+- Avoid shadowing Go predeclared identifiers such as `len`, `error`, `string`, `copy`, `new`, and `make`.
+- Keep interfaces small and define them at the consumer boundary when practical.
+- Prefer table-driven tests for behavior matrices.
+- Run `gofmt` on edited Go files before verification.
+
+## Error Handling
+
+Good default:
+
+```go
+user, err := repo.GetUser(ctx, userID)
+if err != nil {
+    return nil, fmt.Errorf("get user %s: %w", userID, err)
+}
+```
+
+Use exact framework errors when the framework contract requires them:
+
+```go
+if !allowed {
+    return nil, errors.Forbidden("PERMISSION_DENIED", "permission denied")
+}
+```
+
+Expected error categories may be represented by:
+
+- package-level sentinel errors with `errors.Is`
+- typed errors with structured fields
+- Kratos/API status errors
+- existing project domain error helpers
+
+Choose the one already used in the codebase.
+
+## Comments
+
+- Exported symbols should have Go doc comments that start with the symbol name.
+- Short local comments are acceptable when they explain why, not what.
+- Prefer complete sentences for package, exported type, exported function, and non-obvious behavior comments.
+
+## Verification
+
+For Go edits, prefer the narrowest meaningful verification first, then broaden if the touched surface is shared:
+
+```bash
+gofmt -w <edited-go-files>
+go test ./...
+go vet ./...
+```
+
+Use project-specific commands when present, such as `make test`, `make lint`, `golangci-lint run`, or repository scripts.

package/plugins/loopx/skills/kratos/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: kratos
+description: Go-Kratos framework support for loopx. Use for Kratos microservices, proto/buf API work, service/biz/data layering, Kratos middleware, auth, configuration, and troubleshooting.
+---
+
+# Kratos
+
+## Purpose
+
+`kratos` supports Go-Kratos microservice work while staying subordinate to the repository's existing architecture.
+
+Use this skill when the user mentions Kratos, protobuf APIs, buf, service/biz/data layering, Kratos HTTP/gRPC servers, middleware, JWT/Casbin auth, or when the repository shows Kratos signals.
+
+## Project Detection
+
+Before applying Kratos-specific patterns, inspect for these signals:
+
+- `buf.yaml` or `buf.gen.yaml`
+- `api/**/*.proto`
+- `internal/service/`
+- `internal/biz/`
+- `internal/data/`
+- imports containing `github.com/go-kratos/kratos/v2`
+
+If signals are weak, ask whether to proceed with Kratos conventions before creating framework-specific structure.
+
+## Decision Map
+
+Use only the reference file needed for the current task:
+
+- New API / proto: `references/proto-api-design.md`
+- Service, biz, data layering: `references/architecture.md`
+- Configuration / startup: `references/configuration.md`
+- HTTP response customization, WebSocket, files: `references/http-customization.md`
+- JWT / Casbin / auth: `references/security-auth.md`
+- Middleware / logging: `references/middleware-logging.md`
+- Errors and troubleshooting: `references/troubleshooting.md`
+- MCP / advanced extensions: `references/advanced-features.md`
+
+## Architecture Defaults
+
+- Keep protocol concerns in `internal/service`.
+- Keep business rules and use cases in `internal/biz`.
+- Keep persistence, repositories, and external clients in `internal/data`.
+- Avoid leaking proto types into `biz` unless the existing project already does.
+- Prefer existing dependency injection style. Use `fx` examples only when the project already uses `fx`.
+- Preserve generated-code boundaries; edit source `.proto` or handwritten layers, not generated files.
+
+## Proto/API Defaults
+
+- Confirm package and `go_package` before adding proto files.
+- Add HTTP annotations only when HTTP exposure is required.
+- Use validation annotations when the project already uses `buf.validate` or `protovalidate`.
+- Regenerate code with the repository's existing command, such as `buf generate`, `make api`, or project scripts.
+
+## Integration With Other loopx Skills
+
+- Use `go-style` for handwritten `.go` edits.
+- Use `tdd` for behavior changes when a meaningful failing test can be written before implementation.
+- Use `debug` for Kratos runtime failures, generated-code mismatches, middleware ordering bugs, or request/response behavior that is not understood.
+- Use `verify` before claiming the API, generated code, or service behavior is ready.
+
+## Verification
+
+Prefer project-native commands. Common Kratos verification commands include:
+
+```bash
+buf lint
+buf generate
+go test ./...
+go vet ./...
+```
+
+If the project uses Make targets, prefer those over ad hoc commands.

package/plugins/loopx/skills/kratos/references/advanced-features.md

@@ -0,0 +1,314 @@
+# Advanced Features
+
+Guide for MCP server integration and other advanced Kratos features.
+
+## When to Use
+
+- Integrating Kratos with AI agents via MCP
+- Building tool-enabled microservices
+
+---
+
+## MCP Server Integration
+
+Kratos can be combined with MCP (Model Context Protocol) to expose microservice functionality as AI agent tools.
+
+### What is MCP?
+
+MCP is a protocol for AI agents to discover and call tools. By integrating MCP with Kratos services, you can:
+
+- Expose Kratos APIs as MCP tools for AI agents
+- Enable tool discovery and schema validation
+- Handle structured input/output for AI workflows
+
+### Library Options
+
+Two main Go MCP libraries exist:
+
+| Library | Maintainer | Use Case |
+|---------|------------|----------|
+| `github.com/mark3labs/mcp-go` | Mark3 Labs | Community implementation |
+| `github.com/modelcontextprotocol/go-sdk` | Anthropic | Official SDK |
+
+**Note:** No official Kratos MCP transport exists yet. Integration requires custom setup.
+
+### Integration Approach: MCP Handler in Kratos HTTP Server
+
+Add MCP endpoint to existing Kratos HTTP server:
+
+```go
+import (
+    "context"
+    "fmt"
+    "github.com/go-kratos/kratos/v2"
+    "github.com/go-kratos/kratos/v2/log"
+    "github.com/go-kratos/kratos/v2/transport/http"
+    mcp "github.com/mark3labs/mcp-go/mcp"
+    "github.com/mark3labs/mcp-go/server"
+)
+
+func main() {
+    // Create MCP server
+    mcpSrv := server.NewMCPServer("kratos-mcp", "v1.0.0")
+    
+    // Define tool
+    tool := mcp.NewTool("hello_world",
+        mcp.WithDescription("Say hello to someone"),
+        mcp.WithString("name",
+            mcp.Required(),
+            mcp.Description("Name of the person to greet"),
+        ),
+    )
+    
+    // Add tool handler
+    mcpSrv.AddTool(tool, helloHandler)
+    
+    // Create Kratos HTTP server with MCP endpoint
+    httpSrv := http.NewServer(http.Address(":8000"))
+    
+    // Register MCP handler on Kratos HTTP server
+    // MCP typically uses SSE (Server-Sent Events) transport
+    route := httpSrv.Route("/")
+    route.GET("/mcp", func(ctx http.Context) error {
+        // Handle MCP SSE requests
+        return handleMCPRequest(ctx, mcpSrv)
+    })
+    
+    // Create Kratos app
+    app := kratos.New(
+        kratos.Name("kratos-mcp"),
+        kratos.Server(httpSrv),
+    )
+    
+    if err := app.Run(); err != nil {
+        panic(err)
+    }
+}
+```
+
+### Tool Handler
+
+```go
+func helloHandler(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
+    // Extract arguments
+    name, ok := request.Params.Arguments["name"].(string)
+    if !ok {
+        return nil, errors.New("name must be a string")
+    }
+    
+    // Return result
+    return mcp.NewToolResultText(fmt.Sprintf("Hello, %s!", name)), nil
+}
+```
+
+### Multiple Tools
+
+```go
+func registerMCPTools(mcpSrv *server.MCPServer, userUC *biz.UserUseCase, orderUC *biz.OrderUseCase) {
+    // Tool 1: User lookup
+    userTool := mcp.NewTool("get_user",
+        mcp.WithDescription("Get user by ID"),
+        mcp.WithString("user_id",
+            mcp.Required(),
+            mcp.Description("User identifier"),
+        ),
+    )
+    mcpSrv.AddTool(userTool, func(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
+        userID, ok := req.Params.Arguments["user_id"].(string)
+        if !ok {
+            return mcp.NewToolResultError("user_id must be a string"), nil
+        }
+        // Call biz layer
+        user, err := userUC.GetUser(ctx, userID)
+        if err != nil {
+            return mcp.NewToolResultError(err.Error()), nil
+        }
+        return mcp.NewToolResultText(fmt.Sprintf("User: %s, Email: %s", user.Name, user.Email)), nil
+    })
+
+    // Tool 2: Order creation
+    orderTool := mcp.NewTool("create_order",
+        mcp.WithDescription("Create a new order"),
+        mcp.WithString("user_id", mcp.Required()),
+        mcp.WithString("product_id", mcp.Required()),
+        mcp.WithNumber("quantity", mcp.Required()),
+    )
+    mcpSrv.AddTool(orderTool, func(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
+        userID, ok := req.Params.Arguments["user_id"].(string)
+        if !ok {
+            return mcp.NewToolResultError("user_id must be a string"), nil
+        }
+        productID, ok := req.Params.Arguments["product_id"].(string)
+        if !ok {
+            return mcp.NewToolResultError("product_id must be a string"), nil
+        }
+        quantity, ok := req.Params.Arguments["quantity"].(float64)
+        if !ok {
+            return mcp.NewToolResultError("quantity must be a number"), nil
+        }
+        
+        // Call biz layer
+        order, err := orderUC.CreateOrder(ctx, userID, productID, int(quantity))
+        if err != nil {
+            return mcp.NewToolResultError(err.Error()), nil
+        }
+        
+        return mcp.NewToolResultText(fmt.Sprintf("Order created: %s", order.ID)), nil
+    })
+}
+```
+
+### MCP with Kratos Middleware
+
+Wrap MCP endpoint with Kratos middleware for logging, auth, etc.:
+
+```go
+func NewHTTPServer(c *conf.Server, mcpSrv *server.MCPServer, logger log.Logger) *http.Server {
+    srv := http.NewServer(
+        http.Address(c.Http.Addr),
+        http.Middleware(
+            recovery.Recovery(),
+            tracing.Server(),
+            logging.Server(logger),
+        ),
+    )
+    
+    // MCP endpoint with middleware chain
+    route := srv.Route("/")
+    route.GET("/mcp", func(ctx http.Context) error {
+        http.SetOperation(ctx, "/mcp/handle")
+        h := ctx.Middleware(func(ctx context.Context, req interface{}) (interface{}, error) {
+            return handleMCPRequest(ctx, mcpSrv)
+        })
+        resp, err := h(ctx, nil)
+        if err != nil {
+            return err
+        }
+        return ctx.JSON(200, resp)
+    })
+    
+    return srv
+}
+```
+
+### Health Check
+
+Add health check alongside MCP endpoint:
+
+```go
+route := srv.Route("/")
+route.GET("/health/ready", func(ctx http.Context) error {
+    return ctx.JSON(200, map[string]string{"status": "ok"})
+})
+route.GET("/mcp", handleMCP)
+```
+
+---
+
+## MCP Tool Schema Types
+
+### String Parameter
+
+```go
+mcp.WithString("name",
+    mcp.Required(),
+    mcp.Description("Description of parameter"),
+    mcp.Pattern("^[a-z]+$"),  // Optional: regex pattern
+)
+```
+
+### Number Parameter
+
+```go
+mcp.WithNumber("quantity",
+    mcp.Required(),
+    mcp.Description("Number of items"),
+    mcp.MinNumber(1),      // Optional: minimum
+    mcp.MaxNumber(100),    // Optional: maximum
+)
+```
+
+### Boolean Parameter
+
+```go
+mcp.WithBoolean("enabled",
+    mcp.Description("Enable feature"),
+)
+```
+
+### Object Parameter
+
+```go
+mcp.WithObject("config",
+    mcp.Description("Configuration object"),
+    mcp.Properties(map[string]mcp.Property{
+        "timeout": mcp.NewNumberProperty(30),
+        "retries": mcp.NewNumberProperty(3),
+    }),
+)
+```
+
+---
+
+## Result Types
+
+### Text Result
+
+```go
+mcp.NewToolResultText("Operation completed successfully")
+```
+
+### Error Result
+
+```go
+mcp.NewToolResultError("Invalid input: user_id required")
+```
+
+### JSON Result
+
+```go
+mcp.NewToolResultJSON(map[string]interface{}{
+    "user_id": "123",
+    "name": "John",
+    "email": "john@example.com",
+})
+```
+
+---
+
+## MCP Client Integration
+
+AI agents discover and call tools via MCP protocol:
+
+1. **Discovery**: Agent calls `list_tools` to get available tools
+2. **Schema**: Agent receives tool definitions with parameters
+3. **Invocation**: Agent calls `call_tool` with arguments
+4. **Response**: Server returns structured result
+
+### Integration Example
+
+Claude Code MCP client configuration:
+
+```json
+{
+    "mcpServers": {
+        "kratos-mcp": {
+            "url": "http://localhost:8000/mcp"
+        }
+    }
+}
+```
+
+---
+
+## Future Extensions
+
+This reference file can be extended with:
+
+- Plugin system integration
+- Custom transport protocols
+- Service mesh patterns
+- GraphQL gateway
+- Event-driven architecture
+
+Check official Kratos documentation for updates: https://go-kratos.dev