universal-dev-standards 5.0.0 → 5.1.0-beta.1

package/bin/uds.js

@@ -20,16 +20,39 @@ import { auditCommand } from '../src/commands/audit.js';
 import { uninstallCommand } from '../src/commands/uninstall.js';
 import { specCreateCommand, specListCommand, specShowCommand, specConfirmCommand, specArchiveCommand, specDeleteCommand } from '../src/commands/spec.js';
 import { startCommand, missionStatusCommand, missionPauseCommand, missionResumeCommand, missionCancelCommand, missionListCommand } from '../src/commands/start.js';
+import { releaseCommand } from '../src/commands/release.js';
 import { setLanguage, setLanguageExplicit, detectLanguage, t } from '../src/i18n/messages.js';
-import { maybeCheckForUpdates, formatUpdateNotice } from '../src/utils/update-checker.js';
+import { maybeCheckForUpdates, formatUpdateNotice, shouldCheckUpdateForCommand } from '../src/utils/update-checker.js';
 
 const require = createRequire(import.meta.url);
 const pkg = require('../package.json');
 
+/**
+ * Perform update check and print notice if a newer version is available.
+ * Resolves silently on error so it never breaks CLI flow.
+ */
+async function printUpdateNoticeIfAvailable() {
+  try {
+    const result = await maybeCheckForUpdates(pkg.version);
+    if (result?.shouldNotify) {
+      console.log(formatUpdateNotice(result, t()));
+    }
+  } catch {
+    // Silent failure — update check should never break CLI
+  }
+}
+
 program
   .name('uds')
   .description('CLI tool for adopting Universal Development Standards')
   .version(pkg.version)
+  .configureOutput({
+    outputVersion: (str) => {
+      process.stdout.write(str);
+      // Intercept version output to append update notice before exit
+      printUpdateNoticeIfAvailable().finally(() => process.exit(0));
+    }
+  })
   .option('--ui-lang <lang>', 'UI language (en, zh-tw, auto) [default: auto]')
   .hook('preAction', (thisCommand) => {
     const opts = thisCommand.opts();
@@ -44,16 +67,8 @@ program
   })
   .hook('postAction', async (thisCommand) => {
     const cmd = thisCommand.name();
-    const notifyCommands = ['init', 'list', 'add', 'config'];
-    if (!notifyCommands.includes(cmd)) return;
-    try {
-      const result = await maybeCheckForUpdates(pkg.version);
-      if (result?.shouldNotify) {
-        console.log(formatUpdateNotice(result, t()));
-      }
-    } catch {
-      // Silent failure — update check should never break CLI
-    }
+    if (!shouldCheckUpdateForCommand(cmd)) return;
+    await printUpdateNoticeIfAvailable();
   });
 
 program
@@ -196,6 +211,14 @@ program
   .option('-y, --yes', 'Skip confirmation prompts')
   .action(uninstallCommand);
 
+// Release command with subcommands (Manual Deployment Mode)
+program
+  .command('release [subcommand] [args]')
+  .description('Manage release process (promote, deploy, manifest, verify)')
+  .option('--result <result>', 'Test result for deploy command (passed/failed)')
+  .option('--checksum <hash>', 'Package checksum for manifest command')
+  .action(releaseCommand);
+
 // Spec command with subcommands (Vibe Coding)
 const specCommand = program
   .command('spec')

package/bundled/ai/standards/ai-response-navigation.ai.yaml

