@ai-content-space/loopx 0.2.8 → 0.2.10

package/plugins/loopx/skills/cli-developer/references/ux-patterns.md

@@ -0,0 +1,448 @@
+# CLI UX Patterns
+
+## Progress Indicators
+
+### When to Use What
+
+```
+Determinate (known total):
+  [████████████░░░░░░░░] 60% (3/5 files)
+  Use: File operations, downloads, batch processing
+
+Indeterminate (unknown duration):
+  ⠋ Loading...
+  Use: API calls, database queries, waiting for external services
+
+Multi-step:
+  ✓ Dependencies installed
+  ⠋ Building application...
+  ⏳ Running tests...
+  Use: Multi-phase operations (build, deploy, etc.)
+```
+
+### Progress Bar Best Practices
+
+```
+Good:
+[████████████░░░░░░░░] 60% | 120/200 MB | 2.4 MB/s | ETA: 33s
+↑ Visual     ↑ Percent  ↑ Progress  ↑ Rate     ↑ Time
+
+Components:
+- Visual bar (20-40 chars)
+- Percentage (when known)
+- Current/total (with units)
+- Speed/rate (when applicable)
+- ETA (estimated time remaining)
+
+Bad:
+Processing... (no feedback)
+60% (no context)
+[████████████████████████████████████████] (too wide)
+```
+
+### Spinner Styles
+
+```
+⠋ ⠙ ⠹ ⠸ ⠼ ⠴ ⠦ ⠧ ⠇ ⠏   Dots (elegant, low-key)
+⣾ ⣽ ⣻ ⢿ ⡿ ⣟ ⣯ ⣷        Blocks (bold, attention)
+◐ ◓ ◑ ◒                  Circle (classic)
+▖ ▘ ▝ ▗                  Corners (minimal)
+⠁ ⠂ ⠄ ⡀ ⢀ ⠠ ⠐ ⠈        Line (subtle)
+
+Choose based on:
+- Terminal compatibility (stick to ASCII for Windows)
+- Branding (match your tool's personality)
+- Context (subtle for background, bold for main task)
+```
+
+## Color Usage
+
+### Semantic Colors
+
+```
+Red:     Errors, failures, destructive actions
+Yellow:  Warnings, deprecations, non-critical issues
+Green:   Success, completion, positive feedback
+Blue:    Information, hints, neutral messages
+Cyan:    Commands, code, technical details
+Magenta: Highlights, special items
+Gray:    Less important, metadata, timestamps
+
+Examples:
+✓ Success: Deployment complete
+✗ Error: File not found
+⚠ Warning: Deprecated flag --old-flag
+ℹ Info: Using cache from ~/.mycli/cache
+```
+
+### When to Disable Colors
+
+```javascript
+// Detect non-TTY output (piped to file, etc.)
+const noColor = !process.stdout.isTTY ||
+                process.env.NO_COLOR ||
+                process.env.CI === 'true';
+
+if (noColor) {
+  // Disable colors
+}
+
+// Support NO_COLOR standard
+// https://no-color.org/
+```
+
+### Color Accessibility
+
+```
+- Don't rely on color alone (use symbols too)
+- Provide high contrast (test with various terminals)
+- Support color blindness (red/green alternatives)
+
+Good:
+✓ Build successful (green)
+✗ Build failed (red)
+↑ Symbols work without color
+
+Bad:
+Success (only color, no symbol)
+Failed (only color, no symbol)
+```
+
+## Help Text Design
+
+### Command Help Structure
+
+```
+USAGE
+  mycli <command> [options]
+
+COMMANDS
+  init         Initialize a new project
+  deploy       Deploy to environment
+  config       Manage configuration
+  plugins      Manage plugins
+
+OPTIONS
+  -h, --help     Show help
+  -v, --version  Show version
+  --config FILE  Config file path
+
+Run 'mycli <command> --help' for more information on a command.
+
+EXAMPLES
+  # Initialize a new project
+  mycli init my-app
+
+  # Deploy to production
+  mycli deploy production --dry-run
+
+Learn more: https://docs.mycli.dev
+```
+
+### Subcommand Help
+
+```
+USAGE
+  mycli deploy <environment> [options]
+
+ARGUMENTS
+  environment    Target environment (required)
+                 Values: development, staging, production
+
+OPTIONS
+  -c, --config <file>    Config file path
+                         Default: ./mycli.config.yml
+
+  -f, --force            Skip confirmation prompts
+                         Use with caution in production
+
+  -d, --dry-run          Preview changes without executing
+                         Shows what would happen
+
+  -v, --verbose          Show detailed output
+                         Includes debug information
+
+EXAMPLES
+  # Deploy to production (with confirmation)
+  mycli deploy production
+
+  # Preview staging deployment
+  mycli deploy staging --dry-run
+
+  # Use custom config
+  mycli deploy production --config ./prod.yml
+
+  # Force deploy without prompts
+  mycli deploy production --force
+
+For more information, visit https://docs.mycli.dev/deploy
+```
+
+## Error Messages
+
+### Good Error Messages
+
+```
+Pattern: [Context] → [Problem] → [Solution]
+
+Example 1: File not found
+✗ Error: Config file not found
+
+Searched locations:
+  • ./mycli.config.yml
+  • ~/.config/mycli/config.yml
+  • /etc/mycli/config.yml
+
+Solutions:
+  • Run 'mycli init' to create a config file
+  • Use --config to specify a different location
+  • Check file permissions
+
+Example 2: Validation error
+✗ Error: Invalid environment 'prod'
+
+Expected one of:
+  • development
+  • staging
+  • production
+
+Did you mean 'production'?
+
+Example 3: Permission error
+✗ Error: Permission denied writing to /etc/mycli/config.yml
+
+This operation requires elevated permissions.
+
+Try:
+  • Run with sudo: sudo mycli config set key value
+  • Use user config: mycli config set --user key value
+  • Check file permissions: ls -la /etc/mycli/config.yml
+```
+
+### Error Message Guidelines
+
+```
+DO:
+✓ Be specific ("Port 3000 already in use" not "Port unavailable")
+✓ Show context ("in file config.yml, line 42")
+✓ Suggest solutions ("Try running 'mycli fix'")
+✓ Use plain language ("File not found" not "ENOENT")
+
+DON'T:
+✗ Show stack traces to users (save for --debug)
+✗ Use jargon ("EACCES: permission denied")
+✗ Leave users stuck ("Invalid input" with no explanation)
+✗ Be vague ("Something went wrong")
+```
+
+## Interactive Prompts
+
+### Prompt Types
+
+```
+Text Input:
+  Project name: my-awesome-app
+  ↑ Clear label
+
+Select (Single Choice):
+  ? Select environment: (Use arrow keys)
+  ❯ development
+    staging
+    production
+
+Checkbox (Multiple Choice):
+  ? Select features: (Press space to select, enter to confirm)
+  ◉ TypeScript
+  ◯ ESLint
+  ◉ Prettier
+  ◯ Jest
+
+Confirmation:
+  ? Deploy to production? (y/N)
+  ↑ Default is No (safer)
+
+Password:
+  ? Enter password: ********
+  ↑ Masked input
+```
+
+### Prompt Guidelines
+
+```
+DO:
+✓ Show keyboard hints ("Use arrow keys", "Press space")
+✓ Provide sensible defaults (pre-select common choices)
+✓ Allow skipping with Ctrl+C
+✓ Validate input immediately
+✓ Show preview/summary before final action
+
+DON'T:
+✗ Require interaction in CI/CD environments
+✗ Ask obvious questions (confirm every action)
+✗ Hide what will happen next
+✗ Make users repeat information
+```
+
+## Output Formatting
+
+### Tables
+
+```
+Good:
+┌─────────────┬──────────┬──────────┐
+│ Environment │ Status   │ Updated  │
+├─────────────┼──────────┼──────────┤
+│ production  │ ✓ Active │ 2h ago   │
+│ staging     │ ✓ Active │ 5m ago   │
+│ development │ ✗ Down   │ 1d ago   │
+└─────────────┴──────────┴──────────┘
+
+Minimal (for scripting):
+Environment  Status  Updated
+production   Active  2h ago
+staging      Active  5m ago
+development  Down    1d ago
+
+JSON (for programmatic use):
+[
+  {"env": "production", "status": "active", "updated": "2h ago"},
+  {"env": "staging", "status": "active", "updated": "5m ago"}
+]
+```
+
+### Lists
+
+```
+Bulleted:
+Features:
+  • TypeScript support
+  • Hot reload
+  • Auto-formatting
+
+Numbered:
+Steps to deploy:
+  1. Build application
+  2. Run tests
+  3. Deploy to server
+  4. Verify deployment
+
+Tree:
+my-app/
+├── src/
+│   ├── components/
+│   └── utils/
+├── tests/
+└── package.json
+```
+
+## Status Messages
+
+### Real-time Updates
+
+```
+Multi-step process:
+✓ Dependencies installed (2.3s)
+✓ Application built (8.1s)
+⠋ Running tests... (current)
+⏳ Deploying... (pending)
+⏳ Verifying... (pending)
+
+Updates:
+⠋ Installing dependencies...
+  → npm install
+✓ Dependencies installed (2.3s)
+
+⠋ Building application...
+  → webpack build
+✓ Application built (8.1s)
+  → Output: dist/ (2.4 MB)
+```
+
+### Summary/Completion
+
+```
+✓ Deployment complete!
+
+Summary:
+  Environment:  production
+  Version:      v1.2.3
+  Duration:     2m 34s
+  Deployed:     2023-12-14 10:30:45 UTC
+
+Next steps:
+  • View logs: mycli logs production
+  • Monitor:   mycli status production
+  • Rollback:  mycli rollback production
+
+URL: https://app.example.com
+```
+
+## Debugging & Verbose Mode
+
+```
+Normal mode (default):
+✓ Deployed to production (2m 34s)
+
+Verbose mode (--verbose):
+[10:30:12] Starting deployment...
+[10:30:13] Loading config from ./mycli.config.yml
+[10:30:14] Connecting to production server...
+[10:30:15] Uploading files (124 files, 2.4 MB)...
+[10:30:28] Running post-deploy hooks...
+[10:32:46] ✓ Deployment complete
+
+Debug mode (--debug):
+[DEBUG] Config loaded: {env: 'production', ...}
+[DEBUG] SSH connection established: user@host
+[DEBUG] Executing: rsync -avz ./dist/ user@host:/var/www/
+[DEBUG] Output: sending incremental file list...
+[DEBUG] Exit code: 0
+✓ Deployed to production (2m 34s)
+
+Usage:
+# Normal: concise output
+mycli deploy production
+
+# Verbose: detailed steps
+mycli deploy production --verbose
+
+# Debug: everything including internals
+DEBUG=* mycli deploy production
+```
+
+## Man Page Format
+
+```
+NAME
+    mycli-deploy - Deploy application to environment
+
+SYNOPSIS
+    mycli deploy <environment> [options]
+
+DESCRIPTION
+    Deploy your application to the specified environment.
+    Supports development, staging, and production environments.
+
+OPTIONS
+    -c, --config <file>
+        Path to configuration file
+        Default: ./mycli.config.yml
+
+    -f, --force
+        Skip all confirmation prompts
+        Use with caution in production
+
+    -d, --dry-run
+        Preview deployment without executing
+        Shows what would be deployed
+
+EXAMPLES
+    Deploy to production:
+        mycli deploy production
+
+    Preview staging deployment:
+        mycli deploy staging --dry-run
+
+SEE ALSO
+    mycli-init(1), mycli-config(1), mycli-rollback(1)
+```

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

