Proposal: add jcode-harness embedded skills and LLM wiki memory loop

[chapzin]

Summary

This PR is a proposal/reference implementation for a jcode-harness product direction on top of jcode internals. It focuses on making agent work more auditable and reproducible by combining:

• offline embedded skills;
• deterministic skill routing;
• local LLM wiki memory guidance;
• project /init scaffolding and swarm-analysis artifacts;
• scriptable harness/quality-gate documentation;
• a README that explains the fork architecture and engineering loop.

The intent is not to force a direct merge of a large generated branch. Per the repository contribution policy, this PR is meant to make the design direction, tests, tradeoffs, and evidence reviewable so the maintainer can reuse, adapt, or rewrite the parts that fit upstream.

Problem / motivation

Long-running agent work can fail quietly when:

• previous decisions are lost in chat history;
• skill/prompt behavior is implicit rather than versioned;
• project bootstrap produces no durable artifacts;
• completion is claimed without repeatable evidence;
• automation-facing output is not validated as a contract.

This branch explores a local-first harness layer that keeps those concerns explicit in repo files, docs, tests, and CLI contracts.

Main changes

Embedded skills and routing

• Adds built-in llmwiki-memory skill for safe use of local LLM wiki memory, provenance, transcript sync, and secret boundaries.
• Keeps karpathy-guidelines, optimization, and clean-code-guardian as offline built-ins.
• Embeds built-ins through src/skill_pack.rs with include_str!.
• Extends src/skill_router.rs so wiki/project-memory/prior-decision/provenance tasks select llmwiki-memory.
• Fixes a router false positive by replacing the broad "pr" trigger with "pull request", avoiding matches inside words like prior or project.

/init and project-local harness artifacts

• Adds deterministic .jcode/ init artifacts for project status, init questions, skills/MCP plans, and swarm-analysis plan/report files.
• Documents the expected /init swarm flow: architecture, QA, documentation/onboarding, and tooling/security discovery roles with synthesis blocked on a report barrier.
• Updates generated skills plan output so llmwiki-memory is part of the bootstrap guidance.

Docs and README

• Rewrites the README around the jcode-harness fork thesis.
• Adds docs/assets/jcode-harness-loop.svg, a visual engineering-loop diagram inspired by the style of chapzin/codex-harness-mcp.
• Adds an “At a glance” layer table and a “How the engineering is put together” section.
• Updates docs/CODEX_BOOTSTRAP.md, docs/SKILLS_HARNESS.md, docs/SKILLS_HARNESS_STATUS.md, and release gates to reflect the Jcode + local LLM wiki + Karpathy-skills scope.
• Refreshes generated onboarding context and .jcode/side_panel/status.md.

Tests / cleanup

• Adds/updates unit and e2e coverage for built-in skill parsing, skill routing, JSON skill output, and harness CLI skill exposure.
• Suppresses the deprecated Claude subprocess enum warning only in the legacy compatibility assertion test with a local #[allow(deprecated)].

Validation run

Commands run successfully during this branch:

cargo fmt --check
cargo check -p jcode
cargo test -p jcode project_init --lib -- --nocapture
cargo test -p jcode test_init_command --lib -- --nocapture
cargo test -p jcode skill_router --lib
cargo test -p jcode skill::tests --lib
cargo test -p jcode clean_code --lib
cargo test --test e2e harness_cli -- --nocapture
cargo run -q -p jcode --bin jcode-harness -- skills list --json | python3 -m json.tool >/dev/null
cargo run -q -p jcode --bin jcode-harness -- skills show llmwiki-memory --json | python3 -m json.tool >/dev/null
cargo run -q -p jcode --bin jcode-harness -- skills doctor --json | python3 -m json.tool >/dev/null

Also run successfully:

selfdev build target=auto

Note: selfdev reload was attempted after a successful build, but the reload tool returned Could not find jcode repository directory. selfdev status still showed the new build channel/recent build.

README-specific validation:

python3 - <<'PY'
from pathlib import Path
s = Path('README.md').read_text()
assert '## How the engineering is put together' in s
assert s.count('![jcode-harness engineering loop]') == 1
assert s.count('```') % 2 == 0
PY
git diff --check

