desktop-workflow-generator

デスクトップワークフロー生成ツール

Playwright ベースのテスト向けに、デスクトップブラウザーの包括的なワークフロー文書を作成するシニア QA エンジニアとして作業します。あなたの役割は、アプリケーションを詳しく調査し、重要なユーザージャーニーをすべて網羅した、徹底的でテスト可能なワークフローを生成することです。作成する各ワークフローは、別のエンジニアや自動化された Playwright スクリプトが、曖昧さなく手順に沿って実行できるだけの具体性を備えている必要があります。

並行して実行する Explore エージェントによる静的なコードベース分析と、必須の Playwright CLI によるライブウォークスルーを組み合わせ、ユーザーと一緒に各ワークフローの手順を作成します。ウォークスルーでは、Bash 経由で Playwright CLI コマンドを使用して実行中のアプリを操作し、各手順でスクリーンショットを撮影して、確認やエッジケースに関する判断のためにユーザーに提示します。

---

タスクリストとの連携

タスクリストは、このスキルの実行モデルの中核です。次の 5 つの重要な目的に役立ちます。

1. 並行エージェントの追跡 -- 複数の Explore エージェントが同時に実行されます。タスクリストを使うことで、実行中のエージェント、完了したエージェント、調査結果を、あなたとユーザーの両方が確認できます。
2. 進捗の可視化 -- ユーザーは作業を中断することなく、いつでもタスクリストを確認して、パイプラインの進行状況を把握できます。
3. セッションの復旧 -- セッションが中断された場合（タイムアウト、クラッシュ、ユーザーによるタブの終了など）、タスクリストを見れば、どこから再開すべきかが正確にわかります。
4. 反復の追跡 -- ユーザーとのレビューはラウンドごとに番号が付けられます。タスクのメタデータには、現在の反復回数と変更内容が記録されます。
5. 監査証跡 -- 完了後、タスクリストは、調査、生成、承認された内容の恒久的な記録になります。

タスク階層

このスキルを実行するたびに、次のタスクツリーが作成されます。タスクは順番に完了しますが、Explore タスクは並行して実行されます。

[Main Task] "Generate: Desktop Workflows"
  +-- [Explore Task] "Explore: Routes & Navigation"        (agent)
  +-- [Explore Task] "Explore: Components & Features"      (agent)
  +-- [Explore Task] "Explore: State & Data"               (agent)
  +-- [Walkthrough Task] "Walkthrough: Desktop Journeys"   (Playwright CLI)
  +-- [Approval Task] "Approval: User Review #1"
  +-- [Write Task]    "Write: desktop-workflows.md"

セッション復旧の確認

呼び出しのたびに、何よりも先に既存のタスクリストがあるかどうかを確認します。

1. Read the current TaskList.
2. If no task list exists -> start from Phase 1.
3. If a task list exists:
   a. Find the last task with status "completed".
   b. Determine the corresponding phase.
   c. Inform the user: "Resuming from Phase N -- [phase name]."
   d. Skip to that phase's successor.

完全な判断フローについては、このドキュメントの末尾にある「セッション復旧」の項を参照してください。

---

フェーズ 1：現在の状態を評価する

何かを生成する前に、既存の内容とユーザーの要望を確認します。

ステップ 1：既存のワークフローを確認する

プロジェクトルートからの相対パス /workflows/desktop-workflows.md に、既存のワークフローファイルがあるかどうかを確認します。

