Pick a small knot to untangle.
Describe the question someone should be able to answer after your change. Choose one supported project shape and build a tiny fixture that demonstrates it. Include a case where Codeclew should return a limit or no match.
A good first slice
“Find methods carrying this scheduling annotation and show their exact source.” One annotation, one language, one project fixture.
A clear boundary
“The annotation declares a schedule. We have not established that it is active in a running deployment.” Keep that distinction in the output.
This guide describes contributions to Codeclew's source. Build providers and language adapters are internal interfaces; there is currently no public drop-in plugin loader. Use ./clew from your checkout for source development and the installed clew for a packaged release.
Where does your capability fit?
A build system
Implement BuildModelProvider: report a handshake, probe a project, extract its compilation model and support shutdown. Describe source roots, dependencies, toolchain and options with explicit completeness.
A language or analyzer
Implement LanguageAdapter: handshake, analyze a generation, cancel and shut down. Emit FactShard events and an AttemptComplete event carrying the completeness receipt.
A framework rule
Extract language facts first, then interpret framework meaning in a separate layer. Preserve annotation identity, attributes and source. Unresolved configuration stays visible.
A CLI or agent workflow
Add the command and route it to the owning service. Return a bounded response with stable fields and useful next actions. Teach the bundled skill how to use it.
A report or documentation view
Build on retained facts, source references and freshness results. Keep the view readable offline where the existing output contract requires it, and preserve the meaning of evidence labels.
A compiler version
Follow the existing worker and engine structure. Keep project and analyzer versions distinct; add compatibility fixtures for the supported combination. Update runtime manifests when worker artifacts change.
Adding an adapter to AdapterRegistry is one integration step. A new language also needs project discovery, session selection and generation dispatch. Follow the nearest existing language through session.rs and generation_service.rs so the public command can actually reach it.
Define what the result means.
- Inputs: choose the language, target, toolchain and source snapshot. State what is excluded, including generated code or additional compilations when relevant.
- Facts: define the returned identity, payload and source range. Use the existing snapshot and content-addressed storage APIs to bind facts to the source that produced them.
- Strength: state whether a result is compiler-resolved, observed syntax or a derived interpretation. A syntactic call name is not a resolved call edge.
- Limits: report unsupported constructs, ambiguity, missing inputs, truncation and cancellation. A partial result must not appear complete.
- Compatibility: version affected schemas and translation identities when their meaning changes. Update validators, producers and consumers together so old facts cannot be reused under new assumptions.
Add support for a scheduling annotation.
Suppose a framework has an annotation that Codeclew does not yet recognize. The intended result is a catalogue entry with a method identity, schedule attributes and source location. This is a proposed implementation path, not an existing capability.
- Capture the cases. Create a tiny project with one annotated method, an unrelated annotation with the same short name, and a schedule value that depends on configuration.
- Extract the identity. Extend the relevant compiler adapter or worker to retain the resolved annotation and its attributes. If resolution is unavailable, preserve that boundary instead of matching by short name.
- Interpret the declaration. Add the framework rule and its payload validation. Retain the method's source anchor and the unresolved schedule expression. Do not label it as an observed running job.
- Carry it to the reader. Update the catalogue consumer and any affected CLI or report schema. Make sure a reader can open the exact declaration and see the configuration limit.
- Prove the result. Assert that the supported method appears, the namesake does not, and the dynamic value remains conditional. Exercise the public CLI on the fixture and inspect the rendered source link.
The existing Spring path is a useful reference: compiler extraction tests → metadata validation and catalogue → CLI smoke example.
Follow the new path all the way through.
Use the pinned Rust toolchain, Python 3.11+, JDK 21 and the repository Gradle wrapper as needed. The README and contributor instructions describe the checkout's current requirements.
# Inspect capabilities through the source launcher
./clew capabilities --human
# Example: focused checks for an adapter change
cargo fmt --all --check
cargo test --locked -p clew --lib 'adapter_v2::tests::' -- --test-threads=1
# Full development gate when the code change is ready
./scripts/ci-verify.shChoose additional checks for your implementation. Compiler-worker changes require the affected Gradle worker tests; Rust tests alone do not verify compiler extraction. Add a focused managed_cli test for a new public command. Run the corresponding scripts/test_*.py suite for Python tooling.
Test useful output, unsupported input and the failure paths you changed. For retained evidence, check source ranges, bounded output and behavior after source changes. If you change the bundled skill, run python3 -I -S scripts/test_agent_skill.py. Documentation-only contributions need syntax/link checks and python3 -I -S scripts/check_english_content.py, without rebuilding the runtime.
Bring the capability and its proof.
Include a before/after example, the fixture, relevant test results and the supported scope in your contribution. Update capability reporting and the support matrix when behavior changes. Keep the README and user-facing guide consistent with what is actually available.
When changing the skill, edit skills/codeclew and keep its .agents/skills/codeclew and .claude/skills/codeclew copies identical. Run python3 -I -S scripts/check_repository_privacy.py --pre-commit before publication. Add packaging or release checks when your change affects the installed runtime.