universal-dev-standards 5.3.2 → 5.5.0

package/bundled/skills/ai-instruction-standards/SKILL.md

@@ -2,18 +2,18 @@
 name: ai-instruction-standards
 scope: partial
 description: |
-  Create and maintain AI instruction files (CLAUDE.md, .cursorrules, etc.) with proper structure.
+  Create and maintain AI instruction files (CLAUDE.md, AGENTS.md, .cursor/rules/, etc.) with proper structure.
   Use when: creating AI instruction files, separating universal vs project-specific rules, configuring AI tools.
-  Keywords: CLAUDE.md, cursorrules, windsurfrules, clinerules, AI instructions, system prompt, 指令檔案, AI 設定.
+  Keywords: CLAUDE.md, AGENTS.md, cursorrules, windsurfrules, clinerules, AI instructions, system prompt, 指令檔案, AI 設定.
 ---
 
 # AI Instruction File Standards Guide
 
 > **Language**: English | [繁體中文](../../locales/zh-TW/skills/ai-instruction-standards/SKILL.md)
 
-**Version**: 1.0.0
-**Last Updated**: 2026-01-25
-**Applicability**: Claude Code Skills
+**Version**: 2.0.0
+**Last Updated**: 2026-04-28
+**Applicability**: All AI coding tools
 
 ---
 
@@ -23,28 +23,54 @@ description: |
 
 This skill is part of a three-layer AI collaboration system:
 
-| Layer | Skill | Question it Answers | 回答的問題 |
-|-------|-------|-------------------|-----------|
-| **Behavior** (Immediate) | `/ai-collaboration` | "How should AI respond accurately?" | 「AI 如何準確回應？」 |
-| **Configuration** (Session) | `/ai-instruction-standards` (this) | "What to write in CLAUDE.md?" | 「CLAUDE.md 該寫什麼？」 |
-| **Architecture** (Long-term) | `/ai-friendly-architecture` | "How to structure code for AI?" | 「如何讓專案對 AI 友善？」 |
+| Layer | Skill | Question it Answers |
+|-------|-------|-------------------|
+| **Behavior** (Immediate) | `/ai-collaboration` | "How should AI respond accurately?" |
+| **Configuration** (Session) | `/ai-instruction-standards` (this) | "What to write in CLAUDE.md / AGENTS.md?" |
+| **Architecture** (Long-term) | `/ai-friendly-architecture` | "How to structure code for AI?" |
 
 ## Purpose
 
-This skill helps create and maintain AI instruction files with proper separation between universal standards and project-specific configurations.
+This skill helps create and maintain AI instruction files with proper separation between universal standards and project-specific configurations, across all major AI coding tools.
+
+---
 
 ## Quick Reference
 
-### Supported AI Tools
+### Supported AI Tools (2026-04-28)
+
+#### CLI / Agent Tools (Terminal)
+
+| Tool | Primary File | Workflow Mechanism | MCP |
+|------|-------------|-------------------|-----|
+| **Claude Code** | `CLAUDE.md` + `.claude/rules/*.md` | Skills (`.claude/skills/` → `/{name}`) | ✅ |
+| **Gemini CLI** | `GEMINI.md` | `.gemini/commands/*.toml` → `/{name}` | ✅ |
+| **OpenAI Codex CLI** | `AGENTS.md` (+ `AGENTS.override.md`) | Team commands; `/review` built-in | ✅ |
+| **OpenCode** | `AGENTS.md` (CLAUDE.md compatible) | Built-in only (`/init` `/undo` `/share`) | ✅ |
+
+#### AI-native IDE / Editor Integration
+
+| Tool | Primary File | Workflow Mechanism | MCP |
+|------|-------------|-------------------|-----|
+| **Cursor** | `.cursor/rules/*.mdc` ⚠️ | `@`-mentions; `/multitask` | ✅ |
+| **GitHub Copilot** | `.github/copilot-instructions.md` | `.github/prompts/*.prompt.md` → `/{name}` | ✅ |
+| **Windsurf** | `.windsurfrules` / `.windsurf/rules/*.md` | `.windsurf/workflows/*.md` → `/{name}` | ✅ |
+| **Cline** | `.clinerules` | None | ✅ |
+
+> ⚠️ **Cursor**: `.cursorrules` is **deprecated** — migrate to `.cursor/rules/*.mdc`
+
+---
+
+### Cross-Tool Universal Standard: `AGENTS.md`
+
+`AGENTS.md` is the emerging de-facto cross-tool instruction standard:
+
+**Supported by**: Gemini CLI, OpenAI Codex CLI, OpenCode, GitHub Copilot, Windsurf, Cursor
+**Not supported by**: Claude Code (uses `CLAUDE.md`), Cline (uses `.clinerules`)
 
