CrossFrame Code Skill

CrossFrame Code Skill is a Codex skill/plugin for code-structure diagnosis, AI patch review, minimal replacement planning, implementation in small verified slices, and verification discipline.

It translates the CrossFrame idea of "object, mechanism, scale, replacement, verification" into software engineering work. The skill is designed for legacy code, brittle refactors, AI-generated code review, architecture diagnosis, and high-risk code replacement where changing behavior before characterization would be unsafe.

This is not a lint tool. Its value is structural judgment and disciplined execution: separating ordinary local implementation work from legacy rescue, settlement consistency, concurrency/runtime, security boundary, and other high-risk work that needs stronger evidence before code changes.

Dual-Core Model

• crossframe-code is the brain: diagnosis, review, local-project risk scan, mechanism judgment, patch planning, and verification-path design.
• crossframe-coder is the hand: implement clear code changes, add tests, run verification, and report results in small safe slices.

Use crossframe-code when the user asks "what is risky?", "can this PR merge?", "how should this be changed safely?", or when auth, tenant, money, migration, concurrency, durable state, webhook, outbox, security, or legacy behavior is unclear.

Use crossframe-coder when the user explicitly asks to implement, build, add, fix, generate, modify, patch, or directly change code and the change is clear enough to verify.

Approved high-risk implementation is a narrow exception. It requires an approved-plan payload with exact files, behavior to preserve, non-goals, verification, first safe slice, resolved confirmations, high-risk categories, environment marker, and decision_trace; otherwise crossframe-coder hands the work back to crossframe-code.

What It Does

• Diagnoses the exact code object under review: function, component, module, interface, test, runtime path, or architecture boundary.
• Separates facts, evidence, mechanism candidates, judgment, and replacement options.
• Produces a patch plan by default instead of editing code immediately.
• Uses Compact output for ordinary local issues and Deep output for high-risk systems.
• Routes ordinary implementation requests to crossframe-coder instead of expanding crossframe-code into a universal codewriter.
• Implements clear code changes in small verified slices through crossframe-coder.
• Reviews PR diffs, Codex patches, and AI-generated changes with merge-risk verdicts.
• Records review scope for diff, staged, branch, commit, range, PR, or pasted-patch reviews.
• Detects stack signals and checks sibling project conventions before applying generic stack advice.
• Scans local projects for risky modules, legacy hotspots, AI patch regression surfaces, and safe refactoring candidates before implementation.
• Requires P0/P1 findings to have evidence anchors.
• Requires explicit user approval before implementation.
• Requires a verification path before any code change.
• Refuses to claim success when verification is blocked.
• Prefers local, reversible, behavior-preserving replacements over broad rewrites.
• Ships thin adapters for Codex, Claude Code, Cursor, Gemini CLI, and generic agent repositories.

Core Workflow

1. Define the code object and evidence.
2. Select one primary architecture lens and at most two secondary checks.
3. Pass the code five gates: object, evidence, scale, responsibility, observation.
4. Compare mechanism candidates.
5. For local-project risk scans, rank risky modules and hotspots from evidence before choosing a patch target.
6. For diff or PR review, pin the review scope and check stack/convention evidence.
7. Choose Compact, Deep Risk, Review, or read-only Architecture Review output.
8. Score replacement options when a patch plan is appropriate.
9. Stop at a plan or verdict unless implementation is explicitly requested.
10. After implementation, run verification and report actual results.

Output Modes

• Compact Patch Plan: for single-file bugs, UI state issues, small backend handlers, and ordinary changes that do not involve money, permission, concurrency, state machines, migrations, or high-risk persistence.
• Deep Risk Patch Plan: for legacy rescue, settlement consistency, concurrency/runtime, security boundary, auth, multi-tenant, migration, payment, billing, webhook, outbox, or multi-file high-risk refactors.
• Review Output: for PR diffs, staged or unstaged changes, branch comparisons, commits, commit ranges, pasted patches, Codex patches, or AI-generated modifications where the right answer is a merge-risk verdict, not a new patch plan.
• Architecture Review / Risk Scan: for broad local-project diagnosis, risky module discovery, legacy hotspot ranking, AI patch regression surface discovery, or safe refactoring candidate selection. This is read-only and must be converted into a Compact or Deep Risk patch plan before implementation.

