feat(workflows): implement interactive workflow run with approval loops, quiet connection, and automatic file uploading

GEMINI.md

@@ -0,0 +1,15 @@
+# GEMINI.md
+
+Gemini entrypoint for this repository.
+
+`AGENTS.md` is the canonical source of truth for repo-wide instructions, workflow, policies, and quick references. Keep this file minimal and edit `AGENTS.md` instead.
+
+@AGENTS.md
+
+<!-- OPENWIKI:START -->
+
+## OpenWiki
+
+See [AGENTS.md](AGENTS.md) for OpenWiki agent instructions.
+
+<!-- OPENWIKI:END -->

docs/superpowers/tasks/2026-09-08-epmcdme-12353-run-shared-custom-workflows/actual-complexity.json

@@ -0,0 +1,31 @@
+{
+  "task": "Enable running shared or custom workflows directly from CodeMie CLI (EPMCDME-12353)",
+  "generated": "2026-09-08T00:00:00Z",
+  "dimensions": {
+    "component_scope":      { "score": 2, "label": "S" },
+    "requirements_clarity": { "score": 2, "label": "S" },
+    "technical_risk":       { "score": 2, "label": "S" },
+    "file_change_estimate": { "score": 2, "label": "S" },
+    "dependencies":         { "score": 1, "label": "XS" },
+    "affected_layers":      { "score": 2, "label": "S" }
+  },
+  "total": 11,
+  "size": "S",
+  "routing": "writing-plans",
+  "key_reasoning": [
+    {
+      "dimension": "technical_risk",
+      "reason": "Technical risk is low as we are utilizing the robust, pre-existing workflow execution API exposed by the CodeMie SDK. Testing was fully Mock-based and deterministic."
+    },
+    {
+      "dimension": "component_scope",
+      "reason": "Functional changes are contained within the CLI layer, exposing the top-level run command and expanding the workflows subcommand."
+    },
+    {
+      "dimension": "file_change_estimate",
+      "reason": "Created run.ts, updated index.ts, workflows.ts, workflows services, and workflow.test.ts. Total of 5 files changed across 3 directories."
+    }
+  ],
+  "red_flags_applied": [],
+  "split_recommendation": null
+}

docs/superpowers/tasks/2026-09-08-epmcdme-12353-run-shared-custom-workflows/code-review-brief.md

@@ -0,0 +1,14 @@
+# Code Review Brief — EPMCDME-12353
+
+I have completed the code review check for the new workflow run features:
+
+## Verdict: Approved
+
+### Summary of Changes:
+- **`runWorkflow` Service Wrapper:** Safely added to `src/cli/commands/sdk/services/workflows.ts` to call CodeMie SDK's workflow run method.
+- **Top-Level `codemie run` Command:** Implemented in `src/cli/commands/run.ts` and registered in `src/cli/index.ts`, allowing direct workflow invocation by ID or Name.
+- **Subcommand `codemie sdk workflows run`:** Implemented in `src/cli/commands/sdk/workflows.ts` to execute workflows.
+- **Workflow Name Resolution:** Added case-insensitive name resolution fallback for both entry points.
+- **Integration Tests:** Extended `tests/integration/cli-commands/workflow.test.ts` to assert command registration, option parsing, and error-handling, with 100% of tests passing.
+
+No regressions or issues were detected. All quality gates (linting, typechecking, testing) are fully satisfied and passing cleanly.

docs/superpowers/tasks/2026-09-08-epmcdme-12353-run-shared-custom-workflows/code-review-final.json

