{"_id":"@aao-sh/fable-harness","_rev":"2-61549b0244b246c78a195243b93562f9","name":"@aao-sh/fable-harness","dist-tags":{"latest":"0.3.0"},"versions":{"0.2.0":{"name":"@aao-sh/fable-harness","version":"0.2.0","license":"MIT","_id":"@aao-sh/fable-harness@0.2.0","maintainers":[{"name":"lia-astc","email":"liabot.astc@gmail.com"}],"homepage":"https://github.com/AAO-SH/Fable-Harness#readme","bugs":{"url":"https://github.com/AAO-SH/Fable-Harness/issues"},"bin":{"fable-harness":"bin/fable-harness.mjs"},"dist":{"shasum":"14b3f77e284eb3f7342f62794bc852dd7e0822c8","tarball":"https://registry.npmjs.org/@aao-sh/fable-harness/-/fable-harness-0.2.0.tgz","fileCount":16,"integrity":"sha512-RgpB2IE3xK3Xh6SMqCIpoB1K3yG2D/LiWDqjixhdSgDIhp8bW0p1lZJjoYvpKXvHoUaPA4SSxXSU5OgJQY1cxQ==","signatures":[{"sig":"MEYCIQDBQnKgBy5QlIMqVg0nKBWZFoJxtR6P9v0b2aLK1d3kIAIhAJ7m3ENFyUNiOS0NeMIPnjM0tlQeiM3AR+zn4c73SWVw","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@aao-sh%2ffable-harness@0.2.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":104096},"type":"module","engines":{"node":">=18"},"gitHead":"7c82b3d57ba6d728f5ca833ca44f6208dfca6b94","scripts":{"test":"python scripts/test_install_fable_harness.py","pack:check":"npm pack --dry-run","yarn:pack:check":"yarn pack --dry-run"},"_npmUser":{"name":"lia-astc","email":"liabot.astc@gmail.com"},"repository":{"url":"git+https://github.com/AAO-SH/Fable-Harness.git","type":"git"},"_npmVersion":"10.8.2","description":"Project-local agent harness skill for traceable AI workflows.","directories":{},"_nodeVersion":"20.20.2","publishConfig":{"access":"public","registry":"https://registry.npmjs.org"},"_hasShrinkwrap":false,"packageManager":"yarn@4.9.2","_npmOperationalInternal":{"tmp":"tmp/fable-harness_0.2.0_1781662188494_0.4613154837169413","host":"s3://npm-registry-packages-npm-production"}},"0.3.0":{"name":"@aao-sh/fable-harness","version":"0.3.0","description":"Give AI agents project-local memory, planning, verification, and rollback for traceable coding work.","type":"module","license":"MIT","author":{"name":"AAO.sh"},"keywords":["ai-agents","agent-harness","codex","claude-code","ai-workflows","decision-loop","agent-memory","rag","knowledge-graph","code-graph","subagents","rollback","tdd","workflow-automation","llm-tools"],"packageManager":"yarn@4.9.2","repository":{"type":"git","url":"git+https://github.com/AAO-SH/fable-harness.git"},"homepage":"https://fable.aao.sh","bugs":{"url":"https://github.com/aao-sh/fable-harness/issues"},"bin":{"fable-harness":"bin/fable-harness.mjs"},"scripts":{"test":"python scripts/test_install_fable_harness.py","pack:check":"npm pack --dry-run","yarn:pack:check":"yarn pack --dry-run"},"publishConfig":{"registry":"https://registry.npmjs.org","access":"public"},"engines":{"node":">=18"},"_id":"@aao-sh/fable-harness@0.3.0","gitHead":"e4a7b587e95cdf6c4efadd537cf68039ffb1708b","_nodeVersion":"20.20.2","_npmVersion":"10.8.2","dist":{"integrity":"sha512-tSgRWWi6vauPOr62m7CI/v/cEYNx9iHxxapqy4q4CcWtXP70pR98SZ6jwjSre3OwxOJyVRs0m4y3Cv9twN39og==","shasum":"3d01051d163d932493d23ac7f80817432c9e0fde","tarball":"https://registry.npmjs.org/@aao-sh/fable-harness/-/fable-harness-0.3.0.tgz","fileCount":26,"unpackedSize":7060942,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@aao-sh%2ffable-harness@0.3.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDntdVUywqynmePBpWjNEPa7PnwpLuPsCj+PlPVFRNDngIgYpp8PW0Nwruxq9q6MMpep4OZfLKrwyRCMQKS6lDm8YU="}]},"_npmUser":{"name":"lia-astc","email":"liabot.astc@gmail.com"},"directories":{},"maintainers":[{"name":"lia-astc","email":"liabot.astc@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/fable-harness_0.3.0_1782138948089_0.4512712033304438"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-17T02:09:48.343Z","modified":"2026-06-22T14:35:48.711Z","0.2.0":"2026-06-17T02:09:48.713Z","0.3.0":"2026-06-22T14:35:48.388Z"},"bugs":{"url":"https://github.com/aao-sh/fable-harness/issues"},"license":"MIT","homepage":"https://fable.aao.sh","repository":{"type":"git","url":"git+https://github.com/AAO-SH/fable-harness.git"},"description":"Give AI agents project-local memory, planning, verification, and rollback for traceable coding work.","maintainers":[{"name":"lia-astc","email":"liabot.astc@gmail.com"}],"readme":"
\n \"Fable\n     \n \"Fable\n
\n\n

\n Give AI agents a local operating system for memory, planning, verification, and rollback.\n

\n\n

\n \"GitHub\n \"GitHub\n \"GitHub\n \"License\"\n \"Last\n
\n \"npm\n \"Node\n \"Build\"\n
\n \"PyPI\n \"Python\n \"Coverage\"\n

\n \"Website\"\n \"Telegram\"\n \"Discord\"\n

\n\n
\n\nFable Harness installs a project-local control layer for AI coding agents. It gives Codex, Claude Code, and compatible agents a repeatable way to remember project decisions, plan work, run decision loops, delegate safely, verify results, and roll back specific changes without turning your repository into hidden chat state.\n\n## Install\n\n### by prompt\n\nAsk your agent to install it in the current workspace:\n\n```text\nInstall the Fable-Harness skill (https://github.com/aao-sh/fable-harness) and run it to set up this workspace.\n```\n\nThe agent should handle the local project setup, choose the right surface, and run the installer with the workspace context already loaded.\n\n
\n

manually

\n\n\n \n \n \n
\n ⚠️ Fable Harness requires Python 3.9 or newer.
\n The npm entry point can launch the installer, but the installer still runs Python under the hood.\n
\n\nCheck Python version:\n\n```bash\npython --version\n```\n\n
\nInstall Python if needed\n
\n
\n for Windows\n\n```powershell\n winget install Python.Python.3.12\n```\n
\n\n
\n for macOS\n\n```bash\n brew install python@3.12\n```\n
\n\n
\n for Linux (Ubuntu/Debian)\n\n```bash\n sudo apt update && sudo apt install python3.12\n```\n
\n
\n
\n\nThen use the package-manager entry point:\n\n```bash\nnpx @aao-sh/fable-harness \"./path/to/project\" --agent auto\n```\n\nOr install into a workspace from this repository:\n\n\n \n \n \n
\n ℹ️ Use `--without-superpowers` to skip installing the Superpowers skill (not recommended).\n
\n\n```bash\npython \"./scripts/install_fable_harness.py\" \"./path/to/project\" --agent auto --with-superpowers\n```\n\nAgent targets:\n\n| Target | Writes instructions to | Installs harness in |\n|---|---|---|\n| `codex` | `AGENTS.md` | `.codex/` |\n| `claude` | `CLAUDE.md` | `.claude/` |\n| `any` | `AGENTS.md` | `.agents/` |\n| `both` | `AGENTS.md` and `CLAUDE.md` | all supported surfaces |\n| `auto` | detects the workspace | detected surface |\n\n
\n\n## Why Use It\n\nAI agents are strongest when their work is grounded in files, evidence, and repeatable checks. Fable Harness gives them that structure inside your project.\n\n### Benefits\n\n- Project-local memory instead of fragile chat-only context.\n- Decision traces for audit-sensitive work.\n- Semantic notes, RAG, and graph lookup for faster recall.\n- A native decision loop: orient, inspect, decide, act, verify, report.\n- Safer subagent planning for complex work.\n- Protected TDD evidence and closure checks.\n- Selective rollback plans instead of broad destructive resets.\n\n## Main Workflows\n\n
\nMemory\n\n![Memory workflow](assets/01_memory.png)\n\nFable Harness stores durable project knowledge in compact semantic notes, not in raw chat history. Decision traces remain audit evidence, while generated memory shards, retrieval reports, and graph files make recall faster without making every future agent reread everything.\n\nUse it when an agent needs to remember decisions, reload context, search prior work, promote trace evidence, or keep global/model memory from replacing project-local memory.\n\n
\n\n
\nPlanning\n\n![Planning workflow](assets/02_planning.png)\n\nPlanning starts from project evidence: instructions, notes, docs, source files, RAG citations, and graph orientation. If local sources are weak, the harness tells the agent to research before planning; if the task is still underspecified, it interviews the user before inventing requirements.\n\nUse it to keep plans grounded, reviewable, and tied to real files.\n\n
\n\n
\nDecision loop\n\n![Decision loop workflow](assets/03_decision_loop.png)\n\nThe decision loop is the harness core: orient, inspect, decide, act, verify, report. Native loop scripts record events, transitions, checklist evidence, subagent waves, verification, repair attempts, and closure status.\n\nUse it for non-trivial or mutating work where hidden process state would be risky.\n\n
\n\n
\nTask parallelism\n\n![Task parallelism workflow](assets/04_task_parallelism.png)\n\nFable Harness separates independent domains from dependent loop steps. Independent domains can become subagent waves; dependent steps stay ordered. This keeps parallel work fast without corrupting generated state, traces, memory, or verification order.\n\nUse it when a task spans separate files, domains, or responsibilities that can progress independently.\n\n
\n\n
\nRollback\n\n![Rollback workflow](assets/06_rollback.png)\n\nRollback is selective and reviewable. The harness creates rollback plans, checkpoints, backups, and reverse patches before applying changes. It avoids broad destructive commands when the user only wants one file, hunk, or agent change reverted.\n\nUse it when you need to undo specific work without erasing unrelated progress.\n\n
\n\n## ✨ Acknowledgements\n\n* **[Superpowers](https://github.com/obra/superpowers)**: Provides the skill framework that enables agents to run complex tasks.\n\n* Special thanks to all community contributors who help maintain and support the project.\n\n## 📚 References\n\n### Frameworks, Playbooks & Workflow Design\n* **Mark Kashef ([@MarkKashef](https://x.com/MarkKashef)):**\n * *The Fable Mindset Playbook*. Available at [Gumroad](https://markkashef.gumroad.com/l/fable-mindset).\n * *6 Dynamic Workflow Patterns for Claude Code*. Available at [Gumroad](https://markkashef.gumroad.com/l/dynamic-workflow-patterns).\n\n### Knowledge Graphs & Semantic Memory\n* **Alexander Shereshevsky ([Medium](https://medium.com/@shereshevsky)):**\n * *Your Obsidian Vault Is a Knowledge Graph. Here’s How to Make It Think (quickly)*. Published in Graph Praxis. Read on [Medium](https://medium.com/graph-praxis/your-obsidian-vault-is-a-knowledge-graph-heres-how-to-make-it-think-quickly-1487614a7682).\n* **Skjæveland, M. G.; Balog, K.; Bernard, N.; Łajewska, W.; & Linjordet, T. (2024):**\n * *An ecosystem for personal knowledge graphs: A survey and research roadmap*. *AI Open*, Volume 5, Pages 55-69. Available via [ScienceDirect](https://www.sciencedirect.com/science/article/pii/S2666651024000044).\n\n### Graph RAG Implementations\n* **Oscar Campo ([@oscampo](https://github.com/oscampo)):**\n * *Neural Composer: Local Graph RAG made easy (LightRAG integration)*. Discussion and implementation framework available on the [Obsidian Forum](https://forum.obsidian.md/t/neural-composer-local-graph-rag-made-easy-lightrag-integration/109891).\n\n

\n
\n \"AAO.sh\n \n Developed and maintained by the AAO.sh Community.
\n Released under the MIT License.\n \n
\n","readmeFilename":"README.md","keywords":["ai-agents","agent-harness","codex","claude-code","ai-workflows","decision-loop","agent-memory","rag","knowledge-graph","code-graph","subagents","rollback","tdd","workflow-automation","llm-tools"],"author":{"name":"AAO.sh"}}