@ai-content-space/loopx 0.2.9 → 0.2.10

package/skills/architecture-designer/references/nfr-checklist.md

@@ -0,0 +1,212 @@
+# Non-Functional Requirements Checklist
+
+## NFR Categories
+
+### Scalability
+
+| Question | Common Targets | How to Measure |
+|----------|----------------|----------------|
+| Expected concurrent users? | 100 / 1K / 10K / 100K | Load test with realistic user sessions |
+| Requests per second? | 10 / 100 / 1000 / 10000 | Throughput benchmark under load |
+| Data volume? | GB / TB / PB | Current size + growth projection |
+| Growth rate? | 10% / 50% / 100% per year | Historical data or business forecast |
+| Peak vs average load? | 2x / 5x / 10x | Traffic analysis over time windows |
+
+**Quantified Example**:
+> The system must handle 5,000 concurrent WebSocket connections with < 100ms message delivery p95. During daily peak (09:00-11:00 UTC), traffic reaches 8x the off-peak average. The system must auto-scale within 60 seconds when QPS exceeds 2,000.
+
+### Performance
+
+| Question | Common Targets | How to Measure |
+|----------|----------------|----------------|
+| API response time? | < 100ms / 200ms / 500ms p95 | APM percentile tracking |
+| Page load time? | < 1s / 2s / 3s | Lighthouse, Core Web Vitals |
+| Database query time? | < 10ms / 50ms / 100ms | Slow query log, EXPLAIN ANALYZE |
+| Batch processing throughput? | 1K / 10K / 100K records/hour | Job completion time tracking |
+| Cold start time? | < 500ms / 1s / 3s | First-request latency after deploy |
+
+**Quantified Example**:
+> API endpoints must respond within 200ms at p95 and 500ms at p99 under normal load (< 1000 QPS). Search queries over datasets > 1M rows must complete within 1s at p95. Background job processing must sustain 50K events/hour with < 5 minute end-to-end latency.
+
+### Availability
+
+| Target | Downtime/Year | Use Case | Error Budget/Month |
+|--------|---------------|----------|-------------------|
+| 99% | 3.65 days | Internal tools | 7.3 hours |
+| 99.9% | 8.76 hours | Business apps | 43.8 minutes |
+| 99.95% | 4.38 hours | E-commerce | 21.9 minutes |
+| 99.99% | 52.6 minutes | Financial systems | 4.38 minutes |
+| 99.999% | 5.26 minutes | Life-critical | 26.3 seconds |
+
+**Quantified Example**:
+> The payment processing service requires 99.95% availability measured monthly. Planned maintenance windows (max 2 hours/month, announced 72h in advance) are excluded. Degraded mode (read-only, cached responses) is acceptable for up to 15 minutes before counting as downtime.
+
+### Security
+
+| Question | Considerations | Verification |
+|----------|----------------|--------------|
+| Authentication required? | JWT, OAuth, SAML, MFA | Penetration testing, auth bypass tests |
+| Authorization model? | RBAC, ABAC, ACL | Permission matrix review |
+| Data sensitivity? | Public, internal, confidential, PII | Data classification audit |
+| Compliance requirements? | GDPR, HIPAA, PCI DSS, SOC 2 | Compliance audit checklist |
+| Encryption needs? | At rest, in transit, end-to-end | Certificate and key rotation policy |
+| Secret management? | Vault, KMS, env vars | Secret scanning in CI |
+
+**Quantified Example**:
+> All PII must be encrypted at rest (AES-256) and in transit (TLS 1.3). Authentication tokens expire in 15 minutes with refresh tokens valid for 7 days. Failed login attempts are rate-limited to 5 per minute per IP. All admin actions require MFA. Secrets must rotate every 90 days.
+
+### Reliability
+
+| Question | Considerations | Verification |
+|----------|----------------|--------------|
+| Acceptable data loss? | RPO: 0 / 1hr / 24hr | Backup restore drill |
+| Recovery time target? | RTO: 1hr / 4hr / 24hr | Disaster recovery exercise |
+| Backup frequency? | Real-time / hourly / daily | Backup monitoring alerts |
+| Disaster recovery? | Single region / multi-region | Failover test |
+| Data integrity? | Checksums, reconciliation | Periodic data validation jobs |
+
+**Quantified Example**:
+> RPO: 1 hour (max 1 hour of data loss acceptable). RTO: 30 minutes (service must recover within 30 minutes). Automated daily backups with 30-day retention. Cross-region backup replication with 6-hour lag tolerance. Monthly disaster recovery drill required.
+
+### Maintainability
+
+| Question | Considerations | Verification |
+|----------|----------------|--------------|
+| Deployment frequency? | Daily / weekly / monthly | Deployment metrics |
+| Deployment strategy? | Blue-green, canary, rolling | Rollback success rate |
+| Monitoring requirements? | Logs, metrics, traces, alerts | Observability coverage audit |
+| On-call requirements? | 24/7, business hours | Incident response SLA |
+| Code health? | Test coverage, tech debt ratio | SonarQube or equivalent |
+
+**Quantified Example**:
+> Deploy to production at least twice per week with < 5 minute rollback capability. Zero-downtime deployments required. Alert on: error rate > 1%, p95 latency > 500ms, CPU > 80% for 5 minutes. On-call rotation with 15-minute acknowledgment SLA during business hours, 30-minute outside.
+
+### Cost
+
+| Question | Considerations | Verification |
+|----------|----------------|--------------|
+| Infrastructure budget? | $/month, $/user, $/request | Monthly cost reports |
+| Operational budget? | FTE for maintenance | Team capacity planning |
+| Cost per transaction? | Target unit economics | Cost attribution per service |
+| Cost optimization? | Reserved instances, spot, autoscaling | Monthly optimization review |
+| Cost alerts? | Thresholds for notification | Budget alerts in cloud console |
+
+**Quantified Example**:
+> Infrastructure cost must stay below $0.001 per API request at 1M requests/day. Total monthly cloud spend must not exceed $15K for the first year. Auto-scaling must scale down within 10 minutes when load drops below 30% capacity to avoid waste.
+
+## NFR Priority Framework
+
+Not all NFRs are equally important. Use this framework to prioritize.
+
+### Priority Matrix
+
+| Priority | Meaning | Action |
+|----------|---------|--------|
+| **P0 - Must Have** | System is unusable without this | Design for it from day 1 |
+| **P1 - Should Have** | Significant user/business impact | Plan in architecture, may defer implementation |
+| **P2 - Nice to Have** | Improves experience but not critical | Design to not preclude, implement later |
+| **P3 - Future** | Anticipated need, not current | Document for future, avoid painting into corner |
+
+### Common Priority Conflicts
+
+| Conflict | Trade-off | Decision Driver |
+|----------|-----------|-----------------|
+| Performance vs Cost | Faster = more expensive infra | Unit economics, user tolerance |
+| Availability vs Consistency | Higher availability often means eventual consistency | Data correctness requirements |
+| Security vs UX | Stricter auth = more friction | Risk profile, compliance needs |
+| Scalability vs Simplicity | Scale-ready = more complexity | Growth timeline, team size |
+| Maintainability vs Time-to-Market | Clean code takes longer | Technical debt budget |
+
+### Decision Template
+
+When two NFRs conflict, document the trade-off:
+
+```markdown
+## NFR Trade-off: {NFR A} vs {NFR B}
+
+**Context**: [Why they conflict in this system]
+**Decision**: Prioritize {NFR A} because [reason]
+**Consequence**: {NFR B} will be limited to [specific bound]
+**Mitigation**: [How we partially address the deprioritized NFR]
+**Revisit When**: [Trigger for re-evaluating this trade-off]
+```
+
+## NFR Elicitation Questions
+
+Use these when stakeholders haven't specified NFRs.
+
+### For Product Owners
+
+1. What happens to revenue if the system is down for 1 hour? 1 day?
+2. How many users do you expect in 6 months? 2 years?
+3. Which markets/regions must we serve? (latency, compliance implications)
+4. What is the acceptable delay for data to appear after submission?
+5. Are there regulatory requirements we must meet?
+
+### For Engineering Teams
+
+1. What is our current deployment frequency? Target?
+2. What is our error budget? How much have we consumed?
+3. What is the most expensive query/operation today?
+4. What broke last quarter? What would have prevented it?
+5. Where does the on-call team spend the most time?
+
+### For Security/Compliance
+
+1. What data classification applies to our user data?
+2. Which compliance frameworks must we satisfy?
+3. What is our threat model? Who are we defending against?
+4. What is our incident response time target?
+5. How often must secrets/certificates rotate?
+
+## Template
+
+```markdown
+## Non-Functional Requirements
+
+### Performance
+- API response time: < 200ms p95, < 500ms p99
+- Page load time: < 2s (LCP)
+- Database query time: < 50ms p95
+- Background job latency: < 5 min end-to-end
+
+### Scalability
+- Concurrent users: 10,000
+- Requests per second: 1,000 (peak: 5,000)
+- Data volume: 1TB (growing 50%/year)
+- Auto-scale trigger: CPU > 70% for 2 minutes
+
+### Availability
+- Target: 99.9% (43.8 min downtime/month)
+- RPO: 1 hour
+- RTO: 30 minutes
+- Degraded mode: read-only acceptable for 15 min
+
+### Security
+- Authentication: JWT (15 min) + refresh token (7 days)
+- Authorization: RBAC with tenant isolation
+- Encryption: AES-256 at rest, TLS 1.3 in transit
+- Compliance: GDPR, SOC 2
+
+### Observability
+- Logging: Structured JSON, 30-day retention
+- Metrics: Prometheus + Grafana, 1-year retention
+- Tracing: OpenTelemetry, 7-day retention
+- Alerts: PagerDuty, 15-min ack SLA
+
+### Cost
+- Monthly budget: $15K infrastructure
+- Target unit cost: < $0.001 per request
+- Optimization: Reserved instances for baseline, spot for burst
+```
+
+## Quick Reference
+
+| Category | Key Metric | Typical Range |
+|----------|------------|---------------|
+| Performance | Response time (p95) | 100ms - 500ms |
+| Scalability | Concurrent users, RPS | 1K - 100K |
+| Availability | Uptime percentage | 99% - 99.99% |
+| Reliability | RPO, RTO | Minutes - Hours |
+| Security | Compliance requirements | GDPR, SOC2, PCI |
+| Cost | $/month budget | Based on unit economics |