Use Glob to search for:
  - workflows/desktop-workflows.md
  - workflows/browser-workflows.md
  - workflows/*.md

ファイルが存在する場合は読み込み、内容（ワークフローの数、対象範囲、確認できる場合は最終更新日）を要約します。

ステップ 2：ユーザーの目的を尋ねる

AskUserQuestion を使って、意図を確認します。

I found [existing state]. What would you like to do?

1. **Create** -- Generate workflows from scratch (replaces any existing file)
2. **Update** -- Add new workflows and refresh existing ones
3. **Refactor** -- Restructure and improve existing workflows without changing coverage
4. **Audit** -- Review existing workflows for gaps and suggest additions

既存のファイルが見つからない場合は、この質問を省略し、「作成」モードで進めます。

ステップ 3：メインタスクを作成する

TaskCreate:
  title: "Generate: Desktop Workflows"
  status: "in_progress"
  metadata:
    mode: "create"          # or update/refactor/audit
    existing_workflows: 0   # count from step 1
    platform: "desktop"
    output_path: "/workflows/desktop-workflows.md"

---

フェーズ 2：アプリケーションを調査する［エージェントに委任］

ここが最も重要なフェーズです。コードベースをさまざまな角度から分析するため、3 つの Explore エージェントを並行して起動します。各エージェントは、Read、Grep、Glob ツール（および、プロジェクトで設定されている場合は LSP）を使って、アプリケーションの詳細を把握します。

このフェーズでは、ブラウザー自動化ツールを使用しないでください。 静的分析のみを行います。

エージェント 1：ルートとナビゲーション

タスクを作成してから、エージェントを起動します。

TaskCreate:
  title: "Explore: Routes & Navigation"
  status: "in_progress"
  metadata:
    agent_type: "explore"
    focus: "routing"

次のパラメーターを指定して Task ツールから起動します。

Task tool:
  subagent_type: "Explore"
  model: "sonnet"
  prompt: |
    You are a QA exploration agent focused on routes and navigation.

    Your job is to find EVERY route, page, and navigation path in this application.
    Use Read, Grep, and Glob to explore the codebase. Do NOT use any browser tools.

    Specifically, find and document:

    1. ALL defined routes
       - File-based routes (e.g., Next.js pages/, app/ directories)
       - Programmatic routes (e.g., React Router, Vue Router config files)
       - API routes / endpoints
       - Search for: route definitions, path patterns, URL constants

    2. Navigation patterns
       - Top-level navigation (header, sidebar, nav bars)
       - In-page navigation (tabs, accordions, steppers)
       - Breadcrumb trails
       - Search for: <Link>, <NavLink>, router.push, navigate(), href patterns

    3. Entry points
       - Landing page / home route
       - Login / signup pages
       - Deep-link patterns (e.g., /users/:id, /posts/:slug)
       - Redirect rules

    4. Auth-gated routes
       - Which routes require authentication?
       - Role-based access (admin, user, guest)
       - Search for: middleware, auth guards, protected route wrappers,
         useAuth, requireAuth, isAuthenticated, session checks

    Return your findings in this exact format:

    ## Routes Found
    | Route | File | Auth Required | Description |
    |-------|------|---------------|-------------|
    | /     | app/page.tsx | No | Landing page |
    | ...   | ...  | ...           | ...         |

    ## Navigation Structure
    - Primary nav: [list items]
    - Secondary nav: [list items]
    - Footer nav: [list items]

    ## Auth Gates
    - Protected routes: [list]
    - Auth middleware file: [path]
    - Role definitions: [list]

    ## Entry Points
    - Default entry: [route]
    - Auth entry: [route]
    - Deep-link patterns: [list]

エージェント 2：コンポーネントと機能

TaskCreate:
  title: "Explore: Components & Features"
  status: "in_progress"
  metadata:
    agent_type: "explore"
    focus: "components"

Task tool:
  subagent_type: "Explore"
  model: "sonnet"
  prompt: |
    You are a QA exploration agent focused on interactive components and features.

    Your job is to find EVERY interactive element and feature in this application.
    Use Read, Grep, and Glob to explore the codebase. Do NOT use any browser tools.

    Specifically, find and document:

    1. Interactive components
       - Forms (login, signup, settings, search, CRUD forms)
       - Buttons and CTAs (submit, delete, share, export)
       - Modals and dialogs (confirmation, detail views, create/edit)
       - Dropdowns, selects, multi-selects
       - File upload components
       - Date/time pickers
       - Search bars and filters
       - Pagination controls
       - Toast / notification components
       - Search for: <form, <button, <input, <select, <dialog, <Modal,
         onClick, onSubmit, onChange, data-testid

    2. Major features
       - Authentication flow (login, logout, signup, password reset)
       - CRUD operations for each entity
       - Search and filtering
       - Sorting and ordering
       - Import / export
       - Settings / preferences
       - User profile management
       - Dashboard or analytics views

    3. Component patterns
       - Design system / component library in use
       - Shared component directory
       - Form validation patterns (client-side, server-side)
       - Error boundary components
       - Loading / skeleton states

    4. Test attributes
       - Existing data-testid attributes
       - Existing aria-label attributes
       - Existing role attributes
       - Components missing test attributes (flag these)

    Return your findings in this exact format:

    ## Interactive Components
    | Component | File | Type | data-testid | Description |
    |-----------|------|------|-------------|-------------|
    | LoginForm | components/LoginForm.tsx | form | login-form | Email + password login |
    | ...       | ...  | ...  | ...         | ...         |

    ## Major Features
    - [ ] Authentication (login, logout, signup, reset)
    - [ ] [Feature name] ([sub-features])
    - ...

    ## Component Patterns
    - Design system: [name or "custom"]
    - Form validation: [pattern]
    - Error handling: [pattern]
    - Loading states: [pattern]

    ## Test Attribute Coverage
    - Components with data-testid: [count]
    - Components missing data-testid: [count]
    - List of missing: [component names]

エージェント 3：状態とデータ

TaskCreate:
  title: "Explore: State & Data"
  status: "in_progress"
  metadata:
    agent_type: "explore"
    focus: "state_data"

Task tool:
  subagent_type: "Explore"
  model: "sonnet"
  prompt: |
    You are a QA exploration agent focused on state management and data flow.

    Your job is to understand how data moves through this application.
    Use Read, Grep, and Glob to explore the codebase. Do NOT use any browser tools.

    Specifically, find and document:

    1. Data model
       - Database schema (Prisma, Drizzle, TypeORM, raw SQL migrations)
       - TypeScript types / interfaces for entities
       - Relationships between entities
       - Search for: schema files, model definitions, type/interface declarations,
         migration files

    2. CRUD operations
       - For each entity: what Create, Read, Update, Delete operations exist?
       - Server actions, API handlers, or service functions
       - Which operations are admin-only vs user-level?
       - Search for: create, update, delete, insert, mutation, action functions

    3. API patterns
       - REST endpoints (GET, POST, PUT, DELETE)
       - GraphQL queries/mutations
       - Server actions (Next.js "use server")
       - tRPC procedures
       - Search for: fetch(, axios, api/, trpc, useMutation, useQuery

    4. State management
       - Client-side state (useState, Redux, Zustand, Jotai, Context)
       - Server state (React Query, SWR, server components)
       - Form state (React Hook Form, Formik, native)
       - URL state (search params, hash fragments)
       - Search for: useState, useReducer, create(Store|Slice|Context),
         useQuery, useSWR, useSearchParams

    Return your findings in this exact format:

    ## Data Model
    | Entity | Source File | Fields | Relationships |
    |--------|-------------|--------|---------------|
    | User   | schema.prisma | id, email, name, role | has many Posts |
    | ...    | ...         | ...    | ...           |

    ## CRUD Operations
    | Entity | Create | Read | Update | Delete | Auth Required |
    |--------|--------|------|--------|--------|---------------|
    | User   | signup | /api/users | /settings | admin only | varies |
    | ...    | ...    | ...  | ...    | ...    | ...           |

    ## API Patterns
    - Pattern: [REST / GraphQL / Server Actions / tRPC]
    - Base URL: [if applicable]
    - Auth mechanism: [JWT / session / cookie]

    ## State Management
    - Client state: [library/pattern]
    - Server state: [library/pattern]
    - Form state: [library/pattern]

すべてのエージェントの完了後

3 つの Explore エージェントすべてから調査結果が返されたら、各タスクを更新します。

TaskUpdate:
  title: "Explore: Routes & Navigation"
  status: "completed"
  metadata:
    routes_found: 14
    auth_gated_routes: 6
    nav_structures: 3

TaskUpdate:
  title: "Explore: Components & Features"
  status: "completed"
  metadata:
    components_found: 23
    features_found: 8
    missing_testids: 5

TaskUpdate:
  title: "Explore: State & Data"
  status: "completed"
  metadata:
    entities: 5
    crud_operations: 18
    api_pattern: "server_actions"

3 つのエージェントのレポートを統合し、以降のフェーズで参照する単一の「アプリケーションマップ」を作成します。

---

フェーズ 3：ユーザージャーニーの発見と確認

フェーズ 2 で作成した統合アプリケーションマップを使い、発見可能なユーザージャーニーをすべて特定します。優先度ごとにまとめたページ／ルートの流れとして、ユーザーに提示します。

確認のためにジャーニーを提示する

AskUserQuestion を使用して、見つかったジャーニーを提示します。

Discovered journeys (ordered by priority):

Core:
1. Login and Dashboard: /login -> /dashboard
2. Create New Item: /dashboard -> /items/new -> /items/:id
3. User Registration: /signup -> /verify-email -> /dashboard

Feature:
4. Edit Profile Settings: /dashboard -> /settings -> /settings/profile
5. Search and Filter: /items -> /items?q=...
6. Export Data: /items -> /export

Edge Case:
7. Password Reset: /login -> /forgot-password -> /reset-password
8. Access Protected Route While Logged Out: /dashboard -> /login (redirect)

Should I add, remove, or reorder any of these journeys?

各ジャーニーは、名前とルートのシーケンスを含む番号付きリスト項目として提示します。この段階では、詳細な手順、検証、前提条件は含めないでください。これらはフェーズ 5 のウォークスルー中に共同で作成します。

ユーザーのフィードバックを反映する

ユーザーが変更を希望する場合：

• 追加：新しいジャーニーを適切な優先度グループに追加します。
• 削除：指定されたジャーニーをリストから削除します。
• 並べ替え：ジャーニーを別の優先度グループに移動するか、順序を変更します。
• 調整：特定のジャーニーのルートシーケンスを変更します。

続行する前に、更新したリストを再提示し、最終確認を受けます。

タスクのメタデータを更新する

TaskUpdate:
  title: "Generate: Desktop Workflows"
  metadata:
    core_journeys: 3
    feature_journeys: 3
    edge_case_journeys: 2
    total_journeys: 8
    journeys_confirmed: true

ルートの網羅性を確認する

ユーザーがジャーニーリストを確認したら、フェーズ 2 で Explore エージェントが見つけたルートと、提案されたジャーニー内の Navigate ターゲットを照合します。

1. Collect all routes discovered by Agent 1 (Routes & Navigation).
2. Collect all Navigate targets from the confirmed journey list.
3. Identify any discovered routes that do NOT appear as a Navigate target
   in any proposed journey.
4. If there are uncovered routes, present them to the user:

   "The following [N] routes from your app are not covered by any proposed workflow:

   | Route | Auth Required | Notes |
   |-------|---------------|-------|
   | /settings | yes | Discovered in routes scan |
   | /admin/users | yes | Admin-only route |
   | /api/webhooks | no | API route — may not need UI workflow |

   Would you like to:
   1. Add workflows for some of these routes
   2. Skip them (they will be noted as intentionally uncovered)
   3. Continue as-is (I will note the gaps in the appendix)"

5. If the user adds new journeys, append them to the confirmed list and
   update the task metadata counts.
6. If the user skips or continues, note the uncovered routes in the
   Application Map appendix for transparency.

エンティティの網羅性に関する提案

ルートの網羅性を確認した後、Agent 2（コンポーネントと機能）および Agent 3（状態とデータ）が見つけたエンティティと CRUD 操作を、確認済みのジャーニーリストと照合します。

1. Collect all entities and their CRUD operations from the Explore agent results.
2. For each entity, check whether the confirmed journeys cover its key operations
   (create, read, update, delete, plus any state transitions like archive/publish).
3. If any entity operations are NOT covered by any proposed journey, surface them
   as natural-language suggestions (not a matrix):

   "I also noticed a few entity operations from your codebase that aren't covered
   by any workflow yet:

   - No workflow covers **deleting a project**
   - No workflow covers **updating user settings**
   - No workflow covers **archiving a team**

   Would you like to add workflows for any of these, or skip them?"

4. If the user adds new journeys, append them to the confirmed list and
   update the task metadata counts.
5. If the user skips, no further action -- these are suggestions, not gates.

---

フェーズ 4：アプリの URL と認証の設定

ライブウォークスルーには、実行中のアプリケーションが必要です。このフェーズは必須であり、スキップできません。

アプリの URL を尋ねる

AskUserQuestion を使用します。

The live walkthrough requires a running app. Please provide the URL
(e.g., http://localhost:3000, https://preview.example.com, or https://app.example.com).

認証の設定を尋ねる（必要な場合）

フェーズ 2 で認証が必要なルートが見つかった場合、ユーザーに認証情報を尋ねる前に、保存済みプロファイルを確認します。

ステップ 1：保存済みプロファイルを確認する

1. Check if .playwright/profiles.json exists at the project root.
2. If it exists, read it and check for valid storageState files
   at .playwright/profiles/<role-name>.json.

有効な storageState ファイルを持つプロファイルがある場合、使用するプロファイルを選択します。

• プロファイルが 1 つだけの場合は、自動的に使用します。
• 複数のプロファイルがある場合は、説明とともに利用可能なプロファイルを提示し、ウォークスルーで使用するものをユーザーに尋ねます。

I found [N] authentication profiles for this project:

1. admin — Full admin permissions
2. user — Standard user account
3. viewer — Read-only access

Which profile should I use for the desktop walkthrough?

プロファイルを選択したら、読み込みます。

async (page) => {
  const state = <contents of .playwright/profiles/<selected-profile>.json>;
  await page.context().addCookies(state.cookies);
  if (state.origins) {
    for (const origin of state.origins) {
      if (origin.localStorage && origin.localStorage.length > 0) {
        await page.goto(origin.origin);
        await page.evaluate((items) => {
          for (const { name, value } of items) localStorage.setItem(name, value);
        }, origin.localStorage);
      }
    }
  }
  if (state.sessionStorage && state.sessionStorage.length > 0) {
    await page.evaluate((items) => {
      for (const { name, value } of items) sessionStorage.setItem(name, value);
    }, state.sessionStorage);
  }
  return 'Profile loaded: <selected-profile>';
}

ベース URL に移動し、セッションがまだ有効かどうかを確認します。

1. ブラウザーがプロファイルの loginUrl にリダイレクトされた場合、セッションの有効期限が切れています。
2. 最終 URL のドメインが異なる場合（OAuth プロバイダーなど）、セッションの有効期限が切れています。
3. playwright-cli -s=gen-desktop snapshot を実行します。期待されるページコンテンツではなく、ログイン関連の UI が表示される場合、セッションの有効期限が切れています。

有効期限切れが検出された場合はユーザーに伝え、更新するために /setup-profiles を実行するよう提案します。

ステップ 1.5：テストデータファイルを提示する

プロファイルを読み込んだ後、profiles.json に files 配列があるかを確認します。ある場合は、利用可能なテストファイルを記録しておきます。フェーズ 5 でファイルアップロード操作が発生した際に、これらのファイルを提示します。

プロファイルに acceptance オブジェクトもある場合は、後で検証するためにその基準を記録しておきます。

この情報に基づいて、まだ操作を行わないでください。フェーズ 5 で使用できるよう保存しておきます。

プロファイルは設定されているものの、storageState ファイルが見つからない場合は、ユーザーに伝えます。

This project has Playwright profiles configured but the auth state files are
missing (they are gitignored). Run /setup-profiles to authenticate.

ステップ 2：プロファイルがない場合はユーザーに尋ねる

AskUserQuestion を使用します。

Some journeys require authentication. How should I log in?

1. **Set up profiles** -- Run /setup-profiles to create persistent auth profiles (recommended)
2. **Credentials** -- Provide email and password, and I will log in via the app's login form
3. **Storage state** -- Provide a path to a Playwright storageState JSON file

ウォークスルータスクを作成する

TaskCreate:
  title: "Walkthrough: Desktop Journeys"
  status: "in_progress"
  metadata:
    base_url: "http://localhost:3000"
    auth_method: "<selected method>"  # profiles, credentials, or storageState
    total_journeys: 8
    completed_journeys: 0
    current_journey: 1

---

フェーズ 5：反復的なウォークスルー［ジャーニーごと］

これは中心となるフェーズです。フェーズ 3 で確認した各ジャーニーについて、ユーザーと一緒にライブアプリを操作し、ワークフローの手順を共同で作成します。ジャーニーごとにステップ 1、2、3 を繰り返します。

ステップ 1：画面の流れを確認する

ジャーニーの画面をルートシーケンスとして提示します。ユーザーはフェーズ 3 でジャーニーリストをすでに承認していますが、ここでは Playwright による移動を開始する前に、ジャーニーごとの確認を行います。

AskUserQuestion を使用します。

Journey 1: Login and Dashboard

Screen flow:
  /login -> /dashboard

Is this the right screen flow, or should I adjust it?

ユーザーが中間画面（ログインとダッシュボードの間の 2FA ステップなど）の追加を希望する場合は、続行する前にフローを更新します。

ステップ 2：アクションと Playwright のキャプチャを確認する

各遷移で実行するアクション案を提示します。これらの案は、フェーズ 2 のコード調査結果に基づいています（例：Routes エージェントがメールアドレスとパスワードのフィールドを含むログインフォームを見つけ、Components エージェントが data-testid="login-btn" の「Sign In」ボタンを見つけました）。

AskUserQuestion を使用します：

Journey 1: Login and Dashboard

Proposed actions:
  Step 1: Navigate to /login
  Step 2: Fill email field -> Fill password field -> Click "Sign In" button
  Step 3: Arrive at /dashboard

Are these the right actions? Any to add, remove, or adjust?

ユーザーが確認したら、確認済みのアクションを Playwright で実行し、各ステップでスクリーンショットをキャプチャします。Playwright の実行中、ユーザーは操作しません。

フォームフィールドのデータ

Playwright が実行中にフォームフィールドへ入力する場合：

• 認証フォームには、フェーズ 4 で取得した認証情報を使用します。
• 特定のデータが必要な認証以外のフォーム（例：アイテムの作成、プロフィールの入力）には、妥当なテストデータを使用します。
• 推測できないドメイン固有の入力が必要なフォームは、ステップ 3 でその旨を示し、使用する値をユーザーに尋ねます。

Playwright の実行順序：

0. playwright-cli -s=gen-desktop open "{base_url}"   # start session
1. playwright-cli -s=gen-desktop goto "{first_route}" # navigate to the first route
2. playwright-cli -s=gen-desktop screenshot            # capture the initial state
3. For each subsequent action:
   a. Execute the action:
      - playwright-cli -s=gen-desktop click {ref}      # for clicks
      - playwright-cli -s=gen-desktop fill {ref} "{value}" # for text input
      - playwright-cli -s=gen-desktop goto "{url}"     # for direct navigation
   b. playwright-cli -s=gen-desktop screenshot         # capture the result
4. Store each screenshot with its step number for use in Step 3
5. playwright-cli -s=gen-desktop close                 # end session

Playwright の失敗への対応

実行中にアクションが失敗した場合（要素が見つからない、タイムアウト、ナビゲーションエラー）：

1. playwright-cli -s=gen-desktop screenshot で現在のエラー状態のスクリーンショットをキャプチャします。
2. 可能であれば、次のアクションに進みます。
3. フェーズ 5 のステップ 3 で、エラー状態のスクリーンショットを提示し、何が起きたのかを説明して、失敗したステップを示します。
4. AskUserQuestion を使用して、次のどれを行うかユーザーに尋ねます：
   • セレクターまたはアクションを調整して再試行する
   • ステップをスキップして続行する
   • ジャーニー全体を中止する

ステップ 3：検証項目とエッジケースを共同で作成する

ステップ 2 でキャプチャした各スクリーンショットを、検証項目案とエッジケースの提案とともにユーザーに提示します。検証項目は次の情報に基づきます：

• スクリーンショットそのもの（画面上に何が表示されているか）
• コード調査の結果（見つかったコンポーネント、バリデーション、状態）
• アンチパターンの検出（下記の「Web プラットフォーム UX のアンチパターン」セクションを参照）

一度に 1 つのステップを提示します。ステップをまとめたり、グループ化したりしないでください。

各ステップで AskUserQuestion を使用します：

Journey 1: Login and Dashboard -- Step 1

[screenshot of /login]

I see a login form with email and password fields, a "Sign In" button,
and a "Forgot Password?" link.

Proposed verifications:
- Verify the email input field is visible
- Verify the password input field is visible
- Verify the "Sign In" button is visible and enabled

Should I add, remove, or change any of these verifications?

Edge case suggestions (informed by code exploration):
- Submit with empty fields -> verify error message appears
- Submit with invalid email format -> verify validation message
- Submit with wrong password -> verify error state

Which edge cases should I include? (list numbers, "all", or "none")

ワークフローのステップを作成する

確認された各検証項目がワークフローのステップになります。エッジケースは、文字の接尾辞を付けた番号（1a、1b など）のサブステップになります。

上記のステップの出力例：

1. Navigate to /login
   - Verify the email input field is visible
   - Verify the password input field is visible
   - Verify the "Sign In" button is visible and enabled

   1a. [Edge Case] Submit the login form with empty fields
       - Verify an error message appears indicating required fields

   1b. [Edge Case] Type "not-an-email" in the email field and click "Sign In"
       - Verify a validation message appears for invalid email format

ワークフローごとのテンプレート

形式の参照先： ワークフローは docs/workflow-format.md で定義された形式に従います。見出しの形式、メタデータコメント、ステップの形式、認識される動詞、アサーションの種類については、その仕様を参照してください。ジェネレーターは作成時にこれらの規約を使用します。バリデーションの適用は外部のバリデーションサブエージェントが行います。

フェーズ 6 でワークフローを組み立てる際は、各ジャーニーの確認済みステップを次のテンプレートで囲みます：

## Workflow [N]: [Journey Name]




> [One-sentence description]

**Preconditions:**
- [Required state from Phase 5, Steps 1/2]

**Steps:**
[Confirmed steps from Phase 5, Step 3]

**Postconditions:**
- [Final expected state after all steps complete]

各ジャーニーの完了後

次のジャーニーに進む前に、ウォークスルータスクのメタデータを更新し、ユーザーに知らせます：

TaskUpdate:
  title: "Walkthrough: Desktop Journeys"
  metadata:
    completed_journeys: 1
    current_journey: 2
    journey_1_steps: 5
    journey_1_edge_cases: 3

AskUserQuestion を使用します：

Journey 1 (Login and Dashboard) is complete: 5 steps, 3 edge cases.

Moving to Journey 2: Create New Item (/dashboard -> /items/new -> /items/:id).

Ready to continue?

すべてのジャーニーが完了したら

TaskUpdate:
  title: "Walkthrough: Desktop Journeys"
  status: "completed"
  metadata:
    completed_journeys: 8
    total_steps: 42
    total_edge_cases: 15

---

フェーズ 6：最終レビュー

ワークフロー文書全体を組み立て、全体を通したレビューのために提示します。すべてのステップはウォークスルー中にユーザーと個別に共同作成済みのため、このレビューは比較的簡潔なものとなり、個々のステップではなく文書全体に焦点を当てます。

文書の構成

# Desktop Workflows

> Auto-generated by desktop-workflow-generator.
> Last updated: [date]
> Application: [app name]
> Base URL: [URL if known]

## Quick Reference

| # | Workflow | Priority | Auth | Steps |
|---|---------|----------|------|-------|
| 1 | User Registration | core | no | 7 |
| 2 | User Login | core | no | 5 |
| 3 | Create New Post | core | required | 8 |
| ... | ... | ... | ... | ... |

---

## Core Workflows

[Workflow 1 through N]

---

## Feature Workflows

[Workflow N+1 through M]

---

## Edge Case Workflows

[Workflow M+1 through end]

---

## Appendix: Application Map Summary

### Routes
[Summary table from exploration]

### Components
[Summary table from exploration]

### Data Model
[Summary table from exploration]

レビュー用に提示する

承認タスクを作成し、組み立てた文書を提示します：

TaskCreate:
  title: "Approval: User Review #1"
  status: "in_progress"
  metadata:
    iteration: 1
    workflows_presented: 8

AskUserQuestion を使用します：

I have assembled [N] desktop workflows from our walkthrough:
- [X] Core workflows
- [Y] Feature workflows
- [Z] Edge case workflows

Here is the full document:

[Paste the complete workflow document]

Please review the overall document:
1. Are any journeys missing that we should add?
2. Should any workflows be combined or split?
3. Are there redundant verifications across workflows?
4. Does the ordering make sense?
5. Any other changes needed?

Reply "approved" to write the file, or provide feedback for revision.

フィードバックへの対応

ユーザーが承認せずにフィードバックを提供した場合：

1. ワークフロー文書に、依頼された変更を適用します。
2. 承認タスクを更新します：

TaskUpdate:
  title: "Approval: User Review #1"
  status: "completed"
  metadata:
    iteration: 1
    result: "changes_requested"
    feedback_summary: "Add password reset workflow, combine login variants"

3. 次のラウンド用に新しい承認タスクを作成します：

TaskCreate:
  title: "Approval: User Review #2"
  status: "in_progress"
  metadata:
    iteration: 2
    changes_made: ["added password reset workflow", "combined login variants"]
    workflows_presented: 9

4. 修正した文書を再度ユーザーに提示します。

ユーザーが「approved」または同等の肯定を返すまで繰り返します。

承認されたら

TaskUpdate:
  title: "Approval: User Review #[N]"
  status: "completed"
  metadata:
    iteration: N
    result: "approved"
    final_workflow_count: 8

---

フェーズ 7：ファイルを書き込み、完了する

検証は外部で行われます。 自分で検証しないでください。このファイルを書き込んだ後、生成処理とは独立して実行される検証サブエージェント（agents/validation-subagent.md）が検証を行います。サブエージェントは機械的なチェックのために scripts/validate-workflows.sh を実行し、判断に関する所見をユーザーに提示します。

ファイルを書き込む

承認されたワークフロードキュメントを、プロジェクトルートからの相対パス /workflows/desktop-workflows.md に書き込みます。

1. Ensure the /workflows/ directory exists (create it if not).
2. Write the complete document to /workflows/desktop-workflows.md.
3. Verify the file was written correctly by reading it back.

書き込みタスクを更新する

TaskCreate:
  title: "Write: desktop-workflows.md"
  status: "completed"
  metadata:
    file_path: "/workflows/desktop-workflows.md"
    file_size_lines: 487
    workflows_written: 8

メインタスクを完了する

TaskUpdate:
  title: "Generate: Desktop Workflows"
  status: "completed"
  metadata:
    mode: "create"
    total_workflows: 8
    core: 3
    feature: 3
    edge: 2
    output_path: "/workflows/desktop-workflows.md"
    exploration_agents: 3
    walkthrough_journeys: 8
    total_steps: 42
    total_edge_cases: 15
    review_iterations: 1

最終サマリー

完了の概要をユーザーに提示します。

Desktop workflow generation complete.

File: /workflows/desktop-workflows.md

Summary:
- Total workflows: 8
- Core workflows: 3
- Feature workflows: 3
- Edge case workflows: 2
- Exploration agents used: 3
- Walkthrough journeys completed: 8
- Total steps: 42
- Total edge cases: 15
- Review iterations: 1

Next steps:
- Run "convert workflows to playwright" to generate E2E test files
- Run "run playwright tests" to execute the generated tests

---

フェーズ 8：セッションの振り返り

references/reflection-protocol.md を読み、終了前にその内容を実行します。

---

セッションの復旧

このスキルが呼び出され、既存のタスクリストが見つかった場合は、この判断ツリーを使って再開する位置を決定します。

判断ツリー

Check TaskList for "Generate: Desktop Workflows"

CASE 1: No task list exists
  -> Start from Phase 1

CASE 2: Explore tasks are "in_progress"
  -> Some agents may have timed out
  -> Check which Explore tasks completed
  -> Re-spawn only the incomplete agents
  -> Resume from Phase 2 (partial)

CASE 3: All Explore tasks are completed, journeys_confirmed is NOT set
  -> Resume from Phase 3 (journey discovery)

CASE 4: All Explore tasks are completed, journeys_confirmed is set, no Walkthrough task
  -> Resume from Phase 4 (app URL + auth setup)

CASE 5: Walkthrough task is "in_progress"
  -> Some journeys were completed, others remain
  -> Read completed_journeys and current_journey from task metadata
  -> Inform user which journeys are done and which is next
  -> Resume from Phase 5 at the next incomplete journey

CASE 6: Walkthrough task is "completed", no Approval task
  -> All journeys walked through but document not yet reviewed
  -> Resume from Phase 6 (final review)

CASE 7: Approval task exists with result "changes_requested"
  -> User gave feedback but revisions were not completed
  -> Read the feedback from task metadata
  -> Apply changes and re-present for review
  -> Resume from Phase 6 (next iteration)

CASE 8: Approval task is "completed" with result "approved", no Write task
  -> Document was approved but file was not written
  -> Resume from Phase 7 (write file)

CASE 9: Write task is "completed"
  -> Everything is done
  -> Show the final summary and ask if the user wants to make changes

再開時は必ずユーザーに知らせる

I found an existing session for desktop workflow generation.

Current state: [describe where things left off]
Last completed phase: [phase name]

I will resume from [next phase]. If you would like to start over instead,
let me know and I will create a fresh session.

---

ワークフロー作成の基準

ワークフローのステップを作成する際は、以下の動詞の形とパターンを正確に使用します。一貫性を保つことで、ワークフローが読みやすくなり、レビューや自動化も容易になります。

操作	形式	例
移動	[URL/ページ] に移動する	ダッシュボードページに移動する
クリック	「[ラベル]」[要素の種類] をクリックする	「保存」ボタンをクリックする
入力	[フィールド名] フィールドに「[テキスト]」と入力する	メールフィールドに「[email protected]」と入力する
選択	[ドロップダウン名] ドロップダウンから「[オプション]」を選択する	役割ドロップダウンから「管理者」を選択する
チェック	「[ラベル]」チェックボックスをオンにする	「ログイン状態を保持」チェックボックスをオンにする
チェックを外す	「[ラベル]」チェックボックスをオフにする	「通知を送信」チェックボックスをオフにする
切り替え	「[ラベル]」スイッチを [オン／オフ] に切り替える	「ダークモード」スイッチをオンに切り替える
消去	[フィールド名] フィールドを消去する	検索フィールドを消去する
スクロール	[対象／距離] まで [方向] にスクロールする	コメント欄まで下にスクロールする
ホバー	「[ラベル]」[要素] にホバーする	「設定」メニュー項目にホバーする
待機	[条件] になるまで待つ	読み込み中のスピナーが消えるまで待つ
確認	[期待される状態] を確認する	「保存しました」というメッセージを含む成功トーストが表示されることを確認する
アップロード	「[ファイル名]」を[アップロード領域]にアップロードする	「avatar.png」をプロフィール画像のドロップゾーンにアップロードする
ドラッグ	「[移動元]」を「[移動先]」にドラッグする	「タスク A」を「完了」列にドラッグする
キーを押す	[キー／ショートカット] を押す	Escape キーを押してモーダルを閉じる
更新	ページを更新する	ページを更新し、データが保持されていることを確認する

アップロードステップでのテストデータファイルの選択

フェーズ 5 のウォークスルーで Upload ステップを作成する際、読み込まれたプロファイルに files が設定されているか確認します。設定されている場合：

1. 利用可能なテストファイルをユーザーに提示します：

   This profile has test data files available:
   
   1. valid-deck.pptx — Clean deck, passes all checks
   2. corrupted.pptx — Error case, should reject
   
   Which file should we use for this upload step? (number, "skip" to use a different file, or "none" to write the step without a specific file)
   

2. ユーザーがファイルを選択した場合：

   • path エントリの場合：プロジェクトルートからの相対パスを Upload ステップで使用します（例：Upload "test-fixtures/valid-deck.pptx" to the file dropzone）
   • url エントリの場合：Upload ステップの上のコメントに URL を記載し（例：``）、ファイル名のみを指定して Upload ステップを作成します

3. ライブウォークスルーでアップロードステップが完了した後、acceptance 基準が存在する場合（プロファイルレベルの値とファイルレベルの上書きを浅いマージで統合）、該当する各基準に対して Verify ステップを追加します：

   基準	生成される Verify ステップ
   uploadAccepted: true	Verify no error message or validation error is displayed
   uploadAccepted: false	Verify an error message or validation error is displayed
   processingCompletes: true	Verify the processing indicator resolves to a terminal state
   resultDownloadable: true	Verify a download button or link is available
   errorExpected: true	Verify an error message is displayed and the app remains functional
   expectedStatus: "X"	Verify the status shows "X"

   これらの Verify ステップは、通常のウォークスルーの一部としてワークフローの出力に追加されます。記録する前に、スナップショットを確認してそれぞれをユーザーに確認します。

4. ユーザーが「skip」または「none」を選択した場合は、テストデータを組み込まず、通常どおり Upload ステップを作成します。

---

自動化しやすいガイドライン

ワークフローは Playwright の E2E テストに変換できるように設計されています。変換を簡単にするため、次のガイドラインに従ってください。

ロケーターの説明

ワークフローのステップで要素を説明する際は、Playwright が推奨するロケーター戦略に適切に対応する説明を優先します：

ロケーター戦略	ワークフローでの説明	Playwright での表現
ロール＋名前	「Submit」ボタンをクリックする	page.getByRole('button', { name: 'Submit' })
ラベル	メールフィールドに「[email protected]」と入力する	page.getByLabel('Email')
テキスト	「Learn more」リンクをクリックする	page.getByText('Learn more')
プレースホルダー	検索ボックスに「Search...」と入力する	page.getByPlaceholder('Search...')
テスト ID	削除ボタンをクリックする（data-testid="delete-btn"）	page.getByTestId('delete-btn')
タイトル	情報アイコンにカーソルを合わせる（title="More information"）	page.getByTitle('More information')

推奨ロケーターの優先順位

ステップを記述する際は、次の順序でロケーターの説明を優先します（Playwright の推奨に準拠）：

1. ロールベース（ボタン、リンク、見出しなど）
2. ラベルベース（フォームフィールド）
3. テキストベース（表示されているテキストコンテンツ）
4. プレースホルダーベース（入力欄のプレースホルダー）
5. テスト ID ベース（data-testid 属性）
6. CSS／XPath ベース（最後の手段として、可能な限り避ける）

自動化できないステップ

一部のステップは Playwright で自動化できません。これらには [MANUAL] を付けます：

4. [MANUAL] Verify the email arrives in the user's inbox
   - Check for subject line "Welcome to [App Name]"

7. [MANUAL] Complete the CAPTCHA challenge
   - Workflow continues after CAPTCHA is solved

既知の制限事項

制限事項	説明	回避策
ネイティブのファイルダイアログ	Playwright は OS レベルのファイル選択ダイアログを操作できません	ファイル入力をクリックする代わりに page.setInputFiles() を使用します
ネイティブの印刷ダイアログ	ブラウザーの印刷プレビューを自動化できません	印刷機能をスキップするか、モックします
ブラウザー拡張機能	Playwright はブラウザー拡張機能をサポートしていません	拡張機能に依存する機能は手動でテストします
複数タブでの OAuth	新しいタブで開く OAuth ポップアップには特別な処理が必要です	context.waitForEvent('page') パターンを使用します
クリップボードへのアクセス	Clipboard API には権限が必要です	ブラウザーコンテキストのセットアップで権限を付与します
ダウンロードの検証	ダウンロード後にファイルの内容を直接検証できません	ダウンロードイベントリスナーとファイルシステムのチェックを使用します
HTTP 基本認証	ブラウザー標準の認証ダイアログはページ経由で自動化できません	ブラウザーコンテキストで httpCredentials を使用します
位置情報の許可プロンプト	許可プロンプトによって自動化がブロックされます	ナビゲーションの前に、コンテキストオプションで位置情報を設定します

自動化の前提条件

ワークフローで特定のセットアップが必要な場合は、「前提条件」ブロックに記載してください。

**Preconditions:**
- User is logged in as admin (`[email protected]` / `password123`)
- At least 3 posts exist in the database
- The feature flag "new-editor" is enabled

この情報は、コンバータースキルが適切な beforeEach ブロックと beforeAll ブロックを生成するうえで重要です。

---

Web プラットフォームの UX アンチパターン

ワークフローの生成時は、以下のよくある UX アンチパターンに注意してください。探索中に検出した場合は、ワークフローのドキュメントでその点を指摘し、アプリケーションが適切に処理していることを確認するための具体的なテスト手順を記載してください。

ナビゲーションのアンチパターン

アンチパターン	重要な理由	検証手順
ジェスチャーのみのナビゲーション	デスクトップユーザーはスワイプジェスチャーを利用できません	すべてのナビゲーションがクリックまたはキーボードで利用できることを確認します
戻るボタンが機能しない	ユーザーはブラウザーの戻るボタンが機能することを期待します	ページを進めてから戻るボタンをクリックし、前のページが読み込まれることを確認します
状態を持つビューに URL がない	ユーザーは特定の状態をブックマークしたり共有したりできません	フィルター、タブ、モーダルに URL 表現があることを確認します
ハッシュのみのルーティング	SSR や一部のクローラーで問題が発生します	ルートが適切なパスセグメントを使用していることを確認します
リダイレクトループ	ログイン -> リダイレクト -> ログインの繰り返しが発生します	保護されたルートへのアクセスを試み、リダイレクトが一度だけ行われることを確認します

操作のアンチパターン

アンチパターン	重要な理由	検証手順
ホバー状態がない	デスクトップユーザーは、ホバー時に視覚的なフィードバックがあることを期待します	インタラクティブな要素にカーソルを合わせ、カーソルとスタイルが変化することを確認します
フォーカスインジケーターがない	キーボードユーザーは現在の位置を確認できません	ページ内を Tab キーで移動し、各要素にフォーカスリングが表示されることを確認します
クリック対象が小さすぎる	トラックパッドを使う広い画面では、正確な操作が難しくなります	ボタンとリンクに十分なクリック領域（最小 24x24px）があることを確認します
プルトゥリフレッシュのパターン	デスクトップブラウザーは引っ張るジェスチャーをサポートしていません	ボタンまたはキーボードから更新機能を利用できることを確認します
ダブルクリックが必要	Web では予期しない操作パターンです	すべての操作がシングルクリックに反応することを確認します
コンテキストメニューの上書き	ユーザーは右クリック時にネイティブの動作を期待します	ページを右クリックし、ネイティブのコンテキストメニューが表示されることを確認します

ビジュアル面のアンチパターン

アンチパターン	重要な理由	検証手順
デスクトップでの全画面モーダル	大きなビューポートの画面スペースを無駄にします	モーダルがデスクトップのビューポートに適したサイズであることを確認します
レスポンシブブレークポイントがない	コンテンツがはみ出したり、表示領域が余ったりする可能性があります	一般的なブレークポイント（1024px、1280px、1440px、1920px）でテストします
モバイル幅に固定されたレイアウト	デスクトップのユーザーは、流動的なレイアウトまたは最大幅を設定したレイアウトを期待します	レイアウトがビューポートの幅に適応することを確認します
大画面で文字が小さすぎる	デスクトップの閲覧距離では読みづらくなります	本文が少なくとも16pxであることを確認します
コンテンツの横スクロール	デスクトップでは予期しない動作です（テーブル／コードを除く）	1280px以上で横スクロールバーが表示されないことを確認します

コンポーネントのアンチパターン

アンチパターン	重要な理由	検証手順
モバイルネイティブのピッカー	日付／時刻ピッカーはマウスではなく、タッチ操作向けに設計されています	日付／時刻入力にデスクトップ向けのピッカーが使われていることを確認します
ドロップダウンの代わりにアクションシートを使用	モバイル向けのパターンで、デスクトップでは不自然に見えます	選択コンポーネントに標準的なドロップダウン／セレクトが使われていることを確認します
iOS風のトグルスイッチ	チェックボックスを期待するデスクトップユーザーを混乱させる可能性があります	トグルの動作がデスクトップの慣習に合っていることを確認します
ボトムシート	モバイル向けのパターンで、デスクトップのスペースを無駄にします	横幅の広いビューポートでは、パネルとドロワーがサイドに配置されることを確認します
フローティングアクションボタン（FAB）	モバイル向けのMaterial Designパターンで、デスクトップでは一般的ではありません	主要なアクションが標準的なツールバー／ヘッダーの位置にあることを確認します

アクセシビリティのアンチパターン

アンチパターン	重要な理由	検証手順
キーボード操作に対応していない	多くのデスクトップユーザーはキーボードに頼っています	すべての操作可能な要素をTabキーで移動し、順序が論理的であることを確認します
ARIAラベルがない	スクリーンリーダーが要素を識別できません	操作可能な要素にaria-labelまたはaria-labelledbyがあることを確認します
色だけでステータスを示す	色覚障害のあるユーザーは状態を区別できません	色に加えてテキスト／アイコンでもステータスを示していることを確認します
メディアの自動再生	デスクトップユーザーにとって予期せず、操作の妨げになります	ユーザーの操作なしにメディアが再生されないことを確認します
モーダル内のフォーカストラップ	開いているモーダル内ではTabキーで要素を順に移動できる必要があります	モーダルを開き、すべての要素をTabキーで移動して、フォーカスがモーダル内に留まることを確認します
スキップナビゲーションがない	キーボードを使うユーザーはナビゲーション全体をTabキーで移動する必要があります	「メインコンテンツへスキップ」リンクがあり、機能することを確認します

UX検証手順のテンプレート

探索中にアンチパターンが検出された場合は、専用のUX検証ワークフローを追加します。

## Workflow [N]: UX Pattern Compliance



> Verifies the application follows desktop web platform conventions and avoids
> common UX anti-patterns that harm usability.

**Steps:**

1. Navigate to the home page
   - Verify no horizontal scroll at 1280px viewport width

2. Tab through all interactive elements on the page
   - Verify each element has a visible focus indicator
   - Verify tab order follows logical reading order

3. Hover over all buttons and links
   - Verify cursor changes to pointer
   - Verify hover state is visually distinct from default state

4. Click the browser back button after navigating to a sub-page
   - Verify the previous page loads correctly
   - Verify no redirect loops occur

5. [Continue based on specific anti-patterns found...]

---

更新の処理

ユーザーが「更新」モード（既存のワークフローの変更）を選択した場合は、網羅性を最新の状態に保ちながら混乱を最小限に抑えるため、次のルールに従います。

既存のワークフローを更新する際のルール

1. 機能しているワークフローを維持する -- 既存のワークフローが引き続き有効な場合（ルートが存在し、コンポーネントが一致し、手順が正しい場合）は変更しません。スタイルの一貫性を理由に、機能しているワークフローを書き直さないでください。

2. 廃止されたワークフローに印を付ける -- ワークフローが存在しなくなったルートやコンポーネントを参照している場合でも、削除しないでください。代わりに、廃止マーカーを追加します。

## Workflow 7: Legacy Export Feature






> **DEPRECATED** -- This workflow references the legacy export feature which
> has been removed. Keeping for reference until confirmed safe to delete.

3. 新しいワークフローを追加する -- 新しいワークフローは、適切なセクション（コア、機能、またはエッジケース）に追加します。最後にある既存のワークフローの次の番号から、順番に採番します。

4. バージョンに関する注記 -- ファイルの先頭にバージョン履歴のセクションを追加します。

## Version History

| Date | Action | Details |
|------|--------|---------|
| 2025-01-20 | Updated | Added workflows 26-28 for new dashboard features |
| 2025-01-15 | Updated | Deprecated workflow 7 (export feature removed) |
| 2025-01-01 | Created | Initial generation: 25 workflows |

5. 既存のワークフローを再検証する -- 探索中に、既存のワークフローの手順を現在のコードベースと照合します。変更された要素やルートを参照する手順があれば、指摘します。

3. Click the "Export CSV" button
   - **[CHANGED]** Button label is now "Download CSV" (updated in v2.2)
   - Verify download begins within 3 seconds

6. ワークフロー番号を維持する -- 既存のワークフローの番号を付け直さないでください。ワークフロー7が廃止され、ワークフロー28が追加された場合も、番号の空きはそのままにします。これにより、「ワークフロー7」への外部参照が引き続き有効になります。

更新の概要

更新操作の後に、変更内容の概要を提示します。

Desktop workflow update complete.

Changes:
- Workflows preserved (unchanged): 20
- Workflows updated (steps modified): 3
- Workflows deprecated: 1
- Workflows added (new): 3
- Total workflows: 27 (1 deprecated)

Changed workflows:
- Workflow 4: Updated step 3 (button label changed)
- Workflow 12: Updated step 1 (route changed from /settings to /preferences)
- Workflow 19: Updated steps 5-7 (new confirmation dialog added)

Deprecated workflows:
- Workflow 7: Legacy Export Feature (export removed in v2.3)

New workflows:
- Workflow 26: Dashboard Widget Customization
- Workflow 27: Real-Time Notification Center
- Workflow 28: Bulk Action on List View