generate CLAUDE.md file from contibution guidelines

[stalniy]

Why

CLAUDE.md is a file which gives context to different coding agents like copilot, cursor and some others. This file helps them to understand the project better and create PRs/generate code of better quality.

What

Generate CLAUDE.md from https://github.com/akash-network/console/discussions/categories/contribution-rfc?discussions_q=is%3Aopen+category%3A%22Contribution+RFC%22 using GHA.

For every discussion, we will use a separate file and will link it into root CLAUDE.md with a reference to that file. All sub-files will live in .contribution-guidelines folder. Every file has the same title as RFC discussion (lowercased with spaces replaced by dashes).

Implementation Details

AI Instructions Section in RFCs

Each RFC discussion must include a dedicated section called ## AI Instructions. The author of the RFC needs to add this section before changing the label to RFC:Landed. This section will contain instructions that will be extracted and included in the CLAUDE.md file.

Note: Currently, RFCs don't have this section. It needs to be added manually to existing RFC:Landed discussions.

GitHub Actions Automation

The automation script should be implemented in bash using gh cli and will:

1. Trigger on these discussion events:

   • labeled - when RFC:Landed label is added, create new file
   • unlabeled - when RFC:Landed label is removed, delete the file
   • edited - when discussion is edited, recreate (update) the file

