Imported from Cheeyoung-Yoon/personal_work_system (AGENTS.md). Install upstream with npx skills add Cheeyoung-Yoon/personal_work_system. Copyright stays with the author.

Adaptive Context Engine

This repo is an Adaptive Context Engine for expensive Claude/Codex calls. Context is a task-specific materialized view, not conversation history.

Runtime

• Python and tests run in Docker. Do not use a local venv.
• docker compose run --rm test is the test command.
• docker compose run --rm dev is the interactive shell.
• make test / make shell are aliases.

Boundaries

• src/context_engine/ is the product.
• config/context_policy.yaml is policy, not code.
• third_party/ is read-only upstream. Do not edit clones in place.
• .env is secrets. Never commit it or paste keys into prompts.

Implementation order

Do not start with Jev or Headroom wiring.

1. Data model (Experiment, Finding, Evidence, Dependency, ContextItem)
2. Persistence
3. Context tiering (L0–L3)
4. Builder / deterministic retrieval
5. Policy
6. Jev judge slot
7. Compression / Headroom slot
8. Pointer retrieval
9. Trace / evaluation

PINNED (L0) context is never auto-removed. Representations are RAW, COMPRESSED, or POINTER. Do not DROP.

Harness

Large work goes through the project harness, not a freeform swarm.

• Skill: .grok/skills/ace-harness/SKILL.md
• Agents: .grok/agents/ace-*.md
• Artifacts: harness/

Main orchestrates. Workers stay inside a contract. Do not spawn workers for a one-file change that Main can finish itself.

When /opsx-apply is active, each open checkbox in openspec/changes/<name>/tasks.md is a slice. Skip ace-planner. Map the slice to harness/runs/<id>/{TASK,CONTRACT}.md. Independent slices may run in parallel. Verify with docker compose run --rm test.