fix(llm-sync): warn/annotate $ARGUMENTS on Antigravity skill sync - #48
Merged
tstapler merged 9 commits intoAug 12, 2026
Merged
Conversation
…ysis Audits project_plans/<project>/ output volume against a git-derived shipped-code signal, to spot SDD sessions that produced heavy plan docs without matching implementation. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PCjoA8z5seuFnfsnXo7XWS
project_plans/ audit (sdd-plan-audit.py) showed heavy planning output relative to what shipped. Root cause: phases 3 (plan) and 4 (validate) had no complexity gating at all -- every project got the full template, 3 reviewer subagents, and 5-iteration repair loops regardless of size. The one existing gate (research phase) defaulted to max output (all 6 agents) when the Complexity field was missing, which was most of the project history (5/8 projects predate the current requirements.md template). - 2-research: fix missing-Complexity default from "all 6 agents" to Complexity-2 behavior (3 agents + conditional extras) - 3-plan: add step 2.5 calibrating Domain Glossary/Migration Plan elaboration and which of the 3 reviewer subagents run, keyed on Complexity; UX subagent now writes a condensed entry for non-interactive surfaces (config/log/CLI output) instead of the full wireframe treatment - 4-validate: add step 2.5 calibrating which of the 3 validation subagents run and whether the triad review gate applies - full: stop hardcoding "6 agents" / "three reviewers" / "three subagents" in the orchestrator -- defer to each phase's calibration step instead, since full.md's own stated principle is to never duplicate phase logic. Also suggest /sdd:quick when Phase 1 derives Complexity 1, since quick.md already has no template/artifacts/ subagents and is the existing antidote to this problem -- it was just structurally disconnected from full.md. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PCjoA8z5seuFnfsnXo7XWS
History showed a flip-flop: df7b881 consolidated all ADRs to repo-root docs/adr/, then 4b5aa9e reverted sdd:adr specifically back to project_plans/<project>/decisions/ a week later, leaving two ADR skills with different write targets and no stated reason. Keeping the split (it's the right call -- sdd:adr decisions are internal to one SDD project's implementation, plan:adr decisions are cross-cutting dotfiles-repo infra) but documenting it in both skills so it reads as intentional next time, not drift. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PCjoA8z5seuFnfsnXo7XWS
Studied obra/superpowers (an external Claude Code skills library) -- its subagent-driven-development/SKILL.md never inlines a subagent's full prompt in the orchestrating file; it links to sibling files (implementer-prompt.md, task-reviewer-prompt.md) read only when that step actually dispatches. Anthropic's own guidance (cited in superpowers' writing-skills/anthropic-best-practices.md) says the same: keep SKILL.md under 500 lines, split into separate files as you approach it. Our 3-plan and 4-validate were within the 500-line cap but had 25-35% of their body as inline subagent-prompt blockquotes -- prompt text for reviewers the complexity gate (added earlier this session) might not even dispatch. Extracted each into its own file: - 3-plan: planning-prompt.md, architecture-review-prompt.md, adversarial-review-prompt.md, ux-design-prompt.md (342 -> 128 lines, -63%) - 4-validate: validation-prompt.md, pre-mortem-prompt.md, cross-artifact-consistency-prompt.md (230 -> 112 lines, -51%) 2-research's agent prompts (3-8 lines each) were left inline -- splitting those would add indirection without saving anything. Also fixed two hardcoded counts the complexity gate broke: 3-plan's repair loops still said "MAX = 5" regardless of the calibrated cap (2/3/5) from step 2.5, and 4-validate's step 4 said "wait for all three subagents" when Complexity 1 dispatches only one. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PCjoA8z5seuFnfsnXo7XWS
Ran a lean-agent-loop audit (9 parallel agents, one per SDD phase directory) against Anthropic's current prompt-audit methodology (claude-api skill's shared/prompt-audit.md, current as of 2026-06-24) -- target model: current-generation Claude used by Claude Code subagents (Sonnet 5 / Opus 5 tier). 21 findings across 8 files, applied 19: - Stacked/absolutist emphasis booster patterns removed: "## HARD GATE", "CRITICAL:", "Iron Law:", ALL-CAPS mid-sentence shouting (NO CODE EXISTS YET, FRESH SESSION, ALL IN A SINGLE PARALLEL MESSAGE). Current models follow a plainly-stated instruction; stacked emphasis now causes over-triggering and rigid behavior rather than better compliance -- restated each as plain prose, same constraint. - Redundant same-rule restatement collapsed to one instance (1-ideate's "think about X/Y/Z" step folded into the question-design step it fed; several doubled "do not X. do not X again" lines in 5-implement, full, fix-bug). - 6-verify: the four-times-repeated repair-loop skeleton (iteration counter, "spawn a fresh fix subagent", commit-does-not-push, clean/ STUCK exit) factored into one canonical procedure that each of the three gates (Layer 1+2, Layer 3, Layer 4) now invokes with just its own collect/provide/re-run parameters. 412 -> 396 lines despite the new shared section, since three near-duplicate blocks became three short parameter lists. Declined 2 of 21 findings: the ITERATION=0/MAX=5 pseudocode loops in 5-implement were flagged as chain-of-thought scaffolding, but they're control-flow bookkeeping for the orchestrating session (not reasoning scaffolding for an LLM call) and match the same convention used consistently in 3-plan/4-validate/6-verify's repair loops -- rewriting just that one file to prose would have made the convention inconsistent across the skill family. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PCjoA8z5seuFnfsnXo7XWS
Antigravity skills are auto-triggered, not explicitly invoked with
positional args the way Claude commands are, so a bare $ARGUMENTS
token synced verbatim into SKILL.md was silently dead text. Add a
shared build_antigravity_skill_content() helper used by both write
sites (AntigravityTarget.save_commands and GeminiTarget.save_commands's
embedded Antigravity block) that warns at sync time and annotates the
written file. The legacy Gemini CLI .toml $ARGUMENTS->{{args}} path is
untouched. Adds test_gemini_sync.py as a minimal self-check and
documents the limitation in AGENTS.md.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BBE3c8U9NH9dL2yD9DHcBY
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01BBE3c8U9NH9dL2yD9DHcBY
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01R64bt3Joo88G6qRFN3Wu4q
tstapler
marked this pull request as ready for review
August 12, 2026 05:46
…x-antigravity-arguments-sync-gap # Conflicts: # .backlog-context.md # .claude/commands/backlog/done-0.md # .claude/commands/backlog/done-1.md # .claude/commands/backlog/done-2.md # .claude/commands/backlog/done-3.md # .claude/commands/backlog/done-4.md # .claude/commands/backlog/done-5.md # .claude/commands/backlog/done-6.md # .claude/commands/backlog/fail-0.md # .claude/commands/backlog/fail-1.md # .claude/commands/backlog/fail-2.md # .claude/commands/backlog/fail-3.md # .claude/commands/backlog/fail-4.md # .claude/commands/backlog/fail-5.md # .claude/commands/backlog/fail-6.md # .claude/commands/backlog/help.md # .claude/commands/backlog/review.md # .claude/commands/backlog/ship.md # .claude/commands/backlog/status.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
AntigravityTarget.save_commands()andGeminiTarget.save_commands()'s embedded Antigravity-skill block both wrote a Claude command's raw$ARGUMENTStoken verbatim into the syncedSKILL.md. Antigravity skills are auto-triggered by relevance, not explicitly invoked with positional arguments — confirmed against antigravity.google/docs/skills — so$ARGUMENTSsynced there is inert dead text, not a partial gap to template around.Closes #37.
What Changed
build_antigravity_skill_content()instapler-scripts/llm-sync/src/targets/gemini.py, used by both write sites:AntigravityTarget.save_commands()andGeminiTarget.save_commands()'s embedded Antigravity block. It warns viaconsole.printand prepends an inline HTML-comment annotation toSKILL.mdwhencmd.contentcontains$ARGUMENTS..toml$ARGUMENTS→{{args}}substitution path untouched (it's the one write site that already handles this correctly).AGENTS.mdnext to the existing "commands sync as skills here" note.stapler-scripts/llm-sync/test_gemini_sync.py, an assert-based self-check (no test framework dependency) covering both write sites, the unaffected no-$ARGUMENTScase, and a regression check on the legacy.tomlpath.~/.gemini/config/skills/{ponytail-ponytail,git-stacked-prs-stack}/SKILL.mdand confirmed (by reading them back) they now carry the annotation.Known gap
AC0 of the linked issue — confirming in the live Antigravity IDE whether a synced skill actually receives argument text at invocation — could not be completed here: no headless invocation path exists on this machine (no
antigravitybinary onPATH; the localagentapiCLI requires a running language-server session viaANTIGRAVITY_LS_ADDRESS, which isn't set). This needs a manual click-through in the live app.Test plan
uv run test_gemini_sync.pyfromstapler-scripts/llm-sync/→ 5/5 checks pass~/.gemini/config/skills/ponytail-ponytail/SKILL.mdand.../git-stacked-prs-stack/SKILL.md— both now contain thellm-sync:annotation before the original$ARGUMENTStextponytail-ponytail) in the live Antigravity app with trailing argument text and observe whether the argument is used🤖 Generated with Claude Code
https://claude.ai/code/session_01BBE3c8U9NH9dL2yD9DHcBY