Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
71 lines (50 loc) · 3.75 KB

CONTRIBUTING.md

File metadata and controls

71 lines (50 loc) · 3.75 KB
Raw

Contributing to Trace2Skill

Thanks for considering a contribution. This is a pre-alpha research project, so expect rough edges, but we merge PRs that come with tests and match the existing design.

Quick start

git clone https://github.com/Hert4/trace2skill.git
cd trace2skill
pip install -e ".[dev]"

python -m pytest tests/unit -q    # should print "319 passed" (or current count)
ruff check .                       # should print "All checks passed!"
pyright --strict trace2skill       # should print "0 errors"

If any of those three fail on main, that's a bug — open an issue.

Development loop

  1. Branch from main.
  2. Write failing tests first when the change is behavioral. Mocks live in trace2skill/mocks/; use them to avoid hitting real APIs in unit tests.
  3. Make the code change. Keep source files compact — the reference adapters are ~200-280 LOC each including comments.
  4. Run the three checks above before pushing.
  5. Open a PR with a clear why in the description. Link the plan.md phase the work belongs to if applicable.

Conventions

  • Type hints everywhere. pyright --strict gates CI.
  • ruff check . clean. Line length 100, plus E F W I UP B SIM RUF rule families. Run ruff check --fix for auto-fixable lints.
  • No regex in trace2skill/signal/. Rubric + LLM judge. (Paper §2.5 and plan §13.7.)
  • Adapters do not classify. EvidenceAdapter extracts raw signals. The judge decides what they mean. (Plan §13.8.)
  • Tests run offline by default. Live/integration tests live under tests/integration/ and require explicit API keys — don't add them to the default suite.
  • Commit style. Follow the repo's existing commits: imperative subject line, blank, body explaining why. Feature commits prefixed feat:, fixes fix:, docs docs:, etc.

Adding a new adapter

The framework's design goal is "new adapter in <300 LOC." Reference implementations:

Axis Reference
HarnessAdapter trace2skill/harnesses/langchain.py (~200 LOC, lazy import pattern, unit-test-friendly _response_to_trajectory split)
EvidenceAdapter trace2skill/evidence_adapters/langchain.py (~280 LOC, LangSmith-backed, feedback API error-swallowing)
LLMProvider trace2skill/llm/openai_compatible.py (generic — 1 class covers 7+ providers via base_url)
SkillFormat trace2skill/skill_formats/anthropic.py (SKILL.md + resources/ with junk-dir filtering)

Typical new-adapter PR:

  1. Source file: trace2skill/<axis>/<name>.py. Use TYPE_CHECKING for heavy optional dependencies; lazy-import inside method bodies so the module stays importable when the extra isn't installed.
  2. Register in the axis's __init__.py.
  3. Add [<name>] to pyproject.toml's [project.optional-dependencies] if the adapter needs a new SDK.
  4. Tests: tests/unit/test_<name>_<axis>.py. Mock the external SDK (unittest.mock.MagicMock / AsyncMock + patch). Target 10+ tests covering happy path, error paths, protocol conformance via isinstance(obj, HarnessAdapter) etc.
  5. Example (optional): examples/<N>_<name>_<flavor>/ with a README.md, trace2skill.yaml, seed skill, a few tasks, and an evaluator.

Deferred items / good first issues

See plan.md "Deferred checklist" and "Phase 5 remaining." Good starter tickets:

  • ClineHarnessAdapter + ClineSkillFormat (.clinerules)
  • OpenCodeHarnessAdapter
  • Rubric YAMLs: code_editing_agent, qa_agent, search_agent, spreadsheet_agent
  • ast-grep lint rule banning regex inside trace2skill/signal/
  • examples/04_langchain_rag_agent/ demo

Questions

Open a GitHub issue. For design discussions, label with design and the relevant phase.

License

By contributing, you agree your contributions are licensed under the MIT license (same as the repo).