package/skills/architecture-designer/references/system-design.md

@@ -0,0 +1,313 @@
+# System Design Template
+
+## Design Document Structure
+
+```markdown
+# System: {System Name}
+
+## Requirements
+
+### Functional
+- [What the system must do]
+- [Core features and capabilities]
+
+### Non-Functional
+- **Performance**: Response time < 200ms p95
+- **Availability**: 99.9% uptime (8.76 hours downtime/year)
+- **Scalability**: Support 10,000 concurrent users
+- **Security**: PCI DSS compliance required
+
+### Constraints
+- Budget: $X/month for infrastructure
+- Timeline: MVP in 3 months
+- Team: 5 backend, 3 frontend engineers
+
+## High-Level Architecture
+
+[Component diagram with technology choices]
+
+## Component Details
+
+[Per-component: technology, responsibilities, scaling strategy]
+
+## Key Decisions
+
+[Decision table with rationale]
+
+## Scaling Strategy
+
+[Current → 10x → 100x growth plan]
+
+## Security Considerations
+
+[Auth, encryption, compliance, rate limiting]
+
+## Failure Modes
+
+[Failure scenarios with impact and mitigation]
+```
+
+## Capacity Estimation
+
+### Back-of-Envelope Framework
+
+Before selecting technology or sizing infrastructure, estimate the system's load profile.
+
+#### Step 1: Identify Load Drivers
+
+| Driver | Question | Example |
+|--------|----------|---------|
+| Users | DAU / MAU? | 100K DAU |
+| Actions | Actions per user per day? | 10 reads, 2 writes |
+| Data | Bytes per action? | 1KB per read, 5KB per write |
+| Growth | Monthly growth rate? | 15% |
+
+#### Step 2: Calculate Throughput
+
+```
+Read QPS  = DAU × reads_per_user / seconds_per_day
+          = 100,000 × 10 / 86,400
+          ≈ 12 QPS (average)
+
+Write QPS = DAU × writes_per_user / seconds_per_day
+          = 100,000 × 2 / 86,400
+          ≈ 2.3 QPS (average)
+
+Peak QPS  = average × peak_factor (typically 3x-10x)
+          ≈ 12 × 5 = 60 QPS (peak reads)
+```
+
+#### Step 3: Calculate Storage
+
+```
+Daily new data   = DAU × writes_per_user × bytes_per_write
+                 = 100,000 × 2 × 5KB = 1GB/day
+
+Annual storage   = daily × 365 × replication_factor
+                 = 1GB × 365 × 3 = ~1TB/year
+
+With indexes     = storage × 1.3 (30% index overhead)
+                 ≈ 1.3TB/year
+```
+
+#### Step 4: Calculate Bandwidth
+
+```
+Ingress = write_QPS × avg_request_size
+        = 2.3 × 5KB ≈ 12KB/s
+
+Egress  = read_QPS × avg_response_size
+        = 12 × 10KB ≈ 120KB/s (average)
+        = 60 × 10KB ≈ 600KB/s (peak)
+```
+
+#### Step 5: Calculate Memory (Cache)
+
+```
+Cache size = hot_data_percentage × total_data
+           = 20% × 365GB (one year) ≈ 73GB
+
+Or by QPS: cache_entries = peak_QPS × avg_response_time × response_size
+           = 60 × 0.2s × 10KB ≈ 120KB active working set
+```
+
+### Estimation Quick Reference
+
+| Scale | DAU | QPS (avg) | Storage/year | Typical Architecture |
+|-------|-----|-----------|--------------|---------------------|
+| Small | 1K | < 1 | < 10GB | Single server |
+| Medium | 100K | 10-100 | 100GB-1TB | Load balancer + replicas |
+| Large | 10M | 1K-10K | 10TB-100TB | Microservices + sharding |
+| Massive | 1B | 100K+ | PB+ | Global distribution |
+
+### Common Capacity Numbers
+
+| Resource | Typical Limit | Planning Target |
+|----------|--------------|-----------------|
+| Single PostgreSQL | 10K QPS | 5K QPS (headroom) |
+| Single Redis | 100K QPS | 50K QPS |
+| Single API server | 1K-5K req/s | 1K req/s (with business logic) |
+| Network (1Gbps) | 125MB/s | 80MB/s |
+| SSD IOPS | 50K-100K | 30K |
+
+## Load / Store / Compute Analysis
+
+Decompose system load into three dimensions to identify bottlenecks.
+
+### Load (Ingress)
+
+| Question | Analysis |
+|----------|----------|
+| What enters the system? | Requests, events, uploads, streams |
+| What rate? | QPS, messages/sec, bytes/sec |
+| What pattern? | Steady, bursty, time-of-day, seasonal |
+| What size? | Request payload sizes, batch sizes |
+| What validation? | Schema validation, auth, rate limits |
+
+### Store (Persistence)
+
+| Question | Analysis |
+|----------|----------|
+| What must be durable? | Transactions, events, documents, blobs |
+| What access pattern? | Random read, sequential scan, time-range |
+| What consistency? | Strong, eventual, causal, read-your-writes |
+| What retention? | Forever, TTL, tiered (hot/warm/cold) |
+| What growth rate? | Linear, exponential, bounded |
+
+### Compute (Processing)
+
+| Question | Analysis |
+|----------|----------|
+| What transforms data? | Business logic, aggregation, ML inference |
+| What latency budget? | Sync (< 200ms), async (seconds-minutes), batch (hours) |
+| What parallelism? | Independent per request, fan-out/fan-in, pipeline |
+| What failure mode? | Retry, skip, dead-letter, compensate |
+| What cost driver? | CPU, memory, GPU, external API calls |
+
+### Bottleneck Identification
+
+```
+For each dimension, ask:
+  1. What is the current capacity?
+  2. What is the current utilization?
+  3. At what growth rate does it saturate?
+  4. What is the scaling mechanism? (vertical, horizontal, architectural change)
+  5. What is the cost curve? (linear, superlinear, cliff)
+```
+
+## Caching Strategy Selection
+
+### Cache Decision Framework
+
+```
+Should I cache this?
+  1. Is it read more than written? (read:write > 3:1) → Yes
+  2. Is it expensive to compute/fetch? (> 50ms) → Yes
+  3. Can I tolerate stale data? → If no, consider write-through or skip cache
+  4. Is the data set bounded? → If no, need eviction strategy
+```
+
+### Cache Patterns
+
+| Pattern | How It Works | Best For | Risk |
+|---------|-------------|----------|------|
+| **Cache-Aside** | App reads cache, on miss reads DB and fills cache | General purpose | Cache stampede on cold start |
+| **Read-Through** | Cache reads from DB on miss transparently | Simplify app logic | Cache becomes critical path |
+| **Write-Through** | Write to cache and DB synchronously | Strong consistency | Write latency increase |
+| **Write-Behind** | Write to cache, async flush to DB | Write-heavy workloads | Data loss on cache failure |
+| **Refresh-Ahead** | Proactively refresh before TTL expires | Predictable hot keys | Wasted refreshes for cold keys |
+
+### Cache-Aside (Most Common)
+
+```
+Read:
+  1. Check cache → hit → return
+  2. Miss → read DB → write to cache → return
+
+Write:
+  1. Write DB
+  2. Invalidate cache (don't update — avoids race conditions)
+```
+
+### Cache Invalidation Strategies
+
+| Strategy | Consistency | Complexity | Use When |
+|----------|-------------|------------|----------|
+| TTL-based | Eventual (bounded staleness) | Low | Staleness within TTL is acceptable |
+| Event-driven invalidation | Near real-time | Medium | Write events are available |
+| Write-through | Strong | Medium | Cannot tolerate stale reads |
+| Versioned keys | Strong for specific version | Low | Immutable data with version |
+
+### Multi-Layer Caching
+
+```
+┌─────────┐     ┌──────────┐     ┌─────────┐     ┌──────────┐
+│ Browser │────▶│   CDN    │────▶│App Cache│────▶│ Database │
+│  Cache  │     │  (edge)  │     │ (Redis) │     │          │
+└─────────┘     └──────────┘     └─────────┘     └──────────┘
+  seconds         minutes          seconds         source
+  per-user        per-region       per-app         of truth
+```
+
+| Layer | TTL | Scope | Invalidation |
+|-------|-----|-------|-------------|
+| Browser | 60s-1h | Per user | Cache-Control headers |
+| CDN | 5m-24h | Per region | Purge API or TTL |
+| Application (Redis) | 1m-1h | Per app cluster | Event-driven or TTL |
+| Database query cache | Automatic | Per instance | On table mutation |
+
+### Cache Sizing
+
+```
+Working set = unique_keys × avg_value_size × overhead_factor
+
+Example:
+  1M users × 2KB avg profile × 1.5 overhead = 3GB
+  → Fits in a single Redis instance (recommend 8GB for headroom)
+```
+
+### Anti-Patterns
+
+| Anti-Pattern | Problem | Fix |
+|---|---|---|
+| Cache everything | Memory waste, cold start storms | Cache only hot, expensive, read-heavy data |
+| No TTL | Stale data forever | Always set TTL, even if long |
+| Update cache on write | Race condition between concurrent writes | Invalidate on write, let next read fill |
+| Unbounded cache | OOM | Set max memory + eviction policy |
+| Cache as primary store | Data loss on eviction/restart | Cache is acceleration, DB is truth |
+
+## Architecture Diagram Template
+
+Use Mermaid for component, sequence, and deployment diagrams.
+
+### Component Diagram
+
+```mermaid
+graph TD
+    Client[Client App] --> LB[Load Balancer]
+    LB --> API[API Service]
+    API --> Auth[Auth Service]
+    API --> Cache[(Redis)]
+    API --> DB[(PostgreSQL)]
+    API --> Queue[Message Queue]
+    Queue --> Worker[Background Worker]
+    Worker --> DB
+    Worker --> External[External APIs]
+```
+
+### Deployment Diagram
+
+```mermaid
+graph TD
+    subgraph Region A
+        LB_A[Load Balancer]
+        subgraph AZ-1
+            API_1[API x2]
+            Worker_1[Worker x1]
+        end
+        subgraph AZ-2
+            API_2[API x2]
+            Worker_2[Worker x1]
+        end
+        DB_Primary[(DB Primary)]
+        DB_Replica[(DB Replica)]
+        Redis_A[(Redis Cluster)]
+    end
+    LB_A --> API_1
+    LB_A --> API_2
+    API_1 --> DB_Primary
+    API_2 --> DB_Primary
+    DB_Primary --> DB_Replica
+```
+
+## Quick Reference
+
+| Section | Key Questions |
+|---------|---------------|
+| Requirements | What must it do? How well? |
+| Capacity | How much load? How much data? How fast is it growing? |
+| Architecture | What components? How connected? |
+| Caching | What is hot? What tolerance for stale? |
+| Decisions | Why these choices? What was rejected? |
+| Scaling | How to grow 10x? Where is the bottleneck? |
+| Failures | What can break? How to recover? What is the blast radius? |

