universal-dev-standards 4.0.0 → 4.2.0

package/bin/uds.js

@@ -8,6 +8,9 @@ import { checkCommand } from '../src/commands/check.js';
 import { updateCommand } from '../src/commands/update.js';
 import { configureCommand } from '../src/commands/configure.js';
 import { skillsCommand } from '../src/commands/skills.js';
+import { agentListCommand, agentInstallCommand, agentInfoCommand } from '../src/commands/agent.js';
+import { workflowListCommand, workflowInstallCommand, workflowInfoCommand } from '../src/commands/workflow.js';
+import { aiContextInitCommand, aiContextValidateCommand, aiContextGraphCommand } from '../src/commands/ai-context.js';
 import { setLanguage, setLanguageExplicit, detectLanguage } from '../src/i18n/messages.js';
 
 const require = createRequire(import.meta.url);
@@ -98,4 +101,76 @@ program
   .description('List installed Claude Code skills')
   .action(skillsCommand);
 
+// Agent command with subcommands
+const agentCommand = program
+  .command('agent')
+  .description('Manage UDS agents for AI tools');
+
+agentCommand
+  .command('list')
+  .description('List available and installed agents')
+  .option('--installed', 'Show installation status for all AI tools')
+  .action(agentListCommand);
+
+agentCommand
+  .command('install [agent-name]')
+  .description('Install agents (specify name or "all" for all agents)')
+  .option('-t, --tool <tool>', 'Target AI tool (default: claude-code)')
+  .option('-g, --global', 'Install to user level instead of project level')
+  .option('-y, --yes', 'Skip confirmation prompts')
+  .action(agentInstallCommand);
+
+agentCommand
+  .command('info <agent-name>')
+  .description('Show detailed information about an agent')
+  .action(agentInfoCommand);
+
+// Workflow command with subcommands
+const workflowCommand = program
+  .command('workflow')
+  .description('Manage UDS workflows for AI tools');
+
+workflowCommand
+  .command('list')
+  .description('List available and installed workflows')
+  .option('--installed', 'Show installation status for all AI tools')
+  .action(workflowListCommand);
+
+workflowCommand
+  .command('install [workflow-name]')
+  .description('Install workflows (specify name or "all" for all workflows)')
+  .option('-t, --tool <tool>', 'Target AI tool (default: claude-code)')
+  .option('-g, --global', 'Install to user level instead of project level')
+  .option('-y, --yes', 'Skip confirmation prompts')
+  .action(workflowInstallCommand);
+
+workflowCommand
+  .command('info <workflow-name>')
+  .description('Show detailed information about a workflow')
+  .action(workflowInfoCommand);
+
+// AI Context command with subcommands
+const aiContextCommand = program
+  .command('ai-context')
+  .description('Manage .ai-context.yaml configuration for AI-friendly architecture');
+
+aiContextCommand
+  .command('init')
+  .description('Generate .ai-context.yaml configuration file')
+  .option('-f, --force', 'Overwrite existing configuration')
+  .option('-y, --yes', 'Use defaults, skip interactive prompts')
+  .action(aiContextInitCommand);
+
+aiContextCommand
+  .command('validate')
+  .description('Validate .ai-context.yaml configuration')
+  .option('-v, --verbose', 'Show full configuration')
+  .action(aiContextValidateCommand);
+
+aiContextCommand
+  .command('graph')
+  .description('Show module dependency graph')
+  .option('-m, --mermaid', 'Output Mermaid diagram format')
+  .action(aiContextGraphCommand);
+
 program.parse();

package/bundled/core/ai-friendly-architecture.md

