Hugging Face's logo

Spaces:
augment17
/
logic-engine
Sleeping

App Files Community
logic-engine / specs /001-openclaw-integration /tasks.md
ghostdrive1's picture
ghostdrive1
Upload folder using huggingface_hub
116524e verified
preview code
|
Raw
History Blame Contribute Delete
11.6 kB

Tasks: OpenClaw Integration

Input: Design documents from /specs/001-openclaw-integration/ Prerequisites: plan.md, spec.md, data-model.md, research.md, contracts/cli.md, quickstart.md

Tests: Included — plan.md specifies test files and CLAUDE.md requires tests for new features (R-009).

Organization: Tasks grouped by user story to enable independent implementation and testing.

Format: [ID] [P?] [Story] Description

  • [P]: Can run in parallel (different files, no dependencies)
  • [Story]: Which user story this task belongs to (e.g., US1, US2, US3, US4)
  • Include exact file paths in descriptions

Phase 1: Setup

Purpose: Create package structure for the new OpenClaw integration

  • T001 Create ace/integrations/openclaw/ package directory with __init__.py

Phase 2: Foundational (Pipeline Steps)

Purpose: Implement the two new pipeline steps that ALL user stories depend on

CRITICAL: No user story work can begin until this phase is complete

  • T002 [P] Implement LoadTracesStep in ace/steps/load_traces.py — generic step that reads JSONL file at ctx.sample, parses lines into list[dict], places on ctx.trace; requires={"sample"}, provides={"trace"}; skip unparseable lines gracefully per FR-010 and data-model.md validation rules
  • T003 [P] Implement OpenClawToTraceStep (pass-through) in ace/integrations/openclaw/to_trace.py — requires={"trace"}, provides={"trace"}; for now returns ctx unchanged (transformation logic deferred per user decision); follow existing ToTrace step pattern from ClaudeCodeToTrace/BrowserToTrace
  • T004 Export OpenClawToTraceStep from ace/integrations/openclaw/__init__.py and add to ace/integrations/__init__.py exports; export LoadTracesStep from ace/steps/__init__.py

Checkpoint: Pipeline steps ready — user story implementation can now begin

Phase 3: User Story 1 — One-Off Learning from Past Sessions (Priority: P1) MVP

Goal: Developer runs a single command and ACE discovers session transcripts, parses them, runs the learning pipeline, and saves strategies to a persistent skillbook file.

Independent Test: Provide sample JSONL files, run the script, verify strategies extracted and saved to ace_skillbook.json.

Acceptance: FR-001, FR-002, FR-003, FR-004, FR-010, FR-011, FR-012, FR-013

