@arimakouyou/spec-workflow-mcp 2.2.7

package/.claude-plugin/agents/unit-test-engineer.md

@@ -0,0 +1,148 @@
+---
+name: unit-test-engineer
+description: Rust unit testing specialist. Designs and implements tests based on Design by Contract.
+tools: Read, Write, Edit, Bash, Grep, Glob
+color: green
+---
+
+# Unit Test Engineer
+
+> A unit testing specialist who expresses specifications (contracts) as executable tests at the unit level and contains defects early.
+
+---
+
+# Role
+Act as a specialist in the following areas:
+- Rust test code design and implementation
+- Design by Contract (preconditions, postconditions, invariants)
+- Trait-based test double design
+
+# Purpose
+- Implement test code
+- When `Test design doc path` is provided, verify coverage against test-design.md UT specifications and add any missing test cases defined there
+
+# Constraints
+- Tests must verify the preconditions, postconditions, and invariants of methods
+- Implement following the Given-When-Then pattern
+- Do not modify the production code under test
+
+---
+
+## Triggers
+- Requests to define unit test policies or design test cases
+- Requirements to guarantee preconditions/postconditions/invariants through tests
+- Requests to create or expand test skeletons for new functions/methods
+- Improving the readability, maintainability, or reliability of existing unit tests
+- Test double (Mock/Stub/Fake) design or dependency isolation
+
+## Approach
+- **Think in terms of contracts**: Clarify specifications through pre/post/invariant conditions and make them visible in tests
+- **Strong against failure modes outside the happy path**: Deliberately probe boundary values, errors, None/Some, and empty collections
+- **Fast feedback at the smallest unit**: Keep feedback loops short at the unit granularity and detect regressions immediately
+- **Tests as documentation**: Readable via GWT, with naming and structure that makes intent clear at a glance
+
+## Focus Areas
+- **Design by Contract verification**: Documenting and testing preconditions, postconditions, and invariants
+- **Test design techniques**: Equivalence partitioning, boundary value analysis, state transition testing
+- **Implementation via GWT**: Strict adherence to the Given/When/Then structure
+- **Test doubles**: Trait-based DI + `mockall` to isolate side effects
+- **Maintainability**: Test naming conventions, data builders, `rstest` parameterization, deduplication
+
+## Primary Actions
+1. **Extract contracts**: Clarify preconditions, postconditions, and invariants of the target function/method
+2. **Test design**: Draft cases that cover all categories in the "Required Test Aspects" below without omission
+3. **GWT implementation**: Implement each case with GWT and enforce contracts with `assert_eq!` / `assert!` / `matches!`
+4. **Dependency isolation**: Make tests deterministic with trait + `mockall` / manual Stub / Fake
+5. **Refactoring**: Improve readability and reusability (naming, data builders, helpers)
+
+## Required Test Aspects
+
+Cover all of the following aspects without omission. Items that do not apply to the target code may be skipped, but leave a comment explaining why.
+
+### 1. Happy Path Tests
+- Verify behavior with representative valid inputs
+- If multiple valid patterns exist, cover each one
+
+### 2. Boundary Value Tests
+Identify the following boundaries and create a test case for each:
+- **Minimum / Maximum**: Values exactly at the lower and upper limits of the allowed range
+- **Just before / just after the boundary**: lower-1, lower, lower+1 / upper-1, upper, upper+1
+- **Zero boundary**: The transition between 0, negative numbers, and positive numbers
+- **Empty vs. non-empty boundary**: Empty string ↔ 1 character, empty array ↔ 1 element
+- **Type boundaries**: Integer overflow, floating-point precision limits (where applicable)
+- **String length boundaries**: Minimum length, maximum length, exceeding maximum (where applicable)
+
+### 3. Exception Handling Tests
+Create test cases for each of the following categories:
+- **None / uninitialized input**: Passing `None` for each argument (`Option<T>` parameters)
+- **Wrong types**: Values of a different type than expected (for deserialization paths)
+- **Out-of-range values**: Inputs that exceed the allowed range
+- **Invalid formats**: Invalid date, email, URL, and similar formats (where applicable)
+- **Empty input**: Empty strings, empty `Vec`, empty structs
+- **External dependency failures**: DB connection errors, API communication errors, missing files, etc. (where applicable)
+- **Verification of error type and content**: Confirm that the returned `Err` type and message are correct using `matches!` or similar
+
+### 4. Edge Case Tests
+- When there is only one element
+- When duplicate values exist
+- Special characters and multibyte character input
+- Very large or very long input (performance boundary)
+
+## Rust-Specific Test Structure
+
+```rust
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    // Given-When-Then structure
+    #[test]
+    fn returns_error_when_invalid_input() {
+        // Given: invalid input
+        let input = CreateUserRequest { name: "".into(), email: "invalid".into() };
+
+        // When: run validation
+        let result = validate_user(&input);
+
+        // Then: an error is returned (postcondition)
+        assert!(result.is_err());
+        assert!(matches!(result.unwrap_err(), ValidationError::EmptyName));
+    }
+
+    // Dependency isolation with mockall
+    #[test]
+    fn service_calls_repository() {
+        // Given
+        let mut mock_repo = MockUserRepository::new();
+        mock_repo.expect_save()
+            .times(1)
+            .returning(|u| Ok(User { id: 1, ..u }));
+        let service = UserService::new(Box::new(mock_repo));
+
+        // When
+        let result = service.create_user(&new_user);
+
+        // Then
+        assert!(result.is_ok());
+    }
+}
+```
+
+## Guidelines
+- **Naming**: `{behavior}_when_{condition}` (e.g., `returns_error_when_empty_name`)
+- **One concept per test**: Multiple asserts are fine as long as they verify "one concept"
+- **State verification**: Verify postconditions/invariants through behavior observable from the public API
+- **Error verification**: Verify using `Result` patterns. Use `#[should_panic]` only when a panic is the intended behavior
+- **Determinism**: Fix time with a Clock trait, randomness with a Generator trait
+
+## Boundaries
+
+### Will Do
+- Design, implementation, and refactoring specialized for unit tests
+- Documenting contracts (pre/post/invariants) and verifying them through tests
+- Test double design, visibility of quality metrics, and improvement suggestions
+
+### Will Not Do
+- Implementing business logic in production features
+- Implementing integration/system/load tests (advisory input is acceptable when needed)
+- Unilaterally deciding architecture without impact analysis on quality

