# Prose-Kit: Spec-Driven Development, But for Writers ## What if your blog post had a build process? Software engineers don't sit down and just *start typing code*. They spec it out. They plan. They break it into tasks. They test. They ship. Writers? We open a blank document and hope the muse shows up. **Prose-Kit** is my attempt to fix that. It's a structured workflow toolkit for blog posts, essays, research papers, and technical writing — adapted from [GitHub's spec-kit](https://github.com/github/spec-kit) by Den Delimarsky and John Lam. The core idea: treat a piece of writing with the same rigor you'd treat a piece of software. --- ## Origin Story In late 2025 I discovered spec-kit — a framework GitHub engineers built for "Spec-Driven Development." The workflow was elegant: define a constitution (your project's principles), write a spec (what you're building), create a plan (how you'll build it), break it into tasks, then implement. I was halfway through reading the templates when the obvious hit me: **this isn't a software workflow. This is a writing workflow.** Every step mapped cleanly: | Spec-Kit (Software) | Prose-Kit (Writing) | |---|---| | Feature | Piece (blog post, essay, paper) | | User stories | Reader scenarios / content goals | | Technical implementation | Writing structure and outline | | Deployment | Publication | | Bug fix | Revision | The terminology changed, but the bones were identical. So I forked it. --- ## The Five-Stage Workflow Prose-Kit structures writing into five phases: ### 1. Constitution — Define Your Principles Before you write a single word, you define *how* you write. This is the part most writers skip, and it's why most writing projects drift. A constitution includes: - **Voice**: Conversational, academic, technical, persuasive - **Tone**: Casual, formal, authoritative, exploratory - **Audience**: General public, domain experts, academics, decision-makers - **Length targets**: Short-form (<1,000 words), medium (~3,000), long-form (5,000+) - **Citation requirements**: None, basic tracking, formal academic The constitution is your stylistic anchor. It prevents a blog post from drifting into dissertation territory halfway through. ### 2. Specify — Outline the Content Strategy The specification answers: *What are you writing, and why does it matter?* - Topic and thesis statement - Key arguments and supporting evidence - Target scope and word count - Reader scenarios — who reads this, and what do they walk away with? This is where "reader scenarios" replace "user stories." Instead of "As a user, I want to log in," you get "As a technical lead evaluating agent architectures, I want to understand the trade-offs of context reset patterns." ### 3. Plan — Create the Blueprint The plan is your structural outline: section order, research needs, source tracking, and the logical flow from introduction to conclusion. Prose-Kit includes basic research support — tracking sources by title, author, URL, and date accessed. It deliberately does *not* try to replace Zotero or Mendeley. It tracks what you need while you write, nothing more. ### 4. Tasks — Break It Down This is where Prose-Kit diverges most from its spec-kit ancestry. Software has an "implement once" model. Prose does not. Writing is rewriting. The task structure includes explicit draft-revise cycles: - **Phase 1: Research** — Gather sources, verify claims, collect evidence - **Phase 2: Draft** — First pass, get words on paper - **Phase 3: Revise** — Restructure arguments, improve flow, tighten logic - **Phase 4: Polish** — Grammar, style, clarity, voice consistency - **Phase 5: Final review** — Read it fresh, check against the constitution A piece isn't "done" after the first draft. Multiple revision passes are expected and planned for — not treated as afterthoughts. ### 5. Implement — Write the Prose With the constitution anchoring your style, the spec defining your thesis, the plan structuring your argument, and the tasks breaking it into manageable chunks — you write. Systematically. Section by section. With clear checkpoints. --- ## Design Philosophy ### Prose-First, Always Every adaptation decision prioritizes prose writing workflows over software development patterns. When spec-kit terminology conflicts with natural writing workflows, the prose-friendly approach wins. CLI commands use writing-domain language: `prose`, `outline`, `draft` — not `specify`, `implement`. Error messages use plain English. Documentation examples come from writing projects, not codebases. If a novelist can't understand the tool, it has failed. ### Simplicity Over Features Prose-Kit follows YAGNI ruthlessly: - No complex citation management (basic tracking only) - No advanced collaboration features in v1 - No AI writing assistance baked into the core workflow - No publishing/CMS integrations until proven necessary Spec-kit's complexity grew from software development needs. Prose-Kit stays focused and approachable. ### Attribution Is Non-Negotiable Prose-Kit stands on the shoulders of Den Delimarsky and John Lam's work at GitHub. Every template, every file, every README credits the original spec-kit. MIT license with full attribution. This is both legally required and the right thing to do. --- ## Use Cases - **Blog posts** — Structured approach to conversational writing (1,000–3,000 words) - **Essays** — Long-form exploratory writing with clear argumentation - **Research papers** — Academic writing with citations and formal structure - **Technical whitepapers** — Deep technical documentation with evidence - **Documentation** — Project docs and guides --- ## The Meta Part Here's the thing I love most: Prose-Kit uses spec-kit to manage its own development. The tool for structured prose writing is itself being built through structured spec-driven development. It also uses [beads](https://github.com/beadsdotdev/beads) for issue tracking — because when your project is about structured workflows, you'd better practice what you preach. --- ## Status Prose-Kit is in early development. The constitution is ratified, the templates are adapted, and the CLI is being built on Python 3.11 with Typer and Rich. Installation instructions are coming once the core workflow stabilizes. The repo is open source under MIT license. **GitHub:** [prefrontalsys/prose-kit](https://github.com/prefrontalsys/prose-kit) --- *Write better prose, faster. Give your writing a build process.*