Implementation for User Story 1

  • T005 [US1] Rewrite examples/openclaw/learn_from_traces.py: remove broken parse_session_jsonl() function; implement discover_sessions() that globs ~/.openclaw/agents/<agent_id>/sessions/*.jsonl using env vars OPENCLAW_HOME, OPENCLAW_AGENT_ID per R-005 and contracts/cli.md; report clear error if directory missing per edge cases
  • T006 [US1] Implement pipeline composition in examples/openclaw/learn_from_traces.py: for each discovered session, run LoadTracesStep → OpenClawToTraceStep → learning_tail() using TraceAnalyser.from_roles() with LiteLLMClient, Reflector, SkillManager; configure model via ACE_MODEL env var per FR-012
  • T007 [US1] Implement skillbook load/save in examples/openclaw/learn_from_traces.py: load from ~/.openclaw/ace_skillbook.json via Skillbook.load_from_file() (create new if missing); save after learning via Skillbook.save_to_file() per FR-004 and R-006
  • T008 [US1] Implement summary reporting in examples/openclaw/learn_from_traces.py per CLI contract output format: sessions discovered, already processed, new to process, parsed/skipped counts, strategies before/after/new, latest strategy preview per FR-011
  • T009 [US1] Implement CLI entry point with argparse in examples/openclaw/learn_from_traces.py: --dry-run and --reprocess flags (wired in later phases), error handling for missing API key and corrupted skillbook per edge cases, if __name__ == "__main__" block per FR-013

Checkpoint: One-off learning fully functional — can discover, parse, learn, and save strategies

Phase 4: User Story 2 — Strategy Sync to Agent Workspace (Priority: P2)

Goal: Learned strategies are injected into the OpenClaw agent's AGENTS.md between marker boundaries so the agent reads them on next session.

Independent Test: After learning, verify AGENTS.md contains strategies between <!-- ACE:SKILLBOOK:START/END --> markers with existing content preserved.

Acceptance: FR-005, FR-006

Implementation for User Story 2

  • T010 [US2] Implement sync_to_agents_md() in examples/openclaw/learn_from_traces.py: use wrap_skillbook_context() to format strategies; write between <!-- ACE:SKILLBOOK:START --> / <!-- ACE:SKILLBOOK:END --> markers per contracts/cli.md AGENTS.md Marker Contract; replace if markers exist, append if not; preserve content outside markers per FR-006; create file if missing; use OPENCLAW_WORKSPACE env var
  • T011 [US2] Integrate sync into main() flow in examples/openclaw/learn_from_traces.py: call sync_to_agents_md() after skillbook save; skip sync in dry-run mode; report sync path in summary output

Checkpoint: Full learn-and-sync cycle works — strategies extracted and injected into workspace

Phase 5: User Story 3 — Incremental Processing (Priority: P3)

Goal: Only new sessions are processed on subsequent runs; --reprocess overrides to reprocess all.

Independent Test: Run twice — second run skips already-processed sessions. Run with --reprocess — all sessions reprocessed.

Acceptance: FR-007, FR-008

Implementation for User Story 3

  • T012 [US3] Implement processed log read/write in examples/openclaw/learn_from_traces.py: read/write ~/.openclaw/ace_processed.txt as newline-delimited sorted session filenames per data-model.md ProcessedLog; filter discover_sessions() output to exclude already-processed files per FR-007
  • T013 [US3] Wire --reprocess flag in examples/openclaw/learn_from_traces.py: when set, ignore processed log and process all discovered sessions per FR-008; update processed log after successful processing regardless of flag

Checkpoint: Incremental processing works — repeat runs skip processed sessions, --reprocess overrides

Phase 6: User Story 4 — Dry Run Preview (Priority: P4)

Goal: --dry-run parses sessions and reports findings without running the learning pipeline or modifying any files.

Independent Test: Run with --dry-run, verify no skillbook/workspace/processed-log files created or modified.

Acceptance: FR-009

Implementation for User Story 4

  • T014 [US4] Wire --dry-run flag in examples/openclaw/learn_from_traces.py: when set, discover and parse sessions, display summary of extracted data (session count, trace previews), but skip TraceAnalyser.run(), skip Skillbook.save_to_file(), skip sync_to_agents_md(), skip processed log write per FR-009

Checkpoint: All 4 user stories independently functional

Phase 7: Polish & Testing

Purpose: Tests, documentation, and cross-cutting validation

  • T015 [P] Unit tests for LoadTracesStep in tests/test_load_traces_step.py: test JSONL parsing, empty file, missing file, unparseable lines skipped, valid multi-line JSONL; use sample JSONL fixture from examples/openclaw/b3db607f-*.jsonl
  • T016 [P] Unit tests for OpenClawToTraceStep in tests/test_openclaw.py: test pass-through behavior, verify requires/provides contract, verify step returns context unchanged; use MockLLMClient pattern from existing tests per R-009
  • T017 End-to-end test in tests/test_openclaw.py: test full pipeline LoadTracesStep → OpenClawToTraceStep → learning_tail() with MockReflector and MockSkillManager; verify skillbook receives new strategies; use sample JSONL fixture
  • T018 Update examples/openclaw/README.md with current usage matching quickstart.md and contracts/cli.md

Dependencies & Execution Order

Phase Dependencies

  • Setup (Phase 1): No dependencies — start immediately
  • Foundational (Phase 2): Depends on Phase 1 — T002/T003 need the package directory from T001
  • US1 (Phase 3): Depends on Phase 2 — needs LoadTracesStep and OpenClawToTraceStep
  • US2 (Phase 4): Depends on US1 — sync needs a working learning flow to produce strategies
  • US3 (Phase 5): Depends on US1 — incremental processing adds to the base learning flow
  • US4 (Phase 6): Depends on US1 — dry-run modifies the base learning flow
  • Polish (Phase 7): Depends on Phase 2 (tests for steps) and US4 (all features complete for e2e test)

User Story Dependencies

  • US1 (P1): Requires Foundational (Phase 2) — core learning flow
  • US2 (P2): Requires US1 — needs working skillbook to sync
  • US3 (P3): Requires US1 — adds filtering on top of discovery
  • US4 (P4): Requires US1 — adds early-exit branch to main flow
  • US3 and US4 are independent of each other — can be implemented in either order after US1

Within Each Phase

  • T002 and T003 are parallel (different files)
  • T005 → T006 → T007 → T008 → T009 are sequential (same file, building up)
  • T010 → T011 are sequential (same file)
  • T012 → T013 are sequential (same file)
  • T015 and T016 are parallel (different test files)

Parallel Opportunities

  • Phase 2: T002 (LoadTracesStep) and T003 (OpenClawToTraceStep) — different files
  • Phase 7: T015 (test_load_traces_step.py) and T016 (test_openclaw.py) — different files
  • Cross-phase: T015 can start as soon as T002 completes; T016 can start as soon as T003 completes

Parallel Example: Foundational Phase 

# Launch both pipeline steps in parallel (different files):
Task: "Implement LoadTracesStep in ace/steps/load_traces.py"
Task: "Implement OpenClawToTraceStep in ace/integrations/openclaw/to_trace.py"

Parallel Example: Testing Phase 

# Launch both test files in parallel:
Task: "Unit tests for LoadTracesStep in tests/test_load_traces_step.py"
Task: "Unit tests for OpenClawToTraceStep in tests/test_openclaw.py"

Implementation Strategy

MVP First (User Story 1 Only)

  1. Complete Phase 1: Setup (T001)
  2. Complete Phase 2: Foundational (T002–T004)
  3. Complete Phase 3: User Story 1 (T005–T009)
  4. STOP and VALIDATE: Run script against sample JSONL, verify strategies saved
  5. If working → continue to US2–US4

Incremental Delivery

  1. Setup + Foundational → Pipeline steps ready
  2. Add US1 → Test with sample JSONL → Core learning works (MVP!)
  3. Add US2 → Verify AGENTS.md updated → Full loop closed
  4. Add US3 → Run twice, verify incremental → Production-ready
  5. Add US4 → Verify dry-run → Developer-friendly
  6. Polish → Tests + docs → Ship-ready

Notes

  • T003 (OpenClawToTraceStep) is a pass-through for now — transformation logic deferred per user decision
  • The existing learn_from_traces.py (345 lines) will be rewritten starting at T005, not patched incrementally
  • Sample JSONL fixture: examples/openclaw/b3db607f-7ae8-4089-b806-44800e961672.jsonl
  • MockLLMClient, MockReflector, MockSkillManager patterns from tests/conftest.py and tests/test_ace_steps.py
  • All env var defaults per contracts/cli.md: OPENCLAW_HOME=~/.openclaw, OPENCLAW_AGENT_ID=main, ACE_MODEL=anthropic/claude-sonnet-4-20250514