Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
321 lines (257 loc) · 16.3 KB

CONTRIBUTING.md

File metadata and controls

321 lines (257 loc) · 16.3 KB

Contributing to Autoresearch

Thanks for wanting to make autoresearch better. Whether you're fixing a typo, adding examples, creating a new sub-command, or improving the loop protocol — this guide will get you up and running fast.

Quick Start

Autoresearch is Markdown files that Claude Code discovers from skills/ and commands/ directories. No build step, no compilation — edit a .md file, invoke the skill, see your changes.

# 1. Clone the repo
git clone https://github.com/uditgoenka/autoresearch.git
cd autoresearch

# 2. Copy to your local Claude Code (for testing)
cp -r claude-plugin/skills/autoresearch ~/.claude/skills/autoresearch
cp -r claude-plugin/commands/autoresearch ~/.claude/commands/autoresearch
cp claude-plugin/commands/autoresearch.md ~/.claude/commands/autoresearch.md

# 3. Or symlink for live editing (recommended for development)
ln -s $(pwd)/claude-plugin/skills/autoresearch ~/.claude/skills/autoresearch
ln -s $(pwd)/claude-plugin/commands/autoresearch ~/.claude/commands/autoresearch
ln -s $(pwd)/claude-plugin/commands/autoresearch.md ~/.claude/commands/autoresearch.md

When done developing, replace symlinks with stable copies:

rm ~/.claude/skills/autoresearch ~/.claude/commands/autoresearch ~/.claude/commands/autoresearch.md
cp -r claude-plugin/skills/autoresearch ~/.claude/skills/autoresearch
cp -r claude-plugin/commands/autoresearch ~/.claude/commands/autoresearch
cp claude-plugin/commands/autoresearch.md ~/.claude/commands/autoresearch.md

Repository Structure

autoresearch/
├── README.md                                      ← Project overview + quick start
├── .gitignore                                     ← Excludes local .claude/ state
├── .claude-plugin/
│   └── marketplace.json                           ← Plugin marketplace manifest (source: ./claude-plugin)
├── claude-plugin/                                 ← DISTRIBUTION — what users install
│   ├── .claude-plugin/
│   │   └── plugin.json                            ← Plugin metadata + version
│   ├── commands/
│   │   ├── autoresearch.md                        ← Main /autoresearch command
│   │   └── autoresearch/
│   │       ├── plan.md                            ← /autoresearch:plan registration
│   │       ├── security.md                        ← /autoresearch:security registration
│   │       ├── ship.md                            ← /autoresearch:ship registration
│   │       ├── debug.md                           ← /autoresearch:debug registration
│   │       ├── fix.md                             ← /autoresearch:fix registration
│   │       ├── scenario.md                        ← /autoresearch:scenario registration
│   │       ├── predict.md                         ← /autoresearch:predict registration
│   │       └── learn.md                           ← /autoresearch:learn registration
│   └── skills/
│       └── autoresearch/
│           ├── SKILL.md                           ← Main skill (loaded by Claude Code)
│           └── references/
│               ├── autonomous-loop-protocol.md    ← 8-phase loop protocol
│               ├── core-principles.md             ← 7 universal principles
│               ├── plan-workflow.md               ← Plan wizard protocol
│               ├── security-workflow.md           ← Security audit protocol
│               ├── ship-workflow.md               ← Ship workflow protocol
│               ├── debug-workflow.md              ← Debug loop protocol
│               ├── fix-workflow.md                ← Fix loop protocol
│               ├── scenario-workflow.md           ← Scenario exploration protocol
│               ├── predict-workflow.md            ← Multi-persona swarm prediction workflow
│               ├── learn-workflow.md              ← Learn/documentation engine protocol
│               └── results-logging.md             ← TSV tracking format
├── .claude/                                       ← LOCAL development (gitignored except autoresearch)
│   ├── commands/autoresearch/                     ← Dev copies of commands
│   └── skills/autoresearch/                       ← Dev copies of skills
├── guide/                                         ← Comprehensive guides — one per command
│   ├── README.md                                  ← Guide index
│   ├── getting-started.md                         ← Installation, core concepts, FAQ
│   ├── autoresearch.md                            ← The autonomous loop
│   ├── autoresearch-plan.md                       ← Setup wizard
│   ├── autoresearch-debug.md                      ← Bug hunter
│   ├── autoresearch-fix.md                        ← Error crusher
│   ├── autoresearch-security.md                   ← Security auditor
│   ├── autoresearch-ship.md                       ← Shipping workflow
│   ├── autoresearch-scenario.md                   ← Scenario explorer
│   ├── autoresearch-predict.md                    ← Multi-persona swarm prediction
│   ├── autoresearch-learn.md                      ← Documentation engine
│   ├── chains-and-combinations.md                 ← Multi-command pipelines
│   ├── examples-by-domain.md                      ← Real-world examples by domain
│   ├── advanced-patterns.md                       ← Guards, MCP, CI/CD, FAQ
│   └── scenario/                                  ← Scenario-specific guides
│       └── README.md                              ← Scenario guide index
├── COMPARISON.md                                  ← Feature comparison with alternatives
├── CONTRIBUTING.md                                ← You are here
├── LICENSE                                        ← MIT License
└── scripts/
    ├── release.sh                                 ← Release script (version bump + PR + tag)
    └── release.md                                 ← Release process documentation

