universal-dev-standards 5.0.0-rc.8 → 5.0.0

package/bundled/skills/spec-driven-dev/guide.md

@@ -3,15 +3,15 @@ scope: universal
 description: |
   Guide Spec-Driven Development (SDD) workflow for planning changes before implementation.
   Use when: creating specs, proposals, planning features, using OpenSpec or similar tools.
-  Keywords: spec, specification, SDD, proposal, openspec, design doc, 規格, 提案, 設計文件.
+  Keywords: spec, specification, SDD, proposal, openspec, spec-kit, design doc, 規格, 提案, 設計文件.
 ---
 
 # Spec-Driven Development Guide
 
 > **Language**: English | [繁體中文](../../locales/zh-TW/skills/spec-driven-dev/SKILL.md)
 
-**Version**: 1.1.0
-**Last Updated**: 2026-01-26
+**Version**: 1.2.0
+**Last Updated**: 2026-03-23
 **Applicability**: Claude Code Skills
 
 ---
@@ -20,6 +20,14 @@ description: |
 
 This skill guides you through Spec-Driven Development (SDD), ensuring changes are planned, documented, and approved before implementation.
 
+## Session Start Protocol
+
+At the start of each session:
+
+1. **Check for active specs**: Search `docs/specs/`, `specs/`, `openspec/changes/`, or `.specify/` for in-progress work
+2. **If active specs found** → Inform user and offer to resume
+3. **Review context** before starting new work
+
 ## Quick Reference
 
 ### SDD Workflow
@@ -46,6 +54,18 @@ This skill guides you through Spec-Driven Development (SDD), ensuring changes ar
 | **Verification** | Confirm implementation matches spec (max 3 iterations) | Test results, traceability matrix |
 | **Archive** | Close and archive | Archived spec with links |
 
+### Workflow Enforcement Gates
+
+**CRITICAL**: Before executing any workflow phase, you MUST check prerequisites.
+
+| Phase | Prerequisite | On Failure |
+|-------|-------------|------------|
+| Proposal | Discuss completed, scope locked | → Complete Discuss stage first |
+| Implementation | Spec status = Approved | → Get approval first |
+| Verification | All ACs have code + tests | → Complete implementation first |
+| Commit (feat/fix) | Check active specs | → Suggest spec reference (Refs: SPEC-XXX) |
+| Archive | All tasks completed, verified | → Complete remaining tasks |
+
 ### Core Principles
 
 | Principle | Description |
@@ -55,6 +75,7 @@ This skill guides you through Spec-Driven Development (SDD), ensuring changes ar
 | **Tool Priority** | Use SDD tool commands when available |
 | **Methodology > Tooling** | SDD works with any tool or manual process |
 | **Bidirectional Sync** | Changes propagate to all related artifacts |
+| **Simplicity First** | Choose the simplest solution that works |
 
 ### Pre-Spec Evaluation
 
@@ -66,10 +87,114 @@ Before creating a specification, answer these questions:
 | **Interactive?** | Yes / No | Determines if Skill needed |
 | **User-triggered?** | Yes / No | Determines if Command needed |
 
+### Before Creating Specs
+
+- Always check if a similar spec already exists in the project
+- Search existing specs directory before creating new ones
+- Prefer modifying existing specs over creating duplicates
+- If request is ambiguous, ask 1-2 clarifying questions before proceeding
+
 ### Exceptions to "Spec First"
 
 - Critical hotfixes (restore service immediately, document later)
 - Trivial changes (typos, comments, formatting)
