Mk Chom

Chom — Copy-Cat, Replicate & Adapt

Analyze external systems, repos, apps, or ideas and produce a spec for replicating them in your project.

Principles: understand before copy | challenge before plan | adapt to YOUR stack

Usage

the chom skill <github-url|web-url|local-path|description> [feature] [--compare|--copy|--improve|--port] [--lean|--auto]

Modes (all user-explicit — chom does NOT auto-derive adaptation depth):

• --compare: side-by-side analysis only (phases 1–3), no decision or handoff
• --copy: user intent = transplant with minimal changes; biases Phase 3 toward compatibility gaps
• --improve: user intent = adapt anti-patterns during port; biases Phase 3 toward anti-pattern detection
• --port: user intent = rewrite idiomatically for local stack; biases Phase 3 toward idiom translation
• no flag: full 6-phase workflow, emits Replication Spec without declaring adaptation depth

Speed flags (default OFF):

• --lean: skip Phase 1 researcher-agent background gathering. HARD GATE still enforced.
• --auto: auto-approve non-HARD-GATE steps. HARD GATE still requires human approval.

Migration (v1 → v2): --analyze (v1 default) now aliases the no-flag default and emits a deprecation notice. Removed in v1.2.

Intent Detection (keyword → suggested mode)

If the user provides natural-language mode hints, map them to an explicit flag:

If no hint and no flag, run no-flag default (full workflow, no mode declaration in handoff).

Input Routing

Detect input type FIRST, then route:

Clean up cloned repos after analysis.

Workflow

[1. Recon] → [2. Map] → [3. Analyze] → [4. Challenge] ══ HARD GATE ══ [5. Decision] → [6. Handoff]

Hard gate: Phase 4 must complete and get human approval before Phase 5. HARD GATE is non-bypassable — no flag (including --lean or --auto) skips human approval here.

1. Recon

Route input per table above. Always also read local docs/project-context.md for YOUR project's stack. For git repos: clone shallow, run mk:scout for architecture fingerprint. For web URLs: fetch content, capture structure and behavior.

--lean effect depends on input type:

• freeform text input: skip the researcher agent background gathering; proceed to Phase 2 with only the user's description + docs/project-context.md
• git URL / local path: no-op (scout is the primary recon tool and is not skipped; HARD GATE compensates for reduced context)
• web URL: no-op (fetch is primary)
• image/screenshot: no-op (multimodal is primary)

2. Map

Build dependency matrix: source components → local equivalents (EXISTS / NEW / CONFLICT). For each component: what exists locally, what needs building, what libraries are needed.

3. Analyze

Trace execution flow, data model, API contracts, UX patterns. Understand WHY, not just HOW.

Mode-specific focus when the user passed an explicit mode:

• --copy: compatibility gaps and minimum adaptation needed
• --improve: anti-patterns to replace during adoption
• --port: idiomatic translation into local patterns
• --compare or no flag: architectural differences and trade-offs

Escalation: if the feature has ≥3 architectural layers OR stateful workflows, emit handoff text: "Complex flow detected. Before Phase 4, trace via the sequential-thinking skill, then return to chom." Do NOT auto-invoke any skill.

For --compare: produce Comparison Report and STOP here.

4. Challenge

Load references/challenge-framework.md. Ask 7 questions. Score risk. Present decision matrix. Get human approval before continuing. If risk ≥ 5: recommend rejection.

5. Decision

Go/no-go. If go: formalize Replication Spec (no mode declaration — the user's flag, if any, is noted but chom does not pick --copy/--improve/--port on the user's behalf). If no-go: Rejection Report with reasoning.

6. Handoff

Output Replication Spec + handoff text:

Replication Spec ready.

Challenge summary: <N> stack-fit reds, <N> data-model red, <N> blast-radius reds.
Risk level: <low|medium|high> (per challenge-framework.md 0-2 low / 3-4 medium / 5+ high).

To implement, run:
  the plan-creator skill "Replicate [feature] from [source]"

To bias future chom analysis toward a specific adaptation depth, re-invoke with:
  the chom skill [source] --copy | --improve | --port

Output: Replication Spec

# Replication Spec: [Feature/System Name]

## 1. Source — name, URL, tech stack, what we're replicating
## 2. What to Build — specific features/patterns to replicate
## 3. Stack Fit — maps to our stack (exists / new / conflicts)
## 4. Risks & Effort — what's hard, estimated complexity
## 5. Recommendation — replicate / adapt / reject + next step

Handoff text enriches this with challenge reds + risk score.

Output: Comparison Report (--compare)

Same as Replication Spec but replace sections 2+5 with Head-to-Head table + Takeaways. Print to conversation; do not write to disk unless user explicitly asks (the report is single-use analysis, not a durable artifact).

Boundary Rules

This skill emits handoff text. It does NOT invoke any other skill mid-flow — including the plan-creator skill, the brainstorming skill, the cook skill, the sequential-thinking skill.

This is chom's design choice, not a a platform rule. Skills can reference other skills and the model may invoke them; chom opts out because mid-flow invocations of other orchestration skills (plan-creator, brainstorming, cook) would break phase ownership — each of those skills has its own multi-phase workflow that would interleave with chom's HARD GATE discipline. chom's job ends at Phase 6 Handoff; the user invokes the next skill.

HARD GATE (Phase 4 human approval) is non-bypassable. No flag, including --lean or --auto, skips this step.

Error Recovery

• Source private/missing → ask for access or alternative
• Source too large → ask user to narrow scope with feature hint
• Source empty / unreachable / invalid → stop, report what was attempted, ask user to verify URL or path
• Live app behind auth → ask for screenshots or description
• Challenge reveals blocker → offer --compare fallback
• Stack mismatch too large → auto-switch to --compare
• Risk ≥ 5 → reject with Rejection Report

Gotchas

• chom never declares adaptation depth. Pick --copy/--improve/--port explicitly if you want the analysis biased toward that intent. No-flag runs emit a Replication Spec without mode declaration.
• API-surface queries use the pack skill --compress, not chom. If the question is "what's the public API of library X" rather than "should we replicate it," pack's Tree-sitter signature extraction is the right tool. chom is for replication decisions, not API exploration.
• 3+ layers trigger sequential-thinking handoff, not auto-invocation. Trace the flow via the sequential-thinking skill, then return to chom.
• HARD GATE applies in all modes, including --lean and --auto. Phase 4 human approval is never skipped.
• No local context = generic advice: always read docs/project-context.md first. Without it, recommendations won't fit your stack.
• "Obvious" copies hide complexity: auth flows, data models, API contracts — the challenge phase is NEVER skipped.
• chom never chains into other skills mid-flow: handoff text only. USER invokes plan-creator / cook / sequential-thinking. See Boundary Rules for rationale.
• Spec ≠ code: output describes WHAT and WHY, never HOW. No code blocks in specs.

Reference

• references/challenge-framework.md