Add knowledge base context injection to @claude GitHub Action

docs/claude-github-action-knowledge-injection.md

@@ -0,0 +1,109 @@
+# Claude GitHub Action Knowledge Injection Setup
+
+This document explains how to give the @claude GitHub Action access to the same knowledge base files that local Claude Code automatically loads.
+
+## Problem Solved
+
+- **Local `/close-issue` command**: Automatically loads ~30k tokens of context including the full `knowledge/` directory
+- **@claude GitHub Action**: Previously started with zero context, missing all foundational knowledge
+
+## Solution Implemented
+
+### 1. Knowledge Aggregation Script
+
+Created `utils/aggregate-knowledge.sh` that:
+- Aggregates all files from the `knowledge/` directory
+- Compiles principles, procedures, and personalities into a single context file
+- Generates ~1500 lines of foundational knowledge
+- Provides the same context as local `--add-dir knowledge` flag
+
+### 2. Required Workflow Changes
+
+The `.github/workflows/claude-implementation.yml` file needs to be updated to:
+
+1. **Switch Action**: Change from `anthropics/claude-code-action@beta` to `anthropics/claude-code-base-action@beta`
+2. **Add Knowledge Step**: Generate knowledge context using the aggregation script
+3. **Inject Context**: Pass the aggregated knowledge as a custom prompt
+
+#### Workflow Update Required:
+
+```yaml
+      - name: Generate knowledge context
+        id: knowledge
+        run: |
+          echo "Aggregating knowledge base context..."
+          ./utils/aggregate-knowledge.sh > knowledge-context.md
+          echo "Knowledge context generated ($(wc -l < knowledge-context.md) lines)"
+
+          # Create a multiline output for the GitHub Action
+          echo "KNOWLEDGE_CONTEXT<<EOF" >> $GITHUB_OUTPUT
+          cat knowledge-context.md >> $GITHUB_OUTPUT
+          echo "EOF" >> $GITHUB_OUTPUT
+
+      - uses: anthropics/claude-code-base-action@beta
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          allowed_tools: "Bash(*),LS,Read,Write,Edit,MultiEdit,Glob,Grep,Task,TodoWrite,WebFetch(domain:*),WebSearch,mcp__git,mcp__github"
+          prompt: |
+            You are Claude, an AI assistant designed to help with GitHub issues and pull requests.
+
+            # Knowledge Base Context
+
+            The following context provides the same foundational knowledge that local Claude Code 
+            receives automatically via the --add-dir knowledge flag. This includes development 
+            principles, procedures, git workflows, and coding conventions used in this repository.
+
+            Please read and internalize this context before responding to any requests:
+
+            ---
+
+            ${{ steps.knowledge.outputs.KNOWLEDGE_CONTEXT }}
+
+            ---
+
+            # Instructions
+
+            Use the above knowledge base context to inform all your responses and implementations.
+            Pay special attention to:
+
+            - **Principles**: tracer-bullets, versioning-mindset, OSE, subtraction-creates-value, etc.
+            - **Git Workflow**: Always follow established git procedures and branch management
+            - **Code Conventions**: Follow the established patterns and style guides
+            - **MCP Tools**: Use MCP tools for git and GitHub operations as specified
+            - **Procedures**: Follow documented procedures for issue-to-PR workflow
+
+            This context ensures you have the same understanding as local Claude Code sessions.
+```
+
+## Manual Steps Required
+
+Due to GitHub App permissions, the workflow file needs to be updated manually:
+
+1. Apply the workflow changes shown above to `.github/workflows/claude-implementation.yml`
+2. The changes switch to the base action and inject the full knowledge context
+3. This gives @claude the same ~30k tokens of context as local Claude Code
+
+## Benefits
+
+After implementation:
+- **Consistent Knowledge**: GitHub Action @claude will have same understanding as local setup
+- **Better PRs**: Claude will understand principles like tracer-bullets, versioning-mindset, OSE
+- **Proper Workflows**: Claude will follow established git procedures and conventions
+- **Quality Implementation**: Same foundational context leads to consistent quality
+
+## Testing
+
+The knowledge aggregation script can be tested locally:
+
+```bash
+./utils/aggregate-knowledge.sh | wc -l  # Should output ~1500 lines
+./utils/aggregate-knowledge.sh | head -20  # Preview the content
+```
+
+## Technical Notes
+
+- The aggregation script processes files in order: ai-index.md, throughput-definition.md, principles/, procedures/, personalities/, tools/
+- Output is structured markdown with clear section headers
+- Script includes safety checks for missing directories
+- Generated context matches the structure of local Claude Code's knowledge loading

utils/aggregate-knowledge.sh

