[docs] docs: reduce bloat in VS Code integration documentation

[github-actions]

Summary

Improved clarity and conciseness in the VS Code integration documentation (docs/src/content/docs/tools/vscode.md) by removing bloat and streamlining content.

Changes Made

Bloat Removed:

• ❌ Duplicate "Initialize your repository" tip boxes (appeared twice with identical content)
• ❌ Verbose bullet lists converted to concise prose
• ❌ Repetitive language patterns ("Once configured", "Once the prompt file is created")
• ❌ Redundant explanations throughout the document
• ❌ Overly wordy instructions for background compilation

Improvements:

• ✅ Consolidated two separate sections into a unified Setup section
• ✅ Streamlined the /create-agentic-workflow command description
• ✅ Simplified background compilation instructions
• ✅ Preserved all technical accuracy and essential details
• ✅ Maintained all code examples and links

Metrics

• Lines reduced: 96 → 65 (32% reduction)
• Bullet points: Consolidated from verbose lists into prose
• Duplicate content: Eliminated 2 identical tip boxes
• Word count: Significantly reduced while maintaining clarity

Screenshot

The updated documentation page rendered in the Astro Starlight site:

Network Status

✅ All CSS, fonts, and resources loaded successfully - no blocked domains encountered during screenshot capture.

---

🤖 Generated with Claude Code

AI generated by Documentation Unbloat

[Copilot]

Pull Request Overview

This PR reduces bloat in the VS Code integration documentation by consolidating duplicated content, converting verbose bullet lists to concise prose, and streamlining explanations while preserving all technical accuracy.

Key Changes:

• Consolidated two separate sections with duplicate "Initialize your repository" tips into a unified Setup section
• Converted verbose bullet-point instructions into concise prose throughout the document
• Reduced document length by 32% (96 → 65 lines) while maintaining all essential information

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[github-actions]

Agentic Changeset Generator triggered by this pull request.

[github-actions]

🔍 Smoke Test Investigation - Run #65

Summary

The Smoke Copilot workflow failed due to a bash script syntax error caused by unescaped parentheses in --allow-tool flags. When the workflow compiler generates the Copilot CLI command with shell tool permissions like --allow-tool 'shell(cat)', bash interprets the parentheses as subshell syntax instead of literal characters, causing immediate script failure.

Failure Details

• Run: #18810304059
• Commit: b650b2a
• Trigger: schedule
• Duration: 1.0 minutes
• Failed Jobs: agent (28s), create_issue (4s)

Root Cause Analysis

Error Location: agent job → Execute GitHub Copilot CLI step → Line 31

