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

package/bundled/core/documentation-structure.md

@@ -2,9 +2,12 @@
 
 > **Language**: English | [繁體中文](../locales/zh-TW/core/documentation-structure.md)
 
-**Version**: 1.2.2
-**Last Updated**: 2025-12-24
+**Version**: 1.3.0
+**Last Updated**: 2026-01-24
 **Applicability**: All software projects requiring documentation
+**Scope**: partial
+**Industry Standards**: None (Industry convention)
+**References**: [diataxis.fr](https://diataxis.fr/)
 
 ---
 
@@ -34,7 +37,14 @@ project-root/
 │   ├── api-reference.md         # API documentation
 │   ├── deployment.md            # Deployment guide
 │   ├── troubleshooting.md       # Common issues
-│   ├── flows/                   # Flow documentation (NEW)
+│   ├── specs/                   # Specification documents
+│   │   ├── README.md            # Specification index
+│   │   ├── system/              # System design specifications
+│   │   │   └── *.md             # High-level architecture designs
+│   │   └── {component}/         # Component-specific specifications
+│   │       ├── design/          # Design specifications
+│   │       └── {module}/        # Implementation specifications
+│   ├── flows/                   # Flow documentation
 │   │   ├── README.md            # Flow index (REQUIRED when >5 flows)
 │   │   ├── templates/
 │   │   │   └── flow-template.md
@@ -101,21 +111,23 @@ docs/
 
 ## Document Requirements Matrix
 
-Different project types require different documentation:
+> **See Also**: For the complete document requirements matrix with detailed content requirements and project type descriptions, see [documentation-writing-standards.md](documentation-writing-standards.md#document-requirements-matrix).
 
-| Document | New Project | Refactor | Migration | Maintenance | Description |
-|----------|:-----------:|:--------:|:---------:|:-----------:|-------------|
-| **README.md** | ✅ | ✅ | ✅ | ✅ | Project entry point |
-| **ARCHITECTURE.md** | ✅ | ✅ | ✅ | ⚪ | System architecture |
-| **API.md** | ⚪ | ✅ | ✅ | ⚪ | External API specs |
-| **DATABASE.md** | ⚪ | ✅ | ✅ | ⚪ | Database structure |
-| **DEPLOYMENT.md** | ✅ | ✅ | ✅ | ⚪ | Deployment guide |
-| **MIGRATION.md** | ❌ | ✅ | ✅ | ❌ | Migration plan |
-| **ADR/** | ⚪ | ✅ | ✅ | ⚪ | Decision records |
-| **CHANGELOG.md** | ✅ | ✅ | ✅ | ✅ | Change history |
-| **flows/README.md** | ⚪ | ✅ | ✅ | ⚪ | Flow index (when >5 flows) |
+This standard defines WHERE documents go (file structure). The writing standards define WHAT each document should contain.
 
-**Legend**: ✅ Required | ⚪ Recommended | ❌ Not needed
+**Quick Reference** (for full matrix, see writing standards):
+
+| Document | Primary Location |
+|----------|------------------|
+| README.md | Project root |
+| ARCHITECTURE.md | `docs/` |
+| API.md | `docs/` |
+| DATABASE.md | `docs/` |
+| DEPLOYMENT.md | `docs/` |
+| MIGRATION.md | `docs/` |
+| ADR/ | `docs/adr/` |
+| CHANGELOG.md | Project root |
+| flows/ | `docs/flows/` |
 
 ---
 
@@ -220,7 +232,7 @@ When you have more than 5 flow documents, `flows/README.md` is **required** and
 
 1. **Define centrally** in `flows/README.md` or `DATABASE.md`
 2. **Reference in flow docs**: List only relevant codes, with note:
-   > Complete definitions at [flows/README.md](../README.md#status-codes)
+   > Complete definitions at [flows/README.md](../README.md)
 3. **Version control**: Status code changes must be recorded in CHANGELOG.md
 
 **Status Code Definition Format**:
@@ -237,7 +249,89 @@ When you have more than 5 flow documents, `flows/README.md` is **required** and
 
 ---
 
-## Index Document Standards (NEW)
+## Specification Documentation
+
+### Purpose
+
+Specification documents define the design and implementation details **before** coding. They differ from regular documentation:
+
+| Type | Purpose | Audience | When Written | Location |
+|------|---------|----------|--------------|----------|
+| **Specification** | Define WHAT to build and HOW | Developers | Before implementation | `docs/specs/` |
+| **Documentation** | Explain WHAT was built | Users, Developers | After implementation | `docs/` |
+
+### Specification Directory Structure
+
+```
+docs/specs/
+├── README.md               # Specification index (REQUIRED)
+├── system/                 # System-level design specifications
+│   └── {feature}.md        # High-level architecture designs
+└── {component}/            # Component-specific specifications
+    ├── design/             # Design specifications (pre-implementation)
+    ├── shared/             # Cross-module shared specifications
+    └── {module}/           # Implementation specifications
+```
+
+### Specification Types
+
+| Level | Description | Example | Location |
+|-------|-------------|---------|----------|
+| **System Spec** | Cross-cutting architecture | agents-workflows-system.md | `specs/system/` |
+| **Design Spec** | Component design decisions | ui-language-option.md | `specs/{component}/design/` |
+| **Implementation Spec** | Module implementation details | init/00-init-overview.md | `specs/{component}/{module}/` |
+| **Shared Spec** | Cross-module utilities | manifest-schema.md | `specs/{component}/shared/` |
+
+### When to Create Specifications
+
+| Scenario | Create Spec? | Type |
+|----------|--------------|------|
+| New feature with multiple components | Yes | System or Design |
+| New CLI command | Yes | Implementation |
+| Cross-cutting utility | Yes | Shared |
+| Bug fix | No | - |
+| Refactoring (same behavior) | No | - |
+
+### Specification File Format
+
+Every specification document should include:
+
+```markdown
+# Feature Name Specification
+
+**Feature ID**: COMPONENT-FEATURE-NNN
+**Version**: 1.0.0
+**Last Updated**: YYYY-MM-DD
+**Status**: Draft | In Review | Approved | Implemented
+
+## Overview
+[Brief description of what this specification covers]
+
+## Acceptance Criteria
+[AC-1, AC-2, ... with Given-When-Then format]
+
+## Technical Design
+[Implementation details]
+
+## References
+[Related specs and documentation]
+```
+
+### specs/README.md Requirements
+
+The specification index (`specs/README.md`) must include:
+
+| Section | Description | Required |
+|---------|-------------|:--------:|
+| Directory Structure | Specification tree diagram | ✅ |
+| System Specifications | List with descriptions and status | ✅ |
+| Component Specifications | Organized by component | ✅ |
+| Specification Types | Type definitions and locations | ⚪ |
+| Related Documentation | Links to docs/ | ✅ |
+
+---
+
+## Index Document Standards
 
 ### docs/index.md Required Sections
 
@@ -1089,6 +1183,7 @@ git push origin gh-pages
 - [Documentation Writing Standards](documentation-writing-standards.md)
 - [Changelog Standards](changelog-standards.md)
 - [Project Structure Standard](project-structure.md)
+- [Spec-Driven Development](spec-driven-development.md)
 
 ---
 
@@ -1096,6 +1191,7 @@ git push origin gh-pages
 
 | Version | Date | Changes |
 |---------|------|---------|
+| 1.3.0 | 2026-01-24 | Added: Specification documentation standards with specs/ directory structure |
 | 1.2.2 | 2025-12-24 | Added: Related Standards section |
 | 1.2.1 | 2025-12-12 | Added: Physical DFD layer, Flows vs Diagrams separation clarification |
 | 1.2.0 | 2025-12-11 | Added: Flow documentation standards, Cross-reference standards, Index document standards, CHANGELOG documentation integration, Document requirements matrix, DFD standards |

package/bundled/core/documentation-writing-standards.md

@@ -2,9 +2,12 @@
 
 > **English** | [繁體中文](../locales/zh-TW/core/documentation-writing-standards.md)
 
-**Version**: 1.0.1
-**Last Updated**: 2025-12-24
+**Version**: 1.1.0
+**Last Updated**: 2026-01-24
 **Applicability**: All software projects (new, refactoring, migration, maintenance)
+**Scope**: partial
+**Industry Standards**: OpenAPI 3.1, AsyncAPI 2.6, JSON Schema 2020-12
+**References**: [openapis.org](https://www.openapis.org/)
 
 ---
 
@@ -397,6 +400,262 @@ Accepted
 
 ---
 
+## AI Collaboration Documentation
+
+### Overview
+
+Modern documentation must be optimized for both human readers and AI assistants. This section provides guidelines for writing documentation that AI tools can effectively parse and utilize.
+
+### Token-Aware Document Design
+
+AI models have context window limits. Structure documents for efficient LLM consumption:
+
+**Document Structure Principles**:
+
+| Principle | Description | Example |
+|-----------|-------------|---------|
+| **Front-load key info** | Put critical information early | Summary before details |
+| **Use clear headings** | Hierarchical structure aids navigation | H1 > H2 > H3 progression |
+| **Keep sections atomic** | Each section is self-contained | Can be read independently |
+| **Minimize redundancy** | Avoid repeating information | Reference instead of copy |
+| **Use structured formats** | Tables and lists over prose | Easy to parse and extract |
+
+**Recommended Document Sizes**:
+
+| Document Type | Target Size | Rationale |
+|---------------|-------------|-----------|
+| README | 500-1000 words | Quick overview |
+| API endpoint doc | 200-400 words per endpoint | Focused and scannable |
+| Architecture doc | 1000-2000 words per section | Detailed but chunked |
+| ADR | 300-600 words | Decision-focused |
+
+### AI-Friendly Documentation Patterns
+
+**Pattern 1: Structured Metadata Block**
+
+Include machine-readable metadata at the top of documents:
+
+```markdown
+---
+title: User Authentication API
+version: 2.1.0
+last_updated: 2026-01-24
+owner: auth-team
+status: stable
+dependencies:
+  - user-service
+  - token-service
+---
+```
+
+**Pattern 2: Clear Section Markers**
+
+Use consistent section headers that AI can recognize:
+
+```markdown
+## Overview
+[Brief description of what this component/API does]
+
+## Quick Start
+[Minimal steps to get started]
+
+## API Reference
+[Detailed API documentation]
+
+## Configuration
+[Configuration options and defaults]
+
+## Troubleshooting
+[Common issues and solutions]
+```
+
+**Pattern 3: Explicit Examples**
+
+Provide complete, runnable examples with clear context:
+
+```markdown
+### Example: Create User
+
+**Prerequisites**:
+- Valid API key
+- Admin role
+
+**Request**:
+```bash
+curl -X POST https://api.example.com/v1/users \
+  -H "Authorization: Bearer $API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"name": "John", "email": "john@example.com"}'
+```
+
+**Response** (201 Created):
+```json
+{
+  "id": "usr_123",
+  "name": "John",
+  "email": "john@example.com",
+  "created_at": "2026-01-24T10:30:00Z"
+}
+```
+```
+
+### Writing for AI Code Generation
+
+When documentation will be used to generate code:
+
+**Include Explicit Constraints**:
+
+```markdown
+## Validation Rules
+
+| Field | Type | Constraints |
+|-------|------|-------------|
+| email | string | Required, valid email format, max 255 chars |
+| age | integer | Required, range 0-150 |
+| role | string | Enum: "admin", "user", "guest" |
+```
+
+**Specify Error Scenarios**:
+
+```markdown
+## Error Responses
+
+| Scenario | HTTP Status | Error Code | Message |
+|----------|-------------|------------|---------|
+| Invalid email | 400 | INVALID_EMAIL | "Email format is invalid" |
+| User exists | 409 | DUPLICATE_USER | "User with this email already exists" |
+| Missing auth | 401 | UNAUTHORIZED | "Authentication required" |
+```
+
+**Clarify Business Logic**:
+
+```markdown
+## Discount Calculation Logic
+
+1. Base discount = 0%
+2. If customer type is "VIP", add 20%
+3. If order total > $100, add 5%
+4. If coupon code is valid, add coupon discount
+5. Maximum total discount = 50%
+6. Apply discount to subtotal (not including tax)
+```
+
+### AI Prompt Integration
+
+For documents that define AI-assisted workflows:
+
+**Embedded Prompt Templates**:
+
+```markdown
+## AI Code Review Prompt
+
+When reviewing code changes, use this prompt:
+
+```
+Review this code change for:
+1. Security vulnerabilities (OWASP Top 10)
+2. Performance issues
+3. Error handling completeness
+4. Adherence to [project-conventions.md]
+
+Provide feedback in this format:
+- 🔴 Critical: [Must fix before merge]
+- 🟡 Important: [Should address]
+- 🟢 Suggestion: [Nice to have]
+```
+```
+
+---
+
+## API Documentation Standards
+
+### OpenAPI 3.1 Compliance
+
+For REST APIs, use OpenAPI 3.1 (fully aligned with JSON Schema draft 2020-12):
+
+**Key OpenAPI 3.1 Features**:
+
+| Feature | Description |
+|---------|-------------|
+| JSON Schema alignment | Full compatibility with JSON Schema |
+| Webhooks support | First-class webhook documentation |
+| `type` arrays | Support for `"type": ["string", "null"]` |
+| `$ref` alongside properties | Reference and extend in same object |
+
+**Example OpenAPI 3.1 Schema**:
+
+```yaml
+openapi: 3.1.0
+info:
+  title: User API
+  version: 2.1.0
+paths:
+  /users:
+    post:
+      summary: Create a new user
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateUserRequest'
+      responses:
+        '201':
+          description: User created
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/User'
+components:
+  schemas:
+    CreateUserRequest:
+      type: object
+      required: [name, email]
+      properties:
+        name:
+          type: string
+          minLength: 1
+          maxLength: 100
+        email:
+          type: string
+          format: email
+```
+
+### AsyncAPI 2.6 for Event-Driven APIs
+
+For message-based/event-driven APIs, use AsyncAPI 2.6:
+
+**Example AsyncAPI Document**:
+
+```yaml
+asyncapi: 2.6.0
+info:
+  title: Order Events
+  version: 1.0.0
+channels:
+  orders/created:
+    publish:
+      message:
+        $ref: '#/components/messages/OrderCreated'
+components:
+  messages:
+    OrderCreated:
+      payload:
+        type: object
+        properties:
+          orderId:
+            type: string
+          customerId:
+            type: string
+          totalAmount:
+            type: number
+          createdAt:
+            type: string
+            format: date-time
+```
+
+---
+
 ## Quality Standards
 
 ### Format Requirements
@@ -473,10 +732,21 @@ project-root/
 
 ---
 
+## References
+
+- [OpenAPI 3.1 Specification](https://spec.openapis.org/oas/v3.1.0) - Latest OpenAPI specification
+- [AsyncAPI 2.6 Specification](https://www.asyncapi.com/docs/reference/specification/v2.6.0) - Event-driven API documentation
+- [JSON Schema 2020-12](https://json-schema.org/draft/2020-12/json-schema-core.html) - JSON Schema specification
+- [Diátaxis Documentation Framework](https://diataxis.fr/) - Documentation structure methodology
+- [Write the Docs](https://www.writethedocs.org/guide/) - Documentation community best practices
+
+---
+
 ## Version History
 
 | Version | Date | Changes |
 |---------|------|---------|
+| 1.1.0 | 2026-01-24 | Added: AI Collaboration Documentation section, Token-aware document design, API Documentation Standards (OpenAPI 3.1, AsyncAPI 2.6) |
 | 1.0.1 | 2025-12-24 | Added: Related Standards section |
 | 1.0.0 | 2025-12-10 | Initial documentation writing standards |
 

package/bundled/core/error-code-standards.md

@@ -5,6 +5,9 @@
 **Version**: 1.1.0
 **Last Updated**: 2026-01-05
 **Applicability**: All software projects
+**Scope**: universal
+**Industry Standards**: RFC 7807, RFC 9457
+**References**: [datatracker.ietf.org](https://datatracker.ietf.org/doc/html/rfc7807)
 
 ---
 

package/bundled/core/forward-derivation-standards.md

@@ -1,8 +1,11 @@
 # Forward Derivation Standards | 正向推演標準
 
-**Version**: 1.0.0
-**Last Updated**: 2026-01-19
+**Version**: 1.1.0
+**Last Updated**: 2026-01-25
 **Applicability**: All projects using Spec-Driven Development
+**Scope**: uds-specific
+**Industry Standards**: JSON Schema 2020-12
+**References**: [specmatic.io](https://specmatic.io/)
 
 > **Language**: [English](../core/forward-derivation-standards.md) | [繁體中文](../locales/zh-TW/core/forward-derivation-standards.md)
 
@@ -54,6 +57,7 @@ This standard defines the principles and workflows for Forward Derivation—auto
 | **Generate BDD** | Transform AC to Gherkin scenarios | .feature files | [Generated] |
 | **Generate TDD** | Create test skeletons from AC | Test files with TODOs | [Generated] |
 | **Generate ATDD** | Create acceptance test tables | Markdown test tables | [Generated] |
+| **Generate Contracts** | Extract pre/post conditions | contract.json, schema.json | [Generated] |
 | **Human Review** | Verify generated outputs | Approved test structures | [Reviewed] |
 
 ---
@@ -306,6 +310,94 @@ describe('SPEC-001: User Authentication', () => {
 **Notes**: _______________
 ```
 
+### Contract Output (contract.json)
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "metadata": {
+    "generatedFrom": "specs/SPEC-001.md",
+    "generatedAt": "2026-01-25T10:00:00Z",
+    "generator": "forward-derivation v1.1.0",
+    "acCoverage": ["AC-1", "AC-2"]
+  },
+  "contracts": [
+    {
+      "id": "AC-1",
+      "name": "User login with valid credentials",
+      "preconditions": [
+        { "type": "state", "description": "User is registered in system" },
+        { "type": "input", "description": "Valid email and password provided" }
+      ],
+      "postconditions": [
+        { "type": "state", "description": "User session created" },
+        { "type": "output", "description": "Redirect to dashboard" }
+      ],
+      "invariants": [
+        { "description": "Session token is cryptographically secure" }
+      ]
+    },
+    {
+      "id": "AC-2",
+      "name": "Login fails with invalid credentials",
+      "preconditions": [
+        { "type": "input", "description": "Invalid credentials provided" }
+      ],
+      "postconditions": [
+        { "type": "state", "description": "No session created" },
+        { "type": "output", "description": "Error message displayed" }
+      ]
+    }
+  ]
+}
+```
+
+### Schema Output (schema.json)
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "metadata": {
+    "generatedFrom": "specs/SPEC-001.md",
+    "generatedAt": "2026-01-25T10:00:00Z",
+    "generator": "forward-derivation v1.1.0"
+  },
+  "schemas": {
+    "LoginRequest": {
+      "type": "object",
+      "required": ["email", "password"],
+      "properties": {
+        "email": {
+          "type": "string",
+          "format": "email",
+          "description": "[Source] SPEC-001 AC-1: Valid email required"
+        },
+        "password": {
+          "type": "string",
+          "minLength": 8,
+          "description": "[Source] SPEC-001 AC-1: Password required"
+        }
+      }
+    },
+    "LoginResponse": {
+      "type": "object",
+      "required": ["success"],
+      "properties": {
+        "success": { "type": "boolean" },
+        "sessionToken": {
+          "type": "string",
+          "description": "[Source] SPEC-001 AC-1: Session token on success"
+        },
+        "errorMessage": {
+          "type": "string",
+          "description": "[Source] SPEC-001 AC-2: Error message on failure"
+        }
+      }
+    }
+  }
+}
+```
+
 ---
 
 ## Bullet-to-GWT Transformation
@@ -400,7 +492,8 @@ spec-review → forward-derivation → discovery
 | `/derive-bdd` | SPEC-XXX.md | .feature | AC → Gherkin scenarios |
 | `/derive-tdd` | SPEC-XXX.md | .test.ts | AC → Test skeletons |
 | `/derive-atdd` | SPEC-XXX.md | acceptance.md | AC → Acceptance test tables |
-| `/derive-all` | SPEC-XXX.md | All above | Full derivation pipeline |
+| `/derive-contracts` | SPEC-XXX.md | contract.json, schema.json | AC → Contract and schema definitions |
+| `/derive-all` | SPEC-XXX.md | All above | Full derivation pipeline (BDD + TDD + ATDD + Contracts) |
 
 ### Command Parameters
 
@@ -420,7 +513,10 @@ spec-review → forward-derivation → discovery
 # Generate TDD test skeleton with Python/pytest
 /derive-tdd specs/SPEC-001.md --lang python --framework pytest
 
-# Generate all outputs
+# Generate contract and schema definitions for verification
+/derive-contracts specs/SPEC-001.md --output-dir ./contracts
+
+# Generate all outputs (BDD + TDD + ATDD + Contracts)
 /derive-all specs/SPEC-001.md --output-dir ./generated
 
 # Preview without creating files
@@ -479,10 +575,10 @@ spec-review → forward-derivation → discovery
 
 ### Skill References
 
-- [Forward Derivation Skill](../skills/claude-code/forward-derivation/SKILL.md) - Detailed workflow implementation
-- [Spec-Driven Development Skill](../skills/claude-code/spec-driven-dev/SKILL.md) - SDD workflow
-- [BDD Assistant Skill](../skills/claude-code/bdd-assistant/SKILL.md) - Gherkin refinement
-- [TDD Assistant Skill](../skills/claude-code/tdd-assistant/SKILL.md) - Test implementation
+- [Forward Derivation Skill](../skills/forward-derivation/SKILL.md) - Detailed workflow implementation
+- [Spec-Driven Development Skill](../skills/spec-driven-dev/SKILL.md) - SDD workflow
+- [BDD Assistant Skill](../skills/bdd-assistant/SKILL.md) - Gherkin refinement
+- [TDD Assistant Skill](../skills/tdd-assistant/SKILL.md) - Test implementation
 
 ---
 
@@ -497,10 +593,40 @@ spec-review → forward-derivation → discovery
 
 ---
 
+## References
+
+### Books
+
+- Steve Freeman & Nat Pryce - "Growing Object-Oriented Software, Guided by Tests" (2009) - Double-Loop TDD pattern foundation
+- Gojko Adzic - "Specification by Example" (2011) - Specification to test derivation concepts
+
+### Online Resources
+
+#### Contract Testing
+
+- [Microsoft: Consumer-Driven Contract Testing](https://microsoft.github.io/code-with-engineering-playbook/automated-testing/cdc-testing/) - Engineering playbook on CDC testing
+- [BrowserStack: Contract Testing Guide](https://www.browserstack.com/guide/contract-testing) - Comprehensive contract testing overview
+- [Specmatic: AI-powered API Contract Testing](https://specmatic.io/) - Modern contract-first development tool
+
+#### Verification Theory
+
+- [Wikipedia: Formal Verification](https://en.wikipedia.org/wiki/Formal_verification) - Theoretical foundations of verification
+- [Wikipedia: Design by Contract](https://en.wikipedia.org/wiki/Design_by_contract) - Bertrand Meyer's DbC concept (1986)
+
+#### SDD & Forward Derivation
+
+- [Thoughtworks: Spec-Driven Development](https://www.thoughtworks.com/en-us/insights/blog/agile-engineering-practices/spec-driven-development-unpacking-2025-new-engineering-practices) - SDD methodology definition
+- [Martin Fowler: SDD Tools (Kiro, spec-kit, Tessl)](https://martinfowler.com/articles/exploring-gen-ai/sdd-3-tools.html) - AI-era SDD tooling exploration
+- [GitHub spec-kit](https://github.com/github/spec-kit/blob/main/spec-driven.md) - GitHub's SDD implementation
+- [InfoQ: Spec-Driven Development](https://www.infoq.com/articles/spec-driven-development/) - SDD practices overview
+
+---
+
 ## Version History
 
 | Version | Date | Changes |
 |---------|------|---------|
+| 1.1.0 | 2026-01-25 | Added: Contract output (contract.json), Schema output (schema.json), /derive-contracts command for verification artifact generation |
 | 1.0.0 | 2026-01-19 | Initial release |
 
 ---