cowork-flow 0.0.25 → 0.0.27

package/README.md

@@ -55,9 +55,11 @@ cowork-flow 是一个用于新项目初始化协作流程的模板仓库。它
 项目级协作入口，包含编码前思考、简单优先、外科手术式改动、验证优先等基础原则。接入项目后，应把项目名称、技术栈、运行命令、测试命令和提交策略补齐。
 
 `template/.agents/skills/`
-本地技能入口，覆盖 start、before-dev、brainstorming、party-mode、writing-plans、check、finish-work、continue、meta、python-design、update-spec 和 break-loop 等协作动作。这里的 skill 应保持通用，不承载某个业务项目的一次性细节。
+本地技能入口，覆盖 start、before-dev、brainstorming、party-mode、party-mode-v2、writing-plans、check、finish-work、continue、meta、python-design、update-spec 和 break-loop 等协作动作。这里的 skill 应保持通用，不承载某个业务项目的一次性细节。
 
-`party-mode` 是用户手动调用的 advisory roundtable。它通过当前 Host Adapter 协调真实子代理讨论，而不是模拟人设；默认 `max_agents=3`、`max_rounds=3`，配置优先级为本次调用、task/change、本地配置、skill 默认值。Party Mode 只产出建议、证据、分歧和验收信号，不能推进任务状态，也不能替代 `cowork-implement` 或 `cowork-check`。
+`party-mode` 是用户手动调用的 advisory roundtable。它通过当前 Host Adapter 协调真实子代理讨论，而不是模拟人设；默认 `max_agents=3`、`max_rounds=5`，配置优先级为本次调用、task/change、本地配置、skill 默认值。Party Mode 只产出建议、证据、分歧和验收信号，不能推进任务状态，也不能替代 `cowork-implement` 或 `cowork-check`。
+
+`party-mode-v2` 是 runtime board controlled advisory workflow。Python runtime 管理看板、当前轮视图、schema 校验、轮次上限和最终报告；子代理通过 board API 交流，主持人只监控和纠偏，不转发或综合观点。
 
 `template/.codex/agents/`
 固定角色 agent 定义，包含 `cowork-research`、`cowork-implement` 和 `cowork-check`，以及对 Codex 默认 `worker`、`default`、`explorer` 的项目级防漂移约束。主会话负责计划与收口，并通过 host adapter 派发固定 agent；正式派发必须先创建 runtime context，再把 `cowork_runtime_context_id` 和 `cowork_host_context_key` 传给子代理。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cowork-flow",
