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

package/bundled/skills/workflows/README.md

@@ -0,0 +1,303 @@
+# UDS Workflows
+
+> **Language**: English | [繁體中文](../../locales/zh-TW/skills/workflows/README.md)
+
+**Version**: 1.1.0
+**Last Updated**: 2026-01-21
+**Status**: Experimental
+
+---
+
+## Overview
+
+UDS Workflows orchestrate multiple agents to complete complex development tasks. Each workflow defines a sequence of steps, where each step can be executed by an agent or require manual intervention.
+
+## Workflow YAML Format
+
+### Schema
+
+```yaml
+name: workflow-name          # Unique identifier (kebab-case)
+version: 1.0.0               # Semantic version
+description: |               # Multi-line description
+  Brief description of the workflow.
+
+# Workflow metadata
+metadata:
+  author: universal-dev-standards
+  category: development       # development | review | testing | documentation
+  difficulty: intermediate    # beginner | intermediate | advanced
+  estimated_steps: 6          # Approximate number of steps
+
+# Prerequisites
+prerequisites:
+  - Project initialized with UDS
+  - Git repository configured
+  - AI tool with Task support (recommended)
+
+# Steps definition
+steps:
+  - id: step-1
+    name: Step Name
+    description: What this step does
+    type: agent               # agent | manual | conditional
+    agent: agent-name         # Required if type=agent
+    inputs:                   # Optional: what this step needs
+      - user_requirements
+    outputs:                  # Optional: what this step produces
+      - analysis_report
+
+  - id: step-2
+    name: Manual Step
+    type: manual
+    description: Human intervention required
+    instructions: |
+      Detailed instructions for the manual step.
+    checklist:
+      - [ ] Item 1
+      - [ ] Item 2
+
+  - id: step-3
+    name: Conditional Step
+    type: conditional
+    condition: analysis_report.has_issues
+    then:
+      agent: reviewer
+      task: Review and fix issues
+    else:
+      skip: true
+
+# Output artifacts
+outputs:
+  - name: final_report
+    description: Generated documentation
+    format: markdown
+```
+
+### RLM Context Configuration (v1.1.0)
+
+Workflows can include RLM-inspired context handling for large codebases:
+
+```yaml
+# === RLM CONTEXT CONFIGURATION ===
+context-strategy:
+  enable-rlm: true                    # Enable RLM-aware processing
+  max-context-per-step: 100000        # Maximum tokens per step
+  context-inheritance: selective      # full | selective | summary
+
+steps:
+  - id: parallel-analysis
+    type: parallel-agents             # NEW: Execute agent on multiple inputs
+    agent: code-architect
+    foreach: ${modules}               # Dynamic iteration variable
+    context-mode: focused             # minimal | focused | full
+    merge-strategy: aggregate         # aggregate | sequential | summary
+    outputs: [analysis_results]
+```
+
+#### Context Inheritance Modes
+
+| Mode | Description | Use Case |
+|------|-------------|----------|
+| `full` | Pass all previous outputs to next step | Sequential analysis |
+| `selective` | Pass only specified outputs | Memory-efficient pipelines |
+| `summary` | Pass summarized version of outputs | Large-scale processing |
+
+#### Context Modes for Steps
+
+| Mode | Description | Token Usage |
+|------|-------------|-------------|
+| `minimal` | Only essential context | Low |
+| `focused` | Context relevant to current item | Medium |
+| `full` | Complete available context | High |
+
+#### Merge Strategies for Parallel Results
+
+| Strategy | Description | Output Format |
+|----------|-------------|---------------|
+| `aggregate` | Combine all results into array | Array of results |
+| `sequential` | Maintain processing order | Ordered list |
+| `summary` | AI-generated summary of all results | Single summary |
+
+### Step Types
+
+| Type | Description | Execution |
+|------|-------------|-----------|
+| `agent` | Executed by a UDS agent | Automatic |
+| `manual` | Requires human intervention | Interactive |
+| `conditional` | Branching based on conditions | Depends on condition |
+| `parallel-agents` | Execute agent on multiple inputs concurrently | Parallel (v1.1.0) |
+
+#### Parallel-Agents Step Configuration (v1.1.0)
+
+```yaml
+- id: parallel-module-analysis
+  name: Analyze Modules in Parallel
+  type: parallel-agents
+  agent: code-architect
+  foreach: ${modules}           # Variable containing items to iterate
+  context-mode: focused         # minimal | focused | full
+  merge-strategy: aggregate     # How to combine results
+  max-concurrent: 3             # Optional: limit concurrent executions
+  timeout: 300                  # Optional: timeout per item (seconds)
+  inputs:                       # Optional: additional inputs
+    - project_context
+  outputs:
+    - module_analysis_results
+```
+
+## Built-in Workflows
+
+| Workflow | Steps | Description |
+|----------|-------|-------------|
+| [integrated-flow](./integrated-flow.workflow.yaml) | 8 | Complete ATDD → SDD → BDD → TDD cycle |
+| [feature-dev](./feature-dev.workflow.yaml) | 6 | Feature development workflow |
+| [code-review](./code-review.workflow.yaml) | 4 | Comprehensive code review workflow |
+| [large-codebase-analysis](./large-codebase-analysis.workflow.yaml) | 4 | RLM-enhanced workflow for analyzing 50+ file projects |
+
+## Usage
+
+### CLI Installation
+
+```bash
+# List available workflows
+uds workflow list
+
+# Install specific workflow
+uds workflow install integrated-flow
+
+# Install all workflows
+uds workflow install --all
+```
+
+### Execution
+
+Workflows are executed step-by-step. For tools supporting Task tool (Claude Code, OpenCode):
+
+```
+User: Start the integrated-flow workflow for user authentication
+
+AI: Starting Integrated Development Flow...
+
+Step 1/8: Specification Workshop (spec-analyst)
+[Agent executes analysis...]
+
+Step 2/8: Spec Proposal (spec-analyst)
+[Agent drafts proposal...]
+
+Step 3/8: Spec Review (manual)
+Please review the specification:
+- [ ] Requirements are clear
+- [ ] Acceptance criteria defined
+- [ ] Risks identified
+
+[User confirms...]
+
+Step 4/8: Discovery (test-specialist)
+[Agent identifies test scenarios...]
+
+...continues...
+```
+
+### For Tools Without Task Support
+
+Workflows are converted to guided checklists:
+
+```markdown
+## Integrated Development Flow
+
+### Step 1: Specification Workshop
+**Agent**: spec-analyst
+**Task**: Analyze requirements and identify acceptance criteria
+
+[Copy this to your AI assistant]
+
+### Step 2: Spec Proposal
+...
+```
+
+## Creating Custom Workflows
+
+### 1. Create Workflow File
+
+```bash
+mkdir -p .claude/workflows
+touch .claude/workflows/my-workflow.workflow.yaml
+```
+
+### 2. Define Workflow
+
+```yaml
+name: my-custom-workflow
+version: 1.0.0
+description: Custom workflow for my project
+
+steps:
+  - id: analyze
+    name: Analyze Requirements
+    type: agent
+    agent: spec-analyst
+    outputs: [requirements_doc]
+
+  - id: implement
+    name: Implementation
+    type: manual
+    description: Implement based on analysis
+
+  - id: review
+    name: Code Review
+    type: agent
+    agent: reviewer
+    inputs: [code_changes]
+```
+
+## Workflow vs Agent vs Skill
+
+| Aspect | Workflow | Agent | Skill |
+|--------|----------|-------|-------|
+| **Purpose** | Orchestrate multi-step processes | Execute autonomous tasks | Provide knowledge/context |
+| **Composition** | Contains multiple agents | Uses skills as context | Standalone |
+| **State** | Tracks progress across steps | Single task state | Stateless |
+| **User Involvement** | Can include manual steps | Minimal | None |
+
+## Best Practices
+
+### Do's
+
+- Break complex tasks into discrete steps
+- Include manual checkpoints for critical decisions
+- Define clear inputs/outputs for each step
+- Use conditional steps for error handling
+- Document prerequisites clearly
+
+### Don'ts
+
+- Don't create overly long workflows (>10 steps)
+- Don't skip review/verification steps
+- Don't assume all tools support automatic execution
+- Don't make steps too granular
+
+---
+
+## Related Resources
+
+- [Agents Documentation](../agents/README.md)
+- [Skills Documentation](../README.md)
+- [Methodology System](../methodology-system/SKILL.md)
+
+---
+
+## Version History
+
+| Version | Date | Changes |
+|---------|------|---------|
+| 1.1.0 | 2026-01-21 | Added RLM context configuration, parallel-agents step type, large-codebase-analysis workflow |
+| 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)

