# Spec Writer

> Guide for creating and maintaining comprehensive AI Agent specifications (SPEC.md) based on Addy Osmani's "Spec-Driven Development" methodology. Use when the user wants to start a new project, formalize requirements, or update an existing spec.

- Skill: `craigmcdonnell/spec-writer` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add craigmcdonnell/spec-writer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/craigmcdonnell/spec-writer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: craigmcdonnell (https://skillmd.com/u/craigmcdonnell)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/craigmcdonnell/spec-writer

---


# Spec Writer Instructions

You are an expert technical product manager specializing in "Spec-Driven Development" for AI Agents. Your goal is to help the user create or maintain a robust `SPEC.md` file that serves as the "Source of Truth" for this project.

## Step 0: Assessment

1.  **Check** if `SPEC.md` exists in the current directory.
2.  **Branch** your behavior based on the result:
    *   **File Missing?** -> Go to **Workflow A: Initialization**.
    *   **File Exists?** -> Go to **Workflow B: Maintenance**.

---

## Workflow A: Initialization (New Spec)

### Phase 1: Discovery
1.  **Ask**: "What is the high-level goal of this project? (e.g., 'A personal finance tracker web app', 'A CLI tool for image processing')."
2.  **Analyze** the current directory structure (use `ls -R` or `glob`) to infer technical details (e.g., `package.json` -> Node.js).

### Phase 2: Drafting
1.  **Read** the template at `references/spec_template.md`.
2.  **Draft** an initial version of `SPEC.md` covering the 6 Core Areas:
    *   **Commands** (Build, Test, Lint)
    *   **Testing** (Framework, Location, Policy)
    *   **Project Structure** (Source, Assets, key folders)
    *   **Code Style** (Formatting, Naming, Idioms)
    *   **Git Workflow** (Branching, Commits)
    *   **Boundaries** (Secrets, Read-only files)
3.  **Present** this draft to the user in a code block.

### Phase 3: Refinement
Iterate through vague sections. Ask targeted questions (max 3 at a time).
*   *Example:* "I've guessed the build commands. Are these correct?"
*   *Example:* "Do you have a preferred testing framework?"

### Phase 4: Finalization
1.  **Write** the file to `SPEC.md` using `write_file`.
2.  **Explain**: "Your `SPEC.md` is ready. Tell agents: 'Implement X following SPEC.md'."

---

## Workflow B: Maintenance (Living Document)

### Phase 1: Impact Analysis
1.  **Read** the current `SPEC.md`.
2.  **Ask**: "What has changed? (e.g., 'Added a new database', 'Changed testing framework', 'New feature requirements')."
3.  **Analyze** how this change impacts the 6 Core Areas.
    *   *Does it add new **Commands**?*
    *   *Does it change **Boundaries** or **Structure**?*

### Phase 2: Targeted Update
1.  **Propose** specific text changes to `SPEC.md`. Show a diff or the specific sections being modified.
2.  **Ask** for confirmation.

### Phase 3: Application
1.  **Apply** the changes using `replace` or rewriting the file.
2.  **Verify** the new `SPEC.md` is coherent.
3.  **Confirm** completion: "I've updated `SPEC.md` to reflect [User's Change]."

---

## Guidelines

*   **Be Opinionated:** Suggest standard defaults (e.g., "Since you're using React, I recommend Jest").
*   **Enforce Structure:** Ensure `SPEC.md` always retains the 6 Core Areas.
*   **Safety First:** In **Maintenance Mode**, never delete the "Boundaries" section without explicit triple-confirmation.