universal-dev-standards 4.1.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/agents/README.md

@@ -0,0 +1,305 @@
+# UDS Agents
+
+> **Language**: English | [繁體中文](../../locales/zh-TW/skills/agents/README.md)
+
+**Version**: 1.1.0
+**Last Updated**: 2026-01-21
+**Status**: Stable
+
+---
+
+## Overview
+
+UDS Agents are specialized AI subagents that can be orchestrated to handle complex development workflows. Unlike Skills (which provide context/knowledge), Agents are autonomous entities that can execute multi-step tasks.
+
+## AGENT.md Format Specification
+
+### Frontmatter Schema
+
+```yaml
+---
+# === REQUIRED FIELDS ===
+name: agent-name              # Unique identifier (kebab-case)
+version: 1.0.0                # Semantic version
+description: |                # Multi-line description for AI matching
+  Brief description of the agent's purpose.
+  Keywords: keyword1, keyword2, keyword3.
+
+# === ROLE CONFIGURATION ===
+role: specialist              # orchestrator | specialist | reviewer
+expertise:                    # Domain expertise areas
+  - system-design
+  - api-design
+  - database-modeling
+
+# === TOOL PERMISSIONS (Claude Code Task tool) ===
+# Specify which tools this agent can use
+allowed-tools:
+  - Read                      # File reading
+  - Glob                      # Pattern matching
+  - Grep                      # Content search
+  - Bash(git:*)               # Git commands only
+  - WebFetch                  # Web fetching
+  - WebSearch                 # Web search
+disallowed-tools:             # Explicitly blocked tools
+  - Write                     # No file writing
+  - Edit                      # No file editing
+
+# === SKILL DEPENDENCIES ===
+# Skills that provide context/knowledge to this agent
+skills:
+  - spec-driven-dev           # Skill name reference
+  - testing-guide
+
+# === MODEL PREFERENCES (Claude Code only) ===
+model: claude-sonnet-4-20250514  # Preferred model
+temperature: 0.3              # Response creativity (0.0-1.0)
+
+# === CONTEXT STRATEGY (RLM-inspired) ===
+# Configuration for handling large codebases and long contexts
+context-strategy:
+  mode: adaptive              # full | chunked | adaptive
+  max-chunk-size: 50000       # Maximum tokens per chunk
+  overlap: 500                # Token overlap between chunks
+  analysis-pattern: hierarchical  # hierarchical | parallel | sequential
+
+# === TRIGGER CONDITIONS ===
+triggers:
+  keywords:                   # Auto-activate on these keywords
+    - architecture
+    - system design
+    - 架構設計
+  commands:                   # Slash commands that invoke this agent
+    - /architect
+---
+```
+
+### Role Types
+
+| Role | Description | Use Case |
+|------|-------------|----------|
+| `orchestrator` | Coordinates multiple agents | Complex workflows, feature development |
+| `specialist` | Deep expertise in specific domain | Architecture, testing, documentation |
+| `reviewer` | Evaluates and provides feedback | Code review, spec review, PR review |
+
+### Tool Permission Patterns
+
+```yaml
+# Full tool access (default if not specified)
+allowed-tools: [*]
+
+# Read-only agent
+allowed-tools: [Read, Glob, Grep]
+disallowed-tools: [Write, Edit, Bash]
+
+# Git-only bash access
+allowed-tools:
+  - Bash(git:*)     # Only git commands
+  - Bash(npm:test)  # Only npm test
+
+# Specific file patterns
+allowed-tools:
+  - Write(*.md)     # Only markdown files
+  - Edit(src/**)    # Only src directory
+```
+
+### Context Strategy Configuration (RLM-inspired)
+
+The `context-strategy` section enables intelligent handling of large codebases and long contexts using RLM (Recursive Language Model) principles.
+
+#### Mode Options
+
+| Mode | Description | Use Case |
+|------|-------------|----------|
+| `full` | Load complete context at once | Small projects, documentation tasks |
+| `chunked` | Divide context into fixed-size chunks | Sequential code review, large file analysis |
+| `adaptive` | Dynamically adjust based on content structure | Complex analysis, architecture exploration |
+
+#### Analysis Patterns
+
+| Pattern | Description | Best For |
+|---------|-------------|----------|
+| `hierarchical` | Analyze high-level structure first, then drill down | Architecture analysis, system design |
+| `parallel` | Process multiple sections simultaneously | Independent module analysis, spec review |
+| `sequential` | Process sections in order, preserving context | Code review, step-by-step analysis |
+
+#### Configuration Examples
+
+```yaml
+# For architecture analysis (need overview first)
+context-strategy:
+  mode: adaptive
+  max-chunk-size: 50000
+  overlap: 500
+  analysis-pattern: hierarchical
+
+# For code review (sequential processing)
+context-strategy:
+  mode: chunked
+  max-chunk-size: 30000
+  overlap: 200
+  analysis-pattern: sequential
+
+# For documentation (need full context)
+context-strategy:
+  mode: full
+  analysis-pattern: hierarchical
+```
+
+### Cross-Tool Execution Modes
+
+| AI Tool | Execution Mode | How It Works |
+|---------|---------------|--------------|
+| Claude Code | `task` | Uses Task tool to spawn independent subagent |
+| OpenCode | `task` | Similar Task tool support |
+| Cursor / Windsurf | `inline` | Injects AGENT.md as context prefix |
+| Copilot / Gemini | `inline` | Converts to prompt snippets |
+
+## Built-in Agents
+
+| Agent | Role | Description |
+|-------|------|-------------|
+| [code-architect](./code-architect.md) | specialist | Software architecture and system design |
+| [test-specialist](./test-specialist.md) | specialist | Testing strategy and test implementation |
+| [reviewer](./reviewer.md) | reviewer | Code review and quality assessment |
+| [doc-writer](./doc-writer.md) | specialist | Documentation and technical writing |
+| [spec-analyst](./spec-analyst.md) | specialist | Specification analysis and requirement extraction |
+
+## Usage
+
+### CLI Installation
+
+```bash
+# List available agents
+uds agent list
+
+# Install specific agent to project
+uds agent install code-architect
+
+# Install all agents
+uds agent install --all
+
+# Install to user directory (global)
+uds agent install code-architect --global
+```
+
+### Direct Invocation in Claude Code
+
+```
+/architect [task description]
+```
+
+Or through natural language triggers:
+
+```
+Please help me design the architecture for a new authentication system.
+```
+
+## Creating Custom Agents
+
+### 1. Create AGENT.md File
+
+```bash
+# In your project
+mkdir -p .claude/agents
+touch .claude/agents/my-agent.md
+```
+
+### 2. Define Frontmatter
+
+```yaml
+---
+name: my-custom-agent
+version: 1.0.0
+description: |
+  Custom agent for specific project needs.
+  Keywords: custom, specific, project.
+
+role: specialist
+expertise: [domain-specific]
+
+allowed-tools: [Read, Glob, Grep, Edit]
+skills: [relevant-skill]
+
+triggers:
+  commands: [/myagent]
+---
+```
+
+### 3. Write Agent Instructions
+
+```markdown
+# My Custom Agent
+
+## Purpose
+
+Describe what this agent does.
+
+## Workflow
+
+1. Step one
+2. Step two
+3. Step three
+
+## Guidelines
+
+- Guideline 1
+- Guideline 2
+```
+
+## Agent vs Skill Comparison
+
+| Aspect | Skill | Agent |
+|--------|-------|-------|
+| **Purpose** | Provide knowledge/context | Execute autonomous tasks |
+| **Execution** | Loaded as context | Spawned as subagent (or inline) |
+| **State** | Stateless | Can maintain task state |
+| **Tool Access** | None (context only) | Configurable permissions |
+| **Triggers** | Manual loading | Keywords, commands, workflows |
+| **Composition** | Referenced by agents | Can use skills as context |
+
+## Integration with Workflows
+
+Agents can be orchestrated through workflow definitions:
+
+```yaml
+# workflows/feature-dev.workflow.yaml
+name: feature-development
+steps:
+  - agent: spec-analyst
+    task: Analyze requirements
+  - agent: code-architect
+    task: Design solution
+  - agent: test-specialist
+    task: Define test strategy
+  - manual: Implementation
+  - agent: reviewer
+    task: Code review
+```
+
+See [workflows/README.md](../workflows/README.md) for workflow documentation.
+
+---
+
+## Related Resources
+
+- [Skills Documentation](../README.md)
+- [Workflows Documentation](../workflows/README.md)
+- [AI Agent Paths Configuration](../../cli/src/config/ai-agent-paths.js)
+
+---
+
+## Version History
+
+| Version | Date | Changes |
+|---------|------|---------|
+| 1.1.0 | 2026-01-21 | Added RLM-inspired context-strategy configuration |
+| 1.0.0 | 2026-01-20 | Initial release |
+
+---
+
+## License
+
+This documentation 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)