lee-spec-kit 0.7.9 → 0.7.11

package/README.en.md

@@ -7,7 +7,7 @@
 </div>
 
 <p align="center">
-  <strong>Agent-guided development harness CLI for spec-driven projects</strong>
+  <strong>Orchestration harness CLI for AI agent-driven development</strong>
 </p>
 
 <p align="center">
@@ -48,24 +48,21 @@ npx lee-spec-kit flow
 
 ## Why It Exists
 
-This CLI was built to make spec-driven development more consistent when working with AI agents.
-The goal is not just to generate a docs folder, but to make it easier for both humans and agents to follow how a project moves from requirements, through ideas, into concrete implementation work.
+This CLI was built to keep documents and actual execution flow together when working with an AI agent.
 
-To do that, `lee-spec-kit` structures work as `PRD → idea → feature`, and then connects that document flow to a git-centered issue/PR workflow.
-The focus is to keep planning artifacts and code workflow aligned, so the agent-readable state and the human-reviewable state stay in the same operating model.
+It is not just a tool that creates a docs folder. The main agent can use it to understand which feature is active, what the next action is, and where user approval is required.
 
-In that flow, PRD lives in the top-level `docs/prd/` space created by `init`.
-Ideas capture candidates and experiments that come out of those requirements, and Features turn the approved work into executable units with `spec.md`, `plan.md`, and `tasks.md`.
+The project structure follows `PRD → idea → feature`. PRD is where top-level requirements are written under `docs/prd/`, idea is for candidate approaches or experiments, and feature is the stage where actual work is managed through `spec.md`, `plan.md`, and `tasks.md`.
 
-Structurally, it draws inspiration from [spec-kit](https://github.com/github/spec-kit) and [OpenSpec](https://github.com/Fission-AI/OpenSpec),
-but it is adapted toward a more practical project workflow with explicit document stages, feature-level execution units, and tighter git workflow integration for agent orchestration.
+The overall approach is influenced by [spec-kit](https://github.com/github/spec-kit) and [OpenSpec](https://github.com/Fission-AI/OpenSpec). The difference is that this project is less about inventing a new standard and more about keeping my own document flow and execution flow in one CLI.
 
 ## What This CLI Does
 
-`lee-spec-kit` is less a power-user operator console and more a development harness that helps the main agent read project state and choose the next action.
+`lee-spec-kit` is less a power-user console and more an opinionated harness that helps the main agent read project state and choose the next action.
 
 - Humans usually ask in natural language.
-- The main agent translates those requests into commands like `detect`, `context`, `flow`, `idea`, and `feature`.
+- The human-facing surface stays small: `init`, `idea`, `feature`, `context`, `flow`.
+- In practice, the main agent runs `detect`, `context`, and `flow` first.
 - Deeper operational commands still exist, but they are no longer front-loaded in the default help output.
 
 ## How It Works
@@ -75,7 +72,7 @@ but it is adapted toward a more practical project workflow with explicit documen
 3. Create work with `idea` or `feature`.
 4. Let the main agent read `detect` and `context`.
 5. Humans step in for approvals, exceptions, and direction changes.
-6. Use `context` for the current action and `flow` for overall workflow health.
+6. Use `context` for the current action and `flow` as the default workflow runner.
 
 ## Humans Usually Ask Like This
 
@@ -85,14 +82,18 @@ but it is adapted toward a more practical project workflow with explicit documen
 - "What is the next action right now?"
 - "Check the overall project state."
 
-## Commands The Agent Usually Runs
+## Commands
 
-- `init`: initialize docs/workflow scaffolding
-- `idea`: create a pre-feature idea document
-- `feature`: create a concrete execution unit
-- `detect`: detect whether the workspace uses lee-spec-kit
-- `context`: read current feature state and next actions
-- `flow`: summarize workflow state
+- The core agent-facing commands are the three commands below.
+  - `detect`: detect whether the workspace uses lee-spec-kit
+  - `context`: read the current feature state and next actions
+  - `flow`: run the default workflow auto-loop and pause at selection/approval/manual/resume boundaries
+- The public human-facing commands are the five commands below.
+  - `init`: initialize docs/workflow scaffolding
+  - `idea`: create a pre-feature idea document
+  - `feature`: create a concrete execution unit
+  - `context`: show the current state and next action
+  - `flow`: run the default workflow auto-loop and pause at selection/approval/manual/resume boundaries
 
 ## Agent Kickoff Prompt
 
@@ -100,9 +101,10 @@ but it is adapted toward a more practical project workflow with explicit documen
 Start procedure:
 1) Run npx lee-spec-kit detect --json
 2) If isLeeSpecKitProject === true, run npx lee-spec-kit context --json-compact
-3) If approvalRequest.required=true, show approvalRequest.userFacingLines exactly as provided, then wait for user approval
-4) Do not execute before approval; execute requiresUserCheck=true actions only after approval
-5) If isLeeSpecKitProject === false, skip lee-spec-kit-specific flow and continue with normal workflow
+3) Use context as the read-only state probe, and use flow as the default execution/resume entrypoint
+4) If approvalRequest.required=true, briefly restate the current stage from matchedFeature.currentSubstate* when available, then show approvalRequest.userFacingLines exactly as provided and wait for user approval
+5) Do not execute before approval; for command execution, default to npx lee-spec-kit flow <featureRef> --approve <LABEL> --execute
+6) If isLeeSpecKitProject === false, skip lee-spec-kit-specific flow and continue with normal workflow
 ```
 
 ## Docs

package/README.md

@@ -48,27 +48,21 @@ npx lee-spec-kit flow
 
 ## 왜 만들었나
 
-이 CLI는 AI 에이전트와 함께 프로젝트를 진행할 때 spec-driven development 기반의 흐름을 더 일관되게 만들기 위해 만들어졌습니다.
-목표는 단순히 문서 폴더를 생성하는 것이 아니라, 프로젝트가 어떤 요구사항에서 출발했고 어떤 아이디어를 거쳐 어떤 구현 단위로 내려왔는지를
-에이전트와 사람이 함께 추적할 수 있게 만드는 것입니다.
+이 CLI는 AI 에이전트와 함께 프로젝트를 진행할 때, 문서와 실제 작업 흐름이 따로 놀지 않게 하려고 만들었습니다.
 
-이를 위해 `lee-spec-kit`는 `PRD → idea → feature` 단계로 작업을 구조화하고, 실제 구현과 협업 흐름에서는 git 기반의 issue/PR 구조를 자연스럽게 연결하도록 설계되었습니다.
-즉, 문서 작성 단계와 코드 변경 단계가 따로 놀지 않도록, 에이전트가 읽을 수 있는 상태와 사람이 리뷰할 수 있는 상태를 같은 흐름 안에 두는 데 초점을 둡니다.
+단순히 문서 폴더만 만드는 것이 아니라, 메인 에이전트가 지금 어떤 feature를 보고 있는지, 다음에 무엇을 해야 하는지, 어디서 사용자 확인이 필요한지를 같이 다룰 수 있게 하는 쪽에 더 가깝습니다.
 
-여기서 PRD는 `init`이 만들어 주는 `docs/prd/`에서 직접 관리하는 상위 요구사항 공간입니다.
-Idea는 그 요구사항에서 나온 후보와 실험을 정리하는 단계이고, Feature는 그중 실제로 실행하기로 한 단위를
-`spec.md`, `plan.md`, `tasks.md`로 내려서 관리하는 단계입니다.
+작업 구조는 `PRD → idea → feature` 흐름을 따릅니다. PRD는 `docs/prd/`에서 상위 요구사항을 정리하는 공간이고, idea는 후보나 실험을 적어두는 단계이며, feature는 실제로 실행할 단위를 `spec.md`, `plan.md`, `tasks.md`로 내려 관리하는 단계입니다.
 
-구조적으로는 [spec-kit](https://github.com/github/spec-kit)과 [OpenSpec](https://github.com/Fission-AI/OpenSpec)의 접근을 참고했지만,
-`lee-spec-kit`는 실제 프로젝트 진행 방식과 에이전트 오케스트레이션에 맞게 더 실무적인 문서 단계, feature 단위, 그리고 git workflow 연결을 강조하도록 재구성되었습니다.
+구조적으로는 [spec-kit](https://github.com/github/spec-kit)과 [OpenSpec](https://github.com/Fission-AI/OpenSpec)의 접근을 참고했습니다. 다만 이 프로젝트는 새 표준을 만들려는 쪽보다는, 내가 실제로 쓰는 작업 흐름을 더 잘 굴리기 위해 문서 구조와 실행 흐름을 한 CLI에 묶는 쪽에 가깝습니다.
 
 ## 이 CLI가 하는 일
 
-`lee-spec-kit`는 사람이 매번 세부 명령을 직접 치는 도구라기보다,
-메인 에이전트가 현재 상태를 읽고 다음 액션을 고르도록 돕는 개발 하네스입니다.
+`lee-spec-kit`는 사람이 세부 운영 명령을 외우는 도구라기보다, 메인 에이전트가 현재 상태를 읽고 다음 액션을 고르도록 돕는 개인용 하네스에 가깝습니다.
 
 - 사람은 보통 자연어로 요청합니다.
-- 메인 에이전트는 그 요청을 `detect`, `context`, `flow`, `idea`, `feature` 같은 명령으로 번역해 실행합니다.
+- 사람용으로는 `init`, `idea`, `feature`, `context`, `flow` 정도의 작은 표면을 제공합니다.
+- 실제 에이전트 실행은 `detect`, `context`, `flow` 3개 명령을 기준으로 움직입니다.
 - 더 깊은 운영 명령은 여전히 지원되지만 기본 help에는 전면 노출하지 않습니다.
 
 ## 어떻게 동작하나
@@ -78,7 +72,7 @@ Idea는 그 요구사항에서 나온 후보와 실험을 정리하는 단계이
 3. `idea`로 후보/실험을 정리하거나, 바로 `feature`로 실행 단위를 만듭니다.
 4. 메인 에이전트가 `detect`와 `context`를 읽고 진행합니다.
 5. 사람은 승인, 예외 처리, 방향 수정 시점에 개입합니다.
-6. 현재 다음 액션과 승인 대기 상태는 `context`, 전체 상태 요약은 `flow`로 확인합니다.
+6. 현재 다음 액션과 승인 대기 상태는 `context`, 기본 workflow 실행/재개는 `flow`로 진행합니다.
 
 ## 사람은 보통 이렇게 요청합니다
 
@@ -90,12 +84,16 @@ Idea는 그 요구사항에서 나온 후보와 실험을 정리하는 단계이
 
 ## 에이전트가 주로 실행하는 명령
 
-- `init`: docs/workflow 구조를 초기화합니다.
-- `idea`: 구현 전 아이디어 문서를 생성합니다.
-- `feature`: 실제 작업 단위를 생성합니다.
-- `detect`: 현재 워크스페이스가 lee-spec-kit 프로젝트인지 감지합니다.
-- `context`: 현재 feature 상태와 다음 액션을 읽습니다.
-- `flow`: 전체 워크플로우 상태를 요약합니다.
+- 실제 에이전트 실행 기준 명령은 아래 3개입니다.
+  - `detect`: 현재 워크스페이스가 lee-spec-kit 프로젝트인지 감지합니다.
+  - `context`: 현재 feature 상태와 다음 액션을 읽습니다.
+  - `flow`: 기본 workflow auto-run을 진행하고 선택/승인/수동/재개 경계에서 멈춥니다.
+- 사람용 public 명령은 아래 다섯 개입니다.
+  - `init`: docs/workflow 구조를 초기화합니다.
+  - `idea`: 구현 전 아이디어 문서를 생성합니다.
+  - `feature`: 실제 작업 단위를 생성합니다.
+  - `context`: 현재 feature 상태와 다음 액션을 읽습니다.
+  - `flow`: 기본 workflow auto-run을 진행하고 선택/승인/수동/재개 경계에서 멈춥니다.
 
 ## 에이전트 킥오프 프롬프트
 
@@ -103,9 +101,10 @@ Idea는 그 요구사항에서 나온 후보와 실험을 정리하는 단계이
 작업 시작 절차:
 1) npx lee-spec-kit detect --json
 2) isLeeSpecKitProject === true 이면 npx lee-spec-kit context --json-compact 실행
-3) approvalRequest.required=true 이면 approvalRequest.userFacingLines를 그대로 사용자에게 제시하고 승인 대기
-4) 승인 전에는 실행하지 말고, requiresUserCheck=true 액션은 승인 후에만 실행
-5) isLeeSpecKitProject === false 이면 lee-spec-kit 전용 절차를 건너뛰고 일반 워크플로우로 진행
+3) 상태 확인은 context를 read-only probe로 사용하고, 실제 실행/재개는 flow를 기본 엔트리포인트로 사용
+4) approvalRequest.required=true 이면 matchedFeature.currentSubstate* 기반 현재 단계 한 줄 요약을 먼저 짧게 말하고 approvalRequest.userFacingLines를 그대로 사용자에게 제시한 뒤 승인 대기
+5) 승인 전에는 실행하지 말고, 명령 실행은 기본적으로 npx lee-spec-kit flow <featureRef> --approve <LABEL> --execute 사용
+6) isLeeSpecKitProject === false 이면 lee-spec-kit 전용 절차를 건너뛰고 일반 워크플로우로 진행
 ```
 
 ## Docs