speccore 5.19.2 → 5.22.0

package/README.en.md

@@ -1,246 +1,99 @@
-# SpecCore
+# SpecCore — Code by Spec, Not by Vibe
 
-> **Code by Spec, Not by Vibe.**
-
-[![npm version](https://img.shields.io/npm/v/speccore.svg)](https://www.npmjs.com/package/speccore)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org/)
-
-SpecCore is a specification-driven development framework for AI-native teams. It decouples deterministic operations (file creation, directory management, format validation, status statistics) from AI, executing them directly through code to improve efficiency and reduce Token consumption.
-
-> 💡 **v5.19.2** | 68 Commands | 38 Intent Types | Multi-Platform
+SpecCore is a specification-driven development toolkit for AI-native teams. It orchestrates the full cycle: requirement analysis → task splitting → plan scheduling → code generation → archival handoff — all traceable and automated.
 
 ---
 
-## 🧩 Two Ways to Use
-
-SpecCore has two distinct parts:
+## Two Modes
 
-| | 🔧 Terminal (CLI) | 🤖 AI Commands (Slash) |
+| | Simple (default) | Full |
 | :--- | :--- | :--- |
-| **Where** | Terminal | AI coding tools (WorkBuddy / Cursor / Claude) |
-| **How** | `speccore init` | Type `/spec-xxx` |
-| **Mechanism** | TypeScript, direct file ops | Markdown prompts, AI reads & executes |
-| **Count** | 68 CLI commands | 54 Slash Commands |
-| **When** | Init, validation, batch ops | Daily dev: iteration, execution, review, archive |
+| Commands | 17 core | 51 all |
+| For | Daily development | Fine-grained control |
+| Enable | `speccore init` | `speccore init --full` |
 
-> 💡 **Remember**: `speccore` prefix → Terminal; `/spec` prefix → AI tool.
+**Simple mode commands:** `ask init iteration task doc2spec analyze split plan execute pr done change validate rename dev status-panel ops`
 
 ---
 
-## 📦 Install
-
-```bash
-npm install -g speccore          # Global install (recommended)
-npx speccore --version           # Or use npx
-```
-
 ---
 
-## 🚀 Quick Start (5 min)
+## Quick Start
 
 ```bash
-# 1. Initialize
-cd my-project && speccore init
-
-# 2. Import to global layer
-speccore import --project=user-service --path=./backend --type=backend
-
-# 3. Create iteration
-speccore iteration create --name 2026-07-UserSystem
-
-# 4. Multi-platform task
-speccore new-task --name UserLogin --platforms=web,h5
-
-# 5. Smart entry
-speccore spec "How's the progress?"
+npm install -g speccore
+speccore init                          # Initialize
+speccore iteration create --name=Q1    # Create iteration
+speccore doc2spec -f PRD.md -p backend -i Q1  # Import requirements
+speccore analyze -I Q1                 # Analyze (req+code, 3 scopes)
+speccore iteration split -i Q1         # Split into tasks
+speccore plan --iteration=Q1           # Generate plan
+speccore execute --task=Task-001       # AI development
+speccore pr --task=Task-001            # Create PR
+speccore done --task=Task-001          # Complete
 ```
 
-> 📚 See [Quick Start Guide](docs/quick-start.en.md) for detailed steps.
 
----
+## Two Ways to Use
 
-## Feature Highlights
+Same command, different syntax depending on context:
 
-- **🚀 Quick Init**: One command initializes the full project structure, auto-integrates WorkBuddy
-- **📱 Multi-Platform**: `--platforms=web,h5,miniapp` per-platform Task management, dynamic platform types
-- **🧠 Intent Recognition**: 38 intent types, 200+ keywords, natural language → command matching
-- **🌐 Global Layer**: Cross-project requirement indexing via GLOBAL/ architecture
-- **📊 Progress Tracking**: Auto-detect active iteration, per-platform/per-assignee stats
-- **✅ Auto Compliance**: Scan all Spec files, check required fields and format
-- **🔄 Deterministic Execution**: File ops, validation, statistics — all local code, zero Token cost
+| Context | Syntax | Example |
+|:---|:---|:---|
+| 🖥 Terminal CLI | `speccore <command>` | `speccore init` `speccore execute -t Task-001 --force` |
+| 💬 AI Chat | Natural language | "Create a login feature" |
+| 💬 AI Chat | `/spec-<command>` | `/spec-init` `/spec-execute Task-001` |
 
----
+> Full reference (all 17 commands classified) → [Commands Reference — Two Ways to Use](docs/commands.en.md#-two-ways-to-use)
 
-## Design Philosophy
+## Interactive Mode
 
-SpecCore decouples **deterministic logic from intelligent logic**:
+Key steps support `--interactive` for human-AI collaboration:
+`analyze --ask` `split --interactive` `plan --interactive` `change --interactive`
 
-| Logic Type | Responsibility | Executor | Example |
-| :--- | :--- | :--- | :--- |
-| **Deterministic** | Structured operations | CLI code | Create dirs, parse YAML, validate, count |
-| **Intelligent** | Understanding & decision | AI tool | Understand requirements, split tasks, generate code |
+## Smart Entry
 
-```
-User Input (Natural Language / Slash Command)
-        │
-        ▼
-┌───────────────────────────────────────┐
-│   AI Layer (Intelligent Decision)     │
-│   - Understand user intent            │
-│   - Decide which operations to run    │
-│   - Generate code content             │
-└───────────────────────────────────────┘
-        │ Call CLI commands
-        ▼
-┌───────────────────────────────────────┐
-│   CLI Layer (Deterministic Execution) │
-│   - Create directory structure        │
-│   - Read/write config & Spec files    │
-│   - Parse YAML                        │
-│   - Compliance validation             │
-│   - Output structured results         │
-└───────────────────────────────────────┘
+```bash
+speccore                   # Adaptive panel
+speccore "analyze specs"   # Natural language (no subcommand needed)
+speccore dev               # Auto-detect phase + cascade execute
 ```
 
----
-
-## 🔧 CLI Commands Quick Reference (68 total)
-
-> Run in terminal. All commands start with `speccore`.
-
-| Category | Key Commands |
-| :--- | :--- |
-| 🧠 Smart Entry | `speccore spec "<query>"` |
-| 🌐 Global Layer | `import` / `iteration-from-global` / `sync-global` / `global-status` / `history` / `index-update` |
-| 📋 Scenario | `goal` / `bugfix` / `research` / `retro` / `handover` |
-| 📐 Planning | `init` / `iteration create` / `iteration split` / `new-task` / `plan` |
-| ⚡ Execution | `execute` (--platform / --priority / --status) |
-| 🔄 Change | `change` / `sync` / `sync-global` |
-| ✅ Review | `validate` (--fix) |
-| 📊 Progress | `progress` (--platform / --detail) / `status` |
-| 📦 Management | `archive` / `config` / `baseline` / `rename` |
-| 🔗 Analysis | `impact` / `dashboard` / `audit` |
-| 📱 Platform | `platform-add` / `context` |
-| 🛠️ Tools | `health` / `report` / `template-add` / `help` / `demo` / `welcome` |
-
-## 🤖 AI Commands (Slash Command) Mapping
-
-> Type `/` in AI tools (WorkBuddy / Cursor / Claude Code etc.). AI commands call the corresponding CLI command internally.
-
-| CLI Command | AI Slash Command | Purpose |
-| :--- | :--- | :--- |
-| `speccore init` | `/spec-init` | Initialize project |
-| `speccore import` | `/spec-import` | Import to global layer |
-| `speccore iteration create` | `/spec-iteration-create` | Create iteration |
-| `speccore new-task` | `/spec-new-task` | Create multi-platform task |
-| `speccore execute` | `/spec-execute` | Execute development |
-| `speccore progress` | `/spec-progress` | View progress |
-| `speccore validate` | `/spec-validate` | Compliance check |
-| `speccore impact` | `/spec-impact` | Impact analysis |
-| `speccore audit` | `/spec-ai-audit` | AI smart audit |
-| `speccore spec "query"` | `/spec query` | Natural language intent |
-
-> 📋 Full command reference: [Command Reference](docs/commands.en.md) | 🧠 Intent mapping: [Intent Map](docs/commands.en.md#natural-language-intent-mapping-38-types)
+## Multi-Platform
 
----
+All steps support parallel multi-project: backend services (`backend/room-service/`) and frontend platforms (`frontend/web/`, `frontend/h5/`).
 
-## 🏗️ Architecture
+## Bug Fix
 
+```bash
+speccore task new --name="Login timeout" --desc="Token expiry" --type=bugfix              # Single
+speccore task new --batch-file=bugs.xlsx --type=bugfix                                    # Batch import
+speccore task new --batch-file=bugs.xlsx --type=bugfix --interactive                      # Confirm each
 ```
-.speccore/GLOBAL/   ← Global Layer: unified multi-project requirements
-.speccore/           ← Project Layer: constitution, config, patterns
-Iteration-XXX/       ← Iteration Layer: what this iteration does
-  └── Task-XXX/      ← Task Layer: how this feature works
-      ├── _shared/   ← Shared: API Contract + business rules
-      ├── backend/   ← Backend Specs
-      └── frontend/  ← Multi-platform frontend specs (web / h5 / miniapp)
-```
-
----
-
-## 🛠️ Tool Support
-
-| CN | Global |
-| :--- | :--- |
-| WorkBuddy / Qcoder / Trae | Cursor / Claude Code / Windsurf / Gemini CLI / OpenCode |
-
-SpecCore natively integrates WorkBuddy.
 
-> 📚 See [Tool Adaptation](docs/tool-adaptation.en.md)
-
----
-
-## 📚 Documentation
-
-| Document | Content |
-| :--- | :--- |
-| [Scenarios](docs/scenarios.en.md) | 22 real-world scenarios: new project → daily dev → CI/CD |
-| [SDD Methodology](docs/sdd-methodology.en.md) | What is SDD, why, how |
-| [Quick Reference](docs/quick-reference.en.md) | One-page: commands + safety + CI |
-| [Quick Start](docs/quick-start.en.md) | Install → Init → Import → Multi-platform → Scenarios |
-| [Command Reference](docs/commands.en.md) | 68 commands full params + 38 intents |
-| [Tool Adaptation](docs/tool-adaptation.en.md) | WorkBuddy integration + workflow + security |
-| [Usage Guide](docs/usage-guide.en.md) | File safety: manual edit vs CLI command |
-| [Workspace Layout](docs/workspace-organization.en.md) | Recommended directory structure |
-| [Migration Guide](docs/migration-guide.en.md) | Shell v3.x → CLI v5.x |
-| [CHANGELOG](CHANGELOG.en.md) | Version history (v1.0.0 → v5.19.2) |
-| [Example](examples/task-management/README.md) | Full demo: req→Spec→generated code |
-| [README.md](README.md) | 中文项目概述 |
-
----
-
-## FAQ
-
-| Q | A |
-| :--- | :--- |
-| **Command not found?** | Add npm bin to PATH: `export PATH="$(npm bin -g):$PATH"` |
-| **How to update?** | `npm update -g speccore` |
-| **Same feature on Web+H5+MiniApp?** | `speccore new-task --platforms=web,h5,miniapp` |
-| **Add new platform?** | `speccore platform-add --name=tablet --tech="React Native"` |
-| **Rename iteration/task?** | `speccore rename --target=old --new-name=new` |
-| **Batch rename?** | `speccore rename --batch --pattern="Task-" --replacement="Feature-"` |
-| **Rebuild requirement index?** | `speccore index-update` (--dry-run to preview) |
-
-| **Which files are safe to edit manually?** | See [Usage Guide](docs/usage-guide.en.md). TL;DR: `REQ.md`/`TECH.md` safe; `API_CONTRACT.yaml`/`.json` require CLI commands. |
-
----
-
-## File Safety Quick Reference
-
-| Zone | Files | Rule |
-| :--- | :--- | :--- |
-| ✅ Safe | `REQ.md`, `TECH.md`, `GLOSSARY.md`, `*.md` comments | Edit directly, then `speccore sync --reverse` |
-| ❌ Danger | `PROJECT_GRAPH.md` tables, `.task-type`, `API_CONTRACT.yaml`, `.json` data | Use `speccore` commands instead |
-| ⚠️ Caution | `GLOBAL/REQUIREMENT.md`, `CHANGELOG.md` | Edit then immediately run `speccore sync-global` |
-
----
-
-## Development
+## Scheduled Execution
 
 ```bash
-git clone https://github.com/windfallsheng/SpecCore-ts.git
-cd SpecCore-ts/ts-cli
-npm install && npm run build
-npm run watch           # Dev mode
-npm link && speccore --version   # Local test
-bash verify.sh          # Run tests
+# Method 1: Mark tasks for queue, trigger manually
+speccore task new -n "Fix login timeout" --type=bugfix --schedule=night   # Mark as queue
+speccore execute --all --scheduled                                        # Run all queued tasks
+
+# Method 2: Precise time scheduling
+speccore schedule create --at "2026-08-10 21:00:00" -t Task-001          # Schedule single task
+speccore schedule create --at "2026-08-10 02:00:00" --all -i Q1          # Schedule all tasks
+speccore schedule list                                                     # View schedule queue
+speccore schedule cancel --id=sch-xxx                                      # Cancel
+speccore schedule daemon start                                             # Start daemon (auto-execute)
+speccore schedule daemon status                                            # Check daemon status
 ```
 
----
-
-## Version
-
-v5.19.2 | 🔧 CLI Commands: 68 | 🧠 Intents: 38
-
-Changelog: [CHANGELOG.en.md](CHANGELOG.en.md)
+## Documentation
 
----
-
-## License
-
-[MIT](https://opensource.org/licenses/MIT)
-
----
-
-<p align="center">Built with ❤️ by the SpecCore Team</p>
+| Doc | Content |
+| :--- | :--- |
+| 🚀 [Quick Start](docs/快速开始.md) | Full tutorial |
+| 🔧 [Full Command Reference](docs/命令参考.md) | 51 commands |
+| [Scenarios](docs/场景实战.md) | Typical use cases |
+| [Overview](docs/总览.md) | Architecture + concepts |
+| [SDD Methodology](docs/SDD方法论.md) | Why Spec-Driven Development |
+| [Examples](examples/meeting-system/README.md) | Meeting booking system demo |