[codex] Make release and platform guides runnable

Platform/Claude-Code-Prompt.md

@@ -15,7 +15,7 @@ When working with Google Jules:
 - Prompts sent through `create-session`, `send-message`, `resume`, and `request-pr-rework` are wrapped with a strict-scope contract by default.
 - If the task is ambiguous or appears to require out-of-scope work, ask a clarifying question instead of broadening the task.
 - Use `--scope-note` and `--non-goal` when you need extra task boundaries.
-- Use `summary`, `cleanup-report`, `close-ready-report`, and `notify-close-plan --markdown` to keep users informed.
+- Use `summary`, `cleanup-report --markdown`, `close-ready-report --markdown`, and `notify-close-plan --markdown` to keep users informed.
 - Never close or delete a Jules session without explicit user confirmation.
 - Before merge-aware cleanup actions, verify GitHub auth with `gh-auth-check --compact`.
 - Summarize long JSON outputs into concise user-facing updates.
@@ -43,7 +43,7 @@ When working with Google Jules:
 - Prompts sent through `create-session`, `send-message`, `resume`, and `request-pr-rework` are wrapped with a strict-scope contract by default.
 - If the task is ambiguous or appears to require out-of-scope work, ask a clarifying question instead of broadening the task.
 - Use `--scope-note` and `--non-goal` when you need extra task boundaries.
-- Use `summary`, `cleanup-report`, `close-ready-report`, and `notify-close-plan --markdown` to keep users informed.
+- Use `summary`, `cleanup-report --markdown`, `close-ready-report --markdown`, and `notify-close-plan --markdown` to keep users informed.
 - Never close or delete a Jules session without explicit user confirmation.
 - Before merge-aware cleanup actions, verify GitHub auth with `gh-auth-check --compact`.
 - Summarize long JSON outputs into concise user-facing updates.

Platform/Claude-Code.md

@@ -24,6 +24,16 @@ Claude Code에서는 이 저장소의 핵심 자산을 “프로젝트 문서 +
 Use the local project guide at google-jules-control/SKILL.md. Prefer the bundled Jules control script for all Jules operations. Start with doctor, resolve the repo to a Jules source, then continue with session creation or reporting.
 ```
 
+### Setup checks와 완료 기준
+
+- Claude Code 프로젝트 문서나 프롬프트가 `google-jules-control/SKILL.md`를 참조하는지 확인
+- Claude Code shell에서 `doctor --compact`가 `.env`와 `JULES_API_KEY`를 읽는지 확인. 통과 기준은 `dotenv=yes api_key=yes api_ready=yes`
+- long-running 명령은 중간 상태를 `summary`로 요약하고 필요하면 `wait`를 사용
+- 긴 JSON 출력은 사용자에게 그대로 붙이지 말고 핵심 상태만 요약
+- 사용자 검토에는 `--markdown`, 파일 보관이나 자동화에는 `export --output` 사용
+
+완료 기준: Claude Code가 이 문서와 `SKILL.md`만 보고 source 해석, 세션 생성, 세션 요약, markdown/JSON 출력 선택을 수행할 수 있어야 합니다.
+
 ## EN
 
 ### Adaptation Model
@@ -47,3 +57,13 @@ In Claude Code, the safest migration model is to treat this repository as a comb
 ```text
 Use the local project guide at google-jules-control/SKILL.md. Prefer the bundled Jules control script for all Jules operations. Start with doctor, resolve the repo to a Jules source, then continue with session creation or reporting.
 ```
+
+### Setup Checks And Done Criteria
+
+- Confirm Claude Code project docs or prompts point to `google-jules-control/SKILL.md`
+- Confirm Claude Code shell execution can read `.env` and `JULES_API_KEY` with `doctor --compact`; pass only when it includes `dotenv=yes api_key=yes api_ready=yes`
+- Summarize intermediate state for long-running commands with `summary`, and use `wait` when appropriate
+- Do not paste long raw JSON to users; summarize the operational state first
+- Use `--markdown` for human review and `export --output` for archived or automated JSON
+
+Done criteria: Claude Code can use only this guide and `SKILL.md` to resolve a source, create a session, summarize it, and choose markdown versus JSON output correctly.

Platform/Codex.md

@@ -28,6 +28,16 @@ python3 google-jules-control/scripts/jules_api.py create-session ...
 python3 google-jules-control/scripts/jules_api.py summary --session sessions/SESSION_ID
 ```
 
