SKILL.md

name

protocol-knowledge

description

Use this skill when a coding agent needs version-pinned dependency semantics from Maven artifacts and must inspect protocol or adjacent library sources without guessing from namespace, README prose, or latest repository state. Trigger for work involving `pom.xml`, `.thrift`, `.proto`, protocol methods, fields, enums, RPCs, callbacks, lifecycle semantics, transport contracts, or library integration points tied to dependency behavior.

Protocol Knowledge

Overview

Resolve the exact artifact version from the consumer project, query that pinned artifact, and verify behavior against canonical source before making claims or code changes. This skill is for source-grounded protocol navigation, not for latest-based lookup or prose-driven inference.

If protocol-knowledge is not installed as a global CLI in the current environment, run the repo-local entrypoint instead:

npm run dev -- <protocol-knowledge-subcommand> ...

Mode

• Work from the consumer project's pinned dependency version.
• Prefer pom.xml evidence over package-name or namespace guesses.
• Prefer raw .thrift or .proto as semantic truth when available.
• Treat retrieval as navigation, not final truth.
• Open returned canonical source before asserting behavior, field shape, callback semantics, or lifecycle rules.
• If local prose disagrees with canonical source, treat the prose as commentary only.

Workflow

1. Inspect the consumer manifest

1. Start with:

   protocol-knowledge inspect-project --pom pom.xml --all-dependencies --json

   Repo-local fallback:

   npm run dev -- inspect-project --pom pom.xml --all-dependencies --json

2. If direct dependencies do not explain the symbol, package, or import you are tracing, rerun with the effective Maven tree:

   protocol-knowledge inspect-project --pom pom.xml --all-dependencies --transitive --json

   Repo-local fallback:

   npm run dev -- inspect-project --pom pom.xml --all-dependencies --transitive --json

3. Use local implementation files as implementation context only.

4. Use local README or notes only as repository context, never as protocol truth.

2. Select the pinned artifact

1. Identify the relevant dependency from the manifest or transitive tree.
2. If artifact selection by --artifact is ambiguous, use --gav.
3. Do not infer the owning artifact from package or namespace alone; one artifact can expose multiple namespaces or protocol files.

3. Query the exact artifact

1. Query through the consumer project when artifact selection is clear:

   protocol-knowledge query --pom pom.xml --artifact <artifactId> --q "<ExactSymbol> lifecycle semantics" --json

   Repo-local fallback:

   npm run dev -- query --pom pom.xml --artifact <artifactId> --q "<ExactSymbol> lifecycle semantics" --json

2. If the artifact is only reachable through transitive dependencies, include --transitive:

   protocol-knowledge query --pom pom.xml --artifact <artifactId> --q "<ExactSymbol>" --transitive --json

   Repo-local fallback:

   npm run dev -- query --pom pom.xml --artifact <artifactId> --q "<ExactSymbol>" --transitive --json

3. If coordinates are already known or selection is ambiguous, query directly:

   protocol-knowledge query --gav <groupId:artifactId:version> --q "<ExactSymbol>" --json

   Repo-local fallback:

   npm run dev -- query --gav <groupId:artifactId:version> --q "<ExactSymbol>" --json

4. If you want an explicit prefetch and index-build step first, run:

   protocol-knowledge ensure-artifact --gav <groupId:artifactId:version> --json

   Repo-local fallback:

   npm run dev -- ensure-artifact --gav <groupId:artifactId:version> --json

4. Interpret the result

1. Treat the top hit as a starting point, not final truth.
2. Use:
   • artifact_key to confirm the exact pinned artifact version;
   • match_mode to understand exact, FTS/BM25, or hybrid retrieval;
   • kind to distinguish whether the hit is a service, RPC, message, field, enum, enum value, oneof, or adjacent library symbol;
   • symbol, symbol_path, and qualified_symbol to decide what to open next;
   • file_path, start_line, and end_line to open the canonical source location;
   • comments as useful local contract context, while still treating the source definition as authoritative;
   • related_symbols for immediate expansion candidates;
   • score as ranking signal only, not correctness proof.

5. Verify against source

1. Open the returned canonical source files.
2. Reconcile protocol semantics with the local implementation before editing code.
3. For current repository behavior, local implementation code wins.
4. For protocol contract semantics, canonical protocol source wins.

Query Guidance

• Prefer exact symbol names when known.
• Add behavior terms that narrow the question to contract semantics or library intent.
• Good shapes:
  • <ExactMethodOrRpcName> lifecycle semantics
  • <ExactTypeName> validation rules
  • <LibraryClassOrFunctionName> integration flow
• Weak shapes:
  • payment flow
  • callbacks
  • how does it work

Guardrails

• Do not query latest.
• Do not treat unnamed repository state as the source of truth.
• Do not trust retrieval results without opening source.
• Do not use local README as protocol truth.
• Do not use generated Java as the preferred semantic source when raw IDL is available.
• Do not expand scope to unrelated artifacts when --artifact selection is ambiguous; switch to --gav.

Output Contract

When this skill materially informs an answer or code change, make the reasoning traceable:

• identify which pinned artifact version was used;
• state whether the artifact came from direct or transitive dependency inspection;
• mention whether the result path was exact, FTS/BM25, or hybrid when that matters;
• cite the canonical source files inspected before making behavioral claims;
• distinguish protocol truth from local implementation behavior when they are different concerns.