fix: inject ~30k token knowledge base into @claude GitHub Actions (documentation as code)

[atxtechbro]

Summary

Fixes #1183 by injecting the COMPLETE knowledge base into @claude GitHub Actions, achieving true parity with local /close-issue commands. Implements "documentation as code" where the procedure IS the implementation.

The Problem

@claude GitHub Actions operated blind - no access to principles, procedures, personalities, tools, or the throughput definition that guide local development. This created inconsistent PR quality between local and GitHub-triggered implementations.

Changes Made

1. Comprehensive Knowledge Base Aggregation

• Added .github/scripts/aggregate-knowledge.sh - Recursively aggregates ALL files under knowledge/
• Now includes EVERYTHING Claude Code has access to locally:
  • Root files: README.md, ai-index.md, throughput-definition.md
  • principles/: All principle files (tracer-bullets, OSE, versioning-mindset, etc.)
  • procedures/: All procedure files (git-workflow, worktree-workflow, etc.)
  • personalities/: Brent, Jonah, Harrington-Emerson for retros
  • tools/: MCP dashboard documentation
  • Any future directories automatically included
• Increased from ~30k to ~72k characters of knowledge context

2. Documentation as Code Transformation

• Moved implementation to knowledge/procedures/close-issue-procedure.md - The procedure IS the implementation
• Contains the full template with {{ KNOWLEDGE_BASE }} placeholder that:
  • GitHub Actions: Replaces with aggregated content via string substitution
  • Local /close-issue: Stays as literal text (harmless since knowledge is preloaded)

3. Workflow Updates

• Updated .github/workflows/claude-implementation.yml:
  • Switched from claude-code-action@beta to claude-code-base-action@beta for prompt injection
  • Added knowledge aggregation step before Claude invocation
  • Reads template directly from procedures/close-issue-procedure.md
  • Added 30-minute timeout for complex implementations
• Updated .github/workflows/auto-trigger-claude.yml:
  • Added note in auto-comment about knowledge base availability

4. Simplifications

• Simplified .claude/command-templates/close-issue.md to 3 lines - just points to the procedure
• Preserved .github/workflow-prompts/issue-triage.md - Low-value utility script kept separate to preserve tokens

Architecture Decision

Two-tier system based on value:

• knowledge/ - ALL high-value content worth the token cost (now ~72k characters)
• .github/workflow-prompts/ - Low-value utility scripts that just work (issue-triage.md only)

Principles Applied

• systems-stewardship: Single source of truth, exact parity with local behavior
• subtraction-creates-value: Removed duplication, kept only what's needed
• snowball-method: Complete knowledge persistence across all contexts
• versioning-mindset: Iterative refinement to comprehensive solution

Testing Checklist

• Local /close-issue command works (template injection preserved)
• GitHub Actions gets COMPLETE knowledge base (~72k characters verified)
• Error handling for empty knowledge directories
• Auto-labeling workflow remains functional
• Both local and GitHub share EXACT same implementation
• All knowledge subdirectories included (personalities, tools, etc.)

Impact

@claude now operates with COMPLETE architectural context in GitHub Actions - identical to local Claude Code. No subtle differences, no missing context. Full parity achieved.

[amazon-q-developer]

⏳ I'm reviewing this pull request for security vulnerabilities and code quality issues. I'll provide an update when I'm done

[amazon-q-developer]

Warning

Description: Untrusted input has been detected in GitHub Actions workflow run commands. This creates a significant security risk for script injection attacks, where malicious actors could exploit workflow inputs to execute unauthorized commands. GitHub Actions workflows should validate and sanitize all user-provided inputs, especially those used in run commands. Consider using GitHub's built-in security features like actions/github-script for safer command execution, or implement proper input validation before using dynamic values in run commands.

Learn more

Similar issue at line numbers 93, 94, 95, 96, 97, 98, 99, 100, 101, and 128.

Severity: High

[amazon-q-developer]

The remediation replaces the vulnerable run commands with uses: actions/github-script@v7 steps. This change eliminates the risk of script injection by executing JavaScript code within a controlled environment provided by the GitHub Actions script action.

Suggested change

	run: |
	- name: Aggregate knowledge base
	id: knowledge
	uses: actions/github-script@v7
	with:
	github-token: ${{ secrets.GITHUB_TOKEN }}
	script: |
	const fs = require('fs');
	const path = require('path');
	function aggregateKnowledge() {
	console.log("Aggregating knowledge base for Claude...");
	const knowledgeBasePath = path.join('.github', 'scripts', 'aggregate-knowledge.sh');
	if (fs.existsSync(knowledgeBasePath)) {
	const knowledge = fs.readFileSync(knowledgeBasePath, 'utf8');
	console.log(`Knowledge base size: ${knowledge.length} characters`);
	return knowledge;
	} else {
	console.log("Knowledge base script not found.");
	return "";
	}
	}
	const knowledge = aggregateKnowledge();
	core.setOutput('content', knowledge);
	- name: Prepare implementation prompt
	id: prepare-prompt
	uses: actions/github-script@v7
	with:
	github-token: ${{ secrets.GITHUB_TOKEN }}
	script: |
	const fs = require('fs');
	const path = require('path');
	function preparePrompt() {
	const isIssue = !!context.payload.issue && !context.payload.issue.pull_request;
	let prompt = '';
	if (isIssue) {
	console.log("Preparing prompt for issue implementation...");
	const issueNumber = context.payload.issue.number;
	const issueTitle = context.payload.issue.title;
	const issueBody = context.payload.issue.body;
	const templatePath = path.join('.github', 'workflow-prompts', 'issue-implementation.md');
	if (fs.existsSync(templatePath)) {
	let template = fs.readFileSync(templatePath, 'utf8');
	prompt = template
	.replace('{{ KNOWLEDGE_BASE }}', '${{ steps.knowledge.outputs.content }}')
	.replace('{{ ISSUE_NUMBER }}', issueNumber)
	.replace('{{ ISSUE_TITLE }}', issueTitle)
	.replace('{{ ISSUE_BODY }}', issueBody)
	.replace('{{ REPO }}', context.repo.owner + '/' + context.repo.repo);
	} else {
	console.log("Issue implementation template not found.");
	prompt = "Error: Template not found.";
	}
	} else {
	console.log("Preparing prompt for PR review...");
	prompt = `${{ steps.knowledge.outputs.content }}
	## PR Review Request
	The user has requested: ${context.payload.comment.body}
	Please review and respond to this pull request comment with the full context of the codebase principles and procedures available above.`;
	}
	return prompt;
	}
	const prompt = preparePrompt();
	core.setOutput('prompt', prompt);
	- uses: anthropics/claude-code-base-action@beta
	with:

[amazon-q-developer]

✅ I finished the code review, and left comments with the issues I found. I will now generate code fix suggestions.

[atxtechbro]

Update: Restored issue-triage.md

Just pushed a fix - I accidentally deleted .github/workflow-prompts/issue-triage.md in the refactor, but it's actively used by the auto-label-issues.yml workflow.

What I did:

• Restored issue-triage.md from git history
• Added explanatory comment clarifying why it stays in workflow-prompts/ (it's a specialized AI prompt, not a human-executable procedure)
• The directory now contains just this one file that's actively needed

This maintains the clean separation:

• knowledge/procedures/ → Human-executable procedures (including close-issue-procedure.md)
• .github/workflow-prompts/ → Specialized AI prompts for GitHub Actions (just issue-triage.md)

The PR is ready for review with both the knowledge base injection feature and the auto-labeling workflow intact.