Skip to content

Commit 29e7d4b

Browse files
byteland-appbyteland-app
committed
docs: refine spec-forge documentation
1 parent b357095 commit 29e7d4b

30 files changed

Lines changed: 2663 additions & 56 deletions

File tree

‎.github/workflows/release.yml‎

Lines changed: 19 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -190,23 +190,37 @@ jobs:
190190
echo "recovery_version: \"${version}\"" >> ../.cli-forge/release-receipt.yml
191191
if [[ -z "${{ inputs['recover-run-id'] }}" ]]; then
192192
if gh release view "v${version}" --json assets -q '.assets | length' 2>/dev/null | grep -qv '^0$'; then
193-
echo "::error::GitHub Release v${version} already has assets. Provide recover-run-id to reuse original artifacts." >&2
194-
exit 1
193+
echo "::notice::GitHub Release v${version} already has assets. Recovery will reuse them and only upload missing files."
195194
fi
196195
node --input-type=module -e "
197196
import { spawnSync } from 'node:child_process';
198197
import { buildAllPackageNames, readReleaseConfig } from './scripts/release/release-config.mjs';
199198
const v = '${version}';
200199
const names = buildAllPackageNames(readReleaseConfig(process.cwd()));
200+
const already = [];
201+
const missing = [];
201202
for (const name of names) {
202203
const r = spawnSync('npm', ['view', name + '@' + v, 'version'], { encoding: 'utf8', stdio: 'pipe' });
203204
if (r.status === 0) {
204-
console.error(name + '@' + v + ' already published. Provide recover-run-id to reuse original artifacts.');
205-
process.exit(1);
205+
if (r.stdout.trim() === v) {
206+
already.push(name + '@' + v);
207+
continue;
208+
}
206209
}
207210
const stderr = (r.stderr ?? '').toLowerCase();
208211
const notFound = stderr.includes('e404') || stderr.includes('etarget') || stderr.includes('not found');
209-
if (!notFound) throw new Error('npm view ' + name + '@' + v + ' failed: ' + (r.stderr ?? '').trim());
212+
if (r.status !== 0) {
213+
if (!notFound) throw new Error('npm view ' + name + '@' + v + ' failed: ' + (r.stderr ?? '').trim());
214+
missing.push(name + '@' + v);
215+
continue;
216+
}
217+
missing.push(name + '@' + v);
218+
}
219+
if (already.length > 0) {
220+
console.log('Recovery preflight: already published npm packages: ' + already.join(', '));
221+
}
222+
if (missing.length > 0) {
223+
console.log('Recovery preflight: missing npm packages: ' + missing.join(', '));
210224
}
211225
"
212226
fi

