diff --git a/Platform/Claude-Code-Prompt.md b/Platform/Claude-Code-Prompt.md index 5d4e924..e147252 100644 --- a/Platform/Claude-Code-Prompt.md +++ b/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. diff --git a/Platform/Claude-Code.md b/Platform/Claude-Code.md index c49fbb1..778777a 100644 --- a/Platform/Claude-Code.md +++ b/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. diff --git a/Platform/Codex.md b/Platform/Codex.md index d8a289e..f4a8c11 100644 --- a/Platform/Codex.md +++ b/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. diff --git a/Platform/Google-Antigravity.md b/Platform/Google-Antigravity.md index f13fd1a..80e2b2b 100644 --- a/Platform/Google-Antigravity.md +++ b/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. diff --git a/Platform/README.md b/Platform/README.md index 08ace4c..7fbc11e 100644 --- a/Platform/README.md +++ b/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 diff --git a/docs/release-checklist.md b/docs/release-checklist.md index d582a25..163bde8 100644 --- a/docs/release-checklist.md +++ b/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