sb-codex-tool 0.1.0 → 0.1.1

package/README.ko.md

@@ -37,7 +37,7 @@ workflow/runtime scaffold입니다.
 
 ## 요구 사항
 
-- Node.js 25 이상
+- Node.js 24 이상
 - Codex가 working tree를 읽고 쓸 수 있는 프로젝트
 - 기본 launch wrapper를 쓸 경우 `codex` 바이너리
 - 명시적 상태, handoff, verification artifact가 필요한 작업 방식
@@ -66,36 +66,30 @@ npm exec sb-codex-tool -- setup
 
 ## 빠른 시작
 
-repository에 scaffold를 초기화합니다.
+대부분의 팀은 아래 세 명령만 직접 실행하면 됩니다.
 
 ```bash
-sb-codex-tool setup
+npm exec sb-codex-tool -- setup
+npm exec sb-codex-tool -- doctor
+npm exec sb-codex-tool -- status
 ```
 
-현재 scaffold와 운영 상태를 점검합니다.
-
-```bash
-sb-codex-tool doctor
-sb-codex-tool status
-```
+전역 설치를 썼다면 `npm exec` 없이 `sb-codex-tool`를 직접 호출해도 됩니다.
 
-bounded work cycle을 시작합니다.
+`status`까지 확인했으면 그다음부터는 `Codex-first mode`로 들어가면 됩니다.
+Codex에게 hot path를 읽고, 작업 목표와 제약을 물어본 뒤, plan/state/summary
+문서를 대신 정리해 달라고 요청하면 됩니다.
 
-```bash
-sb-codex-tool begin add-status-panel "Add Status Panel"
-```
+예시 프롬프트:
 
