@miniidealab/openlogos 0.9.4 → 0.9.6

package/claude-plugin-template/skills/project-init/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: project-init
+description: "Initialize OpenLogos project structure and directory layout. Use when the user wants to set up a new project with openlogos init or needs help with project initialization."
+---
+
+# Skill: Project Init
+
+> Initialize a project structure following the OpenLogos methodology, generating configuration files, AI instruction files, and standard directories.
+
+## Trigger Conditions
+
+- User requests creating a new project or initializing a project structure
+- User mentions "openlogos init" or "initialize project"
+- No `logos/logos.config.json` exists in the current directory
+
+## Core Capabilities
+
+1. Create the `logos/` directory and its standard substructure
+2. Generate the `logos/logos.config.json` configuration file
+3. Generate the `logos/logos-project.yaml` AI collaboration index
+4. Generate `AGENTS.md` / `CLAUDE.md` AI instruction files (in the root directory)
+5. Create the `logos/changes/` change management directory
+
+## Execution Steps
+
+### Step 1: Gather Project Information
+
+Confirm the following information with the user:
+
+- **Project name**: Used for the `name` field in `logos/logos.config.json`
+- **Project description**: A one-sentence description
+- **Tech stack**: Main framework, language, database, deployment platform
+- **Document modules**: Whether additional modules are needed beyond the default prd/api/scenario/database
+
+If the user does not provide these, use reasonable defaults.
+
+### Step 2: Create Directory Structure
+
+```
+project-root/
+└── logos/
+    ├── resources/
+    │   ├── prd/
+    │   │   ├── 1-product-requirements/
+    │   │   ├── 2-product-design/
+    │   │   │   ├── 1-feature-specs/
+    │   │   │   └── 2-page-design/
+    │   │   └── 3-technical-plan/
+    │   │       ├── 1-architecture/
+    │   │       └── 2-scenario-implementation/
+    │   ├── api/
+    │   ├── database/
+    │   └── scenario/
+    └── changes/
+```
+
+### Step 3: Generate logos/logos.config.json
+
+```json
+{
+  "name": "{project name}",
+  "description": "{project description}",
+  "documents": {
+    "prd": {
+      "label": { "en": "Product Docs", "zh": "产品文档" },
+      "path": "./resources/prd",
+      "pattern": "**/*.{md,html,htm,pdf}"
+    },
+    "api": {
+      "label": { "en": "API Docs", "zh": "API 文档" },
+      "path": "./resources/api",
+      "pattern": "**/*.{yaml,yml,json}"
+    },
+    "scenario": {
+      "label": { "en": "Scenarios", "zh": "业务场景" },
+      "path": "./resources/scenario",
+      "pattern": "**/*.json"
+    },
+    "database": {
+      "label": { "en": "Database", "zh": "数据库" },
+      "path": "./resources/database",
+      "pattern": "**/*.sql"
+    }
+  }
+}
+```
+
+> The `path` field is relative to the directory where `logos.config.json` itself resides (i.e., `logos/`), so `./resources/prd` points to `logos/resources/prd`.
+
+### Step 4: Generate logos/logos-project.yaml
+
+```yaml
+project:
+  name: "{project name}"
+  description: "{project description}"
+  methodology: "OpenLogos"
+
+tech_stack:
+  framework: "{framework provided by user}"
+  language: "{language provided by user}"
+  # ... populate based on user-provided information
+
+resource_index: []
+  # Initially empty; entries are added incrementally as documents are produced
+
+conventions:
+  - "Follow the OpenLogos three-layer progression model (Why → What → How)"
+  - "Every change must first create a change proposal in logos/changes/"
+```
+
+### Step 5: Generate AGENTS.md (Root Directory)
+
+Generate AGENTS.md based on the content from Step 3 and Step 4, placed in the **project root directory**:
+
+```markdown
+# AI Assistant Instructions
+
+This project follows the **OpenLogos** methodology.
+Read `logos/logos-project.yaml` first to understand the project resource index.
+
+## Project Context
+- Config: `logos/logos.config.json`
+- Resource Index: `logos/logos-project.yaml`
+- Tech Stack: {extracted from logos-project.yaml}
+
+## Methodology Rules
+1. Never write code without first completing the design documents
+2. Follow the Why → What → How progression
+3. All API designs must originate from scenario sequence diagrams
+4. All code changes must have corresponding API orchestration tests
+5. Use the Delta change workflow for iterations (see logos/changes/ directory)
+
+## Conventions
+{extracted from conventions in logos-project.yaml}
+```
+
+Also generate `CLAUDE.md` with identical content to AGENTS.md.
+
+### Step 6: Output Initialization Report
+
+Report to the user which files and directories were created, and provide next-step suggestions:
+
+1. Edit `logos/logos.config.json` to refine the project configuration
+2. Start with Phase 1: Write the requirements document
+3. Use the `prd-writer` Skill to assist with writing
+
+## Output Specification
+
+- `logos/logos.config.json`: Valid JSON, conforming to `logos/spec/logos.config.schema.json`
+- `logos/logos-project.yaml`: Valid YAML
+- `AGENTS.md` / `CLAUDE.md`: Markdown format, located in the project root directory
+- All directories under `logos/` are created; empty directories contain `.gitkeep`
+
+## Best Practices
+
+- **Don't over-configure**: Keep configuration minimal during initialization; let users refine it gradually during use
+- **resource_index starts empty**: Add entries as documents are produced, avoiding meaningless placeholder content
+- **Keep AGENTS.md concise**: Only include project-specific information; use fixed templates for universal methodology rules
+- **Prioritize creating the directory structure**: The `logos/` directory structure is the first step in adopting the methodology — more important than any document
+- **Low intrusiveness**: All methodology assets are contained within `logos/`, keeping the project's own structure clean
+
+## Recommended Prompts
+
+The following prompts can be copied directly for use with AI:
+
+- `Help me initialize an OpenLogos project`
+- `Initialize this project with OpenLogos, the project name is xxx`
+- `Help me integrate OpenLogos into an existing project`

