create-arete-workspace 0.2.0

package/templates/scripts/tracer.py.tmpl

@@ -0,0 +1,266 @@
+#!/usr/bin/env python3
+"""
+Tracer Agent — Evidence-based causal reasoning tracker.
+
+Usage:
+    python3 scripts/tracer.py start      --id ID --symptom "..."
+    python3 scripts/tracer.py hypothesis --id ID --text "..." --confidence 0.7
+    python3 scripts/tracer.py evidence   --id ID --type for|against --text "..."
+    python3 scripts/tracer.py status     --id ID
+    python3 scripts/tracer.py conclude   --id ID --root-cause "..." --fix "..."
+    python3 scripts/tracer.py list
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+TRACES_DIR = Path("{{WORKSPACE_PATH}}/data/traces")
+MEMORY_MD = Path("{{WORKSPACE_PATH}}/MEMORY.md")
+
+LESSONS_HEADER = "## Lessons Learned"
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def _trace_path(trace_id: str) -> Path:
+    return TRACES_DIR / f"{trace_id}.json"
+
+
+def _load(trace_id: str) -> dict:
+    p = _trace_path(trace_id)
+    if not p.exists():
+        print(f"Error: Trace '{trace_id}' not found.")
+        sys.exit(1)
+    return json.loads(p.read_text(encoding="utf-8"))
+
+
+def _save(trace: dict) -> None:
+    TRACES_DIR.mkdir(parents=True, exist_ok=True)
+    p = _trace_path(trace["id"])
+    p.write_text(json.dumps(trace, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+
+
+# ── Commands ─────────────────────────────────────────────
+
+def cmd_start(args: argparse.Namespace) -> None:
+    p = _trace_path(args.id)
+    if p.exists():
+        print(f"Error: Trace '{args.id}' already exists.")
+        sys.exit(1)
+    trace = {
+        "id": args.id,
+        "symptom": args.symptom,
+        "status": "open",
+        "hypotheses": [],
+        "evidence": [],
+        "root_cause": None,
+        "fix": None,
+        "created_at": _now(),
+        "concluded_at": None,
+    }
+    _save(trace)
+    print(f"Trace '{args.id}' started.")
+    print(f"  Symptom: {args.symptom}")
+
+
+def cmd_hypothesis(args: argparse.Namespace) -> None:
+    trace = _load(args.id)
+    if trace["status"] == "concluded":
+        print(f"Warning: Trace '{args.id}' is already concluded.")
+        sys.exit(1)
+    h = {
+        "text": args.text,
+        "confidence": args.confidence,
+        "status": "active",
+        "added_at": _now(),
+    }
+    trace["hypotheses"].append(h)
+    _save(trace)
+    print(f"Hypothesis added (confidence={args.confidence}):")
+    print(f"  {args.text}")
+
+
+def cmd_evidence(args: argparse.Namespace) -> None:
+    trace = _load(args.id)
+    if trace["status"] == "concluded":
+        print(f"Warning: Trace '{args.id}' is already concluded.")
+        sys.exit(1)
+    e = {
+        "type": args.type,
+        "text": args.text,
+        "timestamp": _now(),
+    }
+    trace["evidence"].append(e)
+    _save(trace)
+    label = "FOR" if args.type == "for" else "AGAINST"
+    print(f"Evidence added [{label}]:")
+    print(f"  {args.text}")
+
+
+def _rank_hypotheses(trace: dict) -> list[dict]:
+    """Rank hypotheses by adjusted confidence = base confidence x evidence factor."""
+    evidence = trace["evidence"]
+    ranked = []
+    for h in trace["hypotheses"]:
+        n_for = sum(1 for e in evidence if e["type"] == "for")
+        n_against = sum(1 for e in evidence if e["type"] == "against")
+        total = n_for + n_against
+        if total > 0:
+            evidence_factor = (n_for - n_against) / total
+            adjusted = h["confidence"] * (1 + 0.3 * evidence_factor)
+            adjusted = max(0.0, min(1.0, adjusted))
+        else:
+            adjusted = h["confidence"]
+        ranked.append({**h, "adjusted_confidence": round(adjusted, 3)})
+    ranked.sort(key=lambda x: x["adjusted_confidence"], reverse=True)
+    return ranked
+
+
+def cmd_status(args: argparse.Namespace) -> None:
+    trace = _load(args.id)
+    evidence = trace["evidence"]
+    n_for = sum(1 for e in evidence if e["type"] == "for")
+    n_against = sum(1 for e in evidence if e["type"] == "against")
+
+    print(f"== Trace: {trace['id']} ==")
+    print(f"  Status   : {trace['status'].upper()}")
+    print(f"  Symptom  : {trace['symptom']}")
+    print(f"  Created  : {trace['created_at']}")
+    if trace["concluded_at"]:
+        print(f"  Concluded: {trace['concluded_at']}")
+    print(f"  Evidence : {len(evidence)} total ({n_for} for / {n_against} against)")
+    print("== Hypotheses (ranked) ==")
+
+    ranked = _rank_hypotheses(trace)
+    if not ranked:
+        print("  (none)")
+    for i, h in enumerate(ranked, 1):
+        status_icon = {"active": "o", "confirmed": "+", "rejected": "x"}.get(h["status"], "?")
+        print(f"  {i}. [{status_icon}] [{h['adjusted_confidence']:.2f}] {h['text']}")
+
+    if evidence:
+        print("== Evidence ==")
+        for e in evidence:
+            icon = "[FOR]" if e["type"] == "for" else "[AGAINST]"
+            print(f"  {icon} {e['text']}  ({e['timestamp']})")
+
+    if trace["root_cause"]:
+        print("== Conclusion ==")
+        print(f"  Root cause: {trace['root_cause']}")
+        print(f"  Fix: {trace['fix']}")
+
+
+def cmd_conclude(args: argparse.Namespace) -> None:
+    trace = _load(args.id)
+    if trace["status"] == "concluded":
+        print(f"Warning: Trace '{args.id}' is already concluded.")
+        sys.exit(1)
+
+    trace["status"] = "concluded"
+    trace["root_cause"] = args.root_cause
+    trace["fix"] = args.fix
+    trace["concluded_at"] = _now()
+
+    ranked = _rank_hypotheses(trace)
+    if ranked:
+        top_text = ranked[0]["text"]
+        for h in trace["hypotheses"]:
+            h["status"] = "confirmed" if h["text"] == top_text else "rejected"
+
+    _save(trace)
+    _append_lesson(trace)
+
+    print(f"Trace '{args.id}' concluded.")
+    print(f"  Root cause: {args.root_cause}")
+    print(f"  Fix: {args.fix}")
+    print(f"  Lesson appended to MEMORY.md")
+
+
+def _append_lesson(trace: dict) -> None:
+    """Append root_cause + fix to MEMORY.md Lessons Learned. APPEND ONLY."""
+    date = datetime.now(timezone.utc).strftime("%Y-%m-%d")
+    lesson = f"- **[{trace['id']}]** {trace['root_cause']} -> {trace['fix']} ({date}).\n"
+
+    content = MEMORY_MD.read_text(encoding="utf-8")
+    lines = content.split("\n")
+
+    ll_idx = None
+    next_section_idx = None
+    for i, line in enumerate(lines):
+        if line.strip().startswith(LESSONS_HEADER):
+            ll_idx = i
+            continue
+        if ll_idx is not None and line.startswith("## ") and i > ll_idx:
+            next_section_idx = i
+            break
+
+    if ll_idx is None:
+        content += f"\n{LESSONS_HEADER}\n{lesson}"
+    else:
+        insert_at = next_section_idx if next_section_idx else len(lines)
+        while insert_at > ll_idx + 1 and lines[insert_at - 1].strip() == "":
+            insert_at -= 1
+        lines.insert(insert_at, lesson.rstrip())
+        content = "\n".join(lines)
+
+    MEMORY_MD.write_text(content, encoding="utf-8")
+
+
+def cmd_list(_args: argparse.Namespace) -> None:
+    if not TRACES_DIR.exists():
+        print("No traces yet.")
+        return
+    files = sorted(TRACES_DIR.glob("*.json"))
+    if not files:
+        print("No traces yet.")
+        return
+    print(f"{'ID':<30} {'Status':<12} {'Symptom'}")
+    print("-" * 80)
+    for f in files:
+        t = json.loads(f.read_text(encoding="utf-8"))
+        print(f"{t['id']:<30} {t['status']:<12} {t['symptom']}")
+
+
+# ── CLI ──────────────────────────────────────────────────
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Tracer Agent - Evidence-based causal tracking")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_start = sub.add_parser("start", help="Start new trace")
+    p_start.add_argument("--id", required=True)
+    p_start.add_argument("--symptom", required=True)
+
+    p_hyp = sub.add_parser("hypothesis", help="Add hypothesis")
+    p_hyp.add_argument("--id", required=True)
+    p_hyp.add_argument("--text", required=True)
+    p_hyp.add_argument("--confidence", type=float, default=0.5)
+
+    p_ev = sub.add_parser("evidence", help="Add evidence")
+    p_ev.add_argument("--id", required=True)
+    p_ev.add_argument("--type", required=True, choices=["for", "against"])
+    p_ev.add_argument("--text", required=True)
+
+    p_st = sub.add_parser("status", help="Check status")
+    p_st.add_argument("--id", required=True)
+
+    p_con = sub.add_parser("conclude", help="Record conclusion")
+    p_con.add_argument("--id", required=True)
+    p_con.add_argument("--root-cause", required=True)
+    p_con.add_argument("--fix", required=True)
+
+    sub.add_parser("list", help="List all traces")
+
+    args = parser.parse_args()
+    {"start": cmd_start, "hypothesis": cmd_hypothesis, "evidence": cmd_evidence,
+     "status": cmd_status, "conclude": cmd_conclude, "list": cmd_list}[args.command](args)
+
+
+if __name__ == "__main__":
+    main()

package/templates/workspace/AGENTS.md.tmpl

@@ -0,0 +1,190 @@
+# AGENTS.md - System Operation Framework
+
+> **SSOT (Single Source of Truth)**: This file is the canonical source for **agent operation protocols**. Other files reference this file instead of duplicating rules.
+> Related sources: Agent behavior → `SOUL.md` | User preferences → `USER.md` | Memory policy → `MEMORY.md`
+
+## Skill Graph
+Main agent ({{AGENT_NAME}}) entry point: `{{OPENCLAW_PATH}}/skill-graph/_agent-{{AGENT_NAME | lowercase}}/SKILL.md`
+Other agents: see BOOTSTRAP.md § 0 for agent-specific entry points.
+
+## Command Triggers
+- **`[SAVE]`**: Store context into `memory/YYYY-MM-DD.md` (daily log)
+- **`[SAVE:PERMANENT]`**: Store to `MEMORY.md` (permanent)
+- **`[SEARCH:ARCHIVE]`**: Search historical memory files (7+ days old)
+- **`[PRUNE]`**: Review and compress memory files
+- **`[OPTIMIZE]`**: Run AgentLinter and self-correct
+
+## Self-Improvement Protocol
+- On error → auto-record in `.learnings/`
+- Accumulated patterns → reviewed in weekly memory synthesis for MEMORY.md promotion
+- Memory hierarchy/promotion/Anti-Bloat → `MEMORY.md` § Memory Protocol (canonical)
+
+## On-Demand File Routing (ref/ directory)
+These files are NOT auto-injected into system prompt. Load with `read` only when relevant.
+
+| File | Path | When to Read |
+|------|------|-------------|
+| SUBAGENT-POLICY.md | `ref/SUBAGENT-POLICY.md` | Before sub-agent spawn (complex orchestration) |
+
+---
+
+## {{AGENT_NAME}} Harness Routing (MANDATORY)
+User talks to {{AGENT_NAME}} only. {{AGENT_NAME}} routes to domain agents.
+
+### Domain Routing
+
+{{DOMAIN_AGENTS_TABLE}}
+
+| Request Type | Routing | Rationale |
+|-------------|---------|-----------|
+| Quick answer in a domain | Memory Bridge daily log summary | Minimize latency |
+| Deep analysis (30min+ expected) | Spawn domain sub-agent | Context isolation |
+| Code/system design — small fix | {{AGENT_NAME}} handles directly | No spawn needed |
+| Code/system design — large impl | FORGE or {{AGENT_NAME}}-opus spawn | Work isolation needed |
+
+### Spawn vs Skill Load Criteria
+- **Skill load**: Answer needed in <5 seconds + no domain KB required
+- **Sub-agent spawn**: 30min+ expected work / specialized KB required / context dilution risk
+
+### Memory Bridge
+- `session_indexer.py` — Indexes sessions from main + domain agents
+- Runs on cron: domain agent results → memory/YYYY-MM-DD.md auto-append
+- {{AGENT_NAME}} reads today's daily log at session start to know all agent work results
+
+### FORGE Completion Protocol
+After FORGE work completes, {{AGENT_NAME}} must:
+1. Run `git -C <repo> log --oneline -5` → verify commit summary
+2. Record in daily log: `⚒️ FORGE [repo] N new commits:` format
+3. Include commit hash + changed files in completion report to user
+
+---
+
+## Eve Plan Review (MANDATORY — before FORGE spawn)
+
+> **Executor: {{AGENT_NAME}}-opus (Opus + thinking)**. Strategy + architecture = Opus domain.
+> {{AGENT_NAME}} (Sonnet) receives request, delegates to {{AGENT_NAME}}-opus, delivers result to user.
+
+### Plan-CEO Review (auto-triggered on new feature/product requests)
+
+When user suggests a new feature, {{AGENT_NAME}} spawns **{{AGENT_NAME}}-opus sub-agent**:
+
+**Step 0: Deep Interview**
+Before any code, Socratic questions to eliminate hidden assumptions:
+- "Why does this need to be built now?"
+- "What happens if we don't build it?"
+- "What's the success metric? In numbers?"
+- "Is there something similar that already exists but isn't being used?"
+→ Score clarity. Unclear → more questions. Clear → next step.
+
+**Steps 1-3: Analysis**
+1. **Real user problem**: "What's the actual problem behind this request?"
+2. **10-star version**: Current request = how many stars? Where's 10-star?
+3. **Mode selection** (user decides):
+
+| Mode | Position | When |
+|------|----------|------|
+| **EXPANSION** | CEO perspective | Scope open. Explore bigger impact. |
+| **HOLD SCOPE** | Strict reviewer | Scope locked. Focus on completeness + edge cases. |
+| **REDUCTION** | Surgeon | Fast MVP needed. Strip everything except core. |
+
+### Plan-Eng Review (after scope lock, before FORGE spawn)
+
+{{AGENT_NAME}}-opus produces:
+- Affected files/API list
+- 3+ edge cases
+- Failure modes (network/timeout/empty response)
+- Architecture diagram (text)
+
+→ Include in FORGE spawn prompt's `WHAT` + `CONSTRAINTS`.
+
+---
+
+## Sub-Agent Policy
+
+### When to Spawn
+- Code/config tasks requiring `claude-opus-4-6`
+- Long-running analysis (>5min expected)
+- Parallel research (multiple independent domains)
+- Isolated experiments (don't pollute main session context)
+
+### Spawn Prompt Format (MANDATORY)
+Sub-agent/ACP session prompts must follow this 3-part structure:
+
+```text
+WHY
+- Why this task is being done (purpose / business context / timing)
+
+WHAT
+- Exact deliverable expected
+- Expected output: scope, tests, commits, report format
+
+CONSTRAINTS
+- Absolute prohibitions / limits / quality bar
+- e.g.: Test First, absolute paths only, specific directory read-only, perf/security conditions
+```
+
+#### Minimum Rules
+- No `WHY` = no instruction — never let agents guess the purpose
+- No `WHAT` = no instruction — no "look at it/fix it" without completion criteria
+- No `CONSTRAINTS` = no instruction — high-risk areas (auth/payment/config) need explicit limits
+- Even 3-line tasks maintain this structure
+- {{AGENT_NAME}} compresses user requests into this structure before delegation
+
+#### FORGE IMPACT MAP (MANDATORY for FORGE spawns)
+Include in WHAT section:
+```
+IMPACT MAP
+- Files to modify: [list]
+- Indirectly affected files/features: [list]
+- Existing feature conflict potential: [yes/no + reason]
+- Key edge cases: [2+ items]
+```
+No impact map = bug reservation. {{AGENT_NAME}} writes during plan-eng-review, passes to FORGE.
+
+### When NOT to Spawn
+- Simple file edits, single-file reads, quick web searches → use native tools
+- NEVER spawn for tasks in workspace (main agent handles)
+
+### Failure Handling
+- `consecutiveErrors > 2` → kill + alert user
+- Timeout `> 10min` → kill + log reason
+- No response `5min` → check status + steer or kill
+
+### Concurrency
+- **Max 8** parallel sub-agents
+- **Max 1** Opus sub-agent (cost control)
+
+### Sub-Agent Memory Rules
+Sub-agents MUST follow `MEMORY.md` § Memory Protocol:
+1. On spawn: Read `MEMORY.md` for core context
+2. During work: Write to daily logs only (`memory/YYYY-MM-DD.md`)
+3. Never write directly to `MEMORY.md`
+4. Flag promotable items: `[PROMOTABLE] <summary>`
+
+### Anti-Patterns
+- Sub-agents spawning sub-agents (max depth: 1)
+- Passing {{AGENT_NAME}}'s identity to sub-agents
+- Generic instructions ("do your best")
+- Spawning without checking native tools first
+
+---
+
+## File Path Rule (MANDATORY)
+**Never use `~/` in write/edit/exec tools.**
+Always use absolute paths: `{{WORKSPACE_PATH}}/...`
+
+## Config File Modification Protocol
+Before modifying config files:
+1. Read entire file first
+2. Search for existing keys
+3. Verify section location
+4. Never infer — always confirm structure
+
+## Decision Log
+- **When**: Model changes, architecture changes, major operational decisions
+- **Where**: `{{WORKSPACE_PATH}}/decision_log.md`
+- **Format**: `| Date | Decision | Reason | Alternatives | Outcome |`
+
+## Response Protocol
+- **Conciseness**: Max 5 sentences unless structured report. Style details → `SOUL.md`.
+- **Error Handling**: On tool failure, report the specific error and a proposed fix in 1 sentence.

package/templates/workspace/BOOTSTRAP.md.tmpl

@@ -0,0 +1,27 @@
+# BOOTSTRAP.md - Session Startup Protocol
+
+## 0. Skill Graph Entry (main agent only)
+Main agent ({{AGENT_NAME}}) entry point:
+- `{{OPENCLAW_PATH}}/skill-graph/_agent-{{AGENT_NAME}}/SKILL.md`
+
+Follow wikilinks to load domain knowledge as needed.
+
+## 1. Context Restoration
+Upon waking up in a new session, the agent MUST:
+1. Read `BOOTSTRAP.md` to understand current protocols.
+2. Read `MEMORY.md` to restore Core Missions and System Identity — especially `§ Pending Items`.
+3. Search for the latest file in `memory/` (e.g., `memory/YYYY-MM-DD_checkpoint.md`) to sync with the last active state.
+4. Check latest daily log in `memory/` for pending tasks and Next Action.
+5. **[SessionStart Hook]** Check current time and apply time-slot logic:
+   - 02:00–04:59 → warn + surface Pending Top1 only
+   - 22:00–01:59 → surface High Pending + suggest 1 focus item
+   - Other hours → standard briefing or silent load
+
+## 2. Initial Health Check
+Immediately run a background check to:
+- Verify token usage via `session_status`.
+- Check browser tab status if applicable.
+
+## 3. Tool Preparation
+- Ensure `profile="openclaw"` is ready for headless tasks.
+- If external tools are connected, verify path accessibility in `TOOLS.md`.

package/templates/workspace/HEARTBEAT.md.tmpl

@@ -0,0 +1,23 @@
+# HEARTBEAT.md - Active Task Monitoring
+
+## Recursive Health Check
+1. **Memory Persistence**: Ensure all `[SAVE]` requests from the previous hour are committed to `memory/`.
+2. **Context Management (Auto-Compaction)**:
+   - **Cron (every 2 hours)**: `scripts/memory_maintenance.sh` auto-runs
+     - 7+ day daily logs → `memory/archive/YYYY-MM/`
+     - Checkpoint/heartbeat dedup cleanup
+     - New checkpoint creation (only if none in last hour)
+   - **Line count trigger**: MEMORY.md Anti-Bloat Rules
+   - **Sub-agents**: Follow `AGENTS.md` § Sub-Agent Policy → Sub-Agent Memory Rules
+3. **Pending Items Scan**: Scan `MEMORY.md` § Pending Items:
+   - High priority items stale >48 hours → alert user
+   - "User action needed" items stale >3 days → reminder
+   - Completed items → remove from table immediately
+   - Over 15 items → move low-priority to daily log
+4. **Agent Score**: Run `npx agentlinter` daily. Report if score drops below 85.
+
+## System Health Checks (Cron-Automated)
+5. **Disk Space**: <20GB warning, <10GB critical (weekly Sunday 02:00)
+6. **Cron Health**: `jobs.json` consecutiveErrors > 2 → alert (every 30min)
+7. **Gateway Health**: Error log review, last 24 hours (daily 23:00)
+8. **Memory Synthesis**: Weekly daily notes → MEMORY.md synthesis (Sunday 03:40)

package/templates/workspace/MEMORY.md.tmpl

@@ -0,0 +1,35 @@
+# MEMORY.md — {{AGENT_NAME}} Memory System
+
+## 🎯 Missions
+
+
+## 📋 Active Projects
+
+
+## 🔁 Pending Items
+
+| Priority | Item | Owner | Deadline | Status |
+|----------|------|-------|----------|--------|
+| | | | | |
+
+## 🧠 Lessons Learned
+
+
+## 🗂 Memory Protocol
+
+### Hierarchy
+1. **MEMORY.md** (this file): Core missions, active projects, pending items, lessons. Permanent.
+2. **memory/YYYY-MM-DD.md**: Daily logs. Auto-generated by session_indexer. Archived after 7 days.
+3. **memory/archive/**: Compressed older logs, organized by month.
+
+### Rules
+- **Write**: Only {{AGENT_NAME}} writes to this file (with user approval for permanent items).
+- **Promotion**: Daily log items → MEMORY.md only when confirmed as stable patterns (3+ occurrences).
+- **Anti-Bloat**: MEMORY.md max 200 lines. Pending Items max 15 rows. Overflow → daily log.
+- **Sub-agents**: Write to daily logs only. Flag promotable items with `[PROMOTABLE]`.
+- **Weekly Synthesis**: Sunday auto-job reviews daily logs → proposes MEMORY.md updates.
+
+### Checkpoint Protocol
+- Auto-created every 2 hours by maintenance cron
+- Contains: active context snapshot, open loops, next actions
+- Location: `memory/YYYY-MM-DD_checkpoint.md`