# Jeremylongshore Claude Code Plugins Plus Skills Spec Writing > Spec Writing - Skill: `tomevault-io/jeremylongshore-claude-code-plugins-plus-skills-spec-writing` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/jeremylongshore-claude-code-plugins-plus-skills-spec-writing` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/jeremylongshore-claude-code-plugins-plus-skills-spec-writing/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/jeremylongshore-claude-code-plugins-plus-skills-spec-writing --- # Spec Writing ## Overview Spec Writing provides guidance on authoring effective `specs.md` files that drive the Sprint plugin's autonomous development workflow. A well-written specification determines the quality of agent output by clearly defining goals, scope boundaries, and testing requirements. ## Prerequisites - Sprint plugin installed (`/plugin install sprint`) - Project onboarding completed via `/sprint:setup` (creates `project-goals.md` and `project-map.md`) - Sprint directory created via `/sprint:new` (generates `.claude/sprint/[N]/specs.md`) - Understanding of the sprint phase lifecycle (see the `sprint-workflow` skill) ## Instructions 1. Open the generated `specs.md` file at `.claude/sprint/[N]/specs.md` and define a concise goal statement at the top. State what the sprint delivers in one sentence (e.g., "Add user authentication with email/password login"). 2. Define explicit scope boundaries using **In Scope** and **Out of Scope** sections. List specific features, endpoints, or components in each. Agents only implement what appears in scope; ambiguity leads to drift. 3. Add the **Testing** section to control which testing agents run and how. Configure three settings as documented in `${CLAUDE_SKILL_DIR}/references/testing-configuration.md`: - `QA`: `required` | `optional` | `skip` -- Controls API and unit test execution - `UI Testing`: `required` | `optional` | `skip` -- Controls browser-based E2E tests - `UI Testing Mode`: `automated` | `manual` -- Auto-run or user-driven testing 4. Set QA to `required` for new API endpoints, business logic changes, and data validation rules. Set QA to `skip` for frontend-only changes, documentation updates, or configuration changes. 5. Set UI Testing to `required` for user-facing features, form submissions, and navigation flows. Choose `automated` mode for regression testing and standard CRUD flows; choose `manual` mode for complex interactions, visual verification, or exploratory testing. 6. Keep specifications minimal but precise. The architect expands high-level specs into detailed implementation files (`backend-specs.md`, `frontend-specs.md`, `api-contract.md`). Over-specifying implementation details in `specs.md` constrains the architect unnecessarily. 7. For iterative sprints, review `status.md` from the previous iteration. Remove completed items from specs and add any new requirements or bug fixes discovered during testing. ## Output - A complete `specs.md` file with goal, scope (in/out), and testing configuration - Clear scope boundaries that prevent agent drift during implementation - Testing configuration that selects appropriate QA and UI testing agents - Iteratively refined specs where completed work is removed and remaining work is focused ## Error Handling | Error | Cause | Solution | |-------|-------|----------| | Agents implement unintended features | Missing "Out of Scope" section | Explicitly list features excluded from this sprint | | Tests not running during sprint | Testing section omitted or set to `skip` | Add `QA: required` and `UI Testing: required` to the Testing section | | Sprint iterates without converging | Specs too broad for a single sprint | Break into smaller sprints targeting one domain boundary each | | Architect produces conflicting spec files | Ambiguous or contradictory requirements in `specs.md` | Review for conflicting statements; each requirement should have a single interpretation | | Manual tests not triggered | `UI Testing Mode` set to `automated` | Change to `manual` for scenarios requiring visual verification or exploratory testing | ## Examples **Minimal but effective spec:** ```markdown # Sprint 1: User Authentication ## Goal Add user authentication with email/password login ## Scope ### In Scope - Registration endpoint (POST /auth/register) - Login endpoint (POST /auth/login) - JWT token generation and validation - Password hashing with bcrypt ### Out of Scope - OAuth providers (Google, GitHub) - Password reset flow - Email verification ## Testing - QA: required - UI Testing: required - UI Testing Mode: automated ``` **Frontend-only sprint (no QA needed):** ```markdown # Sprint 3: Dashboard Redesign ## Goal Redesign the admin dashboard with responsive layout ## Scope ### In Scope - Responsive grid layout for dashboard widgets - Dark mode toggle - Mobile navigation drawer ### Out of Scope - New API endpoints - Database changes - Authentication changes ## Testing - QA: skip - UI Testing: required - UI Testing Mode: manual ``` ## Resources - `${CLAUDE_SKILL_DIR}/references/testing-configuration.md` -- Testing section options with guidance on when to use each setting - Sprint workflow skill for understanding how specs feed into the phase lifecycle - API contract skill for designing endpoint contracts referenced by specs --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/jeremylongshore) — claim your Tome and manage your conversions.