Local Project Risk Scan

For repository-level diagnosis, the skill looks for evidence-backed candidates instead of rewriting the largest file first:

• Risky modules with mixed responsibilities, hidden side effects, durable-state mutation, contract drift, or weak tests.
• Legacy hotspots that need Golden Master or characterization tests before behavior changes.
• AI patch regression surfaces such as removed guards, owner/tenant check removal, widened types, dropped tests, changed error shapes, or unnamed behavior changes.
• Safe refactoring candidates with behavior to preserve, first safe slice, and verification seam.
• v0.3 multi-tenant SaaS key completeness checks for query, cache, lock, idempotency, dedupe, coupon, invoice uniqueness, webhook binding, outbox/revenue, and schema keys.

Size, line count, or style smell alone is weak evidence. The scan must name the object, risk signal, evidence, likely mechanism, lens or review route, and verification seam before recommending action.

Review Scope and Stack Conventions

For review mode, the skill now records the exact review boundary before judging the change:

• Uncommitted changes, staged changes, branch comparison, single commit, commit range, PR URL, or pasted patch.
• Diff command or evidence source used for the verdict.
• Stack signals from project files such as package.json, tsconfig.json, pyproject.toml, go.mod, *.csproj, Dockerfile, or CI files.
• Project convention evidence from sibling files, nearby tests, route handlers, services, components, migrations, or adapters.

Generic stack advice should not become a blocker unless the diff introduces concrete behavior, security, contract, durable-state, or test risk. A project-wide non-ideal pattern that is already consistent is a suggestion at most unless the current change makes it materially worse.

Architecture Lenses

The skill includes focused references for common failure families:

• Frontend state ownership and derived-state drift.
• Backend boundary, DTO, transaction, and service drift.
• Data pipeline parsing, defaults, schema, and validation failures.
• Test integrity problems such as false-positive mocks and snapshots.
• Legacy rescue with Golden Master and characterization tests.
• Concurrency/runtime problems around retries, locks, caches, and idempotency.
• Security boundary failures around authentication, authorization, tenant isolation, injection, webhook signatures, unsafe IO, secrets, and audit logging.
• Settlement consistency for checkout, billing, payment, coupon, credit, invoice, ledger, webhook, outbox, and revenue recognition risks.

Settlement Consistency Focus

The settlement lens has deeper checks for high-risk billing and payment code:

• Idempotency result type collision.
• Tenant key completeness.
• Commit point audit.
• Event replay safety.
• State transition matrix.
• Cross-function invariant checks.
• Revenue recognition idempotency.
• Webhook authenticity and amount matching.

This is meant for code where a local bug can become a billing, payment, refund, tenant-isolation, or audit problem.

Security Boundary Focus

The security lens requires the review to name the trust boundary and distinguish:

• Authentication.
• Authorization.
• Tenant isolation.
• Object-level authorization / IDOR / BOLA.
• Injection and unsafe input use.
• Webhook signature, event dedupe, ownership binding, amount matching, and state transition.
• Audit logging for security-sensitive operations.

Evidence Anchors

P0/P1 findings must include:

- file:
- line/function/symbol:
- observed behavior:
- why this is risky:

If line numbers are unavailable, the anchor must still name a function, variable, call chain, or exact code fragment.

Repository Structure

.claude-plugin/
  plugin.json
.cursor-plugin/
  plugin.json
.cursor/
  rules/
    crossframe-code.mdc
.codex-plugin/
  plugin.json
AGENTS.md
CLAUDE.md
GEMINI.md
INSTALL.md
VERSION
eval-harness/
  approved-plan.jsonl
  dual-core-routing.jsonl
  verification-failure.jsonl
skills/
  crossframe-code/
    SKILL.md
    agents/
    references/
    templates/
    examples/
    evals/
  crossframe-coder/
    SKILL.md
    agents/
    schemas/
    references/
    templates/
    examples/
    evals/
scripts/
  install-adapters.mjs
  test-install-adapters.mjs
  test-approved-plan-schema.mjs
  validate-eval-harness.mjs
  validate-skill.mjs

