diff --git a/.agents/plugins/marketplace.json b/.agents/plugins/marketplace.json new file mode 100644 index 0000000..52d91e2 --- /dev/null +++ b/.agents/plugins/marketplace.json @@ -0,0 +1,20 @@ +{ + "name": "harness-local", + "interface": { + "displayName": "Harness Local" + }, + "plugins": [ + { + "name": "harness-codex", + "source": { + "source": "local", + "path": "./plugins/harness-codex" + }, + "policy": { + "installation": "AVAILABLE", + "authentication": "ON_INSTALL" + }, + "category": "Productivity" + } + ] +} diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index e6d0b9a..3272659 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -3,7 +3,7 @@ "description": "The team-architecture factory for Claude Code — a meta-skill that turns a domain description into an agent team and the skills they use, with six pre-defined team-architecture patterns (Pipeline, Fan-out/Fan-in, Expert Pool, Producer-Reviewer, Supervisor, Hierarchical Delegation). Claude Code용 팀 아키텍처 팩토리: 도메인 한 문장을 에이전트 팀과 스킬 세트로 변환하는 메타 스킬.", "version": "1.2.0", "author": { - "name": "robin", + "name": "revfactory", "url": "https://github.com/revfactory" }, "homepage": "https://github.com/revfactory/harness", diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml index b99b885..d72fba2 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yml +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -14,26 +14,40 @@ body: **Triage SLA:** we aim to label new issues within 48h and respond substantively within 72h on business days (see [CONTRIBUTING.md](../../CONTRIBUTING.md)). - - type: input - id: claude-code-version + - type: dropdown + id: runtime attributes: - label: Claude Code version - description: Output of `claude --version` (e.g. `2.3.1`) - placeholder: "2.x.y" + label: Runtime + description: Where did you hit this bug? + options: + - "Claude Code" + - "Codex" + - "Both" + - "Other / not sure" validations: required: true + - type: input + id: runtime-version + attributes: + label: Runtime version + description: Output of `claude --version`, Codex app version, or other relevant runtime version. + placeholder: "Claude Code 2.x.y / Codex version / unknown" + validations: + required: false + - type: dropdown id: experimental-flag attributes: label: Experimental Agent Teams flag state - description: Is `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` set in the shell where you hit this bug? + description: For Claude Code reports, is `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` set in the shell where you hit this bug? options: - "Yes, flag is set to 1" - "No, flag is unset" - - "I don't know / N/A" + - "N/A — Codex" + - "I don't know" validations: - required: true + required: false - type: textarea id: reproduction @@ -41,9 +55,15 @@ body: label: Reproduction steps description: Minimal steps to reproduce. Commands, config, and inputs please. placeholder: | - 1. `claude plugin marketplace add harness@harness` - 2. `export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` + Claude Code: + 1. `/plugin marketplace add revfactory/harness` + 2. `/plugin install harness@harness-marketplace` 3. `claude "build a harness for ..."` + + Codex: + 1. Open this repository in Codex + 2. Install `harness-codex` from the `Harness Local` marketplace + 3. `$harness Build a Codex harness for ...` 4. observe ... validations: required: true diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 17ad83f..52264fe 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -21,7 +21,8 @@ See CONTRIBUTING.md for branch naming, commit conventions, and SLAs. - [ ] Skill / meta-skill logic - [ ] Agent template(s) -- [ ] Plugin manifest (`.claude-plugin/plugin.json`, `marketplace.json`) +- [ ] Claude plugin manifest (`.claude-plugin/plugin.json`, `.claude-plugin/marketplace.json`) +- [ ] Codex plugin manifest (`plugins/harness-codex/.codex-plugin/plugin.json`, `.agents/plugins/marketplace.json`) - [ ] Documentation (`README.md`, `README_KO.md`, `README_JA.md`, `docs/`) - [ ] `CHANGELOG.md` - [ ] CI / GitHub Actions diff --git a/CHANGELOG.md b/CHANGELOG.md index 1be8060..9ae7d27 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,11 +5,14 @@ ## [Unreleased] ### Added +- README 3종과 기여 템플릿에 로컬 Codex 플러그인(`harness-codex`) 안내 추가 - 신규 에이전트/스킬 생성 전 중복 검토 단계 (Phase 3-0, Phase 4-0) - `references/agent-design-patterns.md` "에이전트 재사용 설계" 섹션 - `references/skill-writing-guide.md` §9 "스킬 재사용 설계" ### Changed +- 버그 리포트/PR 템플릿이 Claude Code와 Codex 포트 변경을 모두 구분하도록 수정 +- Codex Harness 스킬 frontmatter의 `description`을 YAML 유효 형식으로 수정 - Phase 선택 매트릭스에 3-0/4-0 명시 - Phase 2-3에 재사용 검토 단계 포인터 추가 - 산출물 체크리스트에 재사용 검토 항목 2개 추가 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f30728b..a9d9da2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -29,7 +29,7 @@ Different kinds of contributions go through different entry points. Pick the one ### Bug report - Open an issue using the **Bug report** form (`.github/ISSUE_TEMPLATE/bug_report.yml`). -- Required: Claude Code version, `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` flag state, reproduction steps, expected vs actual, OS. +- Required: runtime, reproduction steps, expected vs actual, OS. Include the Claude Code version and `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` flag state for Claude reports, or the Codex app/version and `harness-codex` install path for Codex reports. - Small reproductions (< 30 lines) are ideal. If your repro needs a full project, link a public fork. ### Feature request @@ -62,7 +62,8 @@ Different kinds of contributions go through different entry points. Pick the one ### Prerequisites -- Claude Code `v2.x` (Agent Teams API required) +- Claude Code `v2.x` for the Claude plugin (Agent Teams API required) +- Codex for the local `harness-codex` plugin path - Node.js `>= 18` (for local tooling used in CI) - Git @@ -74,7 +75,7 @@ Harness currently requires Claude Code's experimental Agent Teams feature. Set t export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 ``` -We track this dependency in `docs/experimental-dependency.md` (if Anthropic promotes the flag to stable, we update the README within 72h per the SLA above). +This flag applies to the Claude Code plugin only. The Codex port does not use Claude Code Agent Teams primitives. We track the Claude dependency in `docs/experimental-dependency.md` (if Anthropic promotes the flag to stable, we update the README within 72h per the SLA above). ### Local plugin link @@ -90,13 +91,17 @@ claude plugin list | grep harness Unlink with `claude plugin unlink harness` when you're done. +### Local Codex plugin + +To test the Codex port, open this repository in Codex and install `harness-codex` from the `Harness Local` marketplace. The Codex plugin lives under `plugins/harness-codex/` and is exposed through `.agents/plugins/marketplace.json`; see `docs/codex-quickstart.md`. + ### Running the meta-skill ```bash claude "build a harness for a fintech risk-assessment team" ``` -Scaffolded agents and skills land under `.claude/agents/` and `.claude/skills/` in the target project. +The Claude plugin scaffolds agents and skills under `.claude/agents/` and `.claude/skills/` in the target project. The Codex plugin generates `.agents/skills/`, `AGENTS.md`, and `_workspace/` artifacts instead. ### Tests & lints diff --git a/README.md b/README.md index b64e786..47138a6 100644 --- a/README.md +++ b/README.md @@ -35,7 +35,7 @@ Harness lives at the **L3 Meta-Factory** layer of the Claude Code ecosystem — |-------|--------------|---------------------------| | **L3 — Meta-Factory / Team-Architecture Factory** (us) | Domain sentence → agent team + skills, via 6 pre-defined team patterns | — | | L3 — Meta-Factory / Runtime-Configuration Factory | Deterministic, repeatable runtime configurations | [coleam00/Archon](https://github.com/coleam00/Archon) | -| L3 — Meta-Factory / Codex Runtime Port | Same concept, Codex runtime | [SaehwanPark/meta-harness](https://github.com/SaehwanPark/meta-harness) | +| L3 — Meta-Factory / Codex Runtime Port | Same concept, Codex runtime | Local [`harness-codex`](docs/codex-quickstart.md), [SaehwanPark/meta-harness](https://github.com/SaehwanPark/meta-harness) | | L2 — Cross-Harness Workflow | Standardize skills/rules/hooks across multiple harnesses | [affaan-m/ECC](https://github.com/affaan-m/everything-claude-code) | > Archon generates deterministic runtime configurations. Harness generates team architectures (pipeline, fan-out/fan-in, expert pool, producer-reviewer, supervisor, hierarchical delegation) plus the skills agents use. Different sub-layers of the same L3. Pick Archon for runtime determinism, Harness for team architecture, or combine them. @@ -89,6 +89,12 @@ Phase 6: Validation & Testing /plugin install harness@harness-marketplace ``` +### Codex Local Plugin + +This repository also ships a Codex-ready plugin at `plugins/harness-codex/`, exposed through +`.agents/plugins/marketplace.json`. See [docs/codex-quickstart.md](docs/codex-quickstart.md) +for local installation and usage. + ### Direct Installation as Global Skill ```shell @@ -102,6 +108,16 @@ cp -r skills/harness ~/.claude/skills/harness harness/ ├── .claude-plugin/ │ └── plugin.json # Plugin manifest +├── .agents/ +│ └── plugins/ +│ └── marketplace.json # Repo-local Codex marketplace +├── plugins/ +│ └── harness-codex/ +│ ├── .codex-plugin/ +│ │ └── plugin.json # Codex plugin manifest +│ └── skills/ +│ └── harness/ +│ └── SKILL.md # Codex-native Harness skill ├── skills/ │ └── harness/ │ ├── SKILL.md # Main skill definition (6-Phase workflow) @@ -233,7 +249,7 @@ Harness is not alone in the Claude Code / agent-framework ecosystem. The followi | Repo | Their position | Relationship to Harness | |------|----------------|-------------------------| | [coleam00/Archon](https://github.com/coleam00/Archon) | "harness builder" — deterministic, repeatable runtime configurations | **Same L3, neighbor sub-layer.** Archon is a Runtime-Configuration Factory, Harness is a Team-Architecture Factory. Pick Archon for runtime determinism, Harness for team architecture, or combine them. | -| [SaehwanPark/meta-harness](https://github.com/SaehwanPark/meta-harness) | Codex port of the same concept | **Same L3, different runtime.** Use Harness on Claude Code, meta-harness on Codex. | +| [SaehwanPark/meta-harness](https://github.com/SaehwanPark/meta-harness) | Independent Codex implementation of the same concept | **Same L3, different runtime lineage.** Use this repo's `harness-codex` plugin for the local Codex port, or compare with meta-harness as a sibling implementation. | | [affaan-m/ECC](https://github.com/affaan-m/everything-claude-code) | "Agent harness performance & workflow layer" (sits on top of existing harnesses) | **Different layer.** ECC is a standardization layer across harnesses; Harness is a factory that generates harnesses. Serial combination possible. | | [wshobson/agents](https://github.com/wshobson/agents) | Subagent / skill catalog (182 agents, 149 skills) | **Factory ↔ parts supply.** wshobson is a catalog to shop from; Harness designs the team. Absorb wshobson entries as parts inside a Harness-generated team. | | [LangGraph](https://langchain-ai.github.io/langgraph/) | State-graph orchestration, LLM-agnostic | **Different track.** LangGraph is for long-running, state-recoverable orchestration; Harness is for fast Claude-Code-native team design. | @@ -290,10 +306,11 @@ Key finding: effectiveness scales with task complexity — the harder the task,
Q3. Isn't "Claude Code only" too narrow? What about Gemini/Codex? -**A.** Currently the official runtime is Claude Code only. A Codex port of the same concept — [SaehwanPark/meta-harness](https://github.com/SaehwanPark/meta-harness) — is already public, so Codex teams can start there. Harness chose "Claude-Code-native, deep" over "multi-runtime, shallow"; cross-runtime collaboration with sibling repos (meta-harness, harness-init, OpenRig) is on the roadmap. +**A.** The primary runtime remains Claude Code, but this repository now includes a local Codex plugin at `plugins/harness-codex/`. Codex users can install it through the repo-local marketplace in `.agents/plugins/marketplace.json`; see [docs/codex-quickstart.md](docs/codex-quickstart.md). The external [SaehwanPark/meta-harness](https://github.com/SaehwanPark/meta-harness) project remains a sibling implementation worth comparing. **Evidence:** -- Codex port: [github.com/SaehwanPark/meta-harness](https://github.com/SaehwanPark/meta-harness) +- Local Codex quickstart: [docs/codex-quickstart.md](docs/codex-quickstart.md) +- Sibling Codex implementation: [github.com/SaehwanPark/meta-harness](https://github.com/SaehwanPark/meta-harness) - Cross-runtime scaffolder: [github.com/Gizele1/harness-init](https://github.com/Gizele1/harness-init)
diff --git a/README_JA.md b/README_JA.md index 542ce3e..b2d7bee 100644 --- a/README_JA.md +++ b/README_JA.md @@ -35,7 +35,7 @@ Harness は Claude Code エコシステムの **L3 Meta-Factory** 層 — 他の |----|----------|--------------| | **L3 — Meta-Factory / Team-Architecture Factory** (当プロジェクト) | ドメイン記述 → エージェントチーム + スキル、事前定義された 6 種のチームパターン経由 | — | | L3 — Meta-Factory / Runtime-Configuration Factory | 決定的で再現可能なランタイム構成 | [coleam00/Archon](https://github.com/coleam00/Archon) | -| L3 — Meta-Factory / Codex Runtime Port | 同一コンセプトの Codex ランタイム版 | [SaehwanPark/meta-harness](https://github.com/SaehwanPark/meta-harness) | +| L3 — Meta-Factory / Codex Runtime Port | 同一コンセプトの Codex ランタイム版 | ローカル [`harness-codex`](docs/codex-quickstart.md), [SaehwanPark/meta-harness](https://github.com/SaehwanPark/meta-harness) | | L2 — Cross-Harness Workflow | 複数ハーネスにまたがるスキル・ルール・フックの標準化 | [affaan-m/ECC](https://github.com/affaan-m/everything-claude-code) | > Archon は決定的なランタイム構成を生成します。Harness はチームアーキテクチャ（パイプライン・ファンアウト/ファンイン・エキスパートプール・プロデューサー-レビューア・スーパーバイザー・階層的委任）と、エージェントが使うスキルを生成します。同じ L3 の異なるサブ層です。ランタイムの決定性が欲しければ Archon、チームアーキテクチャが欲しければ Harness、あるいは両者を組み合わせて利用できます。 @@ -89,9 +89,15 @@ Phase 6: 検証とテスト #### プラグインのインストール ```shell -/plugin install harness-marketplace +/plugin install harness@harness-marketplace ``` +### Codex ローカルプラグイン + +このリポジトリには `plugins/harness-codex/` に Codex 用プラグインも含まれています。 +repo-local マーケットプレイスは `.agents/plugins/marketplace.json` にあり、インストールと利用方法は +[docs/codex-quickstart.md](docs/codex-quickstart.md) を参照してください。 + ### グローバルスキルとして直接インストール ```shell @@ -105,6 +111,16 @@ cp -r skills/harness ~/.claude/skills/harness harness/ ├── .claude-plugin/ │ └── plugin.json # プラグインマニフェスト +├── .agents/ +│ └── plugins/ +│ └── marketplace.json # repo-local Codex マーケットプレイス +├── plugins/ +│ └── harness-codex/ +│ ├── .codex-plugin/ +│ │ └── plugin.json # Codex プラグインマニフェスト +│ └── skills/ +│ └── harness/ +│ └── SKILL.md # Codex ネイティブ Harness スキル ├── skills/ │ └── harness/ │ ├── SKILL.md # メインスキル定義（6フェーズワークフロー） @@ -236,7 +252,7 @@ Harness は Claude Code / エージェントフレームワークのエコシス | リポジトリ | 相手のポジション | Harness との関係 | |------------|------------------|------------------| | [coleam00/Archon](https://github.com/coleam00/Archon) | "harness builder" — 決定的で再現可能なランタイム構成 | **同じ L3、隣のサブ層。** Archon は Runtime-Configuration Factory、Harness は Team-Architecture Factory。ランタイム決定性は Archon、チームアーキテクチャは Harness、または両者の組み合わせ。 | -| [SaehwanPark/meta-harness](https://github.com/SaehwanPark/meta-harness) | 同一コンセプトの Codex 移植 | **同じ L3、異なるランタイム。** Claude Code では Harness、Codex では meta-harness。 | +| [SaehwanPark/meta-harness](https://github.com/SaehwanPark/meta-harness) | 同一コンセプトの独立した Codex 実装 | **同じ L3、異なるランタイム系譜。** このリポジトリのローカル Codex 移植は `harness-codex` プラグインを使い、meta-harness は比較可能な兄弟実装として参照。 | | [affaan-m/ECC](https://github.com/affaan-m/everything-claude-code) | "Agent harness performance & workflow layer" — 既存ハーネスの上に乗る標準化層 | **異なる層。** ECC は複数ハーネスの上の標準化層、Harness はハーネスを生成するファクトリー。直列的に組み合わせ可能。 | | [wshobson/agents](https://github.com/wshobson/agents) | サブエージェント / スキルカタログ (182 agents, 149 skills) | **ファクトリー ↔ 部品供給。** wshobson は「ショッピングするカタログ」、Harness は「チーム設計」。Harness が生成したチーム内に wshobson のエントリを部品として取り込み可能。 | | [LangGraph](https://langchain-ai.github.io/langgraph/) | ステートグラフ・オーケストレーション、LLM-agnostic | **異なるトラック。** 長時間実行・状態復元が要なら LangGraph、Claude Code ネイティブでの素早いチーム設計が要なら Harness。 | @@ -293,10 +309,11 @@ Harness は Claude Code / エージェントフレームワークのエコシス
Q3. 「Claude Code 専用」は狭すぎませんか？ Gemini・Codex は？ -**A.** 現時点で公式のランタイムは Claude Code のみです。同一コンセプトの Codex 移植 [SaehwanPark/meta-harness](https://github.com/SaehwanPark/meta-harness) がすでに公開されており、既存の Codex チームはそちらから開始できます。Harness は「Claude Code ネイティブ・深く」を選択しており、クロスランタイムの需要は共存リポジトリ（meta-harness、harness-init、OpenRig）との連携計画としてロードマップに反映される予定です。 +**A.** 主なランタイムは引き続き Claude Code ですが、このリポジトリには `plugins/harness-codex/` のローカル Codex プラグインが含まれています。Codex ユーザーは `.agents/plugins/marketplace.json` の repo-local マーケットプレイスからインストールできます。詳しくは [docs/codex-quickstart.md](docs/codex-quickstart.md) を参照してください。[SaehwanPark/meta-harness](https://github.com/SaehwanPark/meta-harness) は比較可能な兄弟実装として残ります。 **Evidence:** -- Codex 移植: [github.com/SaehwanPark/meta-harness](https://github.com/SaehwanPark/meta-harness) +- ローカル Codex クイックスタート: [docs/codex-quickstart.md](docs/codex-quickstart.md) +- 兄弟 Codex 実装: [github.com/SaehwanPark/meta-harness](https://github.com/SaehwanPark/meta-harness) - クロスランタイム・スキャフォルダー: [github.com/Gizele1/harness-init](https://github.com/Gizele1/harness-init)
diff --git a/README_KO.md b/README_KO.md index 891994d..5e3e3b6 100644 --- a/README_KO.md +++ b/README_KO.md @@ -35,7 +35,7 @@ Harness는 Claude Code 생태계의 **L3 Meta-Factory** 층 — 다른 하네스 |------|---------|---------------| | **L3 — Meta-Factory / Team-Architecture Factory** (우리) | 도메인 설명 → 에이전트 팀 + 스킬, 6가지 사전 정의된 팀 패턴 | — | | L3 — Meta-Factory / Runtime-Configuration Factory | 결정적(deterministic)·반복 가능한 런타임 설정 생성 | [coleam00/Archon](https://github.com/coleam00/Archon) | -| L3 — Meta-Factory / Codex Runtime Port | 같은 컨셉, Codex 런타임 | [SaehwanPark/meta-harness](https://github.com/SaehwanPark/meta-harness) | +| L3 — Meta-Factory / Codex Runtime Port | 같은 컨셉, Codex 런타임 | 로컬 [`harness-codex`](docs/codex-quickstart.md), [SaehwanPark/meta-harness](https://github.com/SaehwanPark/meta-harness) | | L2 — Cross-Harness Workflow | 여러 하네스 위에서 스킬·규칙·훅을 표준화 | [affaan-m/ECC](https://github.com/affaan-m/everything-claude-code) | > Archon은 결정적 런타임 설정을 뽑아냅니다. Harness는 팀 아키텍처(파이프라인·팬아웃/팬인·전문가 풀·생성-검증·감독자·계층적 위임)와 에이전트가 쓸 스킬을 뽑아냅니다. 같은 L3의 서로 다른 서브 층입니다. 런타임 결정성은 Archon, 팀 아키텍처는 Harness, 또는 둘을 조합해서 쓰세요. @@ -89,9 +89,15 @@ Phase 6: 검증 및 테스트 #### 플러그인 설치 ```shell -/plugin install harness-marketplace +/plugin install harness@harness-marketplace ``` +### Codex 로컬 플러그인 + +이 저장소는 `plugins/harness-codex/`에 Codex용 플러그인도 함께 제공합니다. +repo-local 마켓플레이스는 `.agents/plugins/marketplace.json`에 있으며, 설치와 사용법은 +[docs/codex-quickstart.md](docs/codex-quickstart.md)를 참고하세요. + ### 글로벌 스킬로 직접 설치 ```shell @@ -105,6 +111,16 @@ cp -r skills/harness ~/.claude/skills/harness harness/ ├── .claude-plugin/ │ └── plugin.json # 플러그인 매니페스트 +├── .agents/ +│ └── plugins/ +│ └── marketplace.json # repo-local Codex 마켓플레이스 +├── plugins/ +│ └── harness-codex/ +│ ├── .codex-plugin/ +│ │ └── plugin.json # Codex 플러그인 매니페스트 +│ └── skills/ +│ └── harness/ +│ └── SKILL.md # Codex 네이티브 Harness 스킬 ├── skills/ │ └── harness/ │ ├── SKILL.md # 메인 스킬 정의 (6 Phase 워크플로우) @@ -229,7 +245,7 @@ Harness는 Claude Code / 에이전트 프레임워크 생태계에서 혼자가 | 저장소 | 저장소의 포지션 | Harness와의 관계 | |--------|-----------------|------------------| | [coleam00/Archon](https://github.com/coleam00/Archon) | "harness builder" — 결정적·반복 가능한 런타임 설정 | **같은 L3, 이웃 서브 층.** Archon은 Runtime-Configuration Factory, Harness는 Team-Architecture Factory. 런타임 결정성은 Archon, 팀 아키텍처는 Harness, 또는 조합. | -| [SaehwanPark/meta-harness](https://github.com/SaehwanPark/meta-harness) | 같은 컨셉의 Codex 포트 | **같은 L3, 다른 런타임.** Claude Code에서는 Harness, Codex에서는 meta-harness. | +| [SaehwanPark/meta-harness](https://github.com/SaehwanPark/meta-harness) | 같은 컨셉의 독립 Codex 구현 | **같은 L3, 다른 런타임 계보.** 이 저장소의 로컬 Codex 포트는 `harness-codex` 플러그인을 사용하고, meta-harness는 비교 가능한 형제 구현으로 참고. | | [affaan-m/ECC](https://github.com/affaan-m/everything-claude-code) | "Agent harness performance & workflow layer" — 기존 하네스 위에 앉는 표준화 층 | **다른 층위.** ECC는 여러 하네스 위 표준화 층, Harness는 하네스를 생성하는 팩토리. 직렬 조합 가능. | | [wshobson/agents](https://github.com/wshobson/agents) | 서브 에이전트 / 스킬 카탈로그 (182 agents, 149 skills) | **팩토리 ↔ 부품 공급.** wshobson은 "쇼핑할 카탈로그", Harness는 "팀 설계". Harness가 만든 팀에 wshobson 항목을 부품으로 흡수. | | [LangGraph](https://langchain-ai.github.io/langgraph/) | 상태 그래프 오케스트레이션, LLM-agnostic | **다른 트랙.** 장기 실행·상태 복구가 핵심이면 LangGraph, Claude Code 네이티브의 빠른 팀 설계가 핵심이면 Harness. | @@ -286,10 +302,11 @@ Harness는 Claude Code / 에이전트 프레임워크 생태계에서 혼자가
Q3. "Claude Code 전용"이 너무 좁은 것 아닌가요? Gemini·Codex는? -**A.** 현재 공식 런타임은 Claude Code 단일입니다. 같은 컨셉의 Codex 포트 [SaehwanPark/meta-harness](https://github.com/SaehwanPark/meta-harness)가 이미 공개되어 있어, 기존 Codex 팀은 그쪽에서 바로 시작할 수 있습니다. Harness는 "Claude Code 네이티브·깊게"를 택한 상태이며, 크로스 런타임 수요는 공존 저장소(meta-harness, harness-init, OpenRig)와의 연계 계획을 로드맵에 반영할 예정입니다. +**A.** 주 런타임은 여전히 Claude Code이지만, 이 저장소에는 `plugins/harness-codex/` 로컬 Codex 플러그인이 포함되어 있습니다. Codex 사용자는 `.agents/plugins/marketplace.json`의 repo-local 마켓플레이스를 통해 설치할 수 있으며, 자세한 절차는 [docs/codex-quickstart.md](docs/codex-quickstart.md)를 참고하세요. [SaehwanPark/meta-harness](https://github.com/SaehwanPark/meta-harness)는 비교 가능한 형제 구현으로 남아 있습니다. **Evidence:** -- Codex 포트: [github.com/SaehwanPark/meta-harness](https://github.com/SaehwanPark/meta-harness) +- 로컬 Codex 빠른 시작: [docs/codex-quickstart.md](docs/codex-quickstart.md) +- 형제 Codex 구현: [github.com/SaehwanPark/meta-harness](https://github.com/SaehwanPark/meta-harness) - 크로스 런타임 스캐폴더: [github.com/Gizele1/harness-init](https://github.com/Gizele1/harness-init)
diff --git a/docs/codex-quickstart.md b/docs/codex-quickstart.md new file mode 100644 index 0000000..b8819f7 --- /dev/null +++ b/docs/codex-quickstart.md @@ -0,0 +1,45 @@ +# Codex Quickstart + +This repository now includes a Codex-ready Harness plugin alongside the original Claude Code plugin. +The Codex port lives at `plugins/harness-codex/` and is exposed through the repo-local marketplace +at `.agents/plugins/marketplace.json`. + +## License + +Harness is licensed under Apache-2.0. The Codex plugin keeps the same license metadata and includes +a copy of the license at `plugins/harness-codex/LICENSE` so the plugin can be redistributed with the +required license text. + +## Install Locally + +1. Open this repository in Codex. +2. Restart Codex or refresh the plugin directory so the repo-local marketplace is discovered. +3. In the plugin directory, choose the `Harness Local` marketplace. +4. Install `harness-codex`. + +## Use + +Invoke the bundled skill explicitly: + +```text +$harness Build a Codex harness for this project. +``` + +You can also use natural prompts such as: + +```text +Build a Codex harness for a documentation review workflow. +Design a skill-based agent workflow for this repository. +Audit and improve the existing Codex harness. +``` + +## Generated Outputs + +The Codex port generates Codex-native files: + +- `.agents/skills//SKILL.md` +- `AGENTS.md` +- `_workspace/__.md` + +The skill may use Codex subagents when available. If subagents are not available, it coordinates +roles through file-based handoffs in `_workspace/`. diff --git a/docs/superpowers/plans/2026-07-06-codex-plugin-port.md b/docs/superpowers/plans/2026-07-06-codex-plugin-port.md new file mode 100644 index 0000000..581b77f --- /dev/null +++ b/docs/superpowers/plans/2026-07-06-codex-plugin-port.md @@ -0,0 +1,143 @@ +# Codex Plugin Port 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:** Add a repo-local Codex plugin package for Harness while preserving the existing Claude Code plugin. + +**Architecture:** Create a new `plugins/harness-codex/` plugin containing one Codex-native Harness skill. Expose it through a repo-local `.agents/plugins/marketplace.json` and document installation in `docs/codex-quickstart.md`. + +**Tech Stack:** Codex plugin manifest JSON, Agent Skills Markdown, repo-local Codex marketplace metadata. + +--- + +### Task 1: Codex Plugin Manifest + +**Files:** +- Create: `plugins/harness-codex/.codex-plugin/plugin.json` + +- [ ] **Step 1: Create the manifest** + +Create a minimal Codex plugin manifest that points to the bundled skills directory: + +```json +{ + "name": "harness-codex", + "version": "1.2.0", + "description": "Codex-ready Harness port that designs project-specific skill and guidance harnesses without Claude Code Agent Teams primitives.", + "skills": "./skills/" +} +``` + +- [ ] **Step 2: Inspect the manifest** + +Run: `Get-Content -LiteralPath plugins\harness-codex\.codex-plugin\plugin.json` + +Expected: Valid JSON with `name`, `version`, `description`, and `skills`. + +### Task 2: Codex Harness Skill + +**Files:** +- Create: `plugins/harness-codex/skills/harness/SKILL.md` + +- [ ] **Step 1: Write Codex-native skill instructions** + +Create a skill named `harness` with a trigger description covering harness generation, updates, audits, and Codex porting. + +The skill body must instruct Codex to: + +- Audit existing `.agents/skills`, `AGENTS.md`, and `_workspace`. +- Choose one of six team architecture patterns. +- Generate durable `.agents/skills//SKILL.md` files. +- Add only a concise pointer and change history to `AGENTS.md`. +- Use Codex subagents or file-based orchestration instead of Claude-only `TeamCreate`, `SendMessage`, and `TaskCreate`. + +- [ ] **Step 2: Inspect trigger wording** + +Run: `Select-String -LiteralPath plugins\harness-codex\skills\harness\SKILL.md -Pattern "TeamCreate|SendMessage|TaskCreate|.agents|AGENTS.md"` + +Expected: The Claude-only primitives appear only as things to avoid or translate. + +### Task 3: Repo Marketplace + +**Files:** +- Create: `.agents/plugins/marketplace.json` + +- [ ] **Step 1: Add marketplace entry** + +Create a repo-local marketplace pointing to the plugin: + +```json +{ + "name": "harness-local", + "interface": { + "displayName": "Harness Local" + }, + "plugins": [ + { + "name": "harness-codex", + "source": { + "source": "local", + "path": "./plugins/harness-codex" + }, + "policy": { + "installation": "AVAILABLE", + "authentication": "ON_INSTALL" + }, + "category": "Productivity" + } + ] +} +``` + +- [ ] **Step 2: Inspect marketplace JSON** + +Run: `Get-Content -LiteralPath .agents\plugins\marketplace.json` + +Expected: Entry includes `policy.installation`, `policy.authentication`, and `category`. + +### Task 4: Codex Quickstart + +**Files:** +- Create: `docs/codex-quickstart.md` + +- [ ] **Step 1: Document local installation and usage** + +Document that this repo now contains a Codex plugin at `plugins/harness-codex`, exposed by `.agents/plugins/marketplace.json`. + +Include: + +- Restart Codex or refresh plugins after adding the repo. +- Install `harness-codex` from the `Harness Local` marketplace. +- Invoke with `$harness` or prompts like "Build a Codex harness for this project". +- Generated project outputs use `.agents/skills`, `AGENTS.md`, and `_workspace`. + +- [ ] **Step 2: Inspect docs for stale Claude-only instructions** + +Run: `Select-String -LiteralPath docs\codex-quickstart.md -Pattern ".claude|TeamCreate|CLAUDE.md"` + +Expected: No matches. + +### Task 5: Validation + +**Files:** +- Validate: `plugins/harness-codex/.codex-plugin/plugin.json` +- Validate: `plugins/harness-codex/skills/harness/SKILL.md` +- Validate: `.agents/plugins/marketplace.json` + +- [ ] **Step 1: Run plugin validation** + +Run: `python C:\Users\splion\.codex\skills\.system\plugin-creator\scripts\validate_plugin.py plugins\harness-codex` + +Expected: Validation passes. + +- [ ] **Step 2: Run skill validation** + +Run: `python C:\Users\splion\.codex\skills\.system\skill-creator\scripts\quick_validate.py plugins\harness-codex\skills\harness` + +Expected: Validation passes. + +- [ ] **Step 3: Check git diff** + +Run: `git diff -- docs/superpowers/specs/2026-07-06-codex-plugin-port-design.md docs/superpowers/plans/2026-07-06-codex-plugin-port.md plugins/harness-codex .agents/plugins/marketplace.json docs/codex-quickstart.md` + +Expected: Diff contains only Codex port additions. diff --git a/docs/superpowers/specs/2026-07-06-codex-plugin-port-design.md b/docs/superpowers/specs/2026-07-06-codex-plugin-port-design.md new file mode 100644 index 0000000..a4bdd87 --- /dev/null +++ b/docs/superpowers/specs/2026-07-06-codex-plugin-port-design.md @@ -0,0 +1,48 @@ +# Codex Plugin Port Design + +## Goal + +Add a Codex-ready distribution path for Harness without replacing the existing Claude Code plugin. +The port should let Codex discover and install Harness as a local plugin, then use a Codex-native +skill to design project harnesses. + +## Approach + +Use a repo-local Codex plugin under `plugins/harness-codex/`. + +- Keep the current `.claude-plugin/` and `skills/harness/` files intact. +- Add `plugins/harness-codex/.codex-plugin/plugin.json`. +- Add `plugins/harness-codex/skills/harness/SKILL.md`. +- Add repo marketplace metadata at `.agents/plugins/marketplace.json`. +- Add a short Codex quickstart document. + +This keeps the Claude Code package stable while giving Codex a native install surface. + +## Codex Mapping + +Claude Code concepts map to Codex concepts as follows: + +- `.claude/skills/` -> `.agents/skills/` +- `CLAUDE.md` -> `AGENTS.md` +- `TeamCreate`, `SendMessage`, `TaskCreate` -> Codex subagents or file-based orchestration +- Claude Code plugin manifest -> Codex `.codex-plugin/plugin.json` + +The Codex skill should describe team architecture as reusable project guidance and skill files. +It must not depend on Claude-only Agent Teams primitives. + +## Output Contract + +When the Codex Harness skill runs in a target project, it should create or update: + +- `.agents/skills//SKILL.md` for generated workflows +- `AGENTS.md` with a concise trigger pointer and change history +- `_workspace/` for intermediate analysis artifacts when needed + +It may propose role-specific subagent prompts, but durable behavior should live in checked-in skills +and project guidance rather than only in a single prompt. + +## Validation + +Validate the plugin manifest and skill structure with Codex plugin and skill validation tools where +available. Also inspect trigger wording to make sure the Codex skill is clearly scoped to Harness +generation, updates, audits, and maintenance. diff --git a/plugins/harness-codex/.codex-plugin/plugin.json b/plugins/harness-codex/.codex-plugin/plugin.json new file mode 100644 index 0000000..3ec899e --- /dev/null +++ b/plugins/harness-codex/.codex-plugin/plugin.json @@ -0,0 +1,42 @@ +{ + "name": "harness-codex", + "version": "1.2.0+codex.20260706093754", + "description": "Codex-ready Harness port that designs, ports, audits, and validates project-specific skill and guidance harnesses without Claude Code Agent Teams primitives.", + "author": { + "name": "revfactory", + "url": "https://github.com/revfactory" + }, + "homepage": "https://github.com/revfactory/harness", + "repository": "https://github.com/revfactory/harness", + "license": "Apache-2.0", + "keywords": [ + "harness", + "codex", + "codex-plugin", + "agent-skills", + "team-architecture-factory", + "orchestration", + "multi-agent", + "claude-to-codex", + "workflow-design" + ], + "skills": "./skills/", + "interface": { + "displayName": "Harness for Codex", + "shortDescription": "Design, port, audit, and validate Codex-native project harnesses.", + "longDescription": "A Codex-ready port of revfactory/harness that turns a project or domain description into durable Agent Skills, AGENTS.md guidance, orchestrator workflows, and _workspace handoff artifacts. It preserves the original six team-architecture patterns, skill generation workflow, orchestration templates, QA guidance, and trigger/testing methodology while translating Claude Code team primitives into Codex-native execution.", + "developerName": "revfactory", + "category": "Productivity", + "capabilities": [ + "Write", + "Plan" + ], + "websiteURL": "https://github.com/revfactory/harness", + "defaultPrompt": [ + "Build a Codex harness for this project.", + "Port this Claude harness to Codex.", + "Audit and improve this Codex harness." + ], + "brandColor": "#2563EB" + } +} diff --git a/plugins/harness-codex/LICENSE b/plugins/harness-codex/LICENSE new file mode 100644 index 0000000..6a16d30 --- /dev/null +++ b/plugins/harness-codex/LICENSE @@ -0,0 +1,190 @@ + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to the Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by the Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding any notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + Copyright 2025 robin + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. diff --git a/plugins/harness-codex/skills/harness/SKILL.md b/plugins/harness-codex/skills/harness/SKILL.md new file mode 100644 index 0000000..2f73328 --- /dev/null +++ b/plugins/harness-codex/skills/harness/SKILL.md @@ -0,0 +1,207 @@ +--- +name: harness +description: "Build, design, port, audit, extend, or maintain a Harness-style team architecture for Codex. Use when the user asks to build a harness, design an agent team/workflow, create project-specific skills, port revfactory/harness or a Claude Code harness to Codex, inspect harness drift, sync agents/skills, improve orchestration, or validate a generated harness." +--- + +# Harness for Codex -- Team Architecture & Skill Architect + +Harness is a meta-skill that turns a domain or project description into a Codex-native team architecture: durable role/workflow skills, an orchestrator skill, concise `AGENTS.md` triggers, and `_workspace` handoff artifacts. + +This Codex port preserves the behavior of `revfactory/harness`: analyze a domain, choose one of six team architecture patterns, define specialists, generate their skills, wire an orchestrator, validate triggers, and keep the harness evolving over time. The runtime surface changes from Claude Code agent files to Codex-native project files. + +## Core Principles + +1. Generate durable files, not just chat guidance. +2. Use Codex-native surfaces: + - `.agents/skills//SKILL.md` for specialist roles, workflows, and orchestrators. + - `AGENTS.md` for the shortest possible harness pointer and change history. + - `_workspace/` for intermediate artifacts and team handoffs. +3. Preserve Harness behavior: specialist decomposition, architecture-pattern selection, orchestration, validation, trigger testing, and continuous evolution. +4. Do not require Claude Code runtime primitives such as `TeamCreate`, `SendMessage`, `TaskCreate`, `Agent(...)`, `subagent_type`, `.claude/agents`, `.claude/skills`, or `CLAUDE.md`. +5. When porting from revfactory/harness, translate behavior and structure faithfully, but adapt file locations and execution mechanics to Codex. + +## Runtime Translation + +| revfactory/harness concept | Codex port | +| --- | --- | +| `.claude/agents/{agent}.md` | `.agents/skills//SKILL.md` with role, protocol, inputs, outputs, and verification | +| `.claude/skills/{skill}/SKILL.md` | `.agents/skills//SKILL.md` | +| Orchestrator skill | `.agents/skills//SKILL.md` | +| `CLAUDE.md` pointer | concise `AGENTS.md` Harness section | +| Agent Team communication | Codex subagents when available; otherwise `_workspace` file handoffs and main-thread synthesis | +| `TeamCreate` / `TaskCreate` / `SendMessage` | explicit plan, role assignment, `_workspace` artifacts, review gates, and final synthesis | + +## Reference Routing + +Read only the reference needed for the current phase: + +- `references/agent-design-patterns.md` -- six patterns, execution modes, specialist split/reuse. +- `references/orchestrator-template.md` -- Codex orchestrator templates and handoff protocols. +- `references/team-examples.md` -- example team configurations translated to Codex. +- `references/skill-writing-guide.md` -- generated skill authoring rules. +- `references/skill-testing-guide.md` -- trigger, dry-run, and with/without skill testing. +- `references/qa-agent-guide.md` -- QA role design and boundary-crossing review. + +## Workflow + +### Phase 0: Current Harness Audit + +Read the target project for: + +- `.agents/skills/` +- `AGENTS.md` +- `_workspace/` +- legacy `.claude/agents/`, `.claude/skills/`, `CLAUDE.md` +- relevant README, docs, tests, release notes, package scripts, and domain files + +Classify the run: + +- **New Build:** no useful harness exists. +- **Extension:** existing Codex harness exists and needs new roles, skills, or workflow branches. +- **Port:** a Claude/revfactory harness exists and must be translated to Codex. +- **Maintenance:** existing harness needs audit, repair, sync, simplification, or drift correction. + +For extension and maintenance, use the existing harness rather than generating duplicates. + +### Phase 1: Domain Analysis + +Identify: + +1. project/domain goal +2. recurring task types: generation, review, editing, release, research, QA, data handling, localization, operations +3. expected inputs and outputs +4. target user's technical level and communication style +5. project risks requiring specialists or review gates +6. existing commands, tests, release paths, schemas, resource files, or safety constraints +7. existing skills that can be reused + +### Phase 2: Team Architecture Design + +Choose one primary pattern from revfactory/harness: + +| Pattern | Use When | +| --- | --- | +| Pipeline | sequential dependent tasks | +| Fan-out/Fan-in | independent specialists work in parallel before synthesis | +| Expert Pool | the right specialist depends on the request | +| Producer-Reviewer | generation needs quality review | +| Supervisor | one coordinator routes dynamic work | +| Hierarchical Delegation | broad tasks decompose into nested workflows | + +Use `references/agent-design-patterns.md` for selection rules. + +Then choose a Codex execution mode: + +- **Subagent-capable team:** use Codex subagents for independent work when the session exposes them. +- **File-handoff team:** emulate the team with role skills and `_workspace` artifacts when subagents are unavailable. +- **Hybrid:** use subagents for independent research/review and file handoffs for durable state. + +State the chosen pattern and execution mode before writing files. + +### Phase 3: Specialist Definition + +In Codex, specialists are durable skills. Create each specialist as: + +```text +.agents/skills//SKILL.md +``` + +Each specialist skill must include: + +- frontmatter with `name` and trigger-focused `description` +- core role +- working principles +- inputs and outputs +- process +- collaboration or handoff protocol +- verification criteria +- when to stop and ask the user + +Before adding a specialist, inspect existing `.agents/skills/` entries to avoid duplicate roles. + +### Phase 4: Skill Generation + +Generate any workflow/helper skills that specialists need. Use `references/skill-writing-guide.md`. + +Generated skills must: + +- be lean in the main `SKILL.md` +- use `references/` only for conditional detail +- include scripts only for repeated deterministic work +- explain why important rules exist +- include project-specific paths and commands only after verifying they fit the target repository + +### Phase 5: Integration & Orchestration + +Generate or update one orchestrator skill when the harness needs routing or multi-role coordination. + +The orchestrator must define: + +- context check: previous `_workspace` artifacts, current user request, and changed files +- task classification matrix +- chosen architecture pattern and execution mode +- role assignment +- handoff artifacts in `_workspace/` +- error handling +- retry and partial-result rules +- follow-up behavior such as "rerun", "update", "fix only this part", and "use previous result" +- normal and error test scenarios + +Use `references/orchestrator-template.md`. + +Update `AGENTS.md` with only a pointer: + +```markdown +## Harness: + +Use the generated `.agents/skills/...` harness when the request involves . +For simple factual questions or tiny lookups, answer directly. + +Architecture pattern: . . + +**Change history** +| Date | Change | Scope | Reason | +| --- | --- | --- | --- | +| YYYY-MM-DD | Initial Codex harness | `.agents/skills`, `AGENTS.md`, `_workspace` | User requested a harness | +``` + +### Phase 6: Validation & Testing + +Use `references/skill-testing-guide.md` and validate: + +1. structure: files exist where promised +2. frontmatter: every generated skill has `name` and `description` +3. trigger quality: should-trigger and should-not-trigger prompts +4. orchestration: no dead handoff paths +5. Codex-native surface: no required Claude-only primitives +6. project fit: paths, tests, release assets, locales, and safety gates match the target +7. QA: reviewer skill exists when quality, security, release, storage, localization, or integration risk is meaningful + +Practical Claude-only search: + +```powershell +Select-String -Path .agents\skills\*\SKILL.md,AGENTS.md -Pattern "TeamCreate|SendMessage|TaskCreate|Agent\(|subagent_type|CLAUDE.md|\.claude" +``` + +Those terms are allowed only in migration notes that explain what was translated. + +### Phase 7: Harness Evolution + +Harness is not static. When the user gives feedback or repeated failures appear: + +1. classify the feedback: output quality, role design, workflow order, team composition, trigger gap, validation gap +2. update the affected skill or orchestrator, not every file +3. update the `AGENTS.md` change history +4. rerun the relevant validation checks + +For maintenance requests, audit the current `.agents/skills/` and `AGENTS.md` first, report drift, then patch only what is needed. + +## Completion Report + +When done, report: + +- classification: New Build, Extension, Port, or Maintenance +- chosen architecture pattern and Codex execution mode +- files created or changed +- validation performed +- any remaining gaps or user decisions needed diff --git a/plugins/harness-codex/skills/harness/references/agent-design-patterns.md b/plugins/harness-codex/skills/harness/references/agent-design-patterns.md new file mode 100644 index 0000000..21eaa4a --- /dev/null +++ b/plugins/harness-codex/skills/harness/references/agent-design-patterns.md @@ -0,0 +1,137 @@ +# Agent Design Patterns for Codex + +This file translates the six revfactory/harness team architecture patterns into Codex-native execution. + +## Execution Modes + +| Mode | Use When | Codex Mechanics | +| --- | --- | --- | +| Subagent-capable team | independent specialists can run in parallel and subagent tools are available | assign role prompts to subagents, keep durable outputs in `_workspace/`, synthesize in main thread | +| File-handoff team | subagents are unavailable or durable audit trail matters more than parallelism | process specialist skills sequentially, writing `_workspace/__.md` | +| Hybrid | some phases are parallel and others need durable sequential review | use subagents for independent phases and file handoffs for integration/review | + +Codex does not require generated harnesses to call `TeamCreate`, `SendMessage`, or `TaskCreate`. Preserve the same coordination behavior with explicit plans, role skills, subagents when available, and `_workspace` artifacts. + +## Six Patterns + +### Pipeline + +Sequential dependent work. + +Use for: + +- spec -> plan -> implementation -> review +- collect -> normalize -> analyze -> report +- package -> verify -> publish + +Codex design: + +- one orchestrator skill +- specialist skills for each phase +- `_workspace` artifacts passed from phase to phase + +### Fan-out/Fan-in + +Parallel independent specialists before synthesis. + +Use for: + +- multi-angle research +- code review split by security, architecture, performance, and tests +- product audit split by UX, accessibility, copy, and implementation + +Codex design: + +- subagents when available +- one synthesis step +- each specialist writes a separate `_workspace` finding file + +### Expert Pool + +Only one or two specialists are needed per request. + +Use for: + +- projects with distinct recurring work types +- provider versus UI versus release versus docs changes +- support workflows where request classification matters + +Codex design: + +- concise `AGENTS.md` routing +- specialist skills with strong descriptions +- optional QA reviewer for risky changes + +### Producer-Reviewer + +One role creates, another reviews. + +Use for: + +- generated code or docs that need quality gates +- localization +- release packaging +- security-sensitive changes + +Codex design: + +- producer skill +- reviewer skill +- verification and stop-and-ask gates + +### Supervisor + +A coordinator routes dynamic work. + +Use for: + +- multi-branch feature cycles +- workflows where follow-up requests should reuse prior artifacts +- mixed task types that may trigger several specialists + +Codex design: + +- thin orchestrator skill +- specialist skills for branches +- `_workspace` context check at the start + +### Hierarchical Delegation + +Broad tasks decompose into nested sub-workflows. + +Use for: + +- large migrations +- multi-module systems +- research-to-delivery pipelines + +Codex design: + +- top-level orchestrator +- phase orchestrators or specialist groups +- explicit dependencies and `_workspace` structure + +## Specialist Split Criteria + +Split a role when at least two are true: + +- distinct expertise is needed +- work can happen independently +- the role needs different context or files +- the role will be reused often +- separate review reduces risk + +Merge roles when: + +- they always run together +- handoff overhead is higher than benefit +- one skill can express the workflow clearly + +## Reuse Check + +Before creating a new specialist: + +1. list existing `.agents/skills/*/SKILL.md` +2. compare purpose, triggers, inputs, outputs, and verification +3. update an existing skill when the role is substantially the same +4. create a new skill only when the boundary is durable diff --git a/plugins/harness-codex/skills/harness/references/orchestrator-template.md b/plugins/harness-codex/skills/harness/references/orchestrator-template.md new file mode 100644 index 0000000..0ae292b --- /dev/null +++ b/plugins/harness-codex/skills/harness/references/orchestrator-template.md @@ -0,0 +1,108 @@ +# Codex Orchestrator Template + +Use this template for generated orchestrator skills. + +## Frontmatter + +```markdown +--- +name: -orchestrator +description: "Route and coordinate work. Use for
, follow-ups such as rerun/update/fix, and multi-step workflows that require specialist skills." +--- +``` + +## Required Sections + +### Purpose + +State the workflow this orchestrator coordinates and the architecture pattern. + +### Phase 0: Context Check + +Check: + +- `git status --short` +- existing `_workspace/` artifacts +- relevant changed files or user-provided inputs +- whether this is initial run, follow-up, partial rerun, or maintenance + +### Phase 1: Task Classification + +Use a matrix: + +| Trigger | Task Type | Specialist | Follow-up | +| --- | --- | --- | --- | +| | | | | + +### Phase 2: Role Assignment + +For subagent-capable sessions: + +- assign independent work to subagents with clear role prompts +- require each subagent to write durable output under `_workspace/` + +For file-handoff sessions: + +- run specialist skills sequentially +- write `_workspace/__.md` + +### Phase 3: Integration + +Read specialist artifacts, resolve conflicts, and synthesize the final output. + +When findings conflict: + +- preserve both sources +- state the conflict +- choose only when evidence supports the choice +- ask the user when a product decision is required + +### Error Handling + +Default rule: + +- retry once when a specialist or command fails for an incidental reason +- if it fails again, continue only when the missing result is non-blocking +- report missing or skipped outputs explicitly +- never delete conflicting or partial artifacts silently + +### Follow-up Behavior + +Support: + +- "rerun" +- "update" +- "fix only this part" +- "use previous result" +- "continue from workspace" + +If `_workspace/` exists and the request is partial, reuse relevant artifacts instead of restarting. + +### Verification + +List commands and checks specific to the target project. + +### Test Scenarios + +Include: + +- normal flow +- partial rerun +- error or ambiguity flow + +## Data Handoff Convention + +Use: + +```text +_workspace/__.md +``` + +Examples: + +- `_workspace/01_researcher_sources.md` +- `_workspace/02_builder_plan.md` +- `_workspace/03_qa_findings.md` +- `_workspace/04_orchestrator_summary.md` + +Final outputs may live outside `_workspace/` when they are user-facing deliverables. diff --git a/plugins/harness-codex/skills/harness/references/qa-agent-guide.md b/plugins/harness-codex/skills/harness/references/qa-agent-guide.md new file mode 100644 index 0000000..40d3c95 --- /dev/null +++ b/plugins/harness-codex/skills/harness/references/qa-agent-guide.md @@ -0,0 +1,56 @@ +# QA Specialist Guide + +Use this guide when a generated harness needs a reviewer or QA specialist. + +## When To Add QA + +Add a QA/reviewer skill when the project has meaningful risk in: + +- provider or API integration +- release packaging or publishing +- localization +- security, credentials, or secrets +- storage or migrations +- UI workflows +- generated content quality +- cross-module contracts + +## QA Role + +QA should verify behavior across boundaries, not just check that files exist. + +Examples: + +- API response shape versus UI parser +- localization keys versus resource files +- package script outputs versus README download names +- provider error handling versus user-facing status text +- stored settings versus secret-redaction policy + +## Process + +1. inspect the diff or generated artifacts +2. classify risk +3. read both sides of each boundary +4. run targeted checks where possible +5. report findings ordered by severity +6. include verification gaps + +## Output Format + +Use review style: + +- findings first +- file and line references when possible +- severity ordering +- concise verification summary +- residual risks + +## Stop And Ask + +Ask the user when: + +- QA depends on private logs or credentials +- a finding requires product policy input +- release approval or destructive action is involved +- expected behavior cannot be inferred from code or docs diff --git a/plugins/harness-codex/skills/harness/references/skill-testing-guide.md b/plugins/harness-codex/skills/harness/references/skill-testing-guide.md new file mode 100644 index 0000000..6aaf944 --- /dev/null +++ b/plugins/harness-codex/skills/harness/references/skill-testing-guide.md @@ -0,0 +1,60 @@ +# Skill Testing Guide + +Use this guide to validate generated Codex harness skills. + +## Structural Tests + +Check: + +- every skill has `SKILL.md` +- frontmatter contains `name` and `description` +- descriptions are trigger-focused +- references mentioned in `SKILL.md` exist +- `AGENTS.md` is concise + +## Trigger Tests + +For each skill, write: + +- 8 to 10 should-trigger prompts +- 8 to 10 should-not-trigger near-miss prompts + +Near-miss prompts should be plausible boundary cases, not obviously unrelated tasks. + +## Dry Run Tests + +For an orchestrator: + +1. simulate a normal user request +2. trace phase order +3. verify each role has an input +4. verify each handoff artifact has a reader +5. trace an error path +6. trace a partial rerun + +## With-Skill vs Without-Skill + +When evaluating whether a generated skill adds value: + +- run or mentally compare the same prompt with and without the generated skill +- judge whether the skill improves correctness, completeness, safety, or repeatability +- generalize fixes rather than patching for one example + +## Project-Fit Tests + +Confirm: + +- file paths exist or are discovery patterns +- test commands match the repository +- package names and release assets match the target +- locale lists match actual resources +- provider names and APIs match target code +- no source-project-only terms remain + +## Codex-Native Search + +```powershell +Select-String -Path .agents\skills\*\SKILL.md,AGENTS.md -Pattern "TeamCreate|SendMessage|TaskCreate|Agent\(|subagent_type|CLAUDE.md|\.claude" +``` + +Allowed only in migration notes. diff --git a/plugins/harness-codex/skills/harness/references/skill-writing-guide.md b/plugins/harness-codex/skills/harness/references/skill-writing-guide.md new file mode 100644 index 0000000..e62238f --- /dev/null +++ b/plugins/harness-codex/skills/harness/references/skill-writing-guide.md @@ -0,0 +1,76 @@ +# Skill Writing Guide + +Use this guide when generating `.agents/skills//SKILL.md`. + +## Structure + +Each generated skill must include: + +- YAML frontmatter with `name` and `description` +- purpose +- inputs +- outputs +- process +- verification +- stop-and-ask conditions + +## Description + +Descriptions are trigger surfaces. Include: + +- domain/project name +- concrete verbs +- common user phrasing +- follow-up words when relevant: rerun, update, fix, review, release, localize, validate +- near-boundary context to avoid stealing unrelated requests + +## Body Style + +Write direct, operational instructions. + +Good skill bodies: + +- explain why important rules exist +- stay lean +- use project-specific paths only after verifying them +- include clear verification commands +- say when to ask the user + +Avoid: + +- generic role descriptions without process +- copied paths from another project +- huge examples in the main file +- Claude Code-only runtime snippets + +## Progressive Disclosure + +Keep the main `SKILL.md` focused. Move detail into `references/` when: + +- examples are long +- provider/release/platform variants are conditional +- a command catalog is large +- a domain table is useful but not always needed + +Reference files should be read only when the main skill says they are relevant. + +## Reuse Design + +Before creating a skill: + +1. inspect existing `.agents/skills/` +2. compare purpose and trigger boundary +3. update the existing skill if it is the same durable role +4. create a new skill only for a distinct recurring workflow or specialist + +## Stop And Ask + +Add stop-and-ask conditions for: + +- destructive operations +- credential or private-log needs +- ambiguous product choices +- release/version mismatch +- missing required release notes or artifacts +- storing or displaying secrets +- translation choices that cannot be inferred diff --git a/plugins/harness-codex/skills/harness/references/team-examples.md b/plugins/harness-codex/skills/harness/references/team-examples.md new file mode 100644 index 0000000..2337ff3 --- /dev/null +++ b/plugins/harness-codex/skills/harness/references/team-examples.md @@ -0,0 +1,76 @@ +# Team Examples + +These examples mirror revfactory/harness team designs, translated to Codex-native skills and `_workspace` handoffs. + +## Deep Research + +Pattern: Fan-out/Fan-in. + +Skills: + +- `research-source-finder` +- `research-evidence-reviewer` +- `research-synthesizer` +- `research-qa-reviewer` + +Handoffs: + +- `_workspace/01_source_finder_sources.md` +- `_workspace/02_evidence_reviewer_notes.md` +- `_workspace/03_synthesizer_report.md` +- `_workspace/04_qa_findings.md` + +## Website Development + +Pattern: Pipeline + Producer-Reviewer. + +Skills: + +- `web-product-planner` +- `web-frontend-builder` +- `web-backend-builder` +- `web-qa-reviewer` + +Handoffs: + +- plan -> implementation -> QA -> final summary + +## Code Review + +Pattern: Fan-out/Fan-in. + +Skills: + +- `review-architecture` +- `review-security` +- `review-performance` +- `review-tests` +- `review-synthesizer` + +Each reviewer writes a separate finding file, then synthesizer merges findings by severity. + +## Documentation Generation + +Pattern: Pipeline. + +Skills: + +- `docs-api-analyzer` +- `docs-writer` +- `docs-example-author` +- `docs-reviewer` + +The orchestrator preserves source references and requires review before final docs are delivered. + +## Release Workflow + +Pattern: Supervisor + Producer-Reviewer. + +Skills: + +- `release-coordinator` +- `release-packager` +- `release-notes-writer` +- `release-qa-reviewer` + +The coordinator owns destructive gates, version checks, artifact checks, and final user confirmation.