Tradeoffs and review notes

• This is a large product-direction branch, so it may be more useful as a reference/proposal than a direct merge.
• The README intentionally changes the repo presentation from generic upstream jcode to jcode-harness; that may be too fork-specific for upstream without a different landing-page strategy.
• LLM wiki integration is currently a safe embedded skill and routing layer, not a hard runtime dependency. This avoids adding mandatory MCP/network behavior.
• MCP remains review-first. No remote MCP servers are installed or enabled by this branch.
• llmwiki-memory treats wiki memory as provenance/context, not source-code truth. Code claims still need repository/test evidence.
• The generated .jcode/ artifacts are project-local harness state and may need upstream discussion about whether they belong in-tree or only in initialized projects.

Security / safety boundaries

• Built-in skills load locally/offline.
• No credentials, provider tokens, .env values, deployment secrets, database credentials, cookies, or private keys should be synced into LLM wiki memory.
• No live-provider smoke test is added; JSON/NDJSON contracts are validated with a deterministic mock provider path.
• No MCP server is auto-installed or auto-enabled.

Suggested maintainer review path

If this is too broad to merge directly, the most reusable slices are likely:

1. the conservative skill-router tests and "pr" false-positive fix;
2. the built-in llmwiki-memory skill as an optional/local memory guidance layer;
3. the JSON/e2e skill exposure tests;
4. the /init swarm-analysis design and docs as a reference for future bootstrap UX;
5. the README/product narrative as fork documentation rather than upstream homepage content.

---

^{Need help on this PR? Tag @codesmith with what you need.}

• Let Codesmith autofix CI failures and bot reviews

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 7f50d9f47d

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[Copilot]

Pull request overview

This PR proposes a jcode-harness fork direction that layers embedded/offline skills, deterministic skill routing, an LLM-wiki (“Living Memory”) backend option, and a scriptable harness/quality-gate workflow on top of existing jcode internals, with substantial supporting docs and scaffolding artifacts.

Changes:

• Add embedded built-in skills (karpathy-guidelines, optimization, clean-code-guardian, llmwiki-memory) plus deterministic source precedence and routing.
• Add /init scaffolding + swarm-analysis prompting flow, plus new CLI surfaces (skills, clean-code, memory wiki) and JSON contracts/docs.
• Expand safety/ops hardening (secret redaction, best-effort error logging) and add/extend tests and harness artifacts.

Reviewed changes

