diff --git a/Platform/Claude-Code-Prompt-Minimal.md b/Platform/Claude-Code-Prompt-Minimal.md index c6b126f..48974c2 100644 --- a/Platform/Claude-Code-Prompt-Minimal.md +++ b/Platform/Claude-Code-Prompt-Minimal.md @@ -3,11 +3,11 @@ ## KR ```text -Use google-jules-control/SKILL.md as the local Jules guide. Prefer google-jules-control/scripts/jules_api.py for Jules operations. Prompts are strict-scope by default, and ambiguity should trigger a clarifying question instead of broader work. Start with doctor, resolve owner/repo if needed, and summarize outputs briefly. +Use google-jules-control/SKILL.md as the local Jules guide. Prefer google-jules-control/scripts/jules_api.py for Jules operations. Prompts are strict-scope by default, and ambiguity should trigger a clarifying question instead of broader work. Start with doctor, resolve owner/repo if needed, and summarize outputs briefly. Before approving a Jules plan, run a scope review against the original task, scope notes, non-goals, and strict-scope rules; do not approve scope drift by default. ``` ## EN ```text -Use google-jules-control/SKILL.md as the local Jules guide. Prefer google-jules-control/scripts/jules_api.py for Jules operations. Prompts are strict-scope by default, and ambiguity should trigger a clarifying question instead of broader work. Start with doctor, resolve owner/repo if needed, and summarize outputs briefly. +Use google-jules-control/SKILL.md as the local Jules guide. Prefer google-jules-control/scripts/jules_api.py for Jules operations. Prompts are strict-scope by default, and ambiguity should trigger a clarifying question instead of broader work. Start with doctor, resolve owner/repo if needed, and summarize outputs briefly. Before approving a Jules plan, run a scope review against the original task, scope notes, non-goals, and strict-scope rules; do not approve scope drift by default. ``` diff --git a/Platform/Claude-Code-Prompt-Strict-Ops.md b/Platform/Claude-Code-Prompt-Strict-Ops.md index b44fd9c..ea60804 100644 --- a/Platform/Claude-Code-Prompt-Strict-Ops.md +++ b/Platform/Claude-Code-Prompt-Strict-Ops.md @@ -13,6 +13,7 @@ Rules: - Prompts sent through `create-session`, `send-message`, `resume`, and `request-pr-rework` are strict-scope 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 extra boundaries matter. +- Before approving a Jules plan, compare it against the original task, scope notes, non-goals, and strict-scope rules; do not approve scope drift by default. - Use `summary`, `cleanup-report --markdown`, `close-ready-report --markdown`, and `notify-close-plan --markdown` for user-facing communication. - Check `gh-auth-check --compact` before merge-aware cleanup. - Never delete or close a Jules session without explicit user confirmation. @@ -39,6 +40,7 @@ Rules: - Prompts sent through `create-session`, `send-message`, `resume`, and `request-pr-rework` are strict-scope 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 extra boundaries matter. +- Before approving a Jules plan, compare it against the original task, scope notes, non-goals, and strict-scope rules; do not approve scope drift by default. - Use `summary`, `cleanup-report --markdown`, `close-ready-report --markdown`, and `notify-close-plan --markdown` for user-facing communication. - Check `gh-auth-check --compact` before merge-aware cleanup. - Never delete or close a Jules session without explicit user confirmation. diff --git a/Platform/Claude-Code-Prompt.md b/Platform/Claude-Code-Prompt.md index 5d4e924..399d300 100644 --- a/Platform/Claude-Code-Prompt.md +++ b/Platform/Claude-Code-Prompt.md @@ -15,6 +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. +- Before approving a Jules plan, compare it against the original task, scope notes, non-goals, and strict-scope rules; do not approve scope drift by default. - Use `summary`, `cleanup-report`, `close-ready-report`, 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`. @@ -43,6 +44,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. +- Before approving a Jules plan, compare it against the original task, scope notes, non-goals, and strict-scope rules; do not approve scope drift by default. - Use `summary`, `cleanup-report`, `close-ready-report`, 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`. diff --git a/Platform/Codex-Prompt-Minimal.md b/Platform/Codex-Prompt-Minimal.md index 697338c..3bbc974 100644 --- a/Platform/Codex-Prompt-Minimal.md +++ b/Platform/Codex-Prompt-Minimal.md @@ -3,11 +3,11 @@ ## KR ```text -Use google-jules-control/SKILL.md as the Jules operating guide. Use google-jules-control/scripts/jules_api.py for Jules actions. Prompts are strict-scope by default, and ambiguity should trigger a clarifying question instead of broader work. Start with doctor, resolve owner/repo with repo-to-source if needed, and summarize results concisely. +Use google-jules-control/SKILL.md as the Jules operating guide. Use google-jules-control/scripts/jules_api.py for Jules actions. Prompts are strict-scope by default, and ambiguity should trigger a clarifying question instead of broader work. Start with doctor, resolve owner/repo with repo-to-source if needed, and summarize results concisely. Before approving a Jules plan, run a scope review against the original task, scope notes, non-goals, and strict-scope rules; do not approve scope drift by default. ``` ## EN ```text -Use google-jules-control/SKILL.md as the Jules operating guide. Use google-jules-control/scripts/jules_api.py for Jules actions. Prompts are strict-scope by default, and ambiguity should trigger a clarifying question instead of broader work. Start with doctor, resolve owner/repo with repo-to-source if needed, and summarize results concisely. +Use google-jules-control/SKILL.md as the Jules operating guide. Use google-jules-control/scripts/jules_api.py for Jules actions. Prompts are strict-scope by default, and ambiguity should trigger a clarifying question instead of broader work. Start with doctor, resolve owner/repo with repo-to-source if needed, and summarize results concisely. Before approving a Jules plan, run a scope review against the original task, scope notes, non-goals, and strict-scope rules; do not approve scope drift by default. ``` diff --git a/Platform/Codex-Prompt-Strict-Ops.md b/Platform/Codex-Prompt-Strict-Ops.md index 343fd57..7eb51a8 100644 --- a/Platform/Codex-Prompt-Strict-Ops.md +++ b/Platform/Codex-Prompt-Strict-Ops.md @@ -13,6 +13,7 @@ Rules: - Prompts sent through `create-session`, `send-message`, `resume`, and `request-pr-rework` are strict-scope 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 extra boundaries matter. +- Before approving a Jules plan, compare it against the original task, scope notes, non-goals, and strict-scope rules; do not approve scope drift by default. - Before merge-aware reporting or cleanup, run `gh-auth-check --compact`. - Use `summary`, `cleanup-report --markdown`, `close-ready-report --markdown`, and `notify-close-plan --markdown` for user-facing updates. - Do not close, cancel, or delete a Jules session without explicit user confirmation. @@ -39,6 +40,7 @@ Rules: - Prompts sent through `create-session`, `send-message`, `resume`, and `request-pr-rework` are strict-scope 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 extra boundaries matter. +- Before approving a Jules plan, compare it against the original task, scope notes, non-goals, and strict-scope rules; do not approve scope drift by default. - Before merge-aware reporting or cleanup, run `gh-auth-check --compact`. - Use `summary`, `cleanup-report --markdown`, `close-ready-report --markdown`, and `notify-close-plan --markdown` for user-facing updates. - Do not close, cancel, or delete a Jules session without explicit user confirmation. diff --git a/Platform/Codex-Prompt.md b/Platform/Codex-Prompt.md index e62a4c6..9e5101f 100644 --- a/Platform/Codex-Prompt.md +++ b/Platform/Codex-Prompt.md @@ -15,6 +15,7 @@ When handling Jules-related tasks: - 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. +- Before approving a Jules plan, compare it against the original task, scope notes, non-goals, and strict-scope rules; do not approve scope drift by default. - Use `summary`, `cleanup-report --markdown`, `close-ready-report --markdown`, and `notify-close-plan --markdown` for user-facing updates. - Before merge-aware cleanup, run `gh-auth-check --compact`. - Never close, cancel, or delete a Jules session without explicit user confirmation. @@ -43,6 +44,7 @@ When handling Jules-related tasks: - 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. +- Before approving a Jules plan, compare it against the original task, scope notes, non-goals, and strict-scope rules; do not approve scope drift by default. - Use `summary`, `cleanup-report --markdown`, `close-ready-report --markdown`, and `notify-close-plan --markdown` for user-facing updates. - Before merge-aware cleanup, run `gh-auth-check --compact`. - Never close, cancel, or delete a Jules session without explicit user confirmation. diff --git a/Platform/Google-Antigravity-Prompt-Minimal.md b/Platform/Google-Antigravity-Prompt-Minimal.md index 15dd315..b79de02 100644 --- a/Platform/Google-Antigravity-Prompt-Minimal.md +++ b/Platform/Google-Antigravity-Prompt-Minimal.md @@ -3,11 +3,11 @@ ## KR ```text -Read google-jules-control/SKILL.md first. Use google-jules-control/scripts/jules_api.py for Jules operations. Keep prompts strict-scope by default, ask a clarifying question when the task is ambiguous, start with doctor, resolve owner/repo if needed, and keep user-facing updates short. +Read google-jules-control/SKILL.md first. Use google-jules-control/scripts/jules_api.py for Jules operations. Keep prompts strict-scope by default, ask a clarifying question when the task is ambiguous, start with doctor, resolve owner/repo if needed, and keep user-facing updates short. Before approving a Jules plan, run a scope review against the original task, scope notes, non-goals, and strict-scope rules; do not approve scope drift by default. ``` ## EN ```text -Read google-jules-control/SKILL.md first. Use google-jules-control/scripts/jules_api.py for Jules operations. Keep prompts strict-scope by default, ask a clarifying question when the task is ambiguous, start with doctor, resolve owner/repo if needed, and keep user-facing updates short. +Read google-jules-control/SKILL.md first. Use google-jules-control/scripts/jules_api.py for Jules operations. Keep prompts strict-scope by default, ask a clarifying question when the task is ambiguous, start with doctor, resolve owner/repo if needed, and keep user-facing updates short. Before approving a Jules plan, run a scope review against the original task, scope notes, non-goals, and strict-scope rules; do not approve scope drift by default. ``` diff --git a/Platform/Google-Antigravity-Prompt-Strict-Ops.md b/Platform/Google-Antigravity-Prompt-Strict-Ops.md index 86a9079..3bb2b43 100644 --- a/Platform/Google-Antigravity-Prompt-Strict-Ops.md +++ b/Platform/Google-Antigravity-Prompt-Strict-Ops.md @@ -13,6 +13,7 @@ Rules: - Prompts sent through `create-session`, `send-message`, `resume`, and `request-pr-rework` are strict-scope 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 extra boundaries matter. +- Before approving a Jules plan, compare it against the original task, scope notes, non-goals, and strict-scope rules; do not approve scope drift by default. - Prefer `summary`, `cleanup-report --markdown`, `close-ready-report --markdown`, and `notify-close-plan --markdown` for human review. - Run `gh-auth-check --compact` before merge-aware reporting or cleanup. - Require explicit user confirmation before any delete-style command or `close-merged-session`. @@ -39,6 +40,7 @@ Rules: - Prompts sent through `create-session`, `send-message`, `resume`, and `request-pr-rework` are strict-scope 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 extra boundaries matter. +- Before approving a Jules plan, compare it against the original task, scope notes, non-goals, and strict-scope rules; do not approve scope drift by default. - Prefer `summary`, `cleanup-report --markdown`, `close-ready-report --markdown`, and `notify-close-plan --markdown` for human review. - Run `gh-auth-check --compact` before merge-aware reporting or cleanup. - Require explicit user confirmation before any delete-style command or `close-merged-session`. diff --git a/Platform/Google-Antigravity-Prompt.md b/Platform/Google-Antigravity-Prompt.md index 56be5b9..89f2302 100644 --- a/Platform/Google-Antigravity-Prompt.md +++ b/Platform/Google-Antigravity-Prompt.md @@ -16,6 +16,7 @@ Operational rules: - 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. +- Before approving a Jules plan, compare it against the original task, scope notes, non-goals, and strict-scope rules; do not approve scope drift by default. - Prefer `summary`, `cleanup-report --markdown`, and `close-ready-report --markdown` for human-readable updates. - Use `notify-close-plan --markdown` when preparing a user confirmation message before closure. - Require explicit user confirmation before running `close-merged-session` or any delete-style command. @@ -46,6 +47,7 @@ Operational rules: - 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. +- Before approving a Jules plan, compare it against the original task, scope notes, non-goals, and strict-scope rules; do not approve scope drift by default. - Prefer `summary`, `cleanup-report --markdown`, and `close-ready-report --markdown` for human-readable updates. - Use `notify-close-plan --markdown` when preparing a user confirmation message before closure. - Require explicit user confirmation before running `close-merged-session` or any delete-style command. diff --git a/docs/setup-and-test.md b/docs/setup-and-test.md index ed77685..bb3ce78 100644 --- a/docs/setup-and-test.md +++ b/docs/setup-and-test.md @@ -82,6 +82,9 @@ python3 google-jules-control/scripts/jules_api.py create-session \ python3 google-jules-control/scripts/jules_api.py summary --session sessions/SESSION_ID ``` +`AWAITING_PLAN_APPROVAL` 상태라면 plan이 smoke-test 범위에 머무는지 먼저 확인합니다. 코드 변경, 리팩터링, 의존성 변경이 포함되면 승인하지 않습니다. +If the session is `AWAITING_PLAN_APPROVAL`, review that the plan stays inside the smoke-test scope before approval. Do not approve plans that include code changes, refactors, or dependency changes. + 5. 테스트 세션 정리 / Clean up the test session ```bash @@ -108,6 +111,9 @@ python3 google-jules-control/scripts/jules_api.py resume --session sessions/SESS python3 google-jules-control/scripts/jules_api.py approve-plan --session sessions/SESSION_ID ``` +`approve-plan`과 `AWAITING_PLAN_APPROVAL` 세션을 승인할 수 있는 `resume`은 plan scope review 후에만 실행합니다. +Run `approve-plan`, and `resume` when it would approve an `AWAITING_PLAN_APPROVAL` session, only after reviewing the generated plan against the task scope. + 정리와 리포트 / Cleanup and reporting: ```bash diff --git a/google-jules-control/SKILL.md b/google-jules-control/SKILL.md index 9e2286a..cd69943 100644 --- a/google-jules-control/SKILL.md +++ b/google-jules-control/SKILL.md @@ -19,7 +19,7 @@ Use this skill to delegate coding work to Google Jules from an agentic workflow. - CLI path: run `jules remote list --repo` or use `jules remote new --repo .` from the repo root. 3. Create a session with a concrete prompt and branch. By default the script wraps the prompt with a strict-scope contract so Jules stays narrow and asks questions when needed. 4. Poll session state or activities until Jules requests approval, feedback, or completes. -5. Approve the latest plan if the session enters `AWAITING_PLAN_APPROVAL`. +5. If the session enters `AWAITING_PLAN_APPROVAL`, review the latest plan against the original task, strict-scope rules, `--scope-note`, and `--non-goal` before approving it. 6. If needed, inspect open sessions with `list-active-sessions`. 7. For completed PR work, verify merge status before closing the Jules session. 8. Summarize results for the user, including session URL, current state, latest agent message, PR status, and whether the session is safe to close. @@ -71,6 +71,10 @@ python3 scripts/jules_api.py create-session \ python3 scripts/jules_api.py wait --session sessions/1234567890 +python3 scripts/jules_api.py summary --session sessions/1234567890 + +# Before approving, run a scope review against the original task, +# --scope-note, --non-goal, and strict-scope rules. python3 scripts/jules_api.py approve-plan --session sessions/1234567890 python3 scripts/jules_api.py send-message \ @@ -174,13 +178,30 @@ Approve the current Jules plan and let it continue. Suggested flow: +Before approving, compare the generated plan with: + +- The original user request +- Any `--scope-note` boundaries +- Any `--non-goal` exclusions +- The strict-scope rules that forbid unrelated cleanup, dependency changes, schema changes, broad refactors, or adjacent formatting changes + +If the plan drifts outside scope, do not approve it. Ask the user for confirmation or send Jules a follow-up asking for a narrower plan, for example: + ```bash python3 scripts/jules_api.py summary --session sessions/SESSION_ID python3 scripts/jules_api.py approve-plan --session sessions/SESSION_ID python3 scripts/jules_api.py wait --session sessions/SESSION_ID ``` -Use `resume` instead when you want one helper command that can approve a pending plan automatically: +```bash +python3 scripts/jules_api.py send-message \ + --session sessions/SESSION_ID \ + --prompt "Revise the plan before execution. Keep it limited to the login redirect test and remove the proposed auth helper refactor." \ + --scope-note "Only the login redirect path and its direct tests are in scope." \ + --non-goal "Do not refactor shared auth helpers." +``` + +Use `resume` only after the same scope review when you want one helper command that can approve a pending plan automatically: ```bash python3 scripts/jules_api.py resume --session sessions/SESSION_ID @@ -454,7 +475,8 @@ python3 scripts/jules_api.py close-ready-report --repo-filter owner/repo --requi - Prompts sent through the API helper are strict-scope by default. Use that default unless there is a clear reason to opt out. - Treat strict-scope as both a simplicity rule and a surgical-change rule: minimum necessary patch, minimum necessary blast radius. - If the user gives only an owner/repo pair and not a Jules source resource name, resolve it with `list-sources` first. -- If `AWAITING_PLAN_APPROVAL` appears, surface the plan and explicitly approve it only when the user asked to continue or the task clearly implies execution should proceed. +- If `AWAITING_PLAN_APPROVAL` appears, surface the plan and run a scope review before approval. Approve only when the plan stays within the original request, `--scope-note`, `--non-goal`, and strict-scope rules. +- If the plan includes scope drift, unrelated cleanup, dependency changes, schema changes, broad refactors, or adjacent formatting changes, do not approve it by default. Ask the user or send Jules a narrowing instruction first. - If the session reaches `AWAITING_USER_FEEDBACK`, send a concise clarifying instruction instead of creating a new session. - Use `resume` as a convenience helper only. It is not a first-class Jules API verb; it infers the right next step from the session state. - Use `--scope-note` when a file area, subsystem, or execution boundary must be stated explicitly. diff --git a/google-jules-control/references/jules-reference.md b/google-jules-control/references/jules-reference.md index a47b4c4..91dd754 100644 --- a/google-jules-control/references/jules-reference.md +++ b/google-jules-control/references/jules-reference.md @@ -47,9 +47,10 @@ Important session fields: Practical note: -- There is no dedicated REST `resume` endpoint in the current public API. If a session is waiting, resume it by approving a pending plan or sending a follow-up message. +- There is no dedicated REST `resume` endpoint in the current public API. If a session is waiting, resume it by approving a pending plan only after comparing it against the original task, scope notes, non-goals, and strict-scope rules, or by sending a follow-up message. - There is no reversible REST `cancel` endpoint distinct from deletion. Deleting the session is the closest cancellation-style action. - The public API does not document a reliable remaining-usage or quota-balance endpoint for end users. Handle quota failures explicitly, but do not guess a remaining amount. +- `AWAITING_PLAN_APPROVAL` is a review gate, not an automatic approval signal. Read the generated plan and compare it with the original task, scope notes, non-goals, and strict-scope rules before calling `approve-plan`. Activity types to watch: @@ -133,5 +134,6 @@ Pagination contract: - `Usage or rate limit exceeded`: retry later, reduce automation frequency, or check the Jules account/project limits. The script will fail clearly instead of estimating remaining usage. - No matching source: install/connect the GitHub repository in Jules first, then re-run `list-sources`. - Session appears stuck: inspect the latest activities and state before retrying. `AWAITING_PLAN_APPROVAL` and `AWAITING_USER_FEEDBACK` are usually waiting states, not failures. +- Plan includes unrelated work: do not approve it by default. Send Jules a narrowing instruction or ask the user whether the broader scope is intentional. - Need richer repo context: keep the repository `AGENTS.md` current so Jules can infer project-specific conventions. - `gh pr view` fails: run `gh auth status` and authenticate the right GitHub account before using merge-status commands.