notque/vexjoy-agent / skills/process/workflow
workflow
VerifiedStructured work: multi-phase tasks, feature builds, planning, objective loops, hill climbing.
references/github-profile-rules.md
View on GitHub---
description: "Extract coding conventions from a GitHub user's public profile."
user-invocable: false
argument-hint: "<github-username>"
agent: github-profile-rules-engineer
allowed-tools:
- Read
- Write
- Bash
- Grep
- Glob
- Edit
- WebFetch
routing:
triggers:
- github rules
- profile analysis
- coding style extraction
- github conventions
pairs_with:
- domain-research
complexity: Medium
category: meta
---
# GitHub Profile Rules Extraction
## Overview
This pipeline extracts programming rules from a GitHub user's public profile by analyzing repositories, code files, commit messages, and PR reviews via the GitHub API. It produces confidence-scored rules formatted for CLAUDE.md-compatible markdown or JSON output. All data fetching is API-only (no git clone). Every extracted rule must have evidence from at least one repo or PR review, scored by confidence: high (3+ repos or 2+ repos + review signal), medium (2 repos), low (1 repo).
---
## Instructions
### Phase 0: ADR
**Goal**: Create a persistent reference document before work begins.
**Step 1**: Create `adr/github-profile-rules-{username}.md` with:
- Context: Why rules are being extracted for this user
- Decision: API-only approach, sampling strategy, target repos
- Constraints: Rate limits, public data only
- Test Plan: How generated rules will be validated
**Step 2**: Re-read the ADR before every major decision.
**Gate**: ADR file exists. Username validated via GitHub API. Proceed to Phase 1.
---
### Phase 1: FETCH
**Goal**: Fetch the user's repo list, language statistics, and README samples via GitHub API.
**Step 1**: Run the API fetcher to get repo metadata. Enforce API-only constraint — never use git clone:
```bash
python3 ~/.claude/scripts/github-api-fetcher.py repos \
--username {username} \
--max-repos {N} \
--output-dir /tmp/github-rules-{username}
```
**Step 2**: Review the output. Identify:
- Top repos by stars and recent activity
- Primary languages used
- Repository naming patterns
- README presence and quality signals
**Step 3**: Save profile summary to `/tmp/github-rules-{username}/profile-summary.md` with:
- Total public repos count
- Top 10 repos with stars, language, and description
- Language distribution
- README patterns observed
**Gate**: Repo list fetched. At least 1 repo with accessible content. Profile summary saved. Proceed to Phase 2.
---
### Phase 2: RESEARCH (Parallel Multi-Agent)
**Goal**: Sample code files from top repos to extract coding patterns.
**Step 1**: Prepare shared context block from Phase 1 profile summary.
**Step 2**: Dispatch 4 parallel research agents, each analyzing a different aspect:
- **Agent 1: Naming Conventions** -- variable names, function names, file names, class names across sampled files
- **Agent 2: Code Structure** -- file organization, import patterns, module structure, error handling patterns
- **Agent 3: Commit Messages** -- commit message format, conventional commits usage, message length and detail
- **Agent 4: Documentation Patterns** -- README structure, inline comments, docstring style, documentation quality
Each agent:
- Uses `python3 ~/.claude/scripts/github-api-fetcher.py sample-files` to fetch file contents (API-only, never clone)
- Saves findings to `/tmp/github-rules-{username}/research-{aspect}.md`
- Has a 5-minute timeout
- Operates independently
**Step 3**: Collect and merge research artifacts after all agents complete.
**Gate**: All 4 research agents completed. At least 10 files sampled across repos. Findings saved. Proceed to Phase 3.
---
### Phase 3: SAMPLE
**Goal**: Fetch PR reviews the user has given to extract preference signals. PR reviews carry 2x weight versus code authored when scoring confidence.
**Step 1**: Run the API fetcher to get PR reviews. Check rate limits before each batch (60 req/hr unauthenticated, 5000 req/hr with token):
```bash
python3 ~/.claude/scripts/github-api-fetcher.py pr-reviews \
--username {username} \
--output-dir /tmp/github-rules-{username}
```
**Step 2**: Analyze review comments for recurring themes:
- What patterns do they request changes for?
- What do they approve without comment?
- What feedback do they give most frequently?
- What style/convention issues do they flag?
**Step 3**: Categorize review signals by rule category (naming, style, architecture, testing, error handling, documentation).
**Step 4**: Save review analysis to `/tmp/github-rules-{username}/review-analysis.md`.
**Gate**: PR review data fetched (or documented that user has no public reviews). Review themes categorized. Proceed to Phase 4.
---
### Phase 4: COMPILE
**Goal**: Compile patterns from code analysis and review data, score confidence, and deduplicate.
**Step 1**: Load all research artifacts from Phase 2 and review analysis from Phase 3.
**Step 2**: For each identified pattern:
- Count how many repos it appears in
- Check if it's reinforced by review comments (adds 2x weight)
- Assign confidence: high (3+ repos OR 2+ repos + review signal), medium (2 repos), low (1 repo)
- Categorize using the taxonomy from `references/rule-categories.md`
**Step 3**: Deduplicate similar patterns:
- Merge "uses camelCase for variables" and "prefers camelCase naming" into one rule
- Keep the most specific version
- Combine evidence from all sources
**Step 4**: Run the rules compiler for structured output:
```bash
python3 ~/.claude/scripts/rules-compiler.py compile \
--input-dir /tmp/github-rules-{username} \
--output /tmp/github-rules-{username}/compiled-rules.json
```
**Step 5**: Save synthesis results to `/tmp/github-rules-{username}/synthesis.md`.
**Gate**: Patterns compiled and deduplicated. Confidence scores assigned. At least 5 rules identified. Proceed to Phase 5.
---
### Phase 5: GENERATE
**Goal**: Format compiled patterns as CLAUDE.md-compatible rule entries with evidence.
**Step 1**: For each rule, generate a CLAUDE.md entry following this format:
```markdown
## [Category]: [Rule Name]
**Confidence**: [high/medium/low] (seen in N repos, M review comments)
[Actionable rule description]
**Evidence**:
- Repo: {repo_name} -- {specific example}
- Review: {pr_url} -- "{comment excerpt}"
```
**Step 2**: Group rules by category (naming, style, architecture, testing, error handling, documentation).
**Step 3**: Order rules within each category by confidence (high first).
**Step 4**: Generate the JSON output with full metadata:
```json
{
"username": "{username}",
"generated_at": "{timestamp}",
"total_rules": N,
"rules": [
{
"category": "naming",
"rule": "...",
"confidence": "high",
"repos_observed": ["repo1", "repo2", "repo3"],
"review_signals": 2,
"examples": ["..."]
}
]
}
```
**Gate**: CLAUDE.md entries generated. JSON output generated. Both formats contain the same rules. Proceed to Phase 6.
---
### Phase 6: VALIDATE
**Goal**: Verify rules are actionable, non-contradictory, and properly scoped.
**Step 1**: Check each rule for actionability:
- Can a developer follow this rule without additional context? If not, add specifics.
- Does the rule include a concrete example? If not, add one from evidence.
**Step 2**: Check for contradictions:
- Scan for rules that conflict (e.g., "use camelCase" vs "use snake_case")
- If contradictions found: check if they apply to different languages/contexts
- Resolve by scoping (e.g., "use camelCase in JavaScript, snake_case in Python")
**Step 3**: Check scoping:
- Are language-specific rules properly scoped?
- Are project-type-specific rules properly scoped?
- Remove rules that are too broad to be actionable
**Step 4**: Run the rules compiler in validation mode:
```bash
python3 ~/.claude/scripts/rules-compiler.py validate \
--input-dir /tmp/github-rules-{username} \
--output /tmp/github-rules-{username}/validated-rules.json
```
**Gate**: All rules pass actionability check. No unresolved contradictions. Rules properly scoped. Proceed to Phase 7.
---
### Phase 7: OUTPUT
**Goal**: Save final rules to `rules/{username}/rules-output.md` and `rules/{username}/rules.json`.
**Step 1**: Create output directory:
```bash
mkdir -p rules/{username}
```
**Step 2**: Write `rules/{username}/rules-output.md` with:
- Header: "Programming Rules for {username}"
- Generation metadata: date, repos analyzed, files sampled, reviews mined
- Rules grouped by category, ordered by confidence
- Each rule in CLAUDE.md-compatible format
**Step 3**: Write `rules/{username}/rules.json` with:
- Full structured output including confidence scores, evidence, and metadata
**Step 4**: Generate summary report:
- Total rules by confidence level
- Rules by category distribution
- Top 5 highest-confidence rules
- Data coverage (repos analyzed, files sampled, reviews mined)
**Gate**: Output files exist. Both formats contain consistent data. Summary report delivered.
---
## Error Handling
### Error: API Rate Limit Exceeded
**Cause**: Too many requests without authentication token.
**Solution**: Check `X-RateLimit-Remaining`. Suggest `--token` flag. For unauthenticated: 60/hr. With token: 5000/hr. Implement backoff and check remaining quota before each batch of API calls.
### Error: No Public Repos or Reviews
**Cause**: User has no public GitHub activity.
**Solution**: Report that no data is available for analysis. Suggest checking username or noting the user may have only private activity.
### Error: Insufficient Data for Confident Rules
**Cause**: Too few repos or files to establish patterns.
**Solution**: Lower confidence thresholds and flag all rules as preliminary. Report data limitations. Only extract rules with evidence from the available data.
### Error: Generic or Unauthenticated Rules
**Constraint**: Every generated rule must cite at least one repo or review where the pattern was observed. No generic advice. Extract only patterns with specific evidence from the user's code — patterns like "Follow clean code principles" without concrete repo evidence are too generic to include.
### Error: Clone Attempts
**Constraint**: All GitHub data must be fetched via `scripts/github-api-fetcher.py`. No git clone, no subprocess git calls. This is a non-negotiable constraint. Pattern extraction happens via API-based file content sampling, never by cloning repositories.
---
## References
- [Rule Categories](references/rule-categories.md) -- taxonomy of programming rule types
- ADR: `adr/github-profile-rules.md` -- pipeline architecture decisions
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| planning-and-task-breakdownaddyosmani/agent-skillsBreaks work into ordered tasks. Use when you have a spec or clear requirements and need to break work into implementable tasks. Use when a task feels too large to start, when you need to estimate scope, or when parallel work is possible. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| screenpipethedotmack/claude-memSearch screen and audio history recorded by Screenpipe and optionally save selected context into claude-mem. Use when the user asks to recall desktop activity, a meeting, or something seen in another app through Screenpipe. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| contact-widgetnexu-io/open-designSelf-contained floating chat widget with welcome screen, social links, meeting button, and message input. Single HTML file, zero dependencies. | Stars: 108k | Updated | Claude CodeCodex | Verified | Install |
| meeting-notesnexu-io/open-designMeeting notes page — title bar with attendees, agenda checklist, decisions block, action items table with owners + dates, and a "next meeting" footer. Use when the brief mentions "meeting notes", "minutes", "1:1 notes", "all-hands recap", or "会议纪要". | Stars: 108k | Updated | Claude CodeCodex | Verified | Install |