‎README.ja-JP.md‎

Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
# spec-forge
2+
3+
`spec-forge` は、曖昧な依頼を承認可能な実装仕様へ整理し、その後の実装結果まで YAML で追跡するワークフローです。agent による段階的な進行案内と、`.spec-forge/` に永続状態を保存する Rust CLI を組み合わせています。
4+
5+
言語版:
6+
7+
- [English](./README.md)
8+
- [简体中文](./README.zh-CN.md)
9+
- [日本語](./README.ja-JP.md)
10+
11+
## これは何か
12+
13+
- 依頼整理から実装報告までを扱う段階型ワークフロー
14+
- 承認、gate、focus、成果物を YAML に保存するワークスペースモデル
15+
- 状態変更の権威ランタイムである [`spec-forge-cli`](./spec-forge-cli/README.ja-JP.md)
16+
17+
## 使う場面
18+
19+
`spec-forge` は次のようなときに向いています。
20+
21+
- あいまいな要求を構造化されレビューしやすい spec にしたい
22+
- 計画状態をチャットではなく版管理可能なファイルに残したい
23+
- 複数段階の spec 作業を安全に中断・再開したい
24+
- ステージ進行の前に明示的な承認を入れたい
25+
26+
コマンドライン操作だけが必要なら [`CLI ドキュメント`](./spec-forge-cli/README.ja-JP.md) を参照してください。
27+
28+
## クイックスタート
29+
30+
### Agent 入口
31+
32+
ワークスペースの初期化や再開、最初の未完了ステージの特定、その先の継続を agent に任せたい場合は `$spec-forge` を使うよう依頼します。
33+
34+
依頼例:
35+
36+
- 「`$spec-forge` を使って、この要求を承認可能な spec にしてください」
37+
- 「このリポジトリで `$spec-forge` を使い、`checkout-redesign` を続けてください」
38+
- 「`$spec-forge` を使って次の未完了ステージを見つけて進めてください」
39+
40+
### CLI 入口
41+
42+
以下の例はすべてリポジトリルートから実行します。
43+
44+
```bash
45+
spec-forge-cli init --target . --spec-id demo --request-title "Demo Spec"
46+
spec-forge-cli resolve --target . --spec-id demo --skill spec-forge --stage router --write
47+
spec-forge-cli ux validate --target .
48+
```
49+
50+
> [!NOTE]
51+
> agent スキルは対話を案内しますが、永続化されたワークフロー状態を変更する権威は `spec-forge-cli` です。
52+
53+
## ステージマップ
54+
55+
| ステージ | 目的 |
56+
| ------------------- | --------------------------------------------------- |
57+
| `P0 / Intake` | 依頼、関係者、スコープ、制約を整理します。 |
58+
| `P1 / Architecture` | 全体方針と journey / component index を固めます。 |
59+
| `P2 / Journeys` | 対象 journey をレビューしやすい単位で詳細化します。 |
60+
| `P3 / Components` | 対象 component を実装向け契約へ落とし込みます。 |
61+
| `P4 / Readiness` | 承認済み内容を最終的な実装仕様へ統合します。 |
62+
| `P5 / Implement` | 実装状況、検証、ブロッカー、完了記録を残します。 |
63+
64+
## ワークスペースモデル
65+
66+
永続状態は `.spec-forge/` に保存されます。
67+
68+
```text
69+
.spec-forge/
70+
├── registry.yaml
71+
└── specs/
72+
└── <spec-id>/
73+
├── pipeline-state.yaml
74+
├── handoff.yaml
75+
├── framing/
76+
├── architecture/
77+
├── journeys/
78+
├── components/
79+
├── synthesis/
80+
└── gates/
81+
```
82+
83+
主な成果物:
84+
85+
- `pipeline-state.yaml` はステージ、focus、UX handoff 状態を追跡します。
86+
- `synthesis/implementation-spec.yaml` は実装向けの最終契約です。
87+
- `synthesis/implementation-report.yaml` は実装状況と検証結果を記録します。
88+
- `gates/<stage>.yaml` は各ステージの gate 判定結果を記録します。
89+
90+
## リポジトリ構成
91+
92+
以下のパスはすべてリポジトリルート基準です。
93+
94+
```text
95+
README*.md プロジェクト入口ドキュメント
96+
AGENTS.md このリポジトリ向け agent 指示
97+
spec-forge/ ルーター技能と共有 UX 契約/資産
98+
spec-forge-intake/ P0 ステージ技能
99+
spec-forge-architecture/ P1 ステージ技能
100+
spec-forge-journeys/ P2 ステージ技能
101+
spec-forge-components/ P3 ステージ技能
102+
spec-forge-readiness/ P4 ステージ技能
103+
spec-forge-implement/ P5 ステージ技能
104+
spec-forge-cli/ Rust CLI、テスト、npm wrapper、リリーススクリプト
105+
specs/001-spec-execution-stage/ AGENTS.md が参照するリポジトリ文脈
106+
.spec-forge/specs/001-spec-execution-stage/
107+
このリポジトリ内の永続ワークフロー状態サンプル
108+
```
109+
110+
## CLI 入口
111+
112+
[`CLI ドキュメント`](./spec-forge-cli/README.ja-JP.md) には次がまとまっています。
113+
114+
- インストールと対応プラットフォーム
115+
- クイックスタートのコマンド列
116+
- コマンド参照と構造化ヘルプ
117+
- 出力形式と検証手順
118+
- リリース事前演習と CI 復旧入力
119+
120+
## ドキュメントマップ
121+
122+
| 範囲 | ドキュメント | 用途 |
123+
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
124+
| ワークフロー入口 | [`spec-forge` router ガイド](./spec-forge/README.ja-JP.md)、[`spec-forge/SKILL.md`](./spec-forge/SKILL.md) | ワークフローの開始や再開、router の実行契約の確認。 |
125+
| ステージガイド | [`spec-forge-intake`](./spec-forge-intake/README.ja-JP.md)、[`spec-forge-architecture`](./spec-forge-architecture/README.ja-JP.md)、[`spec-forge-journeys`](./spec-forge-journeys/README.ja-JP.md)、[`spec-forge-components`](./spec-forge-components/README.ja-JP.md)、[`spec-forge-readiness`](./spec-forge-readiness/README.ja-JP.md)、[`spec-forge-implement`](./spec-forge-implement/README.ja-JP.md) | P0-P5 各ステージを使う場面と Agent から聞かれる内容の確認。 |
126+
| ステージ契約 | [`intake`](./spec-forge-intake/SKILL.md)、[`architecture`](./spec-forge-architecture/SKILL.md)、[`journeys`](./spec-forge-journeys/SKILL.md)、[`components`](./spec-forge-components/SKILL.md)、[`readiness`](./spec-forge-readiness/SKILL.md)、[`implement`](./spec-forge-implement/SKILL.md) | 各ステージの実行ルール、gate、必須入力、出力の確認。 |
127+
| CLI パッケージ | [`CLI ドキュメント`](./spec-forge-cli/README.ja-JP.md)、[`npm wrapper`](./spec-forge-cli/npm/main/README.md)、[`リリース記録`](./spec-forge-cli/CHANGELOG.md) | CLI の導入、操作、パッケージング、配布内容の確認。 |
128+
| CLI 契約 | [`spec-forge-cli/SKILL.md`](./spec-forge-cli/SKILL.md) | CLI コマンド面と構造化出力契約の確認。 |
129+
| リポジトリ文脈 | [`spec execution plan`](./specs/001-spec-execution-stage/plan.md)、[`AGENTS.md`](./AGENTS.md) | リポジトリ単位の文脈と agent 指示の確認。 |

