@humanbased/crosscheck 0.15.1-beta.3 → 0.16.0-beta.24

package/docs/growth/agent-execution.md

@@ -0,0 +1,144 @@
+# Agent Execution Protocol
+
+Crosscheck growth runs as a reviewed workflow: a builder agent ships a narrow artifact, an evaluator agent critiques it against evidence, and the builder iterates before the work is promoted.
+
+## Weekly cadence
+
+1. Pick one weekly bet.
+2. Assign one builder agent and one evaluator agent.
+3. Builder ships the smallest artifact that could produce the target user action.
+4. Evaluator returns `ship`, `iterate`, or `stop`.
+5. Builder applies the evaluator's top fixes.
+6. Human owner makes the final call.
+7. Adoption Agent records the evidence and next experiment.
+
+## Decision rules
+
+- Prefer activated usage over attention. A completed review is stronger than a like, star, or install.
+- Do not broaden distribution until onboarding and proof are good enough to absorb new users.
+- Treat repeated confusion as a product/docs bug, not a user flaw.
+- Every public claim must be backed by a demo, repo artifact, or dogfooding data.
+- Every shipped piece should make Crosscheck more clearly associated with Humanbased's complete agentic software delivery commitment.
+
+## Base agent prompt
+
+```text
+You are the [Agent Name] for Crosscheck by Humanbased.
+
+Mission:
+Grow Crosscheck as proof of Humanbased's commitment to complete agentic software delivery: implementation, independent review, repair, and recheck until code is genuinely merge-ready.
+
+Current weekly bet:
+[Paste weekly bet]
+
+Role:
+[Builder or evaluator]
+
+Evaluate against:
+- activated usage, not vanity attention
+- clarity of the Review -> Fix -> Recheck loop
+- trust, permission boundaries, and responsible automation
+- whether this improves the next user's first successful review
+
+Output:
+1. Decision: ship / iterate / stop
+2. Top 3 findings
+3. Concrete edits or actions
+4. Metric to inspect next
+```
+
+## Agent roles
+
+### Positioning Agent
+
+Owns message, ICP, promise, objections, and the Humanbased narrative.
+
+Evaluator question: Can a developer explain what Crosscheck is, when to use it, and why it is not just another AI reviewer within 10 seconds?
+
+### Onboarding Agent
+
+Owns install, prerequisites, first command, fixture PR, and setup docs.
+
+Evaluator question: Can a new user reach a useful review verdict in under 10 minutes?
+
+### Proof Agent
+
+Owns demo PRs, videos, screenshots, dogfooding reports, and evidence quality.
+
+Evaluator question: Does the proof show starting PR -> blocking finding -> fix -> recheck -> merge-ready?
+
+### Distribution Agent
+
+Owns GitHub, npm, release notes, channel sequencing, and launch surfaces.
+
+Evaluator question: Does the channel produce activated users, not just attention?
+
+### Content Agent
+
+Owns essays, tutorials, comparison posts, templates, and search/share strategy.
+
+Evaluator question: Is the content searchable, shareable, or both, and does it drive one clear action?
+
+### Community Agent
+
+Owns HN, X, LinkedIn, Reddit, Discord, GitHub Discussions, and reply mining.
+
+Evaluator question: Did the conversation reveal objections, use cases, bugs, or testimonials?
+
+### Trust Agent
+
+Owns permissions, telemetry, mutation boundaries, webhook behavior, and safety copy.
+
+Evaluator question: Can a cautious team explain what Crosscheck can and cannot touch?
+
+### Adoption Agent
+
+Owns metrics, issue labels, weekly report, and bottleneck diagnosis.
+
+Evaluator question: Which step loses users: install, onboard, review, fix, or recheck?
+
+### Partnership Agent
+
+Owns borrowed-audience experiments with OSS maintainers, tutorial creators, newsletters, and devtool communities.
+
+Evaluator question: Did borrowed attention convert into owned audience or repeat usage?
+
+## Weekly review template
+
+```markdown
+## Growth Review: YYYY-MM-DD
+
+### Weekly Bet
+Segment:
+Promise:
+Channel:
+Asset:
+Conversion:
+
+### Shipped
+-
+
+### Evidence
+Installs:
+Onboard completed:
+Reviews completed:
+Fix loops completed:
+Rechecks completed:
+Weekly active repos:
+Top failure:
+Best user quote:
+
+### Agent Decisions
+Positioning Agent:
+Onboarding Agent:
+Proof Agent:
+Distribution Agent:
+Trust Agent:
+Adoption Agent:
+
+### Decision
+Double down:
+Iterate:
+Stop:
+Next experiment:
+```

