chore(ci): add Claude coded architecture doc validation workflow - Add automated validation of SOFTWARE_ARCHITECTURE.md on PRs to ensure - skip:test:long_running #4
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
| name: "+ Claude Code / Architecture Doc Validation" | ||
| permissions: | ||
| contents: read | ||
| pull-requests: write | ||
| on: | ||
| pull_request: | ||
| types: [opened, synchronize] | ||
| paths: | ||
| - 'src/aignostics/**/*.py' | ||
| - 'pyproject.toml' | ||
| - '.github/workflows/**/*.yml' | ||
| - 'SOFTWARE_ARCHITECTURE.md' | ||
| workflow_dispatch: | ||
| inputs: | ||
| platform_environment: | ||
| description: 'Environment to use' | ||
| required: false | ||
| default: 'staging' | ||
| type: choice | ||
| options: | ||
| - staging | ||
| - production | ||
| pr_number: | ||
| description: 'PR number (for manual runs)' | ||
| required: false | ||
| type: string | ||
| jobs: | ||
| architecture-validation: | ||
|
Check failure on line 30 in .github/workflows/claude-code-architecture-validation.yml
|
||
| uses: ./.github/workflows/_claude-code.yml | ||
| with: | ||
| platform_environment: ${{ inputs.platform_environment || 'staging' }} | ||
| mode: 'automation' | ||
| track_progress: ${{ github.event_name != 'workflow_dispatch' && true || false }} | ||
| allowed_tools: 'Read,Write,Edit,Glob,Grep,Bash(git:*),Bash(gh:*),Bash(find:*),Bash(cat:*),Bash(echo:*)' | ||
| prompt: | | ||
| # SOFTWARE ARCHITECTURE VALIDATION FOR PULL REQUEST | ||
| **REPO**: ${{ github.repository }} | ||
| **PR**: ${{ github.event.pull_request.number && format('#{0}', github.event.pull_request.number) || inputs.pr_number || 'Manual Run' }} | ||
| **BRANCH**: ${{ github.event.pull_request.head.ref || github.ref_name }} | ||
| ## Your Mission | ||
| You are an architecture documentation validator. Your task is to: | ||
| 1. **Analyze** the code changes in this PR to understand their architectural impact | ||
| 2. **Validate** that `SOFTWARE_ARCHITECTURE.md` accurately reflects the current codebase after these changes | ||
| 3. **Identify** any discrepancies between the code and the documentation | ||
| 4. **Suggest** specific, actionable updates to `SOFTWARE_ARCHITECTURE.md` with exact text to add/modify | ||
| 5. **Comment** on the PR with your findings and recommendations for human review | ||
| ## CRITICAL: You MUST use tools to gather information | ||
| - Use the **Bash** tool to execute all git/gh commands shown below | ||
| - Use the **Read** tool to read files | ||
| - Use the **Grep** tool to search for patterns | ||
| - Use the **Glob** tool to find files | ||
| Do NOT just acknowledge these commands - you must ACTUALLY EXECUTE them. | ||
| ## Step 1: Understand PR Changes | ||
| Execute these commands using the Bash tool to understand what changed: | ||
| ```bash | ||
| PR_NUMBER="${{ github.event.pull_request.number || inputs.pr_number }}" | ||
| if [ -n "$PR_NUMBER" ]; then | ||
| echo "=== Changed files in PR #$PR_NUMBER ===" | ||
| gh pr view "$PR_NUMBER" --json files --jq '.files[].path' | sort | ||
| else | ||
| echo "=== Changed files (comparing with main) ===" | ||
| git diff --name-only origin/main...HEAD | sort | ||
| fi | ||
| ``` | ||
| After seeing the file list, get the detailed changes for architectural files: | ||
| ```bash | ||
| PR_NUMBER="${{ github.event.pull_request.number || inputs.pr_number }}" | ||
| if [ -n "$PR_NUMBER" ]; then | ||
| gh pr diff "$PR_NUMBER" | head -500 | ||
| else | ||
| git diff origin/main...HEAD | head -500 | ||
| fi | ||
| ``` | ||
| ## Step 2: Read Current Architecture Document | ||
| Use the Read tool to read `SOFTWARE_ARCHITECTURE.md` and understand its current structure. | ||
| ## Step 3: Validate Architecture Accuracy | ||
| For each change in the PR, check if the architecture document needs updates: | ||
| ### Check 1: New Modules or Files | ||
| ```bash | ||
| # Look for new modules | ||
| echo "=== Checking for New Modules ===" | ||
| PR_NUMBER="${{ github.event.pull_request.number }}" | ||
| # Check if new directories were added in src/aignostics/ | ||
| if [ -n "$PR_NUMBER" ]; then | ||
| NEW_MODULES=$(gh pr diff "$PR_NUMBER" | grep "^+++ b/src/aignostics/" | cut -d/ -f3 | sort -u) | ||
| else | ||
| NEW_MODULES=$(git diff origin/main...HEAD --name-only | grep "^src/aignostics/" | cut -d/ -f3 | sort -u) | ||
| fi | ||
| if [ -n "$NEW_MODULES" ]; then | ||
| echo "New modules detected:" | ||
| echo "$NEW_MODULES" | ||
| # Check if these are documented in SOFTWARE_ARCHITECTURE.md | ||
| for module in $NEW_MODULES; do | ||
| if grep -q "$module" SOFTWARE_ARCHITECTURE.md; then | ||
| echo " ✅ $module is documented" | ||
| else | ||
| echo " ❌ BLOCKING: $module NOT documented in architecture" | ||
| fi | ||
| done | ||
| fi | ||
| ``` | ||
| ### Check 2: Dependency Changes | ||
| ```bash | ||
| echo "=== Checking Dependency Changes ===" | ||
| PR_NUMBER="${{ github.event.pull_request.number }}" | ||
| # Check if pyproject.toml was modified | ||
| if [ -n "$PR_NUMBER" ]; then | ||
| PYPROJECT_CHANGED=$(gh pr diff "$PR_NUMBER" --name-only | grep -q "pyproject.toml" && echo "yes" || echo "no") | ||
| else | ||
| PYPROJECT_CHANGED=$(git diff origin/main...HEAD --name-only | grep -q "pyproject.toml" && echo "yes" || echo "no") | ||
| fi | ||
| if [ "$PYPROJECT_CHANGED" = "yes" ]; then | ||
| echo "⚠️ pyproject.toml was modified - check if dependencies section needs update" | ||
| # Extract new dependencies from diff | ||
| if [ -n "$PR_NUMBER" ]; then | ||
| gh pr diff "$PR_NUMBER" -- pyproject.toml | grep "^+" | grep -E "(dependencies|extras)" || echo "No dependency changes detected" | ||
| else | ||
| git diff origin/main...HEAD -- pyproject.toml | grep "^+" | grep -E "(dependencies|extras)" || echo "No dependency changes detected" | ||
| fi | ||
| fi | ||
| ``` | ||
| ### Check 3: Workflow/CI Changes | ||
| ```bash | ||
| echo "=== Checking CI/CD Changes ===" | ||
| PR_NUMBER="${{ github.event.pull_request.number }}" | ||
| # Check if workflows were added/modified | ||
| if [ -n "$PR_NUMBER" ]; then | ||
| WORKFLOW_FILES=$(gh pr diff "$PR_NUMBER" --name-only | grep ".github/workflows/" || echo "") | ||
| else | ||
| WORKFLOW_FILES=$(git diff origin/main...HEAD --name-only | grep ".github/workflows/" || echo "") | ||
| fi | ||
| if [ -n "$WORKFLOW_FILES" ]; then | ||
| echo "⚠️ GitHub workflows modified - check if CI/CD section needs update" | ||
| echo "$WORKFLOW_FILES" | ||
| fi | ||
| ``` | ||
| ### Check 4: Architecture Pattern Changes | ||
| ```bash | ||
| echo "=== Checking Architecture Patterns ===" | ||
| PR_NUMBER="${{ github.event.pull_request.number }}" | ||
| # Look for significant structural changes | ||
| if [ -n "$PR_NUMBER" ]; then | ||
| SIGNIFICANT_CHANGES=$(gh pr diff "$PR_NUMBER" --name-only | grep -E "(src/aignostics/.*/_service.py|src/aignostics/.*/_cli.py|src/aignostics/.*/_gui.py|src/aignostics/utils/)" || echo "") | ||
| else | ||
| SIGNIFICANT_CHANGES=$(git diff origin/main...HEAD --name-only | grep -E "(src/aignostics/.*/_service.py|src/aignostics/.*/_cli.py|src/aignostics/.*/_gui.py|src/aignostics/utils/)" || echo "") | ||
| fi | ||
| if [ -n "$SIGNIFICANT_CHANGES" ]; then | ||
| echo "Significant architectural files changed:" | ||
| echo "$SIGNIFICANT_CHANGES" | ||
| # Read these files to understand the changes | ||
| for file in $SIGNIFICANT_CHANGES; do | ||
| echo "" | ||
| echo "=== Reading: $file ===" | ||
| cat "$file" 2>/dev/null || echo "File not found or deleted" | ||
| done | ||
| fi | ||
| ``` | ||
| ### Check 5: Module Structure Validation | ||
| ```bash | ||
| echo "=== Validating Module Structure ===" | ||
| # List current modules | ||
| CURRENT_MODULES=$(find src/aignostics -maxdepth 1 -type d -not -name "__pycache__" -not -name "aignostics" | sed 's|src/aignostics/||' | sort) | ||
| echo "Current modules in codebase:" | ||
| echo "$CURRENT_MODULES" | ||
| echo "" | ||
| # Check which modules are documented in SOFTWARE_ARCHITECTURE.md | ||
| echo "Checking documentation coverage:" | ||
| for module in $CURRENT_MODULES; do | ||
| if [ -n "$module" ]; then | ||
| if grep -qi "$module" SOFTWARE_ARCHITECTURE.md; then | ||
| echo " ✅ $module - documented" | ||
| else | ||
| echo " ⚠️ $module - not found in architecture doc" | ||
| fi | ||
| fi | ||
| done | ||
| ``` | ||
| ## Step 4: Generate PR Comment | ||
| After validation, post findings as a PR comment: | ||
| ```bash | ||
| PR_NUMBER="${{ github.event.pull_request.number }}" | ||
| BRANCH_NAME="${{ github.event.pull_request.head.ref || github.ref_name }}" | ||
| # Build the comment with actual values | ||
| cat > /tmp/architecture-validation.md << EOF | ||
| # 🏗️ Software Architecture Validation | ||
| **PR**: $([ -n "$PR_NUMBER" ] && echo "#$PR_NUMBER" || echo "Manual Run") | ||
| **Branch**: $BRANCH_NAME | ||
| **Architecture Doc**: \`SOFTWARE_ARCHITECTURE.md\` | ||
| --- | ||
| ## ❌ BLOCKING ISSUES | ||
| [List any critical discrepancies that must be fixed before merge] | ||
| ### Example: New Module Not Documented | ||
| **Issue**: New module `example_module` added but not documented in architecture | ||
| - **Location**: `src/aignostics/example_module/` | ||
| - **Missing from**: `SOFTWARE_ARCHITECTURE.md` Section 1.5 | ||
| - **Current State**: Module exists with `_service.py`, `_cli.py`, `_gui.py` | ||
| - **Required Action**: Add module description to Section 1.5 "Layers and Modules" | ||
| - **Suggested Content**: | ||
| ```markdown | ||
| **Example Module (`example_module/`)** | ||
| - **Service**: [Brief description of what this module does] | ||
| - **CLI**: [Command-line operations provided] | ||
| - **GUI**: [GUI interface features] | ||
| - **Settings**: [Configuration options] | ||
| ``` | ||
| --- | ||
| ## ⚠️ SUGGESTIONS | ||
| [List recommended but non-critical updates] | ||
| ### Example: Dependency Update | ||
| **Suggestion**: Update dependency list in Section 1.3 | ||
| - **Change**: `pyproject.toml` shows new dependency `new-library==1.0.0` | ||
| - **Current Doc**: Section 1.3 "Language and Frameworks" doesn't mention this | ||
| - **Recommendation**: Add to "Key Dependencies" section | ||
| - **Priority**: Medium (nice-to-have for completeness) | ||
| ### Example: Diagram Update | ||
| **Suggestion**: Update architecture diagram | ||
| - **Change**: New integration with external service | ||
| - **Current Doc**: Diagram in Section 1.2 doesn't show this integration | ||
| - **Recommendation**: Add connection to "External Services" layer in Mermaid diagram | ||
| - **Priority**: Low (diagram still conceptually accurate) | ||
| --- | ||
| ## ✅ VALIDATED SUCCESSFULLY | ||
| ### Code Changes That Don't Require Doc Updates | ||
| - ✅ **Bug fix in `application/_service.py`** - Internal implementation detail, no architectural impact | ||
| - ✅ **Test updates** - Test coverage improvements don't affect architecture | ||
| - ✅ **Minor refactoring** - Code organization changes within existing patterns | ||
| ### Architecture Doc Accuracy | ||
| - ✅ **Module structure** - All existing modules properly documented | ||
| - ✅ **Layer separation** - Presentation/Domain/Platform layers correctly described | ||
| - ✅ **Design principles** - Section 2 accurately reflects implementation patterns | ||
| --- | ||
| ## 📊 Summary | ||
| - **Files Changed**: X | ||
| - **New Modules Added**: Y | ||
| - **Blocking Issues**: N | ||
| - **Suggestions**: M | ||
| - **Architecture Doc Status**: [Accurate / Needs Updates] | ||
| --- | ||
| ## 🎯 Action Required | ||
| **Before merging this PR:** | ||
| 1. Update `SOFTWARE_ARCHITECTURE.md` Section X.Y with [specific changes] | ||
| 2. Add Mermaid diagram update for [new component/integration] | ||
| 3. Update dependency list in Section 1.3 | ||
| **Commands to verify current structure:** | ||
| ```bash | ||
| # List all modules | ||
| find src/aignostics -maxdepth 1 -type d | ||
| # Check dependencies | ||
| cat pyproject.toml | grep -A 50 "dependencies =" | ||
| # View architecture doc sections | ||
| grep "^##" SOFTWARE_ARCHITECTURE.md | ||
| ``` | ||
| --- | ||
| **Remember**: Architecture documentation is the blueprint for understanding and | ||
| maintaining this codebase. Keeping it accurate helps onboarding, compliance, and | ||
| long-term maintainability. | ||
| *Generated by Claude Code Architecture Validation* | ||
| EOF | ||
| # Post comment if this is a PR, otherwise just output to logs | ||
| if [ -n "$PR_NUMBER" ]; then | ||
| echo "Posting comment to PR #$PR_NUMBER" | ||
| gh pr comment "$PR_NUMBER" --body-file /tmp/architecture-validation.md | ||
| else | ||
| echo "Manual run - validation results:" | ||
| cat /tmp/architecture-validation.md | ||
| fi | ||
| ``` | ||
| ## Validation Criteria | ||
| ### BLOCKING Issues (Must Fix): | ||
| - New modules not documented in Section 1.5 | ||
| - Major architectural pattern changes not reflected in Section 1.2 | ||
| - New external integrations missing from Section 3 | ||
| - Significant dependency additions not listed in Section 1.3 | ||
| ### SUGGESTIONS (Nice-to-Have): | ||
| - Diagram updates for new components | ||
| - Minor dependency additions | ||
| - Updated version numbers | ||
| - Enhanced descriptions for existing components | ||
| - Formatting improvements | ||
| ### VALIDATED (No Action Needed): | ||
| - Internal implementation changes within existing patterns | ||
| - Bug fixes that don't change architecture | ||
| - Test coverage improvements | ||
| - Documentation fixes in other files | ||
| - Minor refactoring within same module | ||
| ## Important Guidelines | ||
| 1. **Understand the changes** - Read the actual PR diff thoroughly | ||
| 2. **Read the architecture doc** - Don't assume what's documented | ||
| 3. **Be practical** - Not every code change requires doc updates | ||
| 4. **Be specific** - Provide exact sections and suggested content | ||
| 5. **Be helpful** - Suggest actual text to add, not just "update section X" | ||
| 6. **Check current state** - Verify modules exist before claiming they're undocumented | ||
| ## What to Look For | ||
| ### New Modules | ||
| - Any new directory under `src/aignostics/` with `_service.py`, `_cli.py`, or `_gui.py` | ||
| - Check if documented in Section 1.5 "Layers and Modules" | ||
| ### Dependency Changes | ||
| - New entries in `pyproject.toml` dependencies or optional-dependencies | ||
| - Check if major dependencies are listed in Section 1.3 | ||
| ### CI/CD Changes | ||
| - New or modified workflows in `.github/workflows/` | ||
| - Check if Section 1.4 "Build Chain and CI/CD" is accurate | ||
| ### Integration Changes | ||
| - New external API integrations | ||
| - Check if documented in Section 3 "Integration Patterns" | ||
| ### Pattern Changes | ||
| - Changes to core patterns in `utils/` or base classes | ||
| - Check if Section 2 "Design Principles" needs updates | ||
| --- | ||
| **Focus**: Keep the architecture document as a living, accurate representation | ||
| of the codebase structure and design decisions. | ||
| secrets: | ||
| ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} | ||
| AIGNOSTICS_CLIENT_ID_DEVICE_STAGING: ${{ secrets.AIGNOSTICS_CLIENT_ID_DEVICE_STAGING }} | ||
| AIGNOSTICS_REFRESH_TOKEN_STAGING: ${{ secrets.AIGNOSTICS_REFRESH_TOKEN_STAGING }} | ||
| GCP_CREDENTIALS_STAGING: ${{ secrets.GCP_CREDENTIALS_STAGING }} | ||
| AIGNOSTICS_CLIENT_ID_DEVICE_PRODUCTION: ${{ secrets.AIGNOSTICS_CLIENT_ID_DEVICE_PRODUCTION }} | ||
| AIGNOSTICS_REFRESH_TOKEN_PRODUCTION: ${{ secrets.AIGNOSTICS_REFRESH_TOKEN_PRODUCTION }} | ||
| GCP_CREDENTIALS_PRODUCTION: ${{ secrets.GCP_CREDENTIALS_PRODUCTION }} | ||
