@heyai-rules/pilo-masterkit 1.2.2

package/.agent/workflows/go-test.md

@@ -0,0 +1,268 @@
+---
+description: Enforce TDD workflow for Go. Write table-driven tests first, then implement. Verify 80%+ coverage with go test -cover.
+---
+
+# Go TDD Command
+
+This command enforces test-driven development methodology for Go code using idiomatic Go testing patterns.
+
+## What This Command Does
+
+1. **Define Types/Interfaces**: Scaffold function signatures first
+2. **Write Table-Driven Tests**: Create comprehensive test cases (RED)
+3. **Run Tests**: Verify tests fail for the right reason
+4. **Implement Code**: Write minimal code to pass (GREEN)
+5. **Refactor**: Improve while keeping tests green
+6. **Check Coverage**: Ensure 80%+ coverage
+
+## When to Use
+
+Use `/go-test` when:
+- Implementing new Go functions
+- Adding test coverage to existing code
+- Fixing bugs (write failing test first)
+- Building critical business logic
+- Learning TDD workflow in Go
+
+## TDD Cycle
+
+```
+RED     → Write failing table-driven test
+GREEN   → Implement minimal code to pass
+REFACTOR → Improve code, tests stay green
+REPEAT  → Next test case
+```
+
+## Example Session
+
+````
+User: /go-test I need a function to validate email addresses
+
+Agent:
+# TDD Session: Email Validator
+
+## Step 1: Define Interface
+
+```go
+// validator/email.go
+package validator
+
+// ValidateEmail checks if the given string is a valid email address.
+// Returns nil if valid, error describing the issue otherwise.
+func ValidateEmail(email string) error {
+    panic("not implemented")
+}
+```
+
+## Step 2: Write Table-Driven Tests (RED)
+
+```go
+// validator/email_test.go
+package validator
+
+import (
+    "testing"
+)
+
+func TestValidateEmail(t *testing.T) {
+    tests := []struct {
+        name    string
+        email   string
+        wantErr bool
+    }{
+        // Valid emails
+        {"simple email", "user@example.com", false},
+        {"with subdomain", "user@mail.example.com", false},
+        {"with plus", "user+tag@example.com", false},
+        {"with dots", "first.last@example.com", false},
+
+        // Invalid emails
+        {"empty string", "", true},
+        {"no at sign", "userexample.com", true},
+        {"no domain", "user@", true},
+        {"no local part", "@example.com", true},
+        {"double at", "user@@example.com", true},
+        {"spaces", "user @example.com", true},
+        {"no tld", "user@example", true},
+    }
+
+    for _, tt := range tests {
+        t.Run(tt.name, func(t *testing.T) {
+            err := ValidateEmail(tt.email)
+            if tt.wantErr && err == nil {
+                t.Errorf("ValidateEmail(%q) = nil; want error", tt.email)
+            }
+            if !tt.wantErr && err != nil {
+                t.Errorf("ValidateEmail(%q) = %v; want nil", tt.email, err)
+            }
+        })
+    }
+}
+```
+
+## Step 3: Run Tests - Verify FAIL
+
+```bash
+$ go test ./validator/...
+
+--- FAIL: TestValidateEmail (0.00s)
+    --- FAIL: TestValidateEmail/simple_email (0.00s)
+        panic: not implemented
+
+FAIL
+```
+
+✓ Tests fail as expected (panic).
+
+## Step 4: Implement Minimal Code (GREEN)
+
+```go
+// validator/email.go
+package validator
+
+import (
+    "errors"
+    "regexp"
+)
+
+var emailRegex = regexp.MustCompile(`^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$`)
+
+var (
+    ErrEmailEmpty   = errors.New("email cannot be empty")
+    ErrEmailInvalid = errors.New("email format is invalid")
+)
+
+func ValidateEmail(email string) error {
+    if email == "" {
+        return ErrEmailEmpty
+    }
+    if !emailRegex.MatchString(email) {
+        return ErrEmailInvalid
+    }
+    return nil
+}
+```
+
+## Step 5: Run Tests - Verify PASS
+
+```bash
+$ go test ./validator/...
+
+PASS
+ok      project/validator    0.003s
+```
+
+✓ All tests passing!
+
+## Step 6: Check Coverage
+
+```bash
+$ go test -cover ./validator/...
+
+PASS
+coverage: 100.0% of statements
+ok      project/validator    0.003s
+```
+
+✓ Coverage: 100%
+
+## TDD Complete!
+````
+
+## Test Patterns
+
+### Table-Driven Tests
+```go
+tests := []struct {
+    name     string
+    input    InputType
+    want     OutputType
+    wantErr  bool
+}{
+    {"case 1", input1, want1, false},
+    {"case 2", input2, want2, true},
+}
+
+for _, tt := range tests {
+    t.Run(tt.name, func(t *testing.T) {
+        got, err := Function(tt.input)
+        // assertions
+    })
+}
+```
+
+### Parallel Tests
+```go
+for _, tt := range tests {
+    tt := tt // Capture
+    t.Run(tt.name, func(t *testing.T) {
+        t.Parallel()
+        // test body
+    })
+}
+```
+
+### Test Helpers
+```go
+func setupTestDB(t *testing.T) *sql.DB {
+    t.Helper()
+    db := createDB()
+    t.Cleanup(func() { db.Close() })
+    return db
+}
+```
+
+## Coverage Commands
+
+```bash
+# Basic coverage
+go test -cover ./...
+
+# Coverage profile
+go test -coverprofile=coverage.out ./...
+
+# View in browser
+go tool cover -html=coverage.out
+
+# Coverage by function
+go tool cover -func=coverage.out
+
+# With race detection
+go test -race -cover ./...
+```
+
+## Coverage Targets
+
+| Code Type | Target |
+|-----------|--------|
+| Critical business logic | 100% |
+| Public APIs | 90%+ |
+| General code | 80%+ |
+| Generated code | Exclude |
+
+## TDD Best Practices
+
+**DO:**
+- Write test FIRST, before any implementation
+- Run tests after each change
+- Use table-driven tests for comprehensive coverage
+- Test behavior, not implementation details
+- Include edge cases (empty, nil, max values)
+
+**DON'T:**
+- Write implementation before tests
+- Skip the RED phase
+- Test private functions directly
+- Use `time.Sleep` in tests
+- Ignore flaky tests
+
+## Related Commands
+
+- `/go-build` - Fix build errors
+- `/go-review` - Review code after implementation
+- `/verify` - Run full verification loop
+
+## Related
+
+- Skill: `skills/golang-testing/`
+- Skill: `skills/tdd-workflow/`