What Each File Does

File Purpose Edit when...
SKILL.md Main entry point. Sub-command routing, setup phase, loop pseudocode, domain table. Adding sub-commands, changing activation triggers, updating loop behavior
references/autonomous-loop-protocol.md 8-phase loop protocol with rules for each phase. Changing how the loop works (review, ideate, modify, commit, verify, guard, decide, log)
references/core-principles.md 7 universal principles from Karpathy's autoresearch. Refining principles or adding new ones
references/plan-workflow.md /autoresearch:plan wizard protocol. Changing planning flow, question types, metric suggestions
references/security-workflow.md /autoresearch:security audit protocol. Adding OWASP checks, red-team personas, report structure
references/ship-workflow.md /autoresearch:ship shipping workflow. Adding ship types, checklists, rollback actions
references/debug-workflow.md /autoresearch:debug bug-hunting protocol. Adding investigation techniques, bug patterns, domain checklists
references/fix-workflow.md /autoresearch:fix error repair protocol. Adding fix strategies, anti-patterns, language-specific patterns
references/scenario-workflow.md /autoresearch:scenario scenario exploration. Adding domains, dimensions, output formats
references/predict-workflow.md /autoresearch:predict multi-persona swarm prediction workflow (751 lines). Adding prediction personas, confidence models, output formats
references/learn-workflow.md /autoresearch:learn documentation engine protocol. Adding doc types, validation checks, generation templates
references/results-logging.md TSV log format and reporting rules. Changing log columns, summary format, reporting intervals
claude-plugin/commands/autoresearch/*.md Sub-command registration files. Adding new sub-commands (creates the /autoresearch:name slash command)
claude-plugin/.claude-plugin/plugin.json Plugin metadata + version. Version bumps (use scripts/release.sh)
README.md Public overview, commands table, quick start. Adding features, updating commands, documenting changes
guide/*.md Individual command guides, examples, advanced patterns. Adding scenarios, command combinations, domain examples
guide/scenario/ Scenario-specific guides and domain examples. Adding scenario domains, edge case patterns
COMPARISON.md Feature comparison with alternatives. Updating subcommand count, adding new capabilities to comparison table

What to Contribute

High-Value Contributions

Type Examples Difficulty
New domain examples Add to guide/examples-by-domain.md Easy
Verification script templates Reusable scripts for common metrics Easy
Bug fixes Loop edge cases, incorrect behavior Medium
New sub-commands /autoresearch:refactor, /autoresearch:test Medium
New ship types Additional checklist types for /autoresearch:ship Medium
OWASP/STRIDE additions New security checks for /autoresearch:security Medium
New scenario domains Additional domain templates for /autoresearch:scenario Medium
Protocol improvements Better stuck-detection, smarter ideation Hard
MCP integration patterns Database, API, analytics verification examples Hard

Low-Value (Please Don't)

  • Reformatting or restructuring existing files without functional changes
  • Adding comments to explain obvious things
  • Changing naming conventions or style
  • Whitespace-only changes

Day-to-Day Workflow

# 1. Fork and clone
gh repo fork uditgoenka/autoresearch --clone
cd autoresearch

# 2. Create a feature branch
git checkout -b feat/your-feature-name

# 3. Symlink for live testing
ln -s $(pwd)/claude-plugin/skills/autoresearch ~/.claude/skills/autoresearch
ln -s $(pwd)/claude-plugin/commands/autoresearch ~/.claude/commands/autoresearch
ln -s $(pwd)/claude-plugin/commands/autoresearch.md ~/.claude/commands/autoresearch.md

# 4. Make your changes
# Edit skill files, reference files, commands, docs, etc.

# 5. Test in Claude Code (changes are live via symlink)
# Open Claude Code in any project and invoke the relevant command

# 6. Commit with conventional format
git add -A
git commit -m "feat: add guard rework timeout after 60 seconds"

# 7. Push and create PR
git push -u origin feat/your-feature-name
gh pr create --title "feat: your feature" --body "## Summary\n- What changed\n- Why"

Commit Messages

We use conventional commits:

Prefix When
feat: New feature or sub-command
fix: Bug fix in existing behavior
docs: Documentation-only changes
refactor: Restructuring without behavior change
chore: Maintenance (CI, config, tooling, version bumps)

Pull Request Guidelines

  1. One PR = one feature. Don't bundle unrelated changes.
  2. Branch from master. Target master as base.
  3. Descriptive title. Use conventional commit format.
  4. Write a good body. Explain what changed, why, and how to test it.
  5. Update docs. If you add a feature, update the relevant docs:
    • SKILL.md — register sub-commands, update activation triggers
    • README.md — commands table, quick decision guide, repo structure, FAQ
    • guide/ — add individual command guide or update existing ones
    • guide/scenario/ — update scenario guides if adding new domains or patterns
    • guide/examples-by-domain.md — add copy-paste examples for new features
    • COMPARISON.md — update subcommand count and feature comparison table
  6. Don't bump the version. Maintainers handle version bumps via scripts/release.sh.
  7. Keep files focused. Don't modify files unrelated to your change.

PR Template

## Summary
- What changed and why

## Files Changed
| File | Change |
|------|--------|
| `references/fix-workflow.md` | Added Rust-specific fix strategies |
| `EXAMPLES.md` | Added Rust examples section |

## How to Test
1. Symlink skill to ~/.claude/skills/autoresearch
2. Run /autoresearch:fix in a Rust project
3. Verify Rust-specific strategies are applied

Adding a New Sub-Command

Follow this pattern when adding a command like /autoresearch:yourcommand:

1. Create the reference file

claude-plugin/skills/autoresearch/references/your-workflow.md

Contains: full protocol, phases, rules, examples, flags, error recovery, composite metric, output directory structure.

2. Create the command registration file

claude-plugin/commands/autoresearch/yourcommand.md

This thin wrapper tells Claude Code to load SKILL.md + your reference file and execute the workflow.

3. Register in SKILL.md

Add to the subcommands table:

| `/autoresearch:yourcommand` | Description of what it does |

Add a full sub-command section with:

  • Load: references/your-workflow.md directive
  • Numbered phase summary
  • Usage examples with flags
  • Key behaviors and composite metric

Add to the "When to Activate" section:

- User invokes `/autoresearch:yourcommand` → run your workflow
- User says "relevant trigger phrases" → run your workflow

Add to the interactive setup gate table.

4. Update all docs

Doc What to Update
README.md Commands table, Quick Decision Guide, dedicated section, repo structure, FAQ
guide/ Individual command guide, chains-and-combinations, examples-by-domain, advanced-patterns
guide/scenario/ Scenario guide chain suggestions (if relevant to scenario workflows)
COMPARISON.md Update subcommand count and feature comparison table
CONTRIBUTING.md Repo structure tree, "What Each File Does" table

Testing Your Changes

No automated test suite — autoresearch is Markdown instructions, not code. Testing means using it:

  1. Symlink your working tree (see Quick Start)
  2. Open Claude Code in a real project
  3. Invoke the skill (/autoresearch, /autoresearch:plan, etc.)
  4. Verify behavior matches your changes
  5. Try edge cases — wrong metric? Scope matches 0 files? Guard always fails?

What to Check

  • Does Claude follow your updated instructions?
  • Does the output format match your specification?
  • Are error cases handled gracefully?
  • Does backward compatibility hold? (Existing commands still work)
  • Does the interactive setup ask the right questions?

Release Process

Maintainers use scripts/release.sh to handle releases. See scripts/release.md for full documentation.

# Patch release (bugfixes, docs updates)
./scripts/release.sh 1.7.1 --title "Fix scenario timeout"

# Minor release (new features, new commands)
./scripts/release.sh 1.7.0 --title "New Sub-Command Name"

The script: creates release branch → bumps plugin.json + README badge → pauses for doc review → commits → creates PR → waits for merge confirmation → tags → creates GitHub release.

Contributors don't need to bump versions — maintainers handle this during release.

Things to Know

  • No build step. Everything is Markdown. Edit → test → commit.
  • SKILL.md is the entry point. Claude Code reads this first. References are loaded on demand.
  • References are lazy-loaded. Only loaded when the relevant sub-command is invoked. Keeps context usage low.
  • claude-plugin/commands/ directory is required. Without it, sub-commands (/autoresearch:plan, etc.) won't register as slash commands.
  • Plugin system. Users can install via /plugin install — the .claude-plugin/marketplace.json at root points to ./claude-plugin as the distribution source.
  • The repo is MIT licensed. Your contributions will be under the same license.

Getting Help

  • Questions? Open an issue
  • Ideas? Open an issue with [Idea] prefix
  • Bug reports? Open an issue with reproduction steps
  • Discussion? Tag @uditgoenka in your PR

Thanks for contributing!