@miniidealab/openlogos 0.9.5 → 0.9.7

package/claude-plugin-template/commands/verify.md

@@ -0,0 +1,17 @@
+---
+description: Run test verification and generate acceptance report with three-layer traceability
+---
+
+Verify test results against test case specs and generate an acceptance report.
+
+1. Run `openlogos verify` in the project root directory.
+2. If the `openlogos` CLI is not found, tell the user to install it:
+   ```
+   npm install -g @miniidealab/openlogos
+   ```
+3. The verify command reads `logos/resources/verify/test-results.jsonl` and matches results against test case specs in `logos/resources/test/`.
+4. It generates a three-layer acceptance report:
+   - Layer 1: Design-time coverage (are all test cases defined?)
+   - Layer 2: Runtime coverage (did all tests run?)
+   - Layer 3: Acceptance criteria (did all tests pass?)
+5. Display the report output to the user.

package/claude-plugin-template/hooks/hooks.json

@@ -0,0 +1,14 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/bin/openlogos-phase"
+          }
+        ]
+      }
+    ]
+  }
+}

package/claude-plugin-template/skills/api-designer/SKILL.md

@@ -0,0 +1,230 @@
+---
+name: api-designer
+description: "Design OpenAPI specifications derived from scenario sequence diagrams. Use when scenarios exist in 2-scenario-implementation/ but logos/resources/api/ is empty. All description and summary values in YAML must be double-quoted."
+---
+
+# Skill: API Designer
+
+> Design OpenAPI 3.0+ YAML specifications based on sequence diagrams, letting APIs emerge naturally from scenarios rather than being defined in isolation. Every endpoint is traceable to a Step number in the sequence diagrams, ensuring "no scenario, no API design."
+
+## Trigger Conditions
+
+- User requests API design or API documentation
+- User mentions "Phase 3 Step 2" or "API design"
+- Scenario sequence diagrams already exist and API specifications need to be refined
+- User provides a specific API endpoint that needs detailed design
+
+## Prerequisites
+
+- `logos/resources/prd/3-technical-plan/2-scenario-implementation/` contains scenario sequence diagrams
+- `logos/resources/prd/3-technical-plan/1-architecture/` contains the architecture overview (confirming frontend-backend separation approach, authentication scheme, etc.)
+- `tech_stack` in `logos-project.yaml` is filled in
+
+If the sequence diagram directory is empty, prompt the user to complete Phase 3 Step 1 (scenario-architect) first.
+
+## Core Capabilities
+
+1. Extract all cross-system-boundary API calls from sequence diagrams
+2. Deduplicate, merge, and group by domain to form an endpoint inventory
+3. Design OpenAPI 3.0+ YAML specifications (paths, parameters, request bodies, response structures)
+4. Define a unified error response format and error code system
+5. Design authentication schemes (Bearer Token / API Key / Cookie)
+6. Design standardized parameters for pagination, sorting, and filtering
+
+## 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/`): Extract all cross-system-boundary arrows
+- **Architecture overview** (`logos/resources/prd/3-technical-plan/1-architecture/`): Confirm authentication scheme, frontend-backend separation approach, API gateway, etc.
+- **`logos-project.yaml`**: Read `tech_stack` to confirm backend framework and deployment approach
+
+### Step 2: Extract Endpoint Inventory
+
+Traverse all scenario sequence diagrams and collect every cross-system-boundary call arrow:
+
+1. Identify "cross-system-boundary" arrows — client to server, server to external service, inter-service calls
+2. For each arrow, extract: HTTP method, path, source scenario number, and Step number
+3. Deduplicate and merge — the same endpoint may appear in multiple scenarios (e.g., `POST /api/auth/login` may appear in both S02 and S03)
+4. Output an endpoint inventory summary for user confirmation:
+
+```markdown
+Identified N API endpoints from sequence diagrams:
+
+| # | Method | Path | Source Scenario | Domain |
+|---|--------|------|-----------------|--------|
+| 1 | POST | /api/auth/register | S01 Step 2 | auth |
+| 2 | POST | /api/auth/login | S02 Step 1 | auth |
+| 3 | GET  | /api/projects | S04 Step 1 | projects |
+```
+
+### Step 3: Group by Domain
+
+Group endpoints by business domain, with each group corresponding to a YAML file:
+
+- `auth.yaml` — Authentication-related (registration, login, logout, password reset)
+- `projects.yaml` — CRUD for core business entities
+- `billing.yaml` — Payment and subscriptions
+
+Grouping principles:
+- Operations on the same data entity go together
+- Authentication/authorization is a separate group
+- Third-party service callbacks (e.g., payment callbacks) go under the corresponding business domain
+
+### Step 4: Design Unified Conventions
+
+Before generating specific endpoints, establish global conventions:
+
+**Authentication scheme** (read from architecture overview):
+
+```yaml
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+```
+
+**Unified error response**:
+
+```yaml
+components:
+  schemas:
+    ErrorResponse:
+      type: object
+      required: [code, message]
+      properties:
+        code:
+          type: string
+          description: Machine-readable error code (e.g., EMAIL_EXISTS)
+        message:
+          type: string
+          description: Human-readable error description
+        details:
+          type: object
+          description: Additional error information (e.g., field-level validation errors)
+```
+
+**Pagination parameters** (applicable to list endpoints):
+
+```yaml
+parameters:
+  - name: page
+    in: query
+    schema: { type: integer, minimum: 1, default: 1 }
+  - name: per_page
+    in: query
+    schema: { type: integer, minimum: 1, maximum: 100, default: 20 }
+```
+
+### Step 5: Design Detailed Specification per Endpoint
+
+Design a complete OpenAPI specification for each endpoint, **output by domain**, pausing after each domain for user review:
+
+Each endpoint must include:
+- `operationId`: Unique identifier for code generation
+- `summary`: One-sentence description
+- `description`: Annotate the source sequence diagram step (e.g., `Source: S01 Step 2 → Step 3`)
+- `requestBody`: Schema including all fields (with required, types, validation rules such as minLength/format)
+- `responses`: Cover the normal response + all known exceptions (extracted from EX use cases in sequence diagrams)
+
+**Example**:
+
+```yaml
+paths:
+  /api/auth/register:
+    post:
+      operationId: register
+      summary: User registration
+      description: "Source: S01 Step 2 → Step 3"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [email, password]
+              properties:
+                email: { type: string, format: email }
+                password: { type: string, minLength: 8 }
+      responses:
+        '201':
+          description: Registration successful, verification email sent
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  userId: { type: string, format: uuid }
+                  message: { type: string }
+        '409':
+          description: "Email already registered (EX-2.1)"
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '422':
+          description: Request parameter validation failed
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+```
+
+### Step 6: Verify Traceability Completeness
+
+After output is complete, perform a traceability check:
+
+1. **Forward check**: Every cross-system arrow in the sequence diagrams has a corresponding API endpoint
+2. **Reverse check**: Every API endpoint's `description` annotates the source Step
+3. **Exception coverage**: Every EX use case in the sequence diagrams has a corresponding HTTP error response
+
+If gaps are found, supplement them before outputting the final version.
+
+## Output Specification
+
+- File format: OpenAPI 3.1 YAML
+- Storage location: `logos/resources/api/`
+- Split by domain: `auth.yaml`, `projects.yaml`, `billing.yaml`
+- Each file contains complete `openapi`, `info`, `paths`, and `components` sections
+- Error responses uniformly reference `$ref: '#/components/schemas/ErrorResponse'`
+- Every endpoint's `description` must annotate the source sequence diagram step
+
+## YAML Formatting Rules (MUST Follow)
+
+YAML is whitespace- and character-sensitive. AI-generated YAML frequently breaks due to unquoted special characters. **Strictly follow these rules:**
+
+1. **Always double-quote `description` and `summary` values** — any string containing `:`, `→`, `#`, `&`, `*`, `!`, `>`, `|`, `%`, `@`, `` ` ``, `{`, `}`, `[`, or `]` MUST be wrapped in `"..."`.
+   ```yaml
+   # ❌ WRONG — colon + arrow breaks YAML parsing
+   description: Source: S05 Step 1 → Step 4.
+
+   # ✅ CORRECT
+   description: "Source: S05 Step 1 → Step 4."
+   ```
+2. **Always quote response status code keys** — use `'201'` not `201` to prevent YAML interpreting them as integers.
+3. **Self-check after generation** — after generating each YAML file, mentally re-parse it to verify no unquoted special characters exist. Pay special attention to `description` fields that reference scenario steps (they always contain `:`).
+4. **When in doubt, quote it** — quoting a safe string is harmless; leaving a dangerous string unquoted breaks the entire file.
+
+## Best Practices
+
+- **APIs emerge from sequence diagrams**: If an API cannot be traced back to a sequence diagram, it most likely should not exist. Design sequence diagrams first, then APIs — not the other way around
+- **Path naming**: RESTful style, use plural nouns, `/api/{resource}`
+- **Version prefix**: Do not add a version prefix initially (`/api/auth/register`); add `/api/v2/` when versioning becomes necessary
+- **Status code semantics**: Strictly follow HTTP status code semantics — 200 success, 201 created, 400 bad request, 401 unauthorized, 403 forbidden, 404 not found, 409 conflict, 422 validation failed, 500 server error
+- **Idempotent design**: PUT/DELETE operations must be idempotent
+- **Sensitive data**: Do not include plaintext sensitive information such as passwords or tokens in responses
+- **Output by domain**: Do not output all endpoints at once — output in batches by domain, letting the user review each batch before continuing
+- **Consistent field naming**: Field names in the API should be consistent with column names in the subsequent DB design (or have explicit mapping rules) to avoid unnecessary field transformations in the code layer
+
+## Recommended Prompts
+
+The following prompts can be copied directly for use with the AI:
+
+- `Help me design APIs`
+- `Generate OpenAPI YAML based on the sequence diagrams`
+- `Help me design the API specifications related to S01`
+- `Help me extract all cross-system calls from the sequence diagrams into APIs`

package/claude-plugin-template/skills/architecture-designer/SKILL.md

@@ -0,0 +1,186 @@
+---
+name: architecture-designer
+description: "Design technical architecture and select technology stack. Use when product design exists in logos/resources/prd/2-product-design/ but logos/resources/prd/3-technical-plan/1-architecture/ is empty."
+---
+
+# Skill: Architecture Designer
+
+> Before diving into per-scenario technical implementation, establish the project's technical global view — system architecture, technology selection, deployment topology, and non-functional constraints. Ensure that subsequent sequence diagrams, API designs, and code generation all proceed under consistent architectural constraints.
+
+## Trigger Conditions
+
+- User requests designing technical architecture, making technology selections, or planning system architecture
+- User mentions "Phase 3 Step 0", "architecture design", "technical plan"
+- Phase 2 product design documents are complete, and Phase 3 needs to begin
+- User wants to determine the tech stack or deployment strategy
+
+## Core Capabilities
+
+1. Read Phase 1 requirements documents and Phase 2 product design documents to understand the full product picture
+2. Based on product complexity and scenario characteristics, recommend suitable system architectures
+3. Provide selection rationale and alternative comparisons for each technology choice
+4. Draw system architecture diagrams (Mermaid) and deployment topology diagrams
+5. Update the `tech_stack` field in `logos-project.yaml`
+
+## Integration with Phase 1/2
+
+Architecture design is the bridge from Phase 2 (product design) to Phase 3 (technical implementation). Its inputs come from Phase 1/2, and its outputs influence all subsequent steps in Phase 3:
+
+| Input (from Phase 1/2) | Output (influences subsequent Phase 3 steps) |
+|------------------------|------------------------------|
+| Scenario list and complexity | System boundary definition → sequence diagram participants |
+| Non-functional requirements (performance, security) | Technology selection constraints → API design decisions |
+| Product interaction type (Web/Mobile/API) | Frontend tech stack → prototype implementation approach |
+| Data volume and access patterns | Database selection → DB design |
+| Third-party service dependencies (payment, email, etc.) | Integration approach → external participants in sequence diagrams |
+
+## Execution Steps
+
+### Step 1: Understand the Full Product Picture
+
+Read the following documents to build an overall understanding of the project:
+
+- **Requirements Document** (Phase 1): Product positioning, core scenarios, constraints and boundaries
+- **Product Design Document** (Phase 2): Information architecture, page structure, interaction complexity
+- **Existing `logos-project.yaml`**: Whether there are initial selections in the current `tech_stack`
+
+Key points to extract:
+- Number and complexity of core scenarios
+- Whether there are real-time requirements (WebSocket, SSE)
+- Whether there are background tasks (scheduled tasks, message queues)
+- List of third-party service dependencies
+- Expected user scale
+
+### Step 2: Determine System Architecture
+
+Choose an architecture pattern based on product complexity:
+
+**Simple Projects** (personal SaaS, utility products):
+- Monolithic architecture + single database
+- Architecture overview can be a paragraph of text + a simple diagram
+
+**Medium Projects** (team SaaS, multi-role systems):
+- Frontend-backend separation + monolithic backend + single database
+- May need auxiliary services like object storage, caching, etc.
+
+**Complex Projects** (multi-service, high-concurrency, multi-platform):
+- Microservices / modular monolith
+- Requires detailed Architecture Decision Records (ADR)
+
+Draw system architecture diagram using Mermaid:
+
+```mermaid
+graph TB
+    subgraph Frontend
+        Web[Web App - Next.js]
+    end
+    subgraph Backend
+        API[API Server - Node.js]
+        Worker[Background Worker]
+    end
+    subgraph Data
+        DB[(PostgreSQL)]
+        Cache[(Redis)]
+        S3[Object Storage]
+    end
+    subgraph External
+        Auth[Supabase Auth]
+        Email[SendGrid]
+    end
+
+    Web -->|REST API| API
+    API --> DB
+    API --> Cache
+    API --> S3
+    API --> Auth
+    Worker --> DB
+    Worker --> Email
+```
+
+### Step 3: Technology Selection
+
+Provide selection and rationale for each technology dimension:
+
+```markdown
+| Dimension | Selection | Rationale | Alternatives |
+|-----------|-----------|-----------|-------------|
+| Language | TypeScript | Unified frontend/backend, type safety | Go (when performance is priority) |
+| Frontend Framework | Next.js 15 | SSR + RSC, mature ecosystem | Astro (content sites), Nuxt (Vue ecosystem) |
+| Backend Framework | Hono | Lightweight, edge-first, native TS | Express (ecosystem), Fastify (performance) |
+| Database | PostgreSQL | Feature-rich, JSONB, RLS | MySQL (simple scenarios) |
+| Authentication | Supabase Auth | Out-of-the-box, RLS integration | NextAuth (self-hosted) |
+| Deployment | Vercel + Supabase | Zero-ops, auto-scaling | AWS (full control) |
+```
+
+**Selection Principles**:
+- Prefer technologies the team is already familiar with
+- When there is no significant difference, choose the option with the larger community
+- Selection rationale must be linked to specific product requirements or constraints
+
+### Step 4: Non-Functional Constraints
+
+Define key non-functional requirements:
+
+- **Performance Targets**: Core API response time, page load time
+- **Security Requirements**: Authentication method, data encryption, CORS policy
+- **Scalability**: Expected user scale, data growth estimates
+- **Observability**: Logging, monitoring, alerting strategy
+- **Developer Experience**: Local development environment, CI/CD pipeline
+
+### Step 5: External Dependencies and Test Strategies
+
+Catalog all external service dependencies for the project and determine the isolation strategy for each dependency during orchestration testing. The output of this step directly impacts whether Phase 3 Step 3 (orchestration testing) can be executed smoothly.
+
+1. Identify external dependencies from the architecture diagram and sequence diagram participants (email, SMS, verification codes, payment, OAuth, etc.)
+2. Confirm the test strategy for each dependency with the user
+
+Available test strategies:
+
+| Strategy | Description | Typical Scenario |
+|----------|-------------|-----------------|
+| `test-api` | Test environment provides a backdoor API | Email/SMS verification codes |
+| `fixed-value` | Specific test data uses fixed values | Fixed verification code for test phone numbers |
+| `env-disable` | Environment variable disables the feature | CAPTCHA, slider verification |
+| `mock-callback` | Orchestration actively calls a simulated callback | Payment callbacks, Webhooks |
+| `mock-service` | Local mock service as replacement | OAuth Provider |
+
+If the project has no external service dependencies (e.g., a pure CLI tool), this step can be skipped.
+
+### Step 6: Update logos-project.yaml
+
+Write the confirmed technology selections into the `tech_stack` field of `logos-project.yaml`, and write external dependencies and test strategies into the `external_dependencies` field, ensuring that all subsequent Skills and AI tools can read the unified tech stack and testing conventions.
+
+```yaml
+external_dependencies:
+  - name: "Email Service"
+    provider: "SendGrid"
+    used_in: ["S01-User Registration", "S03-Forgot Password"]
+    test_strategy: "test-api"
+    test_config: "GET /api/test/latest-email?to={email}"
+```
+
+## Output Specification
+
+- Architecture overview document: `logos/resources/prd/3-technical-plan/1-architecture/01-architecture-overview.md`
+- Architecture diagrams use Mermaid format
+- Technology selections use table format, each item must include rationale
+- Update the `tech_stack` and `external_dependencies` fields in `logos-project.yaml`
+- Simple projects are allowed to have streamlined output (not all sections are mandatory)
+
+## Best Practices
+
+- **Don't over-engineer**: For a solo developer building SaaS, monolith + PostgreSQL + Vercel is sufficient — don't jump straight to microservices
+- **Selection rationale matters more than the selection itself**: Documenting "why X was chosen" is more valuable than "X was chosen", because rationale needs to be re-evaluated as the project evolves
+- **Architecture diagrams are prerequisites for sequence diagrams**: System components in the architecture diagram become participants in subsequent sequence diagrams — the two must be consistent
+- **tech_stack is the AI's anchor**: Subsequent AI code generation reads `tech_stack` from `logos-project.yaml` — inaccurate selections will result in unusable generated code
+- **Start loose with non-functional constraints, tighten later**: Don't set overly strict performance targets initially; tighten them as real data becomes available
+- **Test strategies must be decided during the architecture phase**: If test approaches for verification codes, payments, and other external dependencies are left until orchestration testing, you'll often find that no backdoor APIs were provisioned, making fully automated orchestration tests impossible
+
+## Recommended Prompts
+
+The following prompts can be copied directly for use with AI:
+
+- `Help me design the technical architecture`
+- `Based on the product design, help me make technology selections`
+- `Help me draw the system architecture diagram`
+- `Help me determine the tech stack and update logos-project.yaml`

package/claude-plugin-template/skills/change-writer/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: change-writer
+description: "Write change proposals with impact analysis following OpenLogos delta workflow. Use when the project lifecycle is active and source code or methodology documents need modification."
+---
+
+# Skill: Change Writer
+
+> Assist in writing change proposals — analyze the scope of change impact, generate a structured proposal.md and a phase-based tasks.md, ensuring changes are traceable and impact is controllable.
+
+## Trigger Conditions
+
+- User has just run `openlogos change <slug>` and wants AI help filling in the proposal
+- User describes a need to modify, add, or remove a scenario/feature
+- User mentions "change proposal", "iteration", "requirement change"
+
+## Prerequisites
+
+1. Project is initialized (`logos/logos.config.json` exists)
+2. Change proposal directory has been created by CLI (`logos/changes/<slug>/` exists)
+3. Main documents are readable (effective documents exist in `logos/resources/`)
+
+If prerequisites are not met, prompt the user to run `openlogos change <slug>` to create the proposal directory first.
+
+## Core Capabilities
+
+1. Understand the user's intended change
+2. Scan existing documents in `logos/resources/` to identify the affected scope
+3. Determine the change type based on change propagation rules (Requirement-level / Design-level / Interface-level / Code-level)
+4. Generate a compliant proposal.md
+5. Automatically break down tasks.md by change type
+
+## Execution Steps
+
+### Step 1: Understand the Change Intent
+
+Confirm the following information with the user (ask follow-up questions if insufficient, up to 2 rounds):
+
+- **What is the change**: What needs to be added, modified, or removed?
+- **Reason for the change**: Why is this change needed? Is it from requirement feedback, a bug, or an optimization?
+- **Related scenarios**: Which existing scenario IDs are involved (S01, S02...)?
+
+### Step 2: Analyze the Impact Scope
+
+Scan documents in `logos/resources/` to determine the impact scope:
+
+1. Read requirement documents (`prd/1-product-requirements/`) to check related scenario definitions
+2. Read product design (`prd/2-product-design/`) to check related functional specs and prototypes
+3. Read technical plans (`prd/3-technical-plan/`) to check related sequence diagrams
+4. Read API documents (`api/`) to check related endpoints
+5. Read DB documents (`database/`) to check related table structures
+6. Read orchestration tests (`scenario/`) to check related test cases
+
+### Step 3: Determine the Change Type
+
+Refer to change propagation rules to determine the change type and minimum update scope:
+
+| Change Type | Minimum Updates Required |
+|-------------|------------------------|
+| Requirement-level change | Full chain (Requirements → Design → Architecture → API/DB → Orchestration → Code) |
+| Design-level change | Prototypes + Scenarios + API/DB + Orchestration + Code |
+| Interface-level change | API/DB + Orchestration + Code |
+| Code-level fix | Code + Re-verification |
+
+### Step 4: Generate proposal.md
+
+Generate using the following template and write to `logos/changes/<slug>/proposal.md`:
+
+```markdown
+# Change Proposal: [Change Name]
+
+## Reason for Change
+[Why is this change needed? What requirement/feedback/bug does it originate from?]
+
+## Change Type
+[Requirement-level / Design-level / Interface-level / Code-level]
+
+## Change Scope
+- Affected requirement documents: [List, down to filename and section]
+- Affected functional specs: [List]
+- Affected business scenarios: [Scenario ID list]
+- Affected APIs: [Endpoint list]
+- Affected DB tables: [Table name list]
+- Affected orchestration tests: [List]
+
+## Change Summary
+[Describe in 1-3 paragraphs what specifically will change]
+```
+
+### Step 5: Generate tasks.md
+
+Automatically break down the task checklist based on the change type and impact scope. Only list the phases that need updating:
+
+```markdown
+# Implementation Tasks
+
+## Phase 1: Document Changes
+- [ ] Update acceptance criteria for S0x in requirement documents
+- [ ] Add/modify scenario in the scenario overview table
+
+## Phase 2: Design Changes
+- [ ] Update interaction design for S0x in functional specs
+- [ ] Update prototypes
+
+## Phase 3: Technical Changes
+- [ ] Update sequence diagram for S0x
+- [ ] Update API YAML
+- [ ] **Validate API YAML** — all files in `logos/resources/api/` must be valid YAML and valid OpenAPI 3.x (all `description`/`summary` values containing `:` or special chars must be double-quoted)
+- [ ] Update DB DDL
+- [ ] Update orchestration test cases
+- [ ] Implement code changes
+```
+
+### Step 6: Guide Follow-up Actions (Chain-driven)
+
+Provide a ready-to-use prompt that allows the user to kick off chain execution of all tasks with a single command:
+
+- **Requirement-level / Design-level changes** (multiple tasks): Suggest the user say "Follow tasks.md and help me progressively update all affected documents for S0x"
+- **Code-level fixes** (fewer tasks): Suggest the user say "Help me fix the [issue description] for S0x and re-verify"
+
+Chain execution behavior rules:
+1. AI reads `tasks.md` and executes items sequentially
+2. **After completing each task, immediately update that item in `tasks.md` from `[ ]` to `[x]`** (AI does this proactively — no user reminder needed)
+3. After completing each task, report a summary of changes and automatically prompt "Continue to the next item?"
+4. After the user says "Continue" or provides adjustments, proceed to the next item
+5. After all tasks are completed, remind the user to explicitly authorize running `openlogos merge <slug>`
+
+**Key principle**: Do not make the user manually track the task checklist — AI should proactively drive the process.
+
+**`openlogos merge` and `openlogos archive` are human confirmation points**:
+- AI must not execute these commands without explicit user authorization
+- When the user explicitly requests execution (including via `/openlogos:merge` or `/openlogos:archive` slash commands), AI may execute them
+- Must not be triggered implicitly in scenarios like "continue", "finish up", or "follow the process"
+
+AI is only responsible for driving content modifications and must not advance proposal state without explicit authorization.
+
+## Output Specification
+
+- File format: Markdown
+- Storage location: `logos/changes/<slug>/`
+- Filenames: `proposal.md` and `tasks.md` (overwrite the CLI-generated templates)
+
+## Best Practices
+
+- **Overestimate the impact scope**: Missing an update in one link is more dangerous than double-checking
+- **Change type determines workload**: Help users understand before they start that changing one requirement may require a full-chain update
+- **tasks.md is the execution checklist**: Check off each item with `[x]` upon completion for easy progress tracking
+- **Follow the process even for small changes**: A change that appears to be "just one API line" may affect orchestration tests and code
+
+## Recommended Prompts
+
+The following prompts can be copied directly for use with AI:
+
+**Fill in proposal**:
+- `Help me fill in the change proposal <slug>`
+- `I want to add a "remember password" feature to the S02 login scenario, help me analyze the impact scope`
+- `This bug fix only involves the code layer, help me quickly write a proposal`
+
+**Execute tasks (after proposal is completed)**:
+- `Follow tasks.md and help me progressively update all affected documents for S02`
+- `Help me fix the 500 error on the S02 login endpoint and re-verify`