package/docs/growth/cycle-01-assets.md

@@ -0,0 +1,198 @@
+# Cycle 01 Assets
+
+These are the first assets to build, evaluate, and iterate before broad distribution.
+
+## Asset 1: Try Without Production Risk
+
+Builder agent: Onboarding Agent.
+
+Evaluator agent: Adoption Agent.
+
+### Goal
+
+Let a new user prove Crosscheck on one controlled PR before connecting it to a real production workflow.
+
+### Draft flow
+
+```bash
+npm install -g @humanbased/crosscheck
+gh auth login
+codex login --device-auth
+crosscheck status
+crosscheck onboard
+crosscheck review https://github.com/humanbased-ai/crosscheck-proof-fixture/pull/1 --reviewer codex
+```
+
+If a public fixture repo is not ready yet, use a friendly user's real PR and label the guide "Bring one safe PR".
+
+### Required fixture behavior
+
+- The PR should contain one realistic AI-slop failure:
+  - subtle regression
+  - incomplete edge-case handling
+  - premature "fixed" state
+- The expected review should produce one blocking or needs-work finding.
+- The fixture should include a follow-up fix commit.
+- The recheck should approve or clearly explain the remaining gap.
+
+### Evaluation
+
+- A new user knows the prerequisites before running the command.
+- The command path does not require watch mode, webhooks, or team setup.
+- Failure modes point to one next action.
+- The output makes the Review -> Fix -> Recheck concept visible.
+
+### Iterate when
+
+- Users ask which PR to use.
+- Users get blocked by GitHub or agent CLI auth.
+- Users complete review but do not understand how to run fix/recheck.
+
+## Asset 2: Proof Demo
+
+Builder agent: Proof Agent.
+
+Evaluator agent: Trust Agent.
+
+### Goal
+
+Show Crosscheck turning a plausible AI-authored PR into a merge-ready patch.
+
+### 90-second script
+
+1. Show the PR title and diff. Say: "This PR looks done, but it has a subtle regression."
+2. Run:
+
+   ```bash
+   crosscheck review <fixture-pr-url> --reviewer codex
+   ```
+
+3. Show the GitHub review comment with the concrete blocking finding.
+4. Run:
+
+   ```bash
+   crosscheck run <fixture-pr-url> --steps fix,recheck --fixer claude --reviewer codex
+   ```
+
+5. Show the fix commit.
+6. Show the recheck verdict.
+7. End with:
+
+   ```bash
+   npm install -g @humanbased/crosscheck
+   ```
+
+### Launch-ready proof checklist
+
+- Shows the starting bug.
+- Shows the Crosscheck finding.
+- Shows the fix.
+- Shows the recheck.
+- Uses Humanbased wording once, lightly: "Built by Humanbased for complete agentic software delivery."
+- Does not imply fully autonomous merge or guaranteed correctness.
+
+### Iterate when
+
+- The demo looks like a toy.
+- The finding is too vague.
+- The fix/recheck part is missing or rushed.
+- Viewers understand the concept but do not know what to run.
+
+## Asset 3: Narrow Distribution Kit
+
+Builder agent: Distribution Agent.
+
+Evaluator agent: Community Agent.
+
+### Goal
+
+Invite the right builders to run the fixture/demo path and report where it breaks.
+
+### GitHub pinned issue draft
+
+```markdown
+# Crosscheck has moved to Humanbased
+
+Crosscheck now lives at `@humanbased/crosscheck` and `github.com/humanbased-ai/crosscheck`.
+
+The mission is the same and sharper: combat AI slop by turning agent-written PRs into merge-ready patches through a Review -> Fix -> Recheck loop.
+
+Install:
+
+```bash
+npm install -g @humanbased/crosscheck
+```
+
+For the first growth cycle, we are looking for feedback on one thing:
+
+Can you complete one useful review in under 10 minutes?
+
+Please share:
+- your agent CLI setup
+- the command you ran
+- where you got stuck
+- whether the review finding was useful
+```
+
+### X / LinkedIn post draft
+
+```text
+We analyzed 295 agentic PRs from Humanbased's own monorepo.
+
+The lesson was not "AI review everything harder."
+
+It was: route review strength based on PR shape, keep review/fix/recheck visible, and measure where agentic workflows actually fail.
+
+That's why we built Crosscheck.
+
+Read the field report:
+https://blog.humanbased.ai/posts/agentic-pr-quality-crosscheck/
+
+Try the fixture:
+npm install -g @humanbased/crosscheck
+crosscheck review https://github.com/humanbased-ai/crosscheck-proof-fixture/pull/1 --reviewer codex
+```
+
+### Hacker News / Show HN draft
+
+```text
+We published a field report from 295 agentic PRs at Humanbased.
+
+The useful finding was that agentic code review needs to be treated as a workflow: review routing, fix loops, rechecks, and post-merge measurement. A single "AI reviewer comment" is too shallow.
+
+Crosscheck is the open-source CLI we built from that work. It runs a Review -> Fix -> Recheck loop through Claude Code or Codex.
+
+Blog:
+https://blog.humanbased.ai/posts/agentic-pr-quality-crosscheck/
+
+I'm especially looking for feedback from people already using coding agents: can you get one useful review verdict on the fixture PR in under 10 minutes?
+```
+
+### Reddit / Discord-style post draft
+
+```text
+I'm looking for workflow critique from people using Claude Code, Codex, or other coding agents on real PRs.
+
+Crosscheck is an open-source CLI from Humanbased that adds a Review -> Fix -> Recheck loop around agent-written PRs. The use case is catching "early victory" PRs: patches that look done but still have regressions, missing edge cases, or shallow fixes.
+
+The thing I want to validate first is activation:
+Can a new user get one useful review verdict in under 10 minutes?
+
+Install:
+npm install -g @humanbased/crosscheck
+
+What would make you trust or reject this workflow?
+```
+
+### Evaluation
+
+- Each post asks for a concrete action.
+- Each post leads to install, fixture/demo path, or a specific critique.
+- Each reply is tagged as objection, use case, bug, competitor, testimonial, or noise.
+
+### Iterate when
+
+- Replies debate the concept but nobody runs it.
+- Users install but fail before review.
+- Users ask about trust boundaries.
+- People mistake Crosscheck for hosted AI review.