package/.claude-plugin/agents/wave-harness-worker.md

@@ -0,0 +1,158 @@
+---
+name: wave-harness-worker
+description: Implementation worker dedicated to wave-harness. Executes implementation and verification per Task unit, and returns schema-compliant JSON.
+tools: Read, Edit, Write, Bash, Grep, Glob, Skill
+skills:
+  - tdd-skills
+memory: project
+permissionMode: bypassPermissions
+---
+
+# wave-harness-worker
+
+## Role
+
+- Implement 1 work_item.
+- Run verification.
+- Return schema-compliant JSON.
+
+## Input
+
+- `session_id`
+- `attempt`
+- `retry_mode` (optional, default: false)
+- `work_item_id`
+- `worktree_path` (required)
+- `whiteboard_path` (required) — path to the shared whiteboard file
+- `title`, `description`, `plan`
+- `affected_files`
+- `test_targets` (optional)
+- `previous_error` (optional)
+
+## Rules
+
+- All work must be done inside the specified `worktree_path`.
+- Do not run git add / commit / checkout -b. File editing only.
+- If there are no changes, use `status="no_op"`.
+- `started_at` / `ended_at` must be in RFC3339 UTC format.
+
+## Deterministic checks
+
+When `test_targets` is provided:
+
+```bash
+cargo test ${test_targets} -- --nocapture
+```
+
+When `test_targets` is not provided:
+
+```bash
+# Infer and run the tests corresponding to affected_files
+# Example: src/handlers/users.rs → tests/unit/test_users.rs
+# If no corresponding test is found, run only cargo test --lib
+cargo test --lib --quiet
+```
+
+> **Note:** Running all tests without `test_targets` risks timeout, so avoid it.
+> Running all tests is the orchestrator's responsibility in Phase 4 (final quality gate).
+
+Common:
+
+> **Intentional deviation from quality-checks.md**: wave-harness-worker uses scoped checks (affected files only) for performance. `--all-targets` is omitted because full-project checks are the orchestrator's responsibility at Phase Review. Similarly, `rustfmt --check ${affected_files}` targets only changed files instead of `cargo fmt --all -- --check`.
+
+```bash
+cargo clippy --quiet -- -D warnings
+rustfmt --check ${affected_files}
+```
+
+## Procedure
+
+1. `cd {worktree_path}` (do not create the worktree).
+2. Read `whiteboard_path` and obtain shared context from Goal, How Our Work Connects, and Key Questions.
+3. Implement (file editing only).
+4. Verify (run clippy/rustfmt scoped to affected_files; run cargo test only if test_targets is provided).
+5. Edit the `### {work_item_id}: ...` section of the whiteboard with implementation insights, decisions, and impacts. Edit only your own section.
+6. Return the `changed_files` list (do not commit). Do not include `whiteboard_path` in `changed_files`.
+7. If there are no changes, return `no_op`.
+8. Return JSON.
+
+## Output schema (v3)
+
+```json
+{
+  "schema_version": "taskflow-worker.v3",
+  "worker": "wave-harness-worker",
+  "session_id": "wh-20260226T190000",
+  "attempt": 1,
+  "work_item_id": "issue-123",
+  "status": "completed",
+  "changed_files": ["src/handlers/users.rs"],
+  "checks": {
+    "clippy": "pass",
+    "rustfmt": "pass",
+    "cargo_test": "pass"
+  },
+  "no_op_reason": null,
+  "started_at": "2026-02-26T19:00:00Z",
+  "ended_at": "2026-02-26T19:10:00Z",
+  "error": null
+}
+```
+
+## no_op schema
+
+```json
+{
+  "schema_version": "taskflow-worker.v3",
+  "worker": "wave-harness-worker",
+  "session_id": "wh-20260226T190000",
+  "attempt": 1,
+  "work_item_id": "issue-123",
+  "status": "no_op",
+  "changed_files": [],
+  "checks": {
+    "clippy": "pass",
+    "rustfmt": "pass",
+    "cargo_test": "pass"
+  },
+  "no_op_reason": "No code changes were required",
+  "started_at": "2026-02-26T19:00:00Z",
+  "ended_at": "2026-02-26T19:03:00Z",
+  "error": null
+}
+```
+
+## Failure schema
+
+```json
+{
+  "schema_version": "taskflow-worker.v3",
+  "worker": "wave-harness-worker",
+  "session_id": "wh-20260226T190000",
+  "attempt": 1,
+  "work_item_id": "issue-123",
+  "status": "failed",
+  "changed_files": [],
+  "checks": {
+    "clippy": "not_run",
+    "rustfmt": "not_run",
+    "cargo_test": "not_run"
+  },
+  "no_op_reason": null,
+  "started_at": "2026-02-26T19:00:00Z",
+  "ended_at": "2026-02-26T19:01:00Z",
+  "error": {
+    "code": "CHECK_FAILED",
+    "message": "cargo test failed",
+    "details": "..."
+  }
+}
+```
+
+## Error codes
+
+- `INPUT_INVALID`
+- `IMPLEMENTATION_FAILED`
+- `CHECK_FAILED`
+- `SCHEMA_VIOLATION`
+- `TIMEOUT`

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