package/.agent/workflows/gradle-build.md

@@ -0,0 +1,70 @@
+---
+description: Fix Gradle build errors for Android and KMP projects
+---
+
+# Gradle Build Fix
+
+Incrementally fix Gradle build and compilation errors for Android and Kotlin Multiplatform projects.
+
+## Step 1: Detect Build Configuration
+
+Identify the project type and run the appropriate build:
+
+| Indicator | Build Command |
+|-----------|---------------|
+| `build.gradle.kts` + `composeApp/` (KMP) | `./gradlew composeApp:compileKotlinMetadata 2>&1` |
+| `build.gradle.kts` + `app/` (Android) | `./gradlew app:compileDebugKotlin 2>&1` |
+| `settings.gradle.kts` with modules | `./gradlew assemble 2>&1` |
+| Detekt configured | `./gradlew detekt 2>&1` |
+
+Also check `gradle.properties` and `local.properties` for configuration.
+
+## Step 2: Parse and Group Errors
+
+1. Run the build command and capture output
+2. Separate Kotlin compilation errors from Gradle configuration errors
+3. Group by module and file path
+4. Sort: configuration errors first, then compilation errors by dependency order
+
+## Step 3: Fix Loop
+
+For each error:
+
+1. **Read the file** — Full context around the error line
+2. **Diagnose** — Common categories:
+   - Missing import or unresolved reference
+   - Type mismatch or incompatible types
+   - Missing dependency in `build.gradle.kts`
+   - Expect/actual mismatch (KMP)
+   - Compose compiler error
+3. **Fix minimally** — Smallest change that resolves the error
+4. **Re-run build** — Verify fix and check for new errors
+5. **Continue** — Move to next error
+
+## Step 4: Guardrails
+
+Stop and ask the user if:
+- Fix introduces more errors than it resolves
+- Same error persists after 3 attempts
+- Error requires adding new dependencies or changing module structure
+- Gradle sync itself fails (configuration-phase error)
+- Error is in generated code (Room, SQLDelight, KSP)
+
+## Step 5: Summary
+
+Report:
+- Errors fixed (module, file, description)
+- Errors remaining
+- New errors introduced (should be zero)
+- Suggested next steps
+
+## Common Gradle/KMP Fixes
+
+| Error | Fix |
+|-------|-----|
+| Unresolved reference in `commonMain` | Check if the dependency is in `commonMain.dependencies {}` |
+| Expect declaration without actual | Add `actual` implementation in each platform source set |
+| Compose compiler version mismatch | Align Kotlin and Compose compiler versions in `libs.versions.toml` |
+| Duplicate class | Check for conflicting dependencies with `./gradlew dependencies` |
+| KSP error | Run `./gradlew kspCommonMainKotlinMetadata` to regenerate |
+| Configuration cache issue | Check for non-serializable task inputs |

