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

package/bundled/skills/ai-friendly-architecture/SKILL.md

@@ -0,0 +1,216 @@
+---
+scope: uds-specific
+description: |
+  Design AI-friendly architecture with explicit patterns, layered documentation, and semantic boundaries.
+  Use when: structuring projects for AI collaboration, optimizing codebase for AI analysis, setting up AI context.
+  Keywords: architecture, AI-friendly, context, modules, documentation layers, .ai-context.yaml, 架構, AI 友善, 上下文.
+---
+
+# AI-Friendly Architecture Guide
+
+> **Language**: English | [繁體中文](../../locales/zh-TW/skills/ai-friendly-architecture/SKILL.md)
+
+**Version**: 1.0.0
+**Last Updated**: 2026-01-25
+**Applicability**: Claude Code Skills
+
+---
+
+> **Core Standard**: This skill implements [AI-Friendly Architecture](../../core/ai-friendly-architecture.md). For comprehensive methodology documentation, refer to the core standard.
+
+## Purpose
+
+This skill helps design project architecture that maximizes AI collaboration effectiveness through explicit patterns, layered documentation, and semantic boundaries.
+
+## Quick Reference
+
+### Core Principles
+
+| Principle | Description | Benefit |
+|-----------|-------------|---------|
+| **Explicit Over Implicit** | Document behavior explicitly | AI understands without guessing |
+| **Layered Context** | Multi-level documentation | Appropriate detail per task |
+| **Semantic Boundaries** | Clear module boundaries | Independent analysis |
+| **Discoverable Structure** | Self-documenting structure | Quick orientation |
+
+### Context Layers
+
+| Layer | Token Budget | Content |
+|-------|--------------|---------|
+| **L1: Quick Ref** | < 500 | One-liners, API signatures, entry points |
+| **L2: Detailed** | < 5,000 | Full API docs, usage examples |
+| **L3: Examples** | Unlimited | Complete implementations, edge cases |
+
+### Recommended Structure
+
+```
+project/
+├── .ai-context.yaml          # AI context configuration
+├── docs/
+│   ├── QUICK-REF.md          # Level 1 documentation
+│   └── ARCHITECTURE.md       # Level 2 documentation
+├── src/
+│   └── auth/
+│       ├── index.ts          # Entry point with module header
+│       ├── QUICK-REF.md      # Module quick reference
+│       └── README.md         # Module documentation
+└── CLAUDE.md                 # AI instruction file
+```
+
+## Module Header Template
+
+```javascript
+/**
+ * ═══════════════════════════════════════════════════════════
+ * MODULE: [Module Name]
+ * ═══════════════════════════════════════════════════════════
+ *
+ * PURPOSE: [One-sentence description]
+ *
+ * DEPENDENCIES:
+ *   - [dep1]: [reason]
+ *   - [dep2]: [reason]
+ *
+ * EXPORTS:
+ *   - [function1](params): [description]
+ *   - [function2](params): [description]
+ *
+ * CONFIGURATION:
+ *   - [CONFIG_VAR]: [description]
+ *
+ * ═══════════════════════════════════════════════════════════
+ */
+```
+
+## Detailed Guidelines
+
+For complete standards, see:
+- [AI-Friendly Architecture Standards](../../core/ai-friendly-architecture.md)
+
+### AI-Optimized Format (Token-Efficient)
+
+For AI assistants, use the YAML format file for reduced token usage:
+- Base standard: `ai/standards/ai-friendly-architecture.ai.yaml`
+
+## .ai-context.yaml Configuration
+
+```yaml
+# .ai-context.yaml - AI Context Configuration
+version: 1.0.0
+
+project:
+  name: my-project
+  type: web-app  # web-app | library | cli | api | monorepo
+  primary-language: typescript
+
+modules:
+  - name: auth
+    path: src/auth/
+    entry: index.ts
+    description: Authentication and authorization
+    dependencies: [database, crypto]
+    priority: high
+
+  - name: api
+    path: src/api/
+    entry: routes.ts
+    description: REST API endpoints
+    dependencies: [auth, database]
+    priority: high
+
+analysis-hints:
+  entry-points:
+    - src/main.ts
+    - src/index.ts
+  ignore-patterns:
+    - node_modules
+    - dist
+    - "*.test.ts"
+  architecture-type: layered
+
+documentation:
+  quick-ref: docs/QUICK-REF.md
+  detailed: docs/ARCHITECTURE.md
+  examples: docs/examples/
+```
+
+## Context Priority Guidelines
+
+| Priority | Content Type | Reason |
+|----------|--------------|--------|
+| 1 | Entry points | Application structure |
+| 2 | .ai-context.yaml | Module map and dependencies |
+| 3 | QUICK-REF files | Rapid API understanding |
+| 4 | Modified files | Direct task relevance |
+| 5 | Dependency chain | Context for changes |
+
+## Anti-Patterns to Avoid
+
+| Anti-Pattern | Problem | Solution |
+|--------------|---------|----------|
+| **Magic strings** | AI can't trace constants | Typed constants with docs |
+| **Implicit routing** | Hidden behavior | Explicit route mappings |
+| **Global state** | Unpredictable deps | Dependency injection |
+| **Circular deps** | Context confusion | Hierarchical dependencies |
+| **Monolithic files** | Context overflow | Focused modules |
+
+## Implementation Checklist
+
+### Quick Start (< 1 hour)
+
+- [ ] Create `.ai-context.yaml` with module list
+- [ ] Add `QUICK-REF.md` to project root
+- [ ] Document entry points in README
+- [ ] Add module headers to main files
+
+### Standard Implementation (< 1 day)
+
+- [ ] Complete `.ai-context.yaml` configuration
+- [ ] Add `QUICK-REF.md` to each major module
+- [ ] Document all public APIs with type info
+- [ ] Add section dividers to large files
+
+---
+
+## Configuration Detection
+
+This skill supports project-specific configuration.
+
+### Detection Order
+
+1. Check for existing `.ai-context.yaml`
+2. Check for `QUICK-REF.md` files
+3. If not found, **suggest creating AI-friendly structure**
+
+### First-Time Setup
+
+If no configuration found:
+
+1. Suggest: "This project hasn't been configured for AI collaboration. Would you like to set up an AI-friendly structure?"
+2. Create `.ai-context.yaml` template
+3. Create `QUICK-REF.md` in project root
+
+---
+
+## Related Standards
+
+- [AI-Friendly Architecture](../../core/ai-friendly-architecture.md) - Core architecture standard
+- [Project Structure](../../core/project-structure.md) - Directory organization
+- [Documentation Structure](../../core/documentation-structure.md) - Documentation layering
+- [Anti-Hallucination](../../core/anti-hallucination.md) - AI accuracy standards
+
+---
+
+## Version History
+
+| Version | Date | Changes |
+|---------|------|---------|
+| 1.0.0 | 2026-01-25 | Initial release |
+
+---
+
+## License
+
+This skill 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/ai-instruction-standards/SKILL.md