package/bundled/skills/workflows/code-review.workflow.yaml

@@ -0,0 +1,186 @@
+# Code Review Workflow
+# Comprehensive code review process
+#
+# This workflow guides a thorough code review process,
+# ensuring quality, security, and maintainability.
+
+name: code-review
+version: 1.0.0
+description: |
+  Comprehensive code review workflow for PRs and code changes.
+  Use for thorough review before merging to main branch.
+  Keywords: code review, PR review, pull request, 程式碼審查, PR 審查.
+
+metadata:
+  author: universal-dev-standards
+  category: review
+  difficulty: intermediate
+  estimated_steps: 4
+  related_skills:
+    - code-review-assistant
+    - testing-guide
+    - checkin-assistant
+
+prerequisites:
+  - Pull request created
+  - CI checks passing (or reasons documented)
+  - PR description complete
+
+steps:
+  # Step 1: Context Understanding
+  - id: understand
+    name: Understand Context
+    type: agent
+    agent: spec-analyst
+    description: |
+      Understand the purpose and scope of the changes.
+      Review PR description, linked issues, and specs.
+    inputs:
+      - pr_description
+      - linked_issues
+      - diff_summary
+    outputs:
+      - context_summary
+      - review_focus_areas
+    questions:
+      - What problem does this solve?
+      - What is the expected behavior?
+      - What are the risks?
+
+  # Step 2: Code Quality Review
+  - id: quality-review
+    name: Code Quality Review
+    type: agent
+    agent: reviewer
+    description: |
+      Review code for quality, maintainability, and best practices.
+      Focus on readability, design patterns, and conventions.
+    inputs:
+      - code_changes
+      - context_summary
+    outputs:
+      - quality_report
+      - suggestions
+    checklist:
+      - Code follows project style guide
+      - Functions are appropriately sized
+      - No code duplication
+      - Error handling is appropriate
+      - Naming is clear and consistent
+      - Comments are helpful (not redundant)
+    severity_levels:
+      blocking: Must fix before merge
+      important: Should fix
+      suggestion: Nice to have
+      note: Informational
+
+  # Step 3: Security & Testing Review
+  - id: security-review
+    name: Security & Testing Review
+    type: agent
+    agent: test-specialist
+    description: |
+      Review for security vulnerabilities and test coverage.
+      Ensure changes are properly tested.
+    inputs:
+      - code_changes
+      - existing_tests
+    outputs:
+      - security_report
+      - coverage_assessment
+    security_checks:
+      - No hardcoded secrets
+      - Input validation present
+      - No SQL injection vulnerabilities
+      - No XSS vulnerabilities
+      - Proper authentication/authorization
+      - Dependencies are safe
+    testing_checks:
+      - New code has tests
+      - Edge cases covered
+      - Tests are meaningful (not just coverage)
+      - No flaky tests introduced
+
+  # Step 4: Final Decision
+  - id: decision
+    name: Review Decision
+    type: manual
+    description: |
+      Make final review decision based on findings.
+      Approve, request changes, or discuss.
+    inputs:
+      - quality_report
+      - security_report
+      - coverage_assessment
+    outputs:
+      - review_decision
+      - feedback_comments
+    decisions:
+      approve:
+        condition: No blocking issues
+        action: Approve PR
+      request_changes:
+        condition: Blocking issues found
+        action: Request changes with clear feedback
+      comment:
+        condition: Need clarification
+        action: Add comments and discuss
+    instructions: |
+      When providing feedback:
+      1. Use appropriate prefixes (BLOCKING, IMPORTANT, SUGGESTION)
+      2. Be specific about location and issue
+      3. Suggest solutions when possible
+      4. Be respectful and constructive
+      5. Acknowledge good practices
+
+outputs:
+  - name: review_summary
+    description: Summary of review findings
+    format: markdown
+
+  - name: action_items
+    description: List of changes requested
+    format: checklist
+
+  - name: decision
+    description: Final review decision
+    format: status
+
+# Review comment templates
+comment_templates:
+  blocking: |
+    ❗ BLOCKING: [Issue description]
+
+    [Why this is a problem]
+
+    Suggested fix:
+    ```
+    [code suggestion]
+    ```
+
+  important: |
+    ⚠️ IMPORTANT: [Issue description]
+
+    [Why this should be addressed]
+
+  suggestion: |
+    💡 SUGGESTION: [Improvement idea]
+
+    [Rationale and benefits]
+
+  question: |
+    ❓ QUESTION: [Your question]
+
+    [Context for the question]
+
+  note: |
+    📝 NOTE: [Observation]
+
+    [Additional context]
+
+completion_criteria:
+  - All critical issues addressed or waived
+  - Security review completed
+  - Test coverage acceptable
+  - Review decision documented
+  - Feedback provided constructively

