最初の1件をCLIで通す

このQuick Startの完了条件

既存コードへ影響しない小さなdocs変更を、標準の13ステップで実行し、Pull Requestの確認とarchiveまで進めます。

1. 1
   実行前の検証を通過する

   doctorとrequest validateがexit 0。

2. 2
   実行結果に応じて次の操作を選ぶ

   pr-created、awaiting-human、failedを判別。

3. 3
   レビュー後にjobを閉じる

   merge後の状態がarchived。

前提条件

npm install -D @color4pen/specrunner
npx specrunner init
npx specrunner login
npx specrunner doctor

公開バージョンとパッケージ情報はnpmパッケージページで確認できます。

providerや環境変数を変更する場合は設定するを参照してください。

slugから雛形を作り、要件・スコープ外・受け入れ基準を記入します。この例ではdocsファイルを1つ追加します。

npx specrunner request new docs-quickstart

確認結果。 Created: specrunner/drafts/docs-quickstart/request.mdが表示されます。

# Quick Start用ドキュメントを追加する

## Meta

- **type**: chore
- **slug**: docs-quickstart
- **base-branch**: main
- **adr**: false

## 背景

SpecRunnerの実行経路を、小さく独立したドキュメント変更で確認する。

## 現状コードの前提

- なし

## 要件

1. docs/specrunner-quickstart-check.md を新規作成する
2. H1見出し「SpecRunner Quick Start Check」を記載する
3. このファイルがQuick Startで生成されたことを1文で説明する

## スコープ外

- src/ 配下の変更
- package設定と依存関係の変更

## 受け入れ基準

- [ ] docs/specrunner-quickstart-check.md が存在する
- [ ] 指定したH1見出しと説明文を含む
- [ ] typecheck && test がgreen

## architect 評価済みの設計判断

既存ファイルへの影響を避けるため、独立したdocsファイルとして追加する。

npx specrunner request validate docs-quickstart

確認結果。 errorがなくexit 0なら実行できます。失敗した場合はrequest.mdを修正し、同じコマンドを再実行します。

別の変更で試す場合はrequestの書き方を参照してください。

--jsonを付け、終了時のresult contractを保存します。

npx specrunner run docs-quickstart --json

{
  "schemaVersion": 1,
  "result": "pr-created",
  "slug": "docs-quickstart",
  "jobId": "<job-id>",
  "step": "pr-create",
  "prUrl": "https://github.com/.../pull/...",
  "reason": null
}

npx specrunner job show <job-id>
# awaiting-human の場合
npx specrunner job resume docs-quickstart

確認にはresult contractのjobId、resumeにはslugを使います。JobStatusの意味はJob状態にまとめています。

pr-createdならPRの差分とchecksを確認し、問題がなければmerge・archiveします。

# 同じslugの非終端jobがこの1件だけか確認
npx specrunner job ls --all --json
npx specrunner job show <job-id>
npx specrunner job archive --with-merge docs-quickstart
# cleanup後はslugで確認
npx specrunner job show docs-quickstart

完了条件。 最後のjob showで、表示されたJob IDがresult contractと一致し、Status: archivedならQuick Start完了です。

一覧に同じslugの非終端jobが複数ある、またはJob IDがresult contractと違う場合はarchiveしません。