@@ -0,0 +1,70 @@
+# AI Response Navigation Standards (AI-Optimized)
+# Source: core/ai-response-navigation.md
+
+id: ai-response-navigation
+meta:
+  version: "1.0.0"
+  updated: "2026-03-25"
+  source: core/ai-response-navigation.md
+  description: Every substantive AI response must include contextual next-step suggestions with recommended options
+
+rules:
+  - id: navigation-footer
+    trigger: completing any substantive AI response (task completion, analysis, question, error report, code change)
+    instruction: >
+      Append a Navigation Footer at the end of every logical response unit using Markdown blockquote (>).
+      Exempt ultra-short confirmations like "OK", "Done", "Got it" that are not independent logical units.
+    priority: required
+
+  - id: recommendation-marking
+    trigger: providing 2 or more next-step options
+    instruction: >
+      Mark the recommended option with ⭐ **Recommended** (or localized equivalent like ⭐ **推薦**).
+      Append the reason after " — ". If no option is clearly better, describe each option's use case instead.
+      If only one reasonable next step exists, suggest it directly without marking.
+    priority: required
+
+  - id: contextual-templates
+    trigger: generating a Navigation Footer
+    instruction: >
+      Select the template based on response type:
+      - Task completed → title "Suggested next steps" / "建議下一步", 2-3 options
+      - User question → title "Please choose" / "請選擇", 2-5 options with (A)(B)(C) labels
+      - Error/failure → title "Suggested resolution" / "建議修復方向", 1-3 options
+      - In progress → title "Progress: [N/M]. Next" / "目前進度：[N/M]。下一步", 1-2 options
+      - Informational reply → title "Suggested next steps" / "建議下一步", 1-3 options
+    priority: required
+
+  - id: adaptive-quantity
+    trigger: deciding how many options to include in Navigation Footer
+    instruction: >
+      Adjust option count based on context complexity. Minimum 1, maximum 5.
+      Task completed: 2-3. User question: 2-5. Error: 1-3. In progress: 1-2. Info reply: 1-3.
+      Never exceed 5 options — prune to the most relevant ones.
+    priority: required
+
+  - id: slash-command-preference
+    trigger: a next-step suggestion corresponds to a known slash command
+    instruction: >
+      Reference the command using `/command` format so users can copy and execute directly.
+      For steps without corresponding commands, use natural language descriptions.
+    priority: recommended
+
+  - id: tool-agnostic
+    trigger: implementing navigation behavior in any AI tool
+    instruction: >
+      This standard applies to all UDS-supported AI tools (Claude Code, Cursor, Windsurf, Copilot, etc.).
+      Behavioral rules are consistent across tools; rendering format may adapt to tool UI capabilities.
+    priority: required
+
+  - id: skill-next-steps-unification
+    trigger: creating or modifying a skill's "Next Steps Guidance" section
+    instruction: >
+      Align the format with this standard's templates. Keep skill-specific contextual recommendations
+      but ensure format consistency — use blockquote, recommendation marking, and appropriate template.
+    priority: recommended
+
+related_standards:
+  - ai-command-behavior
+  - ai-instruction-standards
+  - ai-agreement-standards

package/bundled/ai/standards/context-aware-loading.ai.yaml

@@ -154,11 +154,12 @@ standard:
       priority: required
 
     - id: version-check-on-uds-operation
-      trigger: "user invokes a UDS slash command or UDS-related operation"
+      trigger: "user invokes a UDS slash command, Skill, or UDS-related operation"
       instruction: >
         When the user invokes a UDS-related slash command (/commit, /sdd,
-        /review, /release, /tdd, /bdd, /docs, /changelog, etc.) for the
-        FIRST TIME in the current conversation, check for UDS updates:
+        /review, /release, /tdd, /bdd, /docs, /changelog, etc.) or uses
+        a UDS Skill for the FIRST TIME in the current conversation,
+        check for UDS updates:
 
         1. Read .standards/manifest.json → extract upstream.version
         2. Run: npm view universal-dev-standards dist-tags --json
@@ -168,7 +169,7 @@ standard:
         5. If versions match or npm is unreachable, skip silently
         6. Only check ONCE per conversation — do not repeat on subsequent
            UDS operations in the same session
-      priority: optional
+      priority: required
 
   architecture:
     classification: always-on-protocol

package/bundled/core/ai-response-navigation.md

