universal-dev-standards 3.5.1-beta.1 → 3.5.1-beta.11

package/bundled/skills/claude-code/methodology-system/runtime.md

@@ -0,0 +1,271 @@
+# Methodology Runtime Guide
+
+> **Language**: English | [繁體中文](../../../locales/zh-TW/skills/claude-code/methodology-system/runtime.md)
+
+> [!WARNING]
+> **Experimental Feature / 實驗性功能**
+>
+> This feature is under active development and may change significantly in v4.0.
+> 此功能正在積極開發中，可能在 v4.0 中有重大變更。
+
+**Version**: 1.0.0
+**Last Updated**: 2026-01-12
+
+---
+
+## Overview
+
+This document defines how AI assistants should behave when a development methodology is active. It provides guidance for phase tracking, checkpoint handling, and user interaction.
+
+---
+
+## AI Behavior Specification
+
+### 1. Context Awareness
+
+When a methodology is active, the AI should:
+
+- **Always know the current phase**
+- **Display phase indicator in responses**
+- **Suggest phase-appropriate actions**
+
+#### Phase Status Display
+
+Include methodology status at the start of relevant responses:
+
+```
+┌────────────────────────────────────────────────┐
+│ 📋 Methodology: TDD                             │
+│ 📍 Phase: 🔴 RED (writing failing test)         │
+│ ⏱️  Duration: 3 minutes                         │
+└────────────────────────────────────────────────┘
+```
+
+### 2. Proactive Guidance
+
+Provide context-appropriate suggestions based on current phase:
+
+```markdown
+**Current Phase: 🔴 RED (TDD)**
+
+You're writing a failing test for: user login validation
+
+**Next step**: Write a test that describes the expected behavior.
+
+Would you like me to:
+1. Generate a test skeleton
+2. Show TDD best practices for this scenario
+3. Continue with your manual approach
+```
+
+### 3. Phase Transition Detection
+
+Monitor for conditions that indicate phase transitions:
+
+| Signal | Transition |
+|--------|------------|
+| Test execution fails | RED → ready for GREEN |
+| All tests pass | GREEN → ready for REFACTOR |
+| User confirms refactor done | REFACTOR → next cycle or DONE |
+| Time elapsed exceeds phase duration | Display reminder |
+| Git commit detected | Reset phase timer |
+
+### 4. Checkpoint Behavior
+
+When checkpoint conditions are triggered, display checkpoint notification:
+
+```
+┌────────────────────────────────────────────────┐
+│ 🔔 Methodology Checkpoint                       │
+├────────────────────────────────────────────────┤
+│ GREEN phase completed                          │
+│                                                │
+│ Checklist Status:                              │
+│   ✅ Minimum code written                      │
+│   ✅ Test passes                               │
+│   ✅ All other tests pass                      │
+│   ⬜ (Optional) Consider edge cases            │
+│                                                │
+│ Change Statistics:                             │
+│   - Files: 3                                   │
+│   - Added: 45 lines                            │
+│   - Deleted: 2 lines                           │
+│                                                │
+│ Suggested commit:                              │
+│   test(auth): add email validation test        │
+│   feat(auth): implement email validation       │
+│                                                │
+│ Options:                                       │
+│   [1] Commit now (show git commands)           │
+│   [2] Continue to REFACTOR phase               │
+│   [3] View detailed changes                    │
+└────────────────────────────────────────────────┘
+```
+
+### 5. Skip Tracking
+
+Track consecutive skips and warn appropriately:
+
+| Skip Count | Action |
+|------------|--------|
+| 1-2 | No action, record skip |
+| 3 | Warning notification |
+| 4+ | Strong warning, recommend commit |
+
+#### Skip Warning Display
+
+```
+┌────────────────────────────────────────────────┐
+│ ⚠️ Skip Warning                                 │
+├────────────────────────────────────────────────┤
+│ You have skipped check-in 3 times consecutively│
+│                                                │
+│ Current accumulated changes:                   │
+│   - Files: 8                                   │
+│   - Added: 320 lines                           │
+│   - Deleted: 45 lines                          │
+│                                                │
+│ Recommendation: Commit your changes now to     │
+│ avoid losing work and maintain atomic commits. │
+│                                                │
+│ [1] Commit now  [2] Skip anyway  [3] View diff │
+└────────────────────────────────────────────────┘
+```
+
+---
+
+## Methodology Detection
+
+### Automatic Detection
+
+AI should detect methodology context from:
+
+1. **Manifest Configuration**
+   ```json
+   // .standards/manifest.json
+   { "methodology": { "active": "tdd" } }
+   ```
+
+2. **Keyword Detection**
+   - "Let's use TDD for this"
+   - "Write a failing test first"
+   - "Given-When-Then"
+   - "Create a spec for this change"
+
+3. **Command Invocation**
+   - `/tdd`, `/bdd`, `/spec`, `/atdd`
+   - `/methodology switch <id>`
+
+### Loading Methodology Definition
+
+```
+Methodology Loading Priority:
+1. Custom: .standards/methodologies/{id}.methodology.yaml
+2. Built-in: methodologies/{id}.methodology.yaml
+3. Fallback: Generic phase-less workflow
+```
+
+---
+
+## Checklist Management
+
+### Display Format
+
+```markdown
+### Phase Checklist
+
+**Required:**
+- [ ] Test describes expected behavior
+- [x] Test name is clear
+- [ ] Test follows AAA pattern
+
+**Optional:**
+- [ ] Consider edge cases
+```
+
+### Tracking
+
+- Update checklist items based on user actions and code analysis
+- Block phase transition if required items incomplete (strict mode)
+- Log completion for audit trail
+
+---
+
+## Integration Points
+
+### With Git
+
+- Detect commits to reset phase timers
+- Suggest commit messages based on methodology
+- Include spec/story references automatically
+
+### With Test Runner
+
+- Detect test pass/fail to trigger phase transitions
+- Report test coverage relevant to current phase
+
+### With Code Review
+
+- Add methodology-specific review checks
+- Reference active methodology in PR description
+
+---
+
+## Error Handling
+
+### Methodology Not Found
+
+```
+⚠️ Methodology 'custom-workflow' not found.
+
+Available methodologies:
+- tdd (built-in)
+- bdd (built-in)
+- sdd (built-in)
+- atdd (built-in)
+
+Use `/methodology list` to see all options.
+```
+
+### Invalid Phase Transition
+
+```
+⚠️ Cannot transition from RED to REFACTOR.
+
+TDD requires: RED → GREEN → REFACTOR
+
+Current phase: RED
+Valid next phases: GREEN
+
+Complete the RED phase checklist first.
+```
+
+---
+
+## Performance Considerations
+
+- Cache methodology definitions after first load
+- Only reload when manifest changes
+- Minimize checkpoint frequency to avoid interruption
+- Batch git status checks
+
+---
+
+## Localization
+
+All user-facing text should use the appropriate language field:
+
+```yaml
+# If user's locale is zh-TW
+name: nameZh || name
+description: descriptionZh || description
+prompt: promptZh || prompt
+```
+
+---
+
+## Version History
+
+| Version | Date | Changes |
+|---------|------|---------|
+| 1.0.0 | 2026-01-12 | Initial runtime specification |

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

