Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
75 lines (52 loc) · 3.84 KB

CONTRIBUTING.md

File metadata and controls

75 lines (52 loc) · 3.84 KB
Raw

Contributing to ForgeWorks

Thanks for considering a contribution! ForgeWorks is two projects in one — loop-engine (a product) and skillforge (a framework). This guide covers both.

Project status & scope

Before contributing, read the README "What's production-ready vs reference implementation" section. Be explicit in PRs about whether your change touches real code paths or reference/placeholder implementations — do not silently upgrade a placeholder to look production-grade without the real logic.

Prerequisites

  • Python 3.10+
  • Git, bash (skill scripts use bash)
  • pip install pyyaml pytest (loop-engine); optional anthropic / openai per your agent_models provider config

Setup

git clone <repo-url> forgeworks
cd forgeworks/loop-engine
pip install -r requirements.txt

# smoke: dry_run needs no API key
python run.py src/sample/

# tests
python -m pytest tests/ -q

Development workflow

  1. Fork & branch from main. Use a descriptive branch name: fix/loop-memory-dedup, feat/skill-tdd, docs/agent-guide.
  2. Run tests before and after changes: 
    cd loop-engine && python -m pytest tests/ -q
  3. Add a test for any new pure-logic behavior (parsing, gates, fallback classification, dedup). Real-LLM behavior goes in experiment/ as a runnable script, not a unit test.
  4. Keep changes minimal and surgical — match surrounding style, comment density, and naming.
  5. Do not hardcode models or secrets. Model config belongs in config/qa-loop.yaml agent_models with ${VAR} env refs; never commit API keys.
  6. Open a PR against main with the PR template filled out.

Conventions (Convention-over-Configuration)

ForgeWorks uses file-location-as-registration. Respect these layouts:

  • Agent = agents/<name>.md (loop-engine) or plugins/<plugin>/agents/<name>.md (skillforge): YAML frontmatter (name, description, model, tools) + Markdown body = system prompt. The description is the trigger engine; <example> blocks are few-shot routing samples.
  • Skill = skills/<name>/SKILL.md + optional references/, examples/, scripts/. Scripts execute without entering the context window (stdout only).
  • Hook = hooks.json using the 9-event format (UserPromptSubmit / PreToolUse / PostToolUse / Stop / PreCompact / ...), with matcher + optional if: Tool(param:value) filtering.

When adding any of these, no build step and no registration API call is needed — placing the file in the right directory is enough.

Commit & PR style

  • Commit messages: imperative, short subject + body explaining why. End with Co-Authored-By: only if relevant.
  • PR title: type: summary (e.g. fix: cross-session memory skipped known-fixed findings).
  • Fill the PR template: what changed, real vs reference path, tests added, dry_run still exits 0.

What we welcome

  • ✅ New skills or agents (Markdown-driven — low risk, high value)
  • ✅ Tests for existing logic
  • ✅ Bug fixes with a failing-test-first approach
  • ✅ Docs improvements and examples
  • ✅ Cross-platform adapters (Cursor .mdc / Codex AGENTS.md / opencode)
  • ⚠️ Upgrading a placeholder to a real implementation (e.g. prompt-hook LLM wiring, semantic compaction) — please open an issue first to align on approach

What we won't accept

  • ❌ Hardcoded API keys or model IDs baked into code
  • ❌ Auto-merge / auto-commit / auto-push behavior (ForgeWorks is assist, not replace)
  • ❌ Removing the silent-fallback-to-zero-dependency contract of loop-engine (it must stay runnable without skillforge installed)
  • ❌ Changes that widen permissions by default (default-deny, explicit-allow is a core principle)

Reporting issues

Use the issue templates. For security issues, see SECURITY.md — do not open a public issue for vulnerabilities.