← graph

reorg-separate-universal

Reorg: separate universal role contract / project context / contributor docs

Metadata

Statusdone
Assignedagent-1160
Agent identityf51439356729d112a6c404803d88015d5b44832c6c584c62b96732b63c2b0c7e
Created2026-04-29T17:53:13.838338469+00:00
Started2026-04-29T17:53:46.302444296+00:00
Completed2026-04-29T18:12:46.372475754+00:00
Tagsfix,docs,architecture, eval-scheduled
Eval score0.83
└ blocking impact0.88
└ completeness0.88
└ constraint fidelity0.55
└ coordination overhead0.88
└ correctness0.82
└ downstream usability0.78
└ efficiency0.75
└ intent fidelity0.90
└ style adherence0.85

Description

Description

Three categories of documentation are conflated in workgraph today:

  1. Universal chat-agent role contract — how chat agents behave in ANY workgraph project. Examples: 'don't read source, use wg add, do quality pass before batch execution, distinguish dispatcher vs chat agent vs worker agent.'
  2. Project-specific context — autohaiku-vs-workgraph-vs-other-project conventions, files, goals.
  3. Workgraph contributor docs — design rationale, architecture choices, why-we-chose-X.

Today they live in:

  • workgraph repo's CLAUDE.md mixes 1 + 2 (workgraph-as-a-project)
  • workgraph repo's docs/designs/ holds 3
  • Each downstream project has its own CLAUDE.md / AGENTS.md mixing layers 1 (often missing) and 2

User confusion: 'is this a piece of documentation that may not be available unless you're actually working in the WorkGraph repo, right? Or is this about how you're supposed to work on WorkGraph itself? I think it's confusing. I don't know where one starts and where the other ends.'

Concrete consequence: chat agents in downstream projects (e.g. ~/autohaiku) may or may not follow workgraph's documented patterns (quality-pass workflow, paused-task convention, chat-vs-dispatcher distinction) depending on what bundled prompt or quickstart output they receive. The quality-pass design doc lives in workgraph source — invisible from downstream projects — yet the BEHAVIOR it describes is supposed to be universal.

Goal

Cleanly separate the three layers and make the universal role contract available wherever wg runs.

Proposal

Layer 1: Universal role contract — bundle with the wg binary

  • Promote the role-contract content (from CLAUDE.md, fallback prompt, quality-pass design) into a single canonical document
  • Ship it inside the wg binary as the output of a new wg agent-guide command (or expand wg quickstart to include it)
  • Every chat agent invocation prepends/references this content as part of its role context — regardless of which project it's working in
  • Source of truth: a single Markdown file in workgraph source (e.g. src/text/agent_guide.md) embedded via include_str! at compile time

Layer 2: Project-specific context — stays in each project's CLAUDE.md / AGENTS.md

  • Workgraph repo's CLAUDE.md becomes ONLY the workgraph-as-a-project layer-2 content (its development guidelines, smoke gate, glossary), no universal role stuff
  • The 'Chat agent role' section of current CLAUDE.md → moves to layer 1
  • The 'Service Configuration' / 'Smoke gate' / project-specific stuff stays in CLAUDE.md
  • Every project that adopts workgraph adds its own layer-2 content; layer 1 is automatically present via the bundled binary

Layer 3: Contributor docs — clearly mark as such

  • docs/designs/ and docs/research/ get a header note: 'This document is for people hacking on workgraph itself. The behavior it describes is implemented; you don't need to read this to USE workgraph.'
  • Optional: add a top-level docs README that explains the three layers and where each thing lives

Validation

  • wg agent-guide command exists; outputs the universal role contract Markdown
  • CLAUDE.md in workgraph repo contains only layer-2 content (workgraph-as-a-project); the 'Chat agent role' / 'For All Agents' / 'Cycles' / 'Task description requirements' / 'Smoke gate' sections that are universal move to the bundled agent-guide
  • A chat agent invoked in a non-workgraph project (e.g. ~/autohaiku) gets the universal role contract via the bundled prompt OR via reading wg agent-guide output at session start
  • docs/designs/ and docs/research/ get the contributor-only header
  • Cross-reference: the quality-pass design doc + phantom-edge analysis explicitly link to the bundled role contract that supersedes them as the source of behavior
  • cargo build + cargo test pass
  • cargo install --path . was run before claiming done

Out of scope (deliberate)

  • Multi-language docs / i18n
  • Generating role contract per-handler (claude vs codex variants) — single Markdown for now; the handler's prompting layer can adapt as needed
  • Versioned / pinned role contracts — single file, evolves with the binary

Depends on

Required by

Log