-현재 cycle을 fresh verification 준비 상태로 올립니다.
-
-```bash
-sb-codex-tool prepare-verify
+```text
+AGENTS.md와 sb-codex-tool hot path를 읽고 시작해줘. 작업 목표와 제약을
+먼저 물어본 뒤, plan, state, summary, verification note를 작업에 맞게 같이
+정리해줘.
 ```
 
-fresh verification agent가 verdict를 남긴 뒤 cycle을 닫습니다.
-
-```bash
-sb-codex-tool close
-```
+`begin`, `prepare-verify`, `close` 같은 helper 명령은 계속 남아 있지만,
+이제 기본 사용자 경로가 아니라 고급 수동 모드로 봅니다.
 
 ## `setup`이 만드는 것
 
@@ -123,18 +117,25 @@ AGENTS.md
 
 ## 명령어
 
+### 기본 사용자 명령
+
 | 명령 | 목적 |
 | --- | --- |
 | `sb-codex-tool setup` | scaffold, workflow 자산, 가이드, ignore 파일을 생성합니다. |
 | `sb-codex-tool doctor` | scaffold 무결성, 현재 cycle 준비도, semantic coherence를 검사합니다. |
 | `sb-codex-tool status` | 현재 stage, next action, hot path, 최신 run, semantic issue를 보여줍니다. |
+| `sb-codex-tool [codex args]` | 명시적 명령이 없으면 wrapper를 통해 Codex를 실행합니다. |
+
+### 고급 수동 helper 명령
+
+| 명령 | 목적 |
+| --- | --- |
 | `sb-codex-tool begin <slug> [title words]` | plan/summary/handoff/review artifact를 갖는 새 cycle을 엽니다. |
 | `sb-codex-tool prepare-verify` | 현재 cycle을 verify-ready 상태로 옮기고 handoff를 다시 씁니다. |
 | `sb-codex-tool close` | fresh verification verdict를 읽어 cycle을 최종 종료합니다. |
 | `sb-codex-tool assign <agent-name> <slug> [title words]` | subagent용 bounded assignment guide를 생성합니다. |
 | `sb-codex-tool complete-assignment <agent-name> <close\|clear\|replace> ...` | 완료된 subagent assignment의 lifecycle 처리를 기록합니다. |
 | `sb-codex-tool review-consistency <agent-name> [title words]` | active cycle에 대한 consistency review artifact를 생성합니다. |
-| `sb-codex-tool [codex args]` | 명시적 명령이 없으면 wrapper를 통해 Codex를 실행합니다. |
 
 ## 워크플로 모델
 
@@ -147,18 +148,25 @@ AGENTS.md
 5. `verify`
 
 최종 verification은 항상 fresh agent가 수행합니다. non-trivial 작업은
-일반적으로 `prepare-verify`를 거친 뒤 fresh verification을 수행하고, 마지막에
-`close`로 닫습니다.
+fresh verification과 verification summary/work journal 정리까지 포함하는
+closure 단계로 끝납니다.
+
+### 기본 Codex-first cycle
+
+1. `setup`, `doctor`, `status`를 실행합니다.
+2. Codex에게 hot path를 읽고 작업 목표와 제약을 질문하게 합니다.
+3. Codex가 approved plan과 state 문서를 직접 정리합니다.
+4. Codex가 구현과 execution summary 갱신을 진행합니다.
+5. Codex가 단순성, 재사용성, 가독성을 기준으로 refactor합니다.
+6. Codex가 verification-ready handoff와 next-agent guidance를 정리합니다.
+7. fresh verification agent가 contract, hot path, 코드, 검증 명령을 독립적으로 확인합니다.
+8. main Codex agent가 verification summary와 work journal을 정리합니다.
 
-### 일반적인 cycle
+### 고급 수동 cycle
 
-1. `begin`으로 새 cycle을 엽니다.
-2. approved plan과 scope guide를 실제 작업 내용으로 채웁니다.
-3. 구현을 진행하고 execution summary를 갱신합니다.
-4. 단순성, 재사용성, 가독성을 기준으로 refactor합니다.
-5. `prepare-verify`를 실행해 handoff, state, verification 입력을 정렬합니다.
-6. fresh verification agent가 contract, hot path, 코드, 검증 명령을 독립적으로 확인합니다.
-7. fresh verifier가 verdict를 남긴 뒤 `close`를 실행합니다.
+명시적인 lifecycle 명령을 선호하면 `begin`, `prepare-verify`, `close` 같은
+helper 명령을 계속 사용할 수 있습니다. 다만 이 경로는 기본 사용자 경로가
+아니라 advanced/manual 모드입니다.
 
 ## 상태 구조
 
@@ -199,6 +207,8 @@ hot-path onboarding은 다음 순서로 시작합니다.
 
 - orchestration을 소유합니다.
 - 사용자 진행 상황을 한국어로 보고합니다.
+- Codex-first mode에서는 plan, summary, handoff, review, work journal을
+  직접 갱신할 수 있습니다.
 - subagent에 bounded task를 배정합니다.
 - 최종 통합과 closure를 담당합니다.
 

package/README.md

@@ -37,7 +37,7 @@ work more repeatable inside a normal repository.
 
 ## Requirements
 
-- Node.js 25 or newer
+- Node.js 24 or newer
 - A project where Codex can read and write the working tree
 - A `codex` binary available when using the default launch wrapper
 - A workflow that benefits from explicit state, handoff, and verification
@@ -67,36 +67,31 @@ npm exec sb-codex-tool -- setup
 
 ## Quick Start
 
-Initialize the scaffold in a repository:
+Most teams only need three direct commands:
 
 ```bash
-sb-codex-tool setup
+npm exec sb-codex-tool -- setup
+npm exec sb-codex-tool -- doctor
+npm exec sb-codex-tool -- status
 ```
 
-Inspect the scaffold and operational state:
-
-```bash
-sb-codex-tool doctor
-sb-codex-tool status
-```
+If you installed the package globally, you can drop `npm exec` and call
+`sb-codex-tool` directly.
 
-Start a bounded work cycle:
+After `status`, switch into Codex-first mode. Ask Codex to read the hot path,
+ask for the task goal and constraints, and maintain the remaining plan/state
+artifacts for you.
 
-```bash
-sb-codex-tool begin add-status-panel "Add Status Panel"
-```
+Example prompt:
 
-Prepare the current cycle for fresh verification:
-
-```bash
-sb-codex-tool prepare-verify
+```text
+Read AGENTS.md and the sb-codex-tool hot path. Ask me for the task goal and
+constraints, then update the plan, state, summaries, and verification notes as
+we work.
 ```
 
-Close the cycle after a fresh verification agent records a verdict:
-
-```bash
-sb-codex-tool close
-```
+The manual helper commands still exist, but they are now the advanced/manual
+path rather than the default human workflow.
 
 ## What `setup` Creates
 
@@ -124,18 +119,25 @@ onboarding, fresh verification, and human-readable work journaling.
 
 ## Commands
 
