@opellen/scaff 0.1.11

package/README.ko.md

@@ -0,0 +1,327 @@
+<div align="center">
+  <img src="https://raw.githubusercontent.com/opellen/scaff/master/assets/scaff-logo-wordmark.webp" alt="Scaff Logo" width="180"/>
+  <p><strong>목표 중심의 기민한 AI 하니스. 오직 마크다운.</strong></p>
+  <p>나와 AI가 바로 이해하는 현재 — <code>CONTEXT.md</code>, <code>GOAL.md</code>, <code>ROADMAP.md</code></p>
+
+  <p>
+    <code>CONTEXT.md</code>를 열면 <b>현재 맥락</b>이 보이고,<br/>
+    <code>GOAL.md</code>를 열면 <b>지금 할 일</b>이 보입니다.<br/>
+    <code>ROADMAP.md</code>를 열면 <b>현재 큰 그림</b>이 보입니다.
+  </p>
+  <p><strong>한국어</strong> · <a href="README.md">English</a></p>
+</div>
+
+## 무엇인가요?
+
+Scaff는 순수 마크다운 기반의 경량 컨텍스트 스캐폴딩입니다.
+CLI, Hook, MCP 없이 — 마크다운 파일만으로 나와 AI가 지금 무엇을 해야 하는지 바로 알 수 있습니다.
+
+## 무엇을 해결하나요?
+
+**맥락 관리가 맥락보다 무겁다.**
+기존 프레임워크들은 세션 간 맥락 유지를 CLI, Hook, MCP로 해결합니다.
+가벼운 탐색에도 CLI가 실행되고, Hook이 매 동작에 개입하고,
+MCP 서버가 설정되어 있으면, 사용하지 않는 세션에서도 도구 정의만으로 토큰을 소모합니다.
+
+**지금 해야 할 것이 보이지 않는다.**
+현재 목표가 상태 파일, 태스크 리스트, 설계 문서에 흩어져 있습니다.
+파일 하나를 열어서 "지금 할 일"을 바로 확인할 수 없습니다.
+
+Scaff에서는 질문 하나에 파일 하나가 답합니다.
+지금 뭘 해야 하지? → `GOAL.md`. 이 프로젝트가 뭐지? → `CONTEXT.md`. 전체 계획은? → `ROADMAP.md`.
+다른 곳을 뒤지지 않아도 됩니다. 도구 없이, 런타임 없이.
+
+## 빠른 시작
+
+```bash
+npx @opellen/scaff init
+```
+
+프로젝트에 마크다운 커맨드가 설치됩니다. 이후 CLI는 필요 없습니다.
+
+```
+/scaff:scout          # 세션 시작 — 이것만 기억하세요
+```
+
+새 프로젝트든 기존 코드베이스든, scout이 현재 상태를 파악하고 다음 단계를 안내합니다.
+기존 코드가 있다면 맥락 설정(`/scaff:context init`)부터, 빈 프로젝트라면 대화를 통해 방향을 잡는 것부터 시작합니다.
+
+대부분의 커맨드는 첫 사용 시 `init`이 자동 실행됩니다 — `/scaff:goal "목표"` 만으로 `init` 타이핑 없이 바로 동작합니다.
+
+### 옵션
+
+```bash
+scaff init --docs .planning      # docs/ 대신 다른 경로 사용
+scaff init --codebase src        # 코드베이스가 하위 디렉토리에 있을 때 (기본: .)
+scaff init --tools cursor        # 특정 도구용으로 설치
+scaff init --tools cursor,windsurf  # 여러 도구 동시 설치
+scaff init --no-subagent         # 서브에이전트 위임 비활성화 (기본: 활성)
+scaff init --root path/to/proj   # 다른 프로젝트 디렉토리에 설치
+scaff init --force               # 기존 파일 덮어쓰기
+scaff init --dry-run             # 설치할 파일 미리보기
+```
+
+> [!NOTE]
+> `Claude Code`, `Cursor`, `Windsurf` 외 [20여 개 도구](docs/supported-tools.md)를 지원합니다.
+> `Claude Code`에서 검증 완료. 나머지는 어댑터가 준비되어 있지만 실전 테스트 전입니다.
+
+## 문서 구조
+
+```
+docs/
+├── CONTEXT.md       ← 프로젝트 맥락, 원칙, 워크플로우
+├── GOAL.md          ← 현재 목표와 체크리스트
+├── CHECKPOINT.md    ← 마지막 세션 진행 상황
+├── DESIGN.md        ← 구현 설계 (필요 시)
+├── PLAN.md          ← 구현 계획 (복잡한 태스크에서 자동 생성)
+├── ROADMAP.md       ← 마일스톤 단위 전체 계획
+├── OVERVIEW.md      ← 프로젝트 전체 조망 (필요 시)
+└── suspended/       ← 중단된 목표
+```
+
+| 문서 | 질문 | 수명 |
+|------|------|------|
+| `CONTEXT.md` | 이 프로젝트는 뭐고, 어떻게 작업하지? | 프로젝트 전체 |
+| `GOAL.md` | 지금 뭘 해야 하지? | 목표 달성까지 |
+| `CHECKPOINT.md` | 지난 세션에서 어디까지 했지? | 세션 단위 (덮어쓰기) |
+| `DESIGN.md` | 어떻게 구현하지? | 목표 달성까지 |
+| `PLAN.md` | 이 태스크를 어떻게 구현하지? | 자동 생성 → 자동 아카이브 |
+| `ROADMAP.md` | 큰 그림에서 어디에 있지? | 프로젝트 전체 |
+| `OVERVIEW.md` | 이 프로젝트 전체를 한눈에 보면? | 프로젝트 전체 |
+
+`GOAL.md` 하나로 시작해서 `ROADMAP.md`로 확장해도 되고, `ROADMAP.md`에서 큰 그림을 잡고 `GOAL.md`로 내려와도 됩니다. 어느 방향으로 가든 Scaff는 '지금 할 일'을 마크다운 위에 유지합니다.
+
+<details>
+<summary>GOAL.md 예시</summary>
+
+```markdown
+---
+id: session-auth
+goal: 인증을 JWT에서 세션 기반으로 전환
+status: in-progress
+started: 2026-04-04
+---
+
+## Tasks
+
+- [x] 1. 세션 스토어 설정
+- [ ] 2. 미들웨어 교체 — Step 1/2 (세션 미들웨어 구현 중)
+  - [x] 2.1. 세션 미들웨어 구현
+  - [ ] 2.2. 기존 JWT 코드 제거
+- [ ] 3. DB 스키마 마이그레이션
+- [ ] 4. 통합 테스트
+```
+
+</details>
+
+<details>
+<summary>CONTEXT.md 예시</summary>
+
+```markdown
+# Project Overview
+Express + PostgreSQL 기반 REST API 서버.
+인증은 JWT → 세션 전환 진행 중.
+
+# Architecture
+- src/server/ — HTTP 라우팅 (Express)
+- src/auth/ — 인증 미들웨어
+- src/db/ — DB 접근 계층
+
+# Principles
+- 마이그레이션 중 무중단 운영
+- 기존 클라이언트 하위호환
+
+# Resources
+- DB: PostgreSQL 14, 마이그레이션은 prisma
+- 인증: express-session + connect-pg-simple
+```
+
+</details>
+
+<details>
+<summary>ROADMAP.md 예시</summary>
+
+```markdown
+---
+id: api-v2
+title: API v2 마이그레이션
+status: active
+started: 2026-03-01
+---
+
+- [x] **M1: 인증 전환**
+- [ ] **M2: Rate limiting 도입**
+- [ ] **M3: API 버저닝**
+```
+
+</details>
+
+## 커맨드
+
+| 커맨드 | 설명 |
+|--------|------|
+| `/scaff:scout` | 세션 시작 — 문서를 읽고 현재 상태를 파악한 뒤 다음 행동을 제안 |
+| `/scaff:go` | 목표 실행 — `GOAL.md`의 다음 태스크부터 순서대로 진행 |
+| `/scaff:context` | `CONTEXT.md` 생성 및 동기화 |
+| `/scaff:goal` | `GOAL.md` 관리 (init, breakdown, checkpoint, suspend, resume, archive) |
+| `/scaff:design` | `DESIGN.md` 관리 (init, sync, archive) |
+| `/scaff:roadmap` | `ROADMAP.md` 마일스톤 관리 (init, add, archive) |
+| `/scaff:overview` | `OVERVIEW.md` 프로젝트 전체 조망 관리 |
+| `/scaff:verify` | 목표, 설계, 구현의 정합성 검증 |
+| `/scaff:recap` | 세션 마무리 — 논의된 결정을 문서에 반영 |
+
+### 호출 방식
+
+맥락이 명확하면 `/scaff:`를 매번 타이핑하지 않아도 됩니다 — 자연어로도 실행 가능합니다.
+
+| 경로 | `/scaff` 필요? | 예시 |
+|------|---------------|------|
+| **명시적 호출** | 필요 | `/scaff goal init`, `/scaff:goal init & design init` |
+| **직전 제안 확인** | 불필요 | AI: "`/scaff:goal init` 권장" → User: "ok" / "진행해" |
+| **연속 맥락 서술** | 불필요 | (goal init 직후) User: "breakdown now" |
+
+맥락이 명확하면 자연어만으로 실행됩니다. `/scaff`는 맥락이 모호할 때 쓰는 명시적 호출 수단입니다.
+
+## 사용 흐름
+
+### 기존 프로젝트에 적용
+
+```
+You: /scaff:scout
+AI:  코드베이스를 확인했습니다. CONTEXT.md가 없네요.
+     `/scaff:context init`으로 프로젝트 맥락을 설정할까요?
+
+You: /scaff:context init
+AI:  ✓ docs/CONTEXT.md 생성 완료
+     목표를 설정하려면 `/scaff:goal init`
+
+You: /scaff:goal 인증 모듈을 JWT에서 세션 기반으로 전환
+AI:  ✓ docs/GOAL.md 생성 완료 (5개 태스크)
+     `/scaff:design init` 권장 — 파일 수준 결정이 필요한 구현 태스크입니다.
+
+You: /scaff:design init
+AI:  ✓ docs/DESIGN.md 생성 완료
+     세션 스토어 선택, 마이그레이션 전략, 롤백 계획 포함
+
+You: /scaff:go
+AI:  Task 1/5: 세션 스토어 설정... ✓ done
+     Task 2/5: 미들웨어 교체... ✓ done
+     Task 3/5에서 DB 스키마 변경이 필요합니다. 진행할까요?
+```
+
+### 새 프로젝트
+
+```
+You: /scaff:scout 실시간 협업 에디터를 만들기 위한 논의를 시작하자
+AI:  (Discovery Mode — 기술 스택, 요구사항, 제약조건을 대화로 탐색)
+     ...
+     ✓ docs/CONTEXT.md 생성 완료
+
+You: /scaff:roadmap init
+AI:  ✓ docs/ROADMAP.md 생성 완료
+     ├── M1: 코어 에디터 엔진
+     ├── M2: 실시간 동기화 (CRDT)
+     └── M3: 배포 및 인프라
+
+You: /scaff:goal
+AI:  ROADMAP.md에서 M1을 선택합니다.
+     ✓ docs/GOAL.md 생성 완료
+
+You: /scaff:goal breakdown
+AI:  7개 서브태스크로 분해 완료
+
+You: /scaff:goal breakdown 3
+AI:  Task 3을 4개 서브태스크로 분해 완료 (3.1–3.4)
+
+You: /scaff:go
+AI:  Task 1/7: 프로젝트 초기화... ✓ done
+     Task 2/7: 에디터 코어 구현... ✓ done
+     여러 태스크를 완료했습니다. `/scaff:goal checkpoint`로 진행 상황을 저장할까요?
+
+You: /scaff:goal checkpoint
+AI:  ✓ docs/CHECKPOINT.md 저장 완료
+     (세션이 끊겨도 다음 scout에서 이어서 시작합니다)
+
+     ... (다음 세션에서 이어서 작업, 모든 태스크 완료)
+
+You: /scaff:goal archive
+AI:  ✓ docs/archive/goals/2026-04-04-editor-core/에 4개 파일 아카이브
+     (GOAL.md, DESIGN.md, PLAN.md, CHECKPOINT.md)
+     ROADMAP.md에서 M1을 done으로 표시했습니다.
+```
+
+### 이어서 작업
+
+```
+You: /scaff:scout
+AI:  CONTEXT.md ✓ | GOAL.md ✓ (3/5 완료)
+     이전 세션에서 API 엔드포인트 작업 중이었습니다.
+     `/scaff:go`로 이어서 진행할까요?
+```
+
+### 블로커 대응
+
+골 진행 중 먼저 해결해야 할 일이 생겼을 때:
+
+```
+You: (Goal A 진행 중) 이 의존성 버그 먼저 고치자.
+AI:  추천: /scaff:goal suspend + /scaff:goal "의존성 버그 수정"
+You: ok
+AI:  ✓ Goal A를 docs/suspended/goal-a/로 중단 보관
+     ✓ 블로커용 새 GOAL.md 생성
+
+     ... (블로커 작업 → 완료 시 archive)
+
+You: /scaff:goal resume
+AI:  Goal A 복귀. `/scaff:go`로 이어서 진행할까요?
+```
+
+중첩 블로커도 동일 패턴 — suspend가 쌓이고, 여러 골이 중단 중이면 resume이 목록을 보여줍니다.
+
+## **틈새**에서
+
+> **무거운 워크플로우가 항상 필요하지는 않았습니다.**
+>
+> 작은 수정을 하려는 거 뿐인데 이게 다 필요한가라는 의문이 들었습니다.
+> 질문 폭탄을 수반하는 완벽한 논의와 물 샐 틈없는 사양이 항상 필요하지는 않았습니다.
+> 완벽한 절차는 매력적입니다. 하지만 AI는 점점 더 많은 것을 흡수해가고 있고,
+> 어쩌면 우리가 기대고 싶은 그 다양한 안전장치들이 많은 경우에 있어서 과잉적인 족쇄가 될 수도 있겠다고 생각했습니다.
+> 하지만 맥락 유지는 필요했습니다.
+>
+> **현재에 집중하고 싶었습니다.**
+>
+> 사양과 태스크에 묻힌 '현재 목표'를 밖으로 꺼내고 싶었습니다.
+> 나와 AI가 바로 이해하고 집중할 수 있는 '현재'를 만들고 싶었습니다.
+> 작은 것에서 시작해 올라가도, 큰 그림에서 내려와도 —
+> 어느 방향이든 '지금 할 일'이 바로 보이는 구조를 원했습니다.
+>
+> **사이를 채우고 싶었습니다.**
+>
+> 저는 OpenSpec으로 시작해서 Scaff로 건너가기도 하고 그 반대로 하기도 합니다.
+> 때로는 Superpowers를 장착하기도 합니다.
+> 잘 하는 것들은 여전히 잘 활용하면 됩니다.
+> 완전함과 강력함의 앞에, 또는 그 사이에 놓일 수 있는 어떤 무엇이 필요했습니다.
+
+## Notation
+
+Scaff의 커맨드와 스킬은 일반 산문이 아닌, 간결한 마크다운 표기법 — `## Constraints`, `(condition) => action` 디스패치 룰, `for each`, `loop until` — 으로 작성되어 있습니다. 이러한 표기법은 LLM이 절차적 텍스트보다 선언적 규칙을 더 안정적으로 따른다는 연구와 프롬프트 엔지니어링 결과를 바탕으로 설계되었습니다. 그 결과 템플릿은 더 짧고, 토큰을 덜 쓰며, LLM이 규칙을 더 안정적으로 따릅니다.
+
+커맨드나 스킬 템플릿을 수정한다면 먼저 [docs/NOTATION.md](docs/NOTATION.md)를 읽어주세요 — 구문 레퍼런스와 우선순위 규칙이 정리되어 있습니다. 표기법이 왜 이런 형태인지, 어떤 연구 근거가 있는지는 [docs/notation-guide.md](docs/notation-guide.md)를 참고하세요.
+
+## 기여하기
+
+버그 수정, 문서 개선 — PR 환영합니다.
+
+### 개발 환경
+
+```bash
+git clone https://github.com/opellen/scaff.git
+cd scaff
+npm install
+npm run build
+npm test
+```
+
+## 라이선스
+
+MIT 라이선스 — 자세한 내용은 [LICENSE](LICENSE)를 참고하세요.

