erode-app/erode / .agents/skills/doc-sync
doc-sync
VerifiedDetect documentation and architecture-model drift by comparing source-of-truth code (CLI commands, flags, env vars, GH Action inputs/outputs, package structure, pipeline stages, providers, adapters, platforms) against web docs, README, and LikeC4 architecture model (.c4 files). Use when files that define the user-facing interface or internal structure change, when the user asks to check docs, or when mentioning doc drift, architecture drift, stale docs, or documentation sync.
Documentation Sync
Detect discrepancies between code (source of truth) and documentation by extracting the user-facing interface from code and comparing it against docs.
When to Activate
Suggest running this skill when you detect changes to any of these files (staged, unstaged, or in recent commits):
CLI interface
packages/cli/src/commands/analyze.tspackages/cli/src/commands/check.tspackages/cli/src/commands/validate.tspackages/cli/src/commands/components.tspackages/cli/src/commands/connections.tspackages/cli/src/utils/command-schemas.ts
CI entry & GitHub Action
packages/core/src/ci-entry.tsaction.yml
Environment variables & config
packages/core/src/utils/config.ts
Public API & output
packages/core/src/index.tspackages/core/src/output.tspackages/core/src/output/structured-output.tspackages/core/src/output/ci-output.tspackages/core/src/schemas/*.schema.ts
Architecture model (.c4 files)
packages/architecture/model.c4packages/architecture/core.c4packages/architecture/externals.c4
Code mapped by the architecture model
package.json(workspace packages list)packages/core/src/pipelines/analyze.tspackages/core/src/providers/provider-factory.tspackages/core/src/providers/ai-provider.tspackages/core/src/providers/anthropic/provider.tspackages/core/src/providers/gemini/provider.tspackages/core/src/adapters/adapter-factory.tspackages/core/src/adapters/architecture-adapter.tspackages/core/src/adapters/likec4/adapter.tspackages/core/src/platforms/platform-factory.tspackages/core/src/platforms/source-platform.tspackages/core/src/platforms/github/reader.tspackages/core/src/platforms/gitlab/reader.tspackages/core/src/analysis/prompt-builder.tspackages/core/src/output/structured-output.tspackages/core/src/index.ts
When any of these appear in changes, say:
Source-of-truth files changed. Want me to run doc-sync to check for documentation and architecture drift?
Documentation Targets
| Doc file | What it documents |
|---|---|
packages/web/src/content/docs/docs/guides/cli-usage.md | CLI commands, arguments, flags |
packages/web/src/content/docs/docs/guides/claude-code.md | Claude Code skill setup and hook configuration |
packages/web/src/content/docs/docs/guides/configuration.md | Environment variables, defaults |
packages/web/src/content/docs/docs/ci/github-actions.md | GH Action inputs, outputs, CI setup |
packages/web/src/content/docs/docs/getting-started.md | Quick-start examples |
packages/web/src/content/docs/docs/how-it-works.md | Pipeline stages overview |
packages/web/src/content/docs/docs/reference/ai-providers.md | Provider names, default models, timeouts |
packages/web/src/content/docs/docs/reference/analysis-pipeline.md | Stage details |
packages/web/src/content/docs/docs/models/likec4.md | Model format, repository links |
packages/architecture/model.c4 | Workspace packages, inter-package dependencies |
packages/architecture/core.c4 | Core internals: pipeline stages, providers, adapters, platforms, modules, dependency arrows |
packages/architecture/externals.c4 | External APIs and libraries (Anthropic, Gemini, GitHub, GitLab, LikeC4) |
README.md | Commands, flags, env vars, examples |
packages/core/schemas/eroderc.schema.json | Generated JSON Schema from ConfigSchema; must match packages/core/src/utils/config.ts |
Workflow
Step 1: Extract from Code
1a. CLI Commands & Flags
Read each command file in packages/cli/src/commands/ and extract:
- Command name (from
new Command('name')) - Description (from
.description()) - Arguments (from
.argument()— name, description, required/optional) - Options (from
.option()and.requiredOption()— flag, description, default, required)
Note: connections uses --output for format selection, not --format like other commands.
Cross-check with Zod schemas in packages/cli/src/utils/command-schemas.ts — defaults there take precedence.
Read packages/core/src/ci-entry.ts to extract the erode-ci binary's flags (getFlag/hasFlag calls).
1b. GitHub Action Interface
Read action.yml in the repo root and extract all inputs (name, description, required, default) and outputs (name, description).
Read packages/core/src/output/ci-output.ts to verify the output names written to GITHUB_OUTPUT match action.yml outputs.
1c. Environment Variables
Read packages/core/src/utils/config.ts and extract:
- Every key in
ENV_MAPPINGS— these are the env var names - The config path each maps to
- The default value from
ConfigSchema(.default()calls) - Zod constraints (
.min(),.max(),.enum())
1d. Structured Output
Read packages/core/src/output/structured-output.ts for StructuredAnalysisOutput fields. Note: status has four values: success, violations, error, skipped.
1e. Architecture Model Elements
Read each .c4 file and extract:
- From
model.c4: everypackageelement (id, name, description, technology), inter-package relationship arrows - From
core.c4: every element insideextend erode.core— pipeline stages (id, name, description, tags like#fast-model/#advanced-model/#optional), provider/adapter/platform/module elements, and all relationship arrows (source → target, label) - From
externals.c4: everyexternalelement (id, name, description, technology, link)
1f. Code Structure for Architecture Comparison
Extract actual state from code:
- Workspace packages: list directories under
packages/that have apackage.json - Providers: subdirectories under
packages/core/src/providers/withprovider.ts(currently:anthropic,gemini) - Adapters: subdirectories under
packages/core/src/adapters/withadapter.ts(currently:likec4) - Platforms: subdirectories under
packages/core/src/platforms/withreader.ts(currently:github,gitlab) - Pipeline stages: section headers in
packages/core/src/pipelines/analyze.ts— count stages, note which are optional - External deps: SDK imports in provider/adapter/platform files (
@anthropic-ai/sdk,@google/generative-ai,likec4,@octokit/*, etc.)
Step 2: Compare Against Docs
For each documentation target, check:
Completeness:
- Every CLI command listed with correct arguments and all flags
- Every env var from
ENV_MAPPINGSin configuration docs - Every GH Action input/output from
action.ymlin github-actions docs - Default values match code exactly
Accuracy:
- Flag names match code (e.g.,
--urlnot--pr) - Positional args shown correctly (e.g.,
<model-path>is a positional arg) - Required vs optional status matches
- Model names in provider docs match config defaults
Cross-page consistency:
- Same item described consistently across all pages
- README and web docs don't contradict each other
Architecture model accuracy:
Check model.c4 against workspace:
- Every
packages/*/dir with apackage.jsonshould have apackageelement (and vice versa) - Note:
packages/architecture/is a meta-package — confirm with user before flagging its absence
Check core.c4 pipeline stages against packages/core/src/pipelines/analyze.ts:
- Stage count and names match
#fast-model/#advanced-model/#optionaltags match code behavior
Check core.c4 providers/adapters/platforms against their respective directories:
- Every implementation directory has a corresponding element (and vice versa)
- Cross-check factory files for the canonical list
Check core.c4 dependency arrows against actual imports:
analyze → adapters/platforms/providers/analysis/output/configarrows match imports inanalyze.ts- Provider → external API arrows match SDK imports
- Platform → external API arrows match API usage
- Adapter → library arrows match imports
Check externals.c4 against actual package.json dependencies and API usage.
Known intentional differences (do NOT flag as bugs):
action.ymldefaultsai-providertoanthropic, butconfig.tsdefaultsERODE_AI_PROVIDERtogemini— these are different interfaces with different defaultspackages/architecture/is a meta-package for diagrams — may or may not be inmodel.c4
Step 3: Report
Group findings by category:
- Missing from docs — Items in code but not documented
- Incorrect in docs — Wrong values (flag names, defaults, descriptions)
- Inconsistent across docs — Same item differs between pages
- Missing from model — Code elements not in any
.c4file - Stale in model —
.c4elements with no corresponding code - Inaccurate descriptions — Element descriptions that don't match code
- Missing/stale dependency arrows — Import relationships without arrows or vice versa
- Up to date — Confirmed-correct items
For every finding: name the exact file, the code value, and the doc value.
Step 4: Propose Edits
For each affected doc file, draft the specific markdown changes as before/after blocks. Group by file. Present for user review before applying.
For .c4 changes, draft LikeC4 DSL snippets as before/after. Follow existing style (element types, indentation, description/technology fields). Place new elements near siblings.
Rules
- Be specific — exact file, line, code snippet vs doc snippet for every finding
- Flag newly-added items prominently (new env var or flag with zero documentation)
- Check both web docs AND README
- Skip internal/non-user-facing items (private types, implementation details)
- Do not flag known intentional differences (see list above)
- For architecture model checks, focus on structural accuracy (elements exist, arrows correct) over prose quality in descriptions
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 318k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 117k | Updated | Claude CodeCodex | Verified | Install |