From 0594da75070174eb5ff86273501ef1581d2fda26 Mon Sep 17 00:00:00 2001 From: Morgan Joyce Date: Mon, 4 Aug 2025 15:07:21 -0500 Subject: [PATCH 01/14] fix(github-actions): inject knowledge base into @claude workflow Switch from claude-code-action to claude-code-base-action to enable custom prompt injection. This gives the @claude GitHub Action access to the full knowledge base (principles, procedures, CLAUDE.md) that the local /close-issue command has. Changes: - Create knowledge aggregation script to collect all knowledge files - Add workflow prompt template with knowledge injection placeholders - Update claude-implementation.yml to use claude-code-base-action - Inject ~30k tokens of context before Claude processes issues - Update auto-trigger message to mention knowledge availability The @claude workflow now has the same rich context as local development, resulting in higher quality PRs that follow established patterns. Closes #1183 Principle: snowball-method Principle: systems-stewardship --- .github/scripts/aggregate-knowledge.sh | 87 +++++++++++++++++++ .../workflow-prompts/issue-implementation.md | 75 ++++++++++++++++ .github/workflows/auto-trigger-claude.yml | 2 +- .github/workflows/claude-implementation.yml | 68 ++++++++++++++- 4 files changed, 227 insertions(+), 5 deletions(-) create mode 100755 .github/scripts/aggregate-knowledge.sh create mode 100644 .github/workflow-prompts/issue-implementation.md diff --git a/.github/scripts/aggregate-knowledge.sh b/.github/scripts/aggregate-knowledge.sh new file mode 100755 index 00000000..3db80f5e --- /dev/null +++ b/.github/scripts/aggregate-knowledge.sh @@ -0,0 +1,87 @@ +#!/bin/bash +# Aggregate knowledge base for GitHub Actions +# This script reads all knowledge files and outputs them as a single text block +# for injection into Claude's prompt in GitHub Actions workflows +# Principle: systems-stewardship + +set -euo pipefail + +# Get the repository root (two levels up from .github/scripts) +REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)" +KNOWLEDGE_DIR="$REPO_ROOT/knowledge" + +# Function to output a section with clear markers +output_section() { + local title="$1" + local content="$2" + + echo "## $title" + echo "" + echo "$content" + echo "" +} + +# Start with a header +echo "# Knowledge Base Context" +echo "" +echo "This context is automatically injected to provide Claude with understanding of:" +echo "- Core development principles" +echo "- Established procedures and workflows" +echo "- Git conventions and standards" +echo "- System architecture patterns" +echo "" + +# Read CLAUDE.md if it exists +if [[ -f "$REPO_ROOT/CLAUDE.md" ]]; then + output_section "CLAUDE.md Instructions" "$(cat "$REPO_ROOT/CLAUDE.md")" +fi + +# Read all principle files +if [[ -d "$KNOWLEDGE_DIR/principles" ]]; then + echo "# Core Principles" + echo "" + + for file in "$KNOWLEDGE_DIR/principles"/*.md; do + if [[ -f "$file" ]]; then + filename=$(basename "$file" .md) + # Convert filename to title case (e.g., tracer-bullets -> Tracer Bullets) + title=$(echo "$filename" | sed 's/-/ /g' | sed 's/\b\(.\)/\u\1/g') + + echo "## $title" + echo "" + cat "$file" + echo "" + echo "---" + echo "" + fi + done +fi + +# Read all procedure files +if [[ -d "$KNOWLEDGE_DIR/procedures" ]]; then + echo "# Established Procedures" + echo "" + + for file in "$KNOWLEDGE_DIR/procedures"/*.md; do + if [[ -f "$file" ]]; then + filename=$(basename "$file" .md) + # Convert filename to title case + title=$(echo "$filename" | sed 's/-/ /g' | sed 's/\b\(.\)/\u\1/g') + + echo "## $title" + echo "" + cat "$file" + echo "" + echo "---" + echo "" + fi + done +fi + +# Add a footer note +echo "" +echo "# Context Note" +echo "" +echo "This knowledge base was automatically aggregated for this GitHub Action workflow." +echo "Follow these principles and procedures to maintain consistency with the codebase patterns." +echo "Reference: Principles are in knowledge/principles/, Procedures are in knowledge/procedures/" \ No newline at end of file diff --git a/.github/workflow-prompts/issue-implementation.md b/.github/workflow-prompts/issue-implementation.md new file mode 100644 index 00000000..bf106e33 --- /dev/null +++ b/.github/workflow-prompts/issue-implementation.md @@ -0,0 +1,75 @@ +# Implement GitHub Issue #{{ ISSUE_NUMBER }} + +You are implementing a GitHub issue with full access to the codebase knowledge, principles, and procedures. + +## Your Knowledge Base + +{{ KNOWLEDGE_BASE }} + +## Issue Details + +**Issue Number**: #{{ ISSUE_NUMBER }} +**Title**: {{ ISSUE_TITLE }} +**Repository**: {{ REPO }} + +### Issue Description + +{{ ISSUE_BODY }} + +## Implementation Instructions + +### 1. Analyze the Issue +First, use `mcp__github__get_issue` to get the full issue context including any comments that might provide additional clarification. + +### 2. Determine Approach +Based on the issue analysis, determine if this is: +- A bug fix requiring immediate implementation +- A feature request needing careful design +- A spike requiring research and documentation +- An invalid/duplicate issue to close + +### 3. Follow Established Patterns +**IMPORTANT**: You have been provided with the full knowledge base above. Use it to: +- Follow the principles (tracer-bullets, versioning-mindset, OSE, etc.) +- Apply the appropriate procedures (git-workflow, worktree-workflow, etc.) +- Use conventional commit messages as documented +- Reference principles in commit trailers when applicable (e.g., `Principle: systems-stewardship`) + +### 4. Implementation +- Create clean, focused changes that follow existing patterns +- Write code that follows the conventions you see in the codebase +- Use TodoWrite to track your progress through complex implementations +- Test your changes when possible + +### 5. PR Creation +The GitHub Action will automatically create a PR after you push your changes. Ensure your commits: +- Have clear, conventional commit messages +- Reference the issue with "Closes #{{ ISSUE_NUMBER }}" +- Follow the git workflow standards from the knowledge base + +## Key Principles to Apply + +1. **Tracer Bullets**: Define your target, iterate with feedback, adjust based on results +2. **Versioning Mindset**: Iterate on existing code rather than rewriting +3. **Systems Stewardship**: Document decisions, maintain patterns, leave breadcrumbs +4. **Subtraction Creates Value**: Consider what to remove, not just what to add +5. **OSE**: Maintain elevated perspective, think systemically + +## Available Tools + +You have access to these tools: +- File operations: Read, Write, Edit, MultiEdit, LS, Glob, Grep +- Git operations: mcp__git (full git functionality) +- GitHub operations: mcp__github (API access) +- Task management: Task, TodoWrite +- Web tools: WebFetch, WebSearch +- Shell: Bash + +## Important Reminders + +- The knowledge base above is your guide - use it actively +- This is not a blind implementation - you have full context +- Create PRs that match the quality of local development +- Follow the established patterns, don't reinvent them + +Now proceed with implementing issue #{{ ISSUE_NUMBER }}. \ No newline at end of file diff --git a/.github/workflows/auto-trigger-claude.yml b/.github/workflows/auto-trigger-claude.yml index 3c544a85..86fc7882 100644 --- a/.github/workflows/auto-trigger-claude.yml +++ b/.github/workflows/auto-trigger-claude.yml @@ -21,5 +21,5 @@ jobs: owner: context.repo.owner, repo: context.repo.repo, issue_number: context.issue.number, - body: '@claude Please implement this issue and CREATE AN ACTUAL PULL REQUEST on GitHub.\n\n**IMPORTANT**: You MUST create a real PR on GitHub (not just provide a link to create one). The PR must be created and visible at github.com/atxtechbro/dotfiles/pulls.\n\nUse the PR template from https://github.com/atxtechbro/dotfiles/blob/main/.github/PULL_REQUEST_TEMPLATE.md when creating the pull request.' + body: '@claude Please implement this issue and CREATE AN ACTUAL PULL REQUEST on GitHub.\n\n**IMPORTANT**: You MUST create a real PR on GitHub (not just provide a link to create one). The PR must be created and visible at github.com/atxtechbro/dotfiles/pulls.\n\n**NOTE**: You now have access to the full knowledge base including all principles (tracer-bullets, versioning-mindset, OSE, etc.) and procedures (git-workflow, worktree-workflow, etc.). Use this context to create high-quality PRs that follow established patterns.\n\nUse the PR template from https://github.com/atxtechbro/dotfiles/blob/main/.github/PULL_REQUEST_TEMPLATE.md when creating the pull request.' }); \ No newline at end of file diff --git a/.github/workflows/claude-implementation.yml b/.github/workflows/claude-implementation.yml index 523d4fed..bef46002 100644 --- a/.github/workflows/claude-implementation.yml +++ b/.github/workflows/claude-implementation.yml @@ -2,16 +2,20 @@ # THE SINGLE SOURCE OF TRUTH for @claude mentions in issues and PRs # # This is the ONLY workflow that responds to @claude mentions. -# Uses the official anthropics/claude-code-action@beta to: -# - Implement issues when @claude is mentioned +# Uses the official anthropics/claude-code-base-action@beta to: +# - Implement issues when @claude is mentioned WITH FULL KNOWLEDGE BASE CONTEXT # - Review PRs when @claude is mentioned # - Create branches and push changes with proper permissions # # Note: Both claude[bot] and github-actions[bot] comments come from this workflow. # The bot identity depends on the context and step being executed. # +# KNOWLEDGE INJECTION: This workflow now aggregates and injects the full knowledge base +# into Claude's context, providing the same rich context as local /close-issue commands. +# # Principle: subtraction-creates-value (removed duplicate workflow) # Principle: systems-stewardship (single clear workflow to maintain) +# Principle: snowball-method (knowledge persistence and compound improvement) name: Claude Implementation on: @@ -69,8 +73,64 @@ jobs: with: token: ${{ secrets.GITHUB_TOKEN }} - - uses: anthropics/claude-code-action@beta + - name: Aggregate knowledge base + id: knowledge + run: | + echo "Aggregating knowledge base for Claude..." + KNOWLEDGE=$(.github/scripts/aggregate-knowledge.sh) + + # Use EOF delimiter to handle multi-line content + echo "content<> $GITHUB_OUTPUT + echo "$KNOWLEDGE" >> $GITHUB_OUTPUT + echo "EOF" >> $GITHUB_OUTPUT + + # Log size for debugging + echo "Knowledge base size: $(echo "$KNOWLEDGE" | wc -c) characters" + + - name: Prepare implementation prompt + id: prepare-prompt + run: | + # Determine if this is an issue or PR + IS_ISSUE="${{ github.event.issue && !github.event.issue.pull_request }}" + + if [ "$IS_ISSUE" == "true" ]; then + echo "Preparing prompt for issue implementation..." + + # Get issue details + ISSUE_NUMBER="${{ github.event.issue.number }}" + ISSUE_TITLE="${{ github.event.issue.title }}" + ISSUE_BODY="${{ github.event.issue.body }}" + + # Load the template + TEMPLATE=$(cat .github/workflow-prompts/issue-implementation.md) + + # Replace placeholders + PROMPT="${TEMPLATE//\{\{ KNOWLEDGE_BASE \}\}/${{ steps.knowledge.outputs.content }}}" + PROMPT="${PROMPT//\{\{ ISSUE_NUMBER \}\}/$ISSUE_NUMBER}" + PROMPT="${PROMPT//\{\{ ISSUE_TITLE \}\}/$ISSUE_TITLE}" + PROMPT="${PROMPT//\{\{ ISSUE_BODY \}\}/$ISSUE_BODY}" + PROMPT="${PROMPT//\{\{ REPO \}\}/${{ github.repository }}}" + else + echo "Preparing prompt for PR review..." + # For PR reviews, use the comment directly with knowledge context + PROMPT="${{ steps.knowledge.outputs.content }} + + ## PR Review Request + + The user has requested: ${{ github.event.comment.body }} + + Please review and respond to this pull request comment with the full context of the codebase principles and procedures available above." + fi + + # Output the prompt + echo "prompt<> $GITHUB_OUTPUT + echo "$PROMPT" >> $GITHUB_OUTPUT + echo "EOF" >> $GITHUB_OUTPUT + + - uses: anthropics/claude-code-base-action@beta with: + prompt: ${{ steps.prepare-prompt.outputs.prompt }} 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" \ No newline at end of file + allowed_tools: "Bash(*),LS,Read,Write,Edit,MultiEdit,Glob,Grep,Task,TodoWrite,WebFetch(domain:*),WebSearch,mcp__git,mcp__github" + timeout_minutes: "30" \ No newline at end of file From 11fe37e38018ebc56f8822767af6acd29a921a4d Mon Sep 17 00:00:00 2001 From: Morgan Joyce Date: Mon, 4 Aug 2025 15:15:26 -0500 Subject: [PATCH 02/14] refactor: create universal issue implementation template Following versioning mindset, maximize reuse of existing content by: - Making issue-implementation.md work for both workflows - Update close-issue.md to INJECT the shared template - Fix knowledge aggregation (remove CLAUDE.md - not in repo) The same template now serves both: - /close-issue command: KNOWLEDGE_BASE placeholder stays empty (preloaded) - GitHub Actions: KNOWLEDGE_BASE gets filled with aggregated knowledge This creates a single source of truth for issue implementation instructions, reducing duplication and ensuring consistency. Principle: versioning-mindset Principle: subtraction-creates-value --- .claude/command-templates/close-issue.md | 13 ++++--------- .github/scripts/aggregate-knowledge.sh | 7 +++---- .github/workflow-prompts/issue-implementation.md | 8 +++----- 3 files changed, 10 insertions(+), 18 deletions(-) diff --git a/.claude/command-templates/close-issue.md b/.claude/command-templates/close-issue.md index 8b655083..e0d5a9a3 100644 --- a/.claude/command-templates/close-issue.md +++ b/.claude/command-templates/close-issue.md @@ -4,17 +4,12 @@ Complete and implement GitHub issue #{{ ISSUE_NUMBER }}. ## Core Principle: Target-First Development {{ INJECT:principles/tracer-bullets.md }} -## Analyze Issue #{{ ISSUE_NUMBER }} -First, use `mcp__github__get_issue` to understand the issue and determine the appropriate workflow path. +## Implementation Instructions -{{ INJECT:procedures/close-issue-procedure.md }} +{{ INJECT:../../.github/workflow-prompts/issue-implementation.md }} -## Apply to Issue #{{ ISSUE_NUMBER }} -When following the procedure: -- Use issue #{{ ISSUE_NUMBER }} for all GitHub API calls -- Replace with {{ ISSUE_NUMBER }} in branch names -- Replace with issue title slug -- Reference "Closes #{{ ISSUE_NUMBER }}" in PR body +## Additional Context: Close Issue Procedure +{{ INJECT:procedures/close-issue-procedure.md }} ## Final Step: Retro Let's retro this context and wring out the gleanings. diff --git a/.github/scripts/aggregate-knowledge.sh b/.github/scripts/aggregate-knowledge.sh index 3db80f5e..a4c74af8 100755 --- a/.github/scripts/aggregate-knowledge.sh +++ b/.github/scripts/aggregate-knowledge.sh @@ -31,10 +31,9 @@ echo "- Git conventions and standards" echo "- System architecture patterns" echo "" -# Read CLAUDE.md if it exists -if [[ -f "$REPO_ROOT/CLAUDE.md" ]]; then - output_section "CLAUDE.md Instructions" "$(cat "$REPO_ROOT/CLAUDE.md")" -fi +# Note: CLAUDE.md is not included here as it's a user-specific file +# that lives in ~/.claude/CLAUDE.md (not in the repository). +# GitHub Actions only has access to committed repository files. # Read all principle files if [[ -d "$KNOWLEDGE_DIR/principles" ]]; then diff --git a/.github/workflow-prompts/issue-implementation.md b/.github/workflow-prompts/issue-implementation.md index bf106e33..09ab408a 100644 --- a/.github/workflow-prompts/issue-implementation.md +++ b/.github/workflow-prompts/issue-implementation.md @@ -2,8 +2,6 @@ You are implementing a GitHub issue with full access to the codebase knowledge, principles, and procedures. -## Your Knowledge Base - {{ KNOWLEDGE_BASE }} ## Issue Details @@ -29,7 +27,7 @@ Based on the issue analysis, determine if this is: - An invalid/duplicate issue to close ### 3. Follow Established Patterns -**IMPORTANT**: You have been provided with the full knowledge base above. Use it to: +**IMPORTANT**: You have access to the full knowledge base (either injected above or preloaded in your context). Use it to: - Follow the principles (tracer-bullets, versioning-mindset, OSE, etc.) - Apply the appropriate procedures (git-workflow, worktree-workflow, etc.) - Use conventional commit messages as documented @@ -42,7 +40,7 @@ Based on the issue analysis, determine if this is: - Test your changes when possible ### 5. PR Creation -The GitHub Action will automatically create a PR after you push your changes. Ensure your commits: +Ensure your commits: - Have clear, conventional commit messages - Reference the issue with "Closes #{{ ISSUE_NUMBER }}" - Follow the git workflow standards from the knowledge base @@ -67,7 +65,7 @@ You have access to these tools: ## Important Reminders -- The knowledge base above is your guide - use it actively +- The knowledge base is your guide - use it actively - This is not a blind implementation - you have full context - Create PRs that match the quality of local development - Follow the established patterns, don't reinvent them From 42ebf45fd3b35752fce4816ae8f2dc212cba33e9 Mon Sep 17 00:00:00 2001 From: Morgan Joyce Date: Mon, 4 Aug 2025 15:20:20 -0500 Subject: [PATCH 03/14] fix: use GitHub raw URL for universal template injection Replace relative path with full GitHub raw URL for clarity and transparency. This makes it explicit where the content comes from and ensures it always pulls from the main branch. Benefits: - No path ambiguity - Self-documenting - Follows MCP tool file path transparency principle Principle: transparency-in-agent-work --- .claude/command-templates/close-issue.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.claude/command-templates/close-issue.md b/.claude/command-templates/close-issue.md index e0d5a9a3..5f89b997 100644 --- a/.claude/command-templates/close-issue.md +++ b/.claude/command-templates/close-issue.md @@ -6,7 +6,7 @@ Complete and implement GitHub issue #{{ ISSUE_NUMBER }}. ## Implementation Instructions -{{ INJECT:../../.github/workflow-prompts/issue-implementation.md }} +{{ INJECT:https://raw.githubusercontent.com/atxtechbro/dotfiles/main/.github/workflow-prompts/issue-implementation.md }} ## Additional Context: Close Issue Procedure {{ INJECT:procedures/close-issue-procedure.md }} From 272ee074996560968ccc6e076e9aa6e1e2084e86 Mon Sep 17 00:00:00 2001 From: Morgan Joyce Date: Mon, 4 Aug 2025 15:25:25 -0500 Subject: [PATCH 04/14] docs: clarify mixed approach for template injection Add clear documentation explaining the design decision: - GitHub raw URL for universal template (consistency) - Local paths for principles/procedures (development flexibility) - Single source of truth for issue implementation This mixed approach provides: - Consistent implementation instructions across both workflows - Ability to test local changes to principles/procedures - Best of both worlds for development and production Principle: transparency-in-agent-work Principle: systems-stewardship --- .claude/command-templates/close-issue.md | 3 +++ .github/workflow-prompts/issue-implementation.md | 13 +++++++++++++ 2 files changed, 16 insertions(+) diff --git a/.claude/command-templates/close-issue.md b/.claude/command-templates/close-issue.md index 5f89b997..074304e3 100644 --- a/.claude/command-templates/close-issue.md +++ b/.claude/command-templates/close-issue.md @@ -6,6 +6,9 @@ Complete and implement GitHub issue #{{ ISSUE_NUMBER }}. ## Implementation Instructions +# Using GitHub raw URL for the universal template ensures consistency between +# local /close-issue and GitHub Actions @claude workflows. Both use the exact +# same implementation instructions from main branch. {{ INJECT:https://raw.githubusercontent.com/atxtechbro/dotfiles/main/.github/workflow-prompts/issue-implementation.md }} ## Additional Context: Close Issue Procedure diff --git a/.github/workflow-prompts/issue-implementation.md b/.github/workflow-prompts/issue-implementation.md index 09ab408a..a81116c9 100644 --- a/.github/workflow-prompts/issue-implementation.md +++ b/.github/workflow-prompts/issue-implementation.md @@ -1,3 +1,16 @@ +# Universal Issue Implementation Template +# +# This is the SINGLE SOURCE OF TRUTH for issue implementation instructions. +# Used by both: +# - Local /close-issue command (via GitHub raw URL injection) +# - GitHub Actions @claude workflow (with knowledge base injection) +# +# The {{ KNOWLEDGE_BASE }} placeholder below: +# - Remains empty for /close-issue (knowledge is preloaded) +# - Gets filled with aggregated knowledge for GitHub Actions +# +# Principle: systems-stewardship (single source of truth) + # Implement GitHub Issue #{{ ISSUE_NUMBER }} You are implementing a GitHub issue with full access to the codebase knowledge, principles, and procedures. From 77b752a69e25e5d17573013414a275d0e32b5fc8 Mon Sep 17 00:00:00 2001 From: Morgan Joyce Date: Mon, 4 Aug 2025 15:28:19 -0500 Subject: [PATCH 05/14] fix: revert to relative path for universal template Use relative path instead of GitHub raw URL to preserve local development workflow. This allows testing changes to the template before merging to main. Both workflows still share the same template: - /close-issue uses relative path for local flexibility - @claude gets it via repository checkout Principle: developer-experience --- .claude/command-templates/close-issue.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/.claude/command-templates/close-issue.md b/.claude/command-templates/close-issue.md index 074304e3..c8326614 100644 --- a/.claude/command-templates/close-issue.md +++ b/.claude/command-templates/close-issue.md @@ -6,10 +6,9 @@ Complete and implement GitHub issue #{{ ISSUE_NUMBER }}. ## Implementation Instructions -# Using GitHub raw URL for the universal template ensures consistency between -# local /close-issue and GitHub Actions @claude workflows. Both use the exact -# same implementation instructions from main branch. -{{ INJECT:https://raw.githubusercontent.com/atxtechbro/dotfiles/main/.github/workflow-prompts/issue-implementation.md }} +# Both /close-issue and @claude workflows share this universal template. +# Using relative path allows testing local changes before merging to main. +{{ INJECT:../../.github/workflow-prompts/issue-implementation.md }} ## Additional Context: Close Issue Procedure {{ INJECT:procedures/close-issue-procedure.md }} From 92a0d3a87f82b097252f48a3262187ac9c8e7ba7 Mon Sep 17 00:00:00 2001 From: Morgan Joyce Date: Mon, 4 Aug 2025 15:47:44 -0500 Subject: [PATCH 06/14] docs(workflow-prompts): clarify {{ KNOWLEDGE_BASE }} placeholder behavior Clarified that the placeholder remains as literal text in local /close-issue commands (not replaced with empty string) while GitHub Actions does actual string substitution. This prevents confusion about how the template works. The placeholder is harmless when shown literally since local Claude sessions already have the knowledge preloaded. Added inline comment to explain this to users who might see the literal placeholder text. Principle: transparency-in-agent-work --- .github/workflow-prompts/issue-implementation.md | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/.github/workflow-prompts/issue-implementation.md b/.github/workflow-prompts/issue-implementation.md index a81116c9..05d4de00 100644 --- a/.github/workflow-prompts/issue-implementation.md +++ b/.github/workflow-prompts/issue-implementation.md @@ -2,12 +2,17 @@ # # This is the SINGLE SOURCE OF TRUTH for issue implementation instructions. # Used by both: -# - Local /close-issue command (via GitHub raw URL injection) +# - Local /close-issue command (via relative path injection) # - GitHub Actions @claude workflow (with knowledge base injection) # -# The {{ KNOWLEDGE_BASE }} placeholder below: -# - Remains empty for /close-issue (knowledge is preloaded) -# - Gets filled with aggregated knowledge for GitHub Actions +# IMPORTANT: How {{ KNOWLEDGE_BASE }} works: +# - For GitHub Actions: Gets replaced with aggregated knowledge files via string substitution +# - For local /close-issue: Remains as literal text "{{ KNOWLEDGE_BASE }}" in the prompt +# (harmless since knowledge is already preloaded in Claude's context) +# +# This is NOT smart placeholder logic - it's simple: +# - GitHub Actions: Does string replacement: {{ KNOWLEDGE_BASE }} → actual content +# - Local command: Does NO replacement: {{ KNOWLEDGE_BASE }} → stays as literal text # # Principle: systems-stewardship (single source of truth) @@ -16,6 +21,7 @@ You are implementing a GitHub issue with full access to the codebase knowledge, principles, and procedures. {{ KNOWLEDGE_BASE }} + ## Issue Details From 43a9f5c7bde09e5410c081c3829dc79adef5e2c8 Mon Sep 17 00:00:00 2001 From: Morgan Joyce Date: Mon, 4 Aug 2025 15:50:49 -0500 Subject: [PATCH 07/14] refactor(templates): consolidate all implementation logic into universal template Moved all special content from /close-issue command into the universal template: - Tracer bullets principle injection - Close issue procedure injection - Post-implementation retro section with eager evolution - Ghost procedures reminder The /close-issue command is now just a minimal 3-line wrapper that injects the universal template. This makes the system DRYer and ensures both workflows (@claude and /close-issue) get identical instructions including retro prompts. Principle: subtraction-creates-value Principle: systems-stewardship --- .claude/command-templates/close-issue.md | 23 +------------------ .../workflow-prompts/issue-implementation.md | 19 ++++++++++++++- 2 files changed, 19 insertions(+), 23 deletions(-) diff --git a/.claude/command-templates/close-issue.md b/.claude/command-templates/close-issue.md index c8326614..e8a47f77 100644 --- a/.claude/command-templates/close-issue.md +++ b/.claude/command-templates/close-issue.md @@ -1,25 +1,4 @@ # Close Issue Command Template Complete and implement GitHub issue #{{ ISSUE_NUMBER }}. -## Core Principle: Target-First Development -{{ INJECT:principles/tracer-bullets.md }} - -## Implementation Instructions - -# Both /close-issue and @claude workflows share this universal template. -# Using relative path allows testing local changes before merging to main. -{{ INJECT:../../.github/workflow-prompts/issue-implementation.md }} - -## Additional Context: Close Issue Procedure -{{ INJECT:procedures/close-issue-procedure.md }} - -## Final Step: Retro -Let's retro this context and wring out the gleanings. - -{{ INJECT:principles/eager-evolution.md }} - -**Consider capturing any ghost procedures** that emerged during this work - see [Procedure Creation](knowledge/procedures/procedure-creation.md). - -**What would you like to focus on?** -- Do you have a specific aspect you want to double-click on? -- Or would you like me to suggest the top 3 areas I predict you'll find most valuable to explore? \ No newline at end of file +{{ INJECT:../../.github/workflow-prompts/issue-implementation.md }} \ No newline at end of file diff --git a/.github/workflow-prompts/issue-implementation.md b/.github/workflow-prompts/issue-implementation.md index 05d4de00..b74dbd25 100644 --- a/.github/workflow-prompts/issue-implementation.md +++ b/.github/workflow-prompts/issue-implementation.md @@ -89,4 +89,21 @@ You have access to these tools: - Create PRs that match the quality of local development - Follow the established patterns, don't reinvent them -Now proceed with implementing issue #{{ ISSUE_NUMBER }}. \ No newline at end of file +## Core Principle: Target-First Development +{{ INJECT:principles/tracer-bullets.md }} + +## Close Issue Procedure +{{ INJECT:procedures/close-issue-procedure.md }} + +Now proceed with implementing issue #{{ ISSUE_NUMBER }}. + +## Post-Implementation Retro +After completing the implementation and creating the PR, let's retro this context and wring out the gleanings. + +{{ INJECT:principles/eager-evolution.md }} + +**Consider capturing any ghost procedures** that emerged during this work - see [Procedure Creation](knowledge/procedures/procedure-creation.md). + +**What would you like to focus on?** +- Do you have a specific aspect you want to double-click on? +- Or would you like me to suggest the top 3 areas I predict you'll find most valuable to explore? \ No newline at end of file From 5e48ab91a4800b9bcefe3f4f473c63c512114e04 Mon Sep 17 00:00:00 2001 From: Morgan Joyce Date: Mon, 4 Aug 2025 15:55:11 -0500 Subject: [PATCH 08/14] refactor(templates): simplify universal template to match original style Removed verbose instructional content and made the template look like the original close-issue.md - just essential prompts and injections: - Removed numbered implementation instructions - Removed "Key Principles to Apply" section (redundant with injections) - Removed "Available Tools" section (Claude already knows) - Removed "Important Reminders" section (too preachy) - Removed verbose issue details section The template now focuses on what matters: injecting principles/procedures and providing issue context, without prescriptive instructions. Principle: subtraction-creates-value Principle: versioning-mindset --- .../workflow-prompts/issue-implementation.md | 91 +++---------------- 1 file changed, 15 insertions(+), 76 deletions(-) diff --git a/.github/workflow-prompts/issue-implementation.md b/.github/workflow-prompts/issue-implementation.md index b74dbd25..036f471f 100644 --- a/.github/workflow-prompts/issue-implementation.md +++ b/.github/workflow-prompts/issue-implementation.md @@ -1,6 +1,6 @@ -# Universal Issue Implementation Template +# Issue Implementation Template # -# This is the SINGLE SOURCE OF TRUTH for issue implementation instructions. +# This is the SINGLE SOURCE OF TRUTH for issue implementation. # Used by both: # - Local /close-issue command (via relative path injection) # - GitHub Actions @claude workflow (with knowledge base injection) @@ -16,89 +16,28 @@ # # Principle: systems-stewardship (single source of truth) -# Implement GitHub Issue #{{ ISSUE_NUMBER }} - -You are implementing a GitHub issue with full access to the codebase knowledge, principles, and procedures. +Complete and implement GitHub issue #{{ ISSUE_NUMBER }}. {{ KNOWLEDGE_BASE }} - - -## Issue Details - -**Issue Number**: #{{ ISSUE_NUMBER }} -**Title**: {{ ISSUE_TITLE }} -**Repository**: {{ REPO }} - -### Issue Description - -{{ ISSUE_BODY }} - -## Implementation Instructions - -### 1. Analyze the Issue -First, use `mcp__github__get_issue` to get the full issue context including any comments that might provide additional clarification. - -### 2. Determine Approach -Based on the issue analysis, determine if this is: -- A bug fix requiring immediate implementation -- A feature request needing careful design -- A spike requiring research and documentation -- An invalid/duplicate issue to close - -### 3. Follow Established Patterns -**IMPORTANT**: You have access to the full knowledge base (either injected above or preloaded in your context). Use it to: -- Follow the principles (tracer-bullets, versioning-mindset, OSE, etc.) -- Apply the appropriate procedures (git-workflow, worktree-workflow, etc.) -- Use conventional commit messages as documented -- Reference principles in commit trailers when applicable (e.g., `Principle: systems-stewardship`) - -### 4. Implementation -- Create clean, focused changes that follow existing patterns -- Write code that follows the conventions you see in the codebase -- Use TodoWrite to track your progress through complex implementations -- Test your changes when possible - -### 5. PR Creation -Ensure your commits: -- Have clear, conventional commit messages -- Reference the issue with "Closes #{{ ISSUE_NUMBER }}" -- Follow the git workflow standards from the knowledge base - -## Key Principles to Apply - -1. **Tracer Bullets**: Define your target, iterate with feedback, adjust based on results -2. **Versioning Mindset**: Iterate on existing code rather than rewriting -3. **Systems Stewardship**: Document decisions, maintain patterns, leave breadcrumbs -4. **Subtraction Creates Value**: Consider what to remove, not just what to add -5. **OSE**: Maintain elevated perspective, think systemically - -## Available Tools - -You have access to these tools: -- File operations: Read, Write, Edit, MultiEdit, LS, Glob, Grep -- Git operations: mcp__git (full git functionality) -- GitHub operations: mcp__github (API access) -- Task management: Task, TodoWrite -- Web tools: WebFetch, WebSearch -- Shell: Bash - -## Important Reminders - -- The knowledge base is your guide - use it actively -- This is not a blind implementation - you have full context -- Create PRs that match the quality of local development -- Follow the established patterns, don't reinvent them + ## Core Principle: Target-First Development {{ INJECT:principles/tracer-bullets.md }} -## Close Issue Procedure +## Analyze Issue #{{ ISSUE_NUMBER }} +First, use `mcp__github__get_issue` to understand the issue and determine the appropriate workflow path. + {{ INJECT:procedures/close-issue-procedure.md }} -Now proceed with implementing issue #{{ ISSUE_NUMBER }}. +## Apply to Issue #{{ ISSUE_NUMBER }} +When following the procedure: +- Use issue #{{ ISSUE_NUMBER }} for all GitHub API calls +- Replace with {{ ISSUE_NUMBER }} in branch names +- Replace with issue title slug +- Reference "Closes #{{ ISSUE_NUMBER }}" in PR body -## Post-Implementation Retro -After completing the implementation and creating the PR, let's retro this context and wring out the gleanings. +## Final Step: Retro +Let's retro this context and wring out the gleanings. {{ INJECT:principles/eager-evolution.md }} From f76032a43f2aca545febf91689a46d4742465464 Mon Sep 17 00:00:00 2001 From: Morgan Joyce Date: Mon, 4 Aug 2025 16:00:38 -0500 Subject: [PATCH 09/14] docs(procedures): achieve documentation as code for close-issue workflow Make the implementation template the authoritative documentation by: - Updating close-issue-procedure.md to point to actual implementation - Adding inline documentation comments to the template - Establishing that the template IS the documentation The template is now both the executable code AND the documentation. What you read is what runs. True documentation as code. This completes the unification of /close-issue and @claude workflows into a single, knowledge-aware, self-documenting system. Principle: systems-stewardship Principle: subtraction-creates-value --- .../workflow-prompts/issue-implementation.md | 2 ++ knowledge/procedures/close-issue-procedure.md | 19 ++++++++++++++++--- 2 files changed, 18 insertions(+), 3 deletions(-) diff --git a/.github/workflow-prompts/issue-implementation.md b/.github/workflow-prompts/issue-implementation.md index 036f471f..9491bed0 100644 --- a/.github/workflow-prompts/issue-implementation.md +++ b/.github/workflow-prompts/issue-implementation.md @@ -25,8 +25,10 @@ Complete and implement GitHub issue #{{ ISSUE_NUMBER }}. {{ INJECT:principles/tracer-bullets.md }} ## Analyze Issue #{{ ISSUE_NUMBER }} + First, use `mcp__github__get_issue` to understand the issue and determine the appropriate workflow path. + {{ INJECT:procedures/close-issue-procedure.md }} ## Apply to Issue #{{ ISSUE_NUMBER }} diff --git a/knowledge/procedures/close-issue-procedure.md b/knowledge/procedures/close-issue-procedure.md index 161c43fe..0144adc3 100644 --- a/knowledge/procedures/close-issue-procedure.md +++ b/knowledge/procedures/close-issue-procedure.md @@ -1,6 +1,19 @@ # Close Issue Procedure -Analyze GitHub issues and determine the path: quick close, spike research, or full implementation to PR. +The authoritative procedure for implementing GitHub issues. -**When to use**: Processing any GitHub issue with the /close-issue command -**Details**: See [close-issue-guide.md](/.github/ISSUE_TEMPLATE/close-issue-guide.md) \ No newline at end of file +**The implementation template IS the documentation.** + +**See the actual implementation:** +- Template: `.github/workflow-prompts/issue-implementation.md` +- Knowledge aggregation: `.github/scripts/aggregate-knowledge.sh` + +**When to use**: Processing any GitHub issue with /close-issue or @claude + +Both workflows use the same template: +- `/close-issue` command: Injects template with preloaded knowledge +- `@claude` GitHub Action: Injects template with aggregated knowledge + +The template defines the entire workflow - what you read is what runs. + +**Detailed guide**: See [close-issue-guide.md](/.github/ISSUE_TEMPLATE/close-issue-guide.md) for decision matrices and edge cases. \ No newline at end of file From 8ba10e521b6ac7640c1113a984fd694cfbf47182 Mon Sep 17 00:00:00 2001 From: Morgan Joyce Date: Mon, 4 Aug 2025 16:09:21 -0500 Subject: [PATCH 10/14] fix(scripts): add error handling for missing knowledge files Added counters to track if any .md files were found in the principles and procedures directories. If no files are found, the script now outputs a clear message instead of failing silently or processing glob patterns as literal strings. This prevents issues when: - Knowledge directories are empty - No .md files exist yet in new installations - Glob patterns don't match any files The script now gracefully handles these edge cases and provides helpful feedback to users and GitHub Actions. Principle: systems-stewardship --- .github/scripts/aggregate-knowledge.sh | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/.github/scripts/aggregate-knowledge.sh b/.github/scripts/aggregate-knowledge.sh index a4c74af8..d86c8176 100755 --- a/.github/scripts/aggregate-knowledge.sh +++ b/.github/scripts/aggregate-knowledge.sh @@ -40,8 +40,10 @@ if [[ -d "$KNOWLEDGE_DIR/principles" ]]; then echo "# Core Principles" echo "" + found_principles=0 for file in "$KNOWLEDGE_DIR/principles"/*.md; do if [[ -f "$file" ]]; then + found_principles=1 filename=$(basename "$file" .md) # Convert filename to title case (e.g., tracer-bullets -> Tracer Bullets) title=$(echo "$filename" | sed 's/-/ /g' | sed 's/\b\(.\)/\u\1/g') @@ -54,6 +56,11 @@ if [[ -d "$KNOWLEDGE_DIR/principles" ]]; then echo "" fi done + + if [[ $found_principles -eq 0 ]]; then + echo "No principle files found in knowledge/principles/" + echo "" + fi fi # Read all procedure files @@ -61,8 +68,10 @@ if [[ -d "$KNOWLEDGE_DIR/procedures" ]]; then echo "# Established Procedures" echo "" + found_procedures=0 for file in "$KNOWLEDGE_DIR/procedures"/*.md; do if [[ -f "$file" ]]; then + found_procedures=1 filename=$(basename "$file" .md) # Convert filename to title case title=$(echo "$filename" | sed 's/-/ /g' | sed 's/\b\(.\)/\u\1/g') @@ -75,6 +84,11 @@ if [[ -d "$KNOWLEDGE_DIR/procedures" ]]; then echo "" fi done + + if [[ $found_procedures -eq 0 ]]; then + echo "No procedure files found in knowledge/procedures/" + echo "" + fi fi # Add a footer note From 49c873ca5a126a5636275c2b8a8f641eb5790ffe Mon Sep 17 00:00:00 2001 From: Morgan Joyce Date: Mon, 4 Aug 2025 16:24:15 -0500 Subject: [PATCH 11/14] refactor(procedures): achieve true documentation as code Move the entire issue implementation template to knowledge/procedures/close-issue-procedure.md where it becomes the single source of truth for both local /close-issue and GitHub @claude. The procedure IS the implementation - no separate template files needed. This achieves true documentation as code where the procedure documents itself by being the executable code. - Delete .github/workflow-prompts/ directory entirely - Update close-issue.md to just 3 lines pointing to the procedure - Update claude-implementation.yml to read directly from procedures/ - Transform close-issue-procedure.md to contain the full implementation Principle: systems-stewardship Principle: subtraction-creates-value --- .claude/command-templates/close-issue.md | 2 +- .../workflow-prompts/issue-implementation.md | 50 ------------------- .github/workflow-prompts/issue-triage.md | 46 ----------------- .github/workflows/claude-implementation.yml | 4 +- knowledge/procedures/close-issue-procedure.md | 50 +++++++++++++++---- 5 files changed, 42 insertions(+), 110 deletions(-) delete mode 100644 .github/workflow-prompts/issue-implementation.md delete mode 100644 .github/workflow-prompts/issue-triage.md diff --git a/.claude/command-templates/close-issue.md b/.claude/command-templates/close-issue.md index e8a47f77..6b9ba45a 100644 --- a/.claude/command-templates/close-issue.md +++ b/.claude/command-templates/close-issue.md @@ -1,4 +1,4 @@ # Close Issue Command Template Complete and implement GitHub issue #{{ ISSUE_NUMBER }}. -{{ INJECT:../../.github/workflow-prompts/issue-implementation.md }} \ No newline at end of file +{{ INJECT:knowledge/procedures/close-issue-procedure.md }} \ No newline at end of file diff --git a/.github/workflow-prompts/issue-implementation.md b/.github/workflow-prompts/issue-implementation.md deleted file mode 100644 index 9491bed0..00000000 --- a/.github/workflow-prompts/issue-implementation.md +++ /dev/null @@ -1,50 +0,0 @@ -# Issue Implementation Template -# -# This is the SINGLE SOURCE OF TRUTH for issue implementation. -# Used by both: -# - Local /close-issue command (via relative path injection) -# - GitHub Actions @claude workflow (with knowledge base injection) -# -# IMPORTANT: How {{ KNOWLEDGE_BASE }} works: -# - For GitHub Actions: Gets replaced with aggregated knowledge files via string substitution -# - For local /close-issue: Remains as literal text "{{ KNOWLEDGE_BASE }}" in the prompt -# (harmless since knowledge is already preloaded in Claude's context) -# -# This is NOT smart placeholder logic - it's simple: -# - GitHub Actions: Does string replacement: {{ KNOWLEDGE_BASE }} → actual content -# - Local command: Does NO replacement: {{ KNOWLEDGE_BASE }} → stays as literal text -# -# Principle: systems-stewardship (single source of truth) - -Complete and implement GitHub issue #{{ ISSUE_NUMBER }}. - -{{ KNOWLEDGE_BASE }} - - -## Core Principle: Target-First Development -{{ INJECT:principles/tracer-bullets.md }} - -## Analyze Issue #{{ ISSUE_NUMBER }} - -First, use `mcp__github__get_issue` to understand the issue and determine the appropriate workflow path. - - -{{ INJECT:procedures/close-issue-procedure.md }} - -## Apply to Issue #{{ ISSUE_NUMBER }} -When following the procedure: -- Use issue #{{ ISSUE_NUMBER }} for all GitHub API calls -- Replace with {{ ISSUE_NUMBER }} in branch names -- Replace with issue title slug -- Reference "Closes #{{ ISSUE_NUMBER }}" in PR body - -## Final Step: Retro -Let's retro this context and wring out the gleanings. - -{{ INJECT:principles/eager-evolution.md }} - -**Consider capturing any ghost procedures** that emerged during this work - see [Procedure Creation](knowledge/procedures/procedure-creation.md). - -**What would you like to focus on?** -- Do you have a specific aspect you want to double-click on? -- Or would you like me to suggest the top 3 areas I predict you'll find most valuable to explore? \ No newline at end of file diff --git a/.github/workflow-prompts/issue-triage.md b/.github/workflow-prompts/issue-triage.md deleted file mode 100644 index 5aff3d8e..00000000 --- a/.github/workflow-prompts/issue-triage.md +++ /dev/null @@ -1,46 +0,0 @@ -You're an issue triage assistant for GitHub issues. Your task is to analyze the issue and select appropriate labels from the provided list. - -IMPORTANT: The GitHub Action will automatically post a progress comment ("Claude Code is working..."). Don't add any additional comments beyond applying labels. Focus solely on analyzing and labeling the issue. - -Issue Information: -- REPO: {{ REPO }} -- ISSUE_NUMBER: {{ ISSUE_NUMBER }} - -TASK OVERVIEW: - -1. First, fetch the list of labels available in this repository by running: `gh label list`. Run exactly this command with nothing else. - -2. Next, use the GitHub tools to get context about the issue: - - You have access to these tools: - - mcp__github-write__get_issue: Use this to retrieve the current issue's details including title, description, and existing labels - - mcp__github-write__get_issue_comments: Use this to read any discussion or additional context provided in the comments - - mcp__github-write__update_issue: Use this to apply labels to the issue (do not use this for commenting) - - mcp__github-write__search_issues: Use this to find similar issues that might provide context for proper categorization and to identify potential duplicate issues - - mcp__github-write__list_issues: Use this to understand patterns in how other issues are labeled - - Start by using mcp__github-write__get_issue to get the issue details - -3. Analyze the issue content, considering: - - Core principles mentioned (versioning-mindset, subtraction-creates-value, ose, snowball-method, tracer-bullets, systems-stewardship, throughput-definition) - - The issue title and description - - The type of issue (bug report, feature request, spike, etc.) - - Technical areas mentioned - - Components affected - -4. Select appropriate labels from the available labels list: - - Focus on principle-based labels when applicable - - If issue was edited, remove labels that no longer apply - - Be minimal - only add labels that add value - - Consider if this is a spike (research/exploration task) - -5. Apply the selected labels: - - Use mcp__github-write__update_issue to apply your selected labels - - DO NOT post any additional comments explaining your decision (the action already posts one) - - DO NOT communicate directly with users - - If no labels are clearly applicable, do not apply any labels - -IMPORTANT GUIDELINES: -- Be thorough in your analysis -- Only select labels from the provided list -- DO NOT post any additional comments (the action's automatic comment is sufficient) -- Your ONLY action should be to apply labels using mcp__github-write__update_issue -- Focus on principles over implementation details \ No newline at end of file diff --git a/.github/workflows/claude-implementation.yml b/.github/workflows/claude-implementation.yml index bef46002..331c7593 100644 --- a/.github/workflows/claude-implementation.yml +++ b/.github/workflows/claude-implementation.yml @@ -101,8 +101,8 @@ jobs: ISSUE_TITLE="${{ github.event.issue.title }}" ISSUE_BODY="${{ github.event.issue.body }}" - # Load the template - TEMPLATE=$(cat .github/workflow-prompts/issue-implementation.md) + # Load the procedure (which IS the implementation) + TEMPLATE=$(cat knowledge/procedures/close-issue-procedure.md) # Replace placeholders PROMPT="${TEMPLATE//\{\{ KNOWLEDGE_BASE \}\}/${{ steps.knowledge.outputs.content }}}" diff --git a/knowledge/procedures/close-issue-procedure.md b/knowledge/procedures/close-issue-procedure.md index 0144adc3..07bd6350 100644 --- a/knowledge/procedures/close-issue-procedure.md +++ b/knowledge/procedures/close-issue-procedure.md @@ -1,19 +1,47 @@ # Close Issue Procedure +# +# This IS the implementation - the procedure documents itself by being the code. +# Used by both: +# - Local /close-issue command (via relative path injection) +# - GitHub Actions @claude workflow (with knowledge base injection) +# +# IMPORTANT: How {{ KNOWLEDGE_BASE }} works: +# - For GitHub Actions: Gets replaced with aggregated knowledge files via string substitution +# - For local /close-issue: Remains as literal text "{{ KNOWLEDGE_BASE }}" in the prompt +# (harmless since knowledge is already preloaded in Claude's context) +# +# This is NOT smart placeholder logic - it's simple: +# - GitHub Actions: Does string replacement: {{ KNOWLEDGE_BASE }} → actual content +# - Local command: Does NO replacement: {{ KNOWLEDGE_BASE }} → stays as literal text +# +# Principle: systems-stewardship (single source of truth, documentation as code) -The authoritative procedure for implementing GitHub issues. +Complete and implement GitHub issue #{{ ISSUE_NUMBER }}. -**The implementation template IS the documentation.** +{{ KNOWLEDGE_BASE }} + -**See the actual implementation:** -- Template: `.github/workflow-prompts/issue-implementation.md` -- Knowledge aggregation: `.github/scripts/aggregate-knowledge.sh` +## Core Principle: Target-First Development +{{ INJECT:principles/tracer-bullets.md }} -**When to use**: Processing any GitHub issue with /close-issue or @claude +## Analyze Issue #{{ ISSUE_NUMBER }} + +First, use `mcp__github__get_issue` to understand the issue and determine the appropriate workflow path. -Both workflows use the same template: -- `/close-issue` command: Injects template with preloaded knowledge -- `@claude` GitHub Action: Injects template with aggregated knowledge +## Apply to Issue #{{ ISSUE_NUMBER }} +When following the procedure: +- Use issue #{{ ISSUE_NUMBER }} for all GitHub API calls +- Replace with {{ ISSUE_NUMBER }} in branch names +- Replace with issue title slug +- Reference "Closes #{{ ISSUE_NUMBER }}" in PR body -The template defines the entire workflow - what you read is what runs. +## Final Step: Retro +Let's retro this context and wring out the gleanings. -**Detailed guide**: See [close-issue-guide.md](/.github/ISSUE_TEMPLATE/close-issue-guide.md) for decision matrices and edge cases. \ No newline at end of file +{{ INJECT:principles/eager-evolution.md }} + +**Consider capturing any ghost procedures** that emerged during this work - see [Procedure Creation](knowledge/procedures/procedure-creation.md). + +**What would you like to focus on?** +- Do you have a specific aspect you want to double-click on? +- Or would you like me to suggest the top 3 areas I predict you'll find most valuable to explore? \ No newline at end of file From ceb00424c10530ce39e6ee3c39f73cab86526e97 Mon Sep 17 00:00:00 2001 From: Morgan Joyce Date: Mon, 4 Aug 2025 16:29:48 -0500 Subject: [PATCH 12/14] fix(workflows): restore issue-triage.md for auto-label workflow Restore the accidentally deleted issue-triage.md which is actively used by the auto-label-issues.yml workflow. Without this file, the auto-labeling functionality would break. Added explanatory comment clarifying why this file remains in workflow-prompts/ rather than procedures/ - it's a specialized AI prompt for GitHub Actions, not a human-executable procedure. Principle: systems-stewardship --- .github/workflow-prompts/issue-triage.md | 54 ++++++++++++++++++++++++ 1 file changed, 54 insertions(+) create mode 100644 .github/workflow-prompts/issue-triage.md diff --git a/.github/workflow-prompts/issue-triage.md b/.github/workflow-prompts/issue-triage.md new file mode 100644 index 00000000..5aa88e26 --- /dev/null +++ b/.github/workflow-prompts/issue-triage.md @@ -0,0 +1,54 @@ +# Issue Triage Template +# +# This template is used by .github/workflows/auto-label-issues.yml for automatic issue labeling. +# It's kept separate from procedures/ because it's a specialized workflow prompt, not a +# human-executable procedure. It doesn't need the formality of the procedures directory. +# +# Principle: systems-stewardship (specialized tools for specialized tasks) + +You're an issue triage assistant for GitHub issues. Your task is to analyze the issue and select appropriate labels from the provided list. + +IMPORTANT: The GitHub Action will automatically post a progress comment ("Claude Code is working..."). Don't add any additional comments beyond applying labels. Focus solely on analyzing and labeling the issue. + +Issue Information: +- REPO: {{ REPO }} +- ISSUE_NUMBER: {{ ISSUE_NUMBER }} + +TASK OVERVIEW: + +1. First, fetch the list of labels available in this repository by running: `gh label list`. Run exactly this command with nothing else. + +2. Next, use the GitHub tools to get context about the issue: + - You have access to these tools: + - mcp__github-write__get_issue: Use this to retrieve the current issue's details including title, description, and existing labels + - mcp__github-write__get_issue_comments: Use this to read any discussion or additional context provided in the comments + - mcp__github-write__update_issue: Use this to apply labels to the issue (do not use this for commenting) + - mcp__github-write__search_issues: Use this to find similar issues that might provide context for proper categorization and to identify potential duplicate issues + - mcp__github-write__list_issues: Use this to understand patterns in how other issues are labeled + - Start by using mcp__github-write__get_issue to get the issue details + +3. Analyze the issue content, considering: + - Core principles mentioned (versioning-mindset, subtraction-creates-value, ose, snowball-method, tracer-bullets, systems-stewardship, throughput-definition) + - The issue title and description + - The type of issue (bug report, feature request, spike, etc.) + - Technical areas mentioned + - Components affected + +4. Select appropriate labels from the available labels list: + - Focus on principle-based labels when applicable + - If issue was edited, remove labels that no longer apply + - Be minimal - only add labels that add value + - Consider if this is a spike (research/exploration task) + +5. Apply the selected labels: + - Use mcp__github-write__update_issue to apply your selected labels + - DO NOT post any additional comments explaining your decision (the action already posts one) + - DO NOT communicate directly with users + - If no labels are clearly applicable, do not apply any labels + +IMPORTANT GUIDELINES: +- Be thorough in your analysis +- Only select labels from the provided list +- DO NOT post any additional comments (the action's automatic comment is sufficient) +- Your ONLY action should be to apply labels using mcp__github-write__update_issue +- Focus on principles over implementation details \ No newline at end of file From a8cdd455ba3b2c8dcd66445d763c495d076b7a3f Mon Sep 17 00:00:00 2001 From: Morgan Joyce Date: Mon, 4 Aug 2025 16:32:51 -0500 Subject: [PATCH 13/14] refactor(workflows): clarify why issue-triage.md stays separate Update comment to be more honest - it's a low-value utility script that works fine and doesn't need to consume precious tokens in the knowledge base context. Not everything needs formal procedure status when it just works. Principle: subtraction-creates-value --- .github/workflow-prompts/issue-triage.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/.github/workflow-prompts/issue-triage.md b/.github/workflow-prompts/issue-triage.md index 5aa88e26..1f42acbb 100644 --- a/.github/workflow-prompts/issue-triage.md +++ b/.github/workflow-prompts/issue-triage.md @@ -1,10 +1,10 @@ # Issue Triage Template # -# This template is used by .github/workflows/auto-label-issues.yml for automatic issue labeling. -# It's kept separate from procedures/ because it's a specialized workflow prompt, not a -# human-executable procedure. It doesn't need the formality of the procedures directory. +# Utility script for .github/workflows/auto-label-issues.yml that auto-labels issues. +# Kept separate from knowledge/ to preserve tokens - this is a low-value script that +# just works and doesn't need to be part of the ~30k token knowledge base context. # -# Principle: systems-stewardship (specialized tools for specialized tasks) +# Principle: subtraction-creates-value (not everything needs formal procedure status) You're an issue triage assistant for GitHub issues. Your task is to analyze the issue and select appropriate labels from the provided list. From 8871a76be778b3a6008e254febb3e19492d6abd7 Mon Sep 17 00:00:00 2001 From: Morgan Joyce Date: Mon, 4 Aug 2025 16:39:16 -0500 Subject: [PATCH 14/14] fix(scripts): aggregate ALL knowledge files to match Claude Code behavior Update aggregate-knowledge.sh to recursively process the entire knowledge/ directory, not just principles/ and procedures/. This ensures GitHub Actions has the exact same context as local Claude Code. Now includes: - Root files (README.md, ai-index.md, throughput-definition.md) - personalities/ directory (Brent, Jonah, Harrington-Emerson) - tools/ directory (MCP dashboard) - All subdirectories that may be added in future Changed from ~30k to ~72k characters of knowledge context, achieving true parity with local Claude Code behavior. Principle: systems-stewardship --- .github/scripts/aggregate-knowledge.sh | 117 +++++++++++++------------ 1 file changed, 60 insertions(+), 57 deletions(-) diff --git a/.github/scripts/aggregate-knowledge.sh b/.github/scripts/aggregate-knowledge.sh index d86c8176..94090ef8 100755 --- a/.github/scripts/aggregate-knowledge.sh +++ b/.github/scripts/aggregate-knowledge.sh @@ -1,7 +1,7 @@ #!/bin/bash # Aggregate knowledge base for GitHub Actions -# This script reads all knowledge files and outputs them as a single text block -# for injection into Claude's prompt in GitHub Actions workflows +# This script reads ALL knowledge files (matching Claude Code's behavior) +# and outputs them as a single text block for injection into Claude's prompt # Principle: systems-stewardship set -euo pipefail @@ -10,45 +10,60 @@ set -euo pipefail REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)" KNOWLEDGE_DIR="$REPO_ROOT/knowledge" -# Function to output a section with clear markers -output_section() { - local title="$1" - local content="$2" - - echo "## $title" - echo "" - echo "$content" - echo "" -} - # Start with a header echo "# Knowledge Base Context" echo "" echo "This context is automatically injected to provide Claude with understanding of:" -echo "- Core development principles" -echo "- Established procedures and workflows" -echo "- Git conventions and standards" -echo "- System architecture patterns" +echo "- Core development principles and procedures" +echo "- Personality models for retrospectives" +echo "- System architecture patterns and tools" +echo "- The North Star throughput definition" echo "" # Note: CLAUDE.md is not included here as it's a user-specific file # that lives in ~/.claude/CLAUDE.md (not in the repository). # GitHub Actions only has access to committed repository files. -# Read all principle files -if [[ -d "$KNOWLEDGE_DIR/principles" ]]; then - echo "# Core Principles" - echo "" +# Process all .md files in knowledge/ recursively to match Claude Code behavior +# This ensures GitHub Actions has the exact same context as local development +process_directory() { + local dir="$1" + local relative_path="${dir#$KNOWLEDGE_DIR}" + relative_path="${relative_path#/}" # Remove leading slash if present - found_principles=0 - for file in "$KNOWLEDGE_DIR/principles"/*.md; do + # Process files in current directory first + for file in "$dir"/*.md; do if [[ -f "$file" ]]; then - found_principles=1 filename=$(basename "$file" .md) - # Convert filename to title case (e.g., tracer-bullets -> Tracer Bullets) - title=$(echo "$filename" | sed 's/-/ /g' | sed 's/\b\(.\)/\u\1/g') - echo "## $title" + # Skip README files in subdirectories (but include the main one) + if [[ "$filename" == "README" && "$relative_path" != "" ]]; then + continue + fi + + # Create section header based on location + if [[ "$relative_path" == "" ]]; then + # Root knowledge files + title=$(echo "$filename" | sed 's/-/ /g' | sed 's/\b\(.\)/\u\1/g') + echo "# $title" + elif [[ "$relative_path" == "principles" ]]; then + title=$(echo "$filename" | sed 's/-/ /g' | sed 's/\b\(.\)/\u\1/g') + echo "## Principle: $title" + elif [[ "$relative_path" == "procedures" ]]; then + title=$(echo "$filename" | sed 's/-/ /g' | sed 's/\b\(.\)/\u\1/g') + echo "## Procedure: $title" + elif [[ "$relative_path" == "personalities" ]]; then + title=$(echo "$filename" | sed 's/-/ /g' | sed 's/\b\(.\)/\u\1/g') + echo "## Personality: $title" + elif [[ "$relative_path" == "tools" ]]; then + title=$(echo "$filename" | sed 's/-/ /g' | sed 's/\b\(.\)/\u\1/g') + echo "## Tool: $title" + else + # Other directories + title=$(echo "$filename" | sed 's/-/ /g' | sed 's/\b\(.\)/\u\1/g') + echo "## $relative_path: $title" + fi + echo "" cat "$file" echo "" @@ -57,38 +72,26 @@ if [[ -d "$KNOWLEDGE_DIR/principles" ]]; then fi done - if [[ $found_principles -eq 0 ]]; then - echo "No principle files found in knowledge/principles/" - echo "" - fi -fi - -# Read all procedure files -if [[ -d "$KNOWLEDGE_DIR/procedures" ]]; then - echo "# Established Procedures" - echo "" - - found_procedures=0 - for file in "$KNOWLEDGE_DIR/procedures"/*.md; do - if [[ -f "$file" ]]; then - found_procedures=1 - filename=$(basename "$file" .md) - # Convert filename to title case - title=$(echo "$filename" | sed 's/-/ /g' | sed 's/\b\(.\)/\u\1/g') - - echo "## $title" - echo "" - cat "$file" - echo "" - echo "---" - echo "" + # Process subdirectories + for subdir in "$dir"/*; do + if [[ -d "$subdir" ]]; then + dirname=$(basename "$subdir") + # Add section header for new directory + if [[ "$relative_path" == "" ]]; then + echo "# $(echo "$dirname" | sed 's/\b\(.\)/\u\1/g')" + echo "" + fi + process_directory "$subdir" fi done - - if [[ $found_procedures -eq 0 ]]; then - echo "No procedure files found in knowledge/procedures/" - echo "" - fi +} + +# Process the entire knowledge directory +if [[ -d "$KNOWLEDGE_DIR" ]]; then + process_directory "$KNOWLEDGE_DIR" +else + echo "Knowledge directory not found at: $KNOWLEDGE_DIR" + echo "" fi # Add a footer note