openspecpm 0.1.0-alpha.0 → 1.0.0

package/skill/openspecpm/references/conventions.md

@@ -1,105 +1,106 @@
-# Conventions
-
-These rules apply to every phase of OpenSpecPM. Read this before touching files.
-
-## Paths
-
-| Artifact | Path |
-|---|---|
-| Project config | `.openspecpm/config.json` (chosen adapter, repo/org/project identifiers) |
-| Project state | `.openspecpm/state.json` (not committed; idempotency hints) |
-| OpenSpec changes | `openspec/changes/<feature>/` (owned by OpenSpec) |
-| Proposal | `openspec/changes/<feature>/proposal.md` |
-| Design | `openspec/changes/<feature>/design.md` |
-| Tasks | `openspec/changes/<feature>/tasks.md` |
-| BDD specs | `openspec/changes/<feature>/specs/*.md` |
-| Progress (local) | `openspec/changes/<feature>/updates/<task-id>/progress.md` |
-| Archive | `openspec/archive/<YYYY-MM-DD>-<feature>/` (owned by OpenSpec) |
-
-The OpenSpec layout is authoritative — do not invent a parallel `.claude/...` tree. We sit *above* OpenSpec, not beside it.
-
-## Secrets
-
-Never write tokens to `.openspecpm/config.json`. Use environment variables:
-
-- GitHub: `gh auth login` handles the token; no env var needed.
-- Azure DevOps: `AZURE_DEVOPS_EXT_PAT` (Work Items: Read/Write).
-- Jira: `JIRA_EMAIL` + `JIRA_API_TOKEN`.
-- Linear: `LINEAR_API_KEY`.
-- GitLab: `GITLAB_TOKEN` (`api` scope).
-
-## Frontmatter schemas
-
-All artifacts use YAML frontmatter. Required fields:
-
-### proposal.md
-
-```yaml
----
-name: <feature-slug>
-status: draft | in_review | approved | shipped
-created: <ISO-8601 timestamp>
-schema_version: 1
-external:                          # filled by `openspecpm sync`
-  github:
-    adapter: github
-    id: "42"
-    url: https://github.com/.../issues/42
----
-```
-
-### tasks.md
-
-```yaml
----
-schema_version: 1
-items:
-  - title: "Implement X"
-    sync_state: pending | created | failed
-    external_id: "43"              # filled after sync
-    external_url: https://...
-    depends_on: []                  # task titles or external ids
-    parallel: true | false
----
-```
-
-If `items:` is absent, OpenSpecPM falls back to parsing `- [ ] title` checklist lines in the body.
-
-## BDD format
-
-Scenarios in `specs/*.md` should use Gherkin-style triplets:
-
-```
-Scenario: User toggles dark mode
-  Given the user is signed in
-  And their theme preference is "system"
-  When they select "Dark" in the appearance menu
-  Then the UI re-renders in dark theme
-  And their preference is saved to the profile
-```
-
-Lint heuristics (enforced softly at `propose`, hard at `sync` in Sprint 3+):
-
-- Each scenario has one `Given`, one `When`, one `Then` (with optional `And`s).
-- `Then` uses an observable verb (displays, returns, stores, rejects, emails, …).
-- Reject "should work", "should be correct", "is successful" as `Then` predicates.
-- Reject tautological `Then` (paraphrase of the `When`).
-
-## ISO timestamps
-
-All `created` / `updated` / `synced` fields use ISO-8601 with timezone:
-
-```
-2026-05-17T14:30:00Z
-```
-
-## Sync markers
-
-Comments pushed to the PM tool are append-only and stamped:
-
-```
-<!-- SYNCED: 2026-05-17T14:30:00Z -->
-…progress narrative…
-```
-
-This lets re-syncs detect what's already been sent without duplicating.
+# Conventions
+
+These rules apply to every phase of OpenSpecPM. Read this before touching files.
+
+## Paths
+
+| Artifact | Path |
+|---|---|
+| Project config | `.openspecpm/config.json` (chosen adapter, repo/org/project identifiers) |
+| Project state | `.openspecpm/state.json` (not committed; idempotency hints) |
+| OpenSpec changes | `openspec/changes/<feature>/` (owned by OpenSpec) |
+| Proposal | `openspec/changes/<feature>/proposal.md` |
+| Design | `openspec/changes/<feature>/design.md` |
+| Tasks | `openspec/changes/<feature>/tasks.md` |
+| BDD specs | `openspec/changes/<feature>/specs/*.md` |
+| Progress (local) | `openspec/changes/<feature>/updates/<task-id>/progress.md` |
+| Archive | `openspec/archive/<YYYY-MM-DD>-<feature>/` (owned by OpenSpec) |
+
+The OpenSpec layout is authoritative — do not invent a parallel `.claude/...` tree. We sit *above* OpenSpec, not beside it.
+
+## Secrets
+
+Never write tokens to `.openspecpm/config.json`. Use environment variables:
+
+- GitHub: `gh auth login` handles the token; no env var needed.
+- Azure DevOps: `AZURE_DEVOPS_EXT_PAT` (Work Items: Read/Write).
+- Jira: `JIRA_EMAIL` + `JIRA_API_TOKEN`.
+- Linear: `LINEAR_API_KEY`.
+- GitLab: `GITLAB_TOKEN` (`api` scope).
+- LLM BDD judge (optional, opt-in via `--llm` or `judge.enabled` config): `ANTHROPIC_API_KEY`.
+
+## Frontmatter schemas
+
+All artifacts use YAML frontmatter. Required fields:
+
+### proposal.md
+
+```yaml
+---
+name: <feature-slug>
+status: draft | in_review | approved | shipped
+created: <ISO-8601 timestamp>
+schema_version: 1
+external:                          # filled by `openspecpm sync`
+  github:
+    adapter: github
+    id: "42"
+    url: https://github.com/.../issues/42
+---
+```
+
+### tasks.md
+
+```yaml
+---
+schema_version: 1
+items:
+  - title: "Implement X"
+    sync_state: pending | created | failed
+    external_id: "43"              # filled after sync
+    external_url: https://...
+    depends_on: []                  # task titles or external ids
+    parallel: true | false
+---
+```
+
+If `items:` is absent, OpenSpecPM falls back to parsing `- [ ] title` checklist lines in the body.
+
+## BDD format
+
+Scenarios in `specs/*.md` should use Gherkin-style triplets:
+
+```
+Scenario: User toggles dark mode
+  Given the user is signed in
+  And their theme preference is "system"
+  When they select "Dark" in the appearance menu
+  Then the UI re-renders in dark theme
+  And their preference is saved to the profile
+```
+
+Lint heuristics (enforced softly at `propose`, hard at `sync` in Sprint 3+):
+
+- Each scenario has one `Given`, one `When`, one `Then` (with optional `And`s).
+- `Then` uses an observable verb (displays, returns, stores, rejects, emails, …).
+- Reject "should work", "should be correct", "is successful" as `Then` predicates.
+- Reject tautological `Then` (paraphrase of the `When`).
+
+## ISO timestamps
+
+All `created` / `updated` / `synced` fields use ISO-8601 with timezone:
+
+```
+2026-05-17T14:30:00Z
+```
+
+## Sync markers
+
+Comments pushed to the PM tool are append-only and stamped:
+
+```
+<!-- SYNCED: 2026-05-17T14:30:00Z -->
+…progress narrative…
+```
+
+This lets re-syncs detect what's already been sent without duplicating.