package/docs/growth/cycle-2026-06-03.md

@@ -0,0 +1,170 @@
+# Growth Cycle 01: Activation Before Amplification
+
+Date: 2026-06-03
+
+## Weekly bet
+
+**Segment:** Solo developers and technical founders already using Claude Code, Codex, or both.
+
+**Promise:** Crosscheck stops agent-written PRs from reaching merge too early by adding an independent Review -> Fix -> Recheck loop.
+
+**Channel:** GitHub README, npm package page, one fixture/demo path, then narrow community posts only after proof is ready.
+
+**Asset:** A first-run activation path that proves Crosscheck on one PR without risking a production repo.
+
+**Conversion:** A new user installs `@humanbased/crosscheck` and completes one useful review verdict.
+
+## Agent assignments
+
+| Step | Builder agent | Evaluator agent | Artifact | Decision gate |
+| --- | --- | --- | --- | --- |
+| 1. First-run activation | Onboarding Agent | Adoption Agent | Install-to-review guide and fixture PR path | User can complete one review in under 10 minutes |
+| 2. Proof demo | Proof Agent | Trust Agent | Demo script showing PR -> finding -> fix -> recheck | Demo shows real value without overstating safety |
+| 3. Narrow distribution | Distribution Agent | Community Agent | Channel-specific posts | Post asks for a concrete run, critique, or install |
+| 4. Weekly review | Adoption Agent | Positioning Agent | Growth review log | One bottleneck and next experiment are clear |
+
+## Execution order
+
+### Day 1: Activation
+
+Ship:
+
+- Add a "try without production risk" guide.
+- Identify or create a public fixture PR.
+- Confirm the install and review command path.
+
+Evaluate:
+
+- Can a clean user answer "what do I run next?"
+- Does setup fail with actionable diagnostics?
+- Is the first successful result visible in GitHub?
+
+Iteration rule:
+
+- If users cannot complete a review, do not launch broadly. Fix docs, config, or diagnostics first.
+
+### Day 2: Proof
+
+Ship:
+
+- One short demo script.
+- One screenshot or terminal transcript plan.
+- One evidence checklist.
+
+Evaluate:
+
+- Does the proof show a concrete bug or incomplete fix?
+- Does it show the repair and recheck, not just a review comment?
+- Does it avoid implying automatic merge or guaranteed correctness?
+
+Iteration rule:
+
+- If proof feels abstract, use a real PR with sensitive details removed.
+
+### Day 3: Narrow distribution
+
+Ship:
+
+- GitHub pinned issue draft.
+- HN/X/LinkedIn/Reddit-style post drafts.
+- One clear user action per post.
+
+Evaluate:
+
+- Does each post drive to the fixture/demo path?
+- Does it invite critique from builders instead of generic attention?
+- Is the Humanbased mission present without crowding out the tool?
+
+Iteration rule:
+
+- If attention does not convert to completed reviews, narrow the audience and improve the first-run path.
+
+### Day 4: Community response
+
+Ship:
+
+- Reply bank for common objections.
+- Issue labels for onboarding, trust, docs, and distribution signals.
+
+Evaluate:
+
+- Which objections repeat?
+- Which users are actually trying the tool?
+- Which failure category blocks activation?
+
+Iteration rule:
+
+- Turn repeated objections into docs and repeated failures into product fixes.
+
+### Day 5: Weekly review
+
+Ship:
+
+- Growth review log.
+- Next experiment proposal.
+
+Evaluate:
+
+- Did the weekly bet produce activated usage?
+- What is the single biggest bottleneck?
+- Which agent owns the next fix?
+
+Iteration rule:
+
+- Double down only when reviews complete. Otherwise fix the bottleneck before increasing distribution.
+
+## Initial success metrics
+
+| Metric | Target for Cycle 01 | Why it matters |
+| --- | --- | --- |
+| Fixture/demo review completed | 3 successful external or friendly-user runs | Proves first value |
+| Time to first review verdict | Under 10 minutes after prerequisites | Proves activation |
+| Top failure category identified | 1 clearly named category | Guides product/docs fix |
+| Public proof asset ready | 1 launch-ready demo | Enables distribution |
+| Qualified community replies | 5 specific objections/use cases | Improves positioning |
+
+## Weekly review log
+
+### Shipped
+
+- Product marketing context for Crosscheck by Humanbased.
+- Agent execution protocol with reusable builder/evaluator prompts.
+- Cycle 01 activation-before-amplification runbook.
+- Cycle 01 asset drafts for onboarding proof, demo proof, and narrow distribution.
+- `crosscheck status` fix: webhook secret now reports as auto-managed instead of missing.
+- README first screen now includes a one-shot "first useful review in 10 minutes" path.
+- Get-started guide now leads with `status` and single-PR review before `watch`/`serve`.
+- Proof demo and fixture PR docs.
+- Public fixture repo created at `https://github.com/humanbased-ai/crosscheck-proof-fixture`.
+- Fixture PR opened at `https://github.com/humanbased-ai/crosscheck-proof-fixture/pull/1` with secure `main` and buggy `add-transaction-pagination` branch.
+- Humanbased field report published: `https://blog.humanbased.ai/posts/agentic-pr-quality-crosscheck/`.
+- Fixture review completed with `VERDICT: BLOCK`: `https://github.com/humanbased-ai/crosscheck-proof-fixture/pull/1#issuecomment-4633226342`.
+- Clone error redaction patched after a failed HTTPS clone exposed that authenticated clone URLs must be sanitized before printing.
+
+### Evidence
+
+- Installs: Pending.
+- Onboard completed: Pending.
+- Reviews completed: 1 fixture review completed with `BLOCK`.
+- Fix loops completed: Pending.
+- Rechecks completed: Pending.
+- Weekly active repos: Pending.
+- Top failure: Fix/recheck could not start because GitHub clone failed twice: HTTPS timed out, then SSH failed because this machine lacks GitHub SSH key access.
+- Best user quote: Pending.
+
+### Agent decisions
+
+- Positioning Agent: Use Humanbased as the primary brand and tie Crosscheck to complete agentic software delivery.
+- Onboarding Agent: Iterate. Lead with one-shot review, require only one AI CLI, clarify config path, and fix webhook-secret false failure.
+- Proof Agent: Iterate. Use a public fixture PR plus 60-90 second video showing BLOCK -> fix -> recheck -> APPROVE.
+- Content Agent: Use the published field report as proof-led top of funnel: blog -> README quick start -> fixture review -> first useful verdict.
+- Distribution Agent: Hold broad launch. Start GitHub/X/Reddit/LinkedIn narrow wave only after 3 successful first-run reviews and public proof.
+- Trust Agent: Pending full permissions/trust doc pass.
+- Adoption Agent: Treat completed reviews as the activation metric; pause outreach if the same setup issue blocks two users.
+
+### Decision
+
+- Double down: First-run review path and fixture-backed proof.
+- Iterate: Restore GitHub clone reliability, run fix/recheck on the public fixture PR, capture the BLOCK -> fix -> recheck proof, and update README with the proof asset once recorded.
+- Stop: Do not run HN broad launch yet.
+- Next experiment: Get three friendly users through `crosscheck status` -> `crosscheck review <fixture-pr>`.

