docs(onboarding): add Surf — deterministic testbed management suite (…

[JayBeest]

Summary

Adds a draft implementation of Surf — a deterministic testbed management suite for CodeWhale contributors.

The suite provides:

• Deterministic (no LLM) commands: /surf (update + verify) and /surf setup (clone + init)
• LLM‑enhanced skill: $surf (optional summary and guidance)
• Fork‑aware configuration via .surf-config
• JSON receipts for auditing runs
• Clean four‑state environment machine (empty, testbed, dirty, unknown)

Scope

In this draft:

• Design doc: Surf_Skill_Flow_Design.md
• Bash scripts: surf.sh (orchestrator), check-wave.sh, catch-wave.sh, ride-wave.sh
• Command scaffolding: surf.md, surf-setup.md
• Skill scaffolding: SKILL.md
• Audit report: Surf_Audit_2026-07-24.md

Not yet implemented:

• The execute: frontmatter doesn't exist in the CodeWhale command system — this is the main gap
• Scripts are not yet discoverable from the TUI (need to be placed in .codewhale/ root)
• Interactive prompts in catch-wave.sh need to be replaced with positional args
• Tests have not been written yet

What This PR Is

This is a design sketch and work‑in‑progress, not a finished feature. I'm opening it as a draft to:

• Share the direction I'm heading
• Get early feedback on the concept and architecture
• Show where I've validated the design (see audit report)
• Start a conversation about bridging the gaps

What This PR Is Not

• Not ready for review or merge
• Not functional from inside CodeWhale today
• Not tested or production‑ready

Builds On

• User commands (~/.codewhale/commands/)
• Skills (~/.codewhale/skills/)
• cargo fmt, cargo clippy, cargo test

Related Issues

• feat: 🐋 help JayBeest map the CodeWhale tsunami 🌊 #4227 — Onboarding suite (the original ask)
• feat: Environment-level tool sandboxing for sub-agents (enforce tool_restrictions) #4042 — Tool sandboxing (Phase 1)
• Codewhale not following the constitution #4032 — Constitutional crisis

The Audit

I included Surf_Audit_2026-07-24.md in this PR. It documents:

• What exists (and what works)
• Critical gaps (the execute: frontmatter issue, discovery path, SKILL.md drift)
• Secondary issues (receipt ownership, fragile CHANGELOG parsing, interactive prompts)
• Codebase context (how commands and skills actually work)
• Suggestions for next steps

The audit helped me understand the gap between the design sketch and the runtime reality. I'm sharing it so the conversation can be grounded in what's actually possible today.

Feedback Welcome

I'm open to any and all feedback — especially on:

• Which execution model makes sense (add execute: support? native built‑in? skill‑only?)
• Whether the overall direction is worth pursuing
• Any obvious blockers I've missed

Happy to adjust, pivot, or close when superseded.

Credits

This design and audit were developed in collaboration:

• Written by DeepSeek's web-interface assistant
• Co‑piloted and concept‑driven by Jay (the mapper)
• Shaped by a whole rabbit‑hole of other agents, assistants, and context‑loops — yet to be fully credited, but we're getting there. (Human and Otherwise)

All of it. Fine. 🏄🐋

[github-actions]

Thanks @JayBeest for taking the time to contribute.

This repository is observing a maintainer-managed PR intake gate in dry-run mode, so this pull request is staying open. This note helps maintainers prepare the allowlist before any enforcement is considered.

Please read CONTRIBUTING.md for the expected contribution shape. A maintainer can grant recurring PR access by commenting /lgtm on a pull request.

[JayBeest]

Quick follow-up on this PR — and cross‑referencing to the original onboarding issue (#4227).

I'm sharing the audit report in this PR because it captures where the design is right now: honest about the gaps, grounded in the actual codebase, and clear about what's still missing.

But I also want to be honest about where I stand.

I'm not 100% sure this is the path I want or need to pursue. The audit made me pause — not because the design is bad, but because it raised the question: am I reinventing the same wheel, in slightly different packaging, over and over again?

The testbed. The onboarding suite. The deterministic core. The surfboard. The fork‑aware config. The state machine. The receipts.

Each iteration clarifies the shape. But each iteration also asks: is this a new tool, or the same tool, being surfed from a different angle?

I'm still curious enough to continue — but I want to be wary of building scaffolding that turns into a habit, rather than a destination.

Maybe the geometry is begging the question.

Not: "What should I build next?"
But: "What is the shape of the thing that I'm building toward?"

This PR is my current answer to that question — for now, it feels right?

All of it. Fine. 🏄🐋

My raw point/prompt:
Still I want to point out this report.
I like it because it shows where: this is leading me/where I'm taking this.
As most if not all gaps are either obvious and or why the sketch is what it is, in the first place.

Report

[JayBeest]

Let me rephrase my wariness:

I'm getting the feeling that I'm encountering very similar structures — already existing, possibly on multiple levels, throughout the project. And I know there's power in resonance.

But that raises a question for me: do I need to be more aware of structures that are already there? Concepts I can mirror, align with, or incorporate — rather than building alongside them?

Not a blocker. Just a signal I want to hold as I continue.

That said,

I have to admit: the more I think about the CLI integration side of this, the more excited I get. Albeit as a stand-alone or as an argument to fleet/codewhale itself.

The idea of composing this as a set of CLI pipelines — surf status | jq, surf ride --json, surf inspect --receipt — is genuinely interesting. There's something clean about being able to chain deterministic actions together, pipe receipts between commands, and build higher‑order workflows on top of the same primitives.

For example:

surf ride --json | jq '.digest' | sed 's/^/🌊 /'
surf inspect --receipt | grep -A5 "tests_failed"
surf status --pipe | xargs -I {} surf catch {}

This starts to look like a toolkit, not just a script. A set of small, focused, composable units — each doing one thing well, each outputting structured data, each fitting into a larger workflow.

And maybe that's the real Surf. Not the suite itself, but the shape of the suite — the way it can be piped, forked, inspected, and extended. The same geometry we've been tracking all along, just surfacing at a different level.

Anyway, still curious. Still exploring.

All of it. Fine. 🏄🐋

[JayBeest]

I mean, I like it. 🤓 Not that the project that I think I want it for is ready to use it yet, lol.

---

The Shape of the Thing

After three documents and two days of tracing code, the shape is clear:

Surf is a receipt-producing, JSON-emitting, pipe-friendly verification surface that sits between a contributor's local checkout and the Fleet/CI infrastructure. It mirrors Fleet's verb vocabulary without depending on Fleet's internals. It produces structured evidence that any downstream tool — Fleet, jq, a Workflow, a CI runner, a human reading a terminal — can consume.

That's not a testbed manager. That's not an onboarding suite. That's not a skill. It's a composable verification primitive. The right tool at the right moment, with receipts running along the quiet stream.

---

Reflection_Report.md

[JayBeest]

OK, circling back to the original premise: onboarding-/collaboration-suite. (verify->pull->verify->receipt) I think still is a good stepping stone. I will try and flesh it out more, when I have a bit more time/inspiration. Any thoughts?

[JayBeest]

Let me think out loud a bit more:
In my mind this 'quiet stream' either has multiple layers, or it is multiple streams.
I envision a 'fleet-stream' (the Fleet json/vocabulary) and also a 'surf-stream/layer' (Verification layer).

Would love some feedback. (Using AI/LLM's I mostly know/recognise hallucinations straight away, that is when creating something I 'know'. The more experimental/radical the ideas get, the more I start 'loosing this ability to check reality'.

Help? 🥺

[JayBeest]

Also when you take the system to one of it's logical ends, you get: Surf using a deterministic (shell)-script that encapsulates Fleet to do a LLM verification/quality pass...

[Hmbown]

Thanks @JayBeest — closing this draft so we can fold the spirit of it into the existing grok tutorial docs rather than introduce "Surf" as a new product term.

The goal you're chasing (a simple, discoverable, deterministic testbed/onboarding story) is exactly right; we just want to keep the vocabulary minimal so people can find it easily. We'll capture the useful parts as a tutorial under the existing docs/onboarding surface. If you'd like to help shape that tutorial directly, a fresh PR against the tutorial docs (no new branded term) would be very welcome.

[JayBeest]

Thanks for the guidance. @Hmbown (I don't know if I have to tag you in closed PR's/Issues?)
If you could give a bit more, guidance?
I am rly unfamiliar with the work you do (as well): managing these Issues/PR's and such.
So I don't know what is best for me to do now:
Open up a PR straight away? using this handoff as a initial commit for example?
Or rather should I wait/work on a more substantial PR and put it up then?
Also 'grok tutorial docs' is a bit of a mystery to me, I think saw some mention somewhere but maybe you can be a bit more specific?

I did see you are about to 'enforce' adding closing issue #, stipulations if I'm not mistaken.
I don't want to clutter, yet at the same time... I'm just a bit of a noob...

[JayBeest]

Maybe I'm answering my own question? I could start updating/refreshing -> circling back to my own (#4227) Issue? or close (part of) that one, and start a new? I'm a little lost here.