-| AI Tool | Instruction File | Format |
-|---------|-----------------|--------|
-| Claude Code | `CLAUDE.md` | Markdown |
-| Cursor | `.cursorrules` | Markdown |
-| Windsurf | `.windsurfrules` | Markdown |
-| Cline | `.clinerules` | Markdown |
-| GitHub Copilot | `.github/copilot-instructions.md` | Markdown |
-| OpenCode | `.opencode/instructions.md` | Markdown |
+**Recommendation**: Use `AGENTS.md` as the universal baseline for cross-tool projects, then add tool-specific files for advanced features (Skills, Workflows, Prompts).
+
+---
 
 ### Core Principle: Universal vs Project-Specific
 
@@ -53,6 +79,8 @@ This skill helps create and maintain AI instruction files with proper separation
 | **Universal** | Generic rules | "Run tests before committing" |
 | **Project-Specific** | Concrete commands | "Run `npm test` before committing" |
 
+---
+
 ### Recommended Layout
 
 ```markdown
@@ -80,89 +108,152 @@ This skill helps create and maintain AI instruction files with proper separation
 [Your project structure]
 ```
 
-## Detailed Guidelines
+---
 
-For complete standards, see:
-- [AI Instruction File Standards](../../core/ai-instruction-standards.md)
+## Tool-Specific Setup Guides
 
-### AI-Optimized Format (Token-Efficient)
+### Claude Code
 
-For AI assistants, use the YAML format file for reduced token usage:
-- Base standard: `ai/standards/ai-instruction-standards.ai.yaml`
+```
+CLAUDE.md                        # Main instructions (hierarchical: global → project → subdir)
+.claude/rules/                   # Glob-scoped additional rules
+.claude/skills/{name}/SKILL.md   # Custom slash commands → /{name}
+.claude/agents/{name}.md         # Subagent definitions
+```
 
-## Content Guidelines
+### Gemini CLI
 
-### Universal Content (Keep Generic)
+```
+GEMINI.md                          # Main instructions
+.gemini/commands/{name}.toml       # Custom slash commands → /{name}
+.gemini/agents/{name}.yaml         # Subagent definitions
+```
 
-| Category | Good Examples |
-|----------|---------------|
-| **Commit Standards** | "Follow Conventional Commits format" |
-| **Code Review** | "Use BLOCKING, IMPORTANT, SUGGESTION prefixes" |
-| **Testing** | "Maintain 80% coverage minimum" |
-| **AI Behavior** | "Always read code before analyzing" |
+Example `.gemini/commands/review.toml`:
+```toml
+description = "Run code review checklist"
+prompt = "Review the following changes: !{git diff HEAD}"
+```
 
-**Avoid in Universal Sections:**
-- Specific commands (`npm test`, `pytest`)
-- Hardcoded paths (`cli/src/`, `/var/www/`)
-- Version numbers (`Node.js 18`, `Python 3.11`)
-- Project names and URLs
+### OpenAI Codex CLI
 
-### Project-Specific Content
+```
+AGENTS.md                  # Main instructions (Git root → cwd traversal)
+AGENTS.override.md         # Temporary override (highest priority)
+~/.codex/AGENTS.md         # Global fallback
+.codex/agents/             # Custom agent definitions
+```
 
-| Category | Examples |
-|----------|----------|
-| **Tech Stack** | Node.js 18, React 18, PostgreSQL 15 |
-| **Commands** | `npm run lint`, `./scripts/deploy.sh` |
-| **File Structure** | `src/`, `cli/`, `tests/` |
-| **Team Conventions** | Traditional Chinese comments |
+### OpenCode
 
