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

package/bundled/core/acceptance-criteria-traceability.md

@@ -0,0 +1,293 @@
+# Acceptance Criteria Traceability Standards
+
+> **Language**: English | [繁體中文](../locales/zh-TW/core/acceptance-criteria-traceability.md)
+
+**Applicability**: All software projects using specification-driven or test-driven workflows
+**Scope**: universal
+
+---
+
+## Overview
+
+Acceptance Criteria Traceability Standards define how to track the relationship between Acceptance Criteria (AC), test implementations, and coverage status. This standard ensures every AC is verifiably tested and provides standardized reporting formats for coverage analysis.
+
+## References
+
+| Standard/Source | Content |
+|----------------|---------|
+| ISO/IEC/IEEE 29119-3 | Test Documentation — Traceability Matrix |
+| IEEE 830 | Software Requirements Specification — Traceability |
+| ISTQB Foundation | Requirements-based testing |
+| INVEST Principles | Acceptance criteria quality |
+
+---
+
+## AC-to-Test Traceability Matrix
+
+### Standard Matrix Format
+
+| AC-ID | Test File | Test Name | Status | Notes |
+|-------|-----------|-----------|--------|-------|
+| AC-1 | `tests/auth.test.ts` | `should login with valid credentials` | ✅ covered | |
+| AC-2 | `tests/auth.test.ts` | `should reject invalid credentials` | ✅ covered | |
+| AC-3 | — | — | ❌ uncovered | Blocked by API dependency |
+| AC-4 | `tests/auth.test.ts` | `should lock account after 5 failures` | ⚠️ partial | Missing edge case |
+
+### Matrix Fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `AC-ID` | Yes | Unique identifier from the specification (e.g., AC-1, AC-2) |
+| `Test File` | Yes (if covered) | Path to the test file implementing this AC |
+| `Test Name` | Yes (if covered) | Name of the test case or describe block |
+| `Status` | Yes | Coverage status: `covered`, `partial`, `uncovered` |
+| `Notes` | No | Additional context (blockers, dependencies, etc.) |
+
+### Linking Convention
+
+Tests MUST reference their source AC using standard annotations:
+
+```typescript
+// TypeScript/JavaScript
+describe('AC-1: User login with valid credentials', () => {
+  // @AC AC-1
+  // @SPEC SPEC-001
+  it('should redirect to dashboard on successful login', () => { ... });
+});
+```
+
+```python
+# Python
+class TestAC1_UserLogin:
+    """AC-1: User login with valid credentials
+    @AC AC-1
+    @SPEC SPEC-001
+    """
+    def test_redirect_to_dashboard(self): ...
+```
+
+```gherkin
+# BDD Feature
+@SPEC-001 @AC-1
+Scenario: User login with valid credentials
+```
+
+---
+
+## Coverage Status Definitions
+
+### Status Classification
+
+| Status | Symbol | Definition | Criteria |
+|--------|--------|-----------|----------|
+| **Covered** | ✅ | AC is fully tested | All conditions in AC have corresponding test assertions |
+| **Partial** | ⚠️ | AC is partially tested | Some conditions tested, but edge cases or paths missing |
+| **Uncovered** | ❌ | AC has no tests | No test case references this AC |
+
+### Coverage Calculation
+
+```
+AC Coverage % = (covered_count / total_ac_count) × 100
+
+Where:
+  covered_count = count of AC with status "covered"
+  total_ac_count = total number of AC in specification
+  partial counts as 0.5 for coverage calculation
+```
+
+### Example Calculation
+
+```
+SPEC-001: 8 AC total
+  - 5 covered (✅)
+  - 2 partial (⚠️)
+  - 1 uncovered (❌)
+
+Coverage = (5 + 2×0.5) / 8 = 6/8 = 75%
+```
+
+---
+
+## Quality Thresholds
+
+### Default Thresholds
+
+| Threshold | Value | Enforcement |
+|-----------|-------|-------------|
+| **Minimum AC Coverage** | 100% | Required for production release |
+| **Minimum for Check-in** | 80% | Required for feature branch merge |
+| **Warning Level** | 60% | Triggers coverage warning |
+
+### Configurable Thresholds
+
+Projects MAY customize thresholds in their configuration:
+
+```json
+{
+  "acCoverage": {
+    "minimum": 100,
+    "checkinMinimum": 80,
+    "warningLevel": 60,
+    "partialWeight": 0.5
+  }
+}
+```
+
+### Threshold Exceptions
+
+Exceptions to coverage requirements MUST be documented:
+
+| Exception Type | When Allowed | Documentation Required |
+|---------------|-------------|----------------------|
+| External dependency blocker | Third-party API unavailable | Issue link + timeline |
+| Infrastructure limitation | Test environment constraint | Workaround plan |
+| Deferred to next iteration | Agreed with stakeholders | Ticket reference |
+
+---
+
+## AC Coverage Report Format
+
+### Standard Report Structure
+
+```markdown
+# AC Coverage Report
+
+**Specification**: SPEC-001 — User Authentication
+**Generated**: 2026-03-18
+**Coverage**: 75% (6/8 AC)
+
+## Summary
+
+| Status | Count | Percentage |
+|--------|-------|------------|
+| ✅ Covered | 5 | 62.5% |
+| ⚠️ Partial | 2 | 25.0% |
+| ❌ Uncovered | 1 | 12.5% |
+
+## Traceability Matrix
+
+| AC-ID | Description | Status | Test Reference |
+|-------|-------------|--------|----------------|
+| AC-1 | Login with valid credentials | ✅ | auth.test.ts:15 |
+| AC-2 | Reject invalid credentials | ✅ | auth.test.ts:32 |
+| AC-3 | Rate limit login attempts | ⚠️ | auth.test.ts:48 (missing edge case) |
+| ...   | ...                        | ... | ... |
+
+## Gaps
+
+### Uncovered AC
+- **AC-8**: Social login integration — Blocked by OAuth provider sandbox
+
+### Partial AC
+- **AC-3**: Rate limit — Missing test for concurrent requests
+- **AC-6**: Session timeout — Missing test for background tab behavior
+
+## Action Items
+1. [ ] AC-8: Set up OAuth sandbox environment (ETA: 2026-03-25)
+2. [ ] AC-3: Add concurrent request test
+3. [ ] AC-6: Add background tab test
+```
+
+### Machine-Readable Format
+
+```json
+{
+  "specId": "SPEC-001",
+  "specName": "User Authentication",
+  "generatedAt": "2026-03-18T10:00:00Z",
+  "coverage": {
+    "percentage": 75,
+    "covered": 5,
+    "partial": 2,
+    "uncovered": 1,
+    "total": 8
+  },
+  "matrix": [
+    {
+      "acId": "AC-1",
+      "description": "Login with valid credentials",
+      "status": "covered",
+      "testFile": "tests/auth.test.ts",
+      "testName": "should login with valid credentials",
+      "testLine": 15
+    }
+  ]
+}
+```
+
+---
+
+## Automatic Spec Generation Quality Rules
+
+### AC Quality Requirements
+
+When generating specifications automatically (from PRD, user stories, or requirements), the generated AC MUST meet these quality criteria:
+
+| Criterion | Description | Validation |
+|-----------|-------------|-----------|
+| **Specific** | AC describes a concrete, observable behavior | No vague terms ("should work well", "fast enough") |
+| **Measurable** | AC has quantifiable or verifiable outcome | Contains expected values, states, or behaviors |
+| **Achievable** | AC is technically feasible | References known APIs, data, or capabilities |
+| **Relevant** | AC relates to the feature's purpose | Maps to a user need or business requirement |
+| **Testable** | AC can be verified by a test | Can be expressed as Given-When-Then |
+
+### Spec Generation I/O Contract
+
+#### Input Format
+
+| Input Type | Required Fields | Example |
+|-----------|----------------|---------|
+| PRD | Title, Description, User Stories | Product Requirements Document |
+| User Story | As a / I want / So that | "As a user, I want to login..." |
+| Feature Brief | Feature name, Goals, Constraints | Feature description document |
+
+#### Output Format
+
+Generated spec MUST include:
+
+| Section | Required | Description |
+|---------|----------|-------------|
+| SPEC ID | Yes | Unique identifier (e.g., SPEC-001) |
+| Title | Yes | Feature name |
+| Description | Yes | What the feature does |
+| Acceptance Criteria | Yes | Numbered AC list (AC-1, AC-2, ...) |
+| AC Format | Yes | Given-When-Then or structured bullet |
+| Testability Flag | Yes | Each AC marked as testable/not-testable |
+
+#### Validation Rules
+
+1. **AC Count**: Generated spec MUST have at least 1 AC
+2. **AC Uniqueness**: No duplicate AC descriptions
+3. **AC Completeness**: Happy path + at least 1 error/edge case
+4. **AC Testability**: 100% of AC must be testable
+5. **Traceability**: Each AC links back to source requirement
+
+---
+
+## Anti-Patterns
+
+| Anti-Pattern | Impact | Correct Approach |
+|--------------|--------|------------------|
+| Untraceable tests | Cannot verify spec coverage | Always annotate tests with AC-ID |
+| Claiming partial as covered | False confidence in coverage | Use honest status classification |
+| Ignoring uncovered AC | Gaps in verification | Track and plan coverage for all AC |
+| AC without testability | Cannot be verified | Ensure all AC are testable |
+| Coverage without assertions | Tests run but verify nothing | Check for meaningful assertions |
+
+---
+
+## Related Standards
+
+- [Forward Derivation Standards](forward-derivation-standards.md) — Generating tests from AC
+- [Spec-Driven Development](spec-driven-development.md) — AC definition format
+- [Testing Standards](testing-standards.md) — Test implementation standards
+- [Check-in Standards](checkin-standards.md) — Coverage gates for check-in
+- [Test Governance](test-governance.md) — Completion criteria
+
+---
+
+## Version History
+
+| Version | Date | Changes |
+|---------|------|---------|
+| 1.0.0 | 2026-03-18 | Initial version — traceability matrix, coverage calculation, spec generation rules |