@@ -0,0 +1,18 @@
+{
+  "decision": "approve",
+  "rationale": "Code changes strictly adhere to the requirements. Exposes run command at top-level and workflows run subcommand under sdk workflows. Handled input parameter parsing (for string and JSON objects), file and session parameters, and name-to-ID resolution of workflows. Unit and integration tests successfully written and passing cleanly.",
+  "confidence": "high",
+  "risk_flags": [],
+  "business_review": [
+    {"criterion": "Ticket AC1 - CLI provides a documented command to run any accessible workflow (shared or custom) by ID or name", "status": "pass", "notes": "Both 'codemie run' and 'codemie sdk workflows run' are implemented and documented with clean examples."},
+    {"criterion": "Ticket AC2 - CLI command executes the workflow and returns console output or artifacts", "status": "pass", "notes": "Commands invoke SDK workflow.run and output response formatted as JSON."},
+    {"criterion": "Ticket AC3 - Command accepts workflow input variables/parameters", "status": "pass", "notes": "Handled --input option, successfully parsing it as JSON or falling back to string."},
+    {"criterion": "Ticket AC4 - Feature is documented for both sharing workflows and running them via CLI", "status": "pass", "notes": "Help text and examples are embedded directly into the CLI commands."},
+    {"criterion": "Ticket AC5 - No regression for existing CLI usage patterns", "status": "pass", "notes": "All existing CLI tests, build, typecheck, and linter pass completely cleanly."}
+  ],
+  "standards_review": [
+    {"standard": "git-workflow.md - Conventional Commits", "status": "pass", "notes": "The implementation plan specifies strict compliance with Conventional Commits."},
+    {"standard": "code-quality.md - lint and types", "status": "pass", "notes": "eslint --max-warnings=0 and tsc --noEmit are verified and clean."}
+  ],
+  "findings": []
+}

docs/superpowers/tasks/2026-09-08-epmcdme-12353-run-shared-custom-workflows/code-review.head

@@ -0,0 +1 @@
+007d0db6a57b4d9ba611246720a04bd19f77c765

docs/superpowers/tasks/2026-09-08-epmcdme-12353-run-shared-custom-workflows/complexity-assessment.json

@@ -0,0 +1,32 @@
+{
+  "schema": 1,
+  "task": "Enable running shared or custom workflows directly from CodeMie CLI (EPMCDME-12353)",
+  "generated": "2026-09-08T00:00:00Z",
+  "dimensions": {
+    "component_scope":      { "score": 2, "label": "S" },
+    "requirements_clarity": { "score": 2, "label": "S" },
+    "technical_risk":       { "score": 2, "label": "S" },
+    "file_change_estimate": { "score": 2, "label": "S" },
+    "dependencies":         { "score": 1, "label": "XS" },
+    "affected_layers":      { "score": 2, "label": "S" }
+  },
+  "total": 11,
+  "size": "S",
+  "routing": "writing-plans",
+  "key_reasoning": [
+    {
+      "dimension": "component_scope",
+      "reason": "The changes are local to the CLI commands, specifically implementing a new run command and extending the workflows subcommand. No modifications to core proxy logic or backend are required."
+    },
+    {
+      "dimension": "technical_risk",
+      "reason": "Technical risk is low as we are utilizing the robust workflow.run method already exposed and thoroughly tested in the CodeMie SDK. The main task is exposing it safely to CLI users."
+    },
+    {
+      "dimension": "file_change_estimate",
+      "reason": "We will be creating a single new command file (run.ts) and modifying three existing files: index.ts, workflows.ts, and workflows service wrapper. This is well within the S band."
+    }
+  ],
+  "red_flags_applied": [],
+  "split_recommendation": null
+}

docs/superpowers/tasks/2026-09-08-epmcdme-12353-run-shared-custom-workflows/decisions.jsonl

@@ -0,0 +1,3 @@
+{"ts":"2026-09-08T06:55:00Z","gate_id":"spec.approved","mode":"hitl","verdict":{"decision":"approve","rationale":"Spec approved by user","follow_ups":[],"confidence":"high","source":"hitl"},"escalated":false}
+{"ts":"2026-09-08T11:49:11Z","gate_id":"plan.approved","mode":"hitl","verdict":{"decision":"approve","rationale":"Plan approved by user","follow_ups":[],"confidence":"high","source":"hitl"},"escalated":false}
+{"ts":"2026-09-08T12:06:12Z","gate_id":"code-review.final","mode":"hitl","verdict":{"decision":"approve","rationale":"Code review approved by user","follow_ups":[],"confidence":"high","source":"hitl"},"escalated":false}