+### Setup checks와 완료 기준
+
+- `$google-jules-control` 또는 `google-jules-control/SKILL.md`가 Codex 컨텍스트에서 발견되는지 확인
+- Codex shell에서 `doctor --compact`가 `.env`와 `JULES_API_KEY`를 읽는지 확인. 통과 기준은 `dotenv=yes api_key=yes api_ready=yes`
+- long-running 세션은 `wait` 또는 반복 `summary`로 상태를 갱신
+- 사용자 보고에는 `cleanup-report --markdown`, `close-ready-report --markdown`, `notify-close-plan --markdown` 사용
+- 구조화된 결과가 필요할 때만 JSON 원문이나 `export --output` 사용
+
+완료 기준: Codex가 source 해석, 세션 생성, 세션 요약, markdown 보고를 사용자에게 간결하게 전달하고, JSON 원문이나 `export --output`은 구조화/보관 용도로만 사용할 수 있어야 합니다.
+
 ## EN
 
 ### Current Reference Platform
@@ -55,3 +65,13 @@ python3 google-jules-control/scripts/jules_api.py repo-to-source --repo owner/re
 python3 google-jules-control/scripts/jules_api.py create-session ...
 python3 google-jules-control/scripts/jules_api.py summary --session sessions/SESSION_ID
 ```
+
+### Setup Checks And Done Criteria
+
+- Confirm `$google-jules-control` or `google-jules-control/SKILL.md` is discoverable in the Codex context
+- Confirm Codex shell execution can read `.env` and `JULES_API_KEY` with `doctor --compact`; pass only when it includes `dotenv=yes api_key=yes api_ready=yes`
+- Monitor long-running sessions with `wait` or repeated `summary`
+- Use `cleanup-report --markdown`, `close-ready-report --markdown`, and `notify-close-plan --markdown` for user-facing reports
+- Use raw JSON or `export --output` only when structured output is needed
+
+Done criteria: Codex can resolve a source, create a session, summarize the session, present markdown reports concisely, and reserve raw JSON or `export --output` for structured or archival use.

Platform/Google-Antigravity.md

@@ -24,6 +24,16 @@ Google Antigravity에서는 이 저장소를 “에이전트가 읽는 운영 
 Read google-jules-control/SKILL.md first. Use the bundled Jules control script for session management, reporting, and cleanup. Prefer markdown reports for human review and require explicit confirmation before any session deletion.
 ```
 
+### Setup checks와 완료 기준
+
+- Antigravity 작업공간에 `google-jules-control/SKILL.md`와 실행 스크립트 경로가 노출되는지 확인
+- shell 실행 컨텍스트에서 `doctor --compact`가 `.env`와 `JULES_API_KEY`를 읽는지 확인. 통과 기준은 `dotenv=yes api_key=yes api_ready=yes`
+- long-running 세션은 `wait` 또는 반복 `summary`를 카드/패널에 갱신 가능한 형태로 표시
+- 카드형 UI에는 `--markdown` 보고서를 우선 사용
+- 자동화나 디버깅에는 JSON 출력 또는 `export --output`을 별도로 보관
+
+완료 기준: Antigravity가 source 해석, 세션 생성, 세션 상태 갱신, markdown 보고, JSON 또는 `export --output` 보관을 구분해서 처리할 수 있어야 합니다.
+
 ## EN
 
 ### Adaptation Model
@@ -47,3 +57,13 @@ For Google Antigravity, this repository works best as an agent-readable operatin
 ```text
 Read google-jules-control/SKILL.md first. Use the bundled Jules control script for session management, reporting, and cleanup. Prefer markdown reports for human review and require explicit confirmation before any session deletion.
 ```