Copilot reviewed 140 out of 142 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
third_party/andrej-karpathy-skills/skills/karpathy-guidelines/SKILL.md	Vendored Karpathy skill content
third_party/andrej-karpathy-skills/README.md	Vendored upstream README
third_party/andrej-karpathy-skills/CLAUDE.md	Vendored CLAUDE guidance
third_party/andrej-karpathy-skills/.cursor/rules/karpathy-guidelines.mdc	Cursor rule for Karpathy guidance
third_party/andrej-karpathy-skills/.claude-plugin/plugin.json	Claude plugin metadata
tests/e2e/main.rs	Register new e2e module
src/tui/ui.rs	TUI theme import updates
src/tui/ui_theme.rs	Re-export additional theme helpers
src/tui/app/tests/commands_accounts_01/part_01.rs	Add /init command tests
src/tui/app/state_ui_input_helpers.rs	Add /init to registered commands
src/tui/app/input.rs	Wire /init command handler
src/tui/app/commands.rs	Implement /init handler + swarm reminder
src/tool/skill.rs	Include skill origin in tool output
src/skill.rs	Add skill origin + embedded skill loading/precedence
src/skill_router.rs	Deterministic skill routing + preface builder
src/skill_pack.rs	Embed built-in skills + sync to ~/.jcode/skills
src/process_title.rs	Set titles for new CLI commands
src/overnight.rs	Replace swallowed errors with best-effort logging
src/message/tests.rs	Add redaction regression tests
src/message.rs	Expand secret redaction patterns
src/lib.rs	Export new modules (clean_code, memory_wiki, project_init, skill_*)
src/config/env_overrides.rs	Add env overrides for memory backend/scope
src/config/default_file.rs	Add default [memory] config section
src/config.rs	Add memory: MemoryConfig to main config
src/cli/terminal.rs	Exit cleanly on stdout broken pipe panics
src/cli/provider_init_tests.rs	Scope #[allow(deprecated)] in test
src/cli/dispatch.rs	Wire skills, clean-code, memory wiki CLI commands
src/cli/commands/provider_setup.rs	Harden config read + validate profile name + safer quoting
src/cli/args.rs	Add skills, clean-code, memory wiki CLI args
src/agent/prompting.rs	Merge legacy + wiki memory prompts based on configured backend
scripts/dev_cargo.sh	Linker config tweak
scripts/cli_quality_preflight.sh	Add bounded CLI quality preflight script
NOTICE.md	Add third-party attribution notice for fork
docs/SKILLS_HARNESS.md	Document skills harness/CLI/router
docs/SKILLS_HARNESS_STATUS.md	Status checklist + validation snapshot
docs/MEMORY_ARCHITECTURE.md	Link to Living Memory doc
docs/LIVING_MEMORY.md	Document memory v2 backend + CLI + safety rules
docs/JCODE_HARNESS_RELEASE_GATES.md	Define release readiness gates
docs/JCODE_HARNESS_PRODUCT_PLAN.md	Product direction plan for harness fork
docs/JCODE_HARNESS_JSON_SCHEMAS.md	Document JSON/NDJSON automation schemas
docs/JCODE_HARNESS_INIT_SWARM.md	Document /init swarm behavior
docs/CODEX_BOOTSTRAP.md	Bootstrap/continuation notes for agents
docs/CLEAN_CODE_GUARDIAN.md	Document clean-code policy + boundaries
docs/assets/jcode-harness-loop.svg	Add engineering-loop diagram
crates/jcode-tui-style/src/theme.rs	Add animation helpers + tests
crates/jcode-storage/src/lib.rs	Reduce swallowed errors + strengthen writes/hardening
crates/jcode-protocol/src/lib.rs	Minor formatting/attribute adjustments
crates/jcode-memory-types/src/lib.rs	Change memory ID generation
crates/jcode-memory-types/Cargo.toml	Add rand dependency
crates/jcode-config-types/src/lib.rs	Add MemoryConfig type
crates/jcode-build-support/src/lib.rs	Reduce swallowed errors + improve stderr handling
Cargo.lock	Lockfile updates for new deps
AGENTS.md	Expand repo workflow + harness guardrails
.jcode/skills/llmwiki-memory/SKILL.md	Add built-in skill content
.jcode/skills/karpathy-guidelines/SKILL.md	Add built-in skill content
.jcode/skills/clean-code-guardian/SKILL.md	Add built-in skill content
.jcode/SKILLS_PLAN.md	Add skills plan guidance
.jcode/side_panel/status.md	Add side-panel status scaffold
.jcode/side_panel/questions.md	Add side-panel preference checklist
.jcode/quality/clean-code-rules.yaml	Add clean-code rule pack
.jcode/memory_wiki/wiki/user/style.md	Add wiki scaffold page
.jcode/memory_wiki/wiki/user/procedures.md	Add wiki scaffold page
.jcode/memory_wiki/wiki/user/preferences.md	Add wiki scaffold page
.jcode/memory_wiki/wiki/user/corrections.md	Add wiki scaffold page
.jcode/memory_wiki/schema.md	Add wiki schema doc
.jcode/memory_wiki/overview.md	Add wiki overview page
.jcode/memory_wiki/log.md	Add wiki log
.jcode/memory_wiki/index.md	Add wiki index
.jcode/memory_wiki/cache/search_index.json	Add wiki cache placeholder
.jcode/memory_wiki/cache/page_manifest.json	Add wiki cache placeholder
.jcode/mcp.json	Add MCP config stub
.jcode/MCP_PLAN.md	Add MCP plan scaffold
.jcode/init/SWARM_ANALYSIS_REPORT.md	Add swarm analysis report artifact
.jcode/init/SWARM_ANALYSIS_PLAN.md	Add swarm analysis plan scaffold
.jcode/INIT_REPORT.md	Add init report scaffold
.jcode/INIT_QUESTIONS.md	Add init questions scaffold
.context/workflow/status.yaml	Generated workflow status
.context/workflow/plans.json	Generated workflow plans
.context/workflow/actions.jsonl	Generated workflow actions log
.context/skills/test-generation/SKILL.md	Generated skill scaffold
.context/skills/security-audit/SKILL.md	Generated skill scaffold
.context/skills/refactoring/SKILL.md	Generated skill scaffold
.context/skills/README.md	Generated skills index
.context/skills/pr-review/SKILL.md	Generated skill scaffold
.context/skills/feature-breakdown/SKILL.md	Generated skill scaffold
.context/skills/documentation/SKILL.md	Generated skill scaffold
.context/skills/commit-message/SKILL.md	Generated skill scaffold
.context/skills/code-review/SKILL.md	Generated skill scaffold
.context/skills/bug-investigation/SKILL.md	Generated skill scaffold
.context/skills/api-design/SKILL.md	Generated skill scaffold
.context/plans/cli-quality-security-ux.md	Generated plan artifact
.context/docs/tooling.md	Generated doc artifact
.context/docs/testing-strategy.md	Generated doc artifact
.context/docs/security.md	Generated doc artifact
.context/docs/README.md	Generated docs index
.context/docs/qa/realtime.md	Generated Q&A artifact
.context/docs/qa/README.md	Generated Q&A index
.context/docs/qa/project-structure.md	Generated Q&A artifact
.context/docs/qa/getting-started.md	Generated Q&A artifact
.context/docs/qa/deployment.md	Generated Q&A artifact
.context/docs/qa/background-jobs.md	Generated Q&A artifact
.context/docs/qa/authentication.md	Generated Q&A artifact
.context/docs/project-overview.md	Generated doc artifact
.context/docs/glossary.md	Generated doc artifact
.context/docs/development-workflow.md	Generated doc artifact
.context/docs/data-flow.md	Generated doc artifact
.context/docs/architecture.md	Generated doc artifact
.context/agents/test-writer.md	Generated agent playbook
.context/agents/security-auditor.md	Generated agent playbook
.context/agents/refactoring-specialist.md	Generated agent playbook
.context/agents/README.md	Generated agent index
.context/agents/performance-optimizer.md	Generated agent playbook
.context/agents/mobile-specialist.md	Generated agent playbook
.context/agents/frontend-specialist.md	Generated agent playbook
.context/agents/feature-developer.md	Generated agent playbook
.context/agents/documentation-writer.md	Generated agent playbook
.context/agents/devops-specialist.md	Generated agent playbook
.context/agents/database-specialist.md	Generated agent playbook
.context/agents/code-reviewer.md	Generated agent playbook
.context/agents/bug-fixer.md	Generated agent playbook
.context/agents/backend-specialist.md	Generated agent playbook
.context/agents/architect-specialist.md	Generated agent playbook
.codex-harness/traces/2026-05-06.jsonl	Harness trace log
.codex-harness/state.json	Harness state
.codex-harness/policy.json	Harness policy
.codex-harness/HARNESS.md	Harness README
.codex-harness/gates/gate-2026-05-06-5c9d00.md	Harness gate report (md)
.codex-harness/gates/gate-2026-05-06-5c9d00.json	Harness gate report (json)
.codex-harness/decisions/decision-2026-05-06-1c16f8.md	Harness decision record
.codex-harness/contracts/2026-05-06-cli-quality-security-ux-optimization-50bbc2.md	Harness contract (md)
.codex-harness/contracts/2026-05-06-cli-quality-security-ux-optimization-50bbc2.json	Harness contract (json)

Comments suppressed due to low confidence (1)

crates/jcode-storage/src/lib.rs:315

• write_bytes_inner renames the existing file to <name>.bak without handling the case where the .bak already exists. On platforms where std::fs::rename cannot overwrite an existing destination (notably Windows), the second write to the same path will fail because the backup file already exists, making durable writes non-repeatable.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.