Skip to content

Share execution rules and shorten skills below 12 KB - #369

Open
briansuchy wants to merge 6 commits into
mainfrom
refactor/compact-draft-and-review-skills
Open

briansuchy wants to merge 6 commits into
mainfrom
refactor/compact-draft-and-review-skills

Conversation

@briansuchy

@briansuchy briansuchy commented Nov 9, 2026 •

Copy link
Copy Markdown
Collaborator

Summary of Key Changes

Closes #371

On origin/main (0997679), skills/egm-bootstrap/SKILL.md (23,931 body B) and skills/egm-review/SKILL.md (23,887 body B) sit within 69 B and 113 B of Antigravity's 24,000-byte skill body limit (tests/unit/test_skill_load_limits.py::test_skill_body_fits_antigravity), while skills/egm-draft/SKILL.md (17,115 body B) and skills/egm-brainstorm/SKILL.md (14,812 body B) carry duplicated boilerplate for delegation, artifact-first delivery, plain-English style, anti-sycophancy word lists, and modal invariants.

This PR refactors shared behavioral constraints into resources/execution_instructions.md across all seven skills and compacts all oversized SKILL.md files in place (without splitting workflows into new references/*.md files), bringing total SKILL.md body volume down by -37,480 B (-37.3%) and keeping every skill under 12,000 B (at least 12,018 B of headroom under the 24,000-byte cap). The packaged Claude runtime under distributions/claude/ is regenerated to match source byte-for-byte (scripts/pack_plugin.py --target claude).

File (plus distributions/claude/ mirror) Before (origin/main Body / Raw) After (0928e5b Body) Delta Headroom Under 24,000 B Cap Lines
skills/egm-bootstrap/SKILL.md 23,931 B / 24,090 B 11,439 B (-52.2%) -12,492 B 69 B -> 12,561 B 432 -> 94
skills/egm-brainstorm/SKILL.md 14,812 B / 15,205 B 7,863 B (-46.9%) -6,949 B 9,188 B -> 16,137 B 271 -> 104
skills/egm-draft/SKILL.md 17,115 B / 17,479 B 10,379 B (-39.4%) -6,736 B 6,885 B -> 13,621 B 321 -> 82
skills/egm-review/SKILL.md 23,887 B / 24,257 B 11,982 B (-49.8%) -11,905 B 113 B -> 12,018 B 426 -> 101
skills/egm-review-loop/SKILL.md 9,846 B / 10,325 B 9,691 B (-1.6%) -155 B 14,154 B -> 14,309 B 199 -> 191
skills/egm-resolve/SKILL.md 8,205 B / 8,541 B 8,647 B (+5.4%) +442 B 15,795 B -> 15,353 B 187 -> 188
skills/egm-drift-report/SKILL.md 2,805 B / 3,169 B 3,120 B (+11.2%) +315 B 21,195 B -> 20,880 B 67 -> 68
Total Across All 7 Skills 100,601 B body 63,121 B body -37,480 B (-37.3%) All <= 11,982 B 1,903 -> 828
resources/execution_instructions.md 2,554 B 4,877 B +2,323 B Shared by all 7 skills 37 -> 72

1. Pure Deduplication & In-Place Compaction (Behavior-Preserving)

  • Centralized shared constraints in resources/execution_instructions.md: Consolidated Artifact-First Delivery, Plain-English Standard, Adversarial Rigor (No Sycophancy) word lists, Subagent Delegation (Goldfish Isolation) and nesting fallbacks, single-select Interaction Invariants, and VCS Isolation into Shared Execution Constraints (All Skills), linked from all seven SKILL.md files via anchored relative Markdown links ([execution instructions](../../resources/execution_instructions.md)), ${CLAUDE_PLUGIN_ROOT}/resources/execution_instructions.md for Claude Code, ~/.gemini/config/plugins/egm/resources/execution_instructions.md for pathless <SKILL> CLI injection, and toolless inline fallbacks (plus system_prompt.rules wiring across all seven skills/*/test_scenarios.yaml suites).
  • Isolated drafting-only rules away from non-drafting skills: Scoped the Design-Only Scratchpad Rule strictly to egm-draft (preserving tests/unit/test_harnesses.py::test_scratch_files_use_private_directories substrings, active-scratch-dir preference before mktemp -d, and anti-implication guard) and kept drafting-only pacing rules (Explicit Consensus Gates, ONE QUESTION AT A TIME, NO SUMMARIES, Contradiction Auditing, Author Decides Architecture) inside skills/egm-draft/SKILL.md so non-drafting skills never inherit conflicting rules.
  • Compacted verbose workflows in place: Collapsed repeated stage checkpoint/notification tails, replaced fenced JSON modal examples with compact question / options specs, folded egm-review Stages 5-9 into one table (with direct-dispatch standard path mapping and retry-once/Failed Reviewers fallback), and compacted egm-bootstrap (preserving #409's .NET / C# discovery, .razor/.cshtml extensions, dotnet test guidance, general hidden/system directory exclusion, and swarm template cues) and egm-brainstorm while preserving extension lists, test exclusions, Bazel target patterns (/..., :all), safety gates, goldfish-explorer schemas and chunking rules, persona paths (agents/<file>.md), concepts_brief.md templates, cumulative design_draft.md section appends, and standalone test_scenarios.yaml anchors.
  • Synchronized packaged runtime & unit guards: Regenerated distributions/claude/ via scripts/pack_plugin.py --target claude and added regression checks in tests/unit/test_harnesses.py and tests/unit/test_scenario_coverage.py rejecting unanchored resources/ or docs/ backtick paths and verifying system_prompt.rules wiring.

2. Reconciled Internal Discrepancies & Semantics-Clarifying Refinements

  1. egm-review (Uninterrupted vs. Checkpoint modes & Stage 8 context): Unified Subflow: Uninterrupted Full Flow into the Stage Specifications (Stages 5-9) table so document standards and Stage 8's zoom_out_report.md prior-report context apply consistently in all modes, while clarifying Stages 7 & 9 so all non-uninterrupted modes (interactive, feature_spec, implementation, 7, 9) write critic_report.md / implementation_readiness_report.md and present the 4-option checkpoint gate first (running egm-resolve when Option 1 is selected, then advancing or re-running the stage with max 1 re-audit).
  2. egm-review (Step 4: Staging Strategy heading removed): Routes Step 2 / Step 3 directly to Stage 5..9 without changing stage numbers 5..9.
  3. Interactive Gate Step Isolation & Non-Empty Chat Guard (execution_instructions.md, egm-draft, egm-review, egm-brainstorm, egm-resolve): Promoted the non-empty visible chat requirement to global Interaction Invariants, required structured question gates to run as the sole tool call in their model response step (after earlier preparatory file writes/reads in the same user turn complete, preventing concurrent [write_file, ask_question] tool-batching races), and explicitly exempted egm-resolve Step 4 and Interactive breakdown so their 5-option / 3-option plain-chat menus remain zero-tool turns.

Contribution Type

Track: Feature / Architectural Change -- Stage 2: Implementation PR

Tracked via maintainer refactor issue #371 (pr-ready); no design document added under docs/designs/.

Verification

  • Rebased cleanly onto origin/main (0997679, preserving #409 .NET / C# bootstrap additions and #427 ruff/actionlint checks). Offline Python unit checks (python3 -m pytest tests/unit -k "not test_ci_workflow and not test_scope_advisory" -q): 378 passed, 3 skipped (Node-dependent tests, lint, and site-validation verified in GitHub Actions).
  • Internal subagent verification across all 7 skills: 7/7 live runtime indirection probes (SKILL.md -> resources/execution_instructions.md), all 43 skills/*/test_scenarios.yaml scenarios A/B verified against origin/main (0 regressions), 9 live tool-using & nested-subagent E2E workflows across all 7 skills, plus 4/4 post-patch live subagent verification probes (egm-bootstrap hidden-dir ignore, egm-review Option 1 max 1 re-audit + direct-dispatch standard mapping/retry, and egm-draft Design-Only Scratchpad & template checks).
  • Live multi-turn gate verification across Antigravity Language Server (21/21 interactive ask_question modals + plain-chat guards across egm-draft and egm-review), interactive CLI TUI modal navigation, and 10/10 side-by-side multi-turn gate evaluation scenarios against origin/main.

Human Accountability Affirmation

@briansuchy
briansuchy requested a review from a team as a code owner November 9, 2026 15:47
@briansuchy
briansuchy requested a review from njeunje November 9, 2026 15:47
@github-actions github-actions Bot added the design-needed Automated scope advisory: Bug Fix PR exceeds minor fix bounds label Nov 9, 2026
@briansuchy briansuchy removed the design-needed Automated scope advisory: Bug Fix PR exceeds minor fix bounds label Nov 9, 2026
@briansuchy briansuchy changed the title Compact egm-review and egm-draft skills under 24 KB body limit Refactor shared execution instructions and compact skills under 12 KB Nov 9, 2026
@briansuchy
briansuchy requested review from n3wth and quinnjim and removed request for njeunje November 9, 2026 17:12

@egm-triage-bot egm-triage-bot left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Automated first-pass review found zero blocking or major issues. Routing to @google/egm-maintainers for maintainer review.

@egm-triage-bot egm-triage-bot added the triage: passed Automated Stage-1 PR triage found zero blocking or major issues label Nov 10, 2026
@briansuchy
briansuchy removed the request for review from a team November 11, 2026 20:07
@briansuchy
briansuchy force-pushed the refactor/compact-draft-and-review-skills branch from 2ba8584 to 943a259 Compare November 12, 2026 15:08

@egm-triage-bot egm-triage-bot left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Automated first-pass review found zero blocking or major issues. Routing to @google/egm-maintainers for maintainer review.

@egm-triage-bot egm-triage-bot left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Automated first-pass review found zero blocking or major issues. Routing to @google/egm-maintainers for maintainer review.

@n3wth n3wth left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed 0928e5b.

[P2] Please retain minimal inline constraints in bootstrap, resolve, review-loop and drift-report when file tools are unavailable. These skills now say “proceed inline” after moving their shared rules to resources/execution_instructions.md, so that fallback cannot enforce rules it never reads. Brainstorm, draft and review already keep an inline fallback; please use the same approach in these four and their packaged copies. Please rebase before the next review.

@n3wth n3wth changed the title Refactor shared execution instructions and compact skills under 12 KB Share execution rules and shorten skills below 12 KB Nov 18, 2026
…ion, and restore audit invariants

- Anchor resources/execution_instructions.md and docs/harnesses.md as relative Markdown links across all 7 skills (with CLAUDE_PLUGIN_ROOT, ~/.gemini pathless <SKILL> fallback, and toolless inline fallback), and enforce anchored links in test_harnesses.py (F1).
- Require interactive question gates to emit non-empty chat text first and run as the sole tool call in their model response step after earlier preparatory file writes/reads finish (F2, F5C).
- Exempt egm-resolve Step 4 and Interactive breakdown zero-tool plain-chat prompts from structured question tool invocation, and clarify egm-review Stages 7 and 9 checkpoint-first routing across all non-uninterrupted modes (F3A, F3B).
- Wire resources/execution_instructions.md into all 7 skills/*/test_scenarios.yaml rule lists, retain compact inline banned-word tuples, and assert rule file presence in test_scenario_coverage.py (F4).
- Restore egm-bootstrap template names, chunking/JSON schema details, and contract drift verification targets; egm-brainstorm 7-lens persona paths and RFC feedback pause; and egm-draft cumulative section append wording while keeping all 7 skill bodies under 12 KB (F5A, F5B, F5C).
- Regenerate distributions/claude/ via scripts/pack_plugin.py --target claude.
@briansuchy
briansuchy force-pushed the refactor/compact-draft-and-review-skills branch from 0928e5b to 731796c Compare November 20, 2026 13:38
@briansuchy

Copy link
Copy Markdown
Collaborator Author

Rebased onto main (70406c4, which removed checked-in distributions/claude/ in #394) and added minimal inline fallback constraints in commit 731796c across egm-bootstrap, egm-resolve, egm-review-loop, and egm-drift-report (covering doc-only/read-only scope, no VCS commits, plain-English non-sycophantic rigor, fresh-context subagent delegation where applicable, and modal/plain-chat interaction invariants when resources/execution_instructions.md cannot be read).

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

triage: passed Automated Stage-1 PR triage found zero blocking or major issues

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Share execution instructions to fit Antigravity's 24 KB skill limit

4 participants