@@ -0,0 +1,289 @@
+# AI Response Navigation Standards
+
+> **Language**: English | [繁體中文](../locales/zh-TW/core/ai-response-navigation.md) | [简体中文](../locales/zh-CN/core/ai-response-navigation.md)
+
+**Version**: 1.0.0
+**Last Updated**: 2026-03-25
+**Applicability**: All projects using AI-assisted development
+**Scope**: universal
+**Industry Standards**: None (Emerging AI tool practice)
+**References**: [SPEC-STD-08](../docs/specs/standards/SPEC-STD-08-ai-response-navigation.md)
+
+---
+
+## Purpose
+
+This standard defines navigation behavior for AI responses: every substantive AI response MUST include contextual next-step suggestions with recommended options. This ensures users are continuously guided through development workflows without needing to memorize available commands.
+
+**Problem**: Users don't know what to do next after receiving an AI response. With 30+ slash commands available, the cognitive load is high and workflow continuity is broken.
+
+**Solution**: A standard "Navigation Footer" appended to every substantive AI response, with contextual templates, recommendation marking, and adaptive option quantities.
+
+---
+
+## Core Rules
+
+### Rule 1: Every Substantive Response Includes Navigation
+
+Every AI response that constitutes a "logical response unit" MUST end with a Navigation Footer.
+
+**A response is a logical response unit when it:**
+
+1. Completes a task or subtask
+2. Provides analysis, explanation, or advice
+3. Asks the user a question or requests a choice
+4. Reports an error or abnormal state
+5. Shows code change results
+
+**Exemption**: Ultra-short confirmations (e.g., "OK", "Done", "Got it") that do not constitute an independent logical unit MAY omit the Navigation Footer.
+
+### Rule 2: Recommend and Explain
+
+When providing multiple options, mark the recommended option with ⭐ **Recommended** and append the reason after ` — `.
+
+| Situation | Marking |
+|-----------|---------|
+| One option is clearly better | ⭐ **Recommended** — [reason] |
+| No clear best option | Describe each option's use case, no ⭐ |
+| Only one reasonable next step | Suggest directly, no ⭐ needed |
+
+### Rule 3: Match the Context
+
+Use the appropriate template based on response type (see [Contextual Templates](#contextual-templates)).
+
+### Rule 4: Adaptive Quantity
+
+Adjust the number of options based on context complexity:
+
+| Context | Options | Rationale |
+|---------|---------|-----------|
+| Task completed | 2–3 | Suggest workflow continuation |
+| User question | 2–5 | Scale with question complexity |
+| Error/failure | 1–3 | Focus on resolution paths |
+| In progress | 1–2 | Continue or adjust |
+| Informational reply | 1–3 | Exploration directions |
+
+**Hard limit**: Never exceed 5 options. Prune to the most relevant ones.
+
+### Rule 5: Prefer Slash Commands
+
+When a next-step suggestion corresponds to a known slash command, reference it using `` `/command` `` format so users can copy and execute directly. Use natural language descriptions for steps without corresponding commands.
+
+---
+
+## Contextual Templates
+
+### Template 1: Task Completed
+
+Use when a task, skill execution, or code modification is finished.
+
+```markdown
+> **Suggested next steps:**
+> - Run `/command1` to do X
+> - Run `/command2` to do Y ⭐ **Recommended** — [reason]
+> - Run `/command3` to do Z
+```
+
+### Template 2: User Question
+
+Use when the AI needs the user to make a choice or provide information.
+
+```markdown
+> **Please choose:**
+> - **(A) Option description** — supplementary info
+> - **(B) Option description** ⭐ **Recommended** — [reason]
+> - **(C) Option description** — supplementary info
+```
+
+### Template 3: Error / Failure
+
+Use when reporting an error, failure, or abnormal state.
+
+```markdown
+> **Suggested resolution:**
+> - Option description ⭐ **Recommended** — [reason]
+> - Option description
+```
+
+### Template 4: In Progress
+
+Use when completing an intermediate stage of a multi-step task.
+
+```markdown
+> **Progress: [N/M]. Next:**
+> - Continue to next stage ⭐ **Recommended**
+> - Adjust direction or parameters
+```
+
+### Template 5: Informational Reply
+
+Use when answering a knowledge question or providing explanation.
+
+```markdown
+> **Suggested next steps:**
+> - Explore [related topic] in more depth
+> - Run `/command` to apply this to implementation
+```
+
+---
+
+## Format Specification
+
+### Structure
+
+All Navigation Footers use Markdown blockquote (`>`):
+
+```markdown
+> **[Title]:**
+> - [Option/suggestion] ⭐ **Recommended** — [reason]
+> - [Option/suggestion] — [supplementary info]
+```
+
+### Titles by Context
+
+| Context | Title |
+|---------|-------|
+| Task completed | `Suggested next steps` |
+| User question | `Please choose` |
+| Error/failure | `Suggested resolution` |
+| In progress | `Progress: [N/M]. Next` |
+| Informational reply | `Suggested next steps` |
+
+### Localization
+
+For bilingual projects, the Navigation Footer follows the conversation language. The titles above are the English variants. Localized equivalents:
+
+| English | 繁體中文 | 简体中文 |
+|---------|----------|----------|
+| Suggested next steps | 建議下一步 | 建议下一步 |
+| Please choose | 請選擇 | 请选择 |
+| Suggested resolution | 建議修復方向 | 建议修复方向 |
+| Progress: [N/M]. Next | 目前進度：[N/M]。下一步 | 当前进度：[N/M]。下一步 |
+| Recommended | 推薦 | 推荐 |
+
+---
+
+## Integration with Skills
+
+### Existing Skills
+
+Skills that already have a `## Next Steps Guidance | 下一步引導` section:
+
+1. **Keep** the skill-specific suggested content (contextual recommendations)
+2. **Align** the format to match the templates defined in this standard
+3. **Add** recommendation marking (⭐) where applicable
+
+### New Skills
+
+New skills SHOULD include a `## Next Steps Guidance | 下一步引導` section that follows this standard's templates.
+
+### Beyond Skills
+
+This standard applies to **all AI responses**, not just skill executions. General conversations, code reviews, debugging sessions, and any other interaction MUST follow these navigation rules when producing substantive responses.
+
+---
+
+## Applicability Across AI Tools
+
+This standard is tool-agnostic. It applies to all AI tools that consume UDS standards:
+
+- Claude Code
+- Cursor
+- Windsurf
+- GitHub Copilot
+- Cline
+- Roo Code
+- Augment Code
+- Trae
+- Other compatible tools
+
+Each tool's integration layer is responsible for rendering the Navigation Footer according to its UI capabilities, but the behavioral rules remain consistent.
+
+---
+
+## Examples
+
+### Example 1: After Completing a Feature Implementation
+
+```markdown
+> **Suggested next steps:**
+> - Run `/test` to write tests for the new feature
+> - Run `/commit` to commit changes ⭐ **Recommended** — changes are complete and verified
+> - Run `/review` for self-review
+```
+
+### Example 2: Asking the User a Design Question
+
+```markdown
+> **Please choose:**
+> - **(A) Use a new database table** — more flexible, higher migration cost
+> - **(B) Extend existing table with columns** ⭐ **Recommended** — simpler migration, sufficient for current needs
+> - **(C) Use a NoSQL store** — best for unstructured data but adds infrastructure
+```
+
+### Example 3: Reporting a Test Failure
+
+```markdown
+> **Suggested resolution:**
+> - Check the failing assertion at `tests/auth.test.js:42` ⭐ **Recommended** — the error message points to a null reference
+> - Run `/debug` for systematic debugging
+> - Revert the last change and investigate
+```
+
+### Example 4: Mid-workflow Progress Update
+
+```markdown
+> **Progress: [2/5]. Next:**
+> - Continue to Phase 3: Implementation ⭐ **Recommended**
+> - Revisit Phase 2 requirements before proceeding
+```
+
+### Example 5: Answering a Technical Question
+
+```markdown
+> **Suggested next steps:**
+> - Explore the related configuration in `config/auth.yaml`
+> - Run `/sdd` to create a spec if you plan to modify this behavior
+```
+
+---
+
+## Quick Reference Card
+
+| Rule | Summary |
+|------|---------|
+| R1 | Every substantive response → Navigation Footer |
+| R2 | Multiple options → ⭐ mark the best + reason |
+| R3 | Match template to response type |
+| R4 | 1–5 options, adapt to context |
+| R5 | Use `/command` format when applicable |
+
+| Exempt | Not Exempt |
+|--------|------------|
+| "OK", "Done", "Got it" | Task completion reports |
+| Single-word acknowledgments | Error explanations |
+| | Analysis or advice |
+| | Questions to user |
+| | Code change summaries |
+
+---
+
+## Related Standards
+
+- [AI Command Behavior Standards](ai-command-behavior.md) — defines how AI executes commands (complementary: behavior = execution, navigation = post-response guidance)
+- [AI Instruction Standards](ai-instruction-standards.md) — file structure for AI instruction files
+- [AI Agreement Standards](ai-agreement-standards.md) — human-AI collaboration agreements
+
+---
+
+## Version History
+
+| Version | Date | Changes |
+|---------|------|---------|
+| 1.0.0 | 2026-03-25 | Initial release |
+
+---
+
+## License
+
+This standard is released under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).

package/bundled/locales/zh-CN/README.md

@@ -6,7 +6,7 @@
 
 > **语言**: [English](../../README.md) | [繁體中文](../zh-TW/README.md) | 简体中文
 
-**版本**: 5.0.0 | **发布日期**: 2026-03-24 | **授权**: [双重授权](../../LICENSE) (CC BY 4.0 + MIT)
+**版本**: 5.1.0-beta.1 | **发布日期**: 2026-03-25 | **授权**: [双重授权](../../LICENSE) (CC BY 4.0 + MIT)
 
 语言无关、框架无关的软件项目文档标准。通过 AI 原生工作流，确保不同技术栈之间的一致性、质量和可维护性。