From f515c2aa1906fd0ccaa5c7d1d2c9ac96a5b65de4 Mon Sep 17 00:00:00 2001 From: Jed Levin Date: Wed, 21 Jan 2026 21:47:06 -0700 Subject: [PATCH] Add antigravity support and generic overlays structure --- overlays/antigravity/plan-product.md | 204 +++++++++++++++++++++ overlays/antigravity/shape-spec.md | 261 +++++++++++++++++++++++++++ scripts/project-install.sh | 134 ++++++++++++-- 3 files changed, 581 insertions(+), 18 deletions(-) create mode 100644 overlays/antigravity/plan-product.md create mode 100644 overlays/antigravity/shape-spec.md diff --git a/overlays/antigravity/plan-product.md b/overlays/antigravity/plan-product.md new file mode 100644 index 00000000..c3927608 --- /dev/null +++ b/overlays/antigravity/plan-product.md @@ -0,0 +1,204 @@ +# Plan Product + +Establish foundational product documentation through an interactive conversation. Creates mission, roadmap, and tech stack files in `agent-os/product/`. + +## Important Guidelines + +- **Always ask the user** when you need input or key decisions. +- **Keep it lightweight** — gather enough to create useful docs without over-documenting +- **One question at a time** — don't overwhelm with multiple questions + +## Process + +### Step 1: Check for Existing Product Docs + +Check if `agent-os/product/` exists and contains any of these files: +- `mission.md` +- `roadmap.md` +- `tech-stack.md` + +**If any files exist**, ask the user: + +``` +I found existing product documentation: +- mission.md: [exists/missing] +- roadmap.md: [exists/missing] +- tech-stack.md: [exists/missing] + +Would you like to: +1. Start fresh (replace all) +2. Update specific files +3. Cancel + +(Choose 1, 2, or 3) +``` + +If option 2, ask which files to update and only gather info for those. +If option 3, stop here. + +**If no files exist**, proceed to Step 2. + +### Step 2: Gather Product Vision (for mission.md) + +Ask the user: + +``` +Let's define your product's mission. + +**What problem does this product solve?** + +(Describe the core problem or pain point you're addressing) +``` + +After they respond, ask the user: + +``` +**Who is this product for?** + +(Describe your target users or audience) +``` + +After they respond, ask the user: + +``` +**What makes your solution unique?** + +(What's the key differentiator or approach?) +``` + +### Step 3: Gather Roadmap (for roadmap.md) + +Ask the user: + +``` +Now let's outline your development roadmap. + +**What are the must-have features for launch (MVP)?** + +(List the core features needed for the first usable version) +``` + +After they respond, ask the user: + +``` +**What features are planned for after launch?** + +(List features you'd like to add in future phases, or say "none yet") +``` + +### Step 4: Establish Tech Stack (for tech-stack.md) + +First, check if `agent-os/standards/global/tech-stack.md` exists. + +**If the tech-stack standard exists**, read it and ask the user: + +``` +I found a tech stack standard in your standards: + +[Summarize the key technologies from global/tech-stack.md] + +Does this project use the same tech stack, or does it differ? + +1. Same as standard (use as-is) +2. Different (I'll specify) + +(Choose 1 or 2) +``` + +If they choose option 1, use the standard's content for tech-stack.md. +If they choose option 2, proceed to ask them to specify (see below). + +**If no tech-stack standard exists** (or they chose option 2 above), ask the user: + +``` +**What technologies does this project use?** + +Please describe your tech stack: +- Frontend: (e.g., React, Vue, vanilla JS, or N/A) +- Backend: (e.g., Rails, Node, Django, or N/A) +- Database: (e.g., PostgreSQL, MongoDB, or N/A) +- Other: (hosting, APIs, tools, etc.) +``` + +### Step 5: Generate Files + +Create the `agent-os/product/` directory if it doesn't exist. + +Generate each file based on the information gathered: + +#### mission.md + +```markdown +# Product Mission + +## Problem + +[Insert what problem this product solves - from Step 2] + +## Target Users + +[Insert who this product is for - from Step 2] + +## Solution + +[Insert what makes the solution unique - from Step 2] +``` + +#### roadmap.md + +```markdown +# Product Roadmap + +## Phase 1: MVP + +[Insert must-have features for launch - from Step 3] + +## Phase 2: Post-Launch + +[Insert planned future features - from Step 3, or "To be determined" if they said none yet] +``` + +#### tech-stack.md + +```markdown +# Tech Stack + +[Organize the tech stack information into logical sections] + +## Frontend + +[Frontend technologies, or "N/A" if not applicable] + +## Backend + +[Backend technologies, or "N/A" if not applicable] + +## Database + +[Database choice, or "N/A" if not applicable] + +## Other + +[Other tools, hosting, services - or omit this section if nothing mentioned] +``` + +### Step 6: Confirm Completion + +After creating all files, output to user: + +``` +✓ Product documentation created: + + agent-os/product/mission.md + agent-os/product/roadmap.md + agent-os/product/tech-stack.md + +Review these files to ensure they accurately capture your product vision. +You can edit them directly or run /plan-product again to update. +``` + +## Tips + +- If the user provides very brief answers, that's fine — the docs can be expanded later +- If they want to skip a section, create the file with a placeholder like "To be defined" +- The `/shape-spec` command will read these files when planning features, so having them populated helps with context diff --git a/overlays/antigravity/shape-spec.md b/overlays/antigravity/shape-spec.md new file mode 100644 index 00000000..bd8088b3 --- /dev/null +++ b/overlays/antigravity/shape-spec.md @@ -0,0 +1,261 @@ +# Shape Spec + +Gather context and structure planning for significant work. **Run this command while in PLANNING mode.** + +## Important Guidelines + +- **Always ask the user** when you need input or key decisions. +- **Offer suggestions** — Present options the user can confirm, adjust, or correct +- **Keep it lightweight** — This is shaping, not exhaustive documentation + +## Prerequisites + +This command **must be run in PLANNING mode**. + +**Before proceeding, check if you are currently in PLANNING mode.** + +If NOT in planning mode, **stop immediately** and call `task_boundary` to switch to PLANNING mode, then continue. + +## Process + +### Step 1: Clarify What We're Building + +Ask the user to understand the scope: + +``` +What are we building? Please describe the feature or change. + +(Be as specific as you like — I'll ask follow-up questions if needed) +``` + +Based on their response, ask 1-2 clarifying questions if the scope is unclear. Examples: +- "Is this a new feature or a change to existing functionality?" +- "What's the expected outcome when this is done?" +- "Are there any constraints or requirements I should know about?" + +### Step 2: Gather Visuals + +Ask the user: + +``` +Do you have any visuals to reference? + +- Mockups or wireframes +- Screenshots of similar features +- Examples from other apps + +(Paste images, share file paths, or say "none") +``` + +If visuals are provided, note them for inclusion in the spec folder. + +### Step 3: Identify Reference Implementations + +Ask the user: + +``` +Is there similar code in this codebase I should reference? + +Examples: +- "The comments feature is similar to what we're building" +- "Look at how src/features/notifications/ handles real-time updates" +- "No existing references" + +(Point me to files, folders, or features to study) +``` + +If references are provided, read and analyze them to inform the plan. + +### Step 4: Check Product Context + +Check if `agent-os/product/` exists and contains files. + +If it exists, read key files (like `mission.md`, `roadmap.md`, `tech-stack.md`) and ask the user: + +``` +I found product context in agent-os/product/. Should this feature align with any specific product goals or constraints? + +Key points from your product docs: +- [summarize relevant points] + +(Confirm alignment or note any adjustments) +``` + +If no product folder exists, skip this step. + +### Step 5: Surface Relevant Standards + +Read `agent-os/standards/index.yml` to identify relevant standards based on the feature being built. + +Ask the user to confirm: + +``` +Based on what we're building, these standards may apply: + +1. **api/response-format** — API response envelope structure +2. **api/error-handling** — Error codes and exception handling +3. **database/migrations** — Migration patterns + +Should I include these in the spec? (yes / adjust: remove 3, add frontend/forms) +``` + +Read the confirmed standards files to include their content in the plan context. + +### Step 6: Generate Spec Folder Name + +Create a folder name using this format: +``` +YYYY-MM-DD-HHMM-{feature-slug}/ +``` + +Where: +- Date/time is current timestamp +- Feature slug is derived from the feature description (lowercase, hyphens, max 40 chars) + +Example: `2026-01-15-1430-user-comment-system/` + +**Note:** If `agent-os/specs/` doesn't exist, create it when saving the spec folder. + +### Step 7: Structure the Plan + +Now build the plan with **Task 1 always being "Save spec documentation"**. + +Present this structure to the user: + +``` +Here's the plan structure. Task 1 saves all our shaping work before implementation begins. + +--- + +## Task 1: Save Spec Documentation + +Create `agent-os/specs/{folder-name}/` with: + +- **plan.md** — This full plan +- **shape.md** — Shaping notes (scope, decisions, context from our conversation) +- **standards.md** — Relevant standards that apply to this work +- **references.md** — Pointers to reference implementations studied +- **visuals/** — Any mockups or screenshots provided + +## Task 2: [First implementation task] + +[Description based on the feature] + +## Task 3: [Next task] + +... + +--- + +Does this plan structure look right? I'll fill in the implementation tasks next. +``` + +### Step 8: Complete the Plan + +After Task 1 is confirmed, continue building out the remaining implementation tasks based on: +- The feature scope from Step 1 +- Patterns from reference implementations (Step 3) +- Constraints from standards (Step 5) + +Each task should be specific and actionable. + +### Step 9: Ready for Execution + +When the full plan is ready: + +``` +Plan complete. When you approve and execute: + +1. Task 1 will save all spec documentation first +2. Then implementation tasks will proceed + +Ready to start? (approve / adjust) +``` + +## Output Structure + +The spec folder will contain: + +``` +agent-os/specs/{YYYY-MM-DD-HHMM-feature-slug}/ +├── plan.md # The full plan +├── shape.md # Shaping decisions and context +├── standards.md # Which standards apply and key points +├── references.md # Pointers to similar code +└── visuals/ # Mockups, screenshots (if any) +``` + +## shape.md Content + +The shape.md file should capture: + +```markdown +# {Feature Name} — Shaping Notes + +## Scope + +[What we're building, from Step 1] + +## Decisions + +- [Key decisions made during shaping] +- [Constraints or requirements noted] + +## Context + +- **Visuals:** [List of visuals provided, or "None"] +- **References:** [Code references studied] +- **Product alignment:** [Notes from product context, or "N/A"] + +## Standards Applied + +- api/response-format — [why it applies] +- api/error-handling — [why it applies] +``` + +## standards.md Content + +Include the full content of each relevant standard: + +```markdown +# Standards for {Feature Name} + +The following standards apply to this work. + +--- + +## api/response-format + +[Full content of the standard file] + +--- + +## api/error-handling + +[Full content of the standard file] +``` + +## references.md Content + +```markdown +# References for {Feature Name} + +## Similar Implementations + +### {Reference 1 name} + +- **Location:** `src/features/comments/` +- **Relevance:** [Why this is relevant] +- **Key patterns:** [What to borrow from this] + +### {Reference 2 name} + +... +``` + +## Tips + +- **Keep shaping fast** — Don't over-document. Capture enough to start, refine as you build. +- **Visuals are optional** — Not every feature needs mockups. +- **Standards guide, not dictate** — They inform the plan but aren't always mandatory. +- **Specs are discoverable** — Months later, someone can find this spec and understand what was built and why. diff --git a/scripts/project-install.sh b/scripts/project-install.sh index 8688d4ad..7845e4a3 100755 --- a/scripts/project-install.sh +++ b/scripts/project-install.sh @@ -22,6 +22,9 @@ source "$SCRIPT_DIR/common-functions.sh" VERBOSE="false" PROFILE="" COMMANDS_ONLY="false" +AGENT_OS_COMMANDS="false" +ANTIGRAVITY="false" +OVERLAY="" # ----------------------------------------------------------------------------- # Help Function @@ -34,15 +37,20 @@ Usage: $0 [OPTIONS] Install Agent OS into the current project directory. Options: - --profile Use specified profile (default: from config.yml) - --commands-only Only update commands, preserve existing standards - --verbose Show detailed output - -h, --help Show this help message + --profile Use specified profile (default: from config.yml) + --commands-only Only update commands, preserve existing standards + --agent-os-commands Install commands to agent-os/commands/ instead of .claude/ + --antigravity Install for Antigravity (sets destination and overlay) + --overlay Apply a command overlay (e.g., antigravity) + --verbose Show detailed output + -h, --help Show this help message Examples: $0 $0 --profile rails $0 --commands-only + $0 --antigravity + $0 --agent-os-commands --overlay antigravity EOF exit 0 @@ -63,6 +71,19 @@ parse_arguments() { COMMANDS_ONLY="true" shift ;; + --agent-os-commands) + AGENT_OS_COMMANDS="true" + shift + ;; + --antigravity) + ANTIGRAVITY="true" + OVERLAY="antigravity" + shift + ;; + --overlay) + OVERLAY="$2" + shift 2 + ;; --verbose) VERBOSE="true" shift @@ -241,11 +262,11 @@ install_standards() { grep -v "^${relative_path}|" "$sources_file" > "${sources_file}.tmp" 2>/dev/null || true mv "${sources_file}.tmp" "$sources_file" echo "${relative_path}|${profile_name}" >> "$sources_file" - ((profile_file_count++)) + ((++profile_file_count)) done < <(find "$profile_standards" -name "*.md" -type f ! -path "*/.backups/*" -print0 2>/dev/null) if [[ "$profile_file_count" -gt 0 ]]; then - ((profiles_used++)) + ((++profiles_used)) fi done <<< "$INHERITANCE_CHAIN" @@ -335,11 +356,11 @@ create_index() { local desc=$(get_existing_description "root" "$filename") if [[ -z "$desc" ]]; then desc="Needs description - run /index-standards" - ((new_count++)) + ((++new_count)) fi echo " $filename:" >> "$temp_file" echo " description: $desc" >> "$temp_file" - ((entry_count++)) + ((++entry_count)) done <<< "$root_files" echo "" >> "$temp_file" fi @@ -357,11 +378,11 @@ create_index() { local desc=$(get_existing_description "$folder_name" "$filename") if [[ -z "$desc" ]]; then desc="Needs description - run /index-standards" - ((new_count++)) + ((++new_count)) fi echo " $filename:" >> "$temp_file" echo " description: $desc" >> "$temp_file" - ((entry_count++)) + ((++entry_count)) done <<< "$md_files" echo "" >> "$temp_file" fi @@ -385,8 +406,60 @@ install_commands() { echo "" print_status "Installing commands..." + # Helper function to extract description (first non-header, non-empty line) + extract_description() { + local file="$1" + # Skip lines starting with #, empty lines, and get the first remaining line + grep -v '^[#[:space:]]' "$file" | grep -v '^$' | head -n 1 | sed 's/^[[:space:]]*//;s/[[:space:]]*$//' + } + + # Helper function to install file with optional frontmatter + install_command_file() { + local src="$1" + local dest_dir="$2" + local filename=$(basename "$src") + local dest="$dest_dir/$filename" + + if [[ "$ANTIGRAVITY" == "true" ]]; then + # Extract description + local description=$(extract_description "$src") + if [[ -z "$description" ]]; then + description="Agent OS command: $filename" + fi + + # Create temp file with frontmatter + local temp_file=$(mktemp) + { + echo "---" + echo "description: $description" + echo "---" + echo "" + cat "$src" + } > "$temp_file" + + mv "$temp_file" "$dest" + chmod 644 "$dest" 2>/dev/null || true + else + cp "$src" "$dest" + fi + } + + local commands_dest="" + local dest_display="" + + # Determine destination based on flag + if [[ "$ANTIGRAVITY" == "true" ]]; then + commands_dest="$PROJECT_DIR/.agent/workflows" + dest_display=".agent/workflows/" + elif [[ "$AGENT_OS_COMMANDS" == "true" ]]; then + commands_dest="$PROJECT_DIR/agent-os/commands" + dest_display="agent-os/commands/" + else + commands_dest="$PROJECT_DIR/.claude/commands/agent-os" + dest_display=".claude/commands/agent-os/" + fi + local commands_source="$BASE_DIR/commands/agent-os" - local commands_dest="$PROJECT_DIR/.claude/commands/agent-os" if [[ ! -d "$commands_source" ]]; then print_warning "No commands found in base installation" @@ -395,18 +468,38 @@ install_commands() { ensure_dir "$commands_dest" - local count=0 + # Install base commands + local base_count=0 for file in "$commands_source"/*.md; do if [[ -f "$file" ]]; then - cp "$file" "$commands_dest/" - ((count++)) + install_command_file "$file" "$commands_dest" + ((++base_count)) fi done - if [[ "$count" -gt 0 ]]; then - print_success "Installed $count commands to .claude/commands/agent-os/" + if [[ "$base_count" -gt 0 ]]; then + print_success "Installed $base_count base commands to $dest_display" else - print_warning "No command files found" + print_warning "No base command files found" + fi + + # Install overlay if specified + if [[ -n "$OVERLAY" ]]; then + local overlay_source="$BASE_DIR/overlays/$OVERLAY" + if [[ -d "$overlay_source" ]]; then + echo "Applying overlay: $OVERLAY" + local overlay_count=0 + for file in "$overlay_source"/*.md; do + if [[ -f "$file" ]]; then + install_command_file "$file" "$commands_dest" + echo " Overriding $(basename "$file")" + ((++overlay_count)) + fi + done + print_success "Applied $overlay_count overlay commands from $OVERLAY" + else + print_warning "Overlay directory not found: overlays/$OVERLAY" + fi fi } @@ -447,11 +540,16 @@ main() { done chain_display="$chain_display"$'\n'"$indent ↳ inherits from: $profile_name" fi - ((chain_depth++)) + ((++chain_depth)) done <<< "$reversed_chain" echo "$chain_display" echo " Commands only: $COMMANDS_ONLY" + echo " Agent OS commands path: $AGENT_OS_COMMANDS" + echo " Antigravity mode: $ANTIGRAVITY" + if [[ -n "$OVERLAY" ]]; then + echo " Overlay: $OVERLAY" + fi # Confirm overwrite if standards folder exists confirm_standards_overwrite