package/.agent/workflows/harness-audit.md

@@ -0,0 +1,71 @@
+# Harness Audit Command
+
+Run a deterministic repository harness audit and return a prioritized scorecard.
+
+## Usage
+
+`/harness-audit [scope] [--format text|json]`
+
+- `scope` (optional): `repo` (default), `hooks`, `skills`, `commands`, `agents`
+- `--format`: output style (`text` default, `json` for automation)
+
+## Deterministic Engine
+
+Always run:
+
+```bash
+node scripts/harness-audit.js <scope> --format <text|json>
+```
+
+This script is the source of truth for scoring and checks. Do not invent additional dimensions or ad-hoc points.
+
+Rubric version: `2026-03-16`.
+
+The script computes 7 fixed categories (`0-10` normalized each):
+
+1. Tool Coverage
+2. Context Efficiency
+3. Quality Gates
+4. Memory Persistence
+5. Eval Coverage
+6. Security Guardrails
+7. Cost Efficiency
+
+Scores are derived from explicit file/rule checks and are reproducible for the same commit.
+
+## Output Contract
+
+Return:
+
+1. `overall_score` out of `max_score` (70 for `repo`; smaller for scoped audits)
+2. Category scores and concrete findings
+3. Failed checks with exact file paths
+4. Top 3 actions from the deterministic output (`top_actions`)
+5. Suggested ECC skills to apply next
+
+## Checklist
+
+- Use script output directly; do not rescore manually.
+- If `--format json` is requested, return the script JSON unchanged.
+- If text is requested, summarize failing checks and top actions.
+- Include exact file paths from `checks[]` and `top_actions[]`.
+
+## Example Result
+
+```text
+Harness Audit (repo): 66/70
+- Tool Coverage: 10/10 (10/10 pts)
+- Context Efficiency: 9/10 (9/10 pts)
+- Quality Gates: 10/10 (10/10 pts)
+
+Top 3 Actions:
+1) [Security Guardrails] Add prompt/tool preflight security guards in hooks/hooks.json. (hooks/hooks.json)
+2) [Tool Coverage] Sync commands/harness-audit.md and .opencode/commands/harness-audit.md. (.opencode/commands/harness-audit.md)
+3) [Eval Coverage] Increase automated test coverage across scripts/hooks/lib. (tests/)
+```
+
+## Arguments
+
+$ARGUMENTS:
+- `repo|hooks|skills|commands|agents` (optional scope)
+- `--format text|json` (optional output format)

package/.agent/workflows/init-docs.md