+- Dependency updates (non-breaking)
+- Configuration changes
+
+## Detailed Stage Guidelines
+
+### Discuss Stage
+
+The Discuss stage ensures all ambiguities are resolved before writing a spec.
+
+#### 1. Establish Governing Principles
+
+Define project conventions, constraints, and non-negotiables upfront:
+
+- What are the project's core architectural decisions?
+- What are the non-negotiable constraints (performance, security, compatibility)?
+- Document in `project.md`, `CONTRIBUTING.md`, or equivalent
+
+#### 2. Structured Clarification
+
+List all ambiguous points as explicit questions and resolve each before proceeding:
+
+```markdown
+## Clarification Log
+
+| # | Question | Options | Decision | Rationale |
+|---|----------|---------|----------|-----------|
+| 1 | Auth method? | OAuth2 / JWT / Session | OAuth2 | Industry standard, SSO support |
+| 2 | Token storage? | Cookie / LocalStorage | HttpOnly Cookie | XSS protection |
+```
+
+#### 3. Lock Scope
+
+- Define what is IN scope and what is OUT of scope
+- Identify related specs that may be affected
+- Build a `read_first` list of files/specs to review
+
+### Implementation Stage
+
+Follow a structured approach during implementation:
+
+1. **Read proposal/spec thoroughly** — Understand all requirements and AC
+2. **Create tasks checklist** — Break down into sequential tasks (in `tasks.md` or within the spec)
+3. **Implement tasks sequentially** — Complete each task in order
+4. **Update checklist after each completion** — Mark tasks as done
+5. **Do NOT skip to next phase** until all tasks are completed
+
+### Requirement Wording
+
+Use precise language in specifications:
+
+| Keyword | Meaning | Usage |
+|---------|---------|-------|
+| **SHALL/MUST** | Mandatory requirement | "The system SHALL validate input" |
+| **SHOULD** | Recommended practice | "The API SHOULD return within 200ms" |
+| **MAY** | Optional feature | "The UI MAY display a loading spinner" |
+
+Avoid ambiguous words: "should try", "might need", "could possibly"
+
+## Simplicity First
+
+### Default Principles
+
+- Default to <100 lines of new code per change
+- Single-file implementations until proven insufficient
+- Avoid frameworks without clear justification
+- Choose boring, proven patterns over novel approaches
+
+### Complexity Triggers
+
+Only add complexity when you have concrete evidence:
+
+| Trigger | Evidence Required |
+|---------|-------------------|
+| Performance optimization | Profiling data showing bottleneck |
+| Abstraction layer | 3+ concrete use cases requiring it |
+| External dependency | Clear justification over built-in solution |
+| Multi-service split | Scale requirements (>1000 users, >100MB data) |
+
+## Naming Conventions
+
+### Spec IDs
+
+- Format: `SPEC-NNN` (e.g., `SPEC-001`, `SPEC-042`)
+- Sequential within the project
+
+### Change IDs
+
+- Format: kebab-case, verb-led
+- Prefixes: `add-`, `update-`, `remove-`, `refactor-`
+- Examples: `add-two-factor-auth`, `update-payment-flow`, `remove-legacy-api`
+
+### Capability Names
+
+- Format: verb-noun (e.g., `user-auth`, `payment-capture`)
+- Single purpose per capability
+- 10-minute understandability rule: if it takes longer to understand, split it
+- Split if description needs "AND"
 
 ## Proposal Template
 
@@ -139,7 +264,7 @@ Reviewers should verify:
 
 ## Examples
 
-### ✅ Good Practices
+### Good Practices
 
 ```markdown
 # SPEC-001 Add OAuth2 Login
@@ -157,7 +282,7 @@ Add Google OAuth2 login to allow users to sign in with their Google accounts.
 - [ ] Existing users are linked to Google account
 ```
 