package/claude-plugin-template/skills/scenario-architect/SKILL.md

@@ -0,0 +1,229 @@
+---
+name: scenario-architect
+description: "Model business scenarios as detailed sequence diagrams with API calls. Use when architecture exists in 3-technical-plan/1-architecture/ but 3-technical-plan/2-scenario-implementation/ is empty. Scenarios must be complete user action paths, NOT single API calls."
+---
+
+# Skill: Scenario Architect
+
+> Expand business scenarios defined in Phase 1/2 into technical sequence diagrams, letting API design emerge naturally, and design comprehensive exception cases. Scenario numbering follows Phase 1 definitions.
+
+## Trigger Conditions
+
+- User requests drawing sequence diagrams, designing business scenarios, or performing scenario modeling
+- User mentions "Phase 3 Step 1", "scenario-driven", "technical plan design"
+- Requirements documents and product design documents (with scenario definitions) already exist, ready to begin technical implementation
+- User specifies a particular scenario number (e.g., S01) to be expanded into a sequence diagram
+
+## Core Capabilities
+
+1. Read scenario definitions and acceptance criteria from Phase 1/2 as input for sequence diagrams
+2. Draw Mermaid sequence diagrams for each scenario (strictly following numbering conventions)
+3. Write explanatory notes for key steps (explaining "why" rather than "what")
+4. Identify exception conditions for each step and design structured exception cases
+5. Generate scenario overview documents (scenario map + scenario index)
+
+## Linking with Phase 1/2
+
+**Phase 3 does not identify scenarios from scratch.** Scenarios are defined in Phase 1 (`S01`, `S02`...), interaction flows are refined in Phase 2, and technical architecture and technology choices are established in Step 0. The job of Phase 3 Step 1 is to expand the same scenario from an "interaction perspective" into a "technical perspective". The participants in the sequence diagram should align with the system components in the architecture diagram:
+
+| Input (from Phase 1/2) | Output (Phase 3) |
+|------------------------|----------------|
+| Scenario number and name | Sequence diagram title retains the number |
+| Trigger conditions | Starting arrow of the sequence diagram |
+| Main path description | Step sequence in the sequence diagram |
+| GIVEN/WHEN/THEN (business level) | Behavior description of sequence diagram steps |
+| Exception acceptance criteria | EX exception cases (technical level) |
+| Pages and interactions involved (Phase 2) | Participant identification |
+
+## Execution Steps
+
+### Step 1: Load Scenario Context
+
+Read scenario definitions from the Phase 1 requirements document, Phase 2 product design document, and Phase 3 Step 0 technical architecture summary. **Do not reinvent scenarios**—directly reuse existing numbers and descriptions. Participant naming should be consistent with the system components in the architecture diagram.
+
+**Scenario Granularity Pre-Check (before drawing any sequence diagram):**
+
+Before proceeding, verify that the scenario definitions from Phase 1 have proper granularity. Check for these anti-patterns:
+
+- **One-API scenarios**: If a scenario's main path only has 1-2 steps (e.g., "Create Task" = just `POST /api/tasks`), it is too fine-grained
+- **CRUD fragmentation**: If the scenario list contains separate "Create X", "Read X", "Update X", "Delete X" scenarios for the same entity, they should be merged into goal-driven scenarios
+- **No business goal**: If a scenario's outcome is just "data was written/read", it lacks a real user goal
+
+**If any anti-pattern is detected**: Stop and recommend returning to Phase 1 to re-organize scenarios by business goals before drawing sequence diagrams. Drawing sequence diagrams for overly fine-grained scenarios will propagate the problem to API design, test cases, and code.
+
+Confirm the following for each scenario:
+- **Scenario number**: Reuse Phase 1's `S01`, `S02`... (or Phase 2 sub-scenarios `S01.1`)
+- **Participants**: Identify which system components are involved from Phase 2's interaction flows
+- **Main path**: Extract the normal flow from Phase 1/2 acceptance criteria
+- **Known exceptions**: Extract from Phase 1/2 exception acceptance criteria
+
+### Step 2: Draw Sequence Diagrams
+
+Draw Mermaid sequence diagrams for each scenario, **strictly following these conventions**:
+
+**Numbering conventions**:
+- Every arrow must have a `Step N:` number prefix
+- Numbering starts at 1 and increments consecutively
+- Each arrow includes a one-line behavior description: `HTTP_METHOD /api/path — brief explanation`
+
+**Participant conventions**:
+- Use short aliases: `U` (User/Browser), `W` (Web/Frontend), `SB` (Supabase), `DB` (Database)
+- Full name for each participant is noted in the `participant` declaration
+
+**Scenario numbering conventions**:
+- Document title format: `S01: Email Registration — Sequence Diagram`
+- One scenario per file, numbered to correspond with Phase 1
+
+**Format example**:
+
+```mermaid
+sequenceDiagram
+    participant U as User/Browser
+    participant W as Web (Astro)
+    participant SB as Supabase Auth
+    participant DB as Supabase DB
+
+    U->>W: Step 1: POST /api/auth/register — Submit {email, password, referral_code?}
+    W->>SB: Step 2: supabase.auth.signUp(email, password, metadata) — Initiate user creation
+    SB-->>W: Step 3: Return {user, session} or error
+    W->>DB: Step 4: INSERT INTO profiles — Write user extended info
+    DB-->>W: Step 5: Return write result
+    W-->>U: Step 6: Return registration result + prompt to verify email
+```
+
+### Step 3: Write Step Narratives
+
+After the sequence diagram, use a **consecutively numbered list** to write out all steps one by one, forming a linear narrative that humans can read fluently from start to finish.
+
+**Format conventions**:
+
+1. **Every step must be written out**—no skipping, no omitting. Simple steps can be covered in one line; complex steps are elaborated below using `>` blockquote
+2. **Every step must have a clear subject**—the reader should never have to guess "who is doing this". Use the alias or full name from the participant table as the subject
+3. **Numbering strictly corresponds to the Step N in the sequence diagram**
+4. **Normal flow and exception cases are written separately**—normal flow comes first, exception cases follow. In the normal flow, only add `→ see EX-N.M` references after steps that trigger exceptions; do not expand exception content inline
+
+**Normal flow format example**:
+
+````markdown
+## Step Descriptions
+
+1. **Developer** enters `openlogos init my-project` in the terminal.
+2. **CLI** checks whether `logos/logos.config.json` already exists. If it exists → see EX-2.1.
+3. **CLI** displays a language selection menu in the terminal (1. English / 2. 中文). If the terminal is non-TTY → see EX-3.1.
+
+> Language selection is placed in the `init` phase (rather than global configuration) because this is the user's first interaction with OpenLogos, making it the most natural moment to confirm language preference.
+
+4. **Developer** selects a language (enters 1 or 2).
+5. **CLI** detects the project name from `package.json` / `Cargo.toml` / `pyproject.toml` / directory name. If the user-provided name conflicts with the config file name → see EX-5.1.
+
+> Priority chain: CLI argument > package.json > Cargo.toml > pyproject.toml > directory name. Scoped names automatically strip the `@org/` prefix.
+
+6. **CLI** creates 11 directories in sequence (`logos/resources/prd/...` etc.), writing `.gitkeep` to each.
+7. **CLI** writes `logos/logos.config.json` (containing locale + 5 document module definitions).
+8. **CLI** writes `logos/logos-project.yaml` (containing empty tech_stack + conventions).
+9. **CLI** writes `AGENTS.md` and `CLAUDE.md` (containing Phase detection logic).
+10. **CLI** outputs the list of created files and next-step suggestions in the terminal.
+````
+
+**Exception case format example**:
+
+````markdown
+## Exception Cases
+
+### EX-2.1: Project Already Initialized
+
+- **Trigger condition**: Step 2 detects that `logos/logos.config.json` already exists
+- **Expected response**: stderr outputs `Error: logos/logos.config.json already exists in current directory.`, exit(1)
+- **Side effects**: No files created, existing configuration not overwritten
+
+### EX-3.1: Non-TTY Environment
+
+- **Trigger condition**: Step 3 detects that `process.stdin.isTTY` is false (CI pipeline / piped input)
+- **Expected response**: Skip language selection interaction, default to `locale = 'en'`
+- **Side effects**: None, flow proceeds directly to Step 5
+
+### EX-5.1: Project Name Conflict
+
+- **Trigger condition**: In Step 5, the user-provided `name` differs from the name in `package.json` (or other config files)
+- **Expected response**: Display two options for the user to choose from; in non-TTY environments, automatically use the user-provided name
+- **Side effects**: None, flow continues to Step 6 after selection
+````
+
+**Narrative principles**:
+- **No skipping steps**: Even if a step is worth only one line (e.g., "CLI writes file"), it must still be written out to maintain consecutive numbering
+- **Subject first**: Each step begins with a bold subject, so the reader can immediately see "who is acting"
+- **Use blockquotes for supplementary notes**: When you need to explain "why" or document a design decision, expand below the step using `>` blockquote without disrupting reading flow
+- **Exception cases as separate sections**: Normal flow only contains `→ see EX-N.M` references; the trigger conditions, expected responses, and side effects of exceptions are expanded in the "Exception Cases" section at the bottom of the document
+
+### Step 4: Design Exception Cases
+
+Expand exception acceptance criteria identified in Phase 1/2 into technical-level exception cases, and supplement with technical exceptions not covered in Phase 1/2 (e.g., service unavailable, database write failure):
+
+```markdown
+#### Exception Cases
+
+##### EX-2.1: Email Already Registered (← Phase 1 S01 exception acceptance criteria)
+- **Trigger condition**: Submitted email already exists in the auth.users table
+- **Expected response**: HTTP 409 `{ code: "EMAIL_EXISTS", message: "Email already registered" }`
+- **Side effects**: No records created, no emails sent
+
+##### EX-2.2: Supabase Auth Service Unavailable (technical exception, not covered in Phase 1)
+- **Trigger condition**: Supabase Auth service times out or returns 5xx
+- **Expected response**: HTTP 503 `{ code: "AUTH_SERVICE_UNAVAILABLE", message: "Authentication service temporarily unavailable" }`
+- **Side effects**: Error logged, alert triggered
+
+##### EX-4.1: Profile Write Failure (technical exception, not covered in Phase 1)
+- **Trigger condition**: INSERT INTO profiles violates unique constraint or RLS denies access
+- **Expected response**: HTTP 500 `{ code: "PROFILE_CREATE_FAILED", message: "User profile creation failed" }`
+- **Side effects**: Record in auth.users already created but profiles not created (compensation mechanism needed)
+```
+
+**Exception case numbering rule**: `EX-{step number}.{sequence number}`
+
+### Step 5: Generate Scenario Overview Document
+
+Summarize the technical implementation status of all scenarios:
+
+```markdown
+# Business Scenario Overview (Technical Implementation)
+
+## Scenario Map
+| Number | Scenario Name | Phase 1 | Phase 2 | Phase 3 Sequence Diagram | API | Orchestration | Status |
+|--------|--------------|---------|---------|--------------------------|-----|---------------|--------|
+| S01    | Email Registration | ✅ | ✅ | ✅ | ✅ | 🔲 | In Progress |
+| S02    | Password Login | ✅ | ✅ | 🔲 | 🔲 | 🔲 | Not Started |
+
+## Scenario Dependencies
+[Describe prerequisite/follow-up relationships between scenarios]
+
+## Scenario Index
+[File links for each scenario, spanning all three Phases]
+```
+
+## Output Specification
+
+- **Scenario overview**: `logos/resources/prd/3-technical-plan/2-scenario-implementation/00-scenario-overview.md`
+- **Scenario documents**: `logos/resources/prd/3-technical-plan/2-scenario-implementation/{scenario-number}-{scenario-name}.md`
+- Sequence diagrams use Mermaid format (renderable directly in Markdown)
+- Exception cases use `EX-N.M` numbering, globally unique
+- Each scenario document contains: sequence diagram + step descriptions + exception cases
+- **Scenario numbers must be consistent with Phase 1/2**
+
+## Best Practices
+
+- **Do not identify scenarios from scratch**: Phase 3 scenarios come from Phase 1 requirements documents. If a scenario not present in Phase 1 is discovered, go back to Phase 1 to add it
+- **Phase 1/2 exceptions are inputs**: Phase 1's "exception: email already registered" should be expanded in Phase 3 into a technical specification with HTTP status codes and response bodies
+- **Draw the main path first, then add exceptions**: Do not try to draw all branches in the first pass; get the main path clear first
+- **Exception case coverage strategy**: Every step involving an external call (database, third-party service) should have at least 1 exception case
+- **Step numbering maintenance**: When inserting a step in the middle, renumber all subsequent steps and update all EX references accordingly
+- **Participant granularity**: In microservice architectures, each service is a participant; in monolithic applications, divide by logical layers (Web, Auth, DB)
+- **Sequence diagrams are the source of APIs**: Cross-system-boundary arrows in sequence diagrams are the APIs that need to be designed—if an API cannot be traced back to a sequence diagram, it probably should not exist
+
+## Recommended Prompts
+
+The following prompts can be copied directly for AI use:
+
+- `Help me draw the sequence diagram for S01`
+- `Help me do scenario modeling for all P0 scenarios`
+- `Help me add exception case sequence diagrams for S03`
+- `Based on the product design, help me do technical scenario modeling`