package/skills/clarify/SKILL.md

@@ -3,7 +3,7 @@ name: clarify
 description: "Grills ambiguous loopx work until material questions are answered, then routes to spec or plan using a design gate. Not for clear implementation tasks, approved specs, or code changes."
 when_to_use: "clarify, requirements, ambiguous request, unclear scope, non-goals, decision boundaries, acceptance criteria, 需求澄清, 范围不清"
 metadata:
-  version: "0.2.9"
+  version: "0.2.10"
 ---
 
 # loopx Clarify

package/skills/cli-developer/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: cli-developer
+description: "Applies loopx CLI design discipline for commands, flags, human and JSON output, errors, interactivity, help text, shell behavior, and cross-platform UX. Not for replacing clarify, spec, implementation planning, code review, or workflow state transitions."
+when_to_use: "cli-developer, CLI, command design, flags, JSON output, stdout stderr, interactive prompt, help text, shell completion, 命令行"
+license: MIT
+metadata:
+  version: "0.2.10"
+  forked_from: https://github.com/Jeffallan/claude-skills/tree/main/skills/cli-developer
+  maintained_by: loopx
+---
+
+# CLI Developer
+
+## loopx Boundary
+
+`cli-developer` is a support lens, not a workflow state. Use it directly when the user asks for CLI design or implementation guidance, and use it from `spec`, `exec`, `review`, or `final-review` when changes affect command behavior.
+
+This skill does not replace `clarify`, `spec`, `plan-to-exec`, `review`, or `final-review`. If product behavior, compatibility, migration, or public CLI contract decisions are unclear, route those decisions through `clarify` or `spec`.
+
+For loopx itself, preserve the established rule that human output is default for first-use commands and complete runtime payloads require explicit `--json`.
+
+## Purpose
+
+Use this skill to design, implement, or review command-line behavior: command hierarchy, flags, arguments, help text, output contracts, errors, prompts, progress indicators, shell completions, terminal behavior, startup cost, and cross-platform UX.
+
+It applies to Node.js, Python, Go, and other CLI stacks, but defer to the repository's existing framework and command conventions before introducing new dependencies.
+
+## Core Workflow
+
+1. **Analyze UX** — Identify the user workflows, command hierarchy, common tasks, automation paths, and first-use onboarding path.
+2. **Design commands** — Plan subcommands, flags, positional arguments, configuration sources, environment variables, and compatibility with existing command signatures.
+3. **Specify output contracts** — Decide which output is human-facing, which output is machine-readable, and how `--json`, stdout, stderr, and exit codes behave.
+4. **Implement** — Use the project's established CLI framework. After wiring commands, run representative `<cli> --help`, `<cli> --version`, success, validation-error, and non-interactive invocations.
+5. **Polish shell behavior** — Review color, TTY detection, SIGINT handling, prompt fallbacks, progress indicators, and shell completion support where the command is public or repeated-use.
+6. **Verify** — Run the relevant test suite and smoke tests on command behavior. Measure startup time against project-specific expectations when startup cost matters.
+
+## Reference Guide
+
+Load detailed guidance based on context:
+
+| Topic | Reference | Load When |
+|-------|-----------|-----------|
+| Design Patterns | `references/design-patterns.md` | Subcommands, flags, config, architecture |
+| Node.js CLIs | `references/node-cli.md` | commander, yargs, inquirer, chalk |
+| Python CLIs | `references/python-cli.md` | click, typer, argparse, rich |
+| Go CLIs | `references/go-cli.md` | cobra, viper, bubbletea |
+| UX Patterns | `references/ux-patterns.md` | Progress bars, colors, prompts, help text |
+
+## Command And Flag Discipline
+
+- Preserve existing command signatures unless a breaking change is explicitly approved and documented.
+- Prefer stable subcommands and explicit flags over mode inference that is hard to script.
+- Keep flag names consistent with existing project vocabulary and common CLI conventions.
+- Support `--help`; support `--version` for installable public CLIs or when the project already exposes it.
+- Validate user input early and return actionable errors with a non-zero exit code.
+- Treat command names, flags, positional arguments, JSON fields, and exit codes as public API once users can script against them.
+- Document deprecated flags before removing them when compatibility matters.
+
+## Output Discipline
+
+- Human output is the default for exploratory, onboarding, and first-use commands.
+- Complete runtime payloads, state snapshots, and automation-friendly output require explicit `--json`.
+- Keep stdout for requested command results. Send diagnostics, warnings, progress, logs, and prompts to stderr.
+- Do not mix spinner/progress text into stdout when stdout may be piped or parsed.
+- Use stable JSON schemas for `--json` output. Avoid prose in JSON fields that callers need to branch on.
+- Include enough structured error data in JSON mode for automation to handle failures.
+- Keep human error messages concise, specific, and action-oriented.
+
+## Interactivity And CI Discipline
+
+- Do not require interactive input in CI or non-TTY contexts.
+- Provide flags, environment variables, config files, or documented defaults for non-interactive operation.
+- Detect TTY before enabling prompts, colors, alternate screens, spinners, or progress bars.
+- When prompting, show the exact consequence of destructive or compatibility-sensitive choices.
+- Respect common non-interactive signals such as `CI=1`, piped stdin/stdout, and explicit `--yes`, `--no-input`, or equivalent project conventions.
+- Handle SIGINT gracefully: stop active work when possible, clean up partial local state when required, and exit with a clear message.
+
+## Installer And Onboarding Discipline
+
+- First-run commands should be readable without `--json` and should not require users to know internal workflow state.
+- Installer and postinstall flows must be non-interactive-safe unless the package manager or platform explicitly permits prompts.
+- Avoid writing generated runtime state into the repository unless the command explicitly operates on repo-managed artifacts.
+- For loopx plugin or skill installation flows, preserve mirror expectations and avoid overwriting user-edited installed copies outside the current repository.
+- Keep help text and error text compatible with common terminals and package manager logs.
+
+## Shell And Cross-Platform Discipline
+
+- Use platform-neutral path APIs. Do not hardcode `/`, `~`, drive letters, or shell-specific quoting.
+- Avoid assuming Bash. Consider zsh, fish, PowerShell, and cmd.exe when commands are public or documented for users.
+- Quote shell examples so paths with spaces work.
+- Detect color support and avoid color in non-TTY output unless the project supports explicit color forcing.
+- Normalize line endings and path display carefully when output may be compared in tests.
+- Provide shell completions for public, repeated-use CLIs when the framework and distribution path make them maintainable. Do not require completions for every internal or one-off CLI.
+
+## Performance Discipline
+
+- Keep startup work proportional to the command. Avoid loading large modules, reading network resources, or scanning large trees before argument parsing when not needed.
+- Measure startup time against project-specific expectations before claiming a performance target.
+- Prefer lazy loading for expensive subcommand-only dependencies.
+- Stream large inputs and outputs instead of buffering unnecessarily.
+
+## Review Checklist
+
+- Is the command hierarchy understandable from `--help`?
+- Are flags, arguments, environment variables, and config precedence explicit?
+- Are stdout and stderr separated correctly for piping and automation?
+- Does `--json` return complete, stable, machine-readable payloads without human-only text?
+- Does the command work in non-interactive CI and non-TTY contexts?
+- Are prompts, colors, spinners, and progress indicators gated by terminal capability?
+- Are errors actionable and backed by appropriate exit codes?
+- Are public command signatures and JSON schemas backward-compatible or intentionally migrated?
+- Are startup costs measured when startup time matters?
+- Are shell examples and path handling cross-platform?
+
+## Output Checklist
+
+When delivering CLI design or implementation guidance, provide:
+
+1. Command structure: entry point, subcommands, arguments, and flags
+2. Output contract: human output, `--json` shape, stdout/stderr behavior, and exit codes
+3. Configuration handling: config files, env vars, flags, and precedence
+4. Interactivity rules: prompts, CI behavior, defaults, and TTY behavior
+5. Shell behavior: help text, completions when applicable, colors, paths, and signal handling
+6. Verification commands: help/version smoke tests, success/error invocations, JSON-mode checks, and project tests