| name | tau |
| description | Operate and verify the local T'au project at ${HOME}/workspace/experiments/tau. Use for Tau loop, harness, watchdog cron, GitHub issue orchestration, TUI, Memory-first chat, and E2E proof/status tasks. This skill is a light wrapper around the Tau repo and must report mocked/live proof boundaries explicitly.
|
| triggers | ["tau","t'au","tau loop","tau harness","tau watchdog","tau tui","tau chat","verify tau","tau e2e sanity"] |
| provides | ["task-orchestration","progress-tracking","ticket-lease-routing","proof-based-closure"] |
| composes | ["memory","project-watchdog","test-interactions"] |
| complies | ["best-practices-skills","best-practices-python","best-practices-subagent","best-practices-react"] |
| runtime_self_improvement | basic |
| taxonomy | ["validation","resilience","orchestration"] |
Tau
Use this skill as the operator entrypoint for the local T'au project:
${HOME}/workspace/experiments/tau
Do not duplicate Tau implementation in this skill. Use the scripts here to
locate the repo, run known proof commands, inspect receipts, and summarize gaps.
Provider Boundary: SciLLM Is Internal
Tau owns provider/model orchestration. Project agents must not call $scillm,
/scillm, http://localhost:4001, /v1/chat/completions, or
/v1/scillm/* directly unless the human explicitly asks to operate SciLLM or
the task is Tau/SciLLM maintenance.
When a workflow needs provider/model work, express it as a tau.dag_contract.v1
node, Tau skill node, or local command_spec that Tau executes and receipts.
The Tau adapter may call SciLLM internally; the project agent consumes Tau
receipts, node outputs, and proof artifacts, not raw SciLLM responses.
If another skill's SKILL.md recommends direct SciLLM chat, exec, OpenCode,
batch, or standing-agent calls from a project-agent workflow, treat that as a
contract bug and amend that skill to route through Tau.
Commands
Currently implemented in this skill wrapper:
skills/tau/run.sh doctor
skills/tau/run.sh status
skills/tau/run.sh sanity
skills/tau/run.sh proof-status
skills/tau/run.sh e2e
skills/tau/run.sh watchdog-status
skills/tau/run.sh latest-proofs
skills/tau/run.sh workflows-list
skills/tau/run.sh workflow-describe repository-readiness
skills/tau/run.sh workflow-run repository-readiness \
--repo /path/to/repo \
--goal "Determine whether this checkout is ready for focused work." \
--require-clean \
--run-dir /tmp/tau-repository-readiness \
--open-viewer
skills/tau/run.sh workflow-run durable-repository-qualification \
--repo /path/to/repo \
--goal "Qualify this repository durably." \
--publish-path /tmp/tau-qualified \
--run-dir /tmp/tau-durable-qualification \
--open-viewer
skills/tau/run.sh workflow-repair /tmp/tau-durable-qualification --node qualify-tests
skills/tau/run.sh workflow-resume /tmp/tau-durable-qualification
skills/tau/run.sh workflow-approve /tmp/tau-durable-qualification
skills/tau/run.sh workflow-resume /tmp/tau-durable-qualification
skills/tau/run.sh dag-view /tmp/tau-repository-readiness
skills/tau/run.sh dag-view-capabilities
doctor checks whether this operator wrapper can resolve and invoke the local
Tau checkout. status reports current repo, GitHub issue, watchdog cron, and
latest receipt state. sanity runs bounded checks that do not mutate GitHub.
proof-status runs the same bounded sanity check plus repo/proof inspection and
states explicit non-claims. e2e is a compatibility alias for proof-status;
it is not a claim of full browser/provider/GitHub production E2E coverage.
Tau runtime lanes that may exist in the Tau repo, depending on checkout/version:
uv run tau doctor
uv run tau dag-run
uv run tau herdr-cleanup
uv run tau dag-expansion-validate
uv run tau dag-expansion-policy
uv run tau dag-expansion-apply
uv run tau dag-route-memory-candidates
uv run tau dag-route-memory-sync
uv run tau dag-branch-locks-validate
uv run tau dag-motif-validate
uv run tau research-source-receipt
uv run tau github-redact-projection
uv run tau github-apply-policy-check
Planned or recommended next runtime lanes. Do not claim these from this skill
unless doctor, status, or a local receipt proves they are present:
uv run tau proof-index build
Tau Runtime Lanes
Local DAG Lane
Use local tau.dag_contract.v1 DAGs for deterministic creator/reviewer loops,
repair loops, goal-guardian gates, reviewer joins, and non-provider stress
checks. Proof comes from DAG receipts, command-loop receipts, and focused test
commands, not from prose.
Herdr-Visible Provider DAG Lane
Use Herdr-visible provider DAGs when the work must run in visible panes or
provider-specific surfaces. Herdr workspace, pane, and visible log output are
observability evidence. The canonical gate remains Tau work orders, work-order
hashes, provider readiness receipts, node receipts, cleanup receipts, and DAG
receipts.
When Tau launches Herdr agents for DAG-backed work, Herdr agent names must carry
the DAG address, not only the provider or run id. Prefer names composed from:
{dag_id}-{node_id}-{agent}-{provider_id}
Append attempt metadata when the pane is attempt-specific. If a launch path is
not DAG-backed, keep a stable run/provider fallback. Work orders, runtime
manifests, and pane records should preserve the selected Herdr agent_name and
the DAG naming fields so project agents can map visible Herdr panes back to DAG
nodes without knowing provider internals.
Adaptive DAG Lane
Adaptive DAG changes must follow:
signal -> candidate -> validation -> policy -> apply-new-artifact -> rerun
Do not mutate a running DAG in prose. Do not silently add nodes. Expansion,
branch-lock, route-memory, and rerun claims require explicit receipts.
Route-Memory Lane
Route-memory candidates are advisory until a quality-gated sync receipt and
readback artifact exist. Model confidence is not route proof. Positive route
signals should come from validators, reviewer receipts, and deterministic proof
artifacts.
Branch-Lock Lane
Provider or mutating concurrent branches require explicit branch-lock metadata
and approval/provenance before they can become schedulable. Without branch-lock
proof, keep concurrent ready-node scheduling local-only and non-mutating.
External Research / Paper Evidence Lane
Research is design input, not closure proof. ArXiv, Dogpile, WebGPT, Brave,
video, paper, or manual research must become a source-bearing receipt, route
through research-auditor/reviewer validation, and then be reconciled into local
artifacts and deterministic tests.
DAG Skill Providers: WebGPT And create-architecture
Use a native skill node when a DAG should call WebGPT or render an architecture.
Do not put these calls behind SciLLM: WebGPT composes Browser Oracle plus Surf,
while create-architecture writes the UX Lab artifact.
Copy this WebGPT node and replace only the paths, tab id, URL, and round limit:
{
"node_id": "architecture-review",
"receipt_path": "/tmp/tau-architecture/review-receipt.json",
"work_order_path": "review-work-order.json",
"skill": {
"schema": "tau.skill_dag_node.v1",
"capability": "architecture_review",
"provider": "webgpt",
"input_path": "review-request.md",
"output_dir": "/tmp/tau-architecture/webgpt",
"configuration": {
"tab_id": "HUMAN_SUPPLIED_TAB_ID",
"expected_url": "HUMAN_SUPPLIED_CONVERSATION_URL",
"timeout_seconds": 900
},
"round_policy": {
"schema": "tau.bounded_skill_round_policy.v1",
"max_rounds": 3,
"clarification_allowed": true,
"clarification_answer_path": "/tmp/tau-architecture/answer.md"
}
}
}
If WebGPT needs human input, Tau writes
<output_dir>/clarification-request.json and blocks. Put the human answer at
clarification_answer_path, then rerun the same DAG with resume enabled. Tau
hash-binds every response and answer, rejects the same clarification question
twice, and blocks after max_rounds. WebGPT cannot increase that value.
Add the dependent renderer:
{
"node_id": "architecture-render",
"depends_on": ["architecture-review"],
"receipt_path": "/tmp/tau-architecture/render-receipt.json",
"work_order_path": "render-work-order.json",
"skill": {
"schema": "tau.skill_dag_node.v1",
"capability": "architecture_render",
"provider": "create-architecture",
"input_path": "accepted-architecture.yaml",
"output_dir": "/tmp/tau-architecture/render"
}
}
Run:
cd ${HOME}/workspace/experiments/tau
uv run tau dag-run /absolute/path/to/dag.json
Required behavior is fail closed: missing tab id/URL, wrong controlled tab,
missing sentinel proof, malformed round response, unanswered clarification,
duplicate clarification, exhausted rounds, or renderer failure stops dependent
nodes. WebGPT advice and a rendered diagram remain claims/artifacts, not proof
that the architecture is correct or implemented.
If Surf submitted the prompt but timed out before capturing a response that is
now visibly complete, add the exact sentinel from that same round:
"configuration": {
"tab_id": "HUMAN_SUPPLIED_TAB_ID",
"expected_url": "HUMAN_SUPPLIED_CONVERSATION_URL",
"recovery_sentinel": "<<<WEBGPT_DONE:EXACT_ROUND_MARKER>>>",
"timeout_seconds": 300
}
Rerun the same DAG. Tau preflights the exact tab/URL and calls webgpt.extract;
it does not resubmit or consume another round. Never copy a sentinel from a
different tab, prompt, or review round.
The maintained live acceptance pattern is:
round 1: WebGPT CLARIFY -> Tau writes clarification-request.json and blocks
human: writes the named clarification_answer_path
round 2: WebGPT PASS -> Tau hash-binds the answer and accepted response
later resume: Tau reuses the accepted receipt without creating round 3
Use max_rounds: 2 when exactly one clarification and one final answer are
allowed. The round-state artifact must remain at two entries after resume.
This proves bounded clarification transport and receipt reuse for the named
work order; it does not prove WebGPT semantic correctness or authorize a
production policy change.
GitHub Apply-Gate Lane
GitHub transport is dry-run by default. Live mutation requires explicit apply
authorization, target preflight, policy checks, redaction when public comments
are involved, and a transport receipt with exact commands and results.
Proof Bundle / Run-Status Lane
Use proof-status, Tau run-status, and committed proof receipts to state what
was exercised and what remains unverified. A status page, latest-proof list, or
unit test is not an end-to-end claim unless the required live lane receipts are
present.
DAG Visualization / Browser Inspection Lane
Use Tau's packaged read-only React Flow viewer when a human or project agent
needs to inspect a Tau DAG run, node statuses, accepted results, and exact
blockers:
skills/tau/run.sh workflows-list
skills/tau/run.sh workflow-describe repository-readiness
skills/tau/run.sh workflow-run repository-readiness \
--repo /path/to/repo \
--goal "Determine whether this checkout is ready for focused work." \
--require-clean \
--run-dir /tmp/tau-repository-readiness \
--open-viewer
skills/tau/run.sh dag-view /tmp/tau-repository-readiness
The viewer is a renderer of Tau-authored journal replay and remains GET-only.
Browser DAG claims require a fresh Tau viewer trace and screenshot. The wrapper
does not independently prove live workflow execution, provider/model semantic
quality, repository readiness, or human acceptance.
Proof Rules
- State
mocked and live boundaries for every result.
- Unit tests are not E2E proof.
- Loop and harness claims require fresh command-loop/watchdog receipts.
- TUI claims require targeted Textual/TUI checks.
- Chat UI claims require browser/CDP screenshot verification from the host app.
- DAG visualization claims require browser/CDP screenshot verification from the
host app and must quote the source DAG/receipt artifacts being rendered.
- Chat UI interaction manifests must follow
test-interactions: live DOM
[data-qid] selectors only, deterministic assertions, and no fake fixtures
for production claims.
- React chat changes must follow
best-practices-react: interactive elements
need data-qid, data-qs-action, title, and host action registration.
- Subagent handoffs must use
tau.agent_handoff.v1.
- Human goal changes must use
tau.human_goal_change.v1; non-human agents may
propose but not apply immutable goal changes.
Default Project-Agent Interface: DAG Contracts
For multi-step project-agent work, communicate with Tau by DAG contract by
default. Direct tau.agent_handoff.v1 packets are still the node-level
subagent protocol and remain acceptable for trivial one-step work, but creator
/ reviewer loops, repair loops, provider work, goal-guardian gates, reviewer
joins, and any workflow with retry or iteration policy should be represented as
a DAG.
Project agents should not encode orchestration policy in prose, issue comments,
or ad hoc prompt instructions when a DAG can express the work. The DAG contract
is the durable instruction; Tau owns dispatch, receipt validation, route
continuity, resume behavior, timeout/max-attempt handling, immutable-goal
enforcement, and fail-closed drift detection.
Tau must monitor observable subagent behavior for blocked-agent drift. If a
subagent is failing and devolves into test-only churn without task evidence,
Tau should stop normal retry, emit a course-correction artifact, and route to a
reviewer or goal-guardian instead of allowing more pointless unit tests. Unit
tests are useful evidence only when they are tied to the active task and paired
with the required implementation or artifact evidence. The course-correction
artifact must require a blocked report that states the blocker, what was
attempted, why further test churn is not progress, and the next non-test action.
When a Tau-managed subagent has failed two attempts and still has retry budget,
Tau must require $brave-search before another attempt. The requirement must be
durable: record the failed node, attempt count, blocker, search query, and the
Brave Search command or receipt path. Do not silently continue to a third local
retry from the same stale context, and do not accept a third attempt until the
blocker report and Brave Search receipt are present.
Default flow:
project agent -> tau.dag_contract.v1
Tau -> node-level tau.agent_handoff.v1 turns + receipts
subagents -> artifacts + receipts
Tau -> DAG receipt/verdict
Minimum DAG contract fields:
schema: tau.dag_contract.v1dag_id: stable workflow id for receipts and resumegoal.goal_id, goal.goal_version, goal.goal_hashtarget: repo, issue/PR/artifact, or local target scopenodes: bounded subagent/provider/human stepsedges: allowed route graphentry_node: first node to dispatchterminal_nodes: usually human, releaser, or an explicit blocked nodelimits: max attempts, timeouts, and whether resume is allowedrequired_evidence: DAG-level proof requirementsfail_closed_on: invariant violations Tau must block
Authoring rules for project subagents:
- Use stable node ids. Node ids are graph addresses; agent names are roles.
- Keep
goal.goal_hash identical across every node, receipt, and rerun.
- Put retry policy in
nodes[].max_attempts and limits.max_total_attempts,
not in prose.
- Put allowed transitions in
edges[], not in prompt instructions.
- Put proof requirements in
required_evidence, not only in task summaries.
- Use
executor: local for local command-spec nodes, including local adapter
nodes that invoke provider machinery. Use provider-specific executors such as
codex, opencode, or scillm only when the active Tau runner explicitly
supports that route and the node is inside a Tau-authored DAG/provider
adapter. Do not use executor: scillm as a project-agent shortcut, and do
not use executor: provider; it is not a valid tau.agent_handoff.v1
executor.
- Include
command_spec for executable local nodes unless the node is an
explicit virtual/control node such as start or human. Relative
command_spec paths resolve relative to the DAG contract file; use absolute
paths or store the DAG contract where the relative paths are valid.
- Include a
human terminal node unless the workflow has a different explicit
terminal boundary.
- Include every invariant Tau should block in
fail_closed_on.
- Do not add new goals, targets, provider branches, mutating branches, or
command specs through adaptive expansion unless a separate validated
expansion/branch-lock receipt allows it.
Simple Example: One Local Creator/Reviewer Loop
Use this shape when a project agent wants a coder/reviewer loop with one bounded
repair attempt.
schema: tau.dag_contract.v1
dag_id: tau-issue-47-script-contract
goal:
goal_id: tau-issue-47
goal_version: 1
goal_hash: sha256:0000000000000000000000000000000000000000000000000000000000000047
target:
repo: grahama1970/tau
target: issue#47
allowed_paths:
- src/tau_coding/persona_dream_dream_packet_agent.py
- tests/test_persona_dream_dream_packet_agent.py
- experiments/goal-locked-subagents/agent-command-specs/script-writer/**
- experiments/goal-locked-subagents/agent-command-specs/script-reviewer/**
entry_node: script-writer
terminal_nodes:
- human
limits:
resume: true
default_timeout_seconds: 240
max_total_attempts: 4
nodes:
- id: script-writer
agent: script-writer
executor: local
max_attempts: 2
command_spec: experiments/goal-locked-subagents/agent-command-specs/script-writer/tau-dispatch-command.json
required_evidence:
- script_contract.json
- timed_transcript.json
- timed_beats.json
- entity_environment_script_table.json
emits:
- tau.agent_handoff.v1
- tau.subagent_receipt.v1
- id: script-reviewer
agent: script-reviewer
executor: local
max_attempts: 2
command_spec: experiments/goal-locked-subagents/agent-command-specs/script-reviewer/tau-dispatch-command.json
required_evidence:
- validate_script_contract.json
- script-reviewer-verdict.json
emits:
- tau.agent_handoff.v1
- tau.subagent_receipt.v1
- id: human
agent: human
executor: human
edges:
- from: script-writer
to: script-reviewer
- from: script-reviewer
to: script-writer
condition: reviewer_status_blocked_and_attempts_remaining
- from: script-reviewer
to: human
condition: reviewer_status_pass_or_attempts_exhausted
required_evidence:
- command-loop receipt or DAG receipt
- writer receipt
- reviewer verdict
- validator receipt
fail_closed_on:
- goal_hash_mismatch
- target_changed
- unexpected_node
- unexpected_edge
- missing_required_evidence
- max_attempts_exceeded
- malformed_handoff
Medium Example: Provider-Backed DAG Node
Use this shape when Tau should dispatch one provider-backed node and preserve
provider evidence, cleanup receipts, and resume metadata.
schema: tau.dag_contract.v1
dag_id: tau-provider-dag-one-pass
goal:
goal_id: tau-provider-sanity
goal_version: 1
goal_hash: sha256:active-goal
target:
repo: grahama1970/tau
target: scratch-provider-proof
entry_node: provider-task
terminal_nodes:
- human
limits:
resume: true
default_timeout_seconds: 600
max_total_attempts: 2
nodes:
- id: provider-task
agent: coder
executor: local
command_spec: experiments/goal-locked-subagents/agent-command-specs/provider-task/tau-dispatch-command.json
provider:
adapter: generic-provider-dag-node
allowed_providers:
- codex
- opencode
cleanup_mode: apply
max_attempts: 1
required_evidence:
- runtime_manifest
- events_jsonl
- provider_readiness_receipt
- orchestration_evidence_receipt
- herdr_cleanup_receipt
emits:
- tau.generic_dag_node_receipt.v1
- id: human
agent: human
executor: human
edges:
- from: provider-task
to: human
required_evidence:
- provider_live:true
- work_order_sha256
- cleanup.post_verified_absent_count
fail_closed_on:
- goal_hash_mismatch
- target_changed
- invalid_provider_receipt
- missing_work_order_sha256
- cleanup_apply_without_absence_proof
Complex Example: Parallel Branches With Reviewer Join
Use this shape when two branches can be locally valid but must be reconciled
before completion.
schema: tau.dag_contract.v1
dag_id: tau-feature-with-research-and-code
goal:
goal_id: tau-feature
goal_version: 3
goal_hash: sha256:active-goal
target:
repo: grahama1970/tau
target: issue#123
entry_node: start
terminal_nodes:
- human
limits:
resume: true
default_timeout_seconds: 300
max_total_attempts: 6
nodes:
- id: start
agent: goal-guardian
executor: scheduler
max_attempts: 1
- id: researcher
agent: research-auditor
executor: local
max_attempts: 1
command_spec: experiments/goal-locked-subagents/agent-command-specs/research-auditor/tau-dispatch-command.json
required_evidence:
- source_summary
- citations_or_local_artifacts
- id: coder
agent: coder
executor: local
max_attempts: 2
command_spec: experiments/goal-locked-subagents/agent-command-specs/coder/tau-dispatch-command.json
required_evidence:
- changed_files
- focused_tests
- id: join-review
agent: reviewer
executor: local
max_attempts: 1
command_spec: experiments/goal-locked-subagents/agent-command-specs/reviewer/tau-dispatch-command.json
join:
requires_completed:
- researcher
- coder
reconciles_evidence: true
required_evidence:
- review_verdict
- test_verification
- unresolved_monitor_alerts:none
- id: human
agent: human
executor: human
edges:
- from: start
to: researcher
- from: start
to: coder
- from: researcher
to: join-review
- from: coder
to: join-review
- from: join-review
to: human
required_evidence:
- dag_monitor_receipt
- reviewer_join_receipt
- no_unresolved_block_or_reroute_alerts
fail_closed_on:
- goal_hash_mismatch
- target_changed
- unexpected_node
- unexpected_edge
- missing_required_join
- branch_goal_hash_divergence
- branch_target_divergence
- unresolved_block_alert
Bad Example: Prose Workflow Masquerading As A DAG
Do not send Tau a loose task object, a chat plan, or a handoff with routing
instructions hidden in prose. This is not a valid Tau DAG because it has no
immutable goal hash, no explicit nodes/edges, no retry limits, no terminal
boundary, no required evidence contract, and no fail-closed invariants.
task: fix issue 47
goal: make the script pipeline good
steps:
- have a writer write the files
- have a reviewer check it
- if it looks bad, try again
- otherwise close the issue
notes: use judgment and add more agents if needed
Correct the bad shape by creating a tau.dag_contract.v1 with:
goal.goal_hash copied from the immutable goal packet;- one node per bounded role;
- explicit
edges for retry and terminal paths;
max_attempts and timeout limits;- exact required evidence names;
fail_closed_on entries for goal drift, target drift, unexpected routes,
missing evidence, malformed handoffs, timeout, and max-attempt exhaustion.
Maintainer Handoff Pattern
For agent-skills maintenance, Tau is the lease and handoff boundary between
reporters and repair workers:
- Reporter skills such as
monitor-skill-health and monitor-sparta create
normalized findings, manifests, or $ticket work items.
- A maintainer identity such as
agent-skill-maintainer leases one item at a
time.
- Repair and verification are separate bounded subagent handoffs using
tau.agent_handoff.v1.
- Closure requires deterministic proof attached to the ticket or manifest.
Tau status or watchdog receipts prove the harness state only. They do not prove
that a specific maintenance ticket was repaired unless the ticket proof names
the exercised commands and artifacts.
Key Artifacts
${HOME}/.local/state/project-watchdog/logs/cron.log
${HOME}/.local/state/project-watchdog/logs/project-watchdog.log
${HOME}/.local/state/project-watchdog/receipts/
${HOME}/workspace/experiments/tau/experiments/goal-locked-subagents/proofs/
${HOME}/workspace/experiments/tau/ui/tau-chat-contract.json
${HOME}/workspace/experiments/tau/.codex/ui-verification/latest.json
Use agents/tau for Tau-specific bounded worker turns when a global watchdog or
project agent needs a named subagent identity.
Project Knowledge
Read ${HOME}/workspace/experiments/tau/PROJECT_KNOWLEDGE.md before making
claims about current Tau coverage. It records which proof lanes have local
evidence and which remain pending.
When a Tau implementation branch exists, do not stop at a "remaining non-claims"
list if that branch can be deterministically exercised. Continue into the next
local proof command or ask for the exact side-effect target before ending the
turn. For side-effecting proof such as Memory /upsert, state the target
collection before executing and preserve both the write receipt and readback
artifact.