package/claude-plugin-template/skills/test-orchestrator/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: test-orchestrator
+description: "Design API orchestration test scenarios as executable JSON. Use when test cases exist in logos/resources/test/ but logos/resources/scenario/ is empty. For API projects only."
+---
+
+# Skill: Test Orchestrator
+
+> Design **API orchestration test** cases based on business scenarios and sequence diagrams (Phase 3 Step 3b), covering normal/exception/boundary scenarios. Automatically identify external dependencies and apply test strategies as end-to-end API acceptance criteria. **Only applicable to projects involving APIs.**
+
+## Relationship with test-writer
+
+This Skill is responsible for the **top layer** of the test pyramid — API orchestration tests (HTTP request level), executed in Phase 3 Step 3b.
+
+The lower-level unit tests and scenario tests (function call level) are completed by the `test-writer` Skill in Step 3a. Step 3a is a mandatory step for all projects; Step 3b (this Skill) is only executed when the project involves APIs.
+
+## Trigger Conditions
+
+- User requests API orchestration test design
+- User mentions "Phase 3 Step 3b", "API orchestration", or "orchestration tests"
+- After Step 3a (test-writer) is complete, AI guides the user to proceed to Step 3b
+- User needs to validate deployed API code
+
+## Prerequisites
+
+- `logos/resources/test/` contains test case specification documents (Step 3a completed)
+- `logos/resources/prd/3-technical-plan/2-scenario-implementation/` contains scenario sequence diagrams
+- `logos/resources/api/` contains API specifications (OpenAPI YAML)
+- `logos-project.yaml` contains `external_dependencies` (if applicable)
+
+If the project does not involve APIs (pure CLI tools, pure frontend, etc.), skip this Skill.
+
+## Core Capabilities
+
+1. Design normal flow orchestration from sequence diagrams and API YAML
+2. Design exception flow orchestration based on exception cases (EX-N.M)
+3. Design boundary cases (valid but non-happy-path variations)
+4. Define variable extraction and passing mechanisms
+5. **Identify external dependencies and apply test strategies**: Read `external_dependencies` from `logos-project.yaml` and automatically insert `mock` fields in steps involving external services
+6. Execute orchestration and verify results
+
+## Execution Steps
+
+### Step 1: Read Scenario Context
+
+Read the following files to establish complete context:
+
+- Scenario sequence diagrams (`logos/resources/prd/3-technical-plan/2-scenario-implementation/`)
+- API YAML (`logos/resources/api/`)
+- `logos-project.yaml` — focus on reading the `external_dependencies` field
+
+### Step 2: Identify External Dependencies
+
+Match `used_in` from `external_dependencies` with the current scenario number. If the current scenario involves external dependencies:
+
+- Record the dependency's `test_strategy` and `test_config`
+- If a dependency declares `used_in` but is missing `test_strategy`, **proactively ask the user** for the test strategy
+
+If there is no `external_dependencies` field in `logos-project.yaml`, but the sequence diagrams contain calls to external services (e.g., sending emails, payment requests, etc.), proactively remind the user to add them.
+
+### Step 3: Design Normal Flow Orchestration
+
+Design the API call chain step by step following the sequence diagram's Step numbers:
+
+- Each step includes method, url, headers, body, expected_status
+- For steps involving external dependencies, insert the `mock` field (see Output Specification)
+- For variables that need to be passed from the previous step's response, use `extract` to define extraction rules
+
+### Step 4: Design Exception Flow Orchestration
+
+Design independent orchestrations for each EX exception case, ensuring:
+
+- Exception scenarios also cover external dependency failure cases
+- Use the `mock` field to simulate external service failures (e.g., timeouts, error responses, etc.)
+
+### Step 5: Design Boundary Case Orchestration
+
+Identify valid but non-happy-path variations (e.g., password length exactly at the boundary value, empty fields, etc.) and add supplementary orchestrations.
+
+### Step 6: Output Orchestration JSON
+
+Output executable orchestration JSON files per scenario.
+
+## Output Specification
+
+- File format: JSON
+- Storage location: `logos/resources/scenario/`
+- Separate files per scenario: `user-auth.json`, `payment-flow.json`
+- Each step in the orchestration corresponds to a Step number in the sequence diagram
+
+### mock Field Structure
+
+When a step involves an external dependency, add a `mock` field to that step:
+
+```json
+{
+  "step": "Step 2: Get email verification code",
+  "mock": {
+    "dependency": "Email Service",
+    "strategy": "test-api",
+    "config": "GET /api/test/latest-email?to={email}",
+    "extract": { "code": "response.body.code" }
+  },
+  "method": "GET",
+  "url": "/api/test/latest-email?to={{email}}",
+  "expected_status": 200,
+  "extract": {
+    "verification_code": "body.code"
+  }
+}
+```
+
+`mock` field description:
+
+| Field | Type | Description |
+|------|------|------|
+| `dependency` | string | Corresponds to `name` in `external_dependencies` |
+| `strategy` | string | Test strategy (`test-api` / `fixed-value` / `env-disable` / `mock-callback` / `mock-service`) |
+| `config` | string | Specific configuration for the test strategy, from `test_config` |
+| `extract` | object | Extract variables from mock response (optional) |
+
+Orchestration behavior for different strategies:
+
+- **`test-api`**: The step's url is replaced with the backdoor API address
+- **`fixed-value`**: The step does not make an actual request; fixed values are injected directly via `extract`
+- **`env-disable`**: The step is marked as skipped, with a comment explaining the precondition
+- **`mock-callback`**: An additional mock callback request is inserted after the previous step completes
+- **`mock-service`**: The step's url is replaced with the local mock service address
+
+## Best Practices
+
+- **Normal orchestration is the skeleton**: Complete the normal flow orchestration first to ensure the happy path works end-to-end
+- **Exception orchestration is the safety net**: At least 1 exception orchestration per external call
+- **Variable passing**: Extract variables from the previous step's response (e.g., token, user_id) and pass them to subsequent steps
+- **Test data**: Prepare test data before orchestration begins and clean up afterwards to ensure idempotency
+- **Concurrency testing**: Key scenarios should account for concurrent situations (e.g., two users registering with the same email simultaneously)
+- **Check the external dependency list first**: Before starting orchestration design, read `external_dependencies` from `logos-project.yaml`; proactively remind the user to add any undeclared external calls
+- **Do not decide mock strategies on your own**: Test strategies are determined during S12 technical architecture design (Phase 3 Step 0, architecture-designer); the orchestration test phase only consumes them — do not modify them unilaterally
+- **Relationship with `openlogos verify`**: API orchestration tests can also produce JSONL results in the same format as `logos/spec/test-results.md`. After orchestration tests run, results are also written to `logos/resources/verify/test-results.jsonl`, and `openlogos verify` reads them uniformly to determine acceptance
+
+## Recommended Prompts
+
+The following prompts can be copied directly for AI use:
+
+- `Help me design orchestration tests`
+- `Generate orchestration tests for S01 based on the API spec`
+- `Help me orchestrate all normal paths for every scenario`
+- `Help me add exception path orchestration tests for S02`