@lbruton/specflow 3.0.0

package/README.ko.md

@@ -0,0 +1,314 @@
+# Spec Workflow MCP
+
+[![npm version](https://img.shields.io/npm/v/@pimzino/spec-workflow-mcp)](https://www.npmjs.com/package/@pimzino/spec-workflow-mcp)
+[![VSCode Extension](https://vsmarketplacebadges.dev/version-short/Pimzino.spec-workflow-mcp.svg)](https://marketplace.visualstudio.com/items?itemName=Pimzino.spec-workflow-mcp)
+
+실시간 대시보드와 VSCode 확장 프로그램을 갖춘 구조화된 스펙 기반 개발을 위한 Model Context Protocol(MCP) 서버입니다.
+
+## ☕ 이 프로젝트 후원하기
+
+<a href="https://buymeacoffee.com/Pimzino" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" style="height: 60px !important;width: 217px !important;" ></a>
+
+## 📺 쇼케이스
+
+### 🔄 승인 시스템 작동 영상
+<a href="https://www.youtube.com/watch?v=C-uEa3mfxd0" target="_blank">
+  <img src="https://img.youtube.com/vi/C-uEa3mfxd0/maxresdefault.jpg" alt="Approval System Demo" width="600">
+</a>
+
+*승인 시스템 작동 방식 확인: 문서 생성, 대시보드를 통한 승인 요청, 피드백 제공, 수정사항 추적.*
+
+### 📊 대시보드 및 스펙 관리
+<a href="https://www.youtube.com/watch?v=g9qfvjLUWf8" target="_blank">
+  <img src="https://img.youtube.com/vi/g9qfvjLUWf8/maxresdefault.jpg" alt="Dashboard Demo" width="600">
+</a>
+
+*실시간 대시보드 탐색: 스펙 보기, 진행 상황 추적, 문서 탐색, 개발 워크플로우 모니터링.*
+
+## ✨ 주요 기능
+
+- **구조화된 개발 워크플로우** - 순차적 스펙 생성 (요구사항 → 설계 → 작업)
+- **실시간 웹 대시보드** - 실시간 업데이트로 스펙, 작업 및 진행 상황 모니터링
+- **VSCode 확장 프로그램** - VSCode 사용자를 위한 통합 사이드바 대시보드
+- **승인 워크플로우** - 수정사항이 포함된 완전한 승인 프로세스
+- **작업 진행 추적** - 시각적 진행률 표시줄 및 상세 상태
+- **구현 로그** - 코드 통계가 포함된 모든 작업 구현의 검색 가능한 로그
+- **다국어 지원** - 11개 언어로 제공
+
+## 🌍 지원 언어
+
+🇺🇸 English • 🇯🇵 日本語 • 🇨🇳 中文 • 🇪🇸 Español • 🇧🇷 Português • 🇩🇪 Deutsch • 🇫🇷 Français • 🇷🇺 Русский • 🇮🇹 Italiano • 🇰🇷 한국어 • 🇸🇦 العربية
+
+## 🚀 빠른 시작
+
+### 1단계: AI 도구에 추가
+
+MCP 구성에 추가 (아래 클라이언트별 설정 참조):
+
+```json
+{
+  "mcpServers": {
+    "spec-workflow": {
+      "command": "npx",
+      "args": ["-y", "@pimzino/spec-workflow-mcp@latest", "/path/to/your/project"]
+    }
+  }
+}
+```
+
+### 2단계: 인터페이스 선택
+
+**옵션 A: 웹 대시보드** (CLI 사용자 필수)
+대시보드 시작 (기본 포트 5000):
+```bash
+npx -y @pimzino/spec-workflow-mcp@latest --dashboard
+```
+
+대시보드는 http://localhost:5000 에서 액세스할 수 있습니다.
+
+> **참고:** 하나의 대시보드 인스턴스만 필요합니다. 모든 프로젝트가 동일한 대시보드에 연결됩니다.
+
+**옵션 B: VSCode 확장 프로그램** (VSCode 사용자 권장)
+
+VSCode 마켓플레이스에서 [Spec Workflow MCP Extension](https://marketplace.visualstudio.com/items?itemName=Pimzino.spec-workflow-mcp)을 설치하세요.
+
+## 📝 사용 방법
+
+대화에서 spec-workflow를 언급하기만 하면 됩니다:
+
+- **"사용자 인증을 위한 스펙 생성"** - 완전한 스펙 워크플로우 생성
+- **"내 스펙 목록 보기"** - 모든 스펙과 상태 표시
+- **"user-auth 스펙의 작업 1.2 실행"** - 특정 작업 실행
+
+[더 많은 예제 보기 →](docs/PROMPTING-GUIDE.md)
+
+## 🔧 MCP 클라이언트 설정
+
+<details>
+<summary><strong>Augment Code</strong></summary>
+
+Augment 설정에서 구성:
+```json
+{
+  "mcpServers": {
+    "spec-workflow": {
+      "command": "npx",
+      "args": ["-y", "@pimzino/spec-workflow-mcp@latest", "/path/to/your/project"]
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary><strong>Claude Code CLI</strong></summary>
+
+MCP 구성에 추가:
+```bash
+claude mcp add spec-workflow npx @pimzino/spec-workflow-mcp@latest -- /path/to/your/project
+```
+
+**중요 참고사항:**
+- `-y` 플래그는 더 원활한 설치를 위해 npm 프롬프트를 우회합니다
+- `--` 구분자는 경로가 npx가 아닌 spec-workflow 스크립트에 전달되도록 합니다
+- `/path/to/your/project`를 실제 프로젝트 디렉터리 경로로 바꾸세요
+
+**Windows용 대안 (위 방법이 작동하지 않는 경우):**
+```bash
+claude mcp add spec-workflow cmd.exe /c "npx @pimzino/spec-workflow-mcp@latest /path/to/your/project"
+```
+</details>
+
+<details>
+<summary><strong>Claude Desktop</strong></summary>
+
+`claude_desktop_config.json`에 추가:
+```json
+{
+  "mcpServers": {
+    "spec-workflow": {
+      "command": "npx",
+      "args": ["-y", "@pimzino/spec-workflow-mcp@latest", "/path/to/your/project"]
+    }
+  }
+}
+```
+
+> **중요:** MCP 서버를 시작하기 전에 `--dashboard`로 대시보드를 별도로 실행하세요.
+
+</details>
+
+<details>
+<summary><strong>Cline/Claude Dev</strong></summary>
+
+MCP 서버 구성에 추가:
+```json
+{
+  "mcpServers": {
+    "spec-workflow": {
+      "command": "npx",
+      "args": ["-y", "@pimzino/spec-workflow-mcp@latest", "/path/to/your/project"]
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary><strong>Continue IDE Extension</strong></summary>
+
+Continue 구성에 추가:
+```json
+{
+  "mcpServers": {
+    "spec-workflow": {
+      "command": "npx",
+      "args": ["-y", "@pimzino/spec-workflow-mcp@latest", "/path/to/your/project"]
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary><strong>Cursor IDE</strong></summary>
+
+Cursor 설정(`settings.json`)에 추가:
+```json
+{
+  "mcpServers": {
+    "spec-workflow": {
+      "command": "npx",
+      "args": ["-y", "@pimzino/spec-workflow-mcp@latest", "/path/to/your/project"]
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary><strong>OpenCode</strong></summary>
+
+`opencode.json` 구성 파일에 추가:
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "spec-workflow": {
+      "type": "local",
+      "command": ["npx", "-y", "@pimzino/spec-workflow-mcp@latest", "/path/to/your/project"],
+      "enabled": true
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary><strong>Windsurf</strong></summary>
+
+`~/.codeium/windsurf/mcp_config.json` 구성 파일에 추가:
+```json
+{
+  "mcpServers": {
+    "spec-workflow": {
+      "command": "npx",
+      "args": ["-y", "@pimzino/spec-workflow-mcp@latest", "/path/to/your/project"]
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary><strong>Codex</strong></summary>
+
+`~/.codex/config.toml` 구성 파일에 추가:
+```toml
+[mcp_servers.spec-workflow]
+command = "npx"
+args = ["-y", "@pimzino/spec-workflow-mcp@latest", "/path/to/your/project"]
+```
+</details>
+
+## 🐳 Docker 배포
+
+격리된 배포를 위해 Docker 컨테이너에서 대시보드 실행:
+
+```bash
+# Docker Compose 사용 (권장)
+cd containers
+docker-compose up --build
+
+# 또는 Docker CLI 사용
+docker build -f containers/Dockerfile -t spec-workflow-mcp .
+docker run -p 5000:5000 -v "./workspace/.spec-workflow:/workspace/.spec-workflow:rw" spec-workflow-mcp
+```
+
+대시보드는 http://localhost:5000 에서 사용 가능합니다.
+
+[Docker 설정 가이드 보기 →](containers/README.md)
+
+## 🔒 샌드박스 환경
+
+`$HOME`이 읽기 전용인 샌드박스 환경(예: `sandbox_mode=workspace-write`가 있는 Codex CLI)의 경우 `SPEC_WORKFLOW_HOME` 환경 변수를 사용하여 전역 상태 파일을 쓰기 가능한 위치로 리디렉션하세요:
+
+```bash
+SPEC_WORKFLOW_HOME=/workspace/.spec-workflow-mcp npx -y @pimzino/spec-workflow-mcp@latest /workspace
+```
+
+[구성 가이드 보기 →](docs/CONFIGURATION.md#environment-variables)
+
+## 📚 문서
+
+- [구성 가이드](docs/CONFIGURATION.md) - 명령줄 옵션, 구성 파일
+- [사용자 가이드](docs/USER-GUIDE.md) - 포괄적인 사용 예제
+- [워크플로우 프로세스](docs/WORKFLOW.md) - 개발 워크플로우 및 모범 사례
+- [인터페이스 가이드](docs/INTERFACES.md) - 대시보드 및 VSCode 확장 프로그램 상세 정보
+- [프롬프팅 가이드](docs/PROMPTING-GUIDE.md) - 고급 프롬프팅 예제
+- [도구 참조](docs/TOOLS-REFERENCE.md) - 완전한 도구 문서
+- [개발](docs/DEVELOPMENT.md) - 기여 및 개발 설정
+- [문제 해결](docs/TROUBLESHOOTING.md) - 일반적인 문제 및 해결책
+
+## 📁 프로젝트 구조
+
+```
+your-project/
+  .spec-workflow/
+    approvals/
+    archive/
+    specs/
+    steering/
+    templates/
+    user-templates/
+    config.example.toml
+```
+
+## 🛠️ 개발
+
+```bash
+# 의존성 설치
+npm install
+
+# 프로젝트 빌드
+npm run build
+
+# 개발 모드로 실행
+npm run dev
+```
+
+[개발 가이드 보기 →](docs/DEVELOPMENT.md)
+
+## 📄 라이선스
+
+GPL-3.0
+
+## ⭐ 스타 히스토리
+
+<a href="https://www.star-history.com/#Pimzino/spec-workflow-mcp&Date">
+ <picture>
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=Pimzino/spec-workflow-mcp&type=Date&theme=dark" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=Pimzino/spec-workflow-mcp&type=Date" />
+   <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=Pimzino/spec-workflow-mcp&type=Date" />
+ </picture>
+</a>

package/README.md

@@ -0,0 +1,239 @@
+<p align="center">
+  <img src="assets/logo-wide.svg" alt="SpecFlow" height="48">
+</p>
+
+<p align="center">
+  Spec-driven development with persistent project memory and semantic code intelligence.
+</p>
+
+<p align="center">
+  <a href="https://github.com/lbruton/specflow"><img src="https://img.shields.io/badge/license-GPL--3.0-green" alt="License"></a>
+  <img src="https://img.shields.io/badge/MCP_Server-Plugin-6366f1" alt="MCP Server Plugin">
+  <img src="https://img.shields.io/badge/self--hosted-zero_cloud_deps-22c55e" alt="Self-hosted">
+</p>
+
+<p align="center">
+  <a href="https://lbruton.github.io/specflow/"><strong>View the full interactive about page</strong></a> &bull;
+  <a href="docs/CASE-STUDY-FORGE.md">Case Study: Forge</a> &bull;
+  <a href="FORK-CHANGELOG.md">Changelog</a>
+</p>
+
+---
+
+AI agents forget everything between sessions. They lose decisions, repeat mistakes, and drift from reality. **SpecFlow** gives them a structured lifecycle, persistent cross-project memory, and semantic code intelligence -- all self-hosted.
+
+Built on [Pimzino/spec-workflow-mcp](https://github.com/Pimzino/spec-workflow-mcp)'s core engine (sequential spec workflow, real-time dashboard, blocking approval gates). This fork layers extended lifecycle phases, multi-project orchestration, three-tier knowledge architecture, and semantic code search on top.
+
+## Four Systems, One Workflow
+
+| System | What It Does |
+|--------|-------------|
+| **SpecFlow** (MCP Server) | Spec-driven lifecycle: Requirements → Design → Tasks → Implementation with dashboard approvals at every gate. 6 tools, 7 prompts. |
+| **DocVault** (Obsidian Vault) | Cross-project knowledge base. One vault serves 8+ repos -- architecture, infrastructure, decisions, issues. Graph visualization + wikilinks. |
+| **Code Context** (Milvus) | Semantic code search via self-hosted vector database. Search by meaning, not keywords. Forked from [Zilliz/claude-context](https://github.com/zilliztech/mcp-server-milvus), hardened with timeouts and pinned versions. |
+| **Skill System** (60+ Skills) | CLAUDE.md stays tiny -- a routing table to skills. Each skill encodes a full workflow: debugging, deployment, PR resolution, infrastructure management. |
+
+## Three-Tier Memory Architecture
+
+Not everything belongs in one file. Each tier has a purpose and a source of truth ranking.
+
+| Tier | System | Role |
+|------|--------|------|
+| **1** | DocVault | Ground truth. Human-curated Obsidian vault. Wins all conflicts. |
+| **2** | File Memory | Session context. Project-scoped markdown at `~/.claude/projects/*/memory/`. |
+| **3** | mem0 | Episodic recall. Semantic retrieval from session digests. Never authoritative. |
+
+## Continuous Learning Loop
+
+Every session learns from the previous. This is the single biggest differentiator.
+
+```
+/prime (morning)              /goodnight (end of day)
+  ├─ Index codebase             ├─ /retro
+  ├─ Read recent digests        │   └─ Extract prescriptive lessons → mem0
+  ├─ Pull mem0 memories         └─ /digest-session
+  ├─ Check issues + git             ├─ Read JSONL transcripts
+  └─ "Here's where you left off"    ├─ Summarize via local Ollama
+                                     ├─ Write to DocVault/Daily Digests/
+                                     └─ Save key facts to mem0
+
+  Tomorrow's /prime reads today's digest + retro lessons
+```
+
+## Spec Workflow Lifecycle
+
+Every non-trivial feature follows the same path. Approvals required at each gate.
+
+```
+Phase 0      Phase 1       Phase 2      Phase 3     Phase 4       Phase 5
+/chat    →   /discover  →  /spec    →   Design  →   Implement  →  /retro
+
+Bug fast path: /systematic-debugging → issue → fix (skip Phases 0-2)
+Casual path:   /gsd — no issue, no spec, chore: PR
+```
+
+### Parallel Subagent Dispatch
+
+Tasks don't execute sequentially. Each runs through an isolated three-stage pipeline:
+
+```
+Orchestrator reads task
+  → Implementer Agent      (fresh context, writes code, tests, commits)
+  → Compliance Reviewer    (reads actual code vs requirements)
+  → Quality Reviewer       (architecture, error handling, readiness)
+  → log-implementation     (record artifacts)
+  → mark complete
+
+Tasks with zero file overlap execute concurrently in batches.
+```
+
+**[Case Study: Forge](docs/CASE-STUDY-FORGE.md)** -- empty repo to deployed production app in 3 hours, 23 tasks across 30 parallel subagents, 8 dashboard approval gates, zero file conflicts.
+
+## Code Intelligence
+
+Agents shouldn't grep blindly through your codebase. Four search tiers, cheapest first:
+
+| Tier | Engine | Query Style |
+|------|--------|-------------|
+| 1 | Code Graph Context (Neo4j) | Structural: "what calls this function?" |
+| 2 | Code Context (Milvus) | Semantic: "find code related to payment processing" |
+| 3 | Grep / Glob | Literal: exact strings, filenames, identifiers |
+| 4 | Code Oracle Agent | Deep analysis: combines all sources + AI reasoning |
+
+Code Context is a [hardened fork](https://github.com/lbruton/claude-context) of Zilliz's MCP server -- self-hosted Milvus, 30s timeouts, pinned npm versions. No collection limits, full data sovereignty.
+
+## Comparison
+
+| Dimension | SpecKit | BMAD | GSD | Taskmaster | mex | Pimzino | **SpecFlow** |
+|-----------|---------|------|-----|------------|-----|---------|------------|
+| Approval gates | None | Advisory | UAT | None | None | Dashboard | **Dashboard + skills** |
+| Memory | constitution.md | Git docs | STATE.md | tasks.json | Scaffold | Steering docs | **3-tier** |
+| Session learning | None | None | None | None | GROW loop | None | **/prime → /goodnight** |
+| Code search | None | None | None | None | None | None | **Semantic + structural** |
+| Multi-project | Per-repo | Per-repo | Per-repo | Per-repo | Per-repo | Per-repo | **One vault, all repos** |
+| Infrastructure | Code only | Code only | Code only | Code only | Code only | Code only | **Docker, DNS, VMs** |
+| Drift detection | None | None | None | None | 8 checkers | None | /vault-update gate |
+| Self-hosted | Files | Files | Files | Files | Files | Node.js | **Milvus, Neo4j, Ollama** |
+| Best for | Quick adoption | Enterprise teams | Solo context eng. | PRD pipelines | Per-repo memory | Structured workflow | **Multi-project governance** |
+
+## Quick Start
+
+### As a Claude Code Plugin (recommended)
+
+```bash
+git clone https://github.com/lbruton/specflow.git
+cd spec-workflow-mcp
+npm install && npm run build
+
+# Symlink into Claude Code plugins
+ln -s "$(pwd)" ~/.claude/plugins/marketplaces/specflow-marketplace
+```
+
+### As an MCP Server
+
+```json
+{
+  "mcpServers": {
+    "spec-workflow": {
+      "command": "npx",
+      "args": ["-y", "@lbruton/specflow@latest", "/path/to/your/project"]
+    }
+  }
+}
+```
+
+### Dashboard
+
+Real-time web UI for spec tracking, approvals, and implementation logs. Port 5051 by default.
+
+```bash
+npx @lbruton/specflow@latest --dashboard --port 5051
+```
+
+## MCP Tools
+
+| Tool | Description |
+|------|-------------|
+| `spec-status` | Get detailed status of a spec |
+| `spec-list` | List all specs across projects |
+| `approvals` | Manage phase approval workflow |
+| `log-implementation` | Record implementation artifacts |
+| `spec-workflow-guide` | Get workflow guidance |
+| `steering-guide` | Access project steering documents |
+
+## MCP Prompts
+
+| Prompt | Description |
+|--------|-------------|
+| `create-spec` | Create a new spec from requirements |
+| `implement-task` | Generate implementation plan for a task |
+| `create-steering-doc` | Create project steering documentation |
+| `refresh-tasks` | Re-sync task state from spec files |
+| + 3 injection prompts | Context injection for guides |
+
+## Prerequisites
+
+The core spec workflow works out of the box with Node.js. Extended features use:
+
+| Component | Purpose | Link |
+|-----------|---------|------|
+| [Obsidian](https://obsidian.md) | DocVault knowledge base | [obsidian.md](https://obsidian.md) |
+| [mem0](https://github.com/mem0ai/mem0) | Cross-session episodic memory | [mem0.ai](https://mem0.ai) |
+| [Milvus](https://milvus.io) | Self-hosted vector DB for Code Context | [milvus.io](https://milvus.io) |
+| [Claude Code](https://claude.ai/claude-code) | CLI agent that consumes MCP servers | [docs](https://docs.anthropic.com/en/docs/claude-code) |
+
+## Architecture
+
+```
+src/
+  tools/               # MCP tool definitions (6 tools)
+  prompts/             # MCP prompt definitions (7 prompts)
+  core/                # Shared logic (parser, task-parser, path-utils)
+  dashboard/           # Dashboard backend (multi-server, approval-storage)
+  dashboard_frontend/  # React 18 frontend (Vite + Tailwind)
+  markdown/            # Document and review templates
+  types.ts             # Shared TypeScript types
+  index.ts             # CLI entry point
+```
+
+## Roadmap
+
+- [x] SpecFlow MCP server -- spec lifecycle + dashboard
+- [x] DocVault -- cross-project knowledge vault
+- [x] Code Context -- semantic search (Milvus, self-hosted)
+- [x] Code Graph Context -- structural search (Neo4j, local)
+- [x] 60+ skills -- procedural knowledge routing
+- [x] Memory pipeline -- session digests via local Ollama
+- [ ] Rebrand Code Context -- merge into SpecFlow plugin
+- [ ] Self-host mem0 -- fork + local deployment
+- [ ] Self-host CGC -- fork + local Neo4j bundle
+- [ ] Unified Docker container -- all services in one stack
+- [ ] One-command install for any project
+
+## Development
+
+```bash
+npm install        # Install dependencies
+npm run build      # Compile TypeScript + build dashboard frontend
+npm run dev        # Development mode with hot reload
+```
+
+## Upstream Documentation
+
+Core functionality docs from Pimzino's project:
+
+- [Configuration Guide](docs/CONFIGURATION.md)
+- [User Guide](docs/USER-GUIDE.md)
+- [Workflow Process](docs/WORKFLOW.md)
+- [Prompting Guide](docs/PROMPTING-GUIDE.md)
+- [Tools Reference](docs/TOOLS-REFERENCE.md)
+
+## Credits
+
+**[Pimzino/spec-workflow-mcp](https://github.com/Pimzino/spec-workflow-mcp)** is the foundation. Pimzino designed and built the core architecture: the MCP server, sequential spec workflow, real-time dashboard with blocking approval gates, approval storage, markdown parser, implementation logging, template engine, multi-language support, VSCode extension, Docker deployment, and security hardening. SpecFlow adds workflow extensions, knowledge architecture, and code intelligence on top of that substantial foundation.
+
+**[Zilliz/claude-context](https://github.com/zilliztech/mcp-server-milvus)** provides the semantic code search engine that Code Context is forked from.
+
+## License
+
+GPL-3.0 -- same as upstream.