Skip to content

armgit / ECC

Public Imported from GitHub
0

The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.

docs(astra-review): add day-to-day workflow for a separate project

kenima-arc5b4ebcf0f9b6
diff --git a/docs/ASTRA-REVIEW-GUIDE.md b/docs/ASTRA-REVIEW-GUIDE.md
index f663938cf..78cb6e043 100644
--- a/docs/ASTRA-REVIEW-GUIDE.md
+++ b/docs/ASTRA-REVIEW-GUIDE.md
@@ -48,6 +48,63 @@ Plugin commands carry the `ecc:` prefix. With a manual (non-plugin) install the
Every invocation is your consent to send that diff to OpenAI. Do not run it on code you are not allowed to share. To see exactly what would leave the machine, run the script with `--dry-run` (see below).
+## Day-to-day workflow in your own project
+
+The project does not need to live inside the ECC checkout. ECC is a user-scope plugin, so `/ecc:astra-review` is available from any directory, and the script reviews whichever git repository Claude Code was started in. Keep your project outside the ECC tree so its diffs are not mixed with ECC's.
+
+### 0. One-time preparation (in the ECC checkout)
+
+```bash
+# refresh the installed plugin whenever the ECC checkout changed
+claude plugin uninstall ecc@ecc && claude plugin install ecc@ecc
+
+# confirm Codex CLI is installed and logged in with ChatGPT (otherwise: codex login)
+codex --version
+grep auth_mode ~/.codex/auth.json
+```
+
+### 1. Create the project and start Claude Code there
+
+```bash
+mkdir -p ~/work/arm && cd ~/work/arm
+git init # required: the review reads git diffs
+claude # this directory becomes the project root
+```
+
+Run `/init` inside Claude Code if you want a project `CLAUDE.md`. ECC hooks and commands apply here because they are installed at user scope.
+
+### 2. Implement as usual
+
+Ask Claude Code for the change, or start with `/ecc:plan` or `/ecc:tdd`.
+
+### 3. Ask Astra for a review
+
+```text
+/ecc:astra-review # uncommitted changes
+/ecc:astra-review --base main # the whole branch, before a PR
+/ecc:astra-review Focus on interrupt handling # extra instructions
+```
+
+Claude fixes confirmed CRITICAL/HIGH findings and re-runs, up to three rounds. To inspect what would be sent without sending it:
+
+```bash
+node ~/.claude/plugins/cache/ecc/ecc/<version>/scripts/astra-review.js --dry-run | less
+```
+
+(`<version>` is the plugin version shown by `claude plugin list`, for example `2.2.1`. Inside a command, the same path is `${CLAUDE_PLUGIN_ROOT}/scripts/astra-review.js`.)
+
+### 4. Commit once the verdict is PASS
+
+Ask Claude Code to commit, or run `git commit` yourself.
+
+### 5. Optionally gate the push
+
+```bash
+node ~/.claude/plugins/cache/ecc/ecc/<version>/scripts/astra-review.js --consent-to-openai --base main && git push
+```
+
+Reminders: the command name carries the `ecc:` prefix; every run sends the diff to OpenAI and takes a few minutes; re-do step 0 after each ECC update because the plugin cache is refreshed only on version changes.
+
## Scopes
| Flag | Reviews | Use it for |
diff --git a/docs/ja-JP/ASTRA-REVIEW-GUIDE.md b/docs/ja-JP/ASTRA-REVIEW-GUIDE.md
index 5aaa46245..8c2fb34a2 100644
--- a/docs/ja-JP/ASTRA-REVIEW-GUIDE.md
+++ b/docs/ja-JP/ASTRA-REVIEW-GUIDE.md
@@ -48,6 +48,63 @@ claude plugin uninstall ecc@ecc && claude plugin install ecc@ecc
コマンドを実行することが、その差分を OpenAI に送ることへの同意になります。共有が許されないコードには使わないでください。何が外に出るかを事前に見たいときは、後述のスクリプトを `--dry-run` で実行します。
+## 自分のプロジェクトでの日常の使い方
+
+プロジェクトを ECC のチェックアウト配下に置く必要はありません。ECC はユーザースコープのプラグインなので `/ecc:astra-review` はどのディレクトリからでも使え、スクリプトは Claude Code を起動した git リポジトリをレビューします。ECC の差分と混ざらないよう、プロジェクトは ECC ツリーの外に置いてください。
+
+### 0. 一度だけの準備(ECC のチェックアウトで)
+
+```bash
+# ECC のチェックアウトを更新したら、インストール済みプラグインを入れ直す
+claude plugin uninstall ecc@ecc && claude plugin install ecc@ecc
+
+# Codex CLI が入っていて ChatGPT でログイン済みか確認(未ログインなら codex login)
+codex --version
+grep auth_mode ~/.codex/auth.json
+```
+
+### 1. プロジェクトを作り、そこで Claude Code を起動する
+
+```bash
+mkdir -p ~/work/arm && cd ~/work/arm
+git init # 必須。レビューは git の差分を読む
+claude # このディレクトリがプロジェクトルートになる
+```
+
+プロジェクト用の `CLAUDE.md` が欲しければ Claude Code 内で `/init` を実行します。ECC の hooks とコマンドはユーザースコープで入っているので、ここでもそのまま効きます。
+
+### 2. いつも通り実装する
+
+Claude Code に変更を依頼するか、`/ecc:plan` や `/ecc:tdd` から始めます。
+
+### 3. Astra にレビューを頼む
+
+```text
+/ecc:astra-review # コミットされていない変更
+/ecc:astra-review --base main # PR 前にブランチ全体
+/ecc:astra-review 割り込み処理を重点的に # 追加指示
+```
+
+Claude は確認できた CRITICAL/HIGH を修正して再実行し、最大 3 ラウンド回します。送らずに送信内容だけ確認するには次を実行します。
+
+```bash
+node ~/.claude/plugins/cache/ecc/ecc/<version>/scripts/astra-review.js --dry-run | less
+```
+
+(`<version>` は `claude plugin list` に表示されるプラグインのバージョンで、例えば `2.2.1` です。コマンド内では同じパスを `${CLAUDE_PLUGIN_ROOT}/scripts/astra-review.js` で参照します。)
+
+### 4. 判定が PASS になったらコミットする
+
+Claude Code にコミットを頼むか、自分で `git commit` します。
+
+### 5. 必要ならプッシュをゲートする
+
+```bash
+node ~/.claude/plugins/cache/ecc/ecc/<version>/scripts/astra-review.js --consent-to-openai --base main && git push
+```
+
+注意: コマンド名には `ecc:` の接頭辞が付きます。実行するたびに差分が OpenAI に送られ、数分かかります。プラグインのキャッシュはバージョンが変わったときしか更新されないので、ECC を更新するごとに手順 0 をやり直してください。
+
## スコープ
| フラグ | レビュー対象 | 用途 |