package/skill/openspecpm/references/structure.md

@@ -1,52 +1,52 @@
-# Structure — Decomposing a proposal into tasks
-
-**When to use this:** A proposal exists at `openspec/changes/<feature>/proposal.md` and the user wants to break it down into individual work items.
-
-## Outcome
-
-A populated `openspec/changes/<feature>/tasks.md` where the `items:` frontmatter array lists every task with: title, dependency edges, parallelizability, and a `sync_state: pending` marker.
-
-## Flow
-
-1. **Read the proposal and specs.** Open `proposal.md`, `design.md`, and every file in `specs/`. Build a mental model of what behavior must exist for the change to be complete.
-
-2. **Group by stream.** Most features decompose into 2–5 independent streams. Common patterns:
-   - **Data:** schema, migrations, persistence layer
-   - **Service:** business logic, validation, domain rules
-   - **API:** HTTP/RPC/CLI surface
-   - **UI:** components, flows, accessibility
-   - **Tests:** end-to-end coverage of the new behavior
-
-   Streams that can be worked in parallel get `parallel: true`. Streams that must wait on another stream get `depends_on: ["<earlier-task-title>"]`.
-
-3. **Right-size each task.** A task should be 2–8 hours of focused work for one engineer. If a task is bigger, split. If smaller, merge into the next one (overhead exceeds value).
-
-4. **Write tasks.md.** Use the frontmatter schema from `conventions.md`. Every task gets:
-   ```yaml
-   - title: "Add user_preferences.theme column"
-     sync_state: pending
-     depends_on: []
-     parallel: true
-     effort_hours: 3
-   ```
-
-5. **Cross-check against BDD scenarios.** Every scenario in `specs/*.md` should map to at least one task. If a scenario is unimplemented, add a task. If a task isn't traceable to any scenario, ask whether it's actually needed.
-
-## Hierarchy and the target PM tool
-
-The backend's `capabilities().hierarchyDepth` determines how the structure projects into work items:
-
-| Backend | Depth | Mapping |
-|---|---|---|
-| GitHub | 2 | Epic issue → sub-issues (via `gh-sub-issue`) |
-| Linear | 2 | Project → Issues |
-| GitLab | 2 | Parent issue → linked child issues (`relates_to` / `blocks`) |
-| Jira | 3 | Epic → Story → Sub-task |
-| Azure DevOps | 4 | Epic → Feature → User Story → Task |
-
-The sync layer will **collapse levels gracefully** when authoring depth exceeds backend depth — e.g. on GitHub, "Feature" and "Story" levels are flattened into siblings of the Epic with a label tag, and a warning is printed. You do not need to author differently for each backend; author the deepest sensible structure and let the adapter compress.
-
-## After this phase
-
-- Route to `references/sync.md` to push tasks to the PM tool.
-- If decomposition surfaced unknowns, route back to `references/plan.md` to refine the proposal.
+# Structure — Decomposing a proposal into tasks
+
+**When to use this:** A proposal exists at `openspec/changes/<feature>/proposal.md` and the user wants to break it down into individual work items.
+
+## Outcome
+
+A populated `openspec/changes/<feature>/tasks.md` where the `items:` frontmatter array lists every task with: title, dependency edges, parallelizability, and a `sync_state: pending` marker.
+
+## Flow
+
+1. **Read the proposal and specs.** Open `proposal.md`, `design.md`, and every file in `specs/`. Build a mental model of what behavior must exist for the change to be complete.
+
+2. **Group by stream.** Most features decompose into 2–5 independent streams. Common patterns:
+   - **Data:** schema, migrations, persistence layer
+   - **Service:** business logic, validation, domain rules
+   - **API:** HTTP/RPC/CLI surface
+   - **UI:** components, flows, accessibility
+   - **Tests:** end-to-end coverage of the new behavior
+
+   Streams that can be worked in parallel get `parallel: true`. Streams that must wait on another stream get `depends_on: ["<earlier-task-title>"]`.
+
+3. **Right-size each task.** A task should be 2–8 hours of focused work for one engineer. If a task is bigger, split. If smaller, merge into the next one (overhead exceeds value).
+
+4. **Write tasks.md.** Use the frontmatter schema from `conventions.md`. Every task gets:
+   ```yaml
+   - title: "Add user_preferences.theme column"
+     sync_state: pending
+     depends_on: []
+     parallel: true
+     effort_hours: 3
+   ```
+
+5. **Cross-check against BDD scenarios.** Every scenario in `specs/*.md` should map to at least one task. If a scenario is unimplemented, add a task. If a task isn't traceable to any scenario, ask whether it's actually needed.
+
+## Hierarchy and the target PM tool
+
+The backend's `capabilities().hierarchyDepth` determines how the structure projects into work items:
+
+| Backend | Depth | Mapping |
+|---|---|---|
+| GitHub | 2 | Epic issue → sub-issues (via `gh-sub-issue`) |
+| Linear | 2 | Project → Issues |
+| GitLab | 2 | Parent issue → linked child issues (`relates_to` / `blocks`) |
+| Jira | 3 | Epic → Story → Sub-task |
+| Azure DevOps | 4 | Epic → Feature → User Story → Task |
+
+The sync layer will **collapse levels gracefully** when authoring depth exceeds backend depth — e.g. on GitHub, "Feature" and "Story" levels are flattened into siblings of the Epic with a label tag, and a warning is printed. You do not need to author differently for each backend; author the deepest sensible structure and let the adapter compress.
+
+## After this phase
+
+- Route to `references/sync.md` to push tasks to the PM tool.
+- If decomposition surfaced unknowns, route back to `references/plan.md` to refine the proposal.