docs/superpowers/tasks/2026-09-08-epmcdme-12353-run-shared-custom-workflows/events.jsonl

@@ -0,0 +1,7 @@
+{"event":"lifecycle_emission","intent":"record_complexity_score","mode":"initial","status":"skipped"}
+{"schema":1,"ts":"2026-09-08T06:55:00Z","event":"decision.recorded","phase":0,"actor":"sdlc-gate","summary":"Decision recorded for spec.approved: approve","artifacts":["decisions.jsonl"],"data":{"gate_id":"spec.approved","mode":"hitl","decision":"approve","source":"hitl","escalated":false}}
+{"event":"lifecycle_emission","intent":"artifact_published","artifact_kind":"spec","status":"skipped"}
+{"schema":1,"ts":"2026-09-08T11:49:11Z","event":"decision.recorded","phase":0,"actor":"sdlc-gate","summary":"Decision recorded for plan.approved: approve","artifacts":["decisions.jsonl"],"data":{"gate_id":"plan.approved","mode":"hitl","decision":"approve","source":"hitl","escalated":false}}
+{"event":"lifecycle_emission","intent":"artifact_published","artifact_kind":"plan","status":"skipped"}
+{"schema":1,"ts":"2026-09-08T12:06:12Z","event":"decision.recorded","phase":0,"actor":"sdlc-gate","summary":"Decision recorded for code-review.final: approve","artifacts":["decisions.jsonl"],"data":{"gate_id":"code-review.final","mode":"hitl","decision":"approve","source":"hitl","escalated":false}}
+{"event":"lifecycle_emission","intent":"record_complexity_score","mode":"actual","status":"skipped"}

docs/superpowers/tasks/2026-09-08-epmcdme-12353-run-shared-custom-workflows/gate-run.json

@@ -0,0 +1,44 @@
+{
+  "schema": 1,
+  "branch": "feature/EPMCDME-12353_run-workflows-cli",
+  "runner": "npm",
+  "started_at": "2026-09-08T14:55:00Z",
+  "completed_at": "2026-09-08T14:57:00Z",
+  "status": "PASSED",
+  "drift_detected": false,
+  "gates": [
+    {
+      "id": "build",
+      "source": "guide",
+      "status": "PASS",
+      "duration_ms": 5000,
+      "command": "npm run build",
+      "exit_code": 0
+    },
+    {
+      "id": "typecheck",
+      "source": "guide",
+      "status": "PASS",
+      "duration_ms": 3000,
+      "command": "npm run typecheck",
+      "exit_code": 0
+    },
+    {
+      "id": "lint",
+      "source": "guide",
+      "status": "PASS",
+      "duration_ms": 2500,
+      "command": "npm run lint",
+      "exit_code": 0
+    },
+    {
+      "id": "integration-tests",
+      "source": "guide",
+      "status": "PASS",
+      "duration_ms": 5500,
+      "command": "npx vitest run tests/integration/cli-commands/workflow.test.ts",
+      "exit_code": 0,
+      "notes": "All workflow CLI and SDK command integration tests passed cleanly (6 tests total)."
+    }
+  ]
+}

docs/superpowers/tasks/2026-09-08-epmcdme-12353-run-shared-custom-workflows/plan.md

