Clarity Forge : Local coding agent done right
An OpenSpec × Grill Mini Book
Monday morning. You typed "add multi-tenancy to the billing service" into Claude Code. Eight hours later: forty-three files touched. Half the tests yellow. You cannot explain to your tech lead what was decided, by whom, or against which constraint.
The code looks fine. The intent is gone.
The Clarity Forge is the antidote — a small, opinionated pipeline that forces every fuzzy idea through explicit spec, structured interrogation, and tailored artifacts before a single line of production code is written.
Six stages. Six copy-paste prompts. One iron rule:
The spec is the durable artifact. The code is the side effect.
Pairs the frontier-grade Architect (Opus, GPT-5, Sonnet 4.6+) with a local Contractor (Gemma, Qwen). Pairs OpenSpec's directory convention with the Grill skills that surface ambiguity before it metastasises into code.
A weekend read. A Monday-morning toolkit. Worked example included.
Stop vibe-coding. Start clarity-trading.
Minimum price
$12.00
$26.00
You pay
Author earns
About
About the Book
The Clarity Forge: Local AI, Done Right
The market is drowning in skill packs, plugin bundles, MCP servers, and "ultimate" prompt collections. They sell well for the same reason ab-roller infomercials sell well: they look like the thing that will fix you. They are not the thing that will fix you.
What fixes you is a small set of artifacts that capture intent before code, and a small set of prompts that move work between those artifacts predictably. Everything else is decoration.
The Clarity Forge is six stages and six prompts. That is the whole pipeline. You can run it on a weekend toy. You can run it on a 200k-LOC microservice. The artifacts scale; the discipline does not change.
What You Get
- The six-stage pipeline — OpenSpec Bootstrap → Grill-Me → Grill-With-Docs → ADR Grill → Tailored Emission → Dispatch → Verify-or-Escalate.
- Six copy-paste glue prompts — the connective tissue between stages, deliberately spare so the work lives in the artifacts, not the prompts.
- The hybrid Architect / Contractor split — frontier model (Opus, GPT-5, Sonnet 4.6+) writes the plan; open-weight local model (Gemma 4, Qwen 3) executes against it.
- Deep dives on the two highest-leverage schemas —
intent-driven(Gherkin specs + ADRs) andspec-driven-with-adr(standard specs + ADRs). - A worked example — passkey login, end to end, with a real ADR draft.
- An anti-pattern catalog — the shortcuts that look like the forge but quietly destroy it.
- A printable one-page reference card.
Who It Is For
- Engineers who use Claude Code, Cursor, Codex, or any coding agent on real production codebases.
- Tech leads tired of explaining to stakeholders why eight hours of agent execution produced code nobody can defend.
- Teams who want to run local open-weight models for execution without giving up frontier-grade reasoning for planning.
- Anyone who has felt the quiet erosion of confidence that comes from shipping AI-generated code with no audit trail of why it was decided.
This is a field guide, not a manifesto. Every prompt is runnable. Every stage produces a versionable artifact. You can be running the pipeline on a real change by Monday morning.
Companion to The Clarity Engineer
This mini book is the working pipeline. The full framework — clarity trading, world models, intent documentation, agent identity, networked agentic organizations — lives in the parent book:
📖 The Clarity Engineer: Code Is the Side Effect by Volodymyr Pavlyshyn — Leanpub · also on Amazon.
The Clarity Engineer names the discipline. The Clarity Forge gives you the working version on a single page.
About the Author
Volodymyr Pavlyshyn writes and builds at the intersection of agent orchestration, AI engineering discipline, and the durable artifacts that make software teams legible to themselves. He is the author of The Clarity Engineer and the maintainer of the OpenSpec schema family that this book documents.
Author
About the Author
Hey I am Volodymyr
Seasoned Developer's Journey from COBOL to Web 3.0, SSI, Privacy First Edge AI, and Beyond
As a seasoned developer with over 20 years of experience, I have worked with various programming languages, including some that are considered "dead," such as COBOL and Smalltalk. However, my passion for innovation and embracing cutting-edge technology has led me to focus on the emerging fields of Web 5.0, Self-Sovereign Identity (SSI),AI Agents, Knowledge Graphs, Agentiic memory systems, and the architecture of a decentralized world that empowers data democratization.
A firm believer in the potential of agent systems and the concept of a "soft" internet, I am dedicated to exploring and promoting these transformative ideas. In addition to writing, I also enjoy sharing my knowledge and insights through videoblogging. Most of my Medium posts serve as supplementary content to the videos on my YouTube channel, which you can explore here: https://www.youtube.com/c/VolodymyrPavlyshyn.
Join me on this exciting journey as we delve into the future of technology and the possibilities it holds.
Contents
Table of Contents
The Clarity Forge
- Local AI, Done Right — An OpenSpec × Grill Mini Book
Preface — Cold Open
Chapter 1 — Why You Need a Forge, Not Another Skill Pack
Chapter 2 — The Pipeline at a Glance
Chapter 3 — OpenSpec in 90 Seconds
Chapter 4 — Project Setup: From Zero to a Forgeable Repo
- 4.1 What “Forgeable” Means
- 4.2 Prerequisites
- 4.3 The Init Step
- 4.4 Reading
openspec/config.yaml - 4.5 Choosing a Schema
- 4.6 Wiring
CLAUDE.mdandAGENTS.md - 4.7 First Scaffold (Sanity Check)
- 4.8 Validation Cadence
- 4.9 You Are Now Forgeable
Chapter 5 — Custom Schemas: Intent-Driven and Spec-Driven With ADR
- 5.1 The Schema Catalog (Brief)
- 5.2 Spec-Driven With ADR — Anatomy
- 5.3 Intent-Driven — Anatomy
- 5.4 The ADR Persistence Contract
- 5.5 The Supersession Rule (The Iron Rule)
- 5.6 Mapping Schemas to Forge Stages
- 5.7 Switching Schemas (And Why You Shouldn’t, Often)
- 5.8 Where To Read More
Chapter 6 — The Six Stages, In Detail
- Stage 1 — OpenSpec Bootstrap
- Stage 2 — Grill-Me Interrogation
- Stage 3 — Grill-With-Docs Reconciliation
- Stage 4 — Tailored Artifact Emission
- Stage 5 — Dispatch & Execute
- Stage 6 — Verify or Escalate
Chapter 7 — The Five Glue Prompts
- Glue 1 — Inversion Prompt (Stage 1 entry)
- Glue 2 — Grill-Me Trigger (Stage 2 entry)
- Glue 3 — Reconciliation Prompt (Stage 3 entry)
- Glue 4 — Dispatch Prompt (Stage 5 entry, repeat per task)
- Glue 5 — Escalation Prompt (Stage 6, failure branch)
Chapter 8 — ADR Grilling: Interrogating Decisions Before They Freeze
- 8.1 Why ADRs Need Their Own Grill
- 8.2 What Makes a Decision ADR-Worthy
- 8.3 Glue 3½ — The ADR Grill Prompt
- 8.4 Grilling The Four MADR Fields
- 8.5 Supersession Reasoning
- 8.6 ADR Grilling in the Hybrid Pipeline
- 8.7 ADR-Specific Anti-Patterns
- 8.8 Where ADR Grilling Sits in the Pipeline
Chapter 9 — Tailoring the Three Targets
- 9.1 Config Tailoring
- 9.2 Project Tailoring
- 9.3 Proposal Tailoring (Human-Facing)
Chapter 10 — Worked Example: Passkey Login (Compressed)
- Stage 1 — Inversion Prompt → OpenSpec Bootstrap
- Stage 2 — Grill-Me
- Stage 3 — Grill-With-Docs
- Stage 3½ — ADR Grill
- Stage 4 — Artifact Emission
- Stage 5 — Dispatch
- Stage 6 — Escalate × 2
- Archive
- Budget
Chapter 11 — Diagnostic Mode: When Reality Has Already Diverged from the Spec
- 11.1 Diagnosis Is Not Debugging
- 11.2 The Six-Move Loop
- 11.3 The Diagnose Glue Prompt
- 11.4 Where Diagnosis Slots Into the Forge
- 11.5 The Architect / Contractor Split During Diagnosis
- 11.6 Diagnosis Anti-Patterns
- 11.7 Diagnosis Is the Forge’s Bug-Shaped Onramp
Chapter 12 — Debugging Mode: Tactical Poking Inside a Disciplined Forge
- 12.1 When Debugging Is the Right Tool
- 12.2 When Debugging Is the Wrong Tool
- 12.3 The Round-Trip Rule
- 12.4 Pairing Debugging with
/verify - 12.5 The Architect / Contractor Split During Debugging
- 12.6 Debugging Anti-Patterns
- 12.7 Closing
Chapter 13 — Anti-Patterns
Chapter 14 — Closing: The Forge Is the Practice
Bonus Chapter — You Are the Bottleneck
- The Typing-Speed Ceiling
- The Two Wrong Beliefs
- The Psychological Challenge
- The Wider View — The Clarity Engineer
- Closing The Loop On Yourself
Appendix A — The Forge on One Page
- The Pipeline
- The Eight Prompts
- The Three Commands
- The Hybrid Split
- The Iron Rules
Appendix B — All Prompts & Installation Setup
- B.1 Installation Setup
- B.2 The Eight Prompts, In Execution Order
- B.3 Prompt-to-Stage Quick Reference
- B.4 Smallest Possible First Run
The Leanpub 60 Day 100% Happiness Guarantee
Within 60 days of purchase you can get a 100% refund on any Leanpub purchase, in two clicks.
Now, this is technically risky for us, since you'll have the book or course files either way. But we're so confident in our products and services, and in our authors and readers, that we're happy to offer a full money back guarantee for everything we sell.
You can only find out how good something is by trying it, and because of our 100% money back guarantee there's literally no risk to do so!
So, there's no reason not to click the Add to Cart button, is there?
See full terms...
Earn $8 on a $10 Purchase, and $16 on a $20 Purchase
We pay 80% royalties on purchases of $7.99 or more, and 80% royalties minus a 50 cent flat fee on purchases between $0.99 and $7.98. You earn $8 on a $10 sale, and $16 on a $20 sale. So, if we sell 5000 non-refunded copies of your book for $20, you'll earn $80,000.
(Yes, some authors have already earned much more than that on Leanpub.)
In fact, authors have earned over $15 million writing, publishing and selling on Leanpub.
Learn more about writing on Leanpub
Free Updates. DRM Free.
If you buy a Leanpub book, you get free updates for as long as the author updates the book! Many authors use Leanpub to publish their books in-progress, while they are writing them. All readers get free updates, regardless of when they bought the book or how much they paid (including free).
Most Leanpub books are available in PDF (for computers) and EPUB (for phones, tablets and Kindle). The formats that a book includes are shown at the top right corner of this page.
Finally, Leanpub books don't have any DRM copy-protection nonsense, so you can easily read them on any supported device.
Learn more about Leanpub's ebook formats and where to read them
Write and Publish on Leanpub
You can use Leanpub to easily write, publish and sell in-progress and completed ebooks and online courses!
Leanpub is a powerful platform for serious authors, combining a simple, elegant writing and publishing workflow with a store focused on selling in-progress ebooks.
Leanpub is a magical typewriter for authors: just write in plain text, and to publish your ebook, just click a button. (Or, if you are producing your ebook your own way, you can even upload your own PDF and/or EPUB files and then publish with one click!) It really is that easy.