䷀ Yi-Jing Agent — I Ching Six Lines AI Agent Lifecycle Framework

Fusing ancient I Ching wisdom with modern AI agent architecture. A structured lifecycle framework that prevents goal drift, enables graceful degradation, and brings philosophical depth to AI agent execution.

🧠 What is Yi-Jing Agent?

Modern AI agents suffer from three structural problems:

1. Goal Drift — Agents forget the original intent mid-task
2. Blind Impulse — Agents rush to call APIs without proper planning
3. Crash with No Recovery — One error cascades into total failure

The I Ching (易經) Six Lines framework solves this by imposing a 6-stage lifecycle on every task, where each stage (爻) has strict behavioral rules and output gates:

Line           Agent Behavior              Output Gate
────────────────────────────────────────────────────────────────
初爻 (Hidden Dragon) → Pure understanding, NO actions → Task Graph
二爻 (Dragon in Field) → Sandbox & prototyping   → Feasibility Report
三爻 (Alert Dragon) → 3D Reflection Engine      → Safety Report
四爻 (Leaping Dragon) → Authorization Gate       → Confirm / Pivot
五爻 (Flying Dragon) → Full execution            → Core Payload
上爻 (Regretful Dragon) → Memory compression     → LTM Write

🔄 Dynamic Fault Tolerance with Hexagram Mutation

When any line encounters an error, the system triggers dynamic hexagram mutation (動爻變卦) — XOR flipping that line's bit and looking up the new hexagram's strategy:

Initial (111111 ䷀ Qian) ──[API Timeout at Line 5]──→ flip bit5
                                                    ↓
Mutation (111011 ䷉ Lu) ──→ Strategy: degrade to Line 2 sandbox

🧿 3D Reflection Engine (錯綜互卦)

At Line 3, the agent performs a mandatory three-dimensional reflection:

🚀 Quick Start

Prerequisites

• Python 3.10+
• An AI agent platform (Hermes Agent, OpenClaw, AutoGPT, etc.)

Install

git clone https://github.com/yayasasapig/yi-jing-agent.git
cd yi-jing-agent
# Copy the skill to your agent's skill directory
cp -r skill/* ~/.hermes/skills/
# Or use the Python library directly
pip install -e .

Basic Usage (Python)

from src.agent_state import YiJingAgentState
from src.executor import YiJingAgentExecutor
import asyncio

async def main():
    executor = YiJingAgentExecutor()
    result = await executor.execute("Analyze this website's pricing strategy")
    print(f"Status: {result['status']}")
    print(f"Hexagram path: {' → '.join(
        t.transition_name for t in result['hexagram_history']
    )}")

asyncio.run(main())

For Hermes/OpenClaw Agents

Load the skill in your SOUL.md or task prompt:

Load the `yi-jing-agent` skill to activate the 六爻 lifecycle.

📂 Repository Structure

yi-jing-agent/
├── README.md                 # ← You are here
├── LICENSE                   # MIT
├── CONTRIBUTING.md           # How to contribute
├── docs/
│   ├── 六爻AI-Agent架構設計書.md  # Original Chinese design document (37KB)
│   └── architecture-overview.md  # English architecture summary
├── skill/
│   └── SKILL.md              # Hermes/OpenClaw skill definition
├── src/
│   ├── agent_state.py        # Core YiJingAgentState
│   ├── executor.py           # Full lifecycle executor
│   ├── hexagram_table.py     # 64 hexagrams → strategies
│   ├── reflection.py         # 3D reflection engine
│   └── yao_positions.py      # Line definitions & enums
├── examples/
│   └── six-yao-lifecycle-demo.md  # Walkthrough demo
└── .github/
    └── workflows/
        └── ci.yml            # GitHub Actions CI

📖 Documentation

🌍 Community & Contributions

This project is open for everyone to use, remix, and improve!

• Share your hexagram strategies — Found a new failure mode? Add it to the table!
• Translate — Help translate the docs to Japanese, Korean, English
• Build tools — Dashboard, VSCode extension, visualization
• Report issues — Found a bug in the lifecycle? Open an issue!

See CONTRIBUTING.md for guidelines.

📜 License

MIT — Free for personal and commercial use.

🙏 Credits

• Concept: yayafu × Gemini conversation distillation
• Implementation: Orchestrator Nova (Hermes Agent)
• Platform: OpenClaw Agent Team

「An agent that knows its time uses wisdom to move mountains.」 「識得時機嘅 Agent，用智慧四兩撥千斤。」