@@ -0,0 +1,143 @@
+---
+name: project-structure-guide
+description: |
+  Guide for organizing project directories following language-specific best practices.
+  Use when: creating projects, reorganizing structure, adding modules, setting up builds.
+  Keywords: project, structure, directory, layout, gitignore, scaffold, 專案結構, 目錄.
+---
+
+# Project Structure Guide
+
+> **Language**: English | [繁體中文](../../../locales/zh-TW/skills/claude-code/project-structure-guide/SKILL.md)
+
+**Version**: 1.0.0
+**Last Updated**: 2025-12-30
+**Applicability**: Claude Code Skills
+
+---
+
+## Purpose
+
+This skill provides guidance on structuring projects according to language and framework conventions. It helps create consistent, maintainable directory layouts.
+
+## Trigger
+
+Use this skill when:
+- Creating a new project
+- Reorganizing existing project structure
+- Adding new modules or features
+- Setting up build configuration
+- Creating .gitignore files
+
+## Supported Languages
+
+| Language | Frameworks/Patterns |
+|----------|---------------------|
+| Node.js | Express, NestJS, Next.js |
+| Python | Django, Flask, FastAPI |
+| Java | Spring Boot, Maven, Gradle |
+| .NET | ASP.NET Core, Console |
+| Go | Standard layout, cmd/pkg |
+| Rust | Binary, Library, Workspace |
+| Kotlin | Gradle, Android, Multiplatform |
+| PHP | Laravel, Symfony, PSR-4 |
+| Ruby | Rails, Gem, Sinatra |
+| Swift | SPM, iOS App, Vapor |
+
+## Common Structure Patterns
+
+### Standard Directories
+
+```
+project-root/
+├── src/              # Source code
+├── tests/            # Test files
+├── docs/             # Documentation
+├── tools/            # Build/deployment scripts
+├── examples/         # Usage examples
+├── config/           # Configuration files
+└── .github/          # GitHub configuration
+```
+
+### Build Output (Always gitignore)
+
+```
+dist/                 # Distribution output
+build/                # Compiled artifacts
+out/                  # Output directory
+bin/                  # Binary executables
+```
+
+## Language-Specific Guidelines
+
+### Node.js
+
+```
+project/
+├── src/
+│   ├── index.js
+│   ├── routes/
+│   ├── controllers/
+│   ├── services/
+│   └── models/
+├── tests/
+├── package.json
+└── .gitignore
+```
+
+### Python
+
+```
+project/
+├── src/
+│   └── package_name/
+│       ├── __init__.py
+│       └── main.py
+├── tests/
+├── pyproject.toml
+└── .gitignore
+```
+
+### Go
+
+```
+project/
+├── cmd/
+│   └── appname/
+│       └── main.go
+├── internal/
+├── pkg/
+├── go.mod
+└── .gitignore
+```
+
+## Quick Actions
+
+### Create Project Structure
+
+When asked to create a project:
+1. Ask for language/framework
+2. Generate appropriate directory structure
+3. Create essential config files
+4. Generate .gitignore
+
+### Review Structure
+
+When reviewing existing structure:
+1. Check language conventions
+2. Verify gitignore patterns
+3. Suggest improvements
+4. Identify misplaced files
+
+## Rules
+
+1. **Follow language conventions** - Each language has established patterns
+2. **Separate concerns** - Keep source, tests, docs separate
+3. **Gitignore build outputs** - Never commit dist/, build/, out/
+4. **Consistent naming** - Use language-appropriate casing
+5. **Config at root** - Place config files at project root
+
+## Related Standards
+
+- [Core: Project Structure](../../../core/project-structure.md)
+- [AI: Project Structure Options](../../../ai/options/project-structure/)

