Skip to content

OXI-717/ai-native-toolkit / plugins/ctx/skills/ctx-lint

ctx-lint

Verified

Validate @-imports across all ctx AGENTS.md files. Finds broken links, missing end markers. Supports auto-fix for trivial issues. Triggers on "/ctx-lint", "validate imports", "check AGENTS.md", "what broke in context".

ctx-lint — context validator

Scans projects with AGENTS.md, validates @-imports and end-markers. Reports broken links and can fix trivial cases.

Supported load_strategy values

ValueFor whatChecks
alphaHub / standalone project with flat @-importsimports, end-marker
orchestratorShared-pack AGENTS.md (e.g. _ecosystem/AGENTS.md in an ecosystem repo)imports (key ones), no end-marker requirement
symlink-consumerProject repo importing orchestrator via _ecosystem/ symlinkimports + presence of _ecosystem/ (symlink or dir) + required @./_ecosystem/AGENTS.md import

Projects without load_strategy in frontmatter are unmanaged (ctx-lint skips import checks, but CLAUDE.md thin-wrapper check still runs).

Separately detectable issue types for the symlink pattern:

  • missing_ecosystem_link — consumer project has no _ecosystem/
  • broken_ecosystem_link — _ecosystem symlink points to a non-existent path
  • consumer_missing_orchestrator_import — _ecosystem/ exists but AGENTS.md has no @-import resolving to <repo>/_ecosystem/AGENTS.md

Subcommands

  • ctx-lint — check projects in CWD scope (see below)
  • ctx-lint <path> — check one specific project
  • ctx-lint --all — force-check all discovered projects
  • ctx-lint --here — only the current project (enclosing CWD)
  • ctx-lint --json — machine-readable output for agent parsing
  • ctx-lint --fix — apply safe auto-fixes (high-confidence only)
  • ctx-lint --list-projects — show all discovered paths (ignores scope)

Default scope (auto-scope)

Without explicit path and without --all/--here, scope is the union of the enclosing project (if CWD is inside one) and all projects directly under CWD:

  • CWD is deep inside a project with no nested sub-projects → just that one project
  • CWD is project root but has sub-projects under it → checks both the project and all sub-projects
  • CWD is a container for projects → all projects under it
  • CWD is neither inside nor above any known project → falls back to all discovered

Selected scope is always visible in the output header (human) and in the scope field (JSON). Force flags: --all (all), --here (strictly enclosing, ignores nested).

Agent procedure

  1. Resolve the plugin root (CLAUDE_PLUGIN_ROOT can be empty under Codex) and the repo to check:

    PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-<installed-plugin-root>}"
    REPO="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
    

    ctx-lint parses frontmatter with PyYAML. If python3 -c 'import yaml' fails, run the commands below as uv run --with pyyaml python3 … (or install it: python3 -m pip install pyyaml).

  2. Run python3 "$PLUGIN_ROOT/lib/ctx-lint.py" "$REPO" --json → structured report like {"scope": {...}, "reports": [...]}. Pass the path explicitly: without it, project discovery relies on local registries that a fresh install does not have, and the report comes back empty. Use --all only when the user asks for every project.

  3. Check scope.kind — all / container / project / explicit / none. If unexpected — show the scope string and suggest --all.

  4. Show the user a human-readable summary (run again without --json).

  5. If there are confidence: high auto-fixes → suggest ctx-lint --fix (same scope flags).

  6. For confidence: low broken imports — do NOT apply auto-fix, show the user the suggestion and ask for confirmation.

Examples

  • /ctx-lint — auto-scope: current project or container, otherwise all
  • /ctx-lint --all — global run across all projects
  • /ctx-lint --here — force only enclosing project
  • /ctx-lint --all --fix — auto-fixes across all projects
  • /ctx-lint ~/myproject — one explicit project
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 469kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 321kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 321kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 321kUpdated Claude CodeCodexVerifiedInstall