# OpenSpec Skeleton Bootstrap

Shared bootstrap procedure used by the `ss-write-spec` and `ss-reverse-spec` skills. Run
this only when a project has no OpenSpec structure yet (no `openspec/specs/` or
`openspec/changes/` directory) — otherwise skip it entirely and never overwrite an
existing skeleton.

## What to Create

```plaintext
openspec/
├── README.md
├── AGENTS.md
├── config.yaml
├── specs/
│   └── .gitkeep
└── changes/
    ├── .gitkeep
    └── archive/
        └── .gitkeep
```

## openspec/README.md

Write:

```markdown
# OpenSpec

This directory holds the project's living capability specs.

- `openspec/specs/` is the source of truth for what the system currently does.
- `openspec/changes/<change-id>/specs/<capability>/spec.md` holds delta specs for changes
  in flight.
- A change's `proposal.md` explains why and what; `design.md` is optional for
  architecturally significant changes. The execution plan itself lives only in
  `docs/plans/` (generated by the `ss-plan` skill) — the change directory does not
  carry a separate tasks file.

Use the `ss-write-spec` or `ss-plan` skill to generate delta specs, and the
`ss-archive` skill to merge them into the source of truth.
```

## openspec/AGENTS.md

Write:

```markdown
# OpenSpec Playbook (for AI agents)

This file is the on-demand playbook for the `openspec/` directory. Read it before touching
any spec, and use it to decide which file to read next and which skill to invoke.

## Directory Layout

    openspec/
    ├── specs/<capability>/spec.md        # current contract (source of truth, produced by
    │                                      # `ss-archive` — never hand-edit)
    ├── changes/<change-id>/               # a change in flight
    │   ├── proposal.md                    # why and what
    │   └── specs/<capability>/spec.md     # delta (ADDED / MODIFIED / REMOVED / RENAMED)
    └── changes/archive/YYYY-MM-DD-<id>/   # archived changes (read on demand)

> The execution plan (task list) lives in `docs/plans/`, generated by `ss-plan`; the
> change directory does not keep a separate tasks file.

## When to Read What

| Situation | Read |
|-----------|------|
| Before a new feature or behavior change | the relevant `openspec/specs/<cap>/spec.md`, plus active `openspec/changes/*/specs/*/spec.md` (excluding archive) |
| Before writing a delta | the full current `openspec/specs/<cap>/spec.md` — a `MODIFIED` entry must paste the complete original Requirement |
| During implementation | `changes/<id>/proposal.md` + `changes/<id>/specs/<cap>/spec.md` + the execution plan in `docs/plans/` |
| Before archiving / opening a PR | the current `specs/` version, to check delta completeness |
| Tracing a Requirement's history | use the `ss-trace-spec` skill |

**Don't load all of `openspec/` into context at once.** Use the `ss-show-spec` skill to
list capabilities or search by keyword, then read only the one file you need.

## Workflow Entry Points

| Goal | Skill |
|------|-------|
| Plan a new requirement; generate a delta plus an execution plan | `ss-plan` (its Phase 0 reads specs and active changes, then runs the same logic as `ss-write-spec`) |
| Look up a capability's current contract, or search capabilities | `ss-show-spec [<capability> \| <keyword>]` — no argument lists everything |
| List active changes and recent archive entries | `ss-list-changes` |
| Trace a Requirement's history | `ss-trace-spec` |
| Merge a delta into the source of truth | `ss-archive` (usually called automatically by `ss-create-pr`) |
| Run a requirement end to end | `ss-feature-workflow` |

## Hard Rule: Read Before You Change Behavior

Before any code change that could affect system behavior, you MUST:

1. List the capabilities (kebab-case names) the change touches.
2. Read `openspec/specs/<cap>/spec.md` for each one.
3. If the change modifies an existing Requirement, also read the 3 most recent archived
   changes that touched it.
4. State explicitly, in the proposal or delta, how the change relates to existing
   behavior: compatible, breaking, or a replacement.

## Delta Format (mandatory)

Only these four sections are allowed:

- `## ADDED Requirements` — new capability behavior
- `## MODIFIED Requirements` — changes to existing behavior
- `## REMOVED Requirements` — deprecated behavior
- `## RENAMED Requirements` — renamed behavior

Rules:

- Every Requirement MUST have at least one `#### Scenario:` (four hashes).
- `MODIFIED` MUST paste the complete updated Requirement (header + all scenarios) — the
  `ss-archive` skill replaces the whole entry, so a partial diff would lose content.
- `REMOVED` MUST include a **Reason** and a **Migration** note.
- `RENAMED` uses `FROM: <old> → TO: <new>`; combine with `MODIFIED` if behavior also
  changes.
- A Requirement's header text must match the `specs/` original (whitespace-insensitive).

## Do Not

- Hand-edit `specs/<cap>/spec.md` — it's generated by the `ss-archive` skill.
- Load the entire `openspec/` directory into context up front.
- Start implementation before a proposal is confirmed.
```

## openspec/config.yaml

Write:

```yaml
schema: spec-driven

context: |
  Describe this service's responsibilities, tech stack, and upstream/downstream
  dependencies here.

rules:
  delta:
    - REMOVED Requirements MUST include a Migration note.
    - Every Requirement MUST have at least one Scenario.
  spec:
    - Capability names use kebab-case business noun phrases.
```

## specs/.gitkeep, changes/.gitkeep, changes/archive/.gitkeep

Create these as empty files so version control tracks the otherwise-empty directories.