@@ -0,0 +1,209 @@
+---
+scope: partial
+description: |
+  Create and maintain AI instruction files (CLAUDE.md, .cursorrules, etc.) with proper structure.
+  Use when: creating AI instruction files, separating universal vs project-specific rules, configuring AI tools.
+  Keywords: CLAUDE.md, cursorrules, windsurfrules, clinerules, AI instructions, system prompt, 指令檔案, AI 設定.
+---
+
+# AI Instruction File Standards Guide
+
+> **Language**: English | [繁體中文](../../locales/zh-TW/skills/ai-instruction-standards/SKILL.md)
+
+**Version**: 1.0.0
+**Last Updated**: 2026-01-25
+**Applicability**: Claude Code Skills
+
+---
+
+> **Core Standard**: This skill implements [AI Instruction File Standards](../../core/ai-instruction-standards.md). For comprehensive methodology documentation, refer to the core standard.
+
+## Purpose
+
+This skill helps create and maintain AI instruction files with proper separation between universal standards and project-specific configurations.
+
+## Quick Reference
+
+### Supported AI Tools
+
+| AI Tool | Instruction File | Format |
+|---------|-----------------|--------|
+| Claude Code | `CLAUDE.md` | Markdown |
+| Cursor | `.cursorrules` | Markdown |
+| Windsurf | `.windsurfrules` | Markdown |
+| Cline | `.clinerules` | Markdown |
+| GitHub Copilot | `.github/copilot-instructions.md` | Markdown |
+| OpenCode | `.opencode/instructions.md` | Markdown |
+
+### Core Principle: Universal vs Project-Specific
+
+| Type | Contains | Example |
+|------|----------|---------|
+| **Universal** | Generic rules | "Run tests before committing" |
+| **Project-Specific** | Concrete commands | "Run `npm test` before committing" |
+
+### Recommended Layout
+
+```markdown
+# [Project Name] - AI Instructions
+
+## Universal Standards
+<!-- Rules applicable to ANY project -->
+- Commit message format
+- Code review checklist
+- Testing standards
+- Anti-hallucination rules
+
+---
+
+## Project-Specific Configuration
+<!-- Unique to THIS project -->
+
+### Tech Stack
+[Your technologies here]
+
+### Quick Commands
+[Your build/test/deploy commands]
+
+### File Structure
+[Your project structure]
+```
+
+## Detailed Guidelines
+
+For complete standards, see:
+- [AI Instruction File Standards](../../core/ai-instruction-standards.md)
+
+### AI-Optimized Format (Token-Efficient)
+
+For AI assistants, use the YAML format file for reduced token usage:
+- Base standard: `ai/standards/ai-instruction-standards.ai.yaml`
+
+## Content Guidelines
+
+### Universal Content (Keep Generic)
+
+| Category | Good Examples |
+|----------|---------------|
+| **Commit Standards** | "Follow Conventional Commits format" |
+| **Code Review** | "Use BLOCKING, IMPORTANT, SUGGESTION prefixes" |
+| **Testing** | "Maintain 80% coverage minimum" |
+| **AI Behavior** | "Always read code before analyzing" |
+
+**Avoid in Universal Sections:**
+- Specific commands (`npm test`, `pytest`)
+- Hardcoded paths (`cli/src/`, `/var/www/`)
+- Version numbers (`Node.js 18`, `Python 3.11`)
+- Project names and URLs
+
+### Project-Specific Content
+
+| Category | Examples |
+|----------|----------|
+| **Tech Stack** | Node.js 18, React 18, PostgreSQL 15 |
+| **Commands** | `npm run lint`, `./scripts/deploy.sh` |
+| **File Structure** | `src/`, `cli/`, `tests/` |
+| **Team Conventions** | Traditional Chinese comments |
+
+## Labeling Convention
+
+### Option A: Section Headers
+
+```markdown
+## Universal Standards
+[universal content]
+
+## Project-Specific Configuration
+[project-specific content]
+```
+
+### Option B: Inline Markers
+
+```markdown
+> ⚠️ **Project-Specific**: This section contains configuration unique to this project.
+
+### Tech Stack
+...
+```
+
+### Option C: Comment Annotations
+
+```markdown
+<!-- UNIVERSAL: The following applies to all projects -->
+### Commit Message Format
+...
+
+<!-- PROJECT-SPECIFIC: Customize for your project -->
+### Quick Commands
+...
+```
+
+## Multi-Tool Configuration
+
+When using multiple AI tools, maintain consistency:
+
+```
+project/
+├── CLAUDE.md              # Claude Code instructions
+├── .cursorrules           # Cursor instructions (can import from CLAUDE.md)
+├── .windsurfrules         # Windsurf instructions
+└── .github/
+    └── copilot-instructions.md  # Copilot instructions
+```
+
+**Best Practice**: Create a shared `docs/ai-standards.md` and reference it from each tool's file to avoid duplication.
+
+## Maintenance Checklist
+
+Before committing changes to AI instruction files:
+
+- [ ] Universal sections contain no project-specific paths, commands, or versions
+- [ ] Project-specific sections are clearly marked
+- [ ] Cross-references to standards documents are correct
+- [ ] Format matches existing sections
+
+---
+
+## Configuration Detection
+
+This skill supports project-specific configuration.
+
+### Detection Order
+
+1. Check for existing `CLAUDE.md` or equivalent files
+2. Analyze content structure for universal/project-specific separation
+3. If not found, **suggest creating structured AI instruction file**
+
+### First-Time Setup
+
+If no AI instruction file found:
+
+1. Ask: "This project doesn't have an AI instruction file. Would you like to create one?"
+2. Determine project type and tech stack
+3. Generate template with appropriate sections
+4. Add to `.gitignore` if contains sensitive info
+
+---
+
+## Related Standards
+
+- [AI Instruction File Standards](../../core/ai-instruction-standards.md) - Core standard
+- [Documentation Writing Standards](../../core/documentation-writing-standards.md) - Writing guidelines
+- [Anti-Hallucination Guidelines](../../core/anti-hallucination.md) - AI accuracy rules
+- [AI-Friendly Architecture](../../core/ai-friendly-architecture.md) - Context optimization
+
+---
+
+## Version History
+
+| Version | Date | Changes |
+|---------|------|---------|
+| 1.0.0 | 2026-01-25 | Initial release |
+
+---
+
+## License
+
+This skill 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/atdd-assistant/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: atdd
+scope: partial
+description: "[UDS] Guide through Acceptance Test-Driven Development workflow"
+allowed-tools: Read, Write, Grep, Glob
+argument-hint: "[feature or spec | 功能或規格]"
+---
+
+# ATDD Assistant | ATDD 助手
+
+Guide through the Acceptance Test-Driven Development (ATDD) workflow for defining and validating user stories.
+
+引導驗收測試驅動開發（ATDD）流程，用於定義和驗證使用者故事。
+
+## ATDD Cycle | ATDD 循環
+
+```
+WORKSHOP ──► DISTILLATION ──► DEVELOPMENT ──► DEMO ──► DONE
+    ^                              │              │
+    └──────────────────────────────┴──────────────┘
+                  (Refinement needed)
+```
+
+## Workflow | 工作流程
+
+### 1. WORKSHOP - Define AC | 定義驗收條件
+PO presents user story, team asks clarifying questions, define acceptance criteria together.
+
+### 2. DISTILLATION - Convert to Tests | 轉換為測試
+Convert AC to executable test format, remove ambiguity, get PO sign-off.
+
+### 3. DEVELOPMENT - Implement | 實作
+Run acceptance tests (should fail initially), use BDD/TDD for implementation, iterate until all pass.
+
+### 4. DEMO - Present | 向利害關係人展示
+Show passing acceptance tests, demonstrate working functionality, get formal acceptance.
+
+### 5. DONE - Complete | 完成
+PO accepted, code merged, story closed.
+
+## INVEST Criteria | INVEST 準則
+
+| Criterion | Description | 說明 |
+|-----------|-------------|------|
+| **I**ndependent | Can be developed separately | 可獨立開發 |
+| **N**egotiable | Details can be discussed | 可協商細節 |
+| **V**aluable | Delivers business value | 提供商業價值 |
+| **E**stimable | Can estimate effort | 可估算工作量 |
+| **S**mall | Fits in one sprint | 一個 Sprint 可完成 |
+| **T**estable | Has clear acceptance criteria | 有明確驗收條件 |
+
+## User Story Format | 使用者故事格式
+
+```markdown
+As a [role],
+I want [feature],
+So that [benefit].
+
+### Acceptance Criteria
+- Given [context], when [action], then [result]
+```
+
+## Usage | 使用方式
+
+```
+/atdd                              - Start interactive ATDD session | 啟動互動式 ATDD 會話
+/atdd "user can reset password"    - ATDD for specific feature | 針對特定功能
+/atdd US-123                       - ATDD for existing user story | 處理現有使用者故事
+```
+
+## Reference | 參考
+
+- Detailed guide: [guide.md](./guide.md)
+- Core standard: [acceptance-test-driven-development.md](../../core/acceptance-test-driven-development.md)