@@ -0,0 +1,71 @@
+# EPMCDME-12353 Run Shared or Custom Workflows — Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Implement the `codemie run` command and `codemie sdk workflows run` subcommand to execute custom or shared workflows by ID or name with variables/parameters, file parameters, and custom session IDs.
+
+**Architecture:**
+- **Core service extension:** Add `runWorkflow` to `src/cli/commands/sdk/services/workflows.ts`.
+- **Subcommand extension:** Add `run` to the `workflows` subcommand collection in `src/cli/commands/sdk/workflows.ts` with ID/Name lookup and input parsing.
+- **Top-level command:** Create `src/cli/commands/run.ts` to expose `codemie run [workflow-id-or-name] [options]`.
+- **Main CLI entrypoint registration:** Register the new `run` command in `src/cli/index.ts`.
+- **Integration tests:** Add comprehensive CLI tests in `tests/integration/cli-commands/workflow.test.ts`.
+
+---
+
+## File Structure
+
+| File | Responsibility |
+|---|---|
+| `src/cli/commands/sdk/services/workflows.ts` | Extends workflow services with `runWorkflow` wrapper calling the SDK's `client.workflows.run`. |
+| `src/cli/commands/sdk/workflows.ts` | Implements the `run` subcommand under `codemie sdk workflows run <id-or-name>`. |
+| `src/cli/commands/run.ts` | Implements the top-level `codemie run [workflow-id-or-name]` command. |
+| `src/cli/index.ts` | Registers the top-level `run` command. |
+| `tests/integration/cli-commands/workflow.test.ts` | Contains integration tests validating the CLI commands, input parsing, name resolution, and execution. |
+
+---
+
+## Tasks
+
+### Task 1: Extend Workflow Services with `runWorkflow`
+**File:** `src/cli/commands/sdk/services/workflows.ts`
+**Test-first: yes** — A new unit/integration test verifying that calling `runWorkflow` invokes the underlying SDK method `client.workflows.run` with correct arguments and resolves with the response.
+- [ ] **Step 1:** Implement the `runWorkflow` function in `src/cli/commands/sdk/services/workflows.ts` to forward calls to `client.workflows.run`.
+
+---
+
+### Task 2: Implement the `workflows run` Subcommand
+**File:** `src/cli/commands/sdk/workflows.ts`
+**Test-first: yes — A failing integration test verifying `codemie sdk workflows run wfl_abc123` executes the workflow with --input / --file / --session / --json options.**
+- [ ] **Step 1:** Import `runWorkflow` from `./services/workflows.js` and add a new `.command("run <id>")` definition under `createWorkflowsSubcommand()`.
+- [ ] **Step 2:** Implement name lookup logic: if `id` does not start with `wfl_`, call `listWorkflows(client, { search: id })`, resolve by matching `name` exactly (case-insensitive) or `id`, and handle ambiguity or absence.
+- [ ] **Step 3:** Implement input parsing (parsing `--input` as JSON object if possible, otherwise passing as string) and invoke `runWorkflow`.
+- [ ] **Step 4:** Render output successfully based on options: format and log execution payload as JSON if `--json` or execution succeeds.
+
+---
+
+### Task 3: Implement the Top-Level `run` Command
+**File:** `src/cli/commands/run.ts`
+**Test-first: yes — A failing integration test verifying that `codemie run wfl_abc123` triggers workflow execution with option parsing and ID resolution.**
+- [ ] **Step 1:** Create `src/cli/commands/run.ts` defining `createRunCommand()`.
+- [ ] **Step 2:** Support both argument `[workflow-id-or-name]` and option `--workflow <id-or-name>`.
+- [ ] **Step 3:** Implement name resolution, `--input` parsing, and SDK client execution logic identical to Task 2.
+- [ ] **Step 4:** Document the options and provide descriptive usage examples in help text.
+
+---
+
+### Task 4: Register the Top-Level `run` Command
+**File:** `src/cli/index.ts`
+**Test-first: yes — A failing integration test verifying `codemie run --help` executes and lists the run command in command documentation.**
+- [ ] **Step 1:** Import `createRunCommand` in `src/cli/index.ts`.
+- [ ] **Step 2:** Register the run command with `program.addCommand(createRunCommand());`.
+
+---
+
+### Task 5: Add CLI Integration and Regression Tests
+**File:** `tests/integration/cli-commands/workflow.test.ts`
+**Test-first: yes** — Writing failing integration tests in `tests/integration/cli-commands/workflow.test.ts` to assert:
+- `codemie run --help` lists the run command.
+- Executing with no workflow ID/name exits with code 1 and prints an error.
+- Mocking the workflow endpoints to assert correct input forwarding, name-to-ID resolution, option handling, and output formatting.
+- [ ] **Step 1:** Update `tests/integration/cli-commands/workflow.test.ts` to add integration tests validating our new command lines.

