universal-dev-standards 4.2.0 → 5.0.0-beta.10

package/bundled/skills/project-discovery/workflow.md

@@ -0,0 +1,566 @@
+# Project Discovery Workflow Guide
+
+> **Language**: English | [繁體中文](../../locales/zh-TW/skills/project-discovery/workflow.md)
+
+**Version**: 1.0.0
+**Last Updated**: 2026-02-09
+
+---
+
+## Overview
+
+This guide provides detailed execution instructions for each step of the Phase 0 Discovery workflow. Use this as a companion to the [Project Discovery SKILL](./SKILL.md).
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                Phase 0: Discovery Pipeline                       │
+│                                                                  │
+│  Input: Existing codebase + proposed feature area               │
+│                                                                  │
+│  ┌──────────┐  ┌──────────┐  ┌──────────┐                      │
+│  │ 0.1 Code │→│ 0.2 Arch │→│ 0.3 Docs │                       │
+│  │  Health   │  │  Review  │  │ Inventory│                       │
+│  └──────────┘  └──────────┘  └──────────┘                      │
+│       │              │              │                             │
+│       ▼              ▼              ▼                             │
+│  ┌──────────┐  ┌──────────┐  ┌──────────┐                      │
+│  │ 0.4 Code │→│ 0.5 Deps │→│ 0.6 Impact│                      │
+│  │  Review   │  │ Security │  │  Scope   │                       │
+│  └──────────┘  └──────────┘  └──────────┘                      │
+│       │              │              │                             │
+│       └──────────────┴──────────────┘                            │
+│                      │                                           │
+│                      ▼                                           │
+│              Discovery Report                                    │
+│          (go / no-go / conditional)                              │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Step 0.1: Code Health Check
+
+### Objective
+
+Establish a quantitative baseline of the codebase's current quality.
+
+### Procedure
+
+#### 0.1.1 Run Test Suite
+
+```bash
+# Example commands (adapt to your project)
+npm test                    # Node.js
+pytest --cov               # Python
+dotnet test                # .NET
+./gradlew test             # Java/Kotlin
+```
+
+Record:
+- Total tests, passed, failed, skipped
+- Coverage percentage (line, branch if available)
+- Execution time
+
+#### 0.1.2 Run Linter
+
+```bash
+# Example commands
+npm run lint               # ESLint
+flake8 .                   # Python
+dotnet format --verify-no-changes  # .NET
+```
+
+Record:
+- Error count
+- Warning count
+- Most frequent rule violations
+
+#### 0.1.3 Identify Code Smells
+
+Look for:
+- Functions exceeding 50 lines
+- Files exceeding 500 lines
+- Nesting depth > 4 levels
+- Duplicated code blocks
+- God classes / modules with too many responsibilities
+
+#### 0.1.4 Check Dead Code
+
+- Unused exports
+- Unreachable code paths
+- Commented-out code blocks
+- Deprecated functions still present
+
+### Output Template
+
+```markdown
+### Step 0.1 Results: Code Health
+
+| Metric | Value | Threshold | Status |
+|--------|-------|-----------|--------|
+| Tests passing | X/Y | 100% | ✅/⚠️/❌ |
+| Test coverage | X% | ≥ 60% | ✅/⚠️/❌ |
+| Lint errors | X | 0 | ✅/⚠️/❌ |
+| Lint warnings | X | < 20 | ✅/⚠️/❌ |
+| Major code smells | X | < 5 | ✅/⚠️/❌ |
+| Dead code files | X | 0 | ✅/⚠️/❌ |
+
+**Health Score**: [Good / Needs Attention / Critical]
+```
+
+### Quality Gate
+
+| Condition | Action |
+|-----------|--------|
+| Test pass rate < 70% | ❌ Flag as high-risk. Recommend fixing tests first. |
+| Coverage < 30% | ⚠️ Recommend adding tests before new features. |
+| Critical lint errors | ⚠️ Address before proceeding. |
+
+### Referenced Standards
+
+- [Testing Standards](../../core/testing-standards.md) — Coverage targets, test pyramid
+- [Reverse Engineering Standards](../../core/reverse-engineering-standards.md) — Code scanning methodology
+
+---
+
+## Step 0.2: Architecture Understanding
+
+### Objective
+
+Map the system's structure, identify patterns, and assess maintainability.
+
+### Procedure
+
+#### 0.2.1 Identify Entry Points
+
+- Main application file (e.g., `index.ts`, `main.py`, `Program.cs`)
+- API route definitions
+- Event handlers / message consumers
+- Scheduled jobs / cron tasks
+- CLI entry points
+
+#### 0.2.2 Map Module Dependencies
+
+Trace the dependency graph:
+```
+entry point → routing → controllers → services → repositories → database
+                                    → external APIs
+                                    → message queues
+```
+
+Look for:
+- Circular dependencies
+- Overly broad imports
+- Tight coupling between unrelated modules
+
+#### 0.2.3 Identify Architectural Pattern
+
+| Pattern | Indicators |
+|---------|-----------|
+| MVC | controllers/, models/, views/ directories |
+| DDD | domain/, application/, infrastructure/ directories |
+| Microservices | Multiple service directories, API gateways |
+| Monolith | Single large application directory |
+| Hexagonal | ports/, adapters/ directories |
+| Event-Driven | Event handlers, message queues, pub/sub |
+
+#### 0.2.4 Assess AI-Friendliness
+
+Check against [AI-Friendly Architecture](../../core/ai-friendly-architecture.md):
+- Clear module boundaries?
+- Discoverable project structure?
+- Consistent naming conventions?
+- Documented interfaces?
+
+### Output Template
+
+```markdown
+### Step 0.2 Results: Architecture
+
+**Identified Pattern**: [Pattern name] [Confirmed/Inferred]
+**Module Count**: X modules across Y packages
+**Entry Points**: [list]
+
+#### Dependency Overview
+[Simplified dependency diagram]
+
+#### Concerns
+- [Confirmed/Inferred] [Description with source: file:line]
+
+#### AI-Friendliness Score
+| Dimension | Rating | Notes |
+|-----------|--------|-------|
+| Discoverability | ✅/⚠️/❌ | ... |
+| Module boundaries | ✅/⚠️/❌ | ... |
+| Naming consistency | ✅/⚠️/❌ | ... |
+| Interface clarity | ✅/⚠️/❌ | ... |
+```
+
+### Quality Gate
+
+| Condition | Action |
+|-----------|--------|
+| No clear module boundaries | ⚠️ Recommend architectural refactoring plan. |
+| Circular dependencies | ⚠️ Document and plan resolution. |
+| Unknown pattern | Flag as [Unknown] — requires stakeholder input. |
+
+### Referenced Standards
+
+- [AI-Friendly Architecture](../../core/ai-friendly-architecture.md)
+- [Reverse Engineering Standards](../../core/reverse-engineering-standards.md)
+
+---
+
+## Step 0.3: Documentation Inventory
+
+### Objective
+
+Assess what documentation exists, its completeness, and freshness.
+
+### Procedure
+
+#### 0.3.1 Check Standard Documents
+
+| Document | Check |
+|----------|-------|
+| README.md | Exists? Setup instructions? Current? |
+| CONTRIBUTING.md | Exists? Covers workflow? |
+| CHANGELOG.md | Exists? Format? Last entry? |
+| LICENSE | Exists? Correct? |
+| API documentation | Exists? Auto-generated? Current? |
+| ADRs (Architecture Decision Records) | Exist? Organized? |
+
+#### 0.3.2 Evaluate Inline Documentation
+
+- Function/method JSDoc/docstrings coverage
+- Module-level documentation
+- Complex algorithm explanations
+- TODO/FIXME/HACK comment count
+
+#### 0.3.3 Assess Documentation Freshness
+
+Compare document dates against recent code changes:
+- If docs haven't been updated in 6+ months but code changed significantly → Stale
+- If docs reference removed features or old APIs → Outdated
+
+### Output Template
+
+```markdown
+### Step 0.3 Results: Documentation
+
+| Document | Exists | Last Updated | Status |
+|----------|--------|-------------|--------|
+| README.md | ✅/❌ | YYYY-MM-DD | ✅ Current / ⚠️ Stale / ❌ Missing |
+| CONTRIBUTING.md | ✅/❌ | ... | ... |
+| CHANGELOG.md | ✅/❌ | ... | ... |
+| API docs | ✅/❌ | ... | ... |
+| ADRs | ✅/❌ | ... | ... |
+| Inline docs | ⚠️ Partial | ... | ... |
+
+**Documentation Score**: [Good / Needs Attention / Critical]
+**TODO/FIXME count**: X
+```
+
+### Quality Gate
+
+| Condition | Action |
+|-----------|--------|
+| No README | ❌ Create README before proceeding. |
+| Docs severely outdated (> 1 year) | ⚠️ Flag as documentation debt. |
+| No CHANGELOG | ⚠️ Recommend adding changelog tracking. |
+
+### Referenced Standards
+
+- [Documentation Structure](../../core/documentation-structure.md)
+- [Changelog Standards](../../core/changelog-standards.md)
+
+---
+
+## Step 0.4: Code Review Snapshot
+
+### Objective
+
+Perform a targeted quality audit of the most critical code paths.
+
+### Procedure
+
+#### 0.4.1 Identify Critical Paths
+
+Select 3-5 paths based on:
+- Business criticality (auth, payments, data access)
+- Complexity (most complex modules)
+- Change frequency (most modified files)
+- Relevance to planned feature work
+
+#### 0.4.2 Apply Code Review Checklist
+
+For each critical path, evaluate:
+
+| Category | Check |
+|----------|-------|
+| Functionality | Does it work correctly? Edge cases handled? |
+| Security | Input validation? SQL injection? XSS? Auth checks? |
+| Error handling | Try/catch? Graceful degradation? Error logging? |
+| Readability | Clear naming? Reasonable function length? |
+| Performance | Obvious bottlenecks? N+1 queries? Memory leaks? |
+
+#### 0.4.3 Apply Anti-Hallucination Labels
+
+**CRITICAL**: Only report what you have actually read.
+
+- `[Confirmed]` — Directly verified in code
+- `[Inferred]` — Logical deduction from patterns
+- `[Unknown]` — Not verified, needs investigation
+
+### Output Template
+
+```markdown
+### Step 0.4 Results: Code Review Snapshot
+
+#### Critical Path 1: [Name]
+[Confirmed] Reviewed: [file list with line ranges]
+
+| Aspect | Rating | Notes |
+|--------|--------|-------|
+| Functionality | ✅/⚠️/❌ | ... |
+| Security | ✅/⚠️/❌ | ... |
+| Error handling | ✅/⚠️/❌ | ... |
+| Readability | ✅/⚠️/❌ | ... |
+| Performance | ✅/⚠️/❌ | ... |
+
+**Findings**: [list with certainty labels]
+```
+
+### Quality Gate
+
+| Condition | Action |
+|-----------|--------|
+| Security vulnerability found | ❌ Must fix before adding features. |
+| Critical error handling gaps | ⚠️ Address before proceeding. |
+
+### Referenced Standards
+
+- [Anti-Hallucination Guidelines](../../core/anti-hallucination.md)
+- [Code Review Checklist](../../core/code-review-checklist.md)
+
+---
+
+## Step 0.5: Dependency & Security Check
+
+### Objective
+
+Identify vulnerable, outdated, or unnecessary dependencies.
+
+### Procedure
+
+#### 0.5.1 Run Security Audit
+
+```bash
+# Node.js
+npm audit
+
+# Python
+pip-audit
+safety check
+
+# .NET
+dotnet list package --vulnerable
+
+# Go
+govulncheck ./...
+```
+
+#### 0.5.2 Check Outdated Packages
+
+```bash
+# Node.js
+npm outdated
+
+# Python
+pip list --outdated
+
+# .NET
+dotnet list package --outdated
+```
+
+#### 0.5.3 Identify Unused Dependencies
+
+```bash
+# Node.js
+npx depcheck
+
+# Python
+pip-extra-reqs --requirements-file=requirements.txt .
+```
+
+#### 0.5.4 Assess License Compliance
+
+Check for incompatible licenses in dependency tree.
+
+### Output Template
+
+```markdown
+### Step 0.5 Results: Dependencies
+
+| Category | Count | Details |
+|----------|-------|---------|
+| Critical vulnerabilities | X | [list CVE IDs] |
+| High vulnerabilities | X | ... |
+| Outdated (major version) | X | ... |
+| Outdated (minor/patch) | X | ... |
+| Unused dependencies | X | [list package names] |
+| License concerns | X | ... |
+
+**Security Score**: [Good / Needs Attention / Critical]
+```
+
+### Quality Gate
+
+| Condition | Action |
+|-----------|--------|
+| Critical CVE | ❌ Must patch before adding features. |
+| > 5 high vulnerabilities | ⚠️ Plan remediation sprint. |
+| Unused dependencies | ℹ️ Clean up to reduce attack surface. |
+
+### Referenced Standards
+
+- [Security Standards](../../core/security-standards.md)
+- [Check-in Standards](../../core/checkin-standards.md)
+
+---
+
+## Step 0.6: Impact Scope Analysis
+
+### Objective
+
+Map how the proposed changes would propagate through the system and assess risk.
+
+### Procedure
+
+#### 0.6.1 Define Change Target
+
+Clearly state:
+- What feature area will be modified?
+- What modules will be directly touched?
+- What is the expected change type (add, modify, refactor)?
+
+#### 0.6.2 Trace Dependencies
+
+For each directly modified module:
+1. List modules that import/depend on it
+2. List modules it imports/depends on
+3. Count total affected modules (direct + transitive)
+
+#### 0.6.3 Build Risk Matrix
+
+| Risk | Likelihood | Impact | Mitigation |
+|------|-----------|--------|------------|
+| [Description] | Low/Med/High | Low/Med/High/Critical | [Action] |
+
+Likelihood factors:
+- Code complexity of affected area
+- Test coverage of affected area
+- Number of modules touched
+
+Impact factors:
+- Business criticality of affected functionality
+- User-facing vs. internal
+- Data integrity implications
+
+#### 0.6.4 Determine Verdict
+
+| Blast Radius | Recommendation |
+|-------------|----------------|
+| < 10% of modules | ✅ GO — Low risk, proceed normally |
+| 10-30% of modules | ⚠️ CONDITIONAL — Add integration tests first |
+| > 30% of modules | ❌ NO-GO — Break into smaller changes |
+
+### Output Template
+
+```markdown
+### Step 0.6 Results: Impact Scope
+
+**Change Target**: [Feature/module name]
+**Blast Radius**: X modules directly, Y transitively (Z% of total)
+
+#### Risk Matrix
+
+| Risk | Likelihood | Impact | Mitigation |
+|------|-----------|--------|------------|
+| ... | ... | ... | ... |
+
+**Verdict**: [GO / CONDITIONAL / NO-GO]
+**Rationale**: [1-2 sentences]
+```
+
+### Referenced Standards
+
+- [Requirement Engineering](../../core/requirement-engineering.md)
+
+---
+
+## Synthesizing the Discovery Report
+
+After completing all 6 steps, combine findings into a single report.
+
+### Report Structure
+
+```markdown
+# Discovery Report: [Project Name]
+
+**Date**: YYYY-MM-DD
+**Assessed by**: [AI assistant / Developer name]
+**Scope**: [Feature area or full project]
+
+## Executive Summary
+[2-3 sentences: overall health, key risks, recommendation]
+
+## Verdict: [GO / NO-GO / CONDITIONAL]
+
+## Scores Summary
+
+| Area | Score | Critical Issues |
+|------|-------|----------------|
+| Code Health (0.1) | ✅/⚠️/❌ | X |
+| Architecture (0.2) | ✅/⚠️/❌ | X |
+| Documentation (0.3) | ✅/⚠️/❌ | X |
+| Code Quality (0.4) | ✅/⚠️/❌ | X |
+| Dependencies (0.5) | ✅/⚠️/❌ | X |
+| Impact Scope (0.6) | ✅/⚠️/❌ | X |
+
+## Blockers
+[List any items that must be resolved before proceeding]
+
+## Recommendations
+[Ordered by priority]
+
+## Next Steps
+- [ ] Address blockers
+- [ ] /reverse — if legacy code needs SDD specs
+- [ ] /sdd — write specifications for new features
+- [ ] Begin implementation
+```
+
+### Verdict Decision Matrix
+
+| Blockers | High Risks | Verdict |
+|----------|-----------|---------|
+| 0 | 0-2 | ✅ GO |
+| 0 | 3+ | ⚠️ CONDITIONAL — address risks first |
+| 1+ | Any | ❌ NO-GO — resolve blockers |
+
+---
+
+## Version History
+
+| Version | Date | Changes |
+|---------|------|---------|
+| 1.0.0 | 2026-02-09 | Initial release |
+
+---
+
+## License
+
+This guide is released under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).
+
+**Source**: [universal-dev-standards](https://github.com/AsiaOstrich/universal-dev-standards)

package/bundled/skills/{claude-code/project-structure-guide → project-structure-guide}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: project-structure-guide
+scope: universal
 description: |
   Guide for organizing project directories following language-specific best practices.
   Use when: creating projects, reorganizing structure, adding modules, setting up builds.
@@ -8,7 +8,7 @@ description: |
 
 # Project Structure Guide
 
-> **Language**: English | [繁體中文](../../../locales/zh-TW/skills/claude-code/project-structure-guide/SKILL.md)
+> **Language**: English | [繁體中文](../../locales/zh-TW/skills/project-structure-guide/SKILL.md)
 
 **Version**: 1.0.0
 **Last Updated**: 2025-12-30
@@ -20,6 +20,16 @@ description: |
 
 This skill provides guidance on structuring projects according to language and framework conventions. It helps create consistent, maintainable directory layouts.
 
+# [Physical Binding]
+## Reality Check
+Before confirming the project structure is valid, you MUST:
+1. Run the validator: `uds check --standard project-structure`
+2. IF exit_code != 0:
+   - Read the error message (e.g., "Missing required directories").
+   - Report the violation to the user.
+   - Suggest specific commands (`mkdir ...`) to fix it.
+   - RETRY validation after fixes are applied.
+
 ## Trigger
 
 Use this skill when:
@@ -139,5 +149,5 @@ When reviewing existing structure:
 
 ## Related Standards
 
-- [Core: Project Structure](../../../core/project-structure.md)
-- [AI: Project Structure Options](../../../ai/options/project-structure/)
+- [Core: Project Structure](../../core/project-structure.md)
+- [AI: Project Structure Options](../../ai/options/project-structure/)

package/bundled/skills/refactoring-assistant/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: refactor
+scope: universal
+description: "[UDS] Guide refactoring decisions and strategy selection"
+allowed-tools: Read, Write, Grep, Glob, Bash(npm test:*), Bash(npx:*)
+argument-hint: "[file or module | 檔案或模組]"
+---
+
+# Refactoring Assistant | 重構助手
+
+Guide refactoring decisions, recommend strategies, and provide step-by-step execution workflows.
+
+引導重構決策、推薦策略，並提供逐步執行工作流程。
+
+## Usage | 使用方式
+
+| Command | Purpose | 用途 |
+|---------|---------|------|
+| `/refactor` | Start interactive refactoring guide | 啟動互動式重構引導 |
+| `/refactor decide` | Run refactor vs. rewrite decision tree | 執行重構 vs 重寫決策樹 |
+| `/refactor tactical` | Suggest tactical (daily) strategies | 建議戰術性（日常）策略 |
+| `/refactor strategic` | Guide strategic/architectural refactoring | 引導戰略性/架構重構 |
+| `/refactor legacy` | Legacy code safety strategies | 遺留程式碼安全策略 |
+| `/refactor debt` | Technical debt assessment | 技術債評估 |
+
+## Strategy Quick Reference | 策略快速參考
+
+### Tactical Strategies (Daily) | 戰術性策略
+
+| Strategy | When to Use | 使用時機 |
+|----------|-------------|---------|
+| **Preparatory Refactoring** | Before adding a blocked feature | 新增被阻擋的功能之前 |
+| **Boy Scout Rule** | During any maintenance work | 任何維護工作中 |
+| **Red-Green-Refactor** | TDD development cycle | TDD 開發循環 |
+
+### Strategic Strategies (Architectural) | 戰略性策略
+
+| Strategy | When to Use | 使用時機 |
+|----------|-------------|---------|
+| **Strangler Fig** | Replacing entire system gradually | 逐步替換整個系統 |
+| **Anti-Corruption Layer** | Integrating with legacy system | 與遺留系統整合 |
+| **Branch by Abstraction** | Shared code refactoring on trunk | 在主幹上重構共享程式碼 |
+
+### Safety Strategies (Legacy) | 安全防護策略
+
+| Strategy | When to Use | 使用時機 |
+|----------|-------------|---------|
+| **Characterization Tests** | Before any legacy refactoring | 任何遺留程式碼重構之前 |
+| **Scratch Refactoring** | Understanding black-box code | 理解黑盒程式碼 |
+| **Finding Seams** | Injecting test doubles into legacy | 在遺留程式碼中注入測試替身 |
+
+## Workflow | 工作流程
+
+1. **Assess** - Identify code to refactor, evaluate test coverage
+2. **Decide** - Run decision tree (refactor vs. rewrite) if needed
+3. **Select strategy** - Choose appropriate strategy based on scope and risk
+4. **Execute** - Follow step-by-step workflow with safety checks
+5. **Verify** - Run tests to confirm behavior is preserved
+
+## Usage Examples | 使用範例
+
+```
+User: /refactor src/legacy-auth/
+AI: Analyzing src/legacy-auth/...
+    Test coverage: 23% — recommending safety-first approach.
+    Suggested strategy: Characterization Tests + Preparatory Refactoring
+```
+
+```
+User: /refactor decide
+AI: Let me help you decide whether to refactor or rewrite.
+    Question 1: Is the code currently working in production? [Y/N]
+```
+
+## Reference | 參考
+
+- Detailed guide: [guide.md](./guide.md)
+- Core standard: [refactoring-standards.md](../../core/refactoring-standards.md)