/home/runner/work/_temp/56e2f420-c07f-4797-a3fd-45d349bc4eb9.sh: line 5: syntax error near unexpected token `('
##[error]Process completed with exit code 2.

Generated Command (from logs):

npx -y `@github/copilot`@0.0.351 \
  --add-dir /tmp/gh-aw/ \
  --allow-tool github \
  --allow-tool safeoutputs \
  --allow-tool 'shell(cat)' \
  --allow-tool 'shell(date)' \
  --allow-tool 'shell(echo)' \
  # ... more shell tools ...

The Problem:

1. Workflow compiler generates: --allow-tool 'shell(cat)'
2. GitHub Actions creates bash script with this command
3. When bash executes, it sees: shell(cat)
4. Bash interprets ( as subshell syntax → syntax error
5. Script exits immediately with code 2

Failed Jobs and Errors

Job Sequence

1. ✅ activation - succeeded (3s)
2. ❌ agent - failed (28s) - Bash syntax error before Copilot could start
3. ❌ create_issue - failed (4s) - No output file (agent never ran)
4. ⏭️ missing_tool - skipped
5. ⏭️ detection - skipped

Error Chain

Bash syntax error
    ↓
Agent job fails immediately (exit code 2)
    ↓
No Copilot execution
    ↓
No agent_output.json created
    ↓
create_issue job fails: ENOENT

Investigation Findings

This is a NEW failure pattern - first occurrence in smoke test history.

Key Technical Details

• Copilot Version: 0.0.351
• Platform: ubuntu-latest, bash 5.x
• Shell Tools Configured: shell(cat), shell(date), shell(echo), shell(grep), shell(head), shell(ls), shell(pwd), shell(sort), shell(tail), shell(uniq), shell(wc), shell(yq)
• Failure Point: Before Copilot CLI execution (bash script parsing)
• Impact: Complete blocker for Copilot smoke tests

Why This Happens

The single quotes in the YAML ('shell(cat)') are not preserved when GitHub Actions generates and executes the bash script. Bash sees the unquoted parentheses and tries to parse them as command substitution/subshell syntax.

Recommended Actions

Critical Priority ⚠️

• Fix workflow compiler to escape parentheses in tool names

  • Location: Likely in pkg/workflow/compiler.go or pkg/workflow/agent.go where --allow-tool flags are generated
  • Option 1: Double-escape in YAML: --allow-tool shell\\(cat\\)
  • Option 2: Use printf-style escaping: --allow-tool "shell(cat)"
  • Option 3: Alternative quoting strategy that survives bash execution
  • Why: This is a workflow generation bug blocking all Copilot executions

• Search codebase for tool permission generation code

  grep -r "allow-tool" pkg/
  grep -r "shell(" pkg/

  • Why: Identify exact location where flags are constructed

• Add test case for special characters in tool names

  func TestToolNamesWithParentheses(t *testing.T) {
    tools := []string{"shell(cat)", "shell(grep)", "shell(ls)"}
    cmd := generateAllowToolFlags(tools)
    // Validate command can be executed by bash without syntax errors
  }

  • Why: Prevent regression

High Priority

• Test the fix across all engines

  • Verify Claude Code, Codex don't have similar issues
  • Check if other special characters (brackets, braces) have problems
  • Why: Ensure comprehensive fix

• Add CI validation for generated bash syntax

  • After workflow compilation, validate bash syntax with bash -n
  • Why: Catch issues before deployment

• Document tool naming conventions

  • Add guidelines for tool names with special characters
  • Why: Prevent future issues

Medium Priority

• Consider alternative tool naming syntax

  • Use shell-cat or shell_cat instead of shell(cat)
  • Why: Avoids special characters entirely (but breaking change)

• Review other workflow generation patterns

  • Check if similar escaping issues exist elsewhere
  • Why: Proactive prevention

Prevention Strategies

1. Shell Escaping Library: Use a robust shell escaping library when generating bash commands

   import "mvdan.cc/sh/v3/syntax"
   
   func escapeForShell(arg string) string {
       return syntax.Quote(arg, syntax.LangBash)
   }

2. Validation Pipeline: Add bash syntax validation to workflow compilation

   awf compile workflow.md
   bash -n workflow.lock.yml  # Validate syntax

3. Integration Tests: Test workflow compilation with edge cases

   • Tool names with parentheses, brackets, quotes
   • Commands with special characters
   • Multi-line commands

4. Pre-commit Hooks: Validate generated YAML before commit

Historical Context

Related Issues: None found - this is a new failure pattern

Pattern Classification:

• Pattern ID: COPILOT_BASH_SHELL_SYNTAX_PARENTHESES
• Category: Bash Script Generation Error
• Severity: Critical
• Is Flaky: No - deterministic compilation bug
• First Occurrence: 2025-10-26T00:12:23Z (this run)

Investigation saved to: /tmp/gh-aw/cache-memory/investigations/2025-10-26-18810304059.json

---

Note: This failure is NOT related to the PR changes (documentation updates). This is a pre-existing workflow compilation bug that was triggered by the scheduled smoke test run on the merged commit.

---

Investigation Metadata:

• Investigator: Smoke Detector
• Investigation Run: #18810315332
• Pattern ID: COPILOT_BASH_SHELL_SYNTAX_PARENTHESES
• Severity: Critical
• Is Flaky: No
• Is New Pattern: Yes

AI generated by Smoke Detector - Smoke Test Failure Investigator