From 0aad18a83049ab299e2d0fd50ccb83002b875aaa Mon Sep 17 00:00:00 2001 From: Affaan Mustafa Date: Sun, 5 Apr 2026 14:39:55 -0700 Subject: [PATCH] docs: add manual adaptation guide for non-native harnesses --- README.md | 1 + docs/MANUAL-ADAPTATION-GUIDE.md | 214 ++++++++++++++++++++++++++++++++ 2 files changed, 215 insertions(+) create mode 100644 docs/MANUAL-ADAPTATION-GUIDE.md diff --git a/README.md b/README.md index 11cc92cb..62215ecb 100644 --- a/README.md +++ b/README.md @@ -916,6 +916,7 @@ Yes. ECC is cross-platform: - **OpenCode**: Full plugin support in `.opencode/`. See [OpenCode Support](#opencode-support). - **Codex**: First-class support for both macOS app and CLI, with adapter drift guards and SessionStart fallback. See PR [#257](https://github.com/affaan-m/everything-claude-code/pull/257). - **Antigravity**: Tightly integrated setup for workflows, skills, and flattened rules in `.agent/`. See [Antigravity Guide](docs/ANTIGRAVITY-GUIDE.md). +- **Non-native harnesses**: Manual fallback path for Grok and similar interfaces. See [Manual Adaptation Guide](docs/MANUAL-ADAPTATION-GUIDE.md). - **Claude Code**: Native — this is the primary target. diff --git a/docs/MANUAL-ADAPTATION-GUIDE.md b/docs/MANUAL-ADAPTATION-GUIDE.md new file mode 100644 index 00000000..8dbd0e5b --- /dev/null +++ b/docs/MANUAL-ADAPTATION-GUIDE.md @@ -0,0 +1,214 @@ +# Manual Adaptation Guide for Non-Native Harnesses + +Use this guide when you want ECC behavior inside a harness that does not natively load `.claude/`, `.codex/`, `.opencode/`, `.cursor/`, or `.agent/` layouts. + +This is the fallback path for tools like Grok and other chat-style interfaces that can accept system prompts, uploaded files, or pasted instructions, but cannot execute the repo's native install surfaces directly. + +## When to Use This + +Use manual adaptation when the target harness: + +- does not auto-load repo folders +- does not support custom slash commands +- does not support hooks +- does not support repo-local skill activation +- has partial or no filesystem/tool access + +Prefer a first-class ECC target whenever one exists: + +- Claude Code +- Codex +- Cursor +- OpenCode +- CodeBuddy +- Antigravity + +Use this guide only when you need ECC behavior in a non-native harness. + +## What You Are Reproducing + +When you adapt ECC manually, you are trying to preserve four things: + +1. Focused context instead of dumping the whole repo. +2. Skill activation cues instead of hoping the model guesses the workflow. +3. Command intent even when the harness has no slash-command system. +4. Hook discipline even when the harness has no native automation. + +You are not trying to mirror every file in the repo. You are trying to recreate the useful behavior with the smallest possible context bundle. + +## The ECC-Native Fallback + +Default to manual selection from the repo itself. + +Start with only the files you actually need: + +- one language or framework skill +- one workflow skill +- one domain skill if the task is specialized +- one agent or command only if the harness benefits from explicit orchestration + +Good minimal examples: + +- Python feature work: + - `skills/python-patterns/SKILL.md` + - `skills/tdd-workflow/SKILL.md` + - `skills/verification-loop/SKILL.md` +- TypeScript API work: + - `skills/backend-patterns/SKILL.md` + - `skills/security-review/SKILL.md` + - `skills/tdd-workflow/SKILL.md` +- Content/outbound work: + - `skills/brand-voice/SKILL.md` + - `skills/content-engine/SKILL.md` + - `skills/crosspost/SKILL.md` + +If the harness supports file upload, upload only those files. + +If the harness only supports pasted context, extract the relevant sections and paste a compressed bundle rather than the raw full files. + +## Manual Context Packing + +You do not need extra tooling to do this. + +Use the repo directly: + +```bash +cd /path/to/everything-claude-code + +sed -n '1,220p' skills/tdd-workflow/SKILL.md > /tmp/ecc-context.md +printf '\n\n---\n\n' >> /tmp/ecc-context.md +sed -n '1,220p' skills/backend-patterns/SKILL.md >> /tmp/ecc-context.md +printf '\n\n---\n\n' >> /tmp/ecc-context.md +sed -n '1,220p' skills/security-review/SKILL.md >> /tmp/ecc-context.md +``` + +You can also use `rg` to identify the right skills before packing: + +```bash +rg -n "When to use|Use when|Trigger" skills -g 'SKILL.md' +``` + +Optional: if you already use a repo packer like `repomix`, it can help compress selected files into one handoff document. It is a convenience tool, not the canonical ECC path. + +## Compression Rules + +When manually packing ECC for another harness: + +- keep the task framing +- keep the activation conditions +- keep the workflow steps +- keep the critical examples +- remove repetitive prose first +- remove unrelated variants second +- avoid pasting whole directories when one or two skills are enough + +If you need a tighter prompt format, convert the essential parts into a compact structured block: + +```xml + + New feature, bug fix, or refactor that should be test-first. + + Write a failing test. + Make it pass with the smallest change. + Refactor and rerun validation. + + +``` + +## Reproducing Commands + +If the harness has no slash-command system, define a small command registry in the system prompt or session preamble. + +Example: + +```text +Command registry: +- /plan -> use planner-style reasoning, produce a short execution plan, then act +- /tdd -> follow the tdd-workflow skill +- /review -> switch into code-review mode and enumerate findings first +- /verify -> run a verification loop before claiming completion +``` + +You are not implementing real commands. You are giving the harness explicit invocation handles that map to ECC behavior. + +## Reproducing Hooks + +If the harness has no native hooks, move the hook intent into the standing instructions. + +Example: + +```text +Before writing code: +1. Check whether a relevant skill should be activated. +2. Check for security-sensitive changes. +3. Prefer tests before implementation when feasible. + +Before finalizing: +1. Re-read the user request. +2. Verify the main changed paths. +3. State what was actually validated and what was not. +``` + +That does not recreate true automation, but it captures the operational discipline of ECC. + +## Harness Capability Matrix + +| Capability | First-Class ECC Targets | Manual-Adaptation Targets | +| --- | --- | --- | +| Folder-based install | Native | No | +| Slash commands | Native | Simulated in prompt | +| Hooks | Native | Simulated in prompt | +| Skill activation | Native | Manual | +| Repo-local tooling | Native | Depends on harness | +| Context packing | Optional | Required | + +## Practical Grok-Style Setup + +1. Pick the smallest useful bundle. +2. Pack the selected ECC skill files into one upload or paste block. +3. Add a short command registry. +4. Add standing “hook intent” instructions. +5. Start with one task and verify the harness follows the workflow before scaling up. + +Example starter preamble: + +```text +You are operating with a manually adapted ECC bundle. + +Active skills: +- backend-patterns +- tdd-workflow +- security-review + +Command registry: +- /plan +- /tdd +- /verify + +Before writing code, follow the active skill instructions. +Before finalizing, verify what changed and report any remaining gaps. +``` + +## Limitations + +Manual adaptation is useful, but it is still second-class compared with native targets. + +You lose: + +- automatic install and sync +- native hook execution +- true command plumbing +- reliable skill discovery at runtime +- built-in multi-agent/worktree orchestration + +So the rule is simple: + +- use manual adaptation to carry ECC behavior into non-native harnesses +- use native ECC targets whenever you want the full system + +## Related Work + +- [Issue #1186](https://github.com/affaan-m/everything-claude-code/issues/1186) +- [Discussion #1077](https://github.com/affaan-m/everything-claude-code/discussions/1077) +- [Antigravity Guide](./ANTIGRAVITY-GUIDE.md) +- [Troubleshooting](./TROUBLESHOOTING.md)