@arimakouyou/spec-workflow-mcp 2.2.7

package/.claude-plugin/rules/design-conformance.md

@@ -0,0 +1,82 @@
+---
+always_apply: true
+---
+
+# Design Conformance
+
+Rules to prevent deviations from the approved design.md.
+
+## Principle
+
+**Do not change the approved design during the implementation phase.** The DB schema, API design, and data model defined in design.md are a "contract" for the implementation; implementers must not change them unilaterally.
+
+## Prohibited Actions During Implementation
+
+### DB Schema
+- Do not add tables or columns not defined in design.md
+- Do not change the type or constraints of already-defined columns
+- Do not add or remove indexes without authorization
+- **Implement FK ON DELETE behavior exactly as defined in design.md** (do not change or add CASCADE / RESTRICT / SET NULL without authorization)
+- Follow design.md for NULL / NOT NULL definitions
+
+### API
+- Do not add endpoints not defined in design.md
+- Do not change defined HTTP methods, paths, or status codes
+- Do not add, remove, or change the type of request/response fields
+- Do not change the format of error responses
+- **Error codes**: Use only the error codes defined in the Error Handling section of design.md. If an undefined error case arises during implementation, handle it in the following order:
+  1. Consider whether an error code already defined in design.md can serve as a substitute (e.g., if `Conflict` is undefined, substitute with `BadRequest("duplicate key")`)
+  2. If substitution is not possible, escalate and confirm with the user
+
+### Data Model
+- Do not add fields to Model / DTO that are not defined in design.md
+- Do not create mismatches between DTO and API definitions
+
+## When a Design Change Is Needed
+
+If a design problem is discovered during implementation:
+
+1. Stop the implementation
+2. Clearly describe the problem and the proposed change
+3. Escalate to the user (review-worker's `review_action: escalate`)
+
+Based on the user's judgment, proceed with one of the following:
+
+**Decision criteria (guidance for choosing A vs B):**
+
+| Indicator | A (Implementation Adjustment) | B (Phase Reset) |
+|-----------|-------------------------------|-----------------|
+| Scope of change | Only the implementation approach of a single task | The DB schema / API spec / data model definitions themselves |
+| Impact on existing implementation | Does not affect other completed tasks | Requires rewriting code for other tasks |
+| Change to design.md | Not required (only appending to Restrictions) | Required |
+| Typical example | Misinterpretation of DTO field usage, change to an existing component in use | Table definition change, addition/removal of response types, FK spec change |
+
+### A. Adjust Implementation Within the Scope of design.md (Minor Cases)
+
+- Append the adjustment details to the Restrictions in `_Prompt`, and return to parallel-worker via rework
+- Do not change design.md
+
+### B. design.md Change Required (Fundamental Problems) — Phase Reset
+
+**If design.md must be changed, discard all implementation so far and restart from Phase 2.** Partial fixes are not permitted.
+
+Phase Reset procedure:
+1. **Suspend Phase 5**: Revert in-progress tasks (`[-]`) to `[ ]`
+2. **Discard implementation code**: Undo code implemented and committed in Phase 5 using `git revert`
+3. **Delete tasks.md**: Delete `.spec-workflow/specs/{spec-name}/tasks.md` (Phase 4 artifact)
+4. **Fix design.md**: Return to Phase 2 and fix design.md
+5. **Re-review**: Re-validate design.md with spec-review (check)
+6. **Re-approval**: Obtain re-approval of design.md via the Approval Workflow
+7. **Re-run Phase 3-4**: Re-create test-design.md with `/spec-test-design`, then tasks.md with `/spec-tasks`
+8. **Re-run Phase 5**: Restart implementation from the beginning with `/spec-implement`
+
+**Note:** Phase Reset carries a high cost. To avoid this, conduct thorough design reviews in Phase 2 (DB Schema, API Design, Data Model, Error Handling).
+
+## Verification in review-worker
+
+When performing a code review, review-worker reads `design.md` and checks the following:
+
+- Whether the implemented DB migrations match the schema definitions in design.md
+- Whether the paths, methods, and request/response types of implemented endpoints match the API definitions in design.md
+- Whether the fields of implemented Model / DTO match the data model definitions in design.md
+- Whether there are any additions not defined in design.md

package/.claude-plugin/rules/design-principles.md

@@ -0,0 +1,53 @@
+---
+always_apply: true
+---
+
+# Design Principles
+
+Design principles to apply during code reviews and implementation.
+
+## Separation of Concerns
+
+- Each function, struct, or module should focus on a single responsibility
+- Do not write business logic in handlers. Handlers should be limited to "accepting input → calling services/repositories → building responses"
+- Place validation, data transformation, and business rules in their appropriate layers
+- If you cannot explain "what this function does" in one sentence, consider splitting it
+
+## Direction of Dependencies
+
+- Higher layers depend on lower layers (handler → service/repository → model)
+- Reverse dependencies (e.g., model referencing handler) are prohibited
+- Do not create circular dependencies
+- Abstract dependencies on external services using traits; avoid direct dependencies on concrete types
+
+## Minimizing the Public API
+
+- Do not add unnecessary `pub`. Keep things private if they do not need to be accessed from outside the module
+- Do not expose internal implementation details (helper functions, intermediate types)
+- Use `pub(crate)` to limit visibility to the minimum necessary
+
+## Consistent Error Handling
+
+- Use the project-wide shared error type (e.g., `AppError`) and convert errors from each layer using `From`
+- `unwrap()` / `expect()` are only permitted in test code or as invariants during initialization. Use the `?` operator in business logic
+- Error messages should include "what happened" and "what was expected"
+- Separate user-facing errors from internal log errors (do not return internal details to the client)
+
+## Naming Appropriateness
+
+- Type names, function names, and variable names should accurately express their intent
+- Avoid abbreviations; use searchable names (`usr` → `user`; `ctx` is conventionally acceptable)
+- Prefix bool variables and functions with `is_`, `has_`, `can_`, etc. to make intent explicit
+- Avoid negative naming (`is_not_empty` → express as the negation of `is_empty`)
+
+## DRY (Don't Repeat Yourself)
+
+- If the same logic appears in two or more places, consider consolidating it
+- However, do not force consolidation for coincidental similarity (code that happens to look the same). Judge by "do they change for the same reason?"
+- Consider consolidation in this order: function extraction, trait extraction, generics — and choose the simplest approach
+
+## YAGNI (You Aren't Gonna Need It)
+
+- Do not preemptively implement features, abstractions, or configuration options that are not currently needed
+- "Might be used in the future" is not a reason to implement something. Add it when it becomes necessary
+- Prioritize concrete, understandable implementations over excessive generalization

package/.claude-plugin/rules/diesel.md

@@ -0,0 +1,176 @@
+---
+paths:
+  - "**/*.rs"
+  - "**/migrations/**"
+  - "**/diesel.toml"
+globs:
+  - "**/Cargo.toml"
+---
+
+# Diesel / diesel-async Best Practices
+
+## Project Structure
+
+- Configure the schema output path in `diesel.toml` (`file = "src/schema.rs"`)
+- Do not manually edit `schema.rs` — it is an auto-generated file
+- Place model definitions in a separate `models/` directory
+- Create migrations with `diesel migration generate`
+
+```
+src/
+├── db/
+│   ├── mod.rs          # DB connection and pool initialization
+│   └── repository/     # Repository layer
+│       ├── mod.rs
+│       └── users.rs
+├── models/
+│   ├── mod.rs
+│   └── user.rs         # Queryable, Insertable, etc.
+├── schema.rs           # Auto-generated (diesel print-schema)
+└── ...
+```
+
+## Model Definitions
+
+- Use `#[derive(Queryable, Selectable)]` for read models
+- Use `#[derive(Insertable)]` for insert models
+- Use `#[derive(AsChangeset)]` for update models
+- Explicitly specify the table with `#[diesel(table_name = ...)]`
+- Use `#[diesel(check_for_backend(Pg))]` to verify backend compatibility at compile time
+
+```rust
+#[derive(Debug, Queryable, Selectable)]
+#[diesel(table_name = users)]
+#[diesel(check_for_backend(Pg))]
+pub struct User {
+    pub id: i64,
+    pub name: String,
+    pub email: Option<String>,
+    pub created_at: NaiveDateTime,
+}
+
+#[derive(Debug, Insertable)]
+#[diesel(table_name = users)]
+pub struct NewUser<'a> {
+    pub name: &'a str,
+    pub email: Option<&'a str>,
+}
+
+#[derive(Debug, AsChangeset)]
+#[diesel(table_name = users)]
+pub struct UpdateUser<'a> {
+    pub name: Option<&'a str>,
+    pub email: Option<Option<&'a str>>,  // Option<Option<T>> controls NULL behavior
+}
+```
+
+## Queries
+
+- Use `.select(Model::as_select())` to select columns in a type-safe manner
+- Chain filters with `.filter()`
+- Implement pagination with `.limit()` + `.offset()`
+- Use `get_result()` to retrieve values after INSERT/UPDATE (PostgreSQL RETURNING)
+- Implement complex queries as repository layer methods
+
+```rust
+// Recommended: type-safe selection with as_select()
+let users: Vec<User> = users::table
+    .filter(users::name.like(format!("%{query}%")))
+    .select(User::as_select())
+    .order(users::created_at.desc())
+    .limit(20)
+    .offset(0)
+    .load(conn)
+    .await?;
+
+// upsert (PostgreSQL)
+diesel::insert_into(users::table)
+    .values(&new_user)
+    .on_conflict(users::email)
+    .do_update()
+    .set(&update_user)
+    .get_result::<User>(conn)
+    .await?;
+```
+
+## diesel-async Connection Pool
+
+- deadpool is recommended (lightweight, simple configuration)
+- Create a pool manager with `AsyncDieselConnectionManager`
+- Store the pool in `AppState` and pass it via Axum's `State` extractor
+- Handle connection acquisition failures with proper error handling
+
+```rust
+use diesel_async::pooled_connection::AsyncDieselConnectionManager;
+use diesel_async::pooled_connection::deadpool::Pool;
+use diesel_async::AsyncPgConnection;
+
+pub type DbPool = Pool<AsyncPgConnection>;
+
+pub fn create_pool(database_url: &str) -> DbPool {
+    let config = AsyncDieselConnectionManager::<AsyncPgConnection>::new(database_url);
+    Pool::builder(config)
+        .build()
+        .expect("Failed to create pool")
+}
+```
+
+## Transactions
+
+- Always use transactions when multiple DB operations must be executed atomically
+- In diesel-async, pass a `scope_boxed()` closure to `connection.transaction()`
+- Errors automatically trigger a rollback
+- Use `test_transaction` in tests to guarantee rollback
+
+```rust
+conn.transaction::<_, diesel::result::Error, _>(|conn| {
+    async move {
+        let user = diesel::insert_into(users::table)
+            .values(&new_user)
+            .get_result::<User>(conn)
+            .await?;
+
+        diesel::insert_into(profiles::table)
+            .values(&NewProfile { user_id: user.id })
+            .execute(conn)
+            .await?;
+
+        Ok(user)
+    }
+    .scope_boxed()
+})
+.await?;
+```
+
+## Migrations
+
+- Create migrations with `diesel migration generate create_users`
+- Always create `up.sql` and `down.sql` as a pair
+- `down.sql` must precisely reverse the operations in `up.sql`
+- Migrations must be idempotent
+- Run `diesel migration run` in the CI/CD pipeline for production environments
+- Make table changes non-destructively (add column → migrate data → drop column)
+
+```sql
+-- up.sql
+CREATE TABLE users (
+    id BIGSERIAL PRIMARY KEY,
+    name VARCHAR(255) NOT NULL,
+    email VARCHAR(255) UNIQUE,
+    created_at TIMESTAMP NOT NULL DEFAULT NOW(),
+    updated_at TIMESTAMP NOT NULL DEFAULT NOW()
+);
+
+CREATE INDEX idx_users_email ON users(email);
+
+-- down.sql
+DROP TABLE users;
+```
+
+## Performance
+
+- Avoid N+1 queries. Fetch related data using JOINs or batch queries
+- Specify only the necessary columns with `.select()`
+- Use `.limit()` + `.offset()` when fetching large amounts of data
+- Perform bulk inserts in a single call with `.values(&vec_of_insertables)`
+- Write queries that can make use of indexes

package/.claude-plugin/rules/feedback-loop.md

@@ -0,0 +1,33 @@
+---
+always_apply: true
+---
+
+# Feedback Loop
+
+## Distinction from Built-in Memory
+
+- **know-how** (`.claude/_docs/know-how/`): Project-specific practical knowledge. Managed under Git and shared with the team. Technical decisions, pitfalls, and best practices.
+- **built-in memory** (`~/.claude/projects/.../memory/`): Personal preferences and working style. Not under Git management.
+
+When in doubt, ask "Should team members know this?" Yes → know-how, No → memory.
+
+## Referencing at Task Start
+
+Before starting a task, check `.claude/_docs/know-how/INDEX.md`, and if there is relevant know-how, Read the corresponding file.
+
+Reference flow:
+1. Check the domain list in INDEX.md
+2. Identify domains that match the task's keywords (e.g., "testing", "migration", "cache")
+3. Reflect the relevant know-how's "checklists" and "counter-examples" in your implementation decisions
+
+If INDEX.md is empty or no matching domain exists, you may skip this step.
+
+## Detecting and Recording Feedback
+
+When any of the following is detected, use the `/knowhow-capture` skill to record know-how:
+
+- The user says something like "remember this" or "from next time, do ~" → Skill Pattern A (record immediately)
+- The user corrects or negates an AI judgment → Skill Pattern B (proposal type)
+- The same feedback has been received two or more times → Skill Pattern B (proposal type)
+
+For recording procedures, format, and rule promotion, follow the `/knowhow-capture` skill.

package/.claude-plugin/rules/leptos.md

@@ -0,0 +1,319 @@
+---
+paths:
+  - "**/*.rs"
+globs:
+  - "**/Cargo.toml"
+---
+
+# Leptos Best Practices
+
+When using a Leptos full-stack configuration, this rule takes precedence over `project-architecture.md`.
+All Diesel, Valkey, and Axum code must be wrapped in `#[cfg(feature = "ssr")]`.
+
+## Project Structure
+
+- In a full-stack configuration, separate compilation targets using `ssr` / `hydrate` / `csr` feature flags
+- Wrap server-only code (Diesel, Valkey, Axum) with `#[cfg(feature = "ssr")]`
+- Use `cargo-leptos` as the build tool
+- Enable the `ssr` feature in rust-analyzer settings
+
+```toml
+[lib]
+crate-type = ["cdylib", "rlib"]
+
+[features]
+csr = ["leptos/csr"]
+hydrate = ["leptos/hydrate"]
+ssr = [
+    "leptos/ssr",
+    "dep:leptos_axum",
+    "dep:axum",
+    "dep:diesel",
+    "dep:diesel-async",
+    "dep:redis",
+    "dep:tokio",
+    "dep:tower",
+    "dep:tower-http",
+]
+```
+
+## Directory Structure (Full-Stack)
+
+```
+src/
+├── lib.rs               # Crate root, branching by feature flag
+├── app.rs               # Leptos App component (Router and Routes definitions)
+├── main.rs              # Entry point (SSR/CSR branching by feature flag)
+├── server/              # Everything under #[cfg(feature = "ssr")]
+│   ├── mod.rs           # Axum server startup
+│   ├── app_state.rs     # AppState definition (DbPool, Valkey, Config)
+│   ├── db/
+│   │   ├── mod.rs       # DB pool initialization
+│   │   └── repository/  # Repository layer
+│   ├── cache/
+│   │   ├── mod.rs       # Valkey connection initialization
+│   │   └── keys.rs
+│   └── middleware/
+│       └── auth.rs
+├── pages/               # Page components (corresponding to routes)
+├── components/          # Reusable UI components
+├── models/              # Diesel models (cfg(feature = "ssr"))
+├── dto/                 # Shared types (used by both server and client)
+├── server_fns/          # #[server] functions
+├── schema.rs            # Diesel auto-generated (cfg(feature = "ssr"))
+└── error_template.rs    # Error display component
+style/
+├── main.css
+migrations/
+└── ...
+```
+
+## Axum Integration (SSR)
+
+- Use `leptos_axum`'s `LeptosRoutes` trait to integrate Leptos routes into the Axum Router
+- Receive server function endpoints at `/api/{*fn_name}`
+- Inject the DB pool and other resources into Leptos context with `provide_context`
+
+```rust
+#[cfg(feature = "ssr")]
+#[tokio::main]
+async fn main() {
+    let routes = generate_route_list(App);
+    let state = AppState { /* db_pool, valkey, leptos_options, routes */ };
+
+    let app = Router::new()
+        .route("/api/{*fn_name}", get(server_fn_handler).post(server_fn_handler))
+        .leptos_routes_with_handler(routes, get(leptos_routes_handler))
+        .fallback(file_and_error_handler)
+        .layer(TraceLayer::new_for_http())
+        .with_state(state);
+
+    let listener = TcpListener::bind(&addr).await?;
+    axum::serve(listener, app)
+        .with_graceful_shutdown(shutdown_signal())
+        .await?;
+}
+```
+
+## Separation by Feature Flag
+
+```rust
+// src/lib.rs
+pub mod app;
+pub mod dto;
+pub mod pages;
+pub mod components;
+pub mod server_fns;
+
+#[cfg(feature = "ssr")]
+pub mod server;
+
+#[cfg(feature = "ssr")]
+pub mod models;
+
+#[cfg(feature = "ssr")]
+pub mod schema;
+```
+
+## Components
+
+- Define components with the `#[component]` macro. Component names must be `UpperCamelCase`
+- Define props as function arguments and control optional values and defaults with the `#[prop]` attribute
+- Keep components small and single-responsibility
+- Place reusable components in the `components/` directory
+
+```rust
+#[component]
+fn UserCard(
+    /// User name
+    name: String,
+    /// Email address (optional)
+    #[prop(optional)]
+    email: Option<String>,
+    /// Avatar size
+    #[prop(default = 48)]
+    avatar_size: u32,
+    /// Click handler
+    #[prop(into)]
+    on_click: Callback<()>,
+) -> impl IntoView {
+    view! {
+        <div class="user-card" on:click=move |_| on_click.run(())>
+            <span>{name}</span>
+            {email.map(|e| view! { <span class="email">{e}</span> })}
+        </div>
+    }
+}
+```
+
+## Signals and the Reactive System
+
+- Create read/write signal pairs with `signal()`
+- Express derived state as closures (`move || ...`). Avoid creating unnecessary signals
+- Use `Memo` for expensive derived computations (avoids recomputation when dependencies have not changed)
+- Share global state with `provide_context` / `use_context`
+- Use `RwSignal` when you want to combine reading and writing into a single value
+
+```rust
+let (count, set_count) = signal(0);
+
+// Derived state: use a closure, not a signal
+let is_even = move || count.get() % 2 == 0;
+let double_count = move || count.get() * 2;
+
+// Use Memo for expensive computations
+let expensive = Memo::new(move |_| heavy_computation(count.get()));
+```
+
+## Conditional Rendering and List Rendering
+
+- Use `move || if ... { ... } else { ... }` for conditional rendering. Unify different types with `.into_any()`
+- Use the keyed `For` component for list rendering
+- Only use `Vec<impl IntoView>` directly for static lists
+
+```rust
+// Conditional rendering
+{move || if is_loading.get() {
+    view! { <p>"Loading..."</p> }.into_any()
+} else {
+    view! { <UserList users=users.get()/> }.into_any()
+}}
+
+// List rendering
+<For
+    each=move || items.get()
+    key=|item| item.id
+    let(item)
+>
+    <ItemRow item=item/>
+</For>
+```
+
+## Server Functions
+
+- Define server-only functions with the `#[server]` macro
+- Use `Result<T, ServerFnError>` as the return type
+- Perform all DB access, authentication, and external API calls inside server functions
+- Use `use_context` inside server functions to obtain the DB pool and other resources
+- Define a custom error type and implement `FromServerFnError`
+
+```rust
+#[server]
+pub async fn get_user(id: i64) -> Result<UserDto, ServerFnError> {
+    use crate::db::repository::users;
+    let pool = use_context::<DbPool>()
+        .ok_or_else(|| ServerFnError::new("No DB pool"))?;
+    let mut conn = pool.get().await
+        .map_err(|e| ServerFnError::new(e.to_string()))?;
+    let user = users::find_by_id(&mut conn, id).await
+        .map_err(|e| ServerFnError::new(e.to_string()))?;
+    Ok(user.into())
+}
+```
+
+## Resources and Async Data
+
+- Fetch server data with `Resource` and display loading states with `Suspense`
+- Declare reactive dependencies in the first argument (source) of `Resource::new`
+- Use `Transition` to reload data in the background while displaying existing content
+
+```rust
+let user_resource = Resource::new(
+    move || user_id.get(),
+    |id| get_user(id),
+);
+
+view! {
+    <Suspense fallback=|| view! { <p>"Loading..."</p> }>
+        {move || Suspend::new(async move {
+            user_resource.await.map(|user| {
+                view! { <UserProfile user=user/> }
+            })
+        })}
+    </Suspense>
+}
+```
+
+## Forms and Actions
+
+- Use `ServerAction` + `ActionForm` to create progressively enhanced forms
+- Forms must work even when JavaScript is disabled
+- Use `action.value()` to get the latest result and `action.pending()` to get the loading state
+
+```rust
+let create_user = ServerAction::<CreateUser>::new();
+
+view! {
+    <ActionForm action=create_user>
+        <input type="text" name="name" required/>
+        <input type="email" name="email"/>
+        <button type="submit" disabled=move || create_user.pending().get()>
+            "Create"
+        </button>
+    </ActionForm>
+}
+```
+
+## Routing
+
+- Configure client-side routing with `leptos_router`
+- Define routes with `<Routes>` + `<Route>`
+- Define path parameters with `path!("/users/:id")` and retrieve them with `use_params`
+- Choose an SSR mode from `ssr=SsrMode::OutOfOrder` (default), `PartiallyBlocked`, or `Async`
+
+```rust
+view! {
+    <Router>
+        <nav>
+            <A href="/">"Home"</A>
+            <A href="/users">"Users"</A>
+        </nav>
+        <main>
+            <Routes fallback=|| view! { <p>"Not Found"</p> }>
+                <Route path=path!("/") view=HomePage/>
+                <Route path=path!("/users") view=UsersPage/>
+                <Route path=path!("/users/:id") view=UserDetailPage/>
+            </Routes>
+        </main>
+    </Router>
+}
+```
+
+## Error Handling
+
+- Use the `ErrorBoundary` component to catch errors from child components
+- Propagate server function errors via `Result` and handle them on the UI side with `match`
+- Separate user-facing error messages from detailed internal error logs
+
+## Styling
+
+- Toggle classes dynamically with `class:name=signal`
+- Set inline styles dynamically with `style:property=signal`
+- Specify CSS files via `style-file` in `[package.metadata.leptos]` in `Cargo.toml`
+
+## Build Verification
+
+In a Leptos full-stack project, `cargo build` and `cargo test` only compile for the **host target** (SSR). WASM frontend code is not compiled or verified by these commands. You **must** run:
+
+```bash
+cargo leptos build
+```
+
+This command builds both SSR and WASM targets. Common WASM-only compilation errors include:
+- Using `std::fs`, `std::net`, or other APIs unavailable in `wasm32-unknown-unknown`
+- Calling `tokio::spawn` or other runtime-specific code outside `#[cfg(feature = "ssr")]`
+- Missing `#[cfg(feature = "ssr")]` guards on server-only dependencies
+
+### TDD with Leptos
+
+- `cargo test` runs tests for the SSR target only. This is sufficient for server functions and repository logic
+- Component rendering tests use `leptos::mount_to` in `#[cfg(test)]` blocks
+- After Green phase in TDD, always run `cargo leptos build` to verify WASM compilation before proceeding to Refactor
+- WASM compilation failure after Green is a signal that `#[cfg(feature = "ssr")]` guards are missing
+
+## Performance
+
+- Keep signal granularity fine. Avoid wrapping large structs in a single signal
+- Use `Memo` to prevent unnecessary recomputation
+- Set keys correctly on the `For` component to minimize list re-rendering
+- Use `Suspense` to isolate async data loading and reduce rendering blocks