package/README.md

@@ -0,0 +1,326 @@
+<div align="center">
+  <img src="https://raw.githubusercontent.com/opellen/scaff/master/assets/scaff-logo-wordmark.webp" alt="Scaff Logo" width="180"/>
+  <p><strong>Agile, goal-centric AI harness. Just markdown.</strong></p>
+  <p>The present that you and AI immediately understand — <code>CONTEXT.md</code>, <code>GOAL.md</code>, <code>ROADMAP.md</code></p>
+  <p>
+    Open <code>CONTEXT.md</code> and see <b>the current context</b>.<br/>
+    Open <code>GOAL.md</code> and see <b>what to do now</b>.<br/>
+    Open <code>ROADMAP.md</code> and see <b>the current big picture</b>.
+  </p>
+  <p><strong>English</strong> · <a href="README.ko.md">한국어</a></p>
+</div>
+
+## What is it?
+
+Scaff is a pure markdown-based, lightweight context scaffolding.
+No CLI, no hooks, no MCP — just markdown files that let you and AI instantly know what to do right now.
+
+## What does it solve?
+
+**Context management is heavier than the context itself.**
+Existing frameworks maintain context across sessions with CLIs, hooks, and MCP servers.
+Even light exploration triggers CLI runs, hooks intercept every action,
+and if MCP servers are configured, tool definitions alone consume tokens even in sessions that don't use them.
+
+**What you need to do right now isn't visible.**
+The current goal is scattered across state files, task lists, and design documents.
+You can't just open one file and immediately see "what to do now".
+
+In Scaff, one question maps to one file.
+What should I do now? → `GOAL.md`. What is this project? → `CONTEXT.md`. The overall plan? → `ROADMAP.md`.
+No digging around. No tools, no runtime.
+
+## Quick start
+
+```bash
+npx @opellen/scaff init
+```
+
+Markdown commands are installed in your project. No CLI needed after this.
+
+```
+/scaff:scout          # Start session — just remember this
+```
+
+Whether it's a new project or an existing codebase, scout reads the current state and guides you to the next step.
+Got existing code? It starts with context setup (`/scaff:context`). Empty project? It starts by exploring your idea through conversation.
+
+Most commands auto-run `init` on first use — `/scaff:goal "my goal"` works immediately without typing `init`.
+
+### Options
+
+```bash
+scaff init --docs .planning      # Use a different path instead of docs/
+scaff init --codebase src        # Point templates at a sub-directory codebase (default: .)
+scaff init --tools cursor        # Install for a specific tool
+scaff init --tools cursor,windsurf  # Multiple tools
+scaff init --no-subagent         # Disable subagent delegation (enabled by default)
+scaff init --root path/to/proj   # Install into a different project directory
+scaff init --force               # Overwrite existing files
+scaff init --dry-run             # Preview files to install
+```
+
+> [!NOTE]
+> Scaff works with `Claude Code`, `Cursor`, `Windsurf`, and [20+ other tools](docs/supported-tools.md).
+> Verified with `Claude Code`. Other tools have adapters ready — not yet battle-tested.
+
+## Document structure
+
+```
+docs/
+├── CONTEXT.md       ← Project context, principles, workflow
+├── GOAL.md          ← Current objective and checklist
+├── CHECKPOINT.md    ← Last session progress
+├── DESIGN.md        ← Implementation design (as needed)
+├── PLAN.md          ← Implementation plan (auto-generated for complex tasks)
+├── ROADMAP.md       ← Milestone-based overall plan
+├── OVERVIEW.md      ← Full project overview (as needed)
+└── suspended/       ← Suspended goals
+```
+
+| Document | Question it answers | Lifespan |
+|----------|-------------------|----------|
+| `CONTEXT.md` | What is this project and how do I work on it? | Project lifetime |
+| `GOAL.md` | What should I do right now? | Until goal is achieved |
+| `CHECKPOINT.md` | Where did the last session leave off? | Per session (overwritten) |
+| `DESIGN.md` | How do I implement this? | Until goal is achieved |
+| `PLAN.md` | How do I implement this task? | Auto-generated → auto-archived |
+| `ROADMAP.md` | Where am I in the big picture? | Project lifetime |
+| `OVERVIEW.md` | What does this whole project look like? | Project lifetime |
+
+Start with just `GOAL.md` and expand to `ROADMAP.md`, or lay out the big picture in `ROADMAP.md` and drill down to `GOAL.md`. Either way, Scaff keeps "what to do now" visible on markdown.
+
+<details>
+<summary>GOAL.md example</summary>
+
+```markdown
+---
+id: session-auth
+goal: Migrate auth from JWT to session-based
+status: in-progress
+started: 2026-04-04
+---
+
+## Tasks
+
+- [x] 1. Set up session store
+- [ ] 2. Replace middleware — Step 1/2 (session middleware in progress)
+  - [x] 2.1. Implement session middleware
+  - [ ] 2.2. Remove legacy JWT code
+- [ ] 3. DB schema migration
+- [ ] 4. Integration tests
+```
+
+</details>
+
+<details>
+<summary>CONTEXT.md example</summary>
+
+```markdown
+# Project Overview
+Express + PostgreSQL REST API server.
+Auth migration from JWT to session-based in progress.
+
+# Architecture
+- src/server/ — HTTP routing (Express)
+- src/auth/ — Auth middleware
+- src/db/ — Database access layer
+
+# Principles
+- Zero downtime during migration
+- Backward compatibility with existing clients
+
+# Resources
+- DB: PostgreSQL 14, migrations via prisma
+- Auth: express-session + connect-pg-simple
+```
+
+</details>
+
+<details>
+<summary>ROADMAP.md example</summary>
+
+```markdown
+---
+id: api-v2
+title: API v2 migration
+status: active
+started: 2026-03-01
+---
+
+- [x] **M1: Auth migration**
+- [ ] **M2: Rate limiting**
+- [ ] **M3: API versioning**
+```
+
+</details>
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/scaff:scout` | Start session — read docs, assess current state, suggest next action |
+| `/scaff:go` | Execute goal — proceed through `GOAL.md` tasks in order |
+| `/scaff:context` | Create and sync `CONTEXT.md` |
+| `/scaff:goal` | `GOAL.md` management (init, breakdown, checkpoint, suspend, resume, archive) |
+| `/scaff:design` | `DESIGN.md` management (init, sync, archive) |
+| `/scaff:roadmap` | `ROADMAP.md` milestone management (init, add, archive) |
+| `/scaff:overview` | `OVERVIEW.md` full project overview |
+| `/scaff:verify` | Verify consistency across goal, design, and implementation |
+| `/scaff:recap` | Session wrap-up — sync decisions into living documents |
+
+### Invocation
+
+You don't always need to type `/scaff:` — when intent is clear from context, natural language works too.
+
+| Path | `/scaff` required? | Example |
+|------|-------------------|---------|
+| **Explicit invocation** | Yes | `/scaff goal init`, `/scaff:goal init & design init` |
+| **Confirming a recent recommendation** | No | AI: "Recommend `/scaff:goal init`" → User: "ok" / "go" |
+| **Continuation in active flow** | No | (after goal init) User: "breakdown now" |
+
+With clear context, natural language alone triggers execution. `/scaff` serves as an escape hatch when context is ambiguous.
+
+## Usage flow
+
+### Applying to an existing project
+
+```
+You: /scaff:scout
+AI:  Found an existing codebase. No CONTEXT.md yet.
+     Set up project context with `/scaff:context`?
+
+You: /scaff:context init
+AI:  ✓ docs/CONTEXT.md created
+     To set a goal: `/scaff:goal init`
+
+You: /scaff:goal Migrate auth module from JWT to session-based
+AI:  ✓ docs/GOAL.md created (5 tasks)
+     Recommend `/scaff:design init` — implementation task with file-level decisions.
+
+You: /scaff:design init
+AI:  ✓ docs/DESIGN.md created
+     Session store selection, migration strategy, rollback plan included
+
+You: /scaff:go
+AI:  Task 1/5: Set up session store... ✓ done
+     Task 2/5: Replace middleware... ✓ done
+     Task 3/5 requires DB schema changes. Proceed?
+```
+
+### New project
+
+```
+You: /scaff:scout Let's discuss building a real-time collaborative editor
+AI:  (Discovery Mode — exploring tech stack, requirements, constraints)
+     ...
+     ✓ docs/CONTEXT.md created
+
+You: /scaff:roadmap init
+AI:  ✓ docs/ROADMAP.md created
+     ├── M1: Core editor engine
+     ├── M2: Real-time sync (CRDT)
+     └── M3: Deployment & infrastructure
+
+You: /scaff:goal
+AI:  Selecting M1 from ROADMAP.md.
+     ✓ docs/GOAL.md created
+
+You: /scaff:goal breakdown
+AI:  Decomposed into 7 subtasks
+
+You: /scaff:goal breakdown 3
+AI:  Decomposed Task 3 into 4 subtasks (3.1–3.4)
+
+You: /scaff:go
+AI:  Task 1/7: Project initialization... ✓ done
+     Task 2/7: Editor core implementation... ✓ done
+     Several tasks completed. Save progress with `/scaff:goal checkpoint`?
+
+You: /scaff:goal checkpoint
+AI:  ✓ docs/CHECKPOINT.md saved
+     (If the session drops, the next scout picks up where you left off)
+
+     ... (continue in next session, all tasks complete)
+
+You: /scaff:goal archive
+AI:  ✓ Archived 4 files to docs/archive/goals/2026-04-04-editor-core/
+     (GOAL.md, DESIGN.md, PLAN.md, CHECKPOINT.md)
+     Marked M1 done in ROADMAP.md.
+```
+
+### Resuming work
+
+```
+You: /scaff:scout
+AI:  CONTEXT.md ✓ | GOAL.md ✓ (3/5 complete)
+     You were working on API endpoints in the previous session.
+     Resume with `/scaff:go`?
+```
+
+### Handling blockers
+
+When something comes up mid-goal that must be fixed first:
+
+```
+You: (during Goal A) Let's fix this dependency bug first.
+AI:  Suggest: /scaff:goal suspend + /scaff:goal "Fix dependency bug"
+You: ok
+AI:  ✓ Goal A suspended to docs/suspended/goal-a/
+     ✓ New GOAL.md created for the blocker.
+
+     ... (work through the blocker, archive when done)
+
+You: /scaff:goal resume
+AI:  Resumed: Goal A. Continue with /scaff:go?
+```
+
+Nested blockers follow the same pattern — suspend stacks, resume presents a list when multiple goals are paused.
+
+## From the **gap**
+
+> **Heavy workflows weren't always necessary.**
+>
+> All I wanted was a small fix — did I really need all this?
+> Exhaustive discussions with question bombardment and airtight specifications weren't always necessary.
+> Thorough processes are appealing. But AI kept absorbing more and more,
+> and I started to think that maybe the safety nets we want to lean on were, in many cases, becoming excessive shackles.
+> Yet context needed to persist.
+>
+> **I wanted to focus on the present.**
+>
+> I wanted to pull the "current goal" out from under specs and task lists.
+> I wanted to create a "present" that both I and AI could immediately understand and focus on.
+> Whether you grow from small to large, or descend from the big picture —
+> either direction, I wanted a structure where "what to do now" is immediately visible.
+>
+> **I wanted to fill the gap.**
+>
+> I sometimes start with OpenSpec and cross over to Scaff, and vice versa.
+> Sometimes I equip Superpowers.
+> What works well should still be used well.
+> I needed something that could sit in front of — or between — completeness and power.
+
+## Notation
+
+Scaff's commands and skills aren't written as plain prose. They follow a small markdown notation — `## Constraints`, `(condition) => action` dispatch rules, `for each`, `loop until` — designed from research and prompt-engineering findings on how LLMs reliably follow declarative rules over procedural text. The result: shorter templates, fewer tokens, and more reliable rule-following from the LLM.
+
+If you're modifying a command or skill template, read [docs/NOTATION.md](docs/NOTATION.md) first — it's the reference for the syntax and priority rules. For the rationale and research background behind the notation, see [docs/notation-guide.md](docs/notation-guide.md).
+
+## Contributing
+
+Bug fixes, documentation improvements — PRs welcome.
+
+### Development
+
+```bash
+git clone https://github.com/opellen/scaff.git
+cd scaff
+npm install
+npm run build
+npm test
+```
+
+## License
+
+MIT License — see [LICENSE](LICENSE) for details.

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};