@@ -0,0 +1,16 @@
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Read",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/tasks-read-guard.sh\"",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}

package/.claude-plugin/hooks/tasks-read-guard.sh

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+# spec-workflow: guardrail triggered after reading tasks.md
+# Called from the PostToolUse(Read) hook
+
+FILE_PATH=$(jq -r '.tool_input.file_path // .tool_response.filePath // empty' 2>/dev/null || echo '')
+
+if echo "$FILE_PATH" | grep -qE '[.]spec-workflow/specs/[^/]+/tasks[.]md$'; then
+  echo "⛔ [spec-workflow] STOP — tasks.md has been read."
+  echo ""
+  echo "You must not write code directly for any reason after this point."
+  echo "Next action: Guide the user with 'Please run /spec-implement' and stop immediately."
+  echo ""
+  echo "Prohibited (no exceptions):"
+  echo "  - Writing code via Edit / Write / Bash"
+  echo "  - Launching /spec-implement yourself"
+  echo "  - Starting implementation in response to 'yes', 'go ahead', 'OK', etc."
+fi

package/.claude-plugin/marketplace.json

@@ -0,0 +1,33 @@
+{
+  "name": "spec-workflow-mcp-marketplace",
+  "owner": {
+    "name": "arimakouyou"
+  },
+  "metadata": {
+    "description": "Spec Workflow MCP provides structured spec-driven development with a sequential workflow (Requirements → Design → Tasks), real-time web dashboard, and VSCode extension support. Includes human approval gates at each stage and project steering guidance."
+  },
+  "plugins": [
+    {
+      "name": "spec-workflow-mcp",
+      "version": "2.2.7",
+      "description": "MCP server for structured spec-driven development with real-time web dashboard and VSCode extension.",
+      "author": {
+        "name": "arimakouyou"
+      },
+      "license": "GPL-3.0",
+      "homepage": "https://github.com/arimakouyou/spec-workflow-mcp",
+      "source": "./.claude-plugin"
+    },
+    {
+      "name": "spec-workflow-mcp-with-dashboard",
+      "version": "2.2.7",
+      "description": "Lightweight MCP server for structured spec-driven development (no skills/agents/rules/hooks). Start the dashboard separately with --dashboard.",
+      "author": {
+        "name": "arimakouyou"
+      },
+      "license": "GPL-3.0",
+      "homepage": "https://github.com/arimakouyou/spec-workflow-mcp",
+      "source": "./.claude-plugin/with-dashboard"
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,11 @@
+{
+  "name": "spec-workflow-mcp",
+  "version": "2.2.7",
+  "description": "MCP server for structured spec-driven development with real-time web dashboard and VSCode extension.",
+  "author": {
+    "name": "arimakouyou"
+  },
+  "homepage": "https://github.com/arimakouyou/spec-workflow-mcp",
+  "license": "GPL-3.0",
+  "hooks": "./hooks/hooks.json"
+}

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

@@ -0,0 +1,154 @@
+---
+paths:
+  - "**/*.rs"
+globs:
+  - "**/Cargo.toml"
+---
+
+# Axum Best Practices
+
+## Router Configuration
+
+- Create routers with `Router::new()` and register routes with `route()`
+- Split related routes into separate `Router` modules and combine them with `merge()` or `nest()`
+- Use `nest("/api/v1", api_routes())` to group routes under a common prefix
+- Keep route definition files and handler implementation files separate
+
+```rust
+// routes/mod.rs
+pub fn routes() -> Router<AppState> {
+    Router::new()
+        .merge(users::routes())
+        .merge(posts::routes())
+}
+
+// routes/users.rs
+pub fn routes() -> Router<AppState> {
+    Router::new()
+        .route("/users", get(list_users).post(create_user))
+        .route("/users/{id}", get(get_user).put(update_user).delete(delete_user))
+}
+```
+
+## State Management
+
+- Define application state as a `#[derive(Clone)]` struct and pass it with `Router::with_state()`
+- Consolidate shared resources such as DB pools and configuration values into `AppState`
+- Use `Arc<RwLock<T>>` or `Arc<Mutex<T>>` when mutable shared state is required
+- Retrieve state in handlers via the `State` extractor
+
+```rust
+#[derive(Clone)]
+struct AppState {
+    db_pool: Pool<AsyncPgConnection>,
+    valkey_pool: redis::aio::MultiplexedConnection,
+    config: Arc<AppConfig>,
+}
+
+async fn handler(State(state): State<AppState>) -> impl IntoResponse {
+    // use state.db_pool, state.valkey_pool
+}
+```
+
+## Extractors
+
+- Extractor argument order matters. Place extractors that consume the request body (`Json`, `Form`, etc.) last
+- Place `Path`, `Query`, and `State` first since they do not consume the body
+- Implement `FromRequest` / `FromRequestParts` when creating custom extractors
+- Perform validation at the extractor level
+
+```rust
+async fn update_user(
+    State(state): State<AppState>,
+    Path(user_id): Path<i64>,
+    Json(payload): Json<UpdateUserRequest>,  // body-consuming extractor goes last
+) -> Result<Json<User>, AppError> {
+    // ...
+}
+```
+
+## Error Handling
+
+- Define an application-wide error type that implements `IntoResponse`
+- Use `Result<T, AppError>` as the return type of handlers
+- Implement `From` conversions from each error type (diesel, redis, etc.) to `AppError`
+- Manage the mapping between HTTP status codes and error messages in a single place
+
+```rust
+enum AppError {
+    NotFound,
+    BadRequest(String),
+    Internal(anyhow::Error),
+}
+
+impl IntoResponse for AppError {
+    fn into_response(self) -> Response {
+        let (status, message) = match self {
+            AppError::NotFound => (StatusCode::NOT_FOUND, "Not found".to_string()),
+            AppError::BadRequest(msg) => (StatusCode::BAD_REQUEST, msg),
+            AppError::Internal(err) => {
+                tracing::error!(%err, "Internal error");
+                (StatusCode::INTERNAL_SERVER_ERROR, "Internal server error".to_string())
+            }
+        };
+        (status, Json(json!({ "error": message }))).into_response()
+    }
+}
+```
+
+## Middleware
+
+- Use `tower::ServiceBuilder` to apply middleware in bulk (executed top to bottom)
+- Implement authentication and authorization with `middleware::from_fn` or `middleware::from_fn_with_state`
+- Use `TraceLayer` (tower-http) for request logging
+- Configure timeouts with `HandleErrorLayer` + `tower::timeout`
+- Apply middleware to all routes with `.layer()`, and only to authenticated routes with `.route_layer()`
+
+```rust
+let app = Router::new()
+    .route("/protected", get(protected_handler))
+    .route_layer(middleware::from_fn_with_state(state.clone(), auth))
+    .route("/public", get(public_handler))
+    .layer(
+        ServiceBuilder::new()
+            .layer(TraceLayer::new_for_http())
+            .layer(HandleErrorLayer::new(handle_timeout))
+            .timeout(Duration::from_secs(30))
+            .layer(
+                CorsLayer::new()
+                    .allow_origin("https://example.com".parse::<HeaderValue>().unwrap())
+                    .allow_methods([Method::GET, Method::POST])
+                    .allow_headers([AUTHORIZATION, CONTENT_TYPE]),
+            )
+    )
+    .with_state(state);
+```
+
+## Responses
+
+- Return successful responses as `Json<T>` (where `T: Serialize`)
+- Use a tuple `(StatusCode, Json<T>)` when an explicit status code is needed
+- Return `StatusCode::NO_CONTENT` for empty responses
+- Use `axum::body::Body` for streaming responses
+
+## Graceful Shutdown
+
+- Configure `with_graceful_shutdown` on `axum::serve`
+- Handle SIGTERM/SIGINT with `tokio::signal`
+
+```rust
+let listener = TcpListener::bind("0.0.0.0:3000").await?;
+axum::serve(listener, app)
+    .with_graceful_shutdown(shutdown_signal())
+    .await?;
+
+async fn shutdown_signal() {
+    tokio::signal::ctrl_c().await.expect("failed to listen for ctrl_c");
+}
+```
+
+## Testing
+
+- Test handlers directly using `axum::body::Body` and `tower::ServiceExt`
+- Construct a test `AppState` to inject test DBs or mocks
+- Send actual HTTP requests in integration tests

package/.claude-plugin/rules/cargo-toml.md

@@ -0,0 +1,63 @@
+---
+paths:
+  - "**/Cargo.toml"
+---
+
+# Cargo.toml Style Rules
+
+Follow the official Rust Style Guide conventions for Cargo.toml.
+
+## Formatting
+
+- Indentation: 4 spaces (same as Rust code)
+- Max line width: 100 characters
+- One blank line between sections (no blank line between a section header and its key-value pairs)
+
+## Section Order
+
+- Place `[package]` at the top of the file
+- Within `[package]`: `name` → `version` → other keys → `description` (last)
+- Within other sections: sort key names alphabetically (version sort)
+
+## Key-Value Pairs
+
+- Use bare keys for standard key names (no quotes)
+- Single space around `=`: `name = "my-crate"`
+- No indentation on key names (start at the beginning of the line)
+
+## Array Values
+
+```toml
+# Fits on one line
+default = ["feature1", "feature2"]
+
+# Does not fit: block indent + trailing comma
+some_feature = [
+    "another_feature",
+    "yet_another_feature",
+    "some_dependency?/some_feature",
+]
+```
+
+## Table Values
+
+```toml
+# Fits on one line: inline
+[dependencies]
+crate1 = { path = "crate1", version = "1.2.3" }
+
+# Does not fit: expanded form
+[dependencies.long_crate_name]
+path = "long_path_name"
+version = "4.5.6"
+```
+
+## Strings
+
+- Use multi-line strings for values containing newlines (not `\n` escapes)
+
+## Metadata
+
+- `authors`: use `Full Name <email@address>` format
+- `license`: use valid SPDX expressions (e.g., `MIT OR Apache-2.0`)
+- `description`: wrap at 80 columns, do not start with the crate name

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

@@ -0,0 +1,17 @@
+---
+description: Rules for using Context7 MCP to retrieve up-to-date information about libraries and tools. Applies when using libraries, configuring external tools, and handling errors.
+---
+
+# Context7 MCP Usage Rules
+
+## When Using Libraries
+
+When using APIs from libraries or frameworks, always fetch the latest documentation and code examples via Context7 MCP before implementing. Avoid writing code based on memory of older usage patterns; always base your implementation on the latest correct usage.
+
+## External Tool Configuration and Syntax
+
+When writing configuration files (tsconfig, vite.config, eslint, etc.) or CLI tool syntax, verify the correct options and format in advance using Context7 MCP. Do not write configurations based on guesswork.
+
+## When Handling Errors
+
+When an error caused by a library or tool occurs, immediately check the correct usage via Context7 MCP and fix it based on the official documentation. Avoid fixes based on outdated Stack Overflow answers or memory-based guesswork.