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

package/bundled/skills/INTEGRATION-GUIDE.md

@@ -0,0 +1,210 @@
+# Skills Integration Guide
+
+This guide explains how to use multiple skills together in development workflows.
+
+## Overview
+
+Universal Development Standards provides 14 Claude Code skills that work together to support the full development lifecycle:
+
+```
+Planning → Coding → Testing → Review → Commit → Release
+    │         │         │        │        │        │
+    ▼         ▼         ▼        ▼        ▼        ▼
+Requirement  Project   Testing  Code   Commit  Release
+Assistant   Structure   Guide  Review Standards Standards
+```
+
+## Skill Interaction Matrix
+
+| From Skill → | To Skill | Interaction |
+|--------------|----------|-------------|
+| Requirement Assistant | All | Requirements inform all decisions |
+| Project Structure | Testing Guide | Test location follows structure |
+| Testing Guide | Code Review | Review checks test coverage |
+| Code Review | Commit Standards | Review approval enables commit |
+| Commit Standards | Release Standards | Commits determine version |
+| Git Workflow | All | Branch strategy affects all |
+
+## Workflow Scenarios
+
+### Scenario 1: New Feature Development
+
+```mermaid
+graph LR
+    A[Requirement] --> B[Project Structure]
+    B --> C[Write Code]
+    C --> D[Testing Guide]
+    D --> E[Code Review]
+    E --> F[Commit Standards]
+    F --> G[Git Workflow]
+```
+
+**Skills Used**:
+1. **Requirement Assistant** - Clarify feature requirements
+2. **Project Structure** - Determine where to add files
+3. **Testing Guide** - Write tests for new feature
+4. **Code Review** - Get code reviewed
+5. **Commit Standards** - Write proper commit message
+6. **Git Workflow** - Merge via correct branch strategy
+
+### Scenario 2: Bug Fix
+
+```mermaid
+graph LR
+    A[Identify Bug] --> B[Write Test]
+    B --> C[Fix Code]
+    C --> D[Review]
+    D --> E[Commit]
+```
+
+**Skills Used**:
+1. **Testing Guide** - Write failing test first
+2. **Code Review** - Quick review of fix
+3. **Commit Standards** - Use `fix:` type
+4. **Git Workflow** - Create `fix/` branch
+
+### Scenario 3: Release Preparation
+
+```mermaid
+graph LR
+    A[Aggregate Changes] --> B[Update Version]
+    B --> C[Update Changelog]
+    C --> D[Create Tag]
+    D --> E[Release]
+```
+
+**Skills Used**:
+1. **Commit Standards** - Review commit history
+2. **Release Standards** - Determine version bump
+3. **Documentation Guide** - Update changelog
+4. **Git Workflow** - Tag and release
+
+## Skill Priority Resolution
+
+When multiple skills apply, use this priority:
+
+| Priority | Category | Skills |
+|----------|----------|--------|
+| 1 | Security | AI Collaboration (anti-hallucination) |
+| 2 | Correctness | Testing Guide, Code Review |
+| 3 | Process | Git Workflow, Commit Standards |
+| 4 | Documentation | Documentation Guide, Release Standards |
+| 5 | Guidance | Requirement Assistant, Project Structure |
+
+## Common Skill Combinations
+
+### Code Quality Combo
+
+Use together for high-quality code:
+- **Testing Guide** + **Code Review**
+- Ensures tests exist AND code is reviewed
+
+### Release Combo
+
+Use together for proper releases:
+- **Commit Standards** + **Release Standards** + **Git Workflow**
+- Ensures proper versioning and changelog
+
+### New Project Combo
+
+Use together when starting projects:
+- **Project Structure** + **Documentation Guide** + **Git Workflow**
+- Sets up proper foundation
+
+## Conflict Resolution
+
+### Testing vs Speed
+
+**Conflict**: Need to ship fast but testing guide requires coverage
+
+**Resolution**:
+1. Write critical path tests (Testing Guide)
+2. Document technical debt (Documentation Guide)
+3. Use appropriate commit type (Commit Standards)
+
+### Review vs Urgency
+
+**Conflict**: Critical fix needs immediate deployment
+
+**Resolution**:
+1. Use expedited review (Code Review - emergency process)
+2. Create hotfix branch (Git Workflow)
+3. Document exception (Documentation Guide)
+
+## Skill Triggers by Activity
+
+| Activity | Primary Skill | Supporting Skills |
+|----------|---------------|-------------------|
+| Start new project | Project Structure | Git Workflow, Documentation |
+| Add feature | Requirement Assistant | Testing, Code Review |
+| Fix bug | Testing Guide | Code Review, Commit |
+| Write tests | Testing Guide | Code Review |
+| Code review | Code Review | Testing, AI Collaboration |
+| Commit code | Commit Standards | Git Workflow |
+| Create PR | Git Workflow | Code Review, Documentation |
+| Release | Release Standards | Git Workflow, Documentation |
+| Write docs | Documentation Guide | - |
+
+## Best Practices
+
+### 1. Start with Requirements
+
+Always begin with clear requirements before other skills:
+```
+User Story → Acceptance Criteria → Implementation → Test → Review
+```
+
+### 2. Test Early
+
+Invoke Testing Guide before code review:
+```
+Write Code → Write Tests → Self Review → Request Review
+```
+
+### 3. Consistent Commits
+
+Use Commit Standards throughout, not just at the end:
+```
+Each logical change = One commit with proper format
+```
+
+### 4. Document Decisions
+
+Use Documentation Guide to record important decisions:
+```
+Decision Made → Document in ADR → Reference in Code
+```
+
+## Quick Reference
+
+### Daily Development
+
+| Task | Skill |
+|------|-------|
+| Start coding | Project Structure |
+| Write tests | Testing Guide |
+| Review code | Code Review |
+| Commit changes | Commit Standards |
+| Push to remote | Git Workflow |
+
+### Weekly/Sprint Tasks
+
+| Task | Skill |
+|------|-------|
+| Plan features | Requirement Assistant |
+| Review progress | Code Review |
+| Update docs | Documentation Guide |
+
+### Release Tasks
+
+| Task | Skill |
+|------|-------|
+| Determine version | Release Standards |
+| Update changelog | Release Standards |
+| Create release | Git Workflow |
+
+## Version History
+
+| Version | Date | Changes |
+|---------|------|---------|
+| 1.0.0 | 2025-12-30 | Initial integration guide |