+
+### Setup Checks And Done Criteria
+
+- Confirm Antigravity workspace exposes `google-jules-control/SKILL.md` and the execution script path
+- Confirm the shell execution context can read `.env` and `JULES_API_KEY` with `doctor --compact`; pass only when it includes `dotenv=yes api_key=yes api_ready=yes`
+- Show long-running sessions through `wait` or repeated `summary` in a card/panel-friendly way
+- Prefer `--markdown` reports for card-style UI review
+- Keep JSON output or `export --output` separate for automation or debugging
+
+Done criteria: Antigravity can resolve a source, create a session, update session status, render markdown reports, and keep JSON or `export --output` separate for archival/debugging.

Platform/README.md

@@ -26,6 +26,20 @@
 - 프롬프트, 도구 호출, 인증, 작업 흐름 차이를 정리하기
 - 동일한 Jules 제어 운영 절차를 다른 에이전트에서도 재현하기
 
+공통 setup checks:
+
+- 스킬 등록 또는 프로젝트 문서 주입 경로가 명확한지 확인
+- `.env`의 `JULES_API_KEY`를 해당 플랫폼의 실행 컨텍스트에서 읽을 수 있는지 `doctor --compact`로 확인. 통과 기준은 `dotenv=yes api_key=yes api_ready=yes`
+- `repo-to-source --repo owner/repo --compact` 결과를 다음 명령에 넘길 수 있는지 확인
+- long-running 작업은 `wait` 또는 반복 `summary`로 갱신 상태를 보여줄 수 있는지 확인
+- 사람 검토용 출력은 `--markdown`, 자동화용 출력은 JSON 또는 `export --output`으로 처리할 수 있는지 확인
+
+완료 기준:
+
+- 플랫폼 가이드만 보고 `doctor`, `repo-to-source`, `create-session`, `summary` 순서를 재현할 수 있음
+- `.env`나 JSON 원문을 사용자에게 노출하지 않고 필요한 상태만 요약할 수 있음
+- 삭제, close, cancel 같은 destructive action 전에 사용자 확인을 요구함
+
 ## EN
 
 This folder contains platform adaptation guides for using the `google-jules-control` workflow beyond Codex.
@@ -51,3 +65,17 @@ Goals:
 - Translate this repository's operating model into platform-specific terms
 - Clarify prompt, tool, auth, and workflow differences
 - Preserve the same Jules control workflow across multiple agent environments
+
+Shared setup checks:
+
+- Confirm the skill registration or project-document injection path is explicit
+- Confirm the platform execution context can read `JULES_API_KEY` from `.env` with `doctor --compact`; pass only when it includes `dotenv=yes api_key=yes api_ready=yes`
+- Confirm `repo-to-source --repo owner/repo --compact` output can be handed to the next command
+- Confirm long-running work can be monitored with `wait` or repeated `summary`
+- Confirm human review uses `--markdown`, while automation uses JSON or `export --output`
+
+Done criteria:
+
+- A user can reproduce the `doctor`, `repo-to-source`, `create-session`, `summary` sequence from the platform guide alone
+- The platform can summarize status without exposing `.env` contents or dumping raw JSON by default
+- Destructive actions such as delete, close, or cancel require user confirmation first

docs/release-checklist.md

@@ -13,38 +13,81 @@ Use this checklist before sharing or publishing the skill.
 - 저장소 루트 `.gitignore`에 `.env`가 포함되는지 확인 / Confirm the repository-root `.gitignore` excludes `.env`
 - 저장소 루트와 스킬 폴더에 실제 시크릿이 추적되지 않는지 확인 / Ensure no real secrets are tracked in the repository root or skill folder
 