@@ -0,0 +1,46 @@
+---
+description: Tự động khởi tạo cấu trúc thư mục tài liệu cho dự án Pilo Masterkit.
+---
+
+# Workflow: Khởi tạo Thư mục Tài liệu (Documentation Init)
+
+Quy trình này tự động tạo các thư mục cần thiết để quản lý tài liệu, báo cáo và nhiệm vụ theo chuẩn Pilo Masterkit.
+
+## Các bước thực hiện:
+
+1. **Kiểm tra và Tạo Thư mục**:
+   Tạo thư mục `docs/` ở thư mục gốc của dự án (nếu chưa có), sau đó tạo 8 thư mục con bên trong `docs/`:
+   - `docs/lessons/`: Lưu trữ bài học kinh nghiệm.
+   - `docs/reports/`: Lưu trữ báo cáo tiến độ và audit.
+   - `docs/plans/`: Lưu trữ kế hoạch triển khai.
+   - `docs/status/`: Lưu trữ trạng thái dự án.
+   - `docs/tasks/`: Lưu trữ danh sách nhiệm vụ chi tiết.
+   - `docs/logs/`: Lưu trữ nhật ký hoạt động của Agent.
+   - `docs/walkthroughs/`: Lưu trữ hướng dẫn thực hiện.
+   - `docs/producs/`: Lưu trữ đặc tả sản phẩm (specs, PRD).
+
+2. **Khởi tạo File mẫu (Tùy chọn)**:
+   Trong mỗi thư mục, tạo một file `README.md` ngắn gọn mô tả mục đích của thư mục đó.
+
+## Lệnh thực thi (Dành cho Agent):
+
+// turbo
+```pwsh
+$docsDir = "docs"
+if (-not (Test-Path $docsDir)) {
+    New-Item -ItemType Directory -Path $docsDir -Force
+    Write-Host "Created base directory: $docsDir"
+}
+
+$dirs = @("lessons", "reports", "plans", "status", "tasks", "logs", "walkthroughs", "producs")
+foreach ($dir in $dirs) {
+    $targetPath = Join-Path $docsDir $dir
+    if (-not (Test-Path $targetPath)) {
+        New-Item -ItemType Directory -Path $targetPath -Force
+        Write-Host "Created directory: $targetPath"
+    }
+}
+```
+
+## Báo cáo kết quả:
+Sau khi hoàn thành, báo cáo danh sách các thư mục đã được khởi tạo thành công.

package/.agent/workflows/instinct-export.md

@@ -0,0 +1,66 @@
+---
+name: instinct-export
+description: Export instincts from project/global scope to a file
+command: /instinct-export
+---
+
+# Instinct Export Command
+
+Exports instincts to a shareable format. Perfect for:
+- Sharing with teammates
+- Transferring to a new machine
+- Contributing to project conventions
+
+## Usage
+
+```
+/instinct-export                           # Export all personal instincts
+/instinct-export --domain testing          # Export only testing instincts
+/instinct-export --min-confidence 0.7      # Only export high-confidence instincts
+/instinct-export --output team-instincts.yaml
+/instinct-export --scope project --output project-instincts.yaml
+```
+
+## What to Do
+
+1. Detect current project context
+2. Load instincts by selected scope:
+   - `project`: current project only
+   - `global`: global only
+   - `all`: project + global merged (default)
+3. Apply filters (`--domain`, `--min-confidence`)
+4. Write YAML-style export to file (or stdout if no output path provided)
+
+## Output Format
+
+Creates a YAML file:
+
+```yaml
+# Instincts Export
+# Generated: 2025-01-22
+# Source: personal
+# Count: 12 instincts
+
+---
+id: prefer-functional-style
+trigger: "when writing new functions"
+confidence: 0.8
+domain: code-style
+source: session-observation
+scope: project
+project_id: a1b2c3d4e5f6
+project_name: my-app
+---
+
+# Prefer Functional Style
+
+## Action
+Use functional patterns over classes.
+```
+
+## Flags
+
+- `--domain <name>`: Export only specified domain
+- `--min-confidence <n>`: Minimum confidence threshold
+- `--output <file>`: Output file path (prints to stdout when omitted)
+- `--scope <project|global|all>`: Export scope (default: `all`)

package/.agent/workflows/instinct-import.md