‎README.md‎

Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
# spec-forge
2+
3+
`spec-forge` is a YAML-first workflow for turning a rough request into an approved implementation spec and an auditable implementation report. It combines agent-guided stage progression with a Rust CLI that persists durable state under `.spec-forge/`.
4+
5+
Language versions:
6+
7+
- [English](./README.md)
8+
- [简体中文](./README.zh-CN.md)
9+
- [日本語](./README.ja-JP.md)
10+
11+
## What It Is
12+
13+
- A staged workflow that moves from request framing to implementation reporting.
14+
- A persistent workspace model that keeps approvals, gates, focus, and artifacts in YAML.
15+
- A CLI runtime, [`spec-forge-cli`](./spec-forge-cli/README.md), that is the source of truth for workspace mutations.
16+
17+
## When To Use It
18+
19+
Use `spec-forge` when you need to:
20+
21+
- turn a vague feature request into a structured, reviewable spec
22+
- persist planning state in versionable files instead of chat memory
23+
- pause and resume multi-stage spec work safely
24+
- require explicit approvals before stage advancement
25+
26+
If you only need the command-line surface, start with [`spec-forge-cli/README.md`](./spec-forge-cli/README.md).
27+
28+
## Quick Start
29+
30+
### Agent entry
31+
32+
Ask your agent to use `$spec-forge` when you want it to initialize or resume a workspace, resolve the earliest incomplete stage, and continue from there.
33+
34+
Example prompts:
35+
36+
- "Use `$spec-forge` to turn this request into an approved spec."
37+
- "Use `$spec-forge` in this repo and continue `checkout-redesign`."
38+
- "Use `$spec-forge` to find the next incomplete stage and keep going."
39+
40+
### CLI entry
41+
42+
Run these examples from the repository root.
43+
44+
```bash
45+
spec-forge-cli init --target . --spec-id demo --request-title "Demo Spec"
46+
spec-forge-cli resolve --target . --spec-id demo --skill spec-forge --stage router --write
47+
spec-forge-cli ux validate --target .
48+
```
49+
50+
> [!NOTE]
51+
> Agent skills guide the conversation, but `spec-forge-cli` is the authoritative runtime for changing persisted workflow state.
52+
53+
## Stage Map
54+
55+
| Stage | Purpose |
56+
| ------------------- | ------------------------------------------------------------------- |
57+
| `P0 / Intake` | Frame the request, stakeholders, scope, and constraints. |
58+
| `P1 / Architecture` | Lock the solution outline plus the journey and component indexes. |
59+
| `P2 / Journeys` | Refine in-scope journeys in reviewable batches. |
60+
| `P3 / Components` | Refine in-scope components into implementation-facing contracts. |
61+
| `P4 / Readiness` | Consolidate approved work into the final implementation spec. |
62+
| `P5 / Implement` | Record delivery status, validations, blockers, and closure details. |
63+
64+
## Workspace Model
65+
66+
Persistent workflow state lives under `.spec-forge/`:
67+
68+
```text
69+
.spec-forge/
70+
├── registry.yaml
71+
└── specs/
72+
└── <spec-id>/
73+
├── pipeline-state.yaml
74+
├── handoff.yaml
75+
├── framing/
76+
├── architecture/
77+
├── journeys/
78+
├── components/
79+
├── synthesis/
80+
└── gates/
81+
```
82+
83+
Key artifacts:
84+
85+
- `pipeline-state.yaml` tracks stage, focus, and UX handoff state.
86+
- `synthesis/implementation-spec.yaml` is the implementation-ready contract.
87+
- `synthesis/implementation-report.yaml` records delivery status and validations.
88+
- `gates/<stage>.yaml` records gate evaluation output per stage.
89+
90+
## Repo Layout
91+
92+
Paths below are relative to the repository root.
93+
94+
```text
95+
README*.md Project entry docs
96+
AGENTS.md Agent instructions for this repo
97+
spec-forge/ Router skill and shared UX contracts/assets
98+
spec-forge-intake/ P0 stage skill
99+
spec-forge-architecture/ P1 stage skill
100+
spec-forge-journeys/ P2 stage skill
101+
spec-forge-components/ P3 stage skill
102+
spec-forge-readiness/ P4 stage skill
103+
spec-forge-implement/ P5 stage skill
104+
spec-forge-cli/ Rust CLI, tests, npm wrapper, release scripts
105+
specs/001-spec-execution-stage/ Repo-level context referenced by AGENTS.md
106+
.spec-forge/specs/001-spec-execution-stage/
107+
Example persisted workflow state for this repo
108+
```
109+
110+
## CLI Entry Point
111+
112+
Use [`spec-forge-cli/README.md`](./spec-forge-cli/README.md) for:
113+
114+
- installation and platform support
115+
- quick-start command sequences
116+
- command reference and structured help
117+
- output formats and validation commands
118+
- release rehearsal and CI recovery workflow inputs
119+
120+
## Documentation Map
121+
122+
| Area | Documents | Use for |
123+
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
124+
| Workflow entry | [`spec-forge` router guide](./spec-forge/README.md), [`spec-forge/SKILL.md`](./spec-forge/SKILL.md) | Start or resume the workflow and inspect the executable router contract. |
125+
| Stage guides | [`spec-forge-intake`](./spec-forge-intake/README.md), [`spec-forge-architecture`](./spec-forge-architecture/README.md), [`spec-forge-journeys`](./spec-forge-journeys/README.md), [`spec-forge-components`](./spec-forge-components/README.md), [`spec-forge-readiness`](./spec-forge-readiness/README.md), [`spec-forge-implement`](./spec-forge-implement/README.md) | Understand when to use each P0-P5 stage and what the Agent will ask. |
126+
| Stage contracts | [`intake`](./spec-forge-intake/SKILL.md), [`architecture`](./spec-forge-architecture/SKILL.md), [`journeys`](./spec-forge-journeys/SKILL.md), [`components`](./spec-forge-components/SKILL.md), [`readiness`](./spec-forge-readiness/SKILL.md), [`implement`](./spec-forge-implement/SKILL.md) | Review the executable rules, gates, required inputs, and outputs for each stage. |
127+
| CLI package | [`spec-forge-cli`](./spec-forge-cli/README.md), [`npm wrapper`](./spec-forge-cli/npm/main/README.md), [`release record`](./spec-forge-cli/CHANGELOG.md) | Install, operate, package, or audit the CLI distribution. |
128+
| CLI contract | [`spec-forge-cli/SKILL.md`](./spec-forge-cli/SKILL.md) | Inspect the CLI command surface and structured output contract. |
129+
| Repo context | [`spec execution plan`](./specs/001-spec-execution-stage/plan.md), [`AGENTS.md`](./AGENTS.md) | Read repository-level context and agent instructions. |

0 commit comments

Comments
 (0)