-## 검증 / Validation
+## Fresh Checkout Validation / 새 checkout 검증
+
+아래 명령은 이 저장소 루트의 fresh checkout에서 그대로 실행 가능해야 합니다. 실제 Jules 계정이나 target repository가 필요한 검증은 다음 섹션으로 분리합니다.
+The commands below must run as-is from a fresh checkout of this repository root. Checks that require a real Jules account or target repository are separated into the next section.
 
 ```bash
 python3 -m py_compile google-jules-control/scripts/jules_api.py
 python3 -m unittest discover -s tests
-python3 /path/to/quick_validate.py google-jules-control
+
+python3 google-jules-control/scripts/jules_api.py --help >/tmp/google-jules-skill-help.txt
+python3 google-jules-control/scripts/jules_api.py doctor --help >/tmp/google-jules-skill-doctor-help.txt
+python3 google-jules-control/scripts/jules_api.py check-pr-readiness --help >/tmp/google-jules-skill-pr-help.txt
+python3 google-jules-control/scripts/jules_api.py request-pr-rework --help >/tmp/google-jules-skill-rework-help.txt
+python3 google-jules-control/scripts/jules_api.py cleanup-report --help >/tmp/google-jules-skill-cleanup-help.txt
+python3 google-jules-control/scripts/jules_api.py close-ready-report --help >/tmp/google-jules-skill-close-ready-help.txt
 ```
 
-`v0.2.0` focus / `v0.2.0` 중점 확인:
+Packaging checks / 패키징 점검:
 
-- `check-pr-readiness --help`와 `request-pr-rework --help`가 정상 출력되는지 확인 / Confirm `check-pr-readiness --help` and `request-pr-rework --help` both render correctly
-- `close-ready-report --compact`가 `candidates`와 `caution` 요약을 정상 반환하는지 확인 / Confirm `close-ready-report --compact` returns the expected `candidates` and `caution` summary
-- `cleanup-report --compact`가 merged, unmerged, without-PR 분류를 정상 반환하는지 확인 / Confirm `cleanup-report --compact` returns merged, unmerged, and without-PR classification
-- API 제한 상황에서 quota 또는 rate-limit 오류 메시지가 명확하게 보이는지 확인 / Confirm quota or rate-limit failures surface a clear error message
+```bash
+test -f README.md
+test -f google-jules-control/SKILL.md
+test -f google-jules-control/agents/openai.yaml
+test -f google-jules-control/.env.example
+grep -qx '.env' .gitignore
+grep -qx '.env' google-jules-control/.gitignore
+test -z "$(git ls-files | grep -E '(^|/)\.env$' || true)"
+```
+
+## Live Account Validation / 실제 계정 검증
 
-## 라이브 점검 / Live Checks
+아래 명령은 실제 `JULES_API_KEY`, GitHub 인증, Jules에 연결된 target repository가 있을 때만 실행합니다.
+Run these only when a real `JULES_API_KEY`, GitHub auth, and a Jules-connected target repository are available.
 
 ```bash
+: "${OWNER_REPO:?Set OWNER_REPO as owner/repo before live checks}"
+
 python3 google-jules-control/scripts/jules_api.py doctor --compact
-python3 google-jules-control/scripts/jules_api.py repo-to-source --repo owner/repo --compact
-python3 google-jules-control/scripts/jules_api.py list-sources
-python3 google-jules-control/scripts/jules_api.py close-ready-report --compact
-python3 google-jules-control/scripts/jules_api.py cleanup-report --compact
+python3 google-jules-control/scripts/jules_api.py gh-auth-check --compact
+
+SOURCE="$(python3 google-jules-control/scripts/jules_api.py repo-to-source --repo "$OWNER_REPO" --compact)"
+test -n "$SOURCE" || { echo "No Jules source found for $OWNER_REPO"; exit 1; }
+printf '%s\n' "$SOURCE"
+
+python3 google-jules-control/scripts/jules_api.py list-sources >/tmp/google-jules-skill-sources.json
+python3 google-jules-control/scripts/jules_api.py cleanup-report --repo-filter "$OWNER_REPO" --compact
+python3 google-jules-control/scripts/jules_api.py close-ready-report --repo-filter "$OWNER_REPO" --markdown
 ```
 