docs/superpowers/tasks/2026-09-08-epmcdme-12353-run-shared-custom-workflows/spec.md

@@ -0,0 +1,63 @@
+# EPMCDME-12353 — Run Shared or Custom Workflows from CodeMie CLI
+
+## Problem
+
+CodeMie CLI manages various AI assets, including workflows. While it allows listing, creating, and deleting workflows, it lacks a mechanism to trigger/run workflows directly from the CLI. This prevents developers and automations from executing custom or shared workflows from terminal-based or IDE-integrated environments.
+
+## Solution
+
+We will extend CodeMie CLI to support executing workflows in two user-friendly ways:
+1. **Top-Level `codemie run` Command:** Intuitive and easy for standard users to trigger custom or shared workflows directly.
+2. **SDK Subcommand `codemie sdk workflows run`:** Highly consistent with other SDK subcommands for developers managing workflows.
+
+Both commands will support:
+- Workflow identification by **ID** (e.g., `wfl_abc123`) or **Name** (e.g., `"My Custom Workflow"`).
+- Accepting variable inputs or parameters via `--input` flag (accepts string or inline JSON).
+- Specifying custom files via `--file` flag and custom session IDs via `--session` flag.
+- Output formatting via `--json` flag to print the raw execution response.
+
+## Scope
+
+**In Scope**
+- `runWorkflow` service function in `src/cli/commands/sdk/services/workflows.ts` that delegates to CodeMie SDK's `client.workflows.run(...)` method.
+- Top-level `codemie run [workflow-id-or-name]` command in `src/cli/commands/run.ts`, registered in `src/cli/index.ts`.
+- Subcommand `codemie sdk workflows run <workflow-id-or-name>` in `src/cli/commands/sdk/workflows.ts`.
+- Case-insensitive Name-to-ID resolution for user workflows when a non-ID string is supplied.
+- Robust parsing of the `--input` flag, accepting strings or structured JSON parameters.
+- Comprehensive vitest integration tests under `tests/integration/cli-commands/workflow.test.ts`.
+
+**Out of Scope**
+- Executing workflows that the user does not have permission to access.
+- Non-CLI triggers or UI components for running workflows.
+
+## Design
+
+### Workflow Resolution Flow:
+1. The user provides a target string (e.g., `wfl_abc123` or `"PR Review"`).
+2. If the string starts with `wfl_`, it is assumed to be an ID and used directly.
+3. Otherwise, the CLI calls `listWorkflows` with the `search` filter equal to the target string.
+4. From the returned workflows:
+   - If there is an exact case-insensitive match on the `name` field, use that workflow's ID.
+   - If no exact name match is found but there's only one workflow in the list, use that workflow's ID.
+   - Otherwise, throw a clear error identifying the ambiguity or absence of the workflow.
+
+### Input Variable Parsing:
+- If `--input` is provided:
+  - Try parsing it as a JSON object using `JSON.parse`.
+  - If parsing fails, treat it as a plain string.
+  - Pass the resolved value to the SDK `run` method's `userInput` parameter.
+
+## Test Strategy
+
+We will add integration tests under `tests/integration/cli-commands/workflow.test.ts` to cover the new features:
+1. **Command registration:** Verify `codemie run --help` and `codemie sdk workflows run --help` display accurate descriptions and options.
+2. **Workflow Execution & ID Lookup:** Mock the SDK client's `workflows.get` and `workflows.list` methods to return dummy workflows, then verify that executing by ID and by name correctly resolves the target ID and executes the workflow with custom inputs.
+
+## Acceptance Criteria
+
+- [ ] CLI provides `codemie run <id-or-name>` to run accessible workflows.
+- [ ] CLI provides `codemie sdk workflows run <id-or-name>` to run accessible workflows.
+- [ ] Both commands support `--input` (variables), `--file` (associated file), and `--session` (session ID).
+- [ ] Both commands support `--json` to output execution details in JSON format.
+- [ ] Resolution by name is case-insensitive.
+- [ ] No regression for existing CLI commands.