From 8a293356b30ea8fa4b477361b03853b9c3b9ca79 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Mon, 4 Aug 2025 20:06:27 +0000 Subject: [PATCH] feat: add knowledge aggregation for @claude GitHub Action - Create utils/aggregate-knowledge.sh to compile knowledge/ directory context - Add comprehensive documentation for manual workflow setup - Script generates ~1500 lines of foundational knowledge (principles, procedures, personalities) - Provides same context as local Claude Code --add-dir knowledge flag - Documentation includes required workflow changes due to GitHub App permissions Partial fix for #1183: Knowledge aggregation infrastructure ready Manual workflow update required to complete implementation Co-authored-by: Morgan Joyce --- ...laude-github-action-knowledge-injection.md | 109 +++++++++++++ utils/aggregate-knowledge.sh | 144 ++++++++++++++++++ 2 files changed, 253 insertions(+) create mode 100644 docs/claude-github-action-knowledge-injection.md create mode 100755 utils/aggregate-knowledge.sh diff --git a/docs/claude-github-action-knowledge-injection.md b/docs/claude-github-action-knowledge-injection.md new file mode 100644 index 00000000..18d44cd5 --- /dev/null +++ b/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<> $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 \ No newline at end of file diff --git a/utils/aggregate-knowledge.sh b/utils/aggregate-knowledge.sh new file mode 100755 index 00000000..03f155b6 --- /dev/null +++ b/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" \ No newline at end of file