-권장 / Recommended:
+통과 기준: `doctor --compact`에 `dotenv=yes api_key=yes api_ready=yes`가 포함되어야 합니다. merge-aware reporting이나 cleanup을 검증하려면 `merge_ready=yes`도 필요합니다.
+Pass criteria: `doctor --compact` must include `dotenv=yes api_key=yes api_ready=yes`. `merge_ready=yes` is also required before validating merge-aware reporting or cleanup.
 
-- `--require-plan-approval`로 스모크 테스트 세션 1회 생성 / Create one smoke-test session with `--require-plan-approval`
-- 해당 세션에서 `summary` 확인 / Verify `summary` works for that session
-- 테스트 세션 또는 기존 세션으로 `check-pr-readiness`를 1회 확인 / Run `check-pr-readiness` once against a test or existing session
-- merge 불가 PR이 있다면 `request-pr-rework --markdown` 출력이 사용자에게 바로 전달 가능한지 확인 / If a PR is not merge-ready, confirm `request-pr-rework --markdown` produces a user-ready follow-up message
-- 테스트 후 세션 삭제 / Delete the smoke-test session afterward
+Smoke session handoff / 스모크 세션 handoff:
+
+- `docs/setup-and-test.md`의 `repo-to-source` -> `create-session` -> `summary` -> `export` -> cleanup 흐름을 한 번 실행 / Run the `repo-to-source` -> `create-session` -> `summary` -> `export` -> cleanup flow in `docs/setup-and-test.md` once
+- long-running 상태는 `wait` 또는 반복 `summary`로 확인 / Inspect long-running states with `wait` or repeated `summary`
+- 사람에게 보여줄 보고서는 `--markdown`, 자동화/보관용 결과는 JSON 또는 `export --output`으로 확인 / Use `--markdown` for human review and JSON or `export --output` for automation or archival checks
+
+## Platform Guide Release Checks / 플랫폼 가이드 릴리즈 점검
+
+- `Platform/README.md`의 공통 setup checks와 done criteria가 현재 명령 이름을 반영하는지 확인 / Confirm shared setup checks and done criteria in `Platform/README.md` reflect current command names
+- `Platform/Codex.md`, `Platform/Claude-Code.md`, `Platform/Google-Antigravity.md`가 skill registration 또는 project-doc injection, `.env` 접근, long-running command 처리, markdown/JSON 출력 처리를 각각 다루는지 확인 / Confirm each platform guide covers skill registration or project-doc injection, `.env` access, long-running command handling, and markdown/JSON output handling
+- full/strict 플랫폼 prompt 문서가 `doctor`, `repo-to-source`, `summary`, markdown report, concise JSON summary 흐름을 유지하는지 확인 / Confirm full and strict platform prompt docs preserve the `doctor`, `repo-to-source`, `summary`, markdown report, and concise JSON-summary flow
+
+## Version-Specific Notes / 버전별 확인 이력
+
+일반 릴리즈 절차와 분리해서 유지합니다. 새 버전에서만 필요한 수동 확인은 이 섹션에 추가하고, 다음 릴리즈에서 일반 절차로 승격할지 판단합니다.
+Keep these separate from the general release procedure. Add one-off manual checks for a specific release here, then decide in the next release whether they should become general procedure.
+
+`v0.2.0` focus / `v0.2.0` 중점 확인:
+
+- `check-pr-readiness --help`와 `request-pr-rework --help`가 정상 출력되는지 확인 / Confirm `check-pr-readiness --help` and `request-pr-rework --help` both render correctly
+- `close-ready-report --compact`가 `candidates`와 `caution` 요약을 정상 반환하는지 확인 / Confirm `close-ready-report --compact` returns the expected `candidates` and `caution` summary
+- `cleanup-report --compact`가 merged, unmerged, without-PR 분류를 정상 반환하는지 확인 / Confirm `cleanup-report --compact` returns merged, unmerged, and without-PR classification
+- API 제한 상황에서 quota 또는 rate-limit 오류 메시지가 명확하게 보이는지 확인 / Confirm quota or rate-limit failures surface a clear error message
 
 ## 배포 판단 / Deployment Judgment