intent-planner 0.13.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yoshishige Tsuji
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -0,0 +1,225 @@
+# intent-planner
+
+![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg) ![node](https://img.shields.io/badge/node-%3E%3D18.17-brightgreen)
+
+README: [日本語](README.md) | [English](README.en.md)
+
+You ask an AI to "just handle this nicely," and each individual change looks fine — yet the whole thing slowly heads somewhere other than what you had in mind. Sound familiar?
+
+intent-planner is a tool for putting "what you want to do" and "what you can't compromise on" into words together with the AI, **before** you ask it to work. Aligning the direction up front keeps things from drifting bit by bit along the way.
+
+What you do is simple: you take the fuzzy idea in your head and organize it by answering the AI's questions. No special knowledge required.
+
+Installing it only adds a few commands and one folder, `.intent/`. **It never rewrites your files or code** (all it writes is notes inside `.intent/`).
+
+> 📌 In more technical terms: intent-planner is a **"Pre-spec Steering Layer" for AI coding agents (Claude Code / Codex)**. It slots in one stage before you write the spec, keeping cross-cutting intent and design direction in effect as steering context throughout implementation. The detailed engineer-facing story is in the [later half](#sec-prespec).
+
+---
+
+## Which one is you?
+
+There are roughly three ways to use it. They get more technical from top to bottom, so read from whichever is closest to you.
+
+| If you're… | How you use it | Section |
+|---|---|---|
+| 📝 **Not writing code** (planning, research, document-making) | As a tool to organize your thinking and produce a readable deliverable (article outline, manual, research notes, etc.) | [① If you don't write code](#sec-no-code) |
+| 💻 **Asking the AI to implement** (everyday development) | Insert one stage **before** writing the spec, to organize intent before handing off | [② Asking the AI to implement (Pre-spec Steering Layer)](#sec-prespec) |
+| 🔁 **Wanting it fully automated** | Let an outer loop (`/loop`, etc.) **self-drive** the intent → implement → reflect cycle | [③ Run the whole thing automatically (full IDD)](#sec-full-idd) |
+
+> The detailed feature usage (modes, command list, enforcement, drift-watch, etc.) is collected in [docs/guide.en.md](docs/guide.en.md). This README focuses on "how to start in your situation."
+
+---
+
+## To begin: the whole picture in 3 minutes
+
+intent-planner is one round-trip loop: organize the intent **before** asking the AI to implement, and write the learnings back into the documents **after**.
+
+```
+1. Organize intent        2. Hand off        3. Implement      4. Write back
+discover → compass        export             (AI implements)    writeback
+  → packets                                                     → improve
+        └────── when in doubt, status (where you are + one next move) ──────┘
+```
+
+Each step's deliverable is Markdown under the `.intent/` folder. Review it before moving on. **When in doubt, `/intent-status`** tells you where you are and recommends exactly one "next move".
+
+### Requirements
+
+- **Claude Code** / **Codex** / **Gemini CLI** (selected via `--agent`)
+- **Node.js** (only to run the installer; zero runtime dependencies)
+- [cc-sdd](https://github.com/gotalab/cc-sdd) or [OpenSpec](https://github.com/Fission-AI/OpenSpec) (optional; if you use them as the handoff target)
+
+### Install
+
+```bash
+# At the root of your project (defaults to Claude Code)
+npx intent-planner
+
+# If you use Codex
+npx intent-planner --agent codex
+
+# If you use Gemini CLI
+npx intent-planner --agent gemini
+
+# To check first what will happen
+npx intent-planner --dry-run
+```
+
+On install, a "thin entry that teaches how to use it" (`CLAUDE.md` for Claude Code, `AGENTS.md` for Codex, `GEMINI.md` for Gemini CLI) and a scaffold `.intent/` folder are placed for the AI you use. An existing `CLAUDE.md` / `AGENTS.md` / `GEMINI.md` is respected and never overwritten. For detailed options, see [the installation section of docs/guide.en.md](docs/guide.en.md#installation-options).
+
+**For engineers who write code**: after working out the intent, the recommended path is to bridge into [cc-sdd](https://github.com/gotalab/cc-sdd) or [OpenSpec](https://github.com/Fission-AI/OpenSpec) drafts via `/intent-export-cc-sdd` and proceed with the spec-driven implementation flow (intent is the upstream layer; cc-sdd / OpenSpec is downstream).
+
+---
+
+<a id="sec-no-code"></a>
+
+## ① If you don't write code
+
+intent-planner was originally for people building programs with AI, but you can also use it as a tool to **organize the ideas in your head into a "readable deliverable"**. Outlining an article, summarizing what you researched, drafting a proposal — that's the path here.
+
+It's easy to use. When you run `/intent-discover`, the AI asks you "what do you want to do?", and you just answer. The AI sees "this is document-making" and switches to a way of working that pulls your writing together (`non-code` mode).
+
+```
+/intent-discover    ← organize what you want to do / think through (the AI asks you questions)
+  → /intent-compass ← decide what you "can't compromise on"
+  → /intent-to-spec ← pull it into a readable form (article outline, manual, research notes, etc.)
+```
+
+- The final `/intent-to-spec` pulls what you organized into one readable document. Parts without a clear basis get an "inferred" mark, so you can tell whether the AI has padded the story on its own.
+- The finished document goes into the `.intent/nl-spec/` folder.
+
+> If you don't write code, this is enough. The sections below are for people building programs, so feel free to skip them.
+
+---
+
+<a id="sec-prespec"></a>
+
+## ② Asking the AI to implement (Pre-spec Steering Layer)
+
+From here on it's for engineers. The most basic use of intent-planner is to insert just one stage **before** writing the spec, organizing intent before handing off to implementation. The organized intent flows straight into the spec-driven flow of [cc-sdd](https://github.com/gotalab/cc-sdd) or [OpenSpec](https://github.com/Fission-AI/OpenSpec).
+
+As the name "Pre-spec" and "Steering" suggests, the criteria you set here keep steering the AI throughout implementation.
+
+### How to proceed
+
+Run these in order, reviewing each step's deliverable.
+
+```
+/intent-discover   →  /intent-compass  →  /intent-packets  →  /intent-export-cc-sdd
+(organize the picture)  (criteria to uphold)  (decompose into units)  (hand off to the tool)
+```
+
+1. **`/intent-discover`** — the AI asks questions about your problem or idea and builds the overall picture of the intent.
+2. **`/intent-compass`** — builds the decision criteria: "the state to aim for", "directions not to take", "invariants that must not break". This becomes the steering handed to the AI on every implementation run.
+3. **`/intent-packets`** — splits into work units (packets) that can be handed to implementation. It recommends one unit to start with, with a reason.
+4. **`/intent-export-cc-sdd`** (or `/intent-export-openspec`) — converts the selected work unit into a draft for the implementation tool.
+
+After that you run the cc-sdd / OpenSpec spec flow (requirements → design → tasks → implementation). intent-planner produces only the draft; the spec body is generated by the implementation tool, and you review it at each phase.
+
+### What's good about this (Before / After)
+
+An example of how a vague one-line request gets concrete when run through intent-planner (subject: a login feature).
+
+**Before** — the request to the AI is just this:
+
+```
+Just build the login feature nicely
+```
+
+The interpretation of "nicely" is left to the AI, which tends to fall into stopgaps — growing its own password auth, going down an implementation that doesn't fit the existing auth foundation.
+
+**After** — running discover → compass → packets turns the same request into this:
+
+- **Goal (with measurable criteria)**: a first-time user can complete login within 2 minutes (measured from start to dashboard display)
+- **Invariant (to uphold)**: don't break compatibility with the existing OAuth providers (Google / GitHub)
+- **Direction not to take**: don't add your own password auth
+- **Work units**:
+  1. **P1: OAuth callback E2E** — thread the thinnest path through first
+  2. **P2: error states and retry UI**
+  3. **P3: audit log**
+
+The first recommendation is P1. Threading the thinnest path first lets you clear the biggest uncertainty (redirect config, session management) at the start.
+
+Because this goal / invariant / direction-not-to-take keeps being handed to the AI on every run from P2 onward, the criteria "don't grow your own auth" and "don't break the existing providers" keep working.
+
+### After implementation (keep growing it)
+
+So it isn't "build once and done", write the learnings from implementation back into the intent documents.
+
+- **`/intent-writeback`** — records what you learned during implementation (newly decided things, invariant violations, implicit behavior) and reflects only what you approve into the documents.
+- **`/intent-improve`** — at a milestone after several units, detects and fixes the gaps between documents and implementation in bulk.
+
+With this, `.intent/` becomes a living decision criterion that stays in sync with implementation reality.
+
+---
+
+<a id="sec-full-idd"></a>
+
+## ③ Run the whole thing automatically (full IDD)
+
+In ②, a human looked at `/intent-status` and advanced each next move by hand. Instead, delegating the driving to an outer loop like `/loop` lets you **self-drive the whole intent → implementation → write-back cycle**. This is using intent-planner to run a full round as **Intent Driven Development (IDD)**.
+
+intent-planner itself records "which stage it's at (state)", but embeds no mechanism (a state machine) to advance that state automatically. That's why the driving can be pushed outside.
+
+```
+/loop /intent-status
+  → the outer loop picks up the "next move" status emits,
+    advances export of the next work unit → implementation → writeback,
+    and returns to status — repeating this
+```
+
+The only difference from ② is **who holds the driving**. Either way, what decides the next thing to build is the Intent (the organized intent, and the "next move" status emits).
+
+> ### ⚠️ The cost of self-driving (make sure you understand it)
+>
+> The commands that rewrite documents (discover / compass / packets / writeback / improve / export) **intentionally assume human approval** — a brake against unsupervised development (vibe coding). Skipping approval with `/loop` trades speed for losing the following:
+>
+> - **The chance to notice drift** — fewer chances to notice "this drifts from the intent" at each stage
+> - **Protection of the documents** — a wrong learning could be reflected into the intent documents as-is
+> - **Review of heavy branches** — filling in questions a human should settle, without approval, could fix a guess as a settled fact
+>
+> **The recommendation is hybrid.** Delegate the inner "implement → test → fix" to `/loop` to spin fast, and have a human cut in at the seams (compass confirmation, packet decomposition, writeback approval, settling heavy questions). The read-only commands (status / validate / overview) need no approval, so they keep emitting decision material safely inside `/loop`. Rather than "running everything approval-less", "concentrating approval on the one point that matters" is the way to balance lightness and safety.
+>
+> The self-driving mechanism and caveats are in [the "running it on a loop" section of docs/guide.en.md](docs/guide.en.md#notes-when-running-it-on-a-loop-loop); the theoretical background is in [the "state, yes — state machine, no" section of docs/theory.md](docs/theory.md).
+
+---
+
+## When to use it
+
+You can also enter from a concrete situation.
+
+| Situation | What intent-planner does | How |
+|---|---|---|
+| Pull together documents, research, planning (no code) | Organize the intent and generate a readable deliverable directly | [①](#sec-no-code) |
+| Start a new product or feature AI-first | Verbalize the intent and criteria before implementation, so steering works from the first line | [②](#sec-prespec) |
+| Build a PoC or personal project solo | Opt in at the entry to the designer-role questions (measurable success criteria, walking skeleton, hypothesis and falsification criteria) | [②](#sec-prespec) |
+| Ask for a large refactor | Build the criteria first that prevent changes that "work correctly but drift from the design intent" | [②](#sec-prespec) |
+| Legacy code whose specs are unknown | Reverse-engineer the intent from observable behavior and document it | [②](#sec-prespec) |
+| Add features to a running system | Decompose into addition units that account for the impact on what exists | [②](#sec-prespec) |
+| Self-drive from planning through implementation and write-back | Delegate the driving to an outer loop; the human approves only the one point that matters | [③](#sec-full-idd) |
+
+---
+
+## Safe to adopt
+
+- **It does not change your application code.** All it writes is Markdown under `.intent/` (writeback / improve reflect only what you approve).
+- **It does not overwrite existing files** (except when you pass `--force`). You can check first with `--dry-run`.
+- **The check layers (enforcement / drift-watch) default to off**, and nothing changes unless you configure them. A git hook is placed only when you explicitly pass `--enforce`.
+- **Zero runtime dependencies** (Node standard modules only). No resident process, no sending anything to an external service.
+
+---
+
+## Want to know more
+
+- **How each feature works** — modes, command-by-command, file layout, enforcement, drift-watch, coined-term management, constraint starters, etc. → [docs/guide.en.md](docs/guide.en.md)
+- **Why this procedure** — its correspondence to requirements engineering and software architecture research, with references → [docs/theory.md](docs/theory.md) (Japanese)
+
+It's designed so that, even without knowing the theory, following the flow and answering the questions fills in the deliverables you need. The docs are for reference when you want one more level of detail.
+
+---
+
+## License
+
+MIT © Yoshishige Tsuji
+
+This project's development uses tooling derived from [cc-sdd](https://github.com/gotalab/cc-sdd) (MIT, © 2025 gotalab). The distributed artifacts (the npm package and this repository's `templates/`, etc.) contain no cc-sdd-derived files.

package/README.md

@@ -0,0 +1,225 @@
+# intent-planner
+
+![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg) ![node](https://img.shields.io/badge/node-%3E%3D18.17-brightgreen)
+
+README: [日本語](README.md) | [English](README.en.md)
+
+AI に「いい感じにやっておいて」とお願いすると、ひとつひとつは悪くないのに、全体としてだんだん思っていたのと違う方向へ進んでいく——そんな経験はないでしょうか。
+
+intent-planner は、AI に作業を頼む**前に**、「何をしたいのか」「これだけは外したくない」を AI といっしょに言葉にしておくための道具です。先に向きを合わせておくと、途中で少しずつズレていくのを防げます。
+
+やることはシンプルで、頭の中にあるぼんやりした考えを、AI が質問してくれるのに答えながら整理していくだけ。むずかしい知識はいりません。
+
+導入しても増えるのは、いくつかのコマンドと `.intent/` というフォルダ1つだけ。**あなたのファイルやコードを勝手に書き換えることはありません**（書き込むのは `.intent/` の中のメモだけです）。
+
+> 📌 もう少し技術的に言うと: intent-planner は **AI コーディングエージェント（Claude Code / Codex）向けの "Pre-spec Steering Layer"** です。spec（仕様）を書く一段手前に挟んで、横断的な意図と設計方針を steering context として実装中ずっと効かせます。エンジニア向けの詳しい話は[後半](#sec-prespec)から。
+
+---
+
+## 自分はどの使い方かな？
+
+使い方は大きく3通り。上から順にだんだん技術寄りになっていくので、自分に近いところから読んでください。
+
+| こんな人 | 使い方 | 読む章 |
+|---|---|---|
+| 📝 **コードは書かない**（企画・調査・文書づくり） | 考えを整理して、読める成果物（記事の構成案・手順書・調査メモなど）を作る道具として | [① コードを書かない人へ](#sec-no-code) |
+| 💻 **AI に実装を頼む**（ふだんの開発） | 仕様を書く**手前**に1段はさんで、意図を整えてから実装に渡す | [② AI に実装を頼むとき（Pre-spec Steering Layer）](#sec-prespec) |
+| 🔁 **まるごと自動で回したい** | 意図→実装→ふりかえりのサイクルを、外側のループ（`/loop` など）で**自走**させる | [③ まるごと自動で回す（full IDD）](#sec-full-idd) |
+
+> 各機能の細かい使い方（モード・コマンド一覧・enforcement・drift-watch など）は [docs/guide.md](docs/guide.md) にまとめてあります。この README は「自分の状況でどう始めるか」に絞っています。
+
+---
+
+## はじめに：3分でわかる全体像
+
+intent-planner は、AI に実装を頼む**前**に意図を整理し、実装の**あと**に学びを文書へ戻す、ひとめぐりのループです。
+
+```
+①意図を整理する          ②実装に渡す        ③実装する         ④学びを戻す
+discover → compass        export            （AI が実装）       writeback
+  → packets                                                    → improve
+        └─────────── 迷ったら status（現在地と次の一手を1つ教える）───────────┘
+```
+
+各ステップの成果物は `.intent/` フォルダの中の Markdown です。レビューしてから次へ進めます。**迷ったら `/intent-status`** が、いまどこにいて次に何をすればいいかを1つだけ教えてくれます。
+
+### 必要なもの
+
+- **Claude Code** / **Codex** / **Gemini CLI**（`--agent` で選択）
+- **Node.js**（インストーラの実行に使うだけ。動作時の依存はゼロ）
+- [cc-sdd](https://github.com/gotalab/cc-sdd) や [OpenSpec](https://github.com/Fission-AI/OpenSpec)（任意。実装に渡す先として使う場合）
+
+### インストール
+
+```bash
+# プロジェクトのルートで（既定は Claude Code）
+npx intent-planner
+
+# Codex を使う場合
+npx intent-planner --agent codex
+
+# Gemini CLI を使う場合
+npx intent-planner --agent gemini
+
+# 何が起きるか先に確認したいとき
+npx intent-planner --dry-run
+```
+
+導入すると、使う AI に合わせて「使い方を教える薄い入口」（Claude Code なら `CLAUDE.md`、Codex なら `AGENTS.md`、Gemini CLI なら `GEMINI.md`）と、雛形の `.intent/` フォルダが置かれます。既存の `CLAUDE.md` / `AGENTS.md` / `GEMINI.md` があれば上書きせず尊重します。詳しいオプションは [docs/guide.md のインストール節](docs/guide.md#インストールのオプション)を参照してください。
+
+**コードを書くエンジニアの方へ**: intent で意図を詰めたあとは、`/intent-export-cc-sdd` で [cc-sdd](https://github.com/gotalab/cc-sdd) または [OpenSpec](https://github.com/Fission-AI/OpenSpec) の下書きへ橋渡しし、spec 駆動の実装フローへ進むのが推奨です（intent は手前のレイヤー、cc-sdd / OpenSpec が下流）。
+
+---
+
+<a id="sec-no-code"></a>
+
+## ① コードを書かない人へ
+
+intent-planner はもともと AI でプログラムを作る人向けですが、**頭の中の考えを整理して「読める成果物」にまとめる**道具としても使えます。記事の構成を練る、調べたことをまとめる、企画書をつくる——そんなときの道筋です。
+
+使い方はかんたん。`/intent-discover` を実行すると、AI が「何をしたいんですか？」と質問してくれるので、それに答えていくだけ。AI のほうで「これは文書づくりですね」と見て、文章をまとめる進め方（`non-code` モード）に切り替えてくれます。
+
+```
+/intent-discover    ← したいこと・考えたいことを整理（AI が質問してくれる）
+  → /intent-compass ← 「これは外したくない」という方針を決める
+  → /intent-to-spec ← 記事の構成案・手順書・調査メモなど、読める形にまとめる
+```
+
+- 最後の `/intent-to-spec` で、整理した内容を1本の読める文書にまとめてくれます。はっきりした根拠のない部分には「推測」の印が付くので、AI が勝手に話を盛っていないか見分けられます。
+- できあがった文書は `.intent/nl-spec/` というフォルダに入ります。
+
+> コードを書かない人は、ここまでで十分です。この先の章はプログラムを作る人向けなので、読み飛ばして大丈夫です。
+
+---
+
+<a id="sec-prespec"></a>
+
+## ② AI に実装を頼むとき（Pre-spec Steering Layer）
+
+ここからはエンジニア向けです。intent-planner のいちばん基本の使い方は、仕様（spec）を書く**手前**に1段だけ挟んで、意図を整理してから実装に渡すこと。整理した意図は、そのまま [cc-sdd](https://github.com/gotalab/cc-sdd) や [OpenSpec](https://github.com/Fission-AI/OpenSpec) の spec 駆動フローへ引き継げます。
+
+「Pre-spec（仕様の手前）」「Steering（舵取り）」の名のとおり、ここで決めた基準が実装中ずっと AI の舵取りをし続けます。
+
+### 進め方
+
+各ステップの成果物をレビューしながら、この順に進めます。
+
+```
+/intent-discover   →  /intent-compass  →  /intent-packets  →  /intent-export-cc-sdd
+（全体像を整理）       （守るべき基準）     （作業単位に分解）    （実装ツールへ引き継ぎ）
+```
+
+1. **`/intent-discover`** — 課題やアイデアについて AI が質問し、意図の全体像を組み立てます。
+2. **`/intent-compass`** — 「目指す姿」「進んではいけない方向」「壊してはいけない不変則」などの判断基準を作ります。これが実装中の AI に毎回渡る舵になります。
+3. **`/intent-packets`** — 実装に渡せる作業単位（packet）に分けます。最初に着手すべき単位を理由つきで1つ薦めてくれます。
+4. **`/intent-export-cc-sdd`**（または `/intent-export-openspec`）— 選んだ作業単位を実装ツールの下書きに変換します。
+
+そのあとは cc-sdd / OpenSpec の spec フロー（requirements → design → tasks → 実装）を回します。intent-planner が作るのは下書きまでで、spec の本体は実装ツールが生成し、各フェーズであなたがレビューします。
+
+### このとき何がうれしいのか（Before / After）
+
+曖昧な依頼1行が、intent-planner を通すとどう具体化されるかの例です（題材: ログイン機能）。
+
+**Before** — AI への依頼はこれだけ:
+
+```
+ログイン機能をいい感じに作って
+```
+
+「いい感じ」の解釈は AI 任せになり、独自のパスワード認証を生やす・既存の認証基盤と合わない実装に進むなど、その場しのぎに流れがちです。
+
+**After** — discover → compass → packets を通すと、同じ依頼がこうなります:
+
+- **ゴール（計測基準つき）**: 初回ユーザーが2分以内にログインを完了できる（開始〜ダッシュボード表示で計測）
+- **不変則（守ること）**: 既存の OAuth provider（Google / GitHub）との互換性を壊さない
+- **進んではいけない方向**: 独自のパスワード認証を追加しない
+- **作業単位**:
+  1. **P1: OAuth callback の E2E** — 一番細い経路を最初に貫通させる
+  2. **P2: エラー状態と再試行 UI**
+  3. **P3: 監査ログ**
+
+最初に薦められるのは P1。一番細い経路を先に通すことで、最大の不確実性（リダイレクト設定・セッション管理）を最初に潰せるからです。
+
+このゴール・不変則・進んではいけない方向が、P2 以降の実装でも AI に毎回渡り続けるので、「独自認証を生やさない」「既存 provider を壊さない」という基準が効き続けます。
+
+### 実装が終わったら（育て続ける）
+
+「作って終わり」にしないために、実装の学びを意図の文書へ戻します。
+
+- **`/intent-writeback`** — 実装で分かったこと（新しく決まったこと・不変則の違反・暗黙の挙動）を記録し、あなたが承認した分だけ文書へ反映します。
+- **`/intent-improve`** — 数件こなした節目に、文書と実装のズレをまとめて検出して直します。
+
+これで `.intent/` は実装の現実と同期し続ける、生きた判断基準になります。
+
+---
+
+<a id="sec-full-idd"></a>
+
+## ③ まるごと自動で回す（full IDD）
+
+②では人が `/intent-status` を見て次の一手を毎回手で進めました。代わりに、`/loop` のような外側のループに駆動を委ねると、**意図→実装→書き戻しのサイクル全体を自走**させられます。これが intent-planner を **Intent Driven Development（IDD）** として一周まるごと回す使い方です。
+
+intent-planner 自身は「いま何工程目か（state）」を記録しますが、それを自動で次へ進める仕組み（状態機械）は内蔵していません。だから駆動を外に出せます。
+
+```
+/loop /intent-status
+  → status が出す「次の一手」を外側のループが拾い、
+    次の作業単位の export → 実装 → writeback まで進めて、
+    また status に戻る — これを繰り返す
+```
+
+②との違いは**駆動を誰が握るか**だけです。どちらでも、次に何を作るかを決めているのは Intent（整理した意図と、status が出す「次の一手」）です。
+
+> ### ⚠️ 自走させるときの代償（必ず把握してください）
+>
+> 文書を書き換えるコマンド（discover / compass / packets / writeback / improve / export）は、**意図的に人間の承認を前提**にしています。無監視で走り続ける開発（vibe coding）への歯止めです。`/loop` で承認を飛ばすと、速さと引き換えに次を失います:
+>
+> - **ズレに気づく機会** — 各段で「意図とズレている」と気づく機会が減る
+> - **文書の保護** — 誤った学びがそのまま意図文書に反映されうる
+> - **重い分岐のレビュー** — 人が確定すべき問いを承認なしで埋めると、推測が確定として固定されうる
+>
+> **おすすめはハイブリッド**です。内側の「実装→テスト→修正」は `/loop` に委ねて速く回し、段の切れ目（compass 確定・packet 分解・writeback 承認・重い問いの確定）では人が割り込む。読むだけのコマンド（status / validate / overview）は承認不要なので、`/loop` の中でも安全に判断材料を出し続けます。「全部を承認レスで回す」より「**効く一点に承認を集中する**」のが、軽さと安全を両立させる使い方です。
+>
+> 自走の仕組みと注意点は [docs/guide.md の「自動で回す」節](docs/guide.md#自動で回すloopときの注意)に、理論的背景は [docs/theory.md の「状態は持つが、状態機械は持たない」節](docs/theory.md)にまとめています。
+
+---
+
+## こんなときに
+
+具体的な状況からも入れます。
+
+| 状況 | intent-planner がやること | 使い方 |
+|---|---|---|
+| 文書・調査・企画をまとめたい（コードを書かない） | 意図を整理し、読める成果物を直接生成する | [①](#sec-no-code) |
+| 新規プロダクト・機能を AI 主導で作り始めたい | 作りたいものの意図と基準を実装前に言語化し、最初の1行から舵を効かせる | [②](#sec-prespec) |
+| PoC・個人開発を1人で作りたい | 詰めの問い（計測できる成功基準・最小貫通・仮説と反証条件）を入口で選べる | [②](#sec-prespec) |
+| 大規模リファクタを頼みたい | 「正しく動くが設計意図からズレる」変更を防ぐ基準を先に作る | [②](#sec-prespec) |
+| レガシーで仕様が分からない | 観測できる振る舞いから意図を逆算して文書化する | [②](#sec-prespec) |
+| 稼働中システムに機能追加したい | 既存への影響を踏まえた追加単位に分解する | [②](#sec-prespec) |
+| 計画から実装・書き戻しまで自走させたい | 外側のループに駆動を委ね、人は効く一点だけ承認する | [③](#sec-full-idd) |
+
+---
+
+## 安心して使うために
+
+- **アプリのコードは変更しません**。書くのは `.intent/` の中の Markdown だけです（writeback / improve も承認した分しか反映しません）。
+- **既存ファイルは上書きしません**（`--force` を指定したときを除く）。まず `--dry-run` で確認できます。
+- **検査系（enforcement / drift-watch）は既定 off** で、設定しない限り動作は何も変わりません。git フックは `--enforce` を明示したときだけ配置します。
+- **動作時の依存ゼロ**（Node 標準モジュールのみ）。常駐プロセスも、外部サービスへの送信もありません。
+
+---
+
+## もっと知りたい
+
+- **各機能の使い方** — モード・コマンド逐条・ファイル構成・enforcement・drift-watch・造語管理・制約叩き台など → [docs/guide.md](docs/guide.md)
+- **なぜこの手順なのか** — 要求工学・ソフトウェアアーキテクチャ研究との対応、参考文献つき → [docs/theory.md](docs/theory.md)
+
+理論を知らなくても、フローに沿って質問に答えていけば必要な成果物が埋まるように設計しています。docs は「もう一段くわしく知りたくなったとき」の参照用です。
+
+---
+
+## ライセンス
+
+MIT © Yoshishige Tsuji
+
+本プロジェクトの開発には [cc-sdd](https://github.com/gotalab/cc-sdd)（MIT, © 2025 gotalab）由来のツーリングを使用しています。配布物（npm パッケージおよび本リポジトリの `templates/` 等）に cc-sdd 由来のファイルは含まれません。