From fd9d5ff998d2b7d051427698acacfcd4ed1c8b74 Mon Sep 17 00:00:00 2001 From: Junichi Kato Date: Thu, 6 Aug 2026 00:49:36 +0900 Subject: [PATCH 1/2] docs: document the self-* scopes and the installer-distribution scope The scope guide described ten scopes while the framework ships fifteen. Split the catalogue into the eleven general scopes and a dedicated section for the four self-development scopes, and add the previously undocumented installer-distribution scope. The new section explains what each self-* scope is for, why none of them is auto-detected, and why self-fix and self-refactor keep Comprehensive verification at Minimal depth. Depth, test strategy, and EXECUTE counts are transcribed from the compiled scope grid; the prose is derived from the scope files under packages/framework/core/scopes/. Extend the routing and test-strategy-default tables to all fifteen scopes, point the skills guide at the section from the scope-runner discussion, and cross-link it from the harness-engineering naming note. --- docs/guide/05-scopes-and-depth.ja.md | 61 +++++++++++++++++++++++- docs/guide/05-scopes-and-depth.md | 61 +++++++++++++++++++++++- docs/guide/17-skills.ja.md | 2 + docs/guide/17-skills.md | 2 + docs/harness-engineering/04-scopes.ja.md | 2 +- docs/harness-engineering/04-scopes.md | 5 +- 6 files changed, 127 insertions(+), 6 deletions(-) diff --git a/docs/guide/05-scopes-and-depth.ja.md b/docs/guide/05-scopes-and-depth.ja.md index f5680a562b..852d0b087a 100644 --- a/docs/guide/05-scopes-and-depth.ja.md +++ b/docs/guide/05-scopes-and-depth.ja.md @@ -6,9 +6,9 @@ --- -## 10 のスコープ +## 11 の一般スコープ -すべてのワークフローは、名前付きの 10 のスコープのいずれかの下で実行されます。各スコープはステージ集合とデフォルトの深度レベルを定義します。 +すべてのワークフローは、いずれか1つの名前付きスコープの下で実行されます。フレームワークには 15 のスコープが同梱されています — 以下の 11 の一般スコープと、Amadeus 自体の開発にのみ使う 4 つの[自己開発スコープ](#自己開発スコープself-)です。各スコープはステージ集合とデフォルトの深度レベルを定義します。 ### enterprise @@ -93,6 +93,52 @@ 複数開発者向けの手動レシピとクレームのセマンティクスについては、[ワークショップモード](workshop-mode.ja.md) を参照してください。 +### installer-distribution + +**使う場面:** 既存のフレームワークリポジトリに、エンドユーザー向けインストーラーとパッケージ配布経路を追加するとき。 + +- **ステージ:** 32 のうち 25 +- **デフォルト深度:** Standard +- **スキップ:** Team Formation(体制は既に確定済み)、両方の Mockup ステージ(インストーラーは CLI 体験であり、その内容は User Stories と Functional Design が受け持つ)、および稼働中のサービスを前提とする4つの運用ステージ — Observability Setup、Incident Response、Performance Validation、Feedback Optimization +- **自動検出されない:** `keywords: []` のため、`/amadeus --scope installer-distribution` で明示的に選択します + +--- + +## 自己開発スコープ(`self-*`) + +4 つのスコープは、あなたのプロジェクトではなく **Amadeus フレームワーク自体**の開発のために存在します。Amadeus を使って自分のソフトウェアを構築している場合、これらを選択することはありません。ここに記載しているのは、`/amadeus --help` やコンパイル済みスコープテーブルに一般スコープと並んで現れるためです。 + +| スコープ | EXECUTE / 合計 | 深度 | テスト戦略 | 使う場面 | +|-------|-----------------|-------|---------------|----------| +| `self-feature` | 14 / 32 | Standard | Comprehensive | Amadeus の実質的な新しい挙動、または複数コンポーネントにまたがる変更 | +| `self-fix` | 7 / 32 | Minimal | Comprehensive | 既存の契約との整合を回復する、範囲の限定された是正 | +| `self-refactor` | 8 / 32 | Minimal | Comprehensive | 挙動を保ったまま Amadeus 内部の構造を変える変更 | +| `self-document` | 9 / 32 | Standard | Minimal | `README*.md` と `docs/` 配下の執筆・更新 | + +一般スコープとの違いは2点です。 + +**決して自動検出されません。** 4 つとも `keywords: []` を宣言しています。スコープ推論はアルファベット順で最初にキーワード一致したものを採るため、`docs` や `refactor` のような一般的な語を主張すると、以降のコールドスタートで別のスコープを恒久的に覆い隠してしまいます。選択は常に明示的です。 + +``` +/amadeus --scope self-feature +/amadeus --scope self-fix +``` + +**検証は深度に合わせて緩みません。** `self-fix` と `self-refactor` は Minimal 深度で実行されますが `testStrategy: Comprehensive` を維持します。成果物が軽量であることは、build-and-test 境界の軽量化を意味しません — 該当するテスト、生成されたハーネスの parity、`dist:check`、`promote:self:check` はいずれも実行されます。これは、深度から Minimal テストを継承する一般の `fix` / `refactor` スコープとの意図的な差異です。 + +### self-* スコープの使い分け + +すでに存在するものを起点に判断します。 + +- 意図した挙動や契約が**すでに存在**し、作業がそれとの整合を回復するもの — 不具合、ハーネス間の parity のずれ、生成物やドキュメントの drift、既存のプロジェクト方針の訂正 → `self-fix`。 +- 挙動は**保たれ**、内部構造だけが変わる → `self-refactor`。`self-fix` の経路に functional design を加え、保つべき挙動と目標とする構造を実装前に明示します。 +- **新しい**機能・仕様・アーキテクチャが関わる → `self-feature`。 +- 成果物が**文章**である → `self-document`。 + +`self-document` が reverse-engineering を第一級のステージとして残しているのは意図的です。ドキュメントは無音で drift します — 3 リリース前に改名されたフラグをページが説明していても、何も失敗しません。そのため、あらゆる記述は「かつてそう言われていた内容」ではなく、実装または git 履歴で実測した事実に遡れる必要があります。build-and-test ステージでは、ドキュメントのゲート(レガシー参照、言語ルール、EN/JA の対応)が実行されます。 + +`self-feature` は 2026 年 7 月に、完了した intent 群の実績に基づいて軽量化されました。`feasibility`、`approval-handoff`、`practices-discovery`、`nfr-requirements` が SKIP へ移りました — いずれも結果を変えた記録がなく、SKIP のたびに承認ゲートの待ち点が1つ減るためです。個別の intent で本当に必要な場合は、`/amadeus compose` でスキップされたステージを戻せます。 + --- ## スコープルーティングテーブル @@ -111,6 +157,11 @@ | `infra` | 13 / 32 | Standard | Standard | インフラ変更 | | `security-patch` | 10 / 32 | Minimal | Minimal | CVE 対応 | | `workshop` | 25 / 32 | Standard | **Minimal** | AI-DLC ワークショップまたはトレーニングセッション | +| `installer-distribution` | 25 / 32 | Standard | Standard | エンドユーザー向けインストーラーと配布経路の追加 | +| `self-feature` | 14 / 32 | Standard | **Comprehensive** | Amadeus 自己開発 — 新しい挙動 | +| `self-fix` | 7 / 32 | Minimal | **Comprehensive** | Amadeus 自己開発 — 範囲限定の是正 | +| `self-refactor` | 8 / 32 | Minimal | **Comprehensive** | Amadeus 自己開発 — 構造変更 | +| `self-document` | 9 / 32 | Standard | **Minimal** | Amadeus 自己開発 — ドキュメント | | (自動検出) | 可変 | 可変 | 可変 | AI が自由記述の intent から判定 | > **プロジェクトごとのデフォルトスコープ:** チームは `.claude/settings.json` に `AMADEUS_DEFAULT_SCOPE` を設定することで、プロジェクトのデフォルトスコープを事前設定できます — 全参加者がフラグを覚えずに `workshop` から開始すべきワークショップに便利です。[カスタマイズ § プロジェクトごとのデフォルトスコープ](13-customization.ja.md#per-project-default-scope) を参照してください。 @@ -310,6 +361,10 @@ You can request different depth or test strategy at any approval gate. | スコープ | 深度 | テスト戦略 | なぜ異なるのか? | |-------|-------|---------------|----------------| | `workshop` | Standard | **Minimal** | 学習のための完全な成果物、ただしペースを保つための高速な Nyquist テスト | +| `self-feature` | Standard | **Comprehensive** | フレームワークの変更は完全な検証境界を通す必要がある | +| `self-fix` | Minimal | **Comprehensive** | 成果物は軽量でも、ハーネス parity と配布チェックは実行する | +| `self-refactor` | Minimal | **Comprehensive** | 挙動が保たれることは仮定せず実証する必要がある | +| `self-document` | Standard | **Minimal** | 成果物は文章であり、検証はドキュメントのゲートが担う | その他のすべてのスコープは、テスト戦略を深度から継承します。`--test-strategy` でいつでも上書きできます。 @@ -356,6 +411,8 @@ You can request different depth or test strategy at any approval gate. | CVE またはセキュリティ脆弱性への対応 | `security-patch` | | コンプライアンスを必要とする規制対象機能 | `enterprise` | | AI-DLC ワークショップまたはトレーニングラボ | `workshop` | +| フレームワークリポジトリへのインストーラー追加 | `installer-distribution` | +| Amadeus フレームワーク自体の開発 | [`self-*` スコープ](#自己開発スコープself-) | 迷ったら `feature` から始めてください — 全 32 ステージを含み、各ステージの承認ゲートで個々のステージをスキップできます。 diff --git a/docs/guide/05-scopes-and-depth.md b/docs/guide/05-scopes-and-depth.md index 19c666d955..ebcf36d4d8 100644 --- a/docs/guide/05-scopes-and-depth.md +++ b/docs/guide/05-scopes-and-depth.md @@ -6,9 +6,9 @@ Scopes control **which stages execute**. Depth controls **how much detail** each --- -## The 10 Scopes +## The 11 General Scopes -Every workflow runs under one of 10 named scopes. Each scope defines a stage set and a default depth level. +Every workflow runs under one named scope. Fifteen ship with the framework: the 11 general scopes below, plus 4 [self-development scopes](#self-development-scopes-self-) used only for work on Amadeus itself. Each scope defines a stage set and a default depth level. ### enterprise @@ -93,6 +93,52 @@ Every workflow runs under one of 10 named scopes. Each scope defines a stage set See [Workshop Mode](workshop-mode.md) for the multi-developer manual recipe and claim semantics. +### installer-distribution + +**Use when:** Adding an end-user installer and a package-distribution path to an existing framework repository. + +- **Stages:** 25 of 32 +- **Default depth:** Standard +- **Skips:** Team Formation (the roster is already fixed), both Mockup stages (an installer is a CLI experience, captured in User Stories and Functional Design instead), and the four operation stages that presuppose a running service — Observability Setup, Incident Response, Performance Validation, Feedback Optimization +- **Not auto-detected:** ships `keywords: []`; reach it with `/amadeus --scope installer-distribution` + +--- + +## Self-development scopes (`self-*`) + +Four scopes exist for work on **the Amadeus framework itself**, not on your project. If you are using Amadeus to build your own software you will never select one — they are documented here because they appear in `/amadeus --help` and in the compiled scope table alongside the general scopes. + +| Scope | EXECUTE / Total | Depth | Test Strategy | Use when | +|-------|-----------------|-------|---------------|----------| +| `self-feature` | 14 / 32 | Standard | Comprehensive | Substantial new Amadeus behavior, or a change spanning components | +| `self-fix` | 7 / 32 | Minimal | Comprehensive | A bounded correction restoring alignment with an existing contract | +| `self-refactor` | 8 / 32 | Minimal | Comprehensive | A behavior-preserving structural change to Amadeus internals | +| `self-document` | 9 / 32 | Standard | Minimal | Writing or updating `README*.md` and everything under `docs/` | + +Two properties separate them from the general scopes. + +**They are never auto-detected.** All four declare `keywords: []`. Scope inference takes the first alphabetical keyword match, so claiming a generic term like `docs` or `refactor` would permanently shadow another scope on every future cold start. Selection is always explicit: + +``` +/amadeus --scope self-feature +/amadeus --scope self-fix +``` + +**Verification does not scale down with depth.** `self-fix` and `self-refactor` run at Minimal depth but keep `testStrategy: Comprehensive`, so lean artifacts never buy a lean build-and-test boundary — applicable tests, generated harness parity, `dist:check`, and `promote:self:check` all still run. This is the deliberate difference from the general `fix` and `refactor` scopes, which inherit Minimal testing from their depth. + +### Choosing between the self-* scopes + +Start from what already exists: + +- The intended behavior or contract **already exists**, and the work restores alignment with it — defects, cross-harness parity gaps, generated or documentation drift, corrections to an existing project policy → `self-fix`. +- Behavior is **preserved** and only the internal structure changes → `self-refactor`. It follows the `self-fix` route and adds functional design, so the preserved behavior and the target structure are explicit before implementation. +- A **new** capability, specification, or architecture is involved → `self-feature`. +- The deliverable is **prose** → `self-document`. + +`self-document` keeps reverse-engineering as a first-class stage on purpose. Documentation drifts silently — nothing fails when a page describes a flag that was renamed three releases ago — so every claim has to trace to a measured fact in the implementation or the git history rather than to what the code was once said to do. Its build-and-test stage still runs the documentation gates (legacy references, language rules, EN/JA pairing). + +`self-feature` was lightened in July 2026 from evidence across completed intents: `feasibility`, `approval-handoff`, `practices-discovery`, and `nfr-requirements` moved to SKIP because none had a recorded case of changing an outcome, and every SKIP removes an approval-gate wait point. Re-add a skipped stage for a single intent with `/amadeus compose` when it genuinely applies. + --- ## Scope Routing Table @@ -111,6 +157,11 @@ Authoritative data lives in the `.claude/scopes/amadeus-.md` files (scope | `infra` | 13 / 32 | Standard | Standard | Infrastructure change | | `security-patch` | 10 / 32 | Minimal | Minimal | CVE response | | `workshop` | 25 / 32 | Standard | **Minimal** | AI-DLC workshop or training session | +| `installer-distribution` | 25 / 32 | Standard | Standard | Add an end-user installer and distribution path | +| `self-feature` | 14 / 32 | Standard | **Comprehensive** | Amadeus self-development — new behavior | +| `self-fix` | 7 / 32 | Minimal | **Comprehensive** | Amadeus self-development — bounded correction | +| `self-refactor` | 8 / 32 | Minimal | **Comprehensive** | Amadeus self-development — structural change | +| `self-document` | 9 / 32 | Standard | **Minimal** | Amadeus self-development — documentation | | (auto-detect) | Varies | Varies | Varies | AI determines from freeform intent | > **Per-project default scope:** teams can pre-set the default scope for a project by setting `AMADEUS_DEFAULT_SCOPE` in `.claude/settings.json` — useful for workshops where every participant should start at `workshop` without remembering the flag. See [Customization § Per-Project Default Scope](13-customization.md#per-project-default-scope). @@ -310,6 +361,10 @@ Test strategy defaults to the **depth level** for most scopes — if your depth | Scope | Depth | Test Strategy | Why different? | |-------|-------|---------------|----------------| | `workshop` | Standard | **Minimal** | Full artifacts for learning, but fast Nyquist testing to keep pace | +| `self-feature` | Standard | **Comprehensive** | Framework changes must clear the full verification boundary | +| `self-fix` | Minimal | **Comprehensive** | Lean artifacts, but harness parity and distribution checks still run | +| `self-refactor` | Minimal | **Comprehensive** | Behavior preservation has to be demonstrated, not assumed | +| `self-document` | Standard | **Minimal** | Prose deliverable — the documentation gates carry the verification | All other scopes inherit their test strategy from depth. You can always override with `--test-strategy`. @@ -356,6 +411,8 @@ You can change the test strategy at three points: | CVE or security vulnerability response | `security-patch` | | Regulated feature requiring compliance | `enterprise` | | AI-DLC workshop or training lab | `workshop` | +| Adding an end-user installer to a framework repo | `installer-distribution` | +| Work on the Amadeus framework itself | a [`self-*` scope](#self-development-scopes-self-) | When in doubt, start with `feature` — it includes all 32 stages, and you can skip individual stages at their approval gates. diff --git a/docs/guide/17-skills.ja.md b/docs/guide/17-skills.ja.md index 76848b559d..f49b79cb45 100644 --- a/docs/guide/17-skills.ja.md +++ b/docs/guide/17-skills.ja.md @@ -130,6 +130,8 @@ basename だけを受け入れ、単一引数として渡します。basename /amadeus --scope poc ``` +4 つの `self-*` スコープも同じ方法 — `/amadeus --scope self-fix` — で到達します。これらにランナーを用意する予定はありません。あなたのプロジェクトではなく、Amadeus フレームワーク自体の開発に適用されるスコープだからです。それぞれの使い分けは[自己開発スコープ](05-scopes-and-depth.ja.md#自己開発スコープself-) を参照してください。 + ワークフローが一度開始すると、そのスコープは `amadeus-state.md` に固定されるため、 同じランナーを再実行すると、再スタートではなくワークフローを resume します。別の スコープで実行するには `/amadeus --scope ` を使ってください。 diff --git a/docs/guide/17-skills.md b/docs/guide/17-skills.md index 3ca9bb6347..b6e2e81f19 100644 --- a/docs/guide/17-skills.md +++ b/docs/guide/17-skills.md @@ -109,6 +109,8 @@ You can pass a description and flags straight through, exactly as you would to ` /amadeus --scope poc ``` +The four `self-*` scopes are reached the same way — `/amadeus --scope self-fix` — and no runner is planned for them: they apply to work on the Amadeus framework itself, not to your project. See [Self-development scopes](05-scopes-and-depth.md#self-development-scopes-self-) for when each one applies. + Once a workflow has started, its scope is fixed in `amadeus-state.md`, so re-running the same runner resumes the workflow rather than restarting it. To run under a different scope, use `/amadeus --scope `. --- diff --git a/docs/harness-engineering/04-scopes.ja.md b/docs/harness-engineering/04-scopes.ja.md index cc000344c8..ccb36878a4 100644 --- a/docs/harness-engineering/04-scopes.ja.md +++ b/docs/harness-engineering/04-scopes.ja.md @@ -39,7 +39,7 @@ Prose intent: why these stages, why skip those. | `keywords` | No | `/amadeus ` の自動検出のための自然言語トリガー。空リストはオプトアウト。 | | `description` | No | `/amadeus --help` に表示される1行説明。(SKILL.md のコンパイル済みスコープテーブルは Scope / Depth / TestStrategy / EXECUTE / Total のみを表示し、description は含めない。) | -プロジェクトローカルなスコープ名には、フレームワーク接頭辞を重ねず、その役割を表す名前を使います。Amadeus の自己開発では `self-feature`、`self-fix`、`self-refactor`、`self-document` を使用し、ファイル名は `amadeus-self-fix.md` のようにします。`amadeus-amadeus-*.md` という二重接頭辞は使用しません。 +プロジェクトローカルなスコープ名には、フレームワーク接頭辞を重ねず、その役割を表す名前を使います。Amadeus の自己開発では `self-feature`、`self-fix`、`self-refactor`、`self-document` を使用し、ファイル名は `amadeus-self-fix.md` のようにします。`amadeus-amadeus-*.md` という二重接頭辞は使用しません。これら4つのスコープがそれぞれ何のためのもので、どう使い分けるかは、ユーザーガイドの[自己開発スコープ](../guide/05-scopes-and-depth.ja.md#自己開発スコープself-) を参照してください。 **2. メンバーシップタグ — 各ステージの `scopes:` フロントマター。** ステージは、`packages/framework/core/amadeus-common/stages//.md` にある自身のフロントマターで、自分が実行されるスコープを列挙します。 diff --git a/docs/harness-engineering/04-scopes.md b/docs/harness-engineering/04-scopes.md index 586df76c34..8f3ad934d4 100644 --- a/docs/harness-engineering/04-scopes.md +++ b/docs/harness-engineering/04-scopes.md @@ -42,7 +42,10 @@ The frontmatter fields divide into one required field and three optional knobs: Project-local scope names should describe their role without repeating the framework prefix. Amadeus self-development therefore uses `self-feature`, `self-fix`, `self-refactor`, and `self-document`, producing filenames such as -`amadeus-self-fix.md`; do not use the doubled `amadeus-amadeus-*.md` form. +`amadeus-self-fix.md`; do not use the doubled `amadeus-amadeus-*.md` form. For +what each of those four scopes is for and when to select it, see +[Self-development scopes](../guide/05-scopes-and-depth.md#self-development-scopes-self-) +in the user guide. **2. The membership tag — each stage's `scopes:` frontmatter.** A stage names the scopes it runs under in its own frontmatter, in `packages/framework/core/amadeus-common/stages//.md`: From 261b50bda7f2d72240f88f1bc6a8a0d79d68f3ce Mon Sep 17 00:00:00 2001 From: Junichi Kato Date: Thu, 6 Aug 2026 00:53:24 +0900 Subject: [PATCH 2/2] docs: drop the stale scope count from the Japanese scopes chapter The Japanese chapter promised a catalogue of ten scopes while the framework ships fifteen, and its English counterpart was already count-free. Match the English wording so the sentence no longer has to be resynchronised whenever a scope is added. --- docs/harness-engineering/04-scopes.ja.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/harness-engineering/04-scopes.ja.md b/docs/harness-engineering/04-scopes.ja.md index ccb36878a4..dc51fb2d56 100644 --- a/docs/harness-engineering/04-scopes.ja.md +++ b/docs/harness-engineering/04-scopes.ja.md @@ -6,7 +6,7 @@ ハーネスエンジニアにとって、スコープは他のすべてのプリミティブと同じ方法で — ファイルとして — 記述される純粋なデータです。スコープは2つの半分から成ります。1つは `packages/framework/core/scopes/amadeus-.md` ファイル(そのアイデンティティ — 名前、深さ、キーワード、説明)、もう1つはステージごとのメンバーシップタグ(各ステージのフロントマターの `scopes:` リストが、そのステージが実行されるスコープを列挙する)です。スコープの追加やチューニングに TypeScript は不要です。この章ではワークフローを追っていきます。スコープが何で構成されるか、チームスコープをどう追加するか、既存のものをどうチューニングするか、そしてツールが何を検証してくれて何をあなたに委ねるか。 -ユースケースとユーザーが読むルーティングテーブルを含む10スコープの完全なカタログについては、ユーザーガイドの [Scopes, Depth, and Test Strategy](../guide/05-scopes-and-depth.ja.md) を参照してください。この章は同じデータを記述する(オーサリング)側です。 +ユースケースとユーザーが読むルーティングテーブルを含む全スコープの完全なカタログについては、ユーザーガイドの [Scopes, Depth, and Test Strategy](../guide/05-scopes-and-depth.ja.md) を参照してください。この章は同じデータを記述する(オーサリング)側です。 ---