-## Labeling Convention
+```
+AGENTS.md                       # Primary (auto-recognized)
+CLAUDE.md                       # Also recognized (migration compatibility)
+.opencode/agents/               # Custom agent definitions
+opencode.json (instructions)    # Glob-pattern file references
+```
 
-### Option A: Section Headers
+### Cursor
 
-```markdown
-## Universal Standards
-[universal content]
+```
+.cursor/rules/                  # MDC format rules (replaces .cursorrules)
+  {name}.mdc                    # Frontmatter: description, globs, alwaysApply
+AGENTS.md                       # Also supported for agent context
+```
 
-## Project-Specific Configuration
-[project-specific content]
+MDC frontmatter example:
+```yaml
+---
+description: "TypeScript coding standards"
+globs: ["**/*.ts", "**/*.tsx"]
+alwaysApply: false
+---
 ```
 
-### Option B: Inline Markers
+> **Migration**: If you have `.cursorrules`, move content to `.cursor/rules/*.mdc`.
 
-```markdown
-> ⚠️ **Project-Specific**: This section contains configuration unique to this project.
+### GitHub Copilot
 
-### Tech Stack
-...
+```
+.github/copilot-instructions.md         # Always-on, all chats
+.github/instructions/*.instructions.md  # File-glob scoped (applyTo frontmatter)
+.github/prompts/*.prompt.md             # Reusable templates → /{name} slash commands
+.github/agents/*.agent.md               # Custom agents with tool access control
+AGENTS.md                               # Also recognized
 ```
 
-### Option C: Comment Annotations
+### Windsurf
 
-```markdown
-<!-- UNIVERSAL: The following applies to all projects -->
-### Commit Message Format
-...
+```
+.windsurfrules                   # Project rules (team-shareable)
+.windsurf/rules/*.md             # MDC frontmatter structured rules
+.windsurf/workflows/*.md         # Reusable task sequences → /{name}
+AGENTS.md                        # Also recognized
+```
 
-<!-- PROJECT-SPECIFIC: Customize for your project -->
-### Quick Commands
-...
+Workflow example (`.windsurf/workflows/review.md`):
+```markdown
+Run a code review:
+1. Run `git diff HEAD`
+2. Check for BLOCKING issues (security, correctness)
+3. Check for IMPORTANT issues (design, tests)
+4. Output findings with BLOCKING/IMPORTANT/SUGGESTION prefixes
 ```
 
-## Multi-Tool Configuration
+---
+
+## Multi-Tool Project Configuration
 
-When using multiple AI tools, maintain consistency:
+When a project uses multiple AI tools:
 
 ```
 project/
-├── CLAUDE.md              # Claude Code instructions
-├── .cursorrules           # Cursor instructions (can import from CLAUDE.md)
-├── .windsurfrules         # Windsurf instructions
+├── AGENTS.md                            # Universal baseline (cross-tool)
+├── CLAUDE.md                            # Claude Code (extends AGENTS.md)
+├── GEMINI.md                            # Gemini CLI
+├── .cursor/rules/
+│   └── standards.mdc                    # Cursor
+├── .windsurf/
+│   └── workflows/                       # Windsurf workflows
+│       ├── review.md
+│       └── checkin.md
 └── .github/
-    └── copilot-instructions.md  # Copilot instructions
+    ├── copilot-instructions.md          # Copilot always-on
+    └── prompts/
+        └── review.prompt.md             # Copilot slash command
 ```
 
-**Best Practice**: Create a shared `docs/ai-standards.md` and reference it from each tool's file to avoid duplication.
+**Best Practice**: Write universal content in `AGENTS.md` once, then import/reference it from tool-specific files to avoid duplication.
+
+---
+
+## Content Guidelines
+
+### Universal Content (Keep Generic)
+
+| Category | Good Examples |
+|----------|---------------|
+| **Commit Standards** | "Follow Conventional Commits format" |
+| **Code Review** | "Use BLOCKING, IMPORTANT, SUGGESTION prefixes" |
+| **Testing** | "Maintain 80% coverage minimum" |
+| **AI Behavior** | "Always read code before analyzing" |
+
+**Avoid in Universal Sections:**
+- Specific commands (`npm test`, `pytest`)
+- Hardcoded paths (`cli/src/`, `/var/www/`)
+- Version numbers (`Node.js 18`, `Python 3.11`)
+- Project names and URLs
+
+### Project-Specific Content
+
+| Category | Examples |
+|----------|----------|
+| **Tech Stack** | Node.js 18, React 18, PostgreSQL 15 |
+| **Commands** | `npm run lint`, `./scripts/deploy.sh` |
+| **File Structure** | `src/`, `cli/`, `tests/` |
+| **Team Conventions** | Traditional Chinese comments |
+
+---
 
 ## Maintenance Checklist
 
@@ -172,38 +263,39 @@ Before committing changes to AI instruction files:
 - [ ] Project-specific sections are clearly marked
 - [ ] Cross-references to standards documents are correct
 - [ ] Format matches existing sections
+- [ ] If using Cursor: `.cursorrules` migrated to `.cursor/rules/*.mdc`
+- [ ] If multi-tool project: `AGENTS.md` covers the universal baseline
 
 ---
 
 ## Configuration Detection
 
-This skill supports project-specific configuration.
-
 ### Detection Order
 
-1. Check for existing `CLAUDE.md` or equivalent files
-2. Analyze content structure for universal/project-specific separation
-3. If not found, **suggest creating structured AI instruction file**
+1. Check for existing `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, or equivalent files
+2. Detect which AI tools are in use (check for `.cursor/`, `.windsurf/`, `.github/copilot-instructions.md`, etc.)
+3. Analyze content structure for universal/project-specific separation
+4. If not found, **suggest creating structured AI instruction file**
 
 ### First-Time Setup
 
 If no AI instruction file found:
 
-1. Ask: "This project doesn't have an AI instruction file. Would you like to create one?"
-2. Determine project type and tech stack
-3. Generate template with appropriate sections
-4. Add to `.gitignore` if contains sensitive info
+1. Ask: "This project doesn't have an AI instruction file. Which AI tools do you use?"
+2. Recommend `AGENTS.md` for cross-tool projects, `CLAUDE.md` for Claude Code only
+3. Determine project type and tech stack
+4. Generate template with appropriate sections
+5. Add to `.gitignore` if contains sensitive info
 
 ---
 
-## Next Steps Guidance | 下一步引導
+## Next Steps Guidance
 
-After `/ai-instructions` completes, the AI assistant should suggest:
+After `/ai-instructions` completes, suggest:
 
-> **AI 指令檔案標準已掌握。建議下一步 / AI instruction file standards understood. Suggested next steps:**
-> - 建立或更新專案的 `CLAUDE.md`（或對應的 AI 指令檔案） ⭐ **Recommended / 推薦** — 立即將標準應用到專案中 / Apply standards to the project immediately
-> - 執行 `/ai-friendly-architecture` 從架構層面優化 AI 協作 — 配合指令檔案提升 AI 理解力 / Enhance AI understanding alongside instruction files
-> - 執行 `/ai-collaboration` 複習 AI 行為準則 — 確保指令檔案中的規則與行為標準一致 / Ensure instruction file rules align with behavior standards
+> - Create or update project's `CLAUDE.md` / `AGENTS.md` ⭐ **Recommended** — Apply standards immediately
+> - Run `/ai-friendly-architecture` to optimize AI collaboration at the architecture level
+> - Run `/ai-collaboration` to review AI behavior guidelines
 
 ---
 
@@ -220,6 +312,7 @@ After `/ai-instructions` completes, the AI assistant should suggest:
 
 | Version | Date | Changes |
 |---------|------|---------|
+| 2.0.0 | 2026-04-28 | Add Gemini CLI, OpenAI Codex CLI; update Cursor (MDC format, deprecated .cursorrules); update OpenCode (AGENTS.md primary); update Copilot (multiple file types); update Windsurf (Workflows); add AGENTS.md cross-tool standard section |
 | 1.0.0 | 2026-01-25 | Initial release |
 
 ---

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

@@ -5,6 +5,14 @@ description: "[UDS] Guide through Acceptance Test-Driven Development workflow"
 allowed-tools: Read, Write, Grep, Glob
 argument-hint: "[feature or spec | 功能或規格]"
 ---
+<!-- DEPRECATION NOTICE (XSPEC-086 Phase 4, 2026-04-28):
+  ATDD lifecycle orchestration (5-phase: WORKSHOP→DISTILLATION→DEVELOPMENT→DEMO→DONE,
+  INVEST validation, AC→Gherkin conversion, RED/GREEN execution, PO sign-off gates) extracted to:
+  - DevAP flow: dev-autopilot/.devap/flows/atdd.flow.yaml
+  - DevAP CLI:  devap atdd (packages/cli/src/commands/atdd.ts)
+  This Skill retains: INVEST criteria table, ATDD cycle diagram, Gherkin AC format, Three Amigos structure.
+  Use `devap atdd` for enforced lifecycle; this Skill for format and principle reference.
+-->
 
 # ATDD Assistant | ATDD 助手
 

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

@@ -5,6 +5,13 @@ description: "[UDS] Guide through Behavior-Driven Development workflow"
 allowed-tools: Read, Write, Grep, Glob
 argument-hint: "[feature or spec | 功能或規格]"
 ---
+<!-- DEPRECATION NOTICE (XSPEC-086 Phase 4, 2026-04-28):
+  BDD lifecycle orchestration (4-phase cycle, Gherkin scaffolding, RED/GREEN execution) extracted to:
+  - DevAP flow: dev-autopilot/.devap/flows/bdd.flow.yaml
+  - DevAP CLI:  devap bdd (packages/cli/src/commands/bdd.ts)
+  This Skill retains: Gherkin format definition, Three Amigos structure, BDD cycle diagram.
+  Use `devap bdd` for enforced cycle; this Skill for format and principle reference.
+-->
 
 # BDD Assistant | BDD 助手
 

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

@@ -5,6 +5,14 @@ description: "[UDS] Pre-commit quality gates verification"
 allowed-tools: Read, Grep, Glob, Bash(git diff:*), Bash(git status:*), Bash(npm test:*), Bash(npm run lint:*)
 disable-model-invocation: true
 ---
+<!-- DEPRECATION NOTICE (XSPEC-086 Phase 4, 2026-04-28):
+  Checkin workflow orchestration (gate execution sequence, abort logic) extracted to:
+  - DevAP flow: dev-autopilot/.devap/flows/checkin.flow.yaml
+  - DevAP CLI:  devap checkin (packages/cli/src/commands/checkin.ts)
+  - Flow spec:  dev-autopilot/standards/flow/checkin-gate-sequence.ai.yaml
+  This Skill retains: quality gate definitions, checklist items, never-commit rules.
+  Use `devap checkin` for enforced execution; this Skill for activity reference.
+-->
 
 # Check-in Assistant | 簽入助手
 

package/bundled/skills/code-review-assistant/SKILL.md

@@ -6,6 +6,13 @@ allowed-tools: Read, Grep, Glob, Bash(git diff:*), Bash(git log:*), Bash(git sho
 argument-hint: "[file path or branch | 檔案路徑或分支名稱]"
 disable-model-invocation: true
 ---
+<!-- DEPRECATION NOTICE (XSPEC-086 Phase 4, 2026-04-28):
+  Code review workflow orchestration (4-step sequence, outcome gating) extracted to:
+  - DevAP flow: dev-autopilot/.devap/flows/review.flow.yaml
+  - DevAP CLI:  devap review (packages/cli/src/commands/review.ts)
+  This Skill retains: 8 review category definitions, BLOCKING/IMPORTANT/SUGGESTION/QUESTION/NOTE prefix semantics.
+  Use `devap review` for enforced execution; this Skill for category and prefix reference.
+-->
 
 # Code Review Assistant | 程式碼審查助手
 

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

@@ -0,0 +1,203 @@
+---
+name: journey-test-assistant
+scope: partial
+description: "[UDS] 從專案描述生成連貫使用者旅程測試計畫（TESTPLAN）與 E2E 骨架"
+allowed-tools: Read, Write, Grep, Glob
+argument-hint: "[project description | --analyze | --archetype A1|A2|A3]"
+status: stable
+---
+
+# Journey Test Assistant | 旅程測試助手
+
+從專案描述生成連貫的使用者旅程測試計畫（TESTPLAN-NNN.md）與對應的 E2E 骨架，讓每個新專案從第一天起就擁有完整測試旅程。
+
+## 與 /e2e 的差異
+
+| 維度 | /e2e | /journey-test |
+|------|------|--------------|
+| 組織單位 | 單一 XSPEC/AC | 跨 Story 的使用者旅程 |
+| 測試結構 | 隔離、獨立 | 連貫、狀態共享 |
+| 產物 | `*.spec.ts` 骨架 | `TESTPLAN.md` + `*.journey.spec.ts` |
+| 觸發時機 | 功能完成後 | 專案建立時（Journey-First） |
+| 偵測目標 | 單一 AC 是否正確 | 跨步驟狀態傳遞是否連貫 |
+
+## 工作流程
+
+```
+輸入：專案描述 / 現有 TESTPLAN / --analyze
+    ↓
+Phase 1：定義 Persona
+    分析專案描述 → 識別所有使用者角色 → 定義 Actor/Role/Key Permissions
+    ↓
+Phase 2：設計旅程地圖
+    列出主要業務目標 → 拆解為 T-NNN 群組 → 宣告依賴鏈
+    ↓
+Phase 3：生成 TESTPLAN
+    按格式輸出 test-plans/TESTPLAN-001.md（含 Personas、步驟、依賴圖）
+    ↓
+Phase 4：生成 E2E 骨架
+    從 TESTPLAN T-NNN 生成 *.journey.spec.ts（含 skipIf + 共享 state）
+```
+
+## 模式
+
+### 1. 生成模式（預設）
+
+從專案描述生成完整的 TESTPLAN + E2E 骨架。
+
+```
+/journey-test "電商平台，需要 buyer/seller/admin 三個角色"
+```
+
+產物：
+- `test-plans/TESTPLAN-001.md`：含 Personas、T-000 環境重置、T-001~T-NNN 步驟群組、執行順序依賴圖
+- `src/e2e/journey/main-flow.journey.spec.ts`：含 `describe.skipIf` + 共享 state + T-NNN 對應的完整骨架
+
+### 2. 分析模式（--analyze）
+
+掃描現有測試，找出旅程覆蓋缺口。
+
+```
+/journey-test --analyze
+```
+
+執行步驟：
+1. 讀取 `test-plans/TESTPLAN-NNN.md`（若存在）
+2. 掃描 `src/e2e/` 下所有 `*.journey.spec.ts` 和 `*.journey.e2e.test.ts`
+3. 比對 TESTPLAN T-NNN 與自動化測試中的 T-NNN 引用
+4. 輸出 Coverage gap 報告：列出 TESTPLAN 中缺乏自動化對應的 T-NNN 步驟
+
+### 3. Archetype 模式（--archetype）
+
+使用預設旅程模板，適合已知類型的專案快速啟動。
+
+```
+/journey-test --archetype A1    # Spec-driven 旅程
+/journey-test --archetype A2    # UI-driven 旅程
+/journey-test --archetype A3    # Brownfield 旅程
+```
+
+| Archetype | 模板 | 適用場景 |
+|-----------|------|---------|
+| A1 | Spec-driven | 需求 → Spec → Code → Test，適合 API/Backend 專案 |
+| A2 | UI-driven | 設計稿 → UI → 視覺回歸，適合前端/全端專案 |
+| A3 | Brownfield | 現有程式碼 → 分析 → 重構驗證，適合既有專案補測試 |
+
+## TESTPLAN 格式（T-NNN）
+
+以下為完整的 TESTPLAN 範本，展示所有必要區段：
+
+```markdown
+# TESTPLAN-001 <ProjectName> 主線旅程
+
+## Personas
+
+| Actor         | Role          | Key Permissions              |
+|---------------|---------------|------------------------------|
+| platform_admin | Platform Admin | 建立 Org、管理使用者、查看所有資源 |
+| org_member    | Org Member    | 讀取專案、執行 Pipeline         |
+
+## Environment
+
+- BASE_URL：`http://localhost:3000`（本機）/ `$JOURNEY_BASE_URL`（CI）
+- 驗證指令：`curl $BASE_URL/health`
+- 必要帳號：`ADMIN_EMAIL`、`ADMIN_PASSWORD` 環境變數
+
+## T-000 環境重置（optional）
+
+前置條件：無
+depends_on：無
+
+| 步驟    | 操作                              | 預期結果        |
+|---------|-----------------------------------|-----------------|
+| T-000-1 | [API] GET /health                | 回傳 200 OK     |
+| T-000-2 | [CHECK] 資料庫連線正常            | 無錯誤日誌      |
+
+## T-001 Platform Admin 登入
+
+前置條件：環境正常運行（T-000 通過）
+depends_on：T-000
+
+| 步驟    | 操作                                        | 預期結果                 |
+|---------|---------------------------------------------|--------------------------|
+| T-001-1 | [API] POST /api/auth/login（admin 帳號）    | 回傳 200 + authToken     |
+| T-001-2 | [CHECK] authToken 存入共享 state            | let authToken 有值       |
+
+## T-010 主要功能操作
+
+前置條件：authToken 已取得（T-001 通過）
+depends_on：T-001
+
+| 步驟    | 操作                                        | 預期結果                 |
+|---------|---------------------------------------------|--------------------------|
+| T-010-1 | [API] POST /api/resources（帶 authToken）   | 回傳 201 + resourceId ★  |
+| T-010-2 | [CHECK] resourceId 存入共享 state           | let resourceId 有值      |
+
+## 執行順序依賴圖
+
+T-000 → T-001 → T-010
+```
+
+## E2E 骨架格式（.journey.spec.ts）
+
+生成的骨架展示三個核心模式：`describe.skipIf` 環境保護、共享 `let` 狀態、T-NNN 識別碼對應。
+
+```typescript
+import { describe, it, expect } from "vitest"
+
+// Journey E2E：需要真實後端，不設定 JOURNEY_BASE_URL 則全部 skip
+const BASE_URL = process.env.JOURNEY_BASE_URL || ""
+
+describe.skipIf(!BASE_URL)("Platform Admin Journey — T-001 → T-010", () => {
+  // 共享 state：每個步驟從前一步驟的結果取值
+  let authToken: string
+  let resourceId: string
+
+  it("T-001: Platform Admin 登入並取得 authToken", async () => {
+    const res = await fetch(`${BASE_URL}/api/auth/login`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        email: process.env.ADMIN_EMAIL,
+        password: process.env.ADMIN_PASSWORD,
+      }),
+    })
+    expect(res.status, "T-001 failed: login should return 200").toBe(200)
+    const data = await res.json()
+    expect(data.token, "T-001 failed: token should be present").toBeTruthy()
+    authToken = data.token  // ← 傳遞給後續步驟
+  })
+
+  it("T-010: 執行主要操作（depends on T-001）", async () => {
+    // 如果 T-001 失敗，authToken 為 undefined，此步驟的錯誤訊息會清楚說明
+    expect(authToken, "T-010 precondition failed: authToken from T-001 is missing").toBeTruthy()
+
+    const res = await fetch(`${BASE_URL}/api/resources`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${authToken}`,
+      },
+      body: JSON.stringify({ name: "journey-test-resource" }),
+    })
+    expect(res.status, `T-010 failed: expected 201, got ${res.status}`).toBe(201)
+    const data = await res.json()
+    resourceId = data.id  // ← 傳遞給後續步驟
+  })
+})
+```
+
+## 後續步驟
+
+完成後建議：
+
+> **TESTPLAN 與 Journey E2E 骨架已生成。建議下一步：**
+> - 執行 `/e2e` 生成各功能的 AC 層測試（補充旅程測試的細節覆蓋）
+> - 執行 `/atdd` 定義各 T-NNN 步驟對應的驗收條件
+> - 執行 `/journey-test --analyze` 定期檢查自動化覆蓋缺口
+
+## 參考
+
+- 標準：[user-journey-testing.ai.yaml](../../.standards/user-journey-testing.ai.yaml)
+- 相關 XSPEC：XSPEC-128（UDS 標準定義）、XSPEC-129（VibeOps 實作範例）
+- 相關 Skill：`/e2e`（AC 層測試）、`/atdd`（驗收條件定義）