package/bundled/skills/README.md

@@ -0,0 +1,95 @@
+# Universal Development Skills
+
+This directory contains the reference implementations of Universal Development Standards (UDS) skills. These skills are designed to be tool-agnostic where possible, serving as the "Source of Truth" for AI coding assistants.
+
+> Derived from [universal-dev-standards](https://github.com/AsiaOstrich/universal-dev-standards) core standards.
+
+## Directory Structure
+
+```
+skills/
+├── commands/          # Universal Slash Command definitions (.md)
+├── agents/            # Universal Agent definitions (.md)
+├── workflows/         # Universal Workflow definitions (.yaml)
+├── tools/             # Tool-specific adapters and configs
+│   ├── cline/         # Cline (.clinerules)
+│   ├── cursor/        # Cursor (.cursorrules)
+│   ├── windsurf/      # Windsurf (.windsurfrules)
+│   └── copilot/       # GitHub Copilot (instructions.md)
+├── _shared/           # Shared templates and utilities
+└── [skill-name]/      # Individual skill definitions (e.g., git-workflow-guide/)
+```
+
+## Universal Skills & Commands
+
+These skills provide standard guidance and workflows. They can be accessed via slash commands in supporting tools (like Claude Code, OpenCode) or referenced manually.
+
+| Skill (Folder) | Command | Description |
+|----------------|---------|-------------|
+| `guide` | `/guide` | [UDS] Access all standard guides |
+| `checkin-assistant` | `/checkin` | [UDS] Pre-commit quality gates |
+| `commit-standards` | `/commit` | [UDS] Conventional Commits format |
+| `code-review-assistant` | `/review` | [UDS] Systematic code review |
+| `tdd-assistant` | `/tdd` | [UDS] Test-Driven Development |
+| `bdd-assistant` | `/bdd` | [UDS] Behavior-Driven Development |
+| `atdd-assistant` | `/atdd` | [UDS] Acceptance Test-Driven Development |
+| `release-standards` | `/release` | [UDS] Release & Changelog management |
+| `documentation-guide` | `/docs` | [UDS] Documentation management |
+| `requirement-assistant` | `/requirement` | [UDS] Requirement writing |
+| `reverse-engineer` | `/reverse` | [UDS] Reverse engineer code |
+| `forward-derivation` | `/derive` | [UDS] Derive artifacts from spec |
+| `spec-driven-dev` | `/sdd` | [UDS] Spec-Driven Development |
+| `test-coverage-assistant` | `/coverage` | [UDS] Test coverage analysis |
+| `methodology-system` | `/methodology` | [UDS] Development methodology |
+| `refactoring-assistant` | `/refactor` | [UDS] Refactoring guidance |
+| `project-discovery` | `/discover` | [UDS] Assess project health and risks |
+| `changelog-guide` | `/changelog` | [UDS] Generate changelog entries |
+| `docs-generator` | `/docgen` | [UDS] Generate usage documentation |
+
+> **Note**: For reference guides (e.g., Git Workflow, Logging, Error Codes), use the `/guide` command.
+
+## Tool Adapters
+
+Specific configurations for various AI tools are located in `skills/tools/`.
+
+### Claude Code / OpenCode
+The files in the root of `skills/` (commands, agents, workflows) are directly compatible with Claude Code and OpenCode.
+
+**Installation (Plugin Marketplace):**
+```bash
+/plugin marketplace add AsiaOstrich/universal-dev-standards
+/plugin install universal-dev-standards@asia-ostrich
+```
+
+### Cursor
+Located in `skills/tools/cursor/`.
+```bash
+cp skills/tools/cursor/.cursorrules .cursorrules
+```
+
+### Windsurf
+Located in `skills/tools/windsurf/`.
+```bash
+cp skills/tools/windsurf/.windsurfrules .windsurfrules
+```
+
+### Cline
+Located in `skills/tools/cline/`.
+```bash
+cp skills/tools/cline/.clinerules .clinerules
+```
+
+### GitHub Copilot
+Located in `skills/tools/copilot/`.
+```bash
+mkdir -p .github
+cp skills/tools/copilot/copilot-instructions.md .github/copilot-instructions.md
+```
+
+## Contributing
+
+See [CONTRIBUTING.template.md](CONTRIBUTING.template.md) for guidelines on adding new skills or supporting additional AI tools.
+
+## License
+
+Dual-licensed: CC BY 4.0 (documentation) + MIT (code)

package/bundled/skills/_shared/README.md

@@ -0,0 +1,60 @@
+# Shared Resources
+
+Shared templates and utilities for generating AI tool-specific rules from core standards.
+
+## Purpose
+
+This directory contains:
+- **Templates**: Common patterns used across different AI tools
+- **Utilities**: Scripts for generating tool-specific configurations
+- **Mappings**: Standard-to-rule mappings for each AI assistant
+
+## Core Standards Mapping
+
+| Core Standard | Skill Concept | Description |
+|---------------|---------------|-------------|
+| `anti-hallucination.md` | AI Collaboration | Evidence-based responses, certainty tags |
+| `commit-message-guide.md` | Commit Standards | Conventional Commits format |
+| `code-review-checklist.md` | Code Review | Review checklists and patterns |
+| `git-workflow.md` | Git Workflow | Branching strategies |
+| `testing-standards.md` | Testing Guide | Testing pyramid, coverage |
+| `versioning.md` | Release Standards | Semantic versioning |
+| `documentation-structure.md` | Documentation | README templates, structure |
+
+## AI Tool Compatibility Matrix
+
+| Feature | Claude Code | Cursor | Windsurf | Cline | Copilot |
+|---------|-------------|--------|----------|-------|---------|
+| Skills/Rules | ✅ SKILL.md | ✅ .cursorrules | ✅ .windsurfrules | ✅ .clinerules | ✅ instructions.md |
+| Auto-trigger | ✅ | ❌ | ❌ | ❌ | ❌ |
+| Project-level | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Global-level | ✅ | ✅ | ✅ | ✅ | ❌ |
+| Notepads | ❌ | ✅ | ❌ | ❌ | ❌ |
+
+## Usage
+
+**macOS / Linux:**
+```bash
+# Generate rules for a specific tool
+./generate.sh cursor
+
+# Generate rules for all tools
+./generate.sh all
+```
+
+**Windows PowerShell:**
+```powershell
+# Generate rules for a specific tool
+.\generate.ps1 cursor
+
+# Generate rules for all tools
+.\generate.ps1 all
+```
+
+## Contributing
+
+When adding new core standards:
+1. Add entry to the mapping table above
+2. Create templates in `templates/`
+3. Update generation scripts
+4. Test with each supported AI tool

package/bundled/skills/{claude-code/agents → agents}/README.md

@@ -1,6 +1,6 @@
 # UDS Agents
 
-> **Language**: English | [繁體中文](../../../locales/zh-TW/skills/claude-code/agents/README.md)
+> **Language**: English | [繁體中文](../../locales/zh-TW/skills/agents/README.md)
 
 **Version**: 1.1.0
 **Last Updated**: 2026-01-21
@@ -285,7 +285,7 @@ See [workflows/README.md](../workflows/README.md) for workflow documentation.
 
 - [Skills Documentation](../README.md)
 - [Workflows Documentation](../workflows/README.md)
-- [AI Agent Paths Configuration](../../../cli/src/config/ai-agent-paths.js)
+- [AI Agent Paths Configuration](../../cli/src/config/ai-agent-paths.js)
 
 ---
 

package/bundled/skills/{claude-code/agents → agents}/code-architect.md

@@ -57,7 +57,7 @@ triggers:
 
 # Code Architect Agent
 
-> **Language**: English | [繁體中文](../../../locales/zh-TW/skills/claude-code/agents/code-architect.md)
+> **Language**: English | [繁體中文](../../locales/zh-TW/skills/agents/code-architect.md)
 
 ## Purpose
 

package/bundled/skills/{claude-code/agents → agents}/doc-writer.md

@@ -55,7 +55,7 @@ triggers:
 
 # Documentation Writer Agent
 
-> **Language**: English | [繁體中文](../../../locales/zh-TW/skills/claude-code/agents/doc-writer.md)
+> **Language**: English | [繁體中文](../../locales/zh-TW/skills/agents/doc-writer.md)
 
 ## Purpose
 

package/bundled/skills/{claude-code/agents → agents}/reviewer.md

@@ -55,7 +55,7 @@ triggers:
 
 # Code Reviewer Agent
 
-> **Language**: English | [繁體中文](../../../locales/zh-TW/skills/claude-code/agents/reviewer.md)
+> **Language**: English | [繁體中文](../../locales/zh-TW/skills/agents/reviewer.md)
 
 ## Purpose
 

package/bundled/skills/{claude-code/agents → agents}/spec-analyst.md

@@ -54,7 +54,7 @@ triggers:
 
 # Specification Analyst Agent
 
-> **Language**: English | [繁體中文](../../../locales/zh-TW/skills/claude-code/agents/spec-analyst.md)
+> **Language**: English | [繁體中文](../../locales/zh-TW/skills/agents/spec-analyst.md)
 
 ## Purpose
 

package/bundled/skills/{claude-code/agents → agents}/test-specialist.md

@@ -57,7 +57,7 @@ triggers:
 
 # Test Specialist Agent
 
-> **Language**: English | [繁體中文](../../../locales/zh-TW/skills/claude-code/agents/test-specialist.md)
+> **Language**: English | [繁體中文](../../locales/zh-TW/skills/agents/test-specialist.md)
 
 ## Purpose
 

package/bundled/skills/{claude-code/ai-collaboration-standards → ai-collaboration-standards}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: ai-collaboration-standards
+scope: universal
 description: |
   Prevent AI hallucination and ensure evidence-based responses when analyzing code or making suggestions.
   Use when: analyzing code, making recommendations, providing options, or when user asks about confidence/certainty.
@@ -8,10 +8,10 @@ description: |
 
 # AI Collaboration Standards
 
-> **Language**: English | [繁體中文](../../../../locales/zh-TW/skills/claude-code/ai-collaboration-standards/SKILL.md)
+> **Language**: English | [繁體中文](../../locales/zh-TW/skills/ai-collaboration-standards/SKILL.md)
 
-**Version**: 1.0.0
-**Last Updated**: 2025-12-24
+**Version**: 1.1.0
+**Last Updated**: 2026-01-25
 **Applicability**: Claude Code Skills
 
 ---
@@ -22,7 +22,11 @@ This skill ensures AI assistants provide accurate, evidence-based responses with
 
 ## Quick Reference
 
-### Certainty Tags
+### Unified Tag System
+
+This skill uses two complementary tag categories:
+
+**Category 1: Certainty Tags** (for analyzing existing content)
 
 | Tag | Use When |
 |-----|----------|
@@ -32,6 +36,24 @@ This skill ensures AI assistants provide accurate, evidence-based responses with
 | `[Unknown]` | Information not available |
 | `[Need Confirmation]` | Requires user clarification |
 
+**Category 2: Derivation Tags** (for generating new content)
+
+| Tag | Use When |
+|-----|----------|
+| `[Source]` | Direct content from spec/requirement |
+| `[Derived]` | Transformed from source content |
+| `[Generated]` | AI-generated structure |
+| `[TODO]` | Requires human implementation |
+
+**When to Use Which**:
+
+| Workflow | Primary Tags |
+|----------|--------------|
+| Code analysis | Certainty Tags |
+| Reverse engineering | Certainty Tags |
+| Forward derivation | Derivation Tags |
+| Spec generation | Derivation Tags |
+
 ### Source Types
 
 | Source Type | Tag | Reliability |
@@ -164,6 +186,7 @@ This project uses **English** certainty tags.
 
 | Version | Date | Changes |
 |---------|------|---------|
+| 1.1.0 | 2026-01-25 | Added: Unified Tag System with Certainty and Derivation tag categories |
 | 1.0.0 | 2025-12-24 | Added: Standard sections (Purpose, Related Standards, Version History, License) |
 
 ---

package/bundled/skills/{claude-code/ai-collaboration-standards → ai-collaboration-standards}/anti-hallucination.md

@@ -1,9 +1,9 @@
 # Anti-Hallucination Guidelines
 
-> **Language**: English | [繁體中文](../../../../locales/zh-TW/skills/claude-code/ai-collaboration-standards/anti-hallucination.md)
+> **Language**: English | [繁體中文](../../locales/zh-TW/skills/ai-collaboration-standards/anti-hallucination.md)
 
-**Version**: 1.0.0
-**Last Updated**: 2025-12-24
+**Version**: 1.1.0
+**Last Updated**: 2026-01-25
 **Applicability**: Claude Code Skills
 
 ---
@@ -74,10 +74,12 @@ When referencing libraries, frameworks, or APIs, always include version informat
 
 ---
 
-### 3. Classify Certainty Levels
+### 3. Classify Certainty Levels (Unified Tag System)
 
 **Rule**: Clearly distinguish between confirmed facts, inferences, and unknowns.
 
+#### Certainty Tags (for analyzing existing content)
+
 | Tag | Use When |
 |-----|----------|
 | `[Confirmed]` | Direct evidence from code/docs |
@@ -86,14 +88,30 @@ When referencing libraries, frameworks, or APIs, always include version informat
 | `[Unknown]` | Information not available |
 | `[Need Confirmation]` | Requires user clarification |
 
+#### Derivation Tags (for generating new content)
+
+| Tag | Use When |
+|-----|----------|
+| `[Source]` | Direct content from spec/requirement |
+| `[Derived]` | Transformed from source content |
+| `[Generated]` | AI-generated structure |
+| `[TODO]` | Requires human implementation |
+
 **Examples**:
 
 ```
+# Certainty Tags (analysis)
 [Confirmed] src/database/connection.ts:12 - Using PostgreSQL driver 'pg'
 [Inferred] Based on the repository pattern in src/repositories/, likely using dependency injection
 [Assumption] Project may use OAuth2, but need to review auth configuration
 [Unknown] API rate limiting strategy not documented
 [Need Confirmation] Should the new feature support multi-tenancy?
+
+# Derivation Tags (generation)
+[Source] Feature title from SPEC-001
+[Derived] Gherkin scenario from bullet-point AC
+[Generated] Test skeleton structure
+[TODO] Implement actual assertions
 ```
 
 ---
@@ -195,7 +213,7 @@ AI assistants MUST NOT:
 
 ## Related Standards
 
-- [Anti-Hallucination Standards](../../../core/anti-hallucination.md)
+- [Anti-Hallucination Standards](../../core/anti-hallucination.md)
 - [Certainty Labels Reference](./certainty-labels.md)
 
 ---
@@ -204,6 +222,7 @@ AI assistants MUST NOT:
 
 | Version | Date | Changes |
 |---------|------|---------|
+| 1.1.0 | 2026-01-25 | Added: Unified Tag System with Certainty and Derivation tags |
 | 1.0.0 | 2025-12-24 | Added: Standard sections (Purpose, Related Standards, Version History, License) |
 
 ---

package/bundled/skills/{claude-code/ai-collaboration-standards → ai-collaboration-standards}/certainty-labels.md

@@ -1,20 +1,31 @@
 # Certainty Labels Reference
 
-> **Language**: English | [繁體中文](../../../../locales/zh-TW/skills/claude-code/ai-collaboration-standards/certainty-labels.md)
+> **Language**: English | [繁體中文](../../locales/zh-TW/skills/ai-collaboration-standards/certainty-labels.md)
 
-**Version**: 1.0.0
-**Last Updated**: 2025-12-24
+**Version**: 1.1.0
+**Last Updated**: 2026-01-25
 **Applicability**: Claude Code Skills
 
 ---
 
 ## Purpose
 
-This document provides reference for certainty labels and source types used in AI responses.
+This document provides reference for certainty labels, derivation tags, and source types used in AI responses.
 
 ---
 
-## Tag Mapping (English / 中文)
+## Unified Tag System Overview
+
+This skill uses two complementary tag categories:
+
+| Category | Purpose | Used In |
+|----------|---------|---------|
+| **Certainty Tags** | Analyzing existing content | Code analysis, reverse engineering |
+| **Derivation Tags** | Generating new content | Forward derivation, spec generation |
+
+---
+
+## Certainty Tags (English / 中文)
 
 | English Tag | 中文標籤 | Use When |
 |-------------|---------|----------|
@@ -26,6 +37,19 @@ This document provides reference for certainty labels and source types used in A
 
 ---
 
+## Derivation Tags (English / 中文)
+
+Used when generating tests, specifications, or documentation from approved sources.
+
+| English Tag | 中文標籤 | Use When |
+|-------------|---------|----------|
+| `[Source]` | `[來源]` | Direct content from spec/requirement (verbatim) |
+| `[Derived]` | `[推演]` | Transformed from source content (e.g., bullet → GWT) |
+| `[Generated]` | `[生成]` | AI-generated structure (test skeleton, TODO comments) |
+| `[TODO]` | `[待辦]` | Requires human implementation |
+
+---
+
 ## Source Types
 
 | Source Type | Tag | Description | Reliability |
@@ -105,7 +129,7 @@ Did you read the actual code/doc?
 ## Related Standards
 
 - [Anti-Hallucination Guidelines](./anti-hallucination.md)
-- [Anti-Hallucination Standards](../../../core/anti-hallucination.md)
+- [Anti-Hallucination Standards](../../core/anti-hallucination.md)
 
 ---
 
@@ -113,6 +137,7 @@ Did you read the actual code/doc?
 
 | Version | Date | Changes |
 |---------|------|---------|
+| 1.1.0 | 2026-01-25 | Added: Unified Tag System, Derivation Tags with Chinese translations |
 | 1.0.0 | 2025-12-24 | Added: Standard sections (Purpose, Related Standards, Version History, License) |
 
 ---