docs: ops-harbor automation pipeline design spec

[masseater]

Summary

• ops-harbor の自動化パイプラインを Typed Phase Pipeline + ActionExecutor パターンで設計
• Codex アーキテクチャレビューを経て、型安全性・DDD ラベル・エラーハンドリング等を改善

Key Design Elements

• 6-phase linear pipeline: ingest → enrich → evaluate → plan → execute → finalize
• ActionExecutor<K> + ExecutorRegistry (Required mapped type で登録漏れをコンパイルエラーに)
• Closed TriggerKind union (境界バリデーションで未知入力を reject)
• Alert (UI) と Trigger (automation) の独立導出
• Phase<I,O> 型制約、PhaseError + retry policy、rate limit budget

Test plan

• スペックドキュメントの内部整合性を確認
• TypeScript 型定義が設計意図通りか実装時に検証

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Added comprehensive specification for the automation pipeline system redesign. Includes documentation of the pipeline architecture with defined operational phases, trigger and alert management, error handling and recovery strategies, execution workflows, and operational safeguards including deduplication, debouncing, and rate limiting controls.

[coderabbitai]

📝 Walkthrough

Walkthrough

A new architectural specification document has been added that defines the redesign of the ops-harbor automation pipeline using a typed phase-based pattern with ActionExecutor pattern, covering a 6-phase sequential pipeline (ingest, enrich, evaluate, plan, execute, finalize) with discriminated union types for Triggers and Actions.

Changes

Cohort / File(s)	Summary
Ops-Harbor Pipeline Architecture Specification docs/superpowers/specs/2026-04-06-ops-harbor-automation-pipeline-design.md	Architectural specification for pipeline redesign introducing typed Phase pattern, ActionExecutor dispatch mechanism, trigger/alert separation, discriminated union types for Actions and Triggers, error categorization (transient/permanent), retry strategies, and module composition boundaries.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

🐰 A pipeline most grand, six phases of cheer,
With Triggers and Actions—the path crystal clear,
Types guard every step, no unknowns slip through,
From ingest to finalize, each role knows what to do!
The rabbit hops forward with architectural glee. 🌟

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and accurately summarizes the main change: addition of a design specification document for the ops-harbor automation pipeline.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch refine-ops-harbor

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

🧹 Nitpick comments (2)

docs/superpowers/specs/2026-04-06-ops-harbor-automation-pipeline-design.md (2)

33-35: Add language specifier to fenced code block.

For consistency and better syntax highlighting, specify the language for code blocks.

📝 Suggested fix

-```
+```text
 ingest → enrich → evaluate → plan → execute → finalize

</details>

<details>
<summary>🤖 Prompt for AI Agents</summary>

Verify each finding against the current code and only fix it if needed.

In @docs/superpowers/specs/2026-04-06-ops-harbor-automation-pipeline-design.md
around lines 33 - 35, The fenced code block containing the pipeline string
"ingest → enrich → evaluate → plan → execute → finalize" lacks a language
specifier; update the triple-backtick fence to include a language (e.g., text or plain) so Markdown renderers apply consistent syntax highlighting for that
block, keeping the block content unchanged.

</details>

---

`169-169`: **Consider adding a comment to explain the `string & {}` pattern.**

The type `"claude" | "codex" | (string & {})` is a valid TypeScript pattern for providing autocomplete for built-in tools while allowing arbitrary custom tool names. However, this pattern may be unfamiliar to some developers.



<details>
<summary>📝 Suggested clarification</summary>

```diff
-type ToolName = "claude" | "codex" | (string & {});  // builtin + custom CLI names
+// ToolName provides autocomplete for built-in tools ("claude" | "codex") 
+// while allowing arbitrary custom CLI tool names via (string & {})
+type ToolName = "claude" | "codex" | (string & {});
```

</details>

<details>
<summary>🤖 Prompt for AI Agents</summary>

```
Verify each finding against the current code and only fix it if needed.

In `@docs/superpowers/specs/2026-04-06-ops-harbor-automation-pipeline-design.md`
at line 169, Add an inline comment next to the ToolName alias explaining that
the union "claude" | "codex" provides IDE autocomplete for known tool names
while the (string & {}) part allows arbitrary custom tool names without
collapsing the union to plain string; mention that (string & {}) is an open
string type used specifically to preserve literal completion for the built-ins
while accepting any other string. Reference the ToolName type and the (string &
{}) pattern so future readers know why that intersection is used and what would
change if it were replaced with plain string.
```

</details>

</blockquote></details>

</blockquote></details>

<details>
<summary>🤖 Prompt for all review comments with AI agents</summary>

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In @docs/superpowers/specs/2026-04-06-ops-harbor-automation-pipeline-design.md:

• Around line 33-35: The fenced code block containing the pipeline string
  "ingest → enrich → evaluate → plan → execute → finalize" lacks a language
  specifier; update the triple-backtick fence to include a language (e.g., text or plain) so Markdown renderers apply consistent syntax highlighting for that
  block, keeping the block content unchanged.
• Line 169: Add an inline comment next to the ToolName alias explaining that the
  union "claude" | "codex" provides IDE autocomplete for known tool names while
  the (string & {}) part allows arbitrary custom tool names without collapsing the
  union to plain string; mention that (string & {}) is an open string type used
  specifically to preserve literal completion for the built-ins while accepting
  any other string. Reference the ToolName type and the (string & {}) pattern so
  future readers know why that intersection is used and what would change if it
  were replaced with plain string.

</details>

---

<details>
<summary>ℹ️ Review info</summary>

<details>
<summary>⚙️ Run configuration</summary>

**Configuration used**: Organization UI

**Review profile**: CHILL

**Plan**: Pro

**Run ID**: `a4e6274a-5605-4db1-857d-b9048b759e5f`

</details>

<details>
<summary>📥 Commits</summary>

Reviewing files that changed from the base of the PR and between 1ffedea7fdc9aebade453da0116f0f106c7e0aca and 40f2da9a3beebd0adbd76ee83231667b1b7164ea.

</details>

<details>
<summary>📒 Files selected for processing (1)</summary>

* `docs/superpowers/specs/2026-04-06-ops-harbor-automation-pipeline-design.md`

</details>

</details>

<!-- This is an auto-generated comment by CodeRabbit for review status -->