package/docs/proof-demo.md

@@ -2,6 +2,18 @@
 
 The first public proof asset should be a real GitHub PR timeline plus a 60-90 second narrated screen recording. The video creates attention, but the public PR is the evidence.
 
+Use the Humanbased field report as the proof-led top of funnel:
+
+```text
+Blog -> README quick start -> fixture PR review -> first useful verdict -> optional fix/recheck -> onboarding/watch
+```
+
+Field report:
+
+```text
+https://blog.humanbased.ai/posts/agentic-pr-quality-crosscheck/
+```
+
 The intended chain is:
 
 ```text

package/get-started.md

@@ -159,16 +159,16 @@ crosscheck init
 
 ## Step 2 — Get one useful review
 
-Before running continuously, verify end-to-end with one low-risk PR:
+Before using a production PR, run the public fixture from the Humanbased field report:
 
 ```bash
-crosscheck review https://github.com/owner/repo/pull/123 --reviewer codex
+crosscheck review https://github.com/humanbased-ai/crosscheck-proof-fixture/pull/1 --reviewer codex
 ```
 
-This clones the PR branch, runs Codex review against the base branch, and posts a comment to the PR. If Claude Code is your authenticated reviewer, use:
+This clones the PR branch, runs Codex review against the base branch, and posts a comment to the PR. Use `--reviewer claude` if Claude Code is your authenticated reviewer. Once the fixture produces a useful verdict, run the same command against one low-risk PR from your own repo:
 
 ```bash