@@ -3,7 +3,7 @@ name: debug
 description: "Finds root cause for bugs, failing tests, build failures, regressions, and unexpected behavior before fixes. Not for new feature planning or routine code review."
 when_to_use: "debug, bug, test failure, build failure, regression, unexpected behavior, root cause, 报错, 失败, 回归, 排查"
 metadata:
-  version: "0.2.8"
+  version: "0.2.10"
 ---
 
 # Systematic Debugging

package/plugins/loopx/skills/doc-readability/SKILL.md

@@ -3,7 +3,7 @@ name: doc-readability
 description: "Use when evaluating, rewriting, or editing documents for human readability, unclear viewpoints, AI-like prose, bloated specs, PRDs, requirements docs, meeting notes, strategy docs, or internal knowledge-base articles. Not for code review, implementation planning, or file-format conversion."
 when_to_use: "document readability, PRD assessment, requirements gaps, AI-like prose, unclear viewpoint, rewrite docs, editing docs, 文档可读性, 去AI味, 需求文档评估"
 metadata:
-  version: "0.2.8"
+  version: "0.2.10"
 ---
 
 # Doc Readability

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

@@ -3,7 +3,7 @@ name: exec
 description: "Executes a written loopx implementation plan sequentially with review checkpoints. Not for unclear plans, missing requirements, or subagent-first execution."
 when_to_use: "written implementation plan, inline execution, sequential plan execution, review checkpoints, no subagent lane"
 metadata:
-  version: "0.2.8"
+  version: "0.2.10"
 ---
 
 # Exec

package/plugins/loopx/skills/final-review/SKILL.md

@@ -3,7 +3,7 @@ name: final-review
 description: "Performs whole-feature review after implementation and staged task review. Not for per-task review, unresolved scope, implementation, or pure documentation polish."
 when_to_use: "final-review, final code review, whole feature review, integration review, pre-finish review, after subagent-exec, runtime risk review, 最终评审"
 metadata:
-  version: "0.2.8"
+  version: "0.2.10"
 ---
 
 # Final Review

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

@@ -3,7 +3,7 @@ name: finish
 description: "Finishes completed loopx development work after tests pass by presenting merge, PR, keep, or discard options. Not for unfinished work or failing verification."
 when_to_use: "implementation complete, tests pass, finish branch, create pull request, merge locally, keep branch, discard work"
 metadata:
-  version: "0.2.8"
+  version: "0.2.10"
 ---
 
 # Finish

package/plugins/loopx/skills/fix-review/SKILL.md

@@ -3,7 +3,7 @@ name: fix-review
 description: "Handles received code review feedback with verification, technical evaluation, pushback, and one-item-at-a-time fixes. Not for requesting a new review or implementing unrelated changes."
 when_to_use: "fix-review, received code review feedback, review comments, reviewer suggestions, requested changes, 处理评审意见"
 metadata:
-  version: "0.2.8"
+  version: "0.2.10"
 ---
 
 # Fix Review

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

@@ -3,7 +3,7 @@ name: go-style
 description: "Applies loopx Go coding style for .go edits, tests, errors, context, naming, and interface boundaries. Not for non-Go code or Kratos-specific architecture by itself."
 when_to_use: "go-style, Go, golang, .go files, go tests, gofmt, idiomatic Go, Go style, Go 代码"
 metadata:
-  version: "0.2.8"
+  version: "0.2.10"
 ---
 
 # Go Style

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

@@ -3,7 +3,7 @@ name: kratos
 description: "Supports Go-Kratos microservices, proto/buf APIs, service/biz/data layers, middleware, auth, config, and troubleshooting. Not for generic Go style alone."
 when_to_use: "kratos, Go-Kratos, proto, buf, service layer, biz layer, data layer, middleware, auth, config, Kratos 微服务"
 metadata:
-  version: "0.2.8"
+  version: "0.2.10"
 ---
 
 # Kratos
@@ -61,6 +61,7 @@ Use only the reference file needed for the current task:
 - MySQL `CREATE TABLE` statements must include a table-level `COMMENT`.
 - MySQL column definitions in `CREATE TABLE` or `ALTER TABLE ... ADD COLUMN` statements must include column-level `COMMENT`.
 - When using Ent schema for MySQL tables, add `.Comment(...)` to fields that are persisted as columns.
+- Use `sql-style` for broader SQL/database discipline: schema semantics, migrations, indexes, dialect behavior, query plans, and performance-sensitive data access.
 
 ## Integration With Other loopx Skills
 

package/plugins/loopx/skills/plan-to-exec/SKILL.md

@@ -3,7 +3,7 @@ name: plan-to-exec
 description: "Creates bite-sized implementation plans from approved requirements, clarify output, or design specs with exact files, tests, commands, expected output, and execution handoff. Not for unresolved requirements, design decisions, PRD generation, or code changes."
 when_to_use: "plan-to-exec, plan, implementation plan, execution plan, task breakdown, approved requirements, approved design spec, docs/loopx/design, 实施计划, 执行计划, 任务拆分"
 metadata:
-  version: "0.2.8"
+  version: "0.2.10"
 argument-hint: "<design spec path or feature name>"
 ---
 
@@ -21,6 +21,17 @@ Use this skill after requirements are clear. The source may be:
 - `.loopx/intake/clarify-<slug>-<timestamp>.md`
 - an issue, PRD, or requirements document that already fixes material decisions
 
+## Repo Specs And Memory Context
+
+Before using this skill in a repository, inspect loopx long-lived context when it exists:
+
+- If `docs/loopx/specs/` exists, inspect the directory names and filenames. If `docs/loopx/specs/index.md` exists, use it as a map, but do not require it. Read only specs relevant to the requested domain, affected files, workflow behavior, or named source document.
+- If `.loopx/memory/MEMORY.md` exists, read it as curated project memory before deciding what is already known.
+- If `.loopx/memory/index.jsonl` exists, use it only as a retrieval index for relevant active memory cards; do not treat it as an append-only log.
+- Treat current user instructions and the named source document as highest priority, `docs/loopx/specs/` as binding long-lived repo rules, and `.loopx/memory/` as advisory context. Memory is advisory and must not override current task instructions, approved source docs, or repo specs.
+
+Do not read every file under `docs/loopx/specs/` by default. Prefer relevant specs selected by filename, title, frontmatter such as `applies_to`, or the files/domains involved in the task.
+
 Do not re-decide product or architecture. If the source is incomplete, contradictory, or missing product behavior, API, data, state, permission, migration, compatibility, or architecture decisions, return to `clarify` or `spec` instead of filling those gaps inside `plan`.
 
 **Announce at start:** "I'm using the plan-to-exec skill to create the implementation plan."

package/plugins/loopx/skills/refactor-plan/SKILL.md

@@ -3,7 +3,7 @@ name: refactor-plan
 description: "Creates a behavior-preserving refactor plan with user interview, repo evidence, tiny commits, scope boundaries, and testing decisions. Not for feature changes or immediate implementation."
 when_to_use: "refactor-plan, refactor request, refactoring RFC, tiny commits, behavior-preserving cleanup, architecture cleanup, 重构计划"
 metadata:
-  version: "0.2.8"
+  version: "0.2.10"
 ---
 
 This skill will be invoked when the user wants to create a refactor request. You should go through the steps below. You may skip steps if you don't consider them necessary.