package/skill/openspecpm/references/sync.md

@@ -1,56 +1,56 @@
-# Sync — Pushing an OpenSpec change to the PM tool
-
-**When to use this:** The user has a proposal + tasks ready and wants them tracked in GitHub Issues / Azure DevOps Boards / Jira / Linear / GitLab Issues.
-
-## Outcome
-
-For the chosen adapter, the epic and every task are created as work items, linked into a hierarchy where the backend supports it, and recorded back into local frontmatter (`external:` on `proposal.md`, `external_id` + `external_url` on each task in `tasks.md`).
-
-## The CLI does the work
-
-```
-openspecpm sync <feature>             # create + update
-openspecpm sync <feature> --dry-run   # print the call plan, no remote writes
-```
-
-Do not script `gh issue create` or hand-craft REST calls in agent reasoning — let the adapter handle vocabulary differences across backends.
-
-## Idempotency contract
-
-Sync is safe to re-run. The rules:
-
-1. **Epic:** if `proposal.md` frontmatter already carries `external.<adapter>` with an `id`, the existing epic is reused. No duplicate epics are ever created.
-2. **Tasks:** each task carries `sync_state: pending | created | failed`. `sync` skips `created` items and retries `failed` ones.
-3. **Comments:** progress comments stamped `<!-- SYNCED: <iso-timestamp> -->` are append-only. Re-running sync after a comment was posted does not repost.
-
-This means: if the network fails halfway through a 30-task sync, fix the cause, re-run, and only the un-created items get created.
-
-## Capabilities and hierarchy collapse
-
-Each adapter reports `capabilities()`. The sync layer reads `hierarchyDepth`:
-
-- **GitHub (depth 2):** Epic issue + flat task sub-issues. If the task tree authored depth >2, intermediate levels are flattened into siblings tagged `openspec:<feature>` and a one-line warning is printed.
-- **Linear (depth 2):** Project as epic, issues as tasks under the project. `parent` relation when supported by the workspace.
-- **GitLab (depth 2):** Parent issue + child issues linked via `relates_to` / `blocks`. Milestone serves as the epic container if `--milestone` is supplied.
-- **Jira (depth 3):** Epic → Story → optional Sub-task. Stories without sub-tasks just sit under the Epic via `Relates` link.
-- **Azure DevOps (depth 4):** Epic → Feature → User Story → Task with `System.LinkTypes.Hierarchy-Reverse` Parent links.
-
-## Field mapping per adapter
-
-| OpenSpec field | GitHub | Azure DevOps | Jira | Linear | GitLab |
-|---|---|---|---|---|---|
-| `task.title` | Issue title | `System.Title` | `summary` | `title` | `title` |
-| `task.body` | Issue body (markdown) | `System.Description` (HTML) | `description` (ADF) | `description` (markdown) | `description` (markdown) |
-| `feature.name` (tag) | label `openspec:<name>` | tag `openspec:<name>` | label `openspec-<name>` | label `openspec:<name>` | label `openspec:<name>` |
-| `task.depends_on` | task-list reference in body | `System.LinkTypes.Dependency` link | `Blocks` issue link | issue relation `blocks` | issue link `blocks` |
-| `task.iteration` | (ignored, depth=2) | `System.IterationPath` | sprint custom field | `cycleId` | `milestone` |
-| `task.assignee` | `--add-assignee` | `System.AssignedTo` | `assignee.accountId` | `assigneeId` | `assignee_ids` |
-| `task.effort_hours` | (ignored) | `Microsoft.VSTS.Scheduling.Effort` | story-points custom field | `estimate` | `weight` |
-
-The CLI handles the translation. Author tasks in the OpenSpec/CCPM dialect described in `conventions.md`.
-
-## After sync
-
-- Each item is now visible in the PM tool. The user can route stakeholders to those URLs for sign-off.
-- Progress narrative still lives locally in `openspec/changes/<feature>/updates/<task>/progress.md`. Use `openspecpm comment <task>` (Sprint 3) to broadcast a new update to the PM tool.
-- Route to `references/execute.md` when the user is ready to start building.
+# Sync — Pushing an OpenSpec change to the PM tool
+
+**When to use this:** The user has a proposal + tasks ready and wants them tracked in GitHub Issues / Azure DevOps Boards / Jira / Linear / GitLab Issues.
+
+## Outcome
+
+For the chosen adapter, the epic and every task are created as work items, linked into a hierarchy where the backend supports it, and recorded back into local frontmatter (`external:` on `proposal.md`, `external_id` + `external_url` on each task in `tasks.md`).
+
+## The CLI does the work
+
+```
+openspecpm sync <feature>             # create + update
+openspecpm sync <feature> --dry-run   # print the call plan, no remote writes
+```
+
+Do not script `gh issue create` or hand-craft REST calls in agent reasoning — let the adapter handle vocabulary differences across backends.
+
+## Idempotency contract
+
+Sync is safe to re-run. The rules:
+
+1. **Epic:** if `proposal.md` frontmatter already carries `external.<adapter>` with an `id`, the existing epic is reused. No duplicate epics are ever created.
+2. **Tasks:** each task carries `sync_state: pending | created | failed`. `sync` skips `created` items and retries `failed` ones.
+3. **Comments:** progress comments stamped `<!-- SYNCED: <iso-timestamp> -->` are append-only. Re-running sync after a comment was posted does not repost.
+
+This means: if the network fails halfway through a 30-task sync, fix the cause, re-run, and only the un-created items get created.
+
+## Capabilities and hierarchy collapse
+
+Each adapter reports `capabilities()`. The sync layer reads `hierarchyDepth`:
+
+- **GitHub (depth 2):** Epic issue + flat task sub-issues. If the task tree authored depth >2, intermediate levels are flattened into siblings tagged `openspec:<feature>` and a one-line warning is printed.
+- **Linear (depth 2):** Project as epic, issues as tasks under the project. `parent` relation when supported by the workspace.
+- **GitLab (depth 2):** Parent issue + child issues linked via `relates_to` / `blocks`. Milestone serves as the epic container if `--milestone` is supplied.
+- **Jira (depth 3):** Epic → Story → optional Sub-task. Stories without sub-tasks just sit under the Epic via `Relates` link.
+- **Azure DevOps (depth 4):** Epic → Feature → User Story → Task with `System.LinkTypes.Hierarchy-Reverse` Parent links.
+
+## Field mapping per adapter
+
+| OpenSpec field | GitHub | Azure DevOps | Jira | Linear | GitLab |
+|---|---|---|---|---|---|
+| `task.title` | Issue title | `System.Title` | `summary` | `title` | `title` |
+| `task.body` | Issue body (markdown) | `System.Description` (HTML) | `description` (ADF) | `description` (markdown) | `description` (markdown) |
+| `feature.name` (tag) | label `openspec:<name>` | tag `openspec:<name>` | label `openspec-<name>` | label `openspec:<name>` | label `openspec:<name>` |
+| `task.depends_on` | task-list reference in body | `System.LinkTypes.Dependency` link | `Blocks` issue link | issue relation `blocks` | issue link `blocks` |
+| `task.iteration` | (ignored, depth=2) | `System.IterationPath` | sprint custom field | `cycleId` | `milestone` |
+| `task.assignee` | `--add-assignee` | `System.AssignedTo` | `assignee.accountId` | `assigneeId` | `assignee_ids` |
+| `task.effort_hours` | (ignored) | `Microsoft.VSTS.Scheduling.Effort` | story-points custom field | `estimate` | `weight` |
+
+The CLI handles the translation. Author tasks in the OpenSpec/CCPM dialect described in `conventions.md`.
+
+## After sync
+
+- Each item is now visible in the PM tool. The user can route stakeholders to those URLs for sign-off.
+- Progress narrative still lives locally in `openspec/changes/<feature>/updates/<task>/progress.md`. Use `openspecpm comment <task>` (Sprint 3) to broadcast a new update to the PM tool.
+- Route to `references/execute.md` when the user is ready to start building.