package/bundled/skills/{claude-code/atdd-assistant → atdd-assistant}/acceptance-criteria-guide.md

@@ -415,6 +415,6 @@ Scenario: Successful password reset
 ## Related Resources
 
 - [ATDD Workflow Guide](./atdd-workflow.md)
-- [ATDD Core Standard](../../../core/acceptance-test-driven-development.md)
+- [ATDD Core Standard](../../core/acceptance-test-driven-development.md)
 - [Gherkin Guide](../bdd-assistant/gherkin-guide.md)
 - [Requirement Assistant](../requirement-assistant/SKILL.md)

package/bundled/skills/{claude-code/atdd-assistant → atdd-assistant}/atdd-workflow.md

@@ -568,6 +568,6 @@ Feature: Order Confirmation Email
 ## Related Resources
 
 - [Acceptance Criteria Guide](./acceptance-criteria-guide.md)
-- [ATDD Core Standard](../../../core/acceptance-test-driven-development.md)
+- [ATDD Core Standard](../../core/acceptance-test-driven-development.md)
 - [BDD Workflow](../bdd-assistant/bdd-workflow.md)
 - [TDD Workflow](../tdd-assistant/tdd-workflow.md)

package/bundled/skills/{claude-code/atdd-assistant/SKILL.md → atdd-assistant/guide.md}