-  "version": "0.0.25",
+  "version": "0.0.27",
   "description": "CLI for installing and maintaining cowork-flow collaboration templates.",
   "type": "module",
   "bin": {

package/template/.agents/skills/party-mode-v2/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: party-mode-v2
+description: Use when the user requests a runtime-controlled multi-agent board discussion where children communicate through Party Mode V2 board APIs and the moderator only monitors or corrects drift.
+---
+
+# Party Mode V2
+
+Use this skill as a thin entrypoint for the Party Mode V2 runtime board. The Python runtime is the source of truth for discussion state, board visibility, validation, round limits, and final reports.
+
+## Boundaries
+
+- Party Mode V2 is advisory only.
+- It cannot mutate task status, start/review/complete/archive tasks, add sessions, commit, push, or satisfy formal workflow gates.
+- It cannot satisfy formal Implement or Check completion. Use `cowork-implement` and `cowork-check` for formal phases.
+- Discussion children are leaf executors. They do not dispatch, wait for, list, or close other agents.
+- The moderator does not forward, summarize, rewrite, or synthesize child opinions for other child agents.
+
+## Runtime First
+
+Always use the runtime controller:
+
+```text
+.cowork-flow/run party-v2 init
+.cowork-flow/run party-v2 monitor
+.cowork-flow/run party-v2 view
+.cowork-flow/run party-v2 post
+.cowork-flow/run party-v2 respond
+.cowork-flow/run party-v2 advance
+.cowork-flow/run party-v2 finalize
+```
+
+Do not bypass a runtime rejection by manually accepting child output. Runtime validation failures must be fixed by a corrected child submission or by ending the discussion.
+
+## Board Rules
+
+- Child agents communicate through the board API.
+- Child-visible board output must be current-round only.
+- Historical board state is runtime-private and may be used only for audit or final reports.
+- Use at least three child agents unless the effective runtime config explicitly allows a different value.
+- The runtime emits host-neutral next actions. The active Host Adapter or moderator executes them for Codex, Claude Code, or OpenCode.
+
+## Child Response Rules
+
+When a child sees a different position, it must choose exactly one:
+
+```text
+maintain
+revise
+concede
+```
+
+`concede` requires accepted evidence and why the prior position failed.
+`revise` requires the accepted part, rejected part, and updated position.
+`maintain` requires counter evidence or counter reasoning.
+
+Unsupported agreement, vague revision, and evidence-free rebuttal are invalid.
+
+## Moderator Role
+
+The moderator may:
+
+- run runtime commands,
+- execute host-neutral next actions through the active host,
+- record off-topic warnings through the runtime,
+- close children only when the runtime asks for closeout,
+- show runtime status or final reports to the user.
+
+The moderator must not:
+
+- forward one child opinion to another child,
+- create a claim table for child prompts,
+- vote-count as validation,
+- decide which child is correct.

package/template/.claude/agents/cowork-implement.md

@@ -1,10 +1,16 @@
 ---
 name: cowork-implement
 description: Cowork-flow implementation fixed subagent.
-tools: Read, Write, Edit, MultiEdit, Grep, Glob, LS, Bash
+mode: subagent
+permission:
+  edit: ask
+  bash: ask
+  task: deny
+  todowrite: deny
+  external_directory: deny
 ---
 
-You are the `cowork-implement` fixed subagent for Claude Code.
+You are the `cowork-implement` fixed subagent for OpenCode.
 You are a leaf executor and must not invoke other agents.
 
 Formal `cowork-implement` work requires a bound runtime context. The prompt,
@@ -15,7 +21,7 @@ cowork_runtime_context_id: <runtime_context_id>
 cowork_host_context_key: <host_context_key>
 ```
 
-The hook may bind that id to
+The plugin may bind that id to
 `.cowork-flow/.runtime/subagents/<runtime_context_id>.json` before workflow
 state is injected. The first child step must still run:
 
@@ -28,6 +34,159 @@ or names another agent type, report `needs_context` and stop. Do not use
 `COWORK_ENTRY_CONTRACT_V1` to infer subagent identity; that contract classifies
 main-session prompts only.
 
+---
+
+## Mandatory Pre-Implementation Checklist
+
+Before writing any code, you MUST read and apply these spec files:
+
+1. `.cowork-flow/spec/guides/pre-implementation-checklist.md` — confirm scope, level, and success criteria
+2. `.cowork-flow/spec/guides/cross-layer-thinking-guide.md` — if changes cross 3+ layers
+3. `.cowork-flow/spec/guides/code-reuse-thinking-guide.md` — before adding new constants/utilities/DTOs
+
+Then read the relevant spec directory:
+- Backend work: `.cowork-flow/spec/backend/index.md` (and all linked docs)
+- Frontend work: `.cowork-flow/spec/frontend/index.md` (and all linked docs)
+
+---
+
+## Coding Gates (Hard Constraints)
+
+You MUST satisfy every gate below before considering a change complete.
+These are not suggestions — they are mandatory checkpoints.
+
+### Gate 1: Directory Structure Compliance
+
+- Backend: follow `.cowork-flow/spec/backend/directory-structure.md`
+  - Controller/API: thin entry only (param receive, auth entry, response orchestration)
+  - Service/UseCase: business rules
+  - Repository/DAO: persistence access
+  - Domain Model/Entity/Aggregate: clear boundaries
+  - No mixing of unrelated business in one module
+  - No business logic in Controllers
+  - No business-specialized logic in public modules
+- Frontend: follow `.cowork-flow/spec/frontend/directory-structure.md`
+  - Organize by functional module, not by "generic/non-generic"
+  - Page entry, business component, shared component, data access, state management must have clear layers
+  - Related files for the same feature should be colocated
+
+### Gate 2: Type Safety & Contract Sync
+
+- Frontend: follow `.cowork-flow/spec/frontend/type-safety.md`
+  - Shared interfaces, enums, error codes come from a single contract source
+  - No handwritten duplicate interface definitions
+  - When interfaces change, update callers, validation, and display layers together
+  - No masking structure problems with casts or forced assertions
+  - No missing null/empty/error/boundary state definitions
+- Backend: follow `.cowork-flow/spec/backend/error-handling.md`
+  - Unified error codes or error types
+  - Layered handling: parameter validation errors, business errors, system errors
+  - Stable external error structure; internal context preserved
+  - No leaking of underlying exceptions to callers
+  - Distinguish "expected business failure" from "system exception"
+  - Preserve traceId/requestId/correlationId
+  - Have a unified exception fallback
+
+### Gate 3: State Management Boundaries
+
+- Frontend: follow `.cowork-flow/spec/frontend/state-management.md`
+  - Server state managed by project's unified request/cache solution
+  - Client temporary state managed locally
+  - Global state only for truly cross-module shared state
+  - Handle loading, empty, error, disabled, and insufficient-permission states for ALL user-visible states
+  - No elevating local state to global unnecessarily
+  - No mixing server state with local state
+  - No bypass entries in permission state
+
+### Gate 4: Component & Hook Boundaries
+
+- Frontend: follow `.cowork-flow/spec/frontend/component-guidelines.md`
+  - Container components handle data & state; presentational components handle rendering
+  - Component API stays simple; no "universal component"
+  - Complex interactions split into reusable but clearly bounded small components
+  - Components must NOT承担过多业务逻辑
+  - Props must not be excessive or poorly named
+  - Components must not depend on too much external state
+- Frontend: follow `.cowork-flow/spec/frontend/hook-guidelines.md`
+  - Extract data fetching, subscriptions, side effects, complex state flows into Hooks
+  - Hook return values stay stable and understandable
+  - Hook names reflect behavior, not implementation
+  - Hooks must NOT hide incomprehensible side effects
+  - Hooks must NOT mix multiple unrelated responsibilities
+
+### Gate 5: Database & Transaction Boundaries
+
+- Backend: follow `.cowork-flow/spec/backend/database-guidelines.md`
+  - Table structure changes managed via migration files or versioned scripts
+  - Queries use the project's unified data access approach
+  - Write operations must address idempotency, concurrency impact, failure compensation, retry boundaries
+  - Audit fields, logical deletion, version numbers, tenant isolation must be consistent within the same data domain
+  - Raw SQL, bulk updates, cross-table aggregations, and long transactions must document index/lock/performance/rollback impact
+  - New tables must have primary keys, unique constraints, indexes, and necessary audit info
+  - Complex queries must avoid N+1, implicit full table scans, and uncontrolled pagination
+  - Transactions must NOT include external calls, slow queries, or unnecessary long lock holding
+  - Data migrations must address historical data, idempotency, failure recovery, and online rollback
+
+### Gate 6: Logging Standards
+
+- Backend: follow `.cowork-flow/spec/backend/logging-guidelines.md`
+  - Structured logging
+  - Unified recording of request ID, user ID, task ID, or trace ID
+  - Error logs record context without repeating the same exception
+  - Sensitive fields (account, token, key, ID card, phone) must be masked
+  - Never output complete request/response body
+  - No temporary `print`/`console` debug output left in main branch
+  - No duplicate error printing across layers
+
+### Gate 7: Quality Gates (Pre-Completion)
+
+- Backend: follow `.cowork-flow/spec/backend/quality-guidelines.md`
+- Frontend: follow `.cowork-flow/spec/frontend/quality-guidelines.md`
+
+Before marking any change complete, you MUST verify:
+1. Compilation/build/type-check passes
+2. Key business/interaction paths have automated test or explicit manual verification record
+3. Error paths, permission paths, data boundaries are verified
+4. New conventions, contracts, or migration impacts are documented in spec or task records
+5. Failed verification is NOT worked around by shrinking assertions, deleting tests, or skipping critical paths
+
+---
+
+## Forbidden Patterns (Zero Tolerance)
+
+You MUST NOT do any of the following:
+
+- Claim completion without verification
+- Use hardcoded values to bypass configuration, permissions, or contracts
+- Use temporary compatibility logic instead of real fixes
+- Change interfaces or data structures without updating docs and callers
+- Catch exceptions and silently swallow errors or return success
+- Use `any`, forced assertions, or empty object defaults to mask real type problems
+- Leave components without loading/empty/error/disabled/permission states
+- Rely on implicit side effects for interactions without explicit data flow and cleanup logic
+- Elevate local state to global state, or duplicate server state as multiple local states
+- Only verify ideal paths, not failures, empty data, or repeated operations
+- Introduce features not required by the PRD
+- Refactor unrelated modules "while you're at it"
+- Make premature abstractions for one-off code
+
+---
+
+## Execution Order
+
+1. Bind runtime context: `./.cowork-flow/run subagent bind <runtime_context_id> <host_context_key>`
+2. Read task directory from bound runtime context
+3. Read `<task>/prd.md`, `<task>/info.md`, `<task>/implement.jsonl`, and each JSONL `file` entry
+4. Read pre-implementation checklist: `.cowork-flow/spec/guides/pre-implementation-checklist.md`
+5. Read relevant spec directory (backend or frontend) and ALL linked documents
+6. Apply coding gates — verify each gate before proceeding
+7. Implement changes within assigned scope
+8. Run verification commands (compile, lint, test, build, type-check)
+9. Report changed files and exact verification commands
+10. Do NOT run task start, task finish, task archive, unscoped resume, commit, or push
+
+---
+
 Rules:
 
 - Read the task directory from the bound runtime context.
@@ -35,6 +194,6 @@ Rules:
   and each JSONL `file` entry.
 - Keep edits inside the assigned scope.
 - Report changed files and exact verification commands.
-- Do not use the Task tool or invoke subagents.
+- Do not use the `task` tool or invoke subagents.
 - Do not run task start, task finish, task archive, unscoped resume, commit, or
   push.

package/template/.claude/skills/party-mode-v2/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: party-mode-v2
+description: Use when the user requests a runtime-controlled multi-agent board discussion where children communicate through Party Mode V2 board APIs and the moderator only monitors or corrects drift.
+---
+
+# Party Mode V2
+
+Use this skill as a thin entrypoint for the Party Mode V2 runtime board. The Python runtime is the source of truth for discussion state, board visibility, validation, round limits, and final reports.
+
+## Boundaries
+
+- Party Mode V2 is advisory only.
+- It cannot mutate task status, start/review/complete/archive tasks, add sessions, commit, push, or satisfy formal workflow gates.
+- It cannot satisfy formal Implement or Check completion. Use `cowork-implement` and `cowork-check` for formal phases.
+- Discussion children are leaf executors. They do not dispatch, wait for, list, or close other agents.
+- The moderator does not forward, summarize, rewrite, or synthesize child opinions for other child agents.
+
+## Runtime First
+
+Always use the runtime controller:
+
+```text
+.cowork-flow/run party-v2 init
+.cowork-flow/run party-v2 monitor
+.cowork-flow/run party-v2 view
+.cowork-flow/run party-v2 post
+.cowork-flow/run party-v2 respond
+.cowork-flow/run party-v2 advance
+.cowork-flow/run party-v2 finalize
+```
+
+Do not bypass a runtime rejection by manually accepting child output. Runtime validation failures must be fixed by a corrected child submission or by ending the discussion.
+
+## Board Rules
+
+- Child agents communicate through the board API.
+- Child-visible board output must be current-round only.
+- Historical board state is runtime-private and may be used only for audit or final reports.
+- Use at least three child agents unless the effective runtime config explicitly allows a different value.
+- The runtime emits host-neutral next actions. The active Host Adapter or moderator executes them for Codex, Claude Code, or OpenCode.
+
+## Child Response Rules
+
+When a child sees a different position, it must choose exactly one:
+
+```text
+maintain
+revise
+concede
+```
+
+`concede` requires accepted evidence and why the prior position failed.
+`revise` requires the accepted part, rejected part, and updated position.
+`maintain` requires counter evidence or counter reasoning.
+
+Unsupported agreement, vague revision, and evidence-free rebuttal are invalid.
+
+## Moderator Role
+
+The moderator may:
+
+- run runtime commands,
+- execute host-neutral next actions through the active host,
+- record off-topic warnings through the runtime,
+- close children only when the runtime asks for closeout,
+- show runtime status or final reports to the user.
+
+The moderator must not:
+
+- forward one child opinion to another child,
+- create a claim table for child prompts,
+- vote-count as validation,
+- decide which child is correct.

package/template/.cowork-flow/.version

@@ -1 +1 @@
-0.0.25
+0.0.27

package/template/.cowork-flow/config.yaml

@@ -28,6 +28,22 @@ codex:
   # .cowork-flow/.runtime/subagents/<id>.json with the subagent helper, then
   # passes cowork_runtime_context_id through the active host adapter transport.
 
+#-------------------------------------------------------------------------------
+# Party Mode V2 Runtime Board
+#-------------------------------------------------------------------------------
+
+# Party Mode V2 is an advisory, runtime-controlled board discussion mode.
+# The Python runtime owns board state and emits host-neutral next actions; the
+# active host adapter still performs dispatch/wait/close.
+party_mode_v2:
+  min_agents: 3
+  max_agents: 5
+  max_rounds: 5
+  max_rebuttal_targets_per_agent: 2
+  max_drift_warnings: 2
+  fresh_context_per_round: "true"
+  require_current_round_only: "true"
+
 #-------------------------------------------------------------------------------
 # Task Lifecycle Hooks
 #-------------------------------------------------------------------------------

package/template/.cowork-flow/scripts/common/active_task.py

@@ -66,6 +66,10 @@ def resolve_context_key(values: Mapping[str, object] | None = None) -> str | Non
     if claude_session and claude_session.strip():
         return f"claude_{_sanitize(claude_session)}"
 
+    claude_code_session = os.environ.get("CLAUDE_CODE_SESSION_ID")
+    if claude_code_session and claude_code_session.strip():
+        return f"claude_{_sanitize(claude_code_session)}"
+
     codex_session = os.environ.get("CODEX_SESSION_ID")
     if codex_session and codex_session.strip():
         return f"codex_{_sanitize(codex_session)}"
@@ -90,6 +94,8 @@ def resolve_context_key(values: Mapping[str, object] | None = None) -> str | Non
         (
             "OPENCODE_SESSION_ID",
             "opencode_session_id",
+            "sessionID",
+            "sessionId",
         ),
     )
     if input_opencode_session:
@@ -100,6 +106,8 @@ def resolve_context_key(values: Mapping[str, object] | None = None) -> str | Non
         (
             "CLAUDE_SESSION_ID",
             "claude_session_id",
+            "CLAUDE_CODE_SESSION_ID",
+            "claude_code_session_id",
         ),
     )
     if input_claude_session:

package/template/.cowork-flow/scripts/common/archive_utils.py

@@ -1,4 +1,4 @@
-#!/usr/bin/env python3
+#!/usr/bin/env python3
 """Small resumable directory archive helpers."""
 
 from __future__ import annotations

package/template/.cowork-flow/scripts/common/config.py

@@ -16,6 +16,13 @@ from .paths import DIR_WORKFLOW, get_repo_root
 DEFAULT_SESSION_COMMIT_MESSAGE = "chore: record journal"
 DEFAULT_MAX_JOURNAL_LINES = 2000
 DEFAULT_CODEX_DISPATCH_MODE = "sub-agent"
+DEFAULT_PARTY_MODE_V2_MIN_AGENTS = 3
+DEFAULT_PARTY_MODE_V2_MAX_AGENTS = 5
+DEFAULT_PARTY_MODE_V2_MAX_ROUNDS = 5
+DEFAULT_PARTY_MODE_V2_MAX_REBUTTAL_TARGETS_PER_AGENT = 2
+DEFAULT_PARTY_MODE_V2_MAX_DRIFT_WARNINGS = 2
+DEFAULT_PARTY_MODE_V2_FRESH_CONTEXT_PER_ROUND = True
+DEFAULT_PARTY_MODE_V2_REQUIRE_CURRENT_ROUND_ONLY = True
 
 CONFIG_FILE = "config.yaml"
 
@@ -139,3 +146,89 @@ def get_codex_dispatch_mode(repo_root: Path | None = None) -> str:
     if mode in {"sub-agent", "inline"}:
         return str(mode)
     return DEFAULT_CODEX_DISPATCH_MODE
+
+def _get_section(config: dict, section_name: str) -> dict:
+    section = config.get(section_name)
+    if isinstance(section, dict):
+        return section
+    return {}
+
+def _get_int(section: dict, key: str, default: int, *, minimum: int | None = None) -> int:
+    value = section.get(key, default)
+    try:
+        parsed = int(value)
+    except (TypeError, ValueError):
+        return default
+    if minimum is not None and parsed < minimum:
+        return default
+    return parsed
+
+def _get_bool(section: dict, key: str, default: bool) -> bool:
+    value = section.get(key, default)
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, str):
+        normalized = value.strip().lower()
+        if normalized in {"true", "1", "yes", "on"}:
+            return True
+        if normalized in {"false", "0", "no", "off"}:
+            return False
+    return default
+
+def get_party_mode_v2_config(repo_root: Path | None = None) -> dict[str, int | bool]:
+    """Get Party Mode V2 runtime-board defaults."""
+    config = _load_config(repo_root)
+    section = _get_section(config, "party_mode_v2")
+    min_agents = _get_int(
+        section,
+        "min_agents",
+        DEFAULT_PARTY_MODE_V2_MIN_AGENTS,
+        minimum=3,
+    )
+    max_agents = _get_int(
+        section,
+        "max_agents",
+        DEFAULT_PARTY_MODE_V2_MAX_AGENTS,
+        minimum=min_agents,
+    )
+    return {
+        "min_agents": min_agents,
+        "max_agents": max_agents,
+        "max_rounds": _get_int(
+            section,
+            "max_rounds",
+            DEFAULT_PARTY_MODE_V2_MAX_ROUNDS,
+            minimum=1,
+        ),
+        "max_rebuttal_targets_per_agent": _get_int(
+            section,
+            "max_rebuttal_targets_per_agent",
+            DEFAULT_PARTY_MODE_V2_MAX_REBUTTAL_TARGETS_PER_AGENT,
+            minimum=1,
+        ),
+        "max_drift_warnings": _get_int(
+            section,
+            "max_drift_warnings",
+            DEFAULT_PARTY_MODE_V2_MAX_DRIFT_WARNINGS,
+            minimum=0,
+        ),
+        "fresh_context_per_round": _get_bool(
+            section,
+            "fresh_context_per_round",
+            DEFAULT_PARTY_MODE_V2_FRESH_CONTEXT_PER_ROUND,
+        ),
+        "require_current_round_only": _get_bool(
+            section,
+            "require_current_round_only",
+            DEFAULT_PARTY_MODE_V2_REQUIRE_CURRENT_ROUND_ONLY,
+        ),
+    }
+
+def get_party_mode_v2_min_agents(repo_root: Path | None = None) -> int:
+    return int(get_party_mode_v2_config(repo_root)["min_agents"])
+
+def get_party_mode_v2_max_agents(repo_root: Path | None = None) -> int:
+    return int(get_party_mode_v2_config(repo_root)["max_agents"])
+
+def get_party_mode_v2_max_rounds(repo_root: Path | None = None) -> int:
+    return int(get_party_mode_v2_config(repo_root)["max_rounds"])

package/template/.cowork-flow/scripts/common/errors.py

@@ -0,0 +1,107 @@
+#!/usr/bin/env python3
+"""
+Error handling utilities for cowork-flow.
+
+Provides centralized error types and formatted output.
+"""
+
+from __future__ import annotations
+
+import sys
+from typing import Any
+
+
+class CoworkFlowError(Exception):
+    """Base error for cowork-flow."""
+
+    def __init__(
+        self,
+        message: str,
+        suggestion: str | None = None,
+        exit_code: int = 1,
+        context: dict[str, Any] | None = None,
+    ):
+        super().__init__(message)
+        self.suggestion = suggestion
+        self.exit_code = exit_code
+        self.context = context or {}
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert error to dictionary format."""
+        result = {
+            "error_code": self.__class__.__name__,
+            "message": str(self),
+            "suggestion": self.suggestion,
+            "context": self.context,
+        }
+        return result
+
+
+class TaskError(CoworkFlowError):
+    """Task-related errors."""
+    pass
+
+
+class ConfigError(CoworkFlowError):
+    """Configuration errors."""
+    pass
+
+
+class ValidationError(CoworkFlowError):
+    """Validation errors."""
+    pass
+
+
+class AdapterError(CoworkFlowError):
+    """Adapter-related errors."""
+    pass
+
+
+def print_error(error: CoworkFlowError, file=None) -> None:
+    """
+    Print formatted error with suggestion.
+
+    Args:
+        error: The error to print
+        file: Output file (defaults to stderr)
+    """
+    output = file or sys.stderr
+
+    print(f"Error: {error}", file=output)
+    if error.suggestion:
+        print(f"Suggestion: {error.suggestion}", file=output)
+
+    if error.context:
+        print("Context:", file=output)
+        for key, value in error.context.items():
+            print(f"  {key}: {value}", file=output)
+
+
+def format_error_message(
+    error_code: str,
+    message: str,
+    suggestion: str | None = None,
+    context: dict[str, Any] | None = None,
+) -> str:
+    """
+    Format error message as JSON string.
+
+    Args:
+        error_code: Error code identifier
+        message: Error message
+        suggestion: Recovery suggestion
+        context: Additional context
+
+    Returns:
+        JSON string of formatted error
+    """
+    import json
+
+    error_dict = {
+        "error_code": error_code,
+        "message": message,
+        "suggestion": suggestion,
+        "context": context or {},
+    }
+
+    return json.dumps(error_dict, ensure_ascii=False)