codebase-sync
npx machina-cli add skill a5c-ai/babysitter/codebase-sync --openclawcodebase-sync
You are codebase-sync -- the convention discovery and rule generation skill for Pilot Shell.
Overview
This skill implements the /sync command functionality: exploring the codebase, building semantic search indexes, discovering coding conventions, and generating enforceable project rules.
Capabilities
1. Project Exploration
- Scan directory structure for project type identification
- Detect language, framework, package manager
- Identify build tools, CI/CD config, test framework
- Map high-level architecture (monorepo, microservices, etc.)
2. Semantic Index Building
Four parallel index domains:
- Code Index: Source files with exports, purposes, dependencies
- Test Index: Test files with cases, fixtures, patterns
- Config Index: Configuration files with parsed rules
- API Index: Public interfaces, types, data models
3. Convention Discovery
- Code style patterns (naming, structure, organization)
- Error handling conventions
- Testing conventions (naming, structure, assertions)
- Git commit message conventions
- Documentation standards
- Language-conditional standards
4. Rule Generation
Convert conventions into enforceable rules:
{
"id": "ts-no-any",
"category": "coding-standards",
"description": "Avoid 'any' type; use 'unknown' and narrow",
"severity": "error",
"autoFixable": false,
"language": "typescript"
}
Rule Categories
| Category | Examples |
|---|---|
| core | task-and-workflow, testing, verification |
| dev-practices | development-practices, context-management |
| tools | research-tools, cli-tools |
| coding-standards | Language-specific rules (conditional) |
Output Artifacts
artifacts/CONVENTIONS.md-- Discovered conventionsartifacts/SEARCH-INDEX.json-- Semantic search indexartifacts/RULES.md-- Generated project rules
Source
git clone https://github.com/a5c-ai/babysitter/blob/main/plugins/babysitter/skills/babysit/process/methodologies/pilot-shell/skills/codebase-sync/SKILL.mdView on GitHub Overview
codebase-sync explores a repository to identify language, framework, and project structure, then builds semantic search indexes across code, tests, config, and APIs. It discovers coding conventions and converts them into enforceable project rules, outputting artifacts that guide consistency and automation.
How This Skill Works
The skill scans the directory structure to identify project type, language, framework, and tooling. It builds four parallel indexes (Code, Test, Config, API) to capture exports, tests, rules, and interfaces, then derives conventions like code style and commit messaging. It converts these conventions into actionable rules, exemplified by a JSON rule snippet, and emits artifacts such as CONVENTIONS.md, SEARCH-INDEX.json, and RULES.md.
When to Use It
- Onboarding a new codebase to establish conventions and baseline rules
- Auditing an existing project to standardize coding styles, tests, and docs
- Enforcing CI/CD, commit message, and documentation conventions across the repo
- Managing monorepos or multi-language projects requiring cross-cut conventions
- Preparing rules for linting/static analysis and automated enforcement
Quick Start
- Step 1: Run the /sync command from the project root to begin analysis
- Step 2: Inspect artifacts/CONVENTIONS.md, artifacts/SEARCH-INDEX.json, and artifacts/RULES.md
- Step 3: Integrate RULES.md into your CI or lint tooling and enforce via code reviews
Best Practices
- Run /sync regularly to keep conventions and rules aligned with code changes
- Review and validate generated RULES.md against real-world code paths before enforcement
- Keep artifacts/ up-to-date with incremental scans and changelog notes
- Align discovered conventions with language-conditional standards and project guidelines
- Version-control the generated conventions and rules and document any deviations
Example Use Cases
- Scanned a monorepo and identified shared coding conventions across packages, producing a unified SEARCH-INDEX.json
- Discovered naming and structure patterns in code and tests, generating corresponding rules in RULES.md
- Detected commit message conventions and integrated them into a repo-wide standard
- Generated a concrete rule example (ts-no-any) to enforce TypeScript typing discipline
- Produced artifacts/CONVENTIONS.md outlining discovered standards and usage guidance