@@ -0,0 +1,114 @@
+---
+name: instinct-import
+description: Import instincts from file or URL into project/global scope
+command: true
+---
+
+# Instinct Import Command
+
+## Implementation
+
+Run the instinct CLI using the plugin root path:
+
+```bash
+python3 "${CLAUDE_PLUGIN_ROOT}/skills/continuous-learning-v2/scripts/instinct-cli.py" import <file-or-url> [--dry-run] [--force] [--min-confidence 0.7] [--scope project|global]
+```
+
+Or if `CLAUDE_PLUGIN_ROOT` is not set (manual installation):
+
+```bash
+python3 ~/.claude/skills/continuous-learning-v2/scripts/instinct-cli.py import <file-or-url>
+```
+
+Import instincts from local file paths or HTTP(S) URLs.
+
+## Usage
+
+```
+/instinct-import team-instincts.yaml
+/instinct-import https://github.com/org/repo/instincts.yaml
+/instinct-import team-instincts.yaml --dry-run
+/instinct-import team-instincts.yaml --scope global --force
+```
+
+## What to Do
+
+1. Fetch the instinct file (local path or URL)
+2. Parse and validate the format
+3. Check for duplicates with existing instincts
+4. Merge or add new instincts
+5. Save to inherited instincts directory:
+   - Project scope: `~/.claude/homunculus/projects/<project-id>/instincts/inherited/`
+   - Global scope: `~/.claude/homunculus/instincts/inherited/`
+
+## Import Process
+
+```
+📥 Importing instincts from: team-instincts.yaml
+================================================
+
+Found 12 instincts to import.
+
+Analyzing conflicts...
+
+## New Instincts (8)
+These will be added:
+  ✓ use-zod-validation (confidence: 0.7)
+  ✓ prefer-named-exports (confidence: 0.65)
+  ✓ test-async-functions (confidence: 0.8)
+  ...
+
+## Duplicate Instincts (3)
+Already have similar instincts:
+  ⚠️ prefer-functional-style
+     Local: 0.8 confidence, 12 observations
+     Import: 0.7 confidence
+     → Keep local (higher confidence)
+
+  ⚠️ test-first-workflow
+     Local: 0.75 confidence
+     Import: 0.9 confidence
+     → Update to import (higher confidence)
+
+Import 8 new, update 1?
+```
+
+## Merge Behavior
+
+When importing an instinct with an existing ID:
+- Higher-confidence import becomes an update candidate
+- Equal/lower-confidence import is skipped
+- User confirms unless `--force` is used
+
+## Source Tracking
+
+Imported instincts are marked with:
+```yaml
+source: inherited
+scope: project
+imported_from: "team-instincts.yaml"
+project_id: "a1b2c3d4e5f6"
+project_name: "my-project"
+```
+
+## Flags
+
+- `--dry-run`: Preview without importing
+- `--force`: Skip confirmation prompt
+- `--min-confidence <n>`: Only import instincts above threshold
+- `--scope <project|global>`: Select target scope (default: `project`)
+
+## Output
+
+After import:
+```
+✅ Import complete!
+
+Added: 8 instincts
+Updated: 1 instinct
+Skipped: 3 instincts (equal/higher confidence already exists)
+
+New instincts saved to: ~/.claude/homunculus/instincts/inherited/
+
+Run /instinct-status to see all instincts.
+```

package/.agent/workflows/instinct-status.md

@@ -0,0 +1,59 @@
+---
+name: instinct-status
+description: Show learned instincts (project + global) with confidence
+command: true
+---
+
+# Instinct Status Command
+
+Shows learned instincts for the current project plus global instincts, grouped by domain.
+
+## Implementation
+
+Run the instinct CLI using the plugin root path:
+
+```bash
+python3 "${CLAUDE_PLUGIN_ROOT}/skills/continuous-learning-v2/scripts/instinct-cli.py" status
+```
+
+Or if `CLAUDE_PLUGIN_ROOT` is not set (manual installation), use:
+
+```bash
+python3 ~/.claude/skills/continuous-learning-v2/scripts/instinct-cli.py status
+```
+
+## Usage
+
+```
+/instinct-status
+```
+
+## What to Do
+
+1. Detect current project context (git remote/path hash)
+2. Read project instincts from `~/.claude/homunculus/projects/<project-id>/instincts/`
+3. Read global instincts from `~/.claude/homunculus/instincts/`
+4. Merge with precedence rules (project overrides global when IDs collide)
+5. Display grouped by domain with confidence bars and observation stats
+
+## Output Format
+
+```
+============================================================
+  INSTINCT STATUS - 12 total
+============================================================
+
+  Project: my-app (a1b2c3d4e5f6)
+  Project instincts: 8
+  Global instincts:  4
+
+## PROJECT-SCOPED (my-app)
+  ### WORKFLOW (3)
+    ███████░░░  70%  grep-before-edit [project]
+              trigger: when modifying code
+
+## GLOBAL (apply to all projects)
+  ### SECURITY (2)
+    █████████░  85%  validate-user-input [global]
+              trigger: when handling user input
+```