@kodevibe/harness 0.8.3

package/harness/skills/bootstrap.md

@@ -0,0 +1,326 @@
+# Bootstrap
+
+## Purpose
+
+Onboard a new or existing project into Musher by filling **state files AND rules files** automatically.
+Solves the cold-start problem: users don't know which `.md` files to fill or how.
+One command does everything — no manual editing required.
+
+## When to Apply
+
+- Right after running `musher init` on a new project
+- When joining an existing project that has empty state files
+- When state files are outdated and need a refresh
+- When any agent reports "state files are empty"
+
+## Procedure
+
+### Phase 1: Project Discovery (read-only)
+
+1. **Scan project root** for configuration files:
+   - `package.json`, `tsconfig.json` → Node.js/TypeScript
+   - `go.mod`, `go.sum` → Go
+   - `requirements.txt`, `pyproject.toml`, `setup.py` → Python
+   - `pom.xml`, `build.gradle` → Java
+   - `Cargo.toml` → Rust
+   - `Gemfile` → Ruby
+2. **Scan directory structure**: List top-level directories and identify patterns
+   - `src/`, `lib/`, `app/` → source code
+   - `tests/`, `test/`, `__tests__/`, `spec/` → test directories
+   - `docs/` → documentation
+3. **Framework Coexistence Check** (경량 — 1회 list_dir만 사용):
+   프로젝트 루트 `list_dir` 결과에서 아래 패턴과 매칭하여 존재 목록만 생성한다.
+   **⚠️ 내부 파일 스캔 금지** — 디렉토리 안의 파일을 읽거나 나열하지 않는다.
+
+   | 패턴 | 프레임워크 |
+   |------|:-----------|
+   | `.bmad-core/` | BMAD-METHOD |
+   | `.claude/` | Claude Code |
+   | `.cursor/` | Cursor |
+   | `.windsurf/` | Windsurf |
+   | `.gemini/` | Gemini |
+   | `.clinerules/` or `.cline/` | Cline |
+   | `.github/chatmodes/` | GitHub Chatmodes |
+   | `AGENTS.md` | Codex / OpenAI |
+   | `opencode.jsonc` | OpenCode |
+
+   > `.github/chatmodes/`는 `.github/` 하위이므로, `.github/` 존재 시 1회 추가 list_dir 허용.
+   > 감지된 프레임워크는 State file에 "공존 프레임워크: [목록]"으로 기록한다.
+
+4. **Scan for existing tests**: Find test files and map them to source modules
+5. **Scan imports/dependencies**: Trace module relationships from import statements
+
+**Do NOT modify any code files in this phase.**
+
+<!-- CREW_MODE_START -->
+### Phase 1.5: Crew Artifact Detection + Indexing
+
+Check if external planning artifacts exist:
+- `docs/crew/` directory — kode:crew output (requirements, analysis, design docs)
+- `docs/PM/`, `docs/Analyst/`, `docs/ARB/` directories — kode:crew role-based output
+- User-provided documents — requirements specs, wireframes, API designs
+- User mentions "산출물", "PRD", "요구사항", "설계서" in their prompt
+
+**If crew artifacts are found:**
+
+1. **Catalog all documents** with path, estimated role (Analyst/PM/ARB/unknown), and key contents
+2. **Check existing state**: If `docs/project-brief.md` already has a `## Crew Artifact Index` section with content:
+   - Ask user: "⚠️ 기존 crew 산출물이 이미 인덱싱되어 있습니다. 재인덱싱하겠습니까?" (user confirms or skips)
+   - If project-brief is empty (first crew sync) → proceed with full indexing
+3. **Lazy Read Protocol로 산출물 읽기** (⚠️ 전문 읽기 금지):
+
+   **Step A: 구조 스캔 (첫 50줄)**
+   - 각 산출물의 **첫 50줄만** 읽는다 (목차, 헤더, Executive Summary)
+   - 이 50줄에서 추출: 프로젝트 비전, 목표, 비목표, 기술 스택, FR/KPI/ARB 목록 존재 여부
+   - 문서 구조를 파악한다 (어떤 섹션이 몇 번째 줄에 있는지)
+   - 첫 50줄에 목차가 없으면 60줄까지 확장 허용
+
+   **Step B: 선택적 상세 읽기**
+   - State file 작성에 필요한 섹션만 추가로 읽는다:
+     - PRD → "Functional Requirements", "KPI", "Non-Functional Requirements" 섹션
+     - Architecture → "Tech Stack", "Module 구조" 섹션
+     - ARB Checklist → "Fail Items" 섹션만 (Pass 항목은 불필요)
+     - Product Brief → "Vision" + "Persona" 섹션
+   - **읽지 않는 섹션**: 배경, 시장 분석, 상세 설명, 참고 자료 등
+
+   > 효과: PRD 336줄 → ~130줄 (61% 감소), 4개 산출물 총합 885줄 → ~350줄 (60% 감소)
+
+4. **Create Artifact Index** in `docs/project-brief.md`:
+   - Add `## Crew Artifact Index` table with: Artifact name, Path, Role, key contents summary (one line each)
+5. **Extract Minimum** for quick reference (these go into the standard sections of project-brief.md):
+   - Vision: 1-2 sentences from product-brief
+   - Goals: KPI list from product-brief (measurable items only, not full descriptions)
+   - Non-Goals: Out-of-scope list from PRD or product-brief
+   - Key Technical Decisions: tech stack from architecture doc
+6. **Build Validation Tracker** in `docs/project-brief.md`:
+   - `### KPI Coverage`: extract KPI items from product-brief → create table with ID, KPI, Source, Story (empty), Status (⬜)
+   - `### ARB Fail Resolution`: extract Fail items from arb-checklist → create table with ID, Item, Severity (CRITICAL/HIGH), Story (empty), Status (⬜ Required)
+   - `### FR Coverage`: extract FR-NNN items from PRD → create table with FR, Description, Priority (P0/P1/P2), Stories (empty), Status (⬜)
+7. **Confirm with user**: "Crew 산출물 [N]개를 발견했습니다. Artifact Index와 Validation Tracker를 생성합니다. 맞나요?"
+   - If user says **yes** → proceed with Phase 3 using crew artifact data
+   - If user says **no** → skip Artifact Index/Tracker creation, proceed with regular Phase 2 interview (treat as 🟢 pipeline)
+8. **Skip most Phase 2 questions** — use artifact data instead. Only confirm implementation-specific decisions (test framework, specific library choices).
+9. Proceed to Phase 3 using extracted data
+
+**Original crew documents are NEVER modified. Only the index and tracker are created.**
+
+**Crew Artifact Path Detection** (bootstrap detects all patterns, priority order):
+1. Pattern C: User-provided paths (explicit in prompt) — highest priority, always authoritative
+2. Pattern B: `docs/crew/` (consolidated directory)
+3. Pattern A: `docs/PM/`, `docs/Analyst/`, `docs/ARB/` (kode:crew role-based directories)
+4. Pattern D: `docs/` files containing `prd`, `product-brief`, `architecture`, `checklist` keywords — lowest priority, fallback scan
+- If multiple patterns match, use the highest priority source. Artifact Index records the actual discovered paths.
+
+**If no crew artifacts:** Continue to Phase 2 (User Interview) normally.
+<!-- CREW_MODE_END -->
+
+### Phase 2: User Interview (interactive)
+
+Ask the user these questions (skip any already answered by Phase 1):
+
+1. "What does this project do? (one sentence)"
+2. "What are the top 3 goals of this project?"
+3. "What is explicitly OUT of scope? (non-goals)"
+4. "What architecture pattern are you using?" (show detected pattern if found)
+5. "Are there any type decisions or conventions the AI should know about?"
+6. "What is your test command?" (show detected command if found, e.g., `npm test`, `pytest`, `go test ./...`)
+
+### Phase 3: Fill State Files
+
+Using data from Phase 1 + Phase 2, fill the following files:
+
+**docs/project-brief.md**:
+- Project Name → from package.json name, go.mod module, or user input
+- Vision → from user answer #1
+- Goals → from user answer #2
+- Non-Goals → from user answer #3
+<!-- CREW_MODE_START -->
+- Crew Artifact Index → from Phase 1.5 (🟣 pipeline only — leave as template comment for 🟢 pipeline)
+- Validation Tracker → from Phase 1.5 (🟣 pipeline only — leave as template comment for 🟢 pipeline)
+<!-- CREW_MODE_END -->
+- Key Technical Decisions → from Phase 1 scan + user answer #4, #5
+
+**docs/features.md**:
+- Add one row per detected module/feature area
+- Status: `✅ done` for modules with passing tests, `🔧 active` for modules without tests
+- Key Files: actual file paths from scan
+- Test Files: actual test file paths from scan
+
+**docs/dependency-map.md**:
+- Add one row per module
+- Layer: inferred from directory structure (domain/application/infrastructure/presentation)
+- Depends On / Depended By: inferred from import scan
+
+**docs/project-state.md**:
+- Quick Summary: filled with current project state
+- Sprint 1 stories: based on what bootstrap discovered
+- Module Registry: summary from docs/dependency-map.md
+
+**docs/failure-patterns.md**:
+- Keep FP-001 through FP-004 as templates (Frequency: 0)
+- No changes unless user reports known issues
+
+### Phase 3.5: Project Brief Auto-Configuration
+
+Using language/framework detected in Phase 1 + user answers from Phase 2, enrich `docs/project-brief.md`:
+
+1. **Fill Key Technical Decisions** with detected tech stack:
+   - Language, framework, database (from Phase 1)
+   - Architecture pattern (from user answer #4)
+   - Type conventions (from user answer #5)
+   - Test command and mock location (from user answer #6)
+
+2. **Ask about coding conventions** for the detected language:
+   - "Any coding style conventions the AI should follow for [detected language]?" (e.g., enum vs union types, Pydantic vs dataclass, etc.)
+   - If the user provides conventions → write them to Key Technical Decisions
+   - If the user skips → do not inject any defaults
+
+### Phase 4: Verify
+
+1. Present a summary of all filled state files to the user
+2. Ask "Does this look correct? What should I change?"
+3. Apply corrections if any
+4. Report completion
+
+<!-- TEAM_MODE_START -->
+## Team Mode: File Locations
+
+In Team mode, state files are split between shared and personal directories:
+
+### Shared (docs/, git committed)
+- `docs/project-brief.md` — project vision, goals, non-goals
+- `docs/features.md` — feature registry
+- `docs/dependency-map.md` — module dependency graph
+
+### Personal (.harness/, gitignored)
+- `.harness/project-state.md` — current sprint/story progress
+- `.harness/failure-patterns.md` — personal failure patterns
+- `.harness/agent-memory/` — agent memory files
+
+When filling state files in Phase 3, write to the correct directories based on this split.
+After bootstrap completes, remind the user that shared files require `git pull` before editing (Pre-Pull Protocol).
+<!-- TEAM_MODE_END -->
+
+## Output Format
+
+```
+## Bootstrap Complete
+
+### Project: [name]
+### Tech Stack: [detected stack]
+### Language: [detected language]
+### Modules Found: [count]
+### Features Mapped: [count]
+### Dependency Links: [count]
+
+### State Files Updated:
+- [x]docs/project-brief.md — [summary]
+- [x]docs/features.md — [N] features registered
+- [x]docs/dependency-map.md — [N] modules, [N] dependencies
+- [x]docs/project-state.md — Sprint 1 initialized
+- [ ]docs/failure-patterns.md — templates only (no changes)
+
+STATUS: DONE
+```
+
+### 🧭 Navigation — After Bootstrap
+
+Bootstrap always leads to `planner`. Append this block after STATUS: DONE:
+
+**If NO crew artifacts** (🟢 pipeline):
+```
+---
+🧭 Next Step
+→ Next: `planner` (슬래시 메뉴에서 선택하거나, 채팅에 아래 프롬프트 입력)
+→ Prompt: "[project]에 [첫 번째 기능]을 추가해줘"
+→ Why: State files are filled — now plan the first feature
+→ Pipeline: 🟢 Step 2/6
+---
+```
+
+<!-- CREW_MODE_START -->
+**If crew artifacts were used** (🟣 pipeline):
+```
+---
+🧭 Next Step
+→ Next: `planner` (슬래시 메뉴에서 선택하거나, 채팅에 아래 프롬프트 입력)
+→ Prompt: "crew 산출물을 기반으로 첫 번째 기능을 계획해줘"
+→ Why: Artifact Index + Validation Tracker created — planner will map FR→Stories
+→ Pipeline: 🟣 Step 2/6
+---
+```
+<!-- CREW_MODE_END -->
+
+## Rules
+
+- Never modify source code — this skill only writes to state files and rules files
+- Always show the user what was discovered BEFORE writing files
+- If the project has 0 source files, skip Phase 1 scan and go straight to Phase 2
+- If a state file already has content, ask before overwriting
+- Rules file TODO sections can be overwritten without asking (they are placeholders)
+- Run this skill only once per project (or when explicitly requested for refresh)
+
+### Small Project Guidance
+
+For projects with fewer than 3 modules (e.g., single-file scripts, small CLI tools):
+- `docs/dependency-map.md` may have only 1-2 rows — this is normal, not a gap
+- `feature-breakdown` Waves may collapse into a single Wave — skip Wave-level pacing
+- Consider a simplified workflow: `bootstrap → planner → [code] → reviewer → learn` (skip sprint-manager for single-story projects)
+
+## Embedded Knowledge
+
+### Session Bootstrap Protocol
+When starting a NEW session (not during bootstrap), read these files in order:
+1. `docs/project-state.md` — Quick Summary tells you where we left off
+2. `docs/features.md` — What features exist
+3. `docs/failure-patterns.md` — What mistakes to avoid
+4. `docs/project-brief.md` — Project vision and non-goals
+
+### Workflow Pipeline
+- New feature: `planner → [code] → reviewer → sprint-manager → learn`
+- Bug fix: `investigate → [fix] → test-integrity → reviewer → learn`
+- Session lifecycle: `sprint-manager ("where are we?") → [work] → learn`
+
+### State File Size Limits
+- docs/project-brief.md: Max 200 lines
+- docs/project-state.md: Max 300 lines
+- docs/failure-patterns.md: Max 50 patterns
+- docs/dependency-map.md: Max 100 modules
+- docs/features.md: Max 50 features
+- docs/agent-memory/*.md: Max 100 lines each
+
+## Anti-patterns
+
+| Anti-pattern | Correct Approach |
+|---|---|
+| Guess module boundaries | Scan actual directory structure and imports |
+| Skip user interview | Phase 1 scan alone is insufficient — always confirm with user |
+| Overwrite existing state files silently | Ask before overwriting non-empty files |
+| Create perfect dependency map on first try | Start with what's detectable, refine over time |
+| Leave rules file TODOs unfilled | Phase 3.5 fills Key Technical Decisions TODOs. Decision Log remains empty (filled later via `pivot` skill during project lifecycle) |
+| Use TypeScript globs for non-TS projects | Detect language in Phase 1 and set correct globs |
+| Only fill state files, skip rules | Bootstrap fills BOTH — state files AND rules files |
+
+<!-- TEAM_MODE_START -->
+## Team Mode: Onboarding
+
+When running bootstrap in Team mode:
+
+### New Project (first developer)
+1. Run `musher init --team` to create shared + personal state files
+2. Fill all state files via normal bootstrap procedure
+3. Commit shared files (docs/) to git
+4. Push to remote — teammates will clone this
+
+### Joining Developer (existing project)
+1. Clone the repository (shared docs/ already exist)
+2. Run `musher init --team` — only personal files (.harness/) are created; shared files are skipped
+3. **DO NOT re-run bootstrap interviews** — shared state is already filled by the first developer
+4. Review docs/project-brief.md to understand project goals
+5. Create your personal .harness/project-state.md with your current Story assignment
+
+### Rules
+- **Never overwrite shared files** when joining an existing project
+- Set your Owner name in docs/features.md and docs/dependency-map.md rows you create
+- Personal state (.harness/) is yours alone — no coordination needed
+<!-- TEAM_MODE_END -->

package/harness/skills/code-review-pr.md

@@ -0,0 +1,141 @@
+# Code Review PR
+
+## Purpose
+
+Review an external Pull Request (PR) for quality, security, and direction alignment before merging.
+Unlike the `reviewer` agent (which reviews your own changes pre-commit with full project context), this skill is for reviewing incoming PRs from teammates or external contributors. code-review-pr is a cold review — stricter on state file compliance because the reviewer has less context about the PR author's intent.
+
+## Invoked By
+
+- **User** (direct) — when assigned as a PR reviewer or asked to review a branch
+- Unlike `reviewer` agent (self-review before commit), this skill is for reviewing **incoming external PRs**
+
+## When to Apply
+
+- When assigned as a PR reviewer
+- When a teammate asks for a review of their branch
+- When reviewing open-source contributions
+
+## Procedure
+
+### Step 1: Gather PR Context
+
+1. Read the PR title, description, and linked issues
+2. Run `git diff <base>...<branch>` (use the PR's base branch, per project-brief.md; default: main) to see all changes
+3. Run `git log --oneline <base>...<branch>` to understand commit history
+4. Count files changed: `git diff --stat <base>...<branch>`
+
+### Step 2: Direction Alignment
+
+1. Read `docs/project-brief.md` — Goals, Non-Goals, Decision Log
+2. Check: Does this PR serve a listed Goal?
+3. Check: Does this PR contradict a Non-Goal or Decision Log entry?
+4. If misaligned → comment on the PR with the concern before proceeding
+
+### Step 3: Scope Check
+
+1. Read `docs/project-state.md` — current Sprint and Stories
+2. Verify the PR changes only files within its stated scope
+3. Flag any out-of-scope modifications
+
+### Step 4: Code Quality
+
+Run through these checks for each changed file:
+
+- [ ] Architecture rules respected (no layer violations — check docs/dependency-map.md)
+- [ ] No hardcoded credentials or API keys
+- [ ] No `TODO` or `FIXME` without a linked issue
+- [ ] Error handling is present where needed
+- [ ] No overly complex functions (single responsibility)
+- [ ] No duplicated logic that should be extracted to a shared module
+- [ ] No circular imports (verify against docs/dependency-map.md)
+- [ ] Naming conventions follow project standards (per project-brief.md → Key Technical Decisions)
+
+### Step 5: Test Coverage
+
+- [ ] New features have corresponding tests
+- [ ] Modified code has updated tests
+- [ ] No `.only` or `.skip` left in test files
+- [ ] Interface changes have synchronized mocks (Iron Law #1)
+
+### Step 6: State File Compliance
+
+- [ ] New features registered in `docs/features.md` (Iron Law #7). If the PR is partial (only one layer of a feature), registration is optional — but must be registered when the feature-completing PR is merged.
+- [ ] New modules registered in `docs/dependency-map.md` (Iron Law #6)
+- [ ] `docs/project-state.md` Story Status updated
+
+### Step 7: Failure Pattern Cross-Check
+
+1. Read `docs/failure-patterns.md`
+2. Check if any active FP-NNN pattern applies to the PR changes
+3. If match found → comment with the pattern ID and prevention guidance
+
+## Output Format
+
+```
+## PR Review: [PR title]
+
+### Direction: ✅ Aligned / ⚠️ Concern / ❌ Misaligned
+[details if not aligned]
+
+### Scope: ✅ Clean / ⚠️ Out-of-scope changes found
+[list of out-of-scope files if any]
+
+### Code Quality: [N] issues found
+- [issue 1]
+- [issue 2]
+
+### Test Coverage: ✅ Sufficient / ⚠️ Gaps found
+[list of gaps if any]
+
+### State Files: ✅ Updated / ⚠️ Missing updates
+[list of missing updates if any]
+
+### Failure Patterns: [N] matches
+- FP-NNN: [description]
+
+### Verdict: APPROVE / REQUEST_CHANGES / COMMENT
+[summary recommendation]
+```
+
+### 🧭 Navigation — After PR Review
+
+After PR review completes, always append a 🧭 block:
+
+| PR Review Result | 🧭 Next Step |
+|---|---|
+| APPROVE | Merge & `deployment` — "리리즈 준비를 확인해줘" |
+| REQUEST_CHANGES | [Fix] — "PR 지적사항을 수정하세요. 완료 후 다시 `code-review-pr` 호출" |
+| Direction misaligned | `pivot` — "방향을 전환하고 state 파일을 업데이트해줘" |
+
+Example 🧭 block for APPROVE:
+```
+---
+🧭 Next Step
+→ Next: `deployment`
+→ Prompt: "리리즈 준비를 확인해줘"
+→ Why: PR approved — validate deployment readiness
+→ Pipeline: 🟢/🔵 Step 5/6
+---
+```
+
+## Rules
+
+- Do not modify the PR code directly — only review and comment
+- Always check direction alignment FIRST — a well-written PR that goes the wrong direction is worse than a messy one that's aligned
+- Be specific: reference file names, line numbers, and function names
+- Suggest fixes, don't just point out problems
+
+<!-- TEAM_MODE_START -->
+## Team Mode: Cross-Team PR Review
+
+### Owner-Aware Review
+1. Check `docs/dependency-map.md` Owner column for each file in the PR
+2. If the PR modifies modules owned by someone else → flag for that owner's review
+3. Only the module Owner (or designated authority per project-brief.md; default: team lead) can approve changes to their modules
+
+### Shared State Verification
+- Verify the PR updates `docs/features.md` Owner column correctly
+- Verify new modules in `docs/dependency-map.md` have an Owner assigned
+- Check that the PR doesn't modify another developer's personal failure patterns
+<!-- TEAM_MODE_END -->

package/harness/skills/deployment.md

@@ -0,0 +1,144 @@
+# Deployment
+
+## Purpose
+
+Pre-deployment validation checklist. Ensures all quality gates pass and state files are consistent before releasing or deploying.
+
+## When to Apply
+
+- Before deploying to staging or production
+- Before publishing a new npm/package version
+- Before creating a release tag
+- When the user says "ready to deploy" or "prepare release"
+
+## Procedure
+
+### Step 1: Version Check
+
+1. Read `package.json` (or equivalent manifest) — note current version
+2. Verify the version was bumped appropriately (Semantic Versioning):
+   - Bug fix → patch (0.0.x) — e.g., `v1.2.3 → v1.2.4`
+   - New feature (backward-compatible) → minor (0.x.0) — e.g., `v1.2.3 → v1.3.0`
+   - Breaking change → major (x.0.0) — e.g., `v1.2.3 → v2.0.0`
+   - If unsure, ask the designated authority (per project-brief.md)
+3. If version was not bumped → **warn and recommend bumping before deploy**
+
+### Step 2: Test Suite
+
+1. Run the project's test command (per project-brief.md → Key Technical Decisions; e.g., `npm test`, `pytest`, `go test ./...`)
+2. **All tests must pass.** If any fail → **BLOCKED, do not proceed**
+3. Report: total tests, passed, failed
+
+### Step 3: State File Consistency
+
+Verify all state files are up to date:
+
+- [ ] `docs/project-state.md` — Quick Summary reflects current state
+- [ ] `docs/features.md` — All implemented features marked as `✅ done`
+- [ ] `docs/dependency-map.md` — No orphaned modules
+- [ ] `docs/failure-patterns.md` — No unresolved critical patterns
+- [ ] `docs/project-brief.md` — Decision Log has entries for all major changes
+- [ ] **Cross-check features ↔ stories**: All `done` stories should have their features marked `✅ done` in features.md
+
+<!-- CREW_MODE_START -->
+- [ ] **Validation Tracker FR Coverage**: All Functional Requirements (FR) have at least one mapped Story (`docs/project-brief.md` → Validation Tracker)
+- [ ] **Validation Tracker ARB Fail Resolution**: All ARB Fail items resolved (✅) or explicitly deferred with rationale
+- [ ] **KPI Coverage**: All KPIs addressed or deferred with documented reason
+<!-- CREW_MODE_END -->
+
+### Step 4: Security Scan
+
+1. Run the `security-checklist` skill
+2. Verify no credentials, API keys, or `.env` files are staged
+3. Check for known vulnerable dependencies (if applicable)
+
+### Step 5: Git Status
+
+1. `git status` — working directory should be clean
+2. `git stash list` — verify no unintended stashes exist (if stashes are present, confirm they are intentional)
+3. `git log --oneline -5` — verify recent commits are meaningful
+3. Verify current branch is appropriate for deployment (the default branch or a release branch, per project-brief.md)
+
+### Step 6: Changelog / Release Notes
+
+1. Check if CHANGELOG.md or release notes exist
+2. If yes → verify they include entries for all changes since last release
+3. If no → generate a summary from `git log --oneline <last-tag>..HEAD`
+
+## Output Format
+
+```
+## Deployment Readiness: [project-name] v[version]
+
+### Pre-flight Checks:
+- [x/✗] Version bumped: [version]
+- [x/✗] Tests: [passed]/[total] passed
+- [x/✗] State files consistent
+- [x/✗] Security scan clean
+- [x/✗] Git status clean
+- [x/✗] Release notes prepared
+
+### Verdict: READY / NOT_READY
+[blockers if not ready]
+
+### Deploy Command:
+[Suggest based on project type detected in project-brief.md Key Technical Decisions:
+  npm: npm publish / npx changeset publish
+  Docker: docker build + docker push
+  GitHub: gh release create vX.Y.Z
+  Cloud: terraform apply / aws deploy]
+```
+
+### 🧭 Navigation — After Deployment Check
+
+After deployment validation completes, always append a 🧭 block:
+
+| Deployment Result | 🧭 Next Step |
+|---|---|
+| READY | [Deploy] — "배포 명령을 실행하세요" |
+| NOT_READY (test failure) | [Fix] — "테스트 실패를 수정해줘. 완료 후 다시 `deployment` 호출" |
+| NOT_READY (state files) | `learn` — "state 파일을 정리해줘" |
+| NOT_READY (security) | `security-checklist` — "보안 이슈를 해결해줘" |
+
+Example 🧭 block for READY:
+```
+---
+🧭 Next Step
+→ Next: [Deploy]
+→ Prompt: "배포 명령을 실행하세요"
+→ Why: All checks passed — safe to deploy
+→ Pipeline: 🟢/🔵 Step 5/6 → deploy
+---
+```
+
+## Rollback Procedure
+
+If a deployment fails or a critical issue is found post-deploy:
+
+1. **Immediate**: Revert to the last known-good version
+   - npm: `npm unpublish <pkg>@<bad-version>` (within 72h) or publish a patch fix
+   - Docker: `docker tag <image>:<previous-tag> <image>:latest && docker push`
+   - GitHub: `gh release delete vX.Y.Z` + `git tag -d vX.Y.Z && git push --delete origin vX.Y.Z`
+2. **Record**: Add entry to `docs/failure-patterns.md` with deployment failure details
+3. **Re-validate**: Run `deployment` skill again on the rollback commit to confirm stability
+4. **Post-mortem**: Run `learn` skill to capture the incident for future sessions
+
+## Rules
+
+- Never deploy with failing tests — no exceptions
+- Never deploy with unstaged changes in the working directory
+- Always verify version bump before deployment
+- This skill is read-only — it validates but does not execute the deployment
+
+<!-- TEAM_MODE_START -->
+## Team Mode: Pre-Deploy Coordination
+
+### Shared State Sync
+1. Run `git pull` on the default branch before starting deploy validation (per project-brief.md → Key Technical Decisions; default: main)
+2. Verify `docs/features.md` and `docs/dependency-map.md` are up to date with latest changes from all developers
+3. Check that no other developer has in-progress stories that depend on the current release
+
+### Owner Verification
+- Verify all modified modules have their Owner's approval
+- If deploying changes to modules owned by others, confirm they have reviewed and approved
+<!-- TEAM_MODE_END -->