@@ -0,0 +1,144 @@
+#!/bin/bash
+# Aggregate knowledge files for GitHub Action context injection
+# This script provides the same ~30k tokens of context that local Claude Code gets
+# via --add-dir knowledge flag
+#
+# Usage: ./aggregate-knowledge.sh > knowledge-context.md
+#
+# Principle: systems-stewardship - Single source of truth for knowledge aggregation
+# Principle: ai-provider-agnosticism - Works across different AI providers
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+DOTFILES_DIR="$(dirname "$SCRIPT_DIR")"
+KNOWLEDGE_DIR="$DOTFILES_DIR/knowledge"
+
+# Check if knowledge directory exists
+if [[ ! -d "$KNOWLEDGE_DIR" ]]; then
+    echo "Error: Knowledge directory not found at: $KNOWLEDGE_DIR" >&2
+    exit 1
+fi
+
+echo "# Knowledge Base Context"
+echo ""
+echo "This context is automatically generated from the knowledge/ directory to provide"
+echo "the same context that local Claude Code receives via the --add-dir flag."
+echo ""
+echo "Generated at: $(date '+%Y-%m-%d %H:%M:%S')"
+echo ""
+
+# Process the main AI index file first
+if [[ -f "$KNOWLEDGE_DIR/ai-index.md" ]]; then
+    echo "## AI Index"
+    echo ""
+    cat "$KNOWLEDGE_DIR/ai-index.md"
+    echo ""
+fi
+
+# Process throughput definition (the north star)
+if [[ -f "$KNOWLEDGE_DIR/throughput-definition.md" ]]; then
+    echo "## Throughput Definition"
+    echo ""
+    cat "$KNOWLEDGE_DIR/throughput-definition.md"
+    echo ""
+fi
+
+# Process all principle files
+echo "## Core Principles"
+echo ""
+if [[ -d "$KNOWLEDGE_DIR/principles" ]]; then
+    # Process README first
+    if [[ -f "$KNOWLEDGE_DIR/principles/README.md" ]]; then
+        echo "### Principles Overview"
+        echo ""
+        cat "$KNOWLEDGE_DIR/principles/README.md"
+        echo ""
+    fi
+
+    # Process individual principles (sorted for consistency)
+    for principle_file in "$KNOWLEDGE_DIR/principles"/*.md; do
+        if [[ -f "$principle_file" && "$(basename "$principle_file")" != "README.md" ]]; then
+            principle_name=$(basename "$principle_file" .md)
+            echo "### Principle: $principle_name"
+            echo ""
+            cat "$principle_file"
+            echo ""
+        fi
+    done
+fi
+
+# Process all procedure files
+echo "## Procedures"
+echo ""
+if [[ -d "$KNOWLEDGE_DIR/procedures" ]]; then
+    # Process README first
+    if [[ -f "$KNOWLEDGE_DIR/procedures/README.md" ]]; then
+        echo "### Procedures Overview"
+        echo ""
+        cat "$KNOWLEDGE_DIR/procedures/README.md"
+        echo ""
+    fi
+
+    # Process individual procedures (sorted for consistency)
+    for procedure_file in "$KNOWLEDGE_DIR/procedures"/*.md; do
+        if [[ -f "$procedure_file" && "$(basename "$procedure_file")" != "README.md" ]]; then
+            procedure_name=$(basename "$procedure_file" .md)
+            echo "### Procedure: $procedure_name"
+            echo ""
+            cat "$procedure_file"
+            echo ""
+        fi
+    done
+fi
+
+# Process personalities for consultation
+echo "## Personalities"
+echo ""
+if [[ -d "$KNOWLEDGE_DIR/personalities" ]]; then
+    # Process README first
+    if [[ -f "$KNOWLEDGE_DIR/personalities/README.md" ]]; then
+        echo "### Personalities Overview"
+        echo ""
+        cat "$KNOWLEDGE_DIR/personalities/README.md"
+        echo ""
+    fi
+
+    # Process individual personalities
+    for personality_file in "$KNOWLEDGE_DIR/personalities"/*.md; do
+        if [[ -f "$personality_file" && "$(basename "$personality_file")" != "README.md" ]]; then
+            personality_name=$(basename "$personality_file" .md)
+            echo "### Personality: $personality_name"
+            echo ""
+            cat "$personality_file"
+            echo ""
+        fi
+    done
+fi
+
+# Process tools directory if it exists
+if [[ -d "$KNOWLEDGE_DIR/tools" ]]; then
+    echo "## Tools"
+    echo ""
+    for tool_file in "$KNOWLEDGE_DIR/tools"/*.md; do
+        if [[ -f "$tool_file" ]]; then
+            tool_name=$(basename "$tool_file" .md)
+            echo "### Tool: $tool_name"
+            echo ""
+            cat "$tool_file"
+            echo ""
+        fi
+    done
+fi
+
+echo "---"
+echo ""
+echo "**End of Knowledge Base Context**"
+echo ""
+echo "This aggregated context provides the same foundational knowledge that local"
+echo "Claude Code receives automatically. Use this context to understand:"
+echo "- Development principles and patterns"
+echo "- Git workflow procedures"
+echo "- Code conventions and standards"
+echo "- MCP tool usage guidelines"
+echo "- Troubleshooting procedures"