package/bundled/core/agent-dispatch.md

@@ -0,0 +1,149 @@
+# Agent Dispatch & Parallel Coordination
+
+> **Language**: English | [繁體中文](../locales/zh-TW/core/agent-dispatch.md)
+
+**Version**: 1.0.0
+**Last Updated**: 2026-03-20
+**Applicability**: AI-assisted development with multi-agent orchestration
+**Scope**: universal
+**Inspired by**: [Superpowers](https://github.com/obra/superpowers) — dispatching-parallel-agents, subagent-driven-development (MIT)
+
+---
+
+## Purpose
+
+Define standards for dispatching AI sub-agents in parallel, coordinating their work, and handling their return states. This standard ensures efficient parallelization while preventing file conflicts and integration failures.
+
+定義 AI 子代理的並行派遣、工作協調與狀態回報標準。確保高效並行化的同時，防止檔案衝突與整合失敗。
+
+---
+
+## Glossary
+
+| Term | Definition |
+|------|-----------|
+| Sub-agent | An AI agent spawned by an orchestrator to handle a specific task |
+| Independent Domain | A task scope with no shared mutable state with other tasks |
+| Status Protocol | The standardized return states a sub-agent must report |
+| File Conflict | When multiple agents modify the same file concurrently |
+
+---
+
+## Core Principle — Independence Before Parallelism
+
+> **Before dispatching agents in parallel, verify their task domains are independent (no shared mutable state).**
+
+派遣前必須識別獨立域 — 無共享可變狀態才可並行。
+
+---
+
+## Prompt Design Principles
+
+Every sub-agent prompt must follow three principles:
+
+### 1. Focused（聚焦）
+
+Each agent handles exactly one problem domain. Do not combine unrelated tasks.
+
+每個代理只處理單一問題域，不混合無關任務。
+
+### 2. Self-contained（自足）
+
+The prompt includes all context needed for execution. The agent should not need to ask questions or search for additional information.
+
+Prompt 包含執行所需的完整上下文，代理不需要額外提問或搜尋。
+
+### 3. Specific Output（明確輸出）
+
+Define exactly what format the agent should return its results in.
+
+明確定義期望的回報格式。
+
+---
+
+## Status Protocol
+
+Every sub-agent must report one of four statuses upon completion:
+
+| Status | Description | Orchestrator Action |
+|--------|-------------|-------------------|
+| `DONE` | Task completed successfully | Continue to next task |
+| `DONE_WITH_CONCERNS` | Completed but with concerns to record | Log concerns, continue |
+| `NEEDS_CONTEXT` | Needs more context to complete | Inject context, re-dispatch (not a retry) |
+| `BLOCKED` | Cannot complete, needs escalation | Upgrade model tier or split task |
+
+### Status Decision Flow
+
+```
+Agent completes work
+  ├── All acceptance criteria met? → DONE
+  ├── Criteria met but concerns exist? → DONE_WITH_CONCERNS
+  ├── Missing information to proceed? → NEEDS_CONTEXT
+  └── Fundamentally unable to complete? → BLOCKED
+```
+
+---
+
+## Conflict Detection
+
+When parallel agents return, the orchestrator must:
+
+1. **Check for file conflicts** — did multiple agents modify the same file?
+2. **Run the full test suite** — verify integration after merging all changes
+3. **Resolve conflicts** — either automatically or flag for human review
+
+```
+Agent A (modifies: src/auth.ts, src/auth.test.ts)  ─┐
+                                                      ├─→ Conflict check → Integration test
+Agent B (modifies: src/api.ts, src/api.test.ts)     ─┘
+```
+
+---
+
+## Rules
+
+| ID | Trigger | Action | Priority |
+|----|---------|--------|----------|
+| AD-001 | Multiple agents edit the same file | Flag conflict, require merge resolution | Critical |
+| AD-002 | Agent reports BLOCKED | Upgrade model tier and retry once | High |
+| AD-003 | All parallel agents complete | Run full test suite to verify integration | High |
+
+---
+
+## Examples
+
+### Good: Parallel Independent Tasks
+
+```yaml
+# Two agents working on independent modules
+Agent 1:
+  task: "Add rate limiting to /api/users endpoint"
+  files: [src/api/users.ts, src/api/users.test.ts]
+
+Agent 2:
+  task: "Add caching to /api/products endpoint"
+  files: [src/api/products.ts, src/api/products.test.ts]
+
+# No shared files → safe to parallelize
+```
+
+### Bad: Parallel Dependent Tasks
+
+```yaml
+# Two agents modifying shared state
+Agent 1:
+  task: "Refactor database connection pool"
+  files: [src/db.ts]  # ⚠️ shared file
+
+Agent 2:
+  task: "Add connection retry logic"
+  files: [src/db.ts]  # ⚠️ conflict!
+```
+
+---
+
+## References
+
+- **Superpowers**: [dispatching-parallel-agents](https://github.com/obra/superpowers), [subagent-driven-development](https://github.com/obra/superpowers) (MIT)
+- **MapReduce**: Conceptual parallel execution model
+- **Actor Model**: Independent agent communication pattern

package/bundled/core/ai-command-behavior.md

@@ -0,0 +1,239 @@
+# AI Command Behavior Standards
+
+> **Language**: English | [繁體中文](../locales/zh-TW/core/ai-command-behavior.md) | [简体中文](../locales/zh-CN/core/ai-command-behavior.md)
+
+**Version**: 1.0.0
+**Last Updated**: 2026-03-24
+**Applicability**: All projects using AI-assisted commands or skills
+**Scope**: universal
+**Industry Standards**: None (Emerging AI tool practice)
+**References**: [SPEC-STD-07](../docs/specs/standards/SPEC-STD-07-ai-command-behavior.md)
+
+---
+
+## Purpose
+
+This standard defines a structure for specifying AI Agent runtime behavior in command/skill definition files. It ensures that AI agents produce consistent, predictable interactions when executing commands — regardless of which AI model or tool runs them.
+
+**Problem**: Commands define "what" to do but lack "how" the AI should interact with the user, leading to unpredictable behavior.
+
+**Solution**: A standard `## AI Agent Behavior` section with four subsections covering entry routing, interaction flow, stop points, and error handling.
+
+---
+
+## AI Behavior Section Structure
+
+Every command definition file that requires AI interaction SHOULD include:
+
+```markdown
+## AI Agent Behavior | AI 代理行為
+
+### Entry Router | 進入路由
+
+### Interaction Script | 互動腳本
+
+### Stop Points | 停止點
+
+### Error Handling | 錯誤處理
+```
+
+---
+
+## Section Definitions
+
+### 1. Entry Router
+
+Defines what the AI does for each invocation pattern. Use a decision table for commands with multiple invocation patterns.
+
+**Format:**
+
+```markdown
+| Input | AI Action |
+|-------|-----------|
+| `/cmd` | [action when no arguments] |
+| `/cmd <name>` | [action with name argument] |
+| `/cmd <phase>` | [action with phase subcommand] |
+| `/cmd <phase> <target>` | [action with phase and target] |
+```
+
+**Simple commands** (single invocation pattern) may use a one-line description instead.
+
+**Rules:**
+- Every documented invocation pattern MUST have a corresponding entry
+- The "no arguments" case MUST always be defined
+- Entry actions MUST be deterministic — no ambiguity in what happens first
+
+### 2. Interaction Script
+
+Defines step-by-step AI behavior using **mixed granularity**:
+
+| Element | Granularity | Reason |
+|---------|-------------|--------|
+| Decision points | Precise (IF/THEN) | Affects downstream flow |
+| General steps | Guideline (numbered list) | AI needs flexibility |
+
+**Decision point format:**
+
+```markdown
+**Decision: [Name]**
+- IF [condition A] → [specific action]
+- IF [condition B] → [specific action]
+- ELSE → [default action]
+```
+
+**General step format:**
+
+```markdown
+1. [Step description]
+2. [Step description]
+3. [Step description]
+```
+
+**Rules:**
+- Decision points MUST use explicit IF/THEN/ELSE
+- General steps SHOULD use numbered lists
+- Output format (what the AI shows to the user) SHOULD be specified for key outputs
+
+### 3. Stop Points
+
+Defines moments where the AI MUST pause and wait for user confirmation.
+
+**Marker format:**
+
+```markdown
+🛑 **STOP**: [description] — wait for user confirmation before continuing
+```
+
+**Default stop principles** (apply when no explicit stop points are defined):
+
+| Situation | Action |
+|-----------|--------|
+| About to write/modify files | 🛑 STOP |
+| About to execute irreversible operations | 🛑 STOP |
+| Phase/stage completion | 🛑 STOP |
+| Need additional information from user | 🛑 STOP |
+| Read-only analysis complete, showing results | ▶️ CONTINUE |
+
+**Rules:**
+- Stop points MUST be explicit — do not rely on AI judgment
+- Each stop point MUST describe what the AI is waiting for
+- The number of stop points should be proportional to the operation's risk
+
+### 4. Error Handling
+
+Defines AI behavior when prerequisites fail or unexpected states occur.
+
+**Format:**
+
+```markdown
+| Error Condition | AI Action |
+|-----------------|-----------|
+| [prerequisite not met] | [guide to correct step] |
+| [unexpected state] | [stop and ask user] |
+```
+
+**Default error principles:**
+
+1. **State the problem**: Tell user which prerequisite failed
+2. **Guide to resolution**: Suggest the correct command or step
+3. **Never silently skip**: Do not proceed by ignoring failures
+4. **Never auto-fix without permission**: Unless explicitly allowed in the command definition
+5. **Ask when uncertain**: Stop and ask rather than guess
+
+---
+
+## Applicability Rules
+
+Not all commands need a full `## AI Agent Behavior` section.
+
+| Condition | Full Definition Required | Reason |
+|-----------|-------------------------|--------|
+| Multi-phase workflow | ✅ Yes | Complex flow needs guidance |
+| Multiple invocation patterns | ✅ Yes | Entry routing is ambiguous otherwise |
+| Single clear action | ❌ No | Behavior is self-evident |
+| Pure information query | ❌ No | No interaction decisions to make |
+| Orchestration of sub-commands | ✅ Yes | Coordination logic needs definition |
+
+**Heuristic**: If two different AI models could reasonably interpret the command differently, it needs a behavior definition.
+
+---
+
+## Example: Minimal Behavior Section
+
+For a command like `/coverage` with moderate complexity:
+
+```markdown
+## AI Agent Behavior
+
+### Entry Router
+
+| Input | AI Action |
+|-------|-----------|
+| `/coverage` | Detect test framework, run coverage, show summary |
+| `/coverage <path>` | Run coverage for specific path only |
+
+### Interaction Script
+
+1. Detect project test framework (look for jest.config, vitest.config, etc.)
+2. Run coverage command
+3. Parse output and present summary table
+
+**Decision: Low coverage detected**
+- IF coverage < project threshold → highlight gaps, suggest files to test
+- ELSE → show summary only
+
+### Stop Points
+
+🛑 **STOP**: After showing coverage summary — ask if user wants detailed file-by-file breakdown
+
+### Error Handling
+
+| Error Condition | AI Action |
+|-----------------|-----------|
+| No test framework detected | Ask user which framework to use |
+| Tests fail during coverage run | Show failures first, ask if user wants coverage anyway |
+```
+
+---
+
+## Quick Reference Card
+
+### Section Checklist
+
+| Section | Must Define | Key Rule |
+|---------|------------|----------|
+| Entry Router | All invocation patterns | "No arguments" case is mandatory |
+| Interaction Script | Decision points + general flow | Decision = precise, Steps = guideline |
+| Stop Points | Every pause moment | Explicit markers, no AI guessing |
+| Error Handling | Prerequisite failures | Never silently skip |
+
+### Granularity Guide
+
+| Element | Level | Format |
+|---------|-------|--------|
+| Entry Router | Precise | Decision table |
+| Stop Points | Precise | 🛑 markers |
+| Interaction Script | Guideline | Numbered steps + IF/THEN for decisions |
+| Error Handling | Principles | Error table + default rules |
+
+---
+
+## Related Standards
+
+- [AI Instruction Standards](ai-instruction-standards.md) — file structure for AI instruction files
+- [AI Agreement Standards](ai-agreement-standards.md) — human-AI collaboration agreements
+- [Anti-Hallucination Standards](anti-hallucination.md) — evidence-based AI behavior
+
+---
+
+## Version History
+
+| Version | Date | Changes |
+|---------|------|---------|
+| 1.0.0 | 2026-03-24 | Initial release |
+
+---
+
+## License
+
+This standard is released under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).