@@ -1,5 +1,5 @@
 ---
-name: atdd-assistant
+scope: partial
 description: |
   Guide teams through Acceptance Test-Driven Development workflow.
   Use when: defining acceptance criteria, running specification workshops, writing user stories with acceptance tests, PO sign-off.
@@ -8,7 +8,7 @@ description: |
 
 # ATDD Assistant
 
-> **Language**: English | [繁體中文](../../../locales/zh-TW/skills/claude-code/atdd-assistant/SKILL.md)
+> **Language**: English | [繁體中文](../../locales/zh-TW/skills/atdd-assistant/SKILL.md)
 
 **Version**: 1.0.0
 **Last Updated**: 2026-01-19
@@ -312,14 +312,14 @@ If no configuration found:
 ## Detailed Guidelines
 
 For complete standards, see:
-- [ATDD Core Standard](../../../core/acceptance-test-driven-development.md)
+- [ATDD Core Standard](../../core/acceptance-test-driven-development.md)
 - [ATDD Workflow Guide](./atdd-workflow.md)
 - [Acceptance Criteria Guide](./acceptance-criteria-guide.md)
 
 For related standards:
-- [BDD Standards](../../../core/behavior-driven-development.md)
-- [TDD Standards](../../../core/test-driven-development.md)
-- [Testing Standards](../../../core/testing-standards.md)
+- [BDD Standards](../../core/behavior-driven-development.md)
+- [TDD Standards](../../core/test-driven-development.md)
+- [Testing Standards](../../core/testing-standards.md)
 
 ---
 
