Articles
Guides and notes
Practical write-ups from building on suherman.net — local AI, coding agents, spec-driven delivery, and product shipping.
10 min readBeyond Gherkin: ADR, SHALL, OpenAPI, and the rest of the specs pack
Gherkin is only the executable proof layer. SurveyDesk also keeps ADRs, SHALL requirements, OpenAPI, FormSpec, product story, and regeneration prompts — so you do not have to rewatch YouTube to learn the architecture.
ADRSpec-Driven DevelopmentSurveyDeskGherkinRead →
7 min readSession notes — SurveyDesk live build (12 Sep 2026)
Durable notes from the English Saturday session: Spec-Driven Development, SurveyDesk across web/iOS/Android, Agent on Rails, Gherkin + ADR as guardrails, and local-agent cost. Complementary to the YouTube recording — not a transcript replacement.
WebinarSurveyDeskSpec-Driven DevelopmentSession notesRead →- 6 min read
Train a chatbot without changing the model
Saturday 19 September 2026. TripSpec plans a holiday from a local guide, offers three flights with no prices, and reminds you in the app. If a reply is wrong, we change the rules and score the same conversation again. The model file stays qwen3.5.
Spec-Driven DevelopmentTripSpecWebinarRead → 
9 min readGet started with SDD: from idea to spec to implementation
Watched the 12 Sep live build (or the recording) and felt more confused afterward? SDD means Spec-Driven Development. This is the short path: idea → spec → implement → prove — and the API contract is language-neutral (Python reference; Java welcome).
Spec-Driven DevelopmentGetting startedSurveyDeskAI agentsRead →
7 min readVibe coding vs spec: the change still has to land in the contract
Live on 12 Sep we typed a natural-language ask into the agent — refresh on Android, not on iPad — and the instruction was update the spec. Here is the real difference between vibe coding and Spec-Driven Development: the vibe is allowed; the chat is not the source of truth.
Vibe codingSpec-Driven DevelopmentSurveyDeskAI agentsRead →
8 min readCrafted vs AI-generated: how to read a Spec-Driven repo
Learners often ask which files a human wrote and which an agent wrote. In Spec-Driven Development the useful split is not committer names — it is contract vs implementation. Here is a general way to tell them apart and how to study commit by commit.
Spec-Driven DevelopmentLearningGitAI agentsRead →
9 min readHow to set up SurveyDesk specs with Agent On Rails
Use the full SurveyDesk product story (local-first, native operators, anonymous Next.js web, language-neutral OpenAPI/SQLite API with a Python reference, FormSpec, brand, non-goals, demo) as gather input. Confirm the outline, and Agent On Rails writes the reference specs pack before any coding agent touches apps/.
Agent On RailsSurveyDeskSpec-Driven DevelopmentRead →
10 min readSpec-Driven Development: write the contract before the agent writes the code
Prompt-driven coding dies with the chat. Specs survive: SHALL requirements, acceptance tests, and regeneration prompts so another agent can rebuild the same product. Here is how we run SDD on Analytica Copilot.
Spec-Driven DevelopmentAI deliveryAnalyticsRead →
8 min readAgent On Rails: stop forever-loops without babysitting the terminal
We approved AOR-006 and AOR-009: intelligent model escalation, environment watchdogs, engine-owned task state, and a durable run report — then published the same story on the product site.
Agent On RailsAI deliveryGovernanceRead →
9 min readMake Ollama actually code with OpenCode
Chat models suggest text. Coding agents need a tool-capable model, a large context window, and the right OpenCode provider config. Here is the full setup flow.
Local AIOpenCodeOllamaRead →