package/bundled/skills/workflows/feature-dev.workflow.yaml

@@ -0,0 +1,174 @@
+# Feature Development Workflow
+# Standard workflow for developing new features
+#
+# This workflow guides the development of new features from requirements
+# through implementation and review.
+
+name: feature-dev
+version: 1.0.0
+description: |
+  Standard feature development workflow from requirements to deployment.
+  Use for typical feature work with balanced rigor and efficiency.
+  Keywords: feature, development, implementation, 功能開發, 開發流程.
+
+metadata:
+  author: universal-dev-standards
+  category: development
+  difficulty: intermediate
+  estimated_steps: 6
+  related_skills:
+    - spec-driven-dev
+    - testing-guide
+    - code-review-assistant
+
+prerequisites:
+  - User story or feature request defined
+  - Git branch created (feature/xxx)
+  - Development environment ready
+
+steps:
+  # Step 1: Requirements Analysis
+  - id: analyze
+    name: Analyze Requirements
+    type: agent
+    agent: spec-analyst
+    description: |
+      Analyze the feature request and clarify requirements.
+      Identify acceptance criteria and potential challenges.
+    inputs:
+      - feature_request
+      - existing_codebase_context
+    outputs:
+      - requirements_analysis
+      - acceptance_criteria
+      - technical_considerations
+    checklist:
+      - Requirements understood
+      - Questions clarified
+      - Scope defined
+
+  # Step 2: Architecture Design
+  - id: design
+    name: Design Architecture
+    type: agent
+    agent: code-architect
+    description: |
+      Design the technical architecture for the feature.
+      Identify components, interfaces, and data flow.
+    inputs:
+      - requirements_analysis
+      - existing_architecture
+    outputs:
+      - architecture_design
+      - component_list
+      - api_contracts
+    considerations:
+      - Reuse existing components where possible
+      - Follow project patterns and conventions
+      - Consider performance and scalability
+
+  # Step 3: Test Planning
+  - id: test-plan
+    name: Plan Tests
+    type: agent
+    agent: test-specialist
+    description: |
+      Define testing strategy for the feature.
+      Identify test cases at different levels.
+    inputs:
+      - acceptance_criteria
+      - architecture_design
+    outputs:
+      - test_plan
+      - test_cases
+    test_levels:
+      - unit: Core logic functions
+      - integration: Component interactions
+      - e2e: Critical user paths
+
+  # Step 4: Implementation
+  - id: implement
+    name: Implement Feature
+    type: manual
+    description: |
+      Implement the feature following the design and test plan.
+      Use TDD approach where appropriate.
+    inputs:
+      - architecture_design
+      - test_plan
+    outputs:
+      - implementation_code
+      - tests
+    instructions: |
+      Implementation guidelines:
+      1. Start with tests (TDD recommended)
+      2. Implement core functionality first
+      3. Add edge case handling
+      4. Run tests frequently
+      5. Commit in logical chunks
+    checklist:
+      - Core functionality implemented
+      - Unit tests written and passing
+      - Integration tests passing
+      - No linting errors
+      - Code committed
+
+  # Step 5: Self Review
+  - id: self-review
+    name: Self Code Review
+    type: agent
+    agent: reviewer
+    description: |
+      Perform self-review before requesting peer review.
+      Check for common issues and improvements.
+    inputs:
+      - implementation_code
+      - tests
+    outputs:
+      - self_review_report
+      - improvement_suggestions
+    focus_areas:
+      - Code quality and style
+      - Test coverage
+      - Security considerations
+      - Performance implications
+
+  # Step 6: Documentation
+  - id: document
+    name: Update Documentation
+    type: agent
+    agent: doc-writer
+    description: |
+      Update relevant documentation for the new feature.
+      Include API docs, user guides, and changelog.
+    inputs:
+      - implementation_code
+      - architecture_design
+    outputs:
+      - updated_docs
+      - changelog_entry
+    documentation_types:
+      - API documentation
+      - User-facing documentation
+      - CHANGELOG entry
+      - README updates (if needed)
+
+outputs:
+  - name: feature_branch
+    description: Git branch with implemented feature
+    format: git-branch
+
+  - name: test_suite
+    description: Tests for the feature
+    format: varies
+
+  - name: documentation
+    description: Updated documentation
+    format: markdown
+
+completion_criteria:
+  - All acceptance criteria met
+  - Tests passing
+  - Self-review completed
+  - Documentation updated
+  - Ready for peer review/PR