From cocosearch
Guides placement and integration of new commands, endpoints, modules, handlers, or capabilities using CocoSearch semantic search for existing patterns.
npx claudepluginhub violetcranberry/coco-search --plugin cocosearchThis skill uses the workspace's default tool permissions.
A systematic workflow for adding new code to an existing codebase. This skill uses semantic search to find existing patterns, conventions, and integration points so the new feature fits naturally into the project architecture.
Guides onboarding to new or unfamiliar codebases by checking CocoSearch index, exploring architecture, key modules, and code patterns via semantic search.
Performs semantic code search across the codebase using ccc CLI, manages initialization, indexing freshness, path/language filtering, and pagination.
Enables semantic codebase search with natural language queries, project indexing for remote retrieval, and AI prompt enhancement via standalone Python CLI. Use for large codebases, before grep/find, and requirement clarification.
Share bugs, ideas, or general feedback.
A systematic workflow for adding new code to an existing codebase. This skill uses semantic search to find existing patterns, conventions, and integration points so the new feature fits naturally into the project architecture.
Philosophy: New code should look like it was always there. Search the codebase for existing patterns before writing anything.
cocosearch.yaml for indexName field -- if found, use itlist_indexes() and match the current project's directory name against available indexes. The MCP tools auto-derive index names from directory paths (e.g., my-project/ -> my_project), so a match is likely if the repo was indexed without a config file.cocosearch.yaml is missing.list_indexes() to confirm project is indexedindex_stats(index_name="<resolved-name>") to check freshnesscocosearch.yaml has linkedIndexes):
warnings array from index_stats() for entries starting with "Linked index"Parse the user's request to identify what needs to be built and where it fits.
Extract from the request:
Classify the feature type:
Confirm with user: "I understand you want to add [feature]. It fits as a [type] in the [subsystem] layer. Is that right?"
This is the most important step. Search for how similar things are already built. New code should follow established conventions.
Every feature has a precedent. Search for the most similar existing implementation.
Semantic search for similar functionality:
search_code(
query="<description of what the feature does>",
use_hybrid_search=True,
smart_context=True,
limit=10
)
Cross-project search: If
linkedIndexesis configured incocosearch.yaml, searches automatically expand to linked indexes. For ad-hoc multi-project pattern discovery, passindex_names=["project1", "project2"].
Search for the subsystem's existing entry points:
search_code(
query="<subsystem> command handler endpoint",
symbol_type=["function", "class"],
use_hybrid_search=True,
smart_context=True
)
Find the registration/wiring pattern:
How are existing features registered? Search for the glue code:
search_code(
query="register add route subcommand handler",
use_hybrid_search=True,
smart_context=True,
limit=10
)
Present the analog: "The closest existing feature to what you want is [analog] in file:line. Here's how it's structured: [brief description]. I'll use this as the template."
From the analog and broader search, identify the project's conventions:
File placement — where does new code go?
search_code(
query="<subsystem-name>",
symbol_type="class",
use_hybrid_search=True,
limit=15
)
Look at the file paths in results. Is there a clear directory structure? (e.g., handlers/*.py, commands/*.py, routes/*.py)
Naming conventions — what do things get called?
search_code(
query="<similar-feature-type>",
symbol_name="*<pattern>*",
use_hybrid_search=True
)
Look for naming patterns: cmd_*, handle_*, test_*, *Handler, *Service.
Interface patterns — how are features exposed?
search_code(
query="<interface-type> definition",
use_hybrid_search=True,
smart_context=True
)
Look for: argument parsing patterns, decorator usage, protocol/interface definitions, configuration patterns.
Testing patterns — how are similar features tested?
search_code(
query="test <analog-feature>",
symbol_name="test_*<analog>*",
symbol_type="function",
use_hybrid_search=True
)
Identify: test file location, fixture usage, mocking patterns, assertion style.
Present conventions:
Conventions for [subsystem]:
- Files go in: src/<module>/<subsystem>/
- Naming: <verb>_<noun> for functions, <Noun><Role> for classes
- Registration: via <mechanism> in <file>
- Tests go in: tests/unit/<subsystem>/test_<feature>.py
- Test pattern: [mock X, call Y, assert Z]
Find where the new feature needs to connect to existing code.
Find imports/dependencies the feature will need:
search_code(
query="<analog-feature> import dependency",
use_hybrid_search=True,
smart_context=True
)
Find where the feature needs to be registered/wired:
search_code(
query="<registration-mechanism>",
symbol_name="<registration-function>*",
use_hybrid_search=True,
smart_context=True
)
Find shared utilities or helpers the feature should reuse:
search_code(
query="<operation the feature needs> utility helper",
use_hybrid_search=True,
limit=10
)
Present integration points:
Integration points:
1. Register in: <file>:<line> (add to <mechanism>)
2. Import from: <module> (for <dependency>)
3. Reuse: <utility> from <file> (don't reinvent)
4. Expose via: <interface> in <file>
Using the patterns, conventions, and integration points found, produce a concrete implementation plan.
Plan structure:
Feature: [name]
Analog: [closest existing feature] in [file]
New files:
- src/<path>/<feature>.py — [purpose]
- tests/unit/<path>/test_<feature>.py — [what it tests]
Modified files:
- <file> — [what changes: add import, register command, wire route]
- <file> — [what changes]
Implementation order:
1. Create <new-file> with <core-logic> (modeled on <analog>)
2. Add tests in <test-file> (modeled on <analog-tests>)
3. Wire into <registration-file>
4. Update <config/docs> if needed
Key decisions:
- [Decision 1: e.g., "Use existing FooService rather than creating new one"]
- [Decision 2: e.g., "Follow handler autodiscovery pattern — no manual registration needed"]
Present to user: "Here's the plan based on existing patterns. Ready to implement, or want to adjust?"
Handle adjustments: If user wants changes, update the plan and re-present.
For each step in the plan, implement by closely following the analog.
For each file to create/modify:
Show the analog code:
search_code(
query="<analog-function>",
symbol_name="<analog-function>",
use_hybrid_search=True,
smart_context=True
)
"Here's the existing pattern I'm following from <analog-file>:"
Write the new code modeled on the analog. Match:
Show the change and request confirmation:
New file: <path>
Based on: <analog-file>
[code]
Proceed? (yes/no/adjust)
After creating the core code, write tests:
Wire the feature in:
After all code is written, verify the feature integrates correctly.
Run the tests:
[project-specific test command for the new test file]
Check for import/lint issues:
[project-specific lint command]
Verify registration:
If the feature should appear in help text, command lists, or API docs, check that it does.
Present results:
Feature implementation complete!
Created:
- <new-file-1> — [description]
- <new-file-2> — [description]
Modified:
- <file> — [what changed]
Tests: [PASS/FAIL]
Lint: [PASS/FAIL]
Based on patterns from: <analog-feature>
Recommended next steps:
1. Try it out: [example usage command]
2. Run full test suite: [command]
3. Commit: git add <files> && git commit -m "feat: <description>"
If tests fail:
Pattern-first development. Always find the analog before writing code. The codebase IS the specification for how new code should look.
Reuse, don't reinvent. Before creating any utility, helper, or abstraction, search for existing ones. Duplicating functionality creates maintenance burden.
Match conventions exactly. If existing functions use snake_case, don't introduce camelCase. Consistency matters more than personal preference.
Test analog first. Find how the closest feature is tested before writing your own tests. Match the coverage level, fixture pattern, and assertion style.
Wire last. Create the core code and tests first. Registration and wiring are the final step.
For common search tips (hybrid search, smart_context, symbol filtering), see skills/README.md.
For installation instructions, see skills/README.md.