Platform Adapters

CrossFrame keeps two authoritative skill bodies and thin per-platform entrypoints:

• Codex: .codex-plugin/plugin.json
• Claude Code: .claude-plugin/plugin.json and CLAUDE.md
• Cursor: .cursor-plugin/plugin.json and .cursor/rules/crossframe-code.mdc
• Gemini CLI: GEMINI.md
• Generic agents: AGENTS.md

Install helpers are documented in INSTALL.md. The installer copies both crossframe-code and crossframe-coder, and refuses to overwrite existing files unless --force is provided:

node scripts/install-adapters.mjs --platform codex
node scripts/install-adapters.mjs --platform claude
node scripts/install-adapters.mjs --platform cursor --target /path/to/project
node scripts/install-adapters.mjs --platform gemini --target /path/to/project
node scripts/install-adapters.mjs --platform generic --target /path/to/project

Validation

Run the static validation script from the repository root:

node scripts/validate-skill.mjs

CI should run the same validator and smoke tests used locally:

node scripts/validate-skill.mjs
node scripts/test-install-adapters.mjs
node scripts/test-approved-plan-schema.mjs
node scripts/validate-eval-harness.mjs

The validator checks plugin metadata, skill frontmatter, referenced files, architecture lenses, templates, eval coverage, Golden Master rules, local-project risk scan rules, review scope and stack-convention rules, settlement-consistency constraints, and installation isolation.

Quick smoke run before publishing:

node scripts/validate-skill.mjs
node scripts/test-install-adapters.mjs
node scripts/test-approved-plan-schema.mjs
node scripts/validate-eval-harness.mjs
node scripts/install-adapters.mjs --platform codex --force

The installer smoke test uses temporary Codex/Claude homes and a temporary target project to verify exact skill sync, stale-file pruning, destination type mismatch recovery, identical-directory skip, --all preflight behavior, version marker copying, test-only source root handling, and multi-platform adapter installs. It can write a CI diagnostic log with CROSSFRAME_INSTALL_TEST_LOG=<path>. The approved-plan schema test validates the sample payload and rejects missing decision_trace, Deep Risk plans without evidence anchors, unsafe file paths, unsafe verification commands, unsafe manual verification, missing file intents, missing high-risk categories, unresolved confirmations, extra fields, and unsupported high-risk categories. It can write a CI diagnostic log with CROSSFRAME_SCHEMA_TEST_LOG=<path>. The JSONL eval harness validates machine-checkable dual-core routing, approved-plan, and verification-failure fixtures. Each JSONL case links back to source_markdown and source_section, and the approved-plan complete case points to the valid schema fixture. It can write a CI diagnostic log with CROSSFRAME_EVAL_HARNESS_LOG=<path>.

Approved high-risk decision traces distinguish shape_schema=pass|fail from policy_validator=pass|fail; implementation is allowed only when both pass and route is implement.

Influences and Attribution

This repository studies adjacent public skill repositories and adapts compatible ideas into the CrossFrame Code workflow. Borrowed ideas are rewritten as local instructions and validator-backed structures rather than copied wholesale.

• felipereisdev/code-review-skill: inspired the review scope selection flow, lightweight stack detection, project convention-first review stance, and category summary for patch/PR review.

What was not copied from that project:

• The full stack checklist library.
• Its exact review output wording.
• Its severity model as the primary risk model.

CrossFrame Code keeps a different center: evidence anchors, behavior preservation, local-project risk scans, Golden Master / characterization, architecture lenses, patch planning before implementation, and verification closure.

Status

This is an early dual-core coding skill suite with:

• crossframe-code for diagnosis, review, risk scan, and patch planning.
• crossframe-coder for clear implementation requests in small verified slices.

Current suite version: 0.10.0.

The root VERSION file and both skill-level VERSION files should match this value. After install, confirm the local skill version with:

cat ~/.codex/skills/crossframe-code/VERSION
cat ~/.codex/skills/crossframe-coder/VERSION

It ships local install helpers, but is not automatically installed unless the user runs scripts/install-adapters.mjs.

Current license status: UNLICENSED.