Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
156 lines (110 loc) · 4.77 KB

CONTRIBUTING.md

File metadata and controls

156 lines (110 loc) · 4.77 KB
Raw

Contributing to Wizard-AI

Thank you for your interest in contributing to Wizard-AI! This document explains how to add new skills, CLI wrappers, and improvements to the ecosystem.

🇮🇹 Leggi questo documento in Italiano

📋 Project Structure

wizard-ai/
├── .agents/      # IDE configs (.claude, .cursor) and autonomous workflows
├── bin/          # CLI wrapper scripts installed to ~/.local/bin/
├── docs/         # Reference guides, architecture specs, and wikis
├── packages/     # Standalone projects, frameworks, and tools
├── skills/       # SKILL.md definitions for AI agents
├── setup.sh      # Automated installation script
└── README.md     # Main documentation

📂 Repository Architecture Standards

To maintain a clean and sustainable ecosystem, all new installations, skills, and tools must adhere to strict boundaries:

  1. .agents/: MUST contain all IDE-specific configurations (.claude, .cursor, .pi, etc.) and autonomous agent workflows. Do NOT place agent configs at the root.
  2. docs/: Central knowledge base (wiki/, repo-docs/, graphify-out/). See Architecture Specs for full details.
  3. packages/: Standalone projects, npm modules, frameworks, and external tools (e.g., an MCP server, a React app). Do NOT initialize generic package.json projects at the root.
  4. .cache/: Temporary files, raw data dumps, and cloned repositories (.local-clones/).
  5. skills/: Strictly reserved for SKILL.md definitions and their immediately related scripts/assets.
  6. Root Directory: Must remain pristine. Only global configs (setup.sh, AGENTS.md, README.md).

🔧 Adding a New Skill

1. Create the CLI wrapper in bin/

# Example: bin/ai-newtool
#!/usr/bin/env bash
# ai-newtool — Short description
# Source: https://github.com/author/repo

set -euo pipefail

# Check prerequisites
if ! command -v newtool &>/dev/null; then
  echo "❌ newtool not found."
  echo "   Install: uv tool install newtool"
  exit 1
fi

exec newtool "$@"

2. Create the skills/skill-name/SKILL.md file

The skill MUST have YAML frontmatter:

---
name: skill-name
description: "Concise description explaining WHEN to use this skill"
---

# /skill-name

Detailed description...

## Usage
...

## Examples
...

Important rules for skills:

  • ❌ DO NOT hardcode absolute paths — use $WIZARD_AI_DIR, $HOME, ~
  • ❌ DO NOT include API keys or secrets of any kind
  • ✅ Document both the base command and the ai-* wrapper
  • ✅ Include practical examples

3. Update setup.sh

Add the installation in the appropriate block:

# For Python tools:
uv tool install packagename

# For GitHub repositories:
if [ ! -d "$HOME/.wizard-ai/repo-name" ]; then
  git clone --quiet https://github.com/author/repo "$HOME/.wizard-ai/repo-name"
fi

4. Update bin/ai-help

Add a line in the appropriate section of the help menu.

5. Sync

ai-sync-skills

📝 Code Style

  • Bash scripts: use set -euo pipefail at the top
  • Error messages: write to stderr (>&2)
  • Icons: ✅ success, ❌ error, ⚠️ warning, 🔄 in progress
  • Comments: describe the "why", not the "what"

🐛 Reporting Bugs

Open a GitHub Issue including:

  1. Output of the failing command
  2. Output of ai-help (to see what's installed)
  3. Operating system and architecture (uname -a)

🚀 Pull Requests & Branching Strategy

This project uses a dual-mode workflow depending on your role.

🟢 Repo Owners & Collaborators

If you have push access to the repository:

  1. Run ai-branch scan to detect your role.
  2. Create a branch: ai-branch feature "my feature"
  3. Make your changes and commit.
  4. Run ai-branch pr --auto-merge. This runs quality checks, creates a PR, and auto-merges it into staging once CI passes.
  5. Run ai-release promote --auto to promote staging to main.
  6. Run ai-release minor to publish the official release.

🟡 External Contributors

If you are contributing from a fork:

  1. Fork the repository and clone your fork locally.
  2. Run ai-branch scan. It will detect that you are EXTERNAL and your target dev branch is staging.
  3. Create a branch: ai-branch feature "my feature"
  4. Make your changes, test with bash -n setup.sh and grep -r "/home/" skills/ bin/.
  5. Run ai-branch pr --target staging.
  6. Wait for review. The maintainer will review your code, run the CI checks, and if everything is correct, they will merge your PR into staging and handle the release.

⚖️ License

By contributing, you agree that your code will be released under the AGPLv3 License. You retain the original copyright to the code you wrote in any case.