Document optional source evidence workflow

[kriptoburak]

Summary

Adds an optional public X/Twitter source-evidence workflow to the agent guide, fixes the packaged Claude skill's relative links back to docs/agent-workflow.md, and updates the skill to reference @wingman-x/agent-kit instead of the old package name.

Why

Wingman-X already has a strong human-reviewed reply flow. Agents sometimes need broader public context than the configured handle list, and the docs now show how to pass that context into the existing candidate review flow without changing who drafts, reviews, or presses Tweet.

Approach

docs/agent-workflow.md now includes an optional source-evidence section for OpenClaw plus TweetClaw. The guidance keeps source tools bounded to public context gathering and keeps final synthesis, daemon state, browser session material, approval, and posting inside Wingman-X.

.claude/skills/discover-twitter-candidates/SKILL.md now links to the correct repo-level docs path, points to the new optional evidence section, and uses the current @wingman-x/agent-kit package name.

How I Tested

Existing tests/checks run:

• git diff --check
• npx --yes markdown-link-check docs/agent-workflow.md .claude/skills/discover-twitter-candidates/SKILL.md --quiet
• npm view @xquik/tweetclaw@1.6.31 version openclaw.install repository.url homepage --json
• npm ci --ignore-scripts --no-audit --no-fund
• npm run build:no-bump
• npm run typecheck

Notes:

• A first npm run typecheck before building local workspace artifacts failed because TypeScript could not resolve local workspace packages such as @wingman-x/kb-contract. After npm run build:no-bump, the same typecheck passed.
• No generated dist/ files or dependency artifacts are included in this PR.

Rollback Plan

1. Maximum blast radius: single docs/skill workflow.
2. Time-to-rollback: under one minute with git revert.

Out of Scope

• No daemon, extension, scraper, or agent-kit runtime code changes.
• No auto-posting behavior.
• No change to the candidate schema or local browser login flow.

Summary by CodeRabbit

• Documentation
  • Updated agent workflow documentation to include an optional public evidence gathering step for enhanced context when drafting replies.
  • Refined skill documentation with corrected resource paths and updated package references.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 82aa8f4c-40af-4c93-acef-585a1a083a21

📥 Commits

Reviewing files that changed from the base of the PR and between 3bbfa92 and 48d9e52.

📒 Files selected for processing (2)

• .claude/skills/discover-twitter-candidates/SKILL.md
• docs/agent-workflow.md

---

📝 Walkthrough

Walkthrough

Adds an "Optional Public Source Evidence" section to docs/agent-workflow.md with a SourceEvidence structure, TweetClaw/OpenClaw usage guidance, and rules constraining evidence tools. Also updates SKILL.md to fix doc link paths and replace the @twitter-helper/agent-kit package reference with @wingman-x/agent-kit.

Changes

Agent Workflow Evidence Docs and SKILL.md Alignment

Layer / File(s)	Summary
Optional Public Source Evidence section docs/agent-workflow.md	Step 5 gains a cross-reference to a new section defining when to gather public X/Twitter context, how to use the TweetClaw/OpenClaw companion, the SourceEvidence shape, and constraints prohibiting evidence tools from deciding or posting replies or copying untrusted source text.
SKILL.md link paths and package name updates .claude/skills/discover-twitter-candidates/SKILL.md	Corrects the agent-workflow.md reference path, changes the daemon-client POST package from @twitter-helper/agent-kit to @wingman-x/agent-kit, and fixes candidate-json-shape and failure-modes doc link paths.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~4 minutes

Poem

A rabbit updates docs with care, 🐇
New evidence paths laid out with flair,
The wingman-x kit takes the stage,
Links corrected, page by page,
TweetClaw hops in, context found—
Untrusted posts stay safely bound! 🌿

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The pull request title 'Document optional source evidence workflow' directly and specifically summarizes the main change: adding documentation for an optional source evidence workflow in the agent guide.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[stone16]

No description provided.

[stone16]