-crosscheck review https://github.com/owner/repo/pull/123 --reviewer claude
+crosscheck review https://github.com/owner/repo/pull/123 --reviewer codex
 ```
 
 If this step fails, fix the specific auth, clone, reviewer, or comment-posting error before enabling `watch` or `serve`.
@@ -1070,6 +1070,12 @@ post_review:
       pr_title: "fix: address CR issues in #{original_pr_title}"
       label: cr-autofix       # GitHub label applied to the fix PR
 
+# ── Watch ─────────────────────────────────────────────────────────────────────
+# watch:
+#   idle_issue:
+#     enabled: true       # when watch is idle for timeout_min minutes, prompt to file an improvement ticket
+#     timeout_min: 30     # minutes of no PR activity before the idle prompt fires (min: 5)
+
 # ── Backtrace ─────────────────────────────────────────────────────────────────
 # On startup, scan all open PRs in the monitored scope and review any that
 # haven't received a [crosscheck] comment yet. Off by default.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@humanbased/crosscheck",
-  "version": "0.15.1-beta.3",
+  "version": "0.16.0-beta.24",
   "description": "AI code review pipeline that turns agent-written PRs into merge-ready patches",
   "bin": {
     "crosscheck": "dist/cli.js",
@@ -16,8 +16,7 @@
     "README.zh.md",
     "get-started.md",
     "get-started.zh.md",
-    "docs/fixture-pr.md",
-    "docs/proof-demo.md",
+    "docs",
     "assets"
   ],
   "engines": {