init-sdd

name	init-sdd
description	Use when bootstrapping a repository for Spec-Driven Development. Scan the codebase, ask 2 targeted questions, then write specs/constitution.md and the first epic's product-requirements.md.

Purpose

Bootstraps a repository for Spec-Driven Development by establishing the two foundational artifacts:

1. specs/constitution.md — the project's governing principles, filled from observed repo context and user intent
2. specs/{epic-name}/product-requirements.md — the first epic, written as a structured product requirement that a Product Owner can use to derive user stories

This skill is written to be tool-agnostic so it can be reused in Copilot, Codex, Claude Code, or any other agent runtime that can read files, ask questions, and write markdown.

When to Use

Use this skill when a repository is being initialized for the SDD workflow and does not yet have a well-formed specs/constitution.md and first epic-level product requirements.

Workflow

Do not skip steps. Do not produce the files before asking the questions. Work in the exact order below.

Step 1 — Scan the Codebase

Before saying anything to the user, scan the repository silently. Look for:

• README.md, package.json, pyproject.toml, *.csproj, Cargo.toml, go.mod, or equivalent — to identify technology stack, frameworks, and dependencies
• Directory structure — to understand how the project is organized (layers, modules, features)
• Any existing files in specs/ — to understand if a constitution or specs already exist
• Config files (.eslintrc, jest.config.*, tsconfig.json, docker-compose.*, etc.) — to infer coding standards, testing approach, and infrastructure
• CHANGELOG.md, HISTORY.md, or git tags — to understand what has already been shipped

Build an internal model of:

• What the project appears to do
• What tech stack it uses
• What coding patterns are visible
• What has already been achieved (if anything is shipped)

Do NOT write the files yet.

Step 2 — Present Your Understanding and Ask 2 Questions

Present a short, honest summary of what you observed. Be specific. Acknowledge clearly what you could infer and what you could not.

Then ask exactly these 2 questions, in plain conversational language:

Question 1: Based on what I can see, [describe your best inference of what the project does and what it has achieved so far]. Is that accurate? What would you add or correct about the current state of this project?

Question 2: What is the intent behind this project — why does it exist, and what would it mean for it to be truly successful? (This is about the purpose and philosophy, not the technical goals.)

Do not ask more than 2 questions. Do not ask about tech stack — you already know it. Wait for the user's answers before continuing.

Step 3 — Ask for the First Epic Name

After the user answers, say:

Great. Before I write the first product requirements, what do you want to call this first epic? This will be the folder name under specs/ — something short and descriptive, like user-onboarding or core-api.

Wait for the user's answer.

Step 4 — Write specs/constitution.md

Using what you scanned in Step 1 and what the user told you in Step 2, fill in specs/constitution.md.

Rules:

• Fill every section you have enough information for
• For sections you cannot fill with confidence, write [NEEDS CLARIFICATION: <specific question>] — do not leave template placeholders
• The Project Intent section must reflect the philosophy the user described, not just technical facts
• Technology Stack must come from what you observed in the codebase, not guesses
• Do not invent architecture principles — only write ones you can justify from what you saw or were told
• Do not modify this file again unless the user explicitly asks

Use this structure:

# Project Constitution

## Project Overview

- **Project name**: [from README or inferred]
- **Description**: [one sentence — what this project does]
- **Primary users**: [who uses this — from user answers]
- **Current state**: [what has been built and shipped so far]

## Project Intent

[2–3 sentences: why this project exists and what success looks like. Write this in the user's voice, from their answer to Question 2.]

## Technology Stack

- **Language**: [observed]
- **Framework**: [observed]
- **Database**: [observed or N/A]
- **Infrastructure**: [observed or N/A]
- **Testing**: [observed or N/A]

## Architecture Principles

[Only include principles you can justify from the codebase or what the user told you. If none are clear yet, write one placeholder with [NEEDS CLARIFICATION].]

1. **[Principle name]**: [Brief description]

## Coding Standards

- **Style**: [observed from lint/format config, or [NEEDS CLARIFICATION]]
- **Naming**: [observed or [NEEDS CLARIFICATION]]
- **Error handling**: [observed or [NEEDS CLARIFICATION]]
- **Comments**: [observed or [NEEDS CLARIFICATION]]

## Testing Standards

- **Required coverage**: [observed or [NEEDS CLARIFICATION]]
- **Test types**: [observed or [NEEDS CLARIFICATION]]
- **Test approach**: [observed or [NEEDS CLARIFICATION]]

## Security Requirements

- **Authentication**: [observed or [NEEDS CLARIFICATION]]
- **Authorization**: [observed or [NEEDS CLARIFICATION]]
- **Data handling**: [observed or [NEEDS CLARIFICATION]]
- **Dependencies**: [observed or [NEEDS CLARIFICATION]]

## Constraints

[List any real constraints visible in the codebase or mentioned by the user. Do not fabricate constraints.]

## Amendment Process

Agents assist human decision-making; they do not replace engineering judgment.

Changes to this constitution require:
1. Explicit documentation of the rationale
2. Review by the project owner
3. Backward compatibility assessment

Step 5 — Write specs/{epic-name}/product-requirements.md

Using everything gathered, write the first product requirements document. This is an epic-level artifact — no user stories, no technical design. It exists so a Product Owner can read it and derive Jira tickets, and so the Architect agent can generate a formal spec from it.

Use this structure:

# Product Requirements: [Epic Name]

## Status

- **Created**: [today's date]
- **Status**: Draft
- **Author**: Strategist (init-sdd)
- **Epic folder**: `specs/[epic-name]/`

## Epic Goal

[One sentence: what this epic achieves and why it matters now.]

## Current State

[What exists today. What has already been built or shipped. What is working and what is not. Be specific about what this epic builds on top of.]

## Problem / Opportunity

[What gap or opportunity does this epic address? Why is this the right thing to build next? Frame it from the user's or business's perspective.]

## Users and Context

- **Who** benefits from this epic?
- **When** do they encounter the problem this solves?
- **What** do they currently do instead (workaround, manual process, nothing)?

## Intent and Philosophy

[Why does this epic exist beyond just shipping a feature? What principle or belief is it expressing? Reflect the project philosophy here.]

## Scope

### In Scope

- [Capability or outcome 1]
- [Capability or outcome 2]

### Out of Scope

- [What this epic explicitly does not address]

## Open Questions

[List unresolved decisions that a Product Owner or Architect will need to answer before or during spec generation. Be specific.]

- [ ] [Question 1]
- [ ] [Question 2]

## Success Criteria

[How will we know this epic was successful? Write these in non-technical, outcome-oriented language.]

- [Criterion 1]
- [Criterion 2]

Step 6 — Confirm and Hand Off

After writing both files, tell the user:

I've written specs/constitution.md and specs/[epic-name]/product-requirements.md.

Next steps:

• Review both files and correct anything that doesn't match your intent
• When you're ready to build, take a user story to the Architect along with the product requirements — it will generate the technical spec, plan, and task breakdown
• To update the constitution, explicitly ask the Strategist to amend it with your reasoning

Rules

• Do not produce any file before completing Steps 1–3
• Do not ask more than 2 questions in Step 2
• Do not write code, tests, or implementation files
• Do not modify specs/constitution.md after writing it unless explicitly instructed by the user
• If specs/constitution.md already exists and is filled in, tell the user and ask if they want to overwrite it before proceeding
• If specs/{epic-name}/product-requirements.md already exists, tell the user before overwriting