Reviewed stone16/wingman-x#21 at 48d9e527aa0f17b261f5b9d520635e817130220c against the full Multica checkout.

No findings. I verified git diff --check, Markdown links for the changed docs/skill files, the pinned TweetClaw npm metadata, and the documented @wingman-x/agent-kit exports / signal client surface.

Verdict: approve.

[stone16]

Verdict: approve

Security findings: none blocking.

• Supply-chain note (informational, non-blocking): the new "Optional Public Source Evidence" section instructs users/agents to install an external OpenClaw plugin npm:@xquik/tweetclaw@1.6.31 (docs/agent-workflow.md:93). Verified live via npm view: real published package, repo github.com/Xquik-dev/tweetclaw, single maintainer burakbayir <support@xquik.com>, last published 2026-05-14, own openclaw.install metadata confirms it is an OpenClaw plugin. Version is pinned (1.6.31) — good hygiene. It is not a repo dependency (no package.json/lockfile change in this PR), is optional and user-initiated, so it does not gate the verdict; flagged so the single-maintainer footprint is on the record. Alternative considered: document the source-evidence capability generically without pinning a specific package — that is a product decision, outside this verdict scope.
• Positive boundary handling: the section correctly treats external public posts as untrusted input — "Do not copy source text directly into suggested_reply; synthesize through the user's tone.md" (docs/agent-workflow.md:111-112). This is the right defense against prompt-injection / verbatim PII leakage. I checked whether untrusted evidence could become a persisted system prompt: tone.md is injected as a system prompt on every drafting call (docs/agent-workflow.md:244-245), but the new section's "synthesize through" wording means use it as a voice guide, not write evidence into it — no path writes SourceEvidence into tone.md/library/*.md. The approval boundary is explicitly preserved: "the user still reviews, edits, and presses Tweet" (docs/agent-workflow.md:115); nothing auto-posts or bypasses the daemon review/POST flow.

Performance findings: none.

• N/A — documentation-only diff (markdown). No database, allocation, async, cache, blocking-call, or runtime/external-API code paths changed.

What I checked:

• Auth boundary / authorization: N/A — docs-only PR, no auth code path changed.
• Input validation: the new section treats external posts as untrusted input and forbids verbatim copy into replies (docs/agent-workflow.md:111-112) — correct.
• Injection surfaces: "synthesize, don't copy" mitigates prompt/text injection from public tweets; confirmed untrusted evidence does not enter the KB system-prompt material — no finding.
• Secrets handling: N/A — diff scan found no tokens/keys/private IPs/internal hostnames.
• Concurrency safety: N/A — docs-only.
• Dependency footprint: @xquik/tweetclaw@1.6.31 characterized above (single maintainer, pinned, optional, not a repo dependency).
• Side channels: N/A — docs-only surface.
• DB queries / allocations / blocking-in-async / complexity / caching / external API calls: N/A — docs-only.

Docs-specific bar (per issue instructions for docs PRs):

• Code/CLI/API claims match current code, verified against the checked-out head: @wingman-x/agent-kit is the real package name (packages/agent-kit/package.json); the old @twitter-helper/agent-kit survives only in historical .harness/retro and design-spec docs, so the rename is correct. createDaemonClient, postCandidates, listSignals, ackSignal all exist in packages/agent-kit/src/client.ts (lines 52, 64, 65, 88, 127, 190, 202). Scraper path packages/agent-kit/scripts/scrape-x-*.ts matches real files (scrape-x-handles.ts, scrape-x-home.ts).
• Relative-link fix is a genuine correctness fix: ../../../docs/agent-workflow.md from .claude/skills/discover-twitter-candidates/SKILL.md resolves to docs/agent-workflow.md; the previous ../../docs/agent-workflow.md resolved to the non-existent .claude/docs/agent-workflow.md. Anchors referenced (#optional-public-source-evidence, #candidate-json-shape, #failure-modes) all exist in the workflow doc.
• Leaked secrets / internal URLs: none found in the diff.

[stone16]

Consensus reached: approve.