package/bundled/skills/claude-code/project-structure-guide/language-patterns.md

@@ -0,0 +1,263 @@
+# Language-Specific Project Patterns
+
+Quick reference for project structures by language.
+
+## Node.js / TypeScript
+
+### Express/NestJS API
+
+```
+project/
+├── src/
+│   ├── index.ts
+│   ├── app.ts
+│   ├── config/
+│   ├── routes/
+│   ├── controllers/
+│   ├── services/
+│   ├── models/
+│   ├── middleware/
+│   └── utils/
+├── tests/
+│   ├── unit/
+│   └── integration/
+├── package.json
+├── tsconfig.json
+└── .gitignore
+```
+
+### Next.js
+
+```
+project/
+├── app/                  # App Router (Next.js 13+)
+│   ├── layout.tsx
+│   ├── page.tsx
+│   └── api/
+├── components/
+├── lib/
+├── public/
+├── package.json
+└── next.config.js
+```
+
+## Python
+
+### FastAPI / Flask
+
+```
+project/
+├── src/
+│   └── app/
+│       ├── __init__.py
+│       ├── main.py
+│       ├── config.py
+│       ├── routers/
+│       ├── services/
+│       ├── models/
+│       └── schemas/
+├── tests/
+├── pyproject.toml
+├── requirements.txt
+└── .gitignore
+```
+
+### Django
+
+```
+project/
+├── project_name/
+│   ├── __init__.py
+│   ├── settings.py
+│   ├── urls.py
+│   └── wsgi.py
+├── apps/
+│   └── app_name/
+├── templates/
+├── static/
+├── manage.py
+└── requirements.txt
+```
+
+## Go
+
+### Standard Layout
+
+```
+project/
+├── cmd/
+│   └── appname/
+│       └── main.go
+├── internal/
+│   ├── app/
+│   ├── handler/
+│   ├── service/
+│   └── repository/
+├── pkg/
+├── api/
+├── configs/
+├── go.mod
+├── go.sum
+└── Makefile
+```
+
+## Rust
+
+### Binary Application
+
+```
+project/
+├── src/
+│   ├── main.rs
+│   ├── lib.rs
+│   ├── config.rs
+│   └── modules/
+├── tests/
+├── benches/
+├── Cargo.toml
+└── Cargo.lock
+```
+
+### Workspace
+
+```
+project/
+├── crates/
+│   ├── core/
+│   ├── api/
+│   └── cli/
+├── Cargo.toml
+└── Cargo.lock
+```
+
+## Kotlin
+
+### Spring Boot
+
+```
+project/
+├── src/
+│   ├── main/
+│   │   ├── kotlin/
+│   │   │   └── com/example/
+│   │   └── resources/
+│   └── test/
+├── build.gradle.kts
+└── settings.gradle.kts
+```
+
+### Android
+
+```
+project/
+├── app/
+│   ├── src/
+│   │   ├── main/
+│   │   ├── test/
+│   │   └── androidTest/
+│   └── build.gradle.kts
+├── build.gradle.kts
+└── settings.gradle.kts
+```
+
+## PHP
+
+### Laravel
+
+```
+project/
+├── app/
+│   ├── Http/
+│   ├── Models/
+│   └── Services/
+├── config/
+├── database/
+├── public/
+├── resources/
+├── routes/
+├── tests/
+├── composer.json
+└── artisan
+```
+
+## Ruby
+
+### Rails
+
+```
+project/
+├── app/
+│   ├── controllers/
+│   ├── models/
+│   ├── views/
+│   └── services/
+├── config/
+├── db/
+├── lib/
+├── spec/
+├── Gemfile
+└── Rakefile
+```
+
+## Swift
+
+### iOS App (SwiftUI)
+
+```
+project/
+├── AppName/
+│   ├── App/
+│   ├── Features/
+│   ├── Core/
+│   └── Resources/
+├── AppNameTests/
+├── AppNameUITests/
+└── AppName.xcodeproj
+```
+
+### SPM Package
+
+```
+project/
+├── Sources/
+│   └── PackageName/
+├── Tests/
+│   └── PackageNameTests/
+├── Package.swift
+└── README.md
+```
+
+## Gitignore Essentials
+
+### Universal
+
+```gitignore
+# Build outputs
+dist/
+build/
+out/
+bin/
+
+# Environment
+.env
+.env.*
+
+# IDE
+.idea/
+.vscode/
+*.swp
+
+# OS
+.DS_Store
+Thumbs.db
+```
+
+### Language-Specific
+
+| Language | Patterns |
+|----------|----------|
+| Node.js | node_modules/, *.log |
+| Python | __pycache__/, *.pyc, .venv/ |
+| Go | vendor/ (if not using modules) |
+| Rust | target/, Cargo.lock (for libraries) |
+| Java/.NET | *.class, bin/, obj/ |