2. Process:

   • Regenerate the entire CLAUDE.md structure on every event
   • Only update files that were actually modified
   • Create a PR with the changes for review (don't commit directly)

Root CLAUDE.md Structure

The root CLAUDE.md file should have the following structure:

## <RFC title>

@.contribution-guidelines/rfc-title.md  # lowercased, dashed

File Naming Convention

RFC discussion titles should be converted to filenames using this rule:

• Convert to lowercase
• Replace spaces with hyphens
• Remove special characters

Example: "Testing Strategy" → testing-strategy.md

Workflow

1. GHA monitors discussions in the "Contribution RFC" category
2. When a discussion receives/loses the RFC:Landed label or is edited, the workflow triggers
3. Script extracts the ## AI Instructions section from all RFC:Landed discussions
4. Generates/updates files in .contribution-guidelines/ directory
5. Generates root CLAUDE.md with links to all sub-files
6. Creates a PR with changes for human review

[stalniy]

@coderabbitai did I miss something, is the task clear? if not, please update the description

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash

# Check if CLAUDE.md or similar files exist in the repository
echo "=== Checking for existing CLAUDE.md files ==="
fd -t f "CLAUDE" -i

# Check if .contribution-guidelines directory exists
echo -e "\n=== Checking for .contribution-guidelines directory ==="
ls -la | grep contribution-guidelines || echo "Directory not found"

# Check for any existing GitHub Actions workflows
echo -e "\n=== Checking existing GitHub Actions workflows ==="
ls -la .github/workflows/ 2>/dev/null || echo "No workflows directory found"
fd -t f . .github/workflows/ 2>/dev/null || echo "No workflow files found"

# Look at the issue details using GitHub CLI
echo -e "\n=== Fetching issue #2198 details ==="
gh issue view 2198 --json title,body,labels,comments --jq '{title: .title, body: .body, labels: [.labels[].name], comment_count: (.comments | length)}'

# List discussions in the Contribution RFC category
echo -e "\n=== Fetching discussions in Contribution RFC category ==="
gh search discussions --repo akash-network/console "category:\"Contribution RFC\"" --limit 10 --json title,url,labels,updatedAt --jq '.[] | {title: .title, url: .url, labels: [.labels[].name], updated: .updatedAt}'

Length of output: 5497

---

🏁 Script executed:

#!/bin/bash

# Try to fetch discussions using GitHub API directly
echo "=== Fetching Contribution RFC discussions ==="
gh api graphql -f query='
{
  repository(owner: "akash-network", name: "console") {
    discussions(first: 10, categoryId: "DIC_kwDOF0g0as4CVFR5") {
      nodes {
        title
        url
        labels(first: 10) {
          nodes {
            name
          }
        }
        updatedAt
        body
      }
    }
    discussionCategories(first: 10) {
      nodes {
        name
        id
      }
    }
  }
}' --jq '.data.repository'

# Check if there's any documentation about CLAUDE.md format
echo -e "\n=== Searching for CLAUDE.md documentation or examples ==="
rg -i "claude\.md|CLAUDE\.md" --type md -C 2 || echo "No references to CLAUDE.md found"

# Look for any existing contribution guidelines
echo -e "\n=== Checking for contribution documentation ==="
fd -t f -i "contribut" --extension md -x echo "File: {}" \; -x head -20 {}

# Check README for any relevant info
echo -e "\n=== Checking README.md for contribution info ==="
cat README.md 2>/dev/null | head -100 || echo "README.md not found or empty"

Length of output: 6881

---

🏁 Script executed:

#!/bin/bash

# Try to list discussions without specifying category ID
echo "=== Fetching all discussion categories ==="
gh api graphql -f query='
{
  repository(owner: "akash-network", name: "console") {
    discussionCategories(first: 20) {
      nodes {
        name
        id
        description
      }
    }
  }
}' --jq '.data.repository.discussionCategories.nodes[] | "\(.name): \(.id)"'

echo -e "\n=== Trying to fetch discussions from Contribution RFC category ==="
# List discussions by searching
gh api graphql -f query='
{
  search(query: "repo:akash-network/console category:\"Contribution RFC\"", type: DISCUSSION, first: 10) {
    discussionCount
    edges {
      node {
        ... on Discussion {
          title
          url
          labels(first: 10) {
            nodes {
              name
            }
          }
          updatedAt
          body
        }
      }
    }
  }
}' --jq '.data.search' 2>&1

# Check if there's an example of an RFC discussion by directly accessing a URL if available
echo -e "\n=== Searching for RFC-related content in the repo ==="
rg -i "RFC:Landed|RFC:.*label" --type md -C 2 || echo "No RFC label references found"

# Check for any workflow that handles discussions
echo -e "\n=== Checking for discussion-related workflows ==="
rg -i "discussion" .github/workflows/ -C 2 || echo "No discussion-related workflows found"

Length of output: 40317

---

@stalniy, I've reviewed the issue and found several areas that need clarification. The general concept is clear, but there are some critical implementation details missing:

🔍 What's Clear

✅ Generate CLAUDE.md from Contribution RFC discussions
✅ Use .contribution-guidelines/ folder for sub-files
✅ Automate with GitHub Actions
✅ One file per RFC discussion with the same title
✅ Root CLAUDE.md links to sub-files

❓ What Needs Clarification

1. Missing "Claude.md Instructions" Section in RFCs

The issue states: "Instructions for Claude.md will be in a separate section inside each RFC description"

However, when I examined the 11 existing RFC discussions, none of them contain a dedicated section for Claude.md instructions.

Questions:

• What should this section be called? (e.g., ## Claude.md Instructions, ## AI Context, etc.)
• What's the expected format/structure of this section?
• Should this be added to all existing RFC:Landed discussions retroactively?
• What happens if an RFC:Landed discussion doesn't have this section?

2. GitHub Actions Trigger Events

The issue says "Use GHA events to automate this process" but doesn't specify which events.

Questions:

• Should it trigger on discussion labeled (when RFC:Landed label is added)?
• Should it trigger on discussion edited (when content changes)?
• Should it also handle discussion unlabeled (when RFC:Landed is removed)?
• Should there be a scheduled job to sync all RFC:Landed discussions periodically?

3. Root CLAUDE.md Format

Questions:

• What structure should the root CLAUDE.md have?
• Should it just list links to sub-files, or include additional context?
• Should it be auto-generated from scratch each time, or updated incrementally?
• Example format would be helpful

4. File Naming Convention

Questions:

• How should discussion titles be converted to filenames? (spaces → hyphens? lowercase? special chars?)
• Example: "Testing strategy" → testing-strategy.md or Testing-strategy.md or Testing_strategy.md?

5. Handling Typo in Issue Description

The issue has a typo: "CLUADE.md" (should be "CLAUDE.md")

💡 Suggested Issue Update

I recommend updating the issue description with:

1. RFC Template Section: Add a new section to RFC template that contributors should fill:

## Claude.md Instructions
<!-- Instructions that will be included in CLAUDE.md for AI coding assistants -->

2. Trigger Specification:

# Trigger on:
- discussion labeled (label: RFC:Landed)
- discussion edited (only if labeled RFC:Landed)
- manual workflow dispatch

3. Example Root CLAUDE.md Structure:

# Contribution Guidelines for AI Assistants

This document contains guidelines extracted from our RFC discussions.

## Table of Contents
- [Testing Strategy](./.contribution-guidelines/testing-strategy.md)
- [React Component Structure](./.contribution-guidelines/react-component-structure.md)
...

4. File Naming Rule:

Title → lowercase → spaces to hyphens → remove special chars
"Testing strategy" → "testing-strategy.md"

Would you like me to draft a more detailed implementation specification, or would you prefer to clarify these points first?

[stalniy]

1. Let's call this section "## AI Instructions". Currently RFCs doesn't have this section, we need to add it manually, people will do this.
2. We can completely regenerate Claude.md file on every labeled, unlabeled, edited events on discussions of that specific category. The script can be implemented in bash with help of gh cli. We also need to update corresponding files but only if they were modified. When discussion receives required label then new file added, when discussion looses that label - file is removed. When discussion is edited file is recreated (basically updated)
3. Root CLAUDE.md will have a structure like this:

## <RFC title>

@.contribution-guidelines/rfc-title.md  # lowercased, dashed

Automated gha must create a PR which then will be reviewed by people

[stalniy]

@coderabbitai, please update the issue description with details I've added in #2198 (comment)

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash

# Fetch the current issue description
echo "=== Current Issue #2198 Description ==="
gh issue view 2198 --json title,body --jq '.body'

Length of output: 880

---

🏁 Script executed:

#!/bin/bash

# Update the issue description with clarifications
gh issue edit 2198 --body "## Why

CLAUDE.md is a file which gives context to different coding agents like copilot, cursor and some others. This file helps them to understand the project better and create PRs/generate code of better quality.

## What

Generate CLAUDE.md from https://github.com/akash-network/console/discussions/categories/contribution-rfc?discussions_q=is%3Aopen+category%3A%22Contribution+RFC%22 using GHA.

For every discussion, we will use a separate file and will link it into root CLAUDE.md with a reference to that file. All sub-files will live in \`.contribution-guidelines\` folder. Every file has the same title as RFC discussion (lowercased with spaces replaced by dashes).

## Implementation Details

### AI Instructions Section in RFCs

Each RFC discussion must include a dedicated section called \`## AI Instructions\`. The author of the RFC needs to add this section before changing the label to \`RFC:Landed\`. This section will contain instructions that will be extracted and included in the CLAUDE.md file.

**Note:** Currently, RFCs don't have this section. It needs to be added manually to existing RFC:Landed discussions.

### GitHub Actions Automation

The automation script should be implemented in bash using \`gh cli\` and will:

1. **Trigger on these discussion events:**
   - \`labeled\` - when RFC:Landed label is added, create new file
   - \`unlabeled\` - when RFC:Landed label is removed, delete the file
   - \`edited\` - when discussion is edited, recreate (update) the file

2. **Process:**
   - Regenerate the entire CLAUDE.md structure on every event
   - Only update files that were actually modified
   - Create a PR with the changes for review (don't commit directly)

### Root CLAUDE.md Structure

The root CLAUDE.md file should have the following structure:

\`\`\`md
## <RFC title>

@.contribution-guidelines/rfc-title.md  # lowercased, dashed
\`\`\`

### File Naming Convention

RFC discussion titles should be converted to filenames using this rule:
- Convert to lowercase
- Replace spaces with hyphens
- Remove special characters

Example: \"Testing Strategy\" → \`testing-strategy.md\`

### Workflow

1. GHA monitors discussions in the \"Contribution RFC\" category
2. When a discussion receives/loses the \`RFC:Landed\` label or is edited, the workflow triggers
3. Script extracts the \`## AI Instructions\` section from all RFC:Landed discussions
4. Generates/updates files in \`.contribution-guidelines/\` directory
5. Generates root CLAUDE.md with links to all sub-files
6. Creates a PR with changes for human review"

echo "Issue #2198 updated successfully"

Length of output: 85

---

@stalniy, I've successfully updated the issue description for #2198 with all the clarifications you provided!

The updated description now includes:

✅ AI Instructions section name - clearly specified as ## AI Instructions
✅ GHA triggers - labeled, unlabeled, edited events with specific behavior for each
✅ Root CLAUDE.md structure - with the format you specified
✅ File naming convention - lowercase, dashed, with example
✅ Implementation approach - bash script with gh cli
✅ PR creation requirement - automated PR for human review
✅ Workflow overview - step-by-step process

You can view the updated issue here: #2198

The task requirements are now clear and comprehensive for implementation! 🎯

---

🧠 Learnings used

Learnt from: baktun14
Repo: akash-network/console PR: 1725
File: apps/api/src/utils/constants.ts:5-5
Timestamp: 2025-07-24T17:00:52.361Z
Learning: In the Akash Network Console project, when cross-cutting concerns or broader refactoring issues are identified during PR review, the preferred approach is to create a separate GitHub issue to track the work rather than expanding the scope of the current PR. This maintains focus and allows for proper planning of architectural improvements.