-### ❌ Bad Practices
+### Bad Practices
 
 ```markdown
 # Add login
@@ -170,12 +295,14 @@ Adding login.
 
 ## Common SDD Tools
 
-| Tool | Description | Command Examples |
-|------|-------------|------------------|
-| **OpenSpec** | Specification management | `/openspec proposal`, `/openspec approve` |
-| **Spec Kit** | Lightweight spec tracking | `/spec create`, `/spec close` |
+| Tool | Description | Key Commands |
+|------|-------------|--------------|
+| **OpenSpec** | Specification management CLI | `openspec list`, `openspec show`, `openspec validate`, `openspec archive` |
+| **Spec Kit** | Slash-command-driven SDD | `specify init`, `/specify`, `/clarify`, `/plan`, `/tasks`, `/implement` |
 | **Manual** | No tool, file-based | Create `specs/SPEC-XXX.md` manually |
 
+> **Note**: When an SDD tool is detected in the project, prioritize using its native commands over manual file editing for consistency and traceability.
+
 ## Sync Verification
 
 After completing a spec, verify synchronization:
@@ -205,21 +332,24 @@ After completing a spec, verify synchronization:
 
 ### Do's
 
-- ✅ Evaluate scope before creating spec
-- ✅ Keep specs focused and atomic (one change per spec)
-- ✅ Include clear acceptance criteria
-- ✅ Link specs to implementation PRs
-- ✅ Archive specs after completion
-- ✅ Verify sync status before closing
+- Evaluate scope before creating spec
+- Check for existing specs before creating new ones
+- Keep specs focused and atomic (one change per spec)
+- Include clear acceptance criteria with Given/When/Then
+- Use SHALL/MUST for normative requirements
+- Link specs to implementation PRs
+- Archive specs after completion
+- Verify sync status before closing
 
 ### Don'ts
 
-- ❌ Start coding before spec approval
-- ❌ Skip scope evaluation
-- ❌ Modify scope during implementation without updating spec
-- ❌ Leave specs in limbo (always close or archive)
-- ❌ Skip verification step
-- ❌ Forget to sync related artifacts
+- Start coding before spec approval
+- Skip scope evaluation or the Discuss stage
+- Modify scope during implementation without updating spec
+- Leave specs in limbo (always close or archive)
+- Skip verification step
+- Forget to sync related artifacts
+- Add complexity without concrete evidence of need
 
 ---
 
@@ -229,7 +359,10 @@ This skill supports project-specific configuration.
 
 ### Detection Order
 
-1. Check for SDD tool in workspace (OpenSpec, Spec Kit, etc.)
+1. Check for SDD tool in workspace:
+   - `openspec/` directory → OpenSpec detected
+   - `.specify/` directory → Spec Kit detected
+   - `specs/` or `docs/specs/` → Manual file-based workflow
 2. Check `CONTRIBUTING.md` for spec workflow documentation
 3. If not found, **default to manual file-based workflow**
 
@@ -269,6 +402,7 @@ See `specs/TEMPLATE.md`
 
 | Version | Date | Changes |
 |---------|------|---------|
+| 1.2.0 | 2026-03-23 | Added: Session Start Protocol, Workflow Enforcement Gates, Discuss Stage (Constitution + Clarify), Simplicity First, Naming Conventions, Implementation Stage enhancement, Requirement Wording, Search Guidance, updated Common SDD Tools |
 | 1.1.0 | 2026-01-26 | Added: Pre-Spec Evaluation, Sync Verification, Sync Matrix, enhanced best practices |
 | 1.0.0 | 2025-12-30 | Initial release |
 

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

@@ -72,3 +72,10 @@ After `/tdd` completes, the AI assistant should suggest:
 
 - Detailed guide: [guide.md](./guide.md)
 - Core standard: [test-driven-development.md](../../core/test-driven-development.md)
+
+
+## AI Agent Behavior | AI 代理行為
+
+> 完整的 AI 行為定義請參閱對應的命令文件：[`/tdd`](../commands/tdd.md#ai-agent-behavior--ai-代理行為)
+>
+> For complete AI agent behavior definition, see the corresponding command file: [`/tdd`](../commands/tdd.md#ai-agent-behavior--ai-代理行為)

package/bundled/skills/test-coverage-assistant/SKILL.md

@@ -12,6 +12,10 @@ Analyze test coverage across multiple dimensions and provide actionable recommen
 
 多維度分析測試覆蓋率並提供可執行的建議。
 
+> **Related**: For requirement-level coverage (which AC have tests?), use `/ac-coverage` instead. This skill (`/coverage`) focuses on code-level coverage (lines, branches, functions).
+>
+> **相關**：如需需求層級覆蓋率（哪些 AC 有對應測試？），請改用 `/ac-coverage`。此技能（`/coverage`）專注於程式碼層級覆蓋率。
+
 ## Coverage Dimensions | 覆蓋率維度
 
 | Dimension | What it Measures | 測量內容 |
@@ -70,3 +74,10 @@ After `/coverage` completes, the AI assistant should suggest:
 
 - Detailed guide: [guide.md](./guide.md)
 - Core standard: [test-completeness-dimensions.md](../../core/test-completeness-dimensions.md)
+
+
+## AI Agent Behavior | AI 代理行為
+
+> 完整的 AI 行為定義請參閱對應的命令文件：[`/coverage`](../commands/coverage.md#ai-agent-behavior--ai-代理行為)
+>
+> For complete AI agent behavior definition, see the corresponding command file: [`/coverage`](../commands/coverage.md#ai-agent-behavior--ai-代理行為)

package/bundled/skills/testing-guide/SKILL.md

@@ -21,6 +21,29 @@ description: |
 
 This skill provides testing pyramid standards and best practices for systematic testing, supporting both ISTQB and Industry Pyramid frameworks.
 
+## Testing Skills Navigator | 測試技能導航
+
+UDS provides 6 testing-related skills. Use this decision tree to find the right one:
+
+```
+What do you want to do? | 你想做什麼？
+├── Measure code coverage (lines/branches/functions)    → /coverage
+├── Track which requirements have tests (AC traceability) → /ac-coverage
+├── Develop with Test-Driven Development (Red-Green-Refactor) → /tdd
+├── Write BDD scenarios (Given-When-Then)               → /bdd
+├── Define acceptance tests with stakeholders            → /atdd
+└── Learn testing standards and best practices           → /testing (this skill)
+```
+
+| Skill | Focus | 焦點 |
+|-------|-------|------|
+| `/testing` | Standards and best practices reference | 測試標準與最佳實踐參考 |
+| `/coverage` | Code-level coverage analysis | 程式碼層級覆蓋率分析 |
+| `/ac-coverage` | Requirement-level AC traceability | 需求層級 AC 可追蹤性 |
+| `/tdd` | Red-Green-Refactor development cycle | 紅-綠-重構開發循環 |
+| `/bdd` | Behavior scenarios with Given-When-Then | Given-When-Then 行為場景 |
+| `/atdd` | Acceptance criteria with stakeholders | 與利害關係人定義驗收條件 |
+
 ## Framework Selection
 
 | Framework | Levels | Best For |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "universal-dev-standards",
-  "version": "5.0.0-rc.8",
+  "version": "5.0.0",
   "description": "CLI tool for adopting Universal Development Standards",
   "keywords": [
     "documentation",

package/src/commands/check.js

@@ -34,6 +34,7 @@ import { getToolFormat } from '../core/constants.js';
 import { checkForUpdates } from '../utils/npm-registry.js';
 import { writeUpdateCache } from '../utils/update-checker.js';
 import { StandardValidator } from '../utils/standard-validator.js';
+import { WorkflowGate } from '../utils/workflow-gate.js';
 import { t, getLanguage, setLanguage, isLanguageExplicitlySet } from '../i18n/messages.js';
 
 /**
@@ -344,12 +345,18 @@ export async function checkCommand(options = {}) {
   // Integration files check
   checkIntegrationFiles(manifest, projectPath, msg);
 
+  // Universal AGENTS.md sync check
+  checkAgentsMdSync(manifest, projectPath, msg);
+
   // Skills status
   const { missingSkills, missingCommands } = displaySkillsStatus(manifest, projectPath, msg);
 
   // Coverage report
   displayCoverageReport(manifest, msg, common, projectPath);
 
+  // Workflow status
+  displayWorkflowStatus(projectPath);
+
   // Final status
   const allGood = fileStatus.missing.length === 0 &&
                   fileStatus.modified.length === 0;
@@ -588,7 +595,7 @@ async function restoreFiles(projectPath, manifest, files) {
 /**
  * Restore a single file
  */
-async function restoreSingleFile(projectPath, manifest, relativePath, msg) {
+export async function restoreSingleFile(projectPath, manifest, relativePath, msg) {
   // Get msg if not passed (for backward compatibility)
   if (!msg) {
     msg = t().commands.check;
@@ -631,14 +638,15 @@ async function restoreSingleFile(projectPath, manifest, relativePath, msg) {
 /**
  * Update file hash in manifest
  */
-function updateFileHash(projectPath, manifest, relativePath) {
-  const fullPath = join(projectPath, relativePath);
+export function updateFileHash(projectPath, manifest, relativePath) {
+  const normalizedPath = relativePath.replace(/\\/g, '/');
+  const fullPath = join(projectPath, normalizedPath);
   const hashInfo = computeFileHash(fullPath);
   if (hashInfo) {
     if (!manifest.fileHashes) {
       manifest.fileHashes = {};
     }
-    manifest.fileHashes[relativePath] = {
+    manifest.fileHashes[normalizedPath] = {
       ...hashInfo,
       installedAt: new Date().toISOString()
     };
@@ -664,7 +672,7 @@ function removeFromManifest(manifest, relativePath) {
 /**
  * Get source path from relative path
  */
-function getSourcePathFromRelative(manifest, relativePath) {
+export function getSourcePathFromRelative(manifest, relativePath) {
   const fileName = basename(relativePath);
 
   // Check standards
@@ -712,9 +720,9 @@ async function migrateToHashBasedTracking(projectPath, manifest) {
   // Process standards
   for (const std of manifest.standards) {
     const fileName = basename(std);
-    const relativePath = std.includes('options/')
+    const relativePath = (std.includes('options/')
       ? join('.standards', 'options', fileName)
-      : join('.standards', fileName);
+      : join('.standards', fileName)).replace(/\\/g, '/');
     const fullPath = join(projectPath, relativePath);
 
     const hashInfo = computeFileHash(fullPath);
@@ -728,7 +736,7 @@ async function migrateToHashBasedTracking(projectPath, manifest) {
   for (const ext of manifest.extensions) {
     if (typeof ext !== 'string') continue;
     const fileName = basename(ext);
-    const relativePath = join('.standards', fileName);
+    const relativePath = join('.standards', fileName).replace(/\\/g, '/');
     const fullPath = join(projectPath, relativePath);
 
     const hashInfo = computeFileHash(fullPath);
@@ -1039,6 +1047,70 @@ function checkIntegrationFiles(manifest, projectPath, msg) {
   console.log();
 }
 
+/**
+ * Check universal AGENTS.md sync with installed standards
+ * Verifies the standards listed in AGENTS.md match the manifest
+ */
+function checkAgentsMdSync(manifest, projectPath, msg) {
+  // Skip if generateAgentsMd is not enabled
+  if (!manifest.generateAgentsMd) {
+    return;
+  }
+
+  // Skip if codex/opencode already handles AGENTS.md
+  const hasAgentsMdTool = (manifest.aiTools || []).some(t => t === 'codex' || t === 'opencode');
+  if (hasAgentsMdTool) {
+    return;
+  }
+
+  const agentsMdPath = join(projectPath, 'AGENTS.md');
+
+  console.log(chalk.cyan(msg.agentsMdSyncCheck || 'AGENTS.md Standards Sync'));
+
+  if (!existsSync(agentsMdPath)) {
+    console.log(chalk.red(`  ✗ AGENTS.md ${msg.missing || 'missing'}`));
+    console.log(chalk.gray(`    ${msg.runUpdateToRestore || 'Run "uds update" to restore'}`));
+    console.log();
+    return;
+  }
+
+  const content = readFileSync(agentsMdPath, 'utf-8');
+  const installedStandards = (manifest.standards || []).map(s => basename(s));
+
+  // Check standards listed in AGENTS.md vs manifest
+  const aiYamlStandards = installedStandards.filter(s => s.endsWith('.ai.yaml'));
+  let listedCount = 0;
+  let missingFromAgentsMd = [];
+
+  for (const std of aiYamlStandards) {
+    if (content.includes(std)) {
+      listedCount++;
+    } else {
+      missingFromAgentsMd.push(std);
+    }
+  }
+
+  if (missingFromAgentsMd.length === 0) {
+    console.log(chalk.green(`  ✓ AGENTS.md ${msg.standardsSynced || 'standards synced'} (${listedCount}/${aiYamlStandards.length})`));
+  } else {
+    console.log(chalk.yellow(`  ⚠ AGENTS.md ${msg.standardsOutOfSync || 'standards out of sync'} (${listedCount}/${aiYamlStandards.length})`));
+    if (missingFromAgentsMd.length <= 5) {
+      console.log(chalk.gray(`    ${msg.missingInAgentsMd || 'Missing'}: ${missingFromAgentsMd.join(', ')}`));
+    } else {
+      console.log(chalk.gray(`    ${msg.missingInAgentsMd || 'Missing'}: ${missingFromAgentsMd.slice(0, 5).join(', ')}... (+${missingFromAgentsMd.length - 5})`));
+    }
+    console.log(chalk.gray(`    ${msg.runUpdateToSync || 'Run "uds update" to sync'}`));
+  }
+
+  // Check line count
+  const lineCount = content.split('\n').length;
+  if (lineCount > 150) {
+    console.log(chalk.yellow(`  ⚠ AGENTS.md ${msg.exceedsLineLimit || 'exceeds 150 line limit'} (${lineCount} lines)`));
+  }
+
+  console.log();
+}
+
 /**
  * Check reference sync status between manifest standards and integration files
  */
@@ -1445,6 +1517,12 @@ async function displaySummary(projectPath, _options = {}) {
     console.log(`  ${summaryMsg.commands || 'Commands'}: ${commandsStatus}`);
   }
 
+  // === Row 6: Workflow Status ===
+  const workflowStatus = getWorkflowStatusSummary(projectPath);
+  if (workflowStatus) {
+    console.log(`  ${summaryMsg.workflow || 'Workflow'}: ${workflowStatus}`);
+  }
+
   console.log(chalk.gray('─'.repeat(50)));
   console.log();
 }
@@ -1569,3 +1647,71 @@ function getCommandsStatusSummary(manifest, projectPath) {
 
   return parts.length > 0 ? parts.join(' | ') : null;
 }
+
+/**
+ * Get workflow status summary string (for --summary mode)
+ * @param {string} projectPath - Project root path
+ * @returns {string|null} Formatted workflow status or null if no active workflows
+ */
+function getWorkflowStatusSummary(projectPath) {
+  try {
+    const gate = new WorkflowGate(projectPath);
+    const active = gate.listActiveWorkflows();
+
+    if (active.length === 0) {
+      return chalk.green('No active workflows ✓');
+    }
+
+    const parts = active.map(wf => {
+      const progress = wf.progress
+        ? `${wf.progress.percentage}%`
+        : '';
+      return chalk.yellow(`${wf.workflowName}:${wf.currentStep || '?'} ${progress}`);
+    });
+
+    return parts.join(' | ') + chalk.yellow(` (${active.length} active)`);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Display workflow status in full check mode
+ * @param {string} projectPath - Project root path
+ */
+function displayWorkflowStatus(projectPath) {
+  try {
+    const gate = new WorkflowGate(projectPath);
+    const active = gate.listActiveWorkflows();
+
+    if (active.length === 0) return;
+
+    console.log(chalk.cyan('Workflow Status | 工作流程狀態'));
+    console.log();
+
+    for (const wf of active) {
+      const progress = wf.progress
+        ? `${wf.progress.completed}/${wf.progress.total} (${wf.progress.percentage}%)`
+        : 'unknown';
+      const statusColor = wf.status === 'paused' ? chalk.yellow : chalk.blue;
+
+      console.log(`  ${statusColor('●')} ${chalk.bold(wf.workflowName)} — ${wf.status}`);
+      console.log(chalk.gray(`    Step: ${wf.currentStep || 'N/A'} | Progress: ${progress}`));
+
+      // Staleness warning
+      if (wf.updatedAt) {
+        const updatedDate = new Date(wf.updatedAt);
+        const daysSince = Math.floor((Date.now() - updatedDate.getTime()) / (1000 * 60 * 60 * 24));
+        if (daysSince > 7) {
+          console.log(chalk.yellow(`    ⚠ Stale: last updated ${daysSince} days ago`));
+        } else {
+          console.log(chalk.gray(`    Updated: ${wf.updatedAt}`));
+        }
+      }
+    }
+
+    console.log();
+  } catch {
+    // Silently skip if workflow gate not available
+  }
+}