+### Default human workflow
+
 | Command | Purpose |
 | --- | --- |
 | `sb-codex-tool setup` | Create the scaffold, workflow assets, guides, and ignore files. |
 | `sb-codex-tool doctor` | Validate scaffold integrity, current-cycle readiness, and semantic coherence. |
 | `sb-codex-tool status` | Show the current stage, next action, hot path, latest run details, and semantic issues. |
+| `sb-codex-tool [codex args]` | Launch Codex through the wrapper when no explicit command is given. |
+
+### Advanced/manual helpers
+
+| Command | Purpose |
+| --- | --- |
 | `sb-codex-tool begin <slug> [title words]` | Open a new bounded work cycle with plan/summary/handoff/review artifacts. |
 | `sb-codex-tool prepare-verify` | Move the current cycle into verify-ready state and rewrite the handoff. |
 | `sb-codex-tool close` | Finalize the current cycle from the recorded fresh verification verdict. |
 | `sb-codex-tool assign <agent-name> <slug> [title words]` | Create a bounded assignment guide for a subagent. |
 | `sb-codex-tool complete-assignment <agent-name> <close\|clear\|replace> ...` | Record lifecycle handling for a completed subagent assignment. |
 | `sb-codex-tool review-consistency <agent-name> [title words]` | Write a bounded consistency review artifact for the active cycle. |
-| `sb-codex-tool [codex args]` | Launch Codex through the wrapper when no explicit command is given. |
 
 ## Workflow Model
 
@@ -148,18 +150,27 @@ onboarding, fresh verification, and human-readable work journaling.
 5. `verify`
 
 Final verification is always fresh-agent-only. Non-trivial work is expected to
-end with `prepare-verify` and then a fresh verification pass before `close`.
+end with fresh verification and a recorded closure summary.
 
-### Typical Cycle
+### Typical Codex-first cycle
 
-1. Run `begin` to open a new cycle.
-2. Fill the approved plan and scope guide with real work.
-3. Implement the change and update the execution summary.
-4. Refactor for simplicity, reuse, and readability.
-5. Run `prepare-verify` to align handoff, state, and verification inputs.
+1. Run `setup`, `doctor`, and `status`.
+2. Ask Codex to read the hot path, clarify the task, and write or update the
+   approved plan and state files.
+3. Let Codex implement the change and keep the execution summary current.
+4. Let Codex refactor for simplicity, reuse, and readability.
+5. Let Codex prepare a verification-ready handoff and next-agent guidance.
 6. Have a fresh verification agent inspect the contracts, hot path, code, and
    checks.
-7. Run `close` after the fresh verifier records a verdict.
+7. Let the main Codex agent record the verification summary and update the
+   human work journal.
+
+### Manual helper mode
+
+If you prefer explicit lifecycle commands, `begin`, `prepare-verify`, `close`,
+`assign`, and the other helper commands are still available. They are useful
+for teams that want CLI-created cycle artifacts instead of asking Codex to
+write those files directly.
 
 ## State Layout
 
@@ -200,6 +211,8 @@ Hot-path onboarding starts with:
 
 - Owns orchestration
 - Reports progress to the user in Korean
+- Can update plans, summaries, handoffs, reviews, and work-journal entries
+  directly when operating in Codex-first mode
 - Assigns bounded work to subagents
 - Integrates and closes work
 

package/dist/cli.js

@@ -222,7 +222,7 @@ function createInitialCurrentIndex() {
   return {
     version: 2,
     currentStage: "clarify",
-    nextAction: "Review AGENTS.md and customize .sb-codex-tool/project.md.",
+    nextAction: "Review AGENTS.md, run status if needed, and ask Codex to organize the first task.",
     latestApprovedPlan: null,
     latestRelevantSummary: null,
     latestRun: null,
@@ -251,7 +251,8 @@ function createInitialCurrentIndex() {
     },
     assignmentGuides: {},
     notes: [
-      "Keep this file current enough for a fresh agent to start from the hot path."
+      "Keep this file current enough for a fresh agent to start from the hot path.",
+      "Default usage is human setup/doctor/status plus Codex-managed plan, state, and summary updates."
     ]
   };
 }
@@ -323,6 +324,14 @@ Read in this order before implementation or verification:
 
 ${renderHotPath(current.hotPath)}
 