@@ -353,11 +353,11 @@ For related standards:
 
 ## Related Standards
 
-- [Acceptance Test-Driven Development](../../../core/acceptance-test-driven-development.md) - Core ATDD standard
-- [Behavior-Driven Development](../../../core/behavior-driven-development.md) - BDD standard
-- [Test-Driven Development](../../../core/test-driven-development.md) - TDD standard
-- [Spec-Driven Development](../../../core/spec-driven-development.md) - SDD workflow
-- [Testing Standards](../../../core/testing-standards.md) - Testing framework
+- [Acceptance Test-Driven Development](../../core/acceptance-test-driven-development.md) - Core ATDD standard
+- [Behavior-Driven Development](../../core/behavior-driven-development.md) - BDD standard
+- [Test-Driven Development](../../core/test-driven-development.md) - TDD standard
+- [Spec-Driven Development](../../core/spec-driven-development.md) - SDD workflow
+- [Testing Standards](../../core/testing-standards.md) - Testing framework
 - [BDD Assistant](../bdd-assistant/SKILL.md) - BDD skill
 - [TDD Assistant](../tdd-assistant/SKILL.md) - TDD skill
 

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

@@ -0,0 +1,70 @@
+---
+name: bdd
+scope: partial
+description: "[UDS] Guide through Behavior-Driven Development workflow"
+allowed-tools: Read, Write, Grep, Glob
+argument-hint: "[feature or spec | 功能或規格]"
+---
+
+# BDD Assistant | BDD 助手
+
+Guide through the Behavior-Driven Development (BDD) workflow using Given-When-Then format.
+
+引導行為驅動開發（BDD）流程，使用 Given-When-Then 格式。
+
+## BDD Cycle | BDD 循環
+
+```
+DISCOVERY ──► FORMULATION ──► AUTOMATION ──► LIVING DOCS
+    ^                                            │
+    └────────────────────────────────────────────┘
+```
+
+## Workflow | 工作流程
+
+### 1. DISCOVERY - Explore Behavior | 探索行為
+Discuss with stakeholders, identify examples and edge cases, understand the "why".
+
+### 2. FORMULATION - Write Scenarios | 制定場景
+Write Gherkin scenarios using ubiquitous language, make them concrete and specific.
+
+### 3. AUTOMATION - Implement Tests | 自動化測試
+Implement step definitions, write minimal code to pass, follow TDD within automation.
+
+### 4. LIVING DOCUMENTATION - Maintain | 活文件維護
+Keep scenarios current, use as shared documentation, review with stakeholders.
+
+## Gherkin Format | Gherkin 格式
+
+```gherkin
+Feature: User Login
+  As a registered user
+  I want to log in to my account
+  So that I can access my dashboard
+
+  Scenario: Successful login
+    Given I am on the login page
+    When I enter valid credentials
+    Then I should see my dashboard
+```
+
+## Three Amigos | 三劍客會議
+
+| Role | Focus | 角色 | 關注點 |
+|------|-------|------|--------|
+| **Business** | What & Why | 業務 | 什麼和為什麼 |
+| **Development** | How | 開發 | 如何實現 |
+| **Testing** | What if | 測試 | 假設情況 |
+
+## Usage | 使用方式
+
+```
+/bdd                              - Start interactive BDD session | 啟動互動式 BDD 會話
+/bdd "user can reset password"    - BDD for specific feature | 針對特定功能
+/bdd login-feature.feature        - Work with existing feature file | 處理現有功能檔案
+```
+
+## Reference | 參考
+
+- Detailed guide: [guide.md](./guide.md)
+- Core standard: [behavior-driven-development.md](../../core/behavior-driven-development.md)

package/bundled/skills/{claude-code/bdd-assistant → bdd-assistant}/bdd-workflow.md

@@ -394,5 +394,5 @@ Then('I should see error {string}', async function (message) {
 ## Related Resources
 
 - [Gherkin Quick Reference](./gherkin-guide.md)
-- [BDD Core Standard](../../../core/behavior-driven-development.md)
+- [BDD Core Standard](../../core/behavior-driven-development.md)
 - [TDD Workflow](../tdd-assistant/tdd-workflow.md)

package/bundled/skills/{claude-code/bdd-assistant → bdd-assistant}/gherkin-guide.md

@@ -442,5 +442,5 @@ AfterAll(async function () {
 ## Related Resources
 
 - [BDD Workflow Guide](./bdd-workflow.md)
-- [BDD Core Standard](../../../core/behavior-driven-development.md)
+- [BDD Core Standard](../../core/behavior-driven-development.md)
 - [Official Gherkin Reference](https://cucumber.io/docs/gherkin/reference/)