@@ -0,0 +1,542 @@
+# AI-Friendly Architecture Standards
+
+> **Language**: English | [繁體中文](../locales/zh-TW/core/ai-friendly-architecture.md)
+
+**Version**: 1.0.0
+**Last Updated**: 2026-01-21
+**Applicability**: All software projects collaborating with AI assistants
+
+---
+
+## Purpose
+
+This standard defines architecture and documentation practices that maximize the effectiveness of AI-assisted development. By following these guidelines, projects become more analyzable, understandable, and modifiable by AI tools while maintaining human readability.
+
+**Reference Concepts**:
+- RLM (Recursive Language Model) context management principles
+- Token-aware documentation design
+- Modular architecture for AI comprehension
+
+---
+
+## Table of Contents
+
+1. [Core Principles](#core-principles)
+2. [Module Design Standards](#module-design-standards)
+3. [Context Boundary Markers](#context-boundary-markers)
+4. [Documentation Layering](#documentation-layering)
+5. [Metadata Standards](#metadata-standards)
+6. [Query Interface Design](#query-interface-design)
+7. [AI Context Configuration](#ai-context-configuration)
+8. [Anti-Patterns](#anti-patterns)
+9. [Implementation Checklist](#implementation-checklist)
+
+---
+
+## Core Principles
+
+### 1. Explicit Over Implicit
+
+AI assistants perform best when behavior and structure are explicitly documented rather than implied through convention.
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                 Explicit vs Implicit                         │
+├─────────────────────────────────────────────────────────────┤
+│                                                              │
+│  ❌ IMPLICIT (Hard for AI)                                  │
+│  └── Magic naming conventions                               │
+│  └── Undocumented folder structures                         │
+│  └── Convention-based routing                               │
+│  └── Assumed knowledge of framework behavior                │
+│                                                              │
+│  ✅ EXPLICIT (AI-Friendly)                                  │
+│  └── Documented module responsibilities                     │
+│  └── Clear entry point annotations                          │
+│  └── Explicit dependency declarations                       │
+│  └── Self-documenting configuration files                   │
+│                                                              │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### 2. Layered Context
+
+Structure documentation in layers so AI can access appropriate detail levels based on task complexity.
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│               Context Layering Strategy                      │
+├─────────────────────────────────────────────────────────────┤
+│                                                              │
+│  Layer 1: Quick Reference (< 500 tokens)                    │
+│  └── One-liner descriptions                                 │
+│  └── API signatures only                                    │
+│  └── Key entry points                                       │
+│                                                              │
+│  Layer 2: Detailed Guide (< 5,000 tokens)                   │
+│  └── Full API documentation                                 │
+│  └── Usage examples                                         │
+│  └── Configuration options                                  │
+│                                                              │
+│  Layer 3: Full Examples (unlimited)                         │
+│  └── Complete implementation examples                       │
+│  └── Edge case documentation                                │
+│  └── Migration guides                                       │
+│                                                              │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### 3. Semantic Boundaries
+
+Design clear module boundaries that allow AI to analyze components independently without requiring full project context.
+
+### 4. Discoverable Structure
+
+Ensure project structure can be understood by analyzing configuration files and entry points without reading all source code.
+
+---
+
+## Module Design Standards
+
+### Single Responsibility at Module Level
+
+Each module should have a clearly defined, singular purpose that can be summarized in one sentence.
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│              Module Header Template                          │
+├─────────────────────────────────────────────────────────────┤
+│                                                              │
+│  /**                                                         │
+│   * @module auth                                             │
+│   * @description Handles user authentication and session    │
+│   *              management for the application.            │
+│   *                                                          │
+│   * @responsibility Authentication and authorization         │
+│   * @dependencies [database, crypto, config]                │
+│   * @exports {login, logout, verify, refreshToken}          │
+│   * @entrypoint ./index.ts                                  │
+│   */                                                         │
+│                                                              │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Clear Input/Output Contracts
+
+Every public interface should have explicit type definitions or documentation.
+
+| Element | Requirement | Example |
+|---------|-------------|---------|
+| Function Parameters | Type + description | `@param {string} email - User's email address` |
+| Return Values | Type + possible values | `@returns {Promise<User \| null>}` |
+| Side Effects | Documented explicitly | `@sideeffect Writes to database` |
+| Error Conditions | All possible errors | `@throws {AuthError} Invalid credentials` |
+
+### Explicit Dependency Declaration
+
+Dependencies should be declared at module level, not hidden in implementation details.
+
+**JavaScript/TypeScript:**
+```javascript
+// module: src/auth/index.ts
+// dependencies: [database, crypto, config]
+import { db } from '../database';
+import { hash } from '../crypto';
+import { config } from '../config';
+```
+
+**Python:**
+```python
+# module: src/auth/__init__.py
+# dependencies: [database, crypto, config]
+from ..database import db
+from ..crypto import hash_password
+from ..config import settings
+```
+
+---
+
+## Context Boundary Markers
+
+### Module Header Comments
+
+Use standardized header comments that AI can parse for quick module understanding.
+
+```javascript
+/**
+ * ═══════════════════════════════════════════════════════════
+ * MODULE: Payment Processing
+ * ═══════════════════════════════════════════════════════════
+ *
+ * PURPOSE: Handles all payment-related operations including
+ *          processing, refunds, and subscription management.
+ *
+ * DEPENDENCIES:
+ *   - stripe: Payment gateway integration
+ *   - database: Transaction storage
+ *   - events: Payment event publishing
+ *
+ * EXPORTS:
+ *   - processPayment(amount, method): Process single payment
+ *   - refund(transactionId): Issue refund
+ *   - createSubscription(plan): Start subscription
+ *
+ * CONFIGURATION:
+ *   - STRIPE_SECRET_KEY: Required
+ *   - PAYMENT_WEBHOOK_SECRET: Required
+ *
+ * ═══════════════════════════════════════════════════════════
+ */
+```
+
+### Section Dividers
+
+Use consistent section dividers within large files:
+
+```javascript
+// ============================================================
+// SECTION: Validation Helpers
+// ============================================================
+
+// ... validation code ...
+
+// ============================================================
+// SECTION: API Handlers
+// ============================================================
+
+// ... handler code ...
+```
+
+---
+
+## Documentation Layering
+
+### Level 1: Quick Reference (< 500 tokens)
+
+Create `QUICK-REF.md` in each major module:
+
+```markdown
+# Auth Module - Quick Reference
+
+## Purpose
+User authentication and session management.
+
+## Key Functions
+- `login(email, password)` → `Promise<Session>`
+- `logout(sessionId)` → `void`
+- `verify(token)` → `Promise<User | null>`
+
+## Configuration
+- `AUTH_SECRET`: JWT signing secret
+- `SESSION_DURATION`: Session lifetime (default: 24h)
+
+## Entry Point
+`src/auth/index.ts`
+```
+
+### Level 2: Detailed Guide (< 5,000 tokens)
+
+Main `README.md` with comprehensive documentation:
+
+```markdown
+# Authentication Module
+
+## Overview
+[2-3 paragraph description]
+
+## Architecture
+[Diagram or description of internal structure]
+
+## API Reference
+[Full function signatures with parameters]
+
+## Configuration Options
+[All configuration with defaults and descriptions]
+
+## Usage Examples
+[Common use cases with code samples]
+
+## Error Handling
+[Error types and handling strategies]
+```
+
+### Level 3: Full Examples (unlimited)
+
+Separate `examples/` directory with complete implementations:
+
+```
+auth/
+├── QUICK-REF.md          # Level 1
+├── README.md             # Level 2
+└── examples/             # Level 3
+    ├── basic-login.ts
+    ├── oauth-integration.ts
+    └── custom-middleware.ts
+```
+
+---
+
+## Metadata Standards
+
+### Package Metadata Extensions
+
+Extend standard package files with AI-relevant metadata:
+
+**package.json (JavaScript/TypeScript):**
+```json
+{
+  "name": "my-project",
+  "ai-context": {
+    "entryPoints": ["src/index.ts", "src/api/index.ts"],
+    "modules": {
+      "auth": "src/auth/",
+      "api": "src/api/",
+      "database": "src/db/"
+    },
+    "ignorePatterns": ["node_modules", "dist", "coverage"],
+    "quickRef": "docs/QUICK-REF.md"
+  }
+}
+```
+
+**pyproject.toml (Python):**
+```toml
+[tool.ai-context]
+entry_points = ["src/main.py", "src/api/__init__.py"]
+modules = { auth = "src/auth/", api = "src/api/" }
+ignore_patterns = ["__pycache__", ".venv", "*.pyc"]
+quick_ref = "docs/QUICK-REF.md"
+```
+
+### .ai-context.yaml Configuration
+
+Dedicated AI context configuration file:
+
+```yaml
+# .ai-context.yaml - AI Context Configuration
+version: 1.0.0
+
+project:
+  name: my-project
+  type: web-app  # web-app | library | cli | api | monorepo
+  primary-language: typescript
+
+modules:
+  - name: auth
+    path: src/auth/
+    entry: index.ts
+    description: Authentication and authorization
+    dependencies: [database, crypto]
+    priority: high
+
+  - name: api
+    path: src/api/
+    entry: routes.ts
+    description: REST API endpoints
+    dependencies: [auth, database]
+    priority: high
+
+  - name: utils
+    path: src/utils/
+    entry: index.ts
+    description: Shared utility functions
+    dependencies: []
+    priority: low
+
+analysis-hints:
+  entry-points:
+    - src/main.ts
+    - src/index.ts
+  ignore-patterns:
+    - node_modules
+    - dist
+    - coverage
+    - "*.test.ts"
+  architecture-type: layered  # layered | microservices | modular | monolith
+
+documentation:
+  quick-ref: docs/QUICK-REF.md
+  detailed: docs/ARCHITECTURE.md
+  examples: docs/examples/
+
+context-strategy:
+  max-chunk-size: 50000
+  overlap: 500
+  analysis-pattern: hierarchical
+```
+
+---
+
+## Query Interface Design
+
+### Structured API Documentation Format
+
+Design API documentation that's easy to query:
+
+```markdown
+## API: createUser
+
+**Endpoint**: `POST /api/users`
+**Module**: `src/api/users.ts:45`
+
+### Parameters
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| email | string | Yes | User's email address |
+| password | string | Yes | Min 8 characters |
+| name | string | No | Display name |
+
+### Response
+```json
+{
+  "id": "string",
+  "email": "string",
+  "createdAt": "ISO8601"
+}
+```
+
+### Errors
+| Code | Condition |
+|------|-----------|
+| 400 | Invalid email format |
+| 409 | Email already exists |
+
+### Example
+```javascript
+const user = await api.createUser({
+  email: 'user@example.com',
+  password: 'securePassword123'
+});
+```
+```
+
+### Searchable Code Annotations
+
+Use consistent annotation patterns that AI can search for:
+
+```javascript
+// @ai-hint: This function is performance-critical
+// @ai-complexity: O(n log n)
+// @ai-dependencies: [sortUtils, comparators]
+function sortLargeDataset(data) {
+  // ...
+}
+
+// @ai-security: Validates user input
+// @ai-validation: email, password strength
+function validateRegistration(input) {
+  // ...
+}
+```
+
+---
+
+## AI Context Configuration
+
+### Recommended Directory Structure
+
+```
+project/
+├── .ai-context.yaml          # AI context configuration
+├── docs/
+│   ├── QUICK-REF.md          # Level 1 documentation
+│   ├── ARCHITECTURE.md       # Level 2 documentation
+│   └── examples/             # Level 3 documentation
+├── src/
+│   ├── auth/
+│   │   ├── index.ts          # Entry point with module header
+│   │   ├── QUICK-REF.md      # Module-level quick reference
+│   │   └── README.md         # Module documentation
+│   ├── api/
+│   │   ├── index.ts
+│   │   └── README.md
+│   └── index.ts              # Application entry point
+└── CLAUDE.md / INSTRUCTIONS.md  # AI instruction file
+```
+
+### Context Priority Guidelines
+
+When AI context is limited, prioritize:
+
+| Priority | Content Type | Reason |
+|----------|--------------|--------|
+| 1 | Entry points | Understand application structure |
+| 2 | .ai-context.yaml | Module map and dependencies |
+| 3 | QUICK-REF files | Rapid API understanding |
+| 4 | Modified files | Direct task relevance |
+| 5 | Dependency chain | Context for changes |
+
+---
+
+## Anti-Patterns
+
+### ❌ Patterns to Avoid
+
+| Anti-Pattern | Problem | Solution |
+|--------------|---------|----------|
+| **Magic strings** | AI can't trace constants | Use typed constants with documentation |
+| **Implicit routing** | Hidden behavior | Document route mappings explicitly |
+| **Global state** | Unpredictable dependencies | Dependency injection with explicit wiring |
+| **Circular dependencies** | Context confusion | Clear hierarchical dependencies |
+| **Monolithic files** | Context overflow | Split into focused modules |
+| **Convention over documentation** | Assumed knowledge | Explicit documentation |
+
+### ❌ Documentation Anti-Patterns
+
+| Anti-Pattern | Problem | Solution |
+|--------------|---------|----------|
+| **Outdated docs** | Misleading AI | Keep docs in sync with code |
+| **Generated only** | Missing context | Add human-written context |
+| **No examples** | Ambiguous usage | Include working examples |
+| **Wall of text** | Hard to parse | Use structured formats |
+
+---
+
+## Implementation Checklist
+
+### Quick Start (< 1 hour)
+
+- [ ] Create `.ai-context.yaml` with module list
+- [ ] Add `QUICK-REF.md` to project root
+- [ ] Document entry points in README
+- [ ] Add module headers to main files
+
+### Standard Implementation (< 1 day)
+
+- [ ] Complete `.ai-context.yaml` configuration
+- [ ] Add `QUICK-REF.md` to each major module
+- [ ] Document all public APIs with type information
+- [ ] Add section dividers to large files
+- [ ] Create dependency documentation
+
+### Full Implementation (< 1 week)
+
+- [ ] Three-layer documentation for all modules
+- [ ] Searchable code annotations
+- [ ] Examples directory with use cases
+- [ ] Architecture diagrams
+- [ ] Integration with CI for doc validation
+
+---
+
+## Version History
+
+| Version | Date | Changes |
+|---------|------|---------|
+| 1.0.0 | 2026-01-21 | Initial release |
+
+---
+
+## Related Standards
+
+- [Project Structure](./project-structure.md) - Directory organization
+- [Documentation Structure](./documentation-structure.md) - Documentation organization
+- [Anti-Hallucination](./anti-hallucination.md) - AI accuracy standards
+
+---
+
+## License
+
+This standard is released under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).
+
+**Source**: [universal-dev-standards](https://github.com/AsiaOstrich/universal-dev-standards)