+## Default Operating Mode
+
+- Most users run \`setup\`, \`doctor\`, and \`status\` directly.
+- After that, ask Codex to read the hot path, clarify the task, and update
+  plans, summaries, handoffs, and state files in-session.
+- Use manual helper commands only when you want explicit CLI-managed cycle
+  artifacts.
+
 ## Additional Repo Docs
 
 ${renderImplementationReference(implementationMenuPath)}
@@ -508,6 +517,8 @@ verification-friendly.
 
 - The main agent owns orchestration and user communication.
 - Main-agent progress updates to the user are always in Korean.
+- Most users run \`setup\`, \`doctor\`, and \`status\` directly, then let Codex
+  update plans, state, summaries, handoffs, and reviews in-session.
 - Subagents are bounded workers and must be reset or replaced after completion.
 - Every new implementation agent reads \`${STATE_ROOT_NAME}/guides/code-consistency.md\` first.
 - The main agent references \`${STATE_ROOT_NAME}/guides/code-consistency.md\` before assigning new work.
@@ -533,6 +544,8 @@ verification-friendly.
 
 - Hot path starts with \`${STATE_ROOT_NAME}/project.md\` and \`${STATE_ROOT_NAME}/state.md\`.
 - Update next-agent guidance after non-trivial code changes.
+- Codex may create or update plan, summary, handoff, and review artifacts
+  directly when the team is operating in Codex-first mode.
 - If new conventions are introduced, update \`${STATE_ROOT_NAME}/guides/code-consistency.md\`.
 
 ## Work Journal Rules
@@ -566,6 +579,8 @@ function projectTemplate(context) {
 - Follow the workflow defined in AGENTS.md.
 - Keep state inspectable through ${STATE_ROOT_NAME}/.
 - Optimize for reuse, readability, and low complexity.
+- Most users will run \`setup\`, \`doctor\`, and \`status\` directly, then let
+  Codex maintain plans, summaries, handoffs, and reviews during normal work.
 
 ## Important Entrypoints
 
@@ -3514,27 +3529,33 @@ function printHelp() {
   console.log("sb-codex-tool");
   console.log("");
   console.log("Usage:");
+  console.log("  sb-codex-tool setup");
+  console.log("  sb-codex-tool doctor");
+  console.log("  sb-codex-tool status");
   console.log("  sb-codex-tool assign <agent-name> <slug> [title words]");
   console.log("  sb-codex-tool begin <slug> [title words]");
   console.log("  sb-codex-tool close");
   console.log("  sb-codex-tool complete-assignment <agent-name> <close|clear|replace> [replacement-agent] [replacement-slug] [title words]");
   console.log("  sb-codex-tool prepare-verify");
   console.log("  sb-codex-tool review-consistency <agent-name> [title words]");
-  console.log("  sb-codex-tool setup");
-  console.log("  sb-codex-tool doctor");
-  console.log("  sb-codex-tool status");
   console.log("  sb-codex-tool [codex args]");
   console.log("");
-  console.log("Commands:");
+  console.log("Default human workflow:");
+  console.log("  setup   Create the sb-codex-tool scaffold in the current project.");
+  console.log("  doctor  Validate the scaffold and required operational files.");
+  console.log("  status  Show current stage, next action, hot path, and git context.");
+  console.log("");
+  console.log("Advanced/manual helpers:");
   console.log("  assign  Create a bounded assignment guide and update active subagents.");
   console.log("  begin   Create the next work-cycle artifacts and update current state.");
   console.log("  close   Finalize the current cycle from the recorded review verdict.");
   console.log("  complete-assignment  Record close/clear/replace lifecycle handling for a bounded subagent task.");
   console.log("  prepare-verify  Align handoff, run state, and current state for fresh verification.");
   console.log("  review-consistency  Create a consistency review artifact and update visible review state.");
-  console.log("  setup   Create the sb-codex-tool scaffold in the current project.");
-  console.log("  doctor  Validate the scaffold and required operational files.");
-  console.log("  status  Show current stage, next action, hot path, and git context.");
+  console.log("");
+  console.log("Codex-first mode:");
+  console.log("  Run setup, doctor, and status yourself.");
+  console.log("  Then ask Codex to read the hot path, clarify the task, and update the plan/state/summaries for you.");
   console.log("  help    Show this message.");
   console.log("");
   console.log("When no command is provided, sb-codex-tool launches Codex through the wrapper.");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sb-codex-tool",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Lightweight Codex workflow and runtime scaffold for general software projects.",
   "license": "UNLICENSED",
   "publishConfig": {
@@ -45,6 +45,6 @@
     "esbuild": "^0.27.0"
   },
   "engines": {
-    "node": ">=25.0.0"
+    "node": ">=24.0.0"
   }
 }