@trench-craft/sds 1.0.0

package/README.en.md

@@ -0,0 +1,522 @@
+# @trench-craft/sds
+
+**Spec-Driven Superpowers** — A structured development workflow for AI coding tools.
+
+Transform vague requirements into quality code through a 6-phase pipeline: **explore → brainstorm → propose → plan → apply → verify → archive**.
+
+Works with **Claude Code**, **OpenCode**, and compatible AI coding assistants.
+
+---
+
+## Table of Contents
+
+- [Features](#features)
+- [Prerequisites](#prerequisites)
+- [Quick Start](#quick-start)
+- [Workflow Overview](#workflow-overview)
+  - [Phase 0: Context Awareness](#phase-0-context-awareness)
+  - [Phase 1: Requirements Analysis](#phase-1-requirements-analysis)
+  - [Phase 2: Generate 4 Artifacts](#phase-2-generate-4-artifacts)
+  - [Phase 3: Write Plans](#phase-3-write-plans)
+  - [Phase 4: Implementation](#phase-4-implementation)
+  - [Phase 5: Quality Verification](#phase-5-quality-verification)
+  - [Phase 6: Archive & Delivery](#phase-6-archive--delivery)
+- [CLI Reference](#cli-reference)
+- [Platform Support](#platform-support)
+- [Uninstall](#uninstall)
+- [Troubleshooting](#troubleshooting)
+- [FAQ](#faq)
+- [Architecture](#architecture)
+- [Development](#development)
+- [Migrate from V1](#migrate-from-v1)
+- [License](#license)
+
+---
+
+## Features
+
+| Feature | Description |
+|---------|-------------|
+| **6-Phase Pipeline** | From context gathering to delivery archive — every change follows a proven path |
+| **4 Standard Artifacts** | `proposal.md` / `design.md` / `specs.md` / `tasks.md` for every change |
+| **HARD-GATE** | No coding before design approval — enforced at the skill level |
+| **TDD Mandatory** | Test-driven development enforced during implementation |
+| **Subagent Review** | Spec compliance + code quality reviews via parallel subagents |
+| **Empty Project Skip** | Phase 0 auto-skipped when project has no code |
+| **Dual Platform** | Works with both Claude Code and OpenCode |
+| **Conversation Guard** | Skills only trigger on development tasks, not casual chat |
+
+---
+
+## Prerequisites
+
+- **Node.js** >= 18.0.0
+- **npm** >= 9.0.0
+- One of: **Claude Code** CLI or **OpenCode** (or compatible AI coding tool)
+
+---
+
+## Quick Start
+
+> This is a **project-level installation** — run `npx` in your project directory, no `npm install -g` needed.
+> SDS skills are installed to your project's `.opencode/skills/` or `.claude/skills/` directory.
+
+### 1. Install Skills
+
+```bash
+# Navigate to your project
+cd my-project
+
+# ─── Option A: Auto-detect tool (recommended) ───
+# Automatically detects if .opencode or .claude exists
+npx @trench-craft/sds@2.0.0 skills install core
+
+# ─── Option B: Specify tool manually ───
+# OpenCode:
+npx @trench-craft/sds@2.0.0 skills install core --tool opencode
+# Shorthand: --tool oc
+
+# Claude Code:
+npx @trench-craft/sds@2.0.0 skills install core --tool claude
+# Shorthand: --tool cc or --tool claude-code
+
+# Install all skills (core + locale plugins)
+npx @trench-craft/sds skills install all --tool opencode
+```
+
+### 2. Verify Installation
+
+```bash
+# Check installed skills
+# OpenCode:
+ls .opencode/skills/
+
+# Claude Code:
+ls .claude/skills/
+
+# Check generated config files
+# OpenCode:
+cat AGENTS.md
+
+# Claude Code:
+cat CLAUDE.md
+```
+
+### 3. View Available Commands
+
+```bash
+npx @trench-craft/sds --help
+```
+
+### 2. Verify Installation
+
+```bash
+# Check installed skills
+# OpenCode:
+ls .opencode/skills/
+
+# Claude Code:
+ls .claude/skills/
+
+# Check generated config
+# OpenCode:
+cat AGENTS.md
+
+# Claude Code:
+cat CLAUDE.md
+```
+
+### 3. Start Using
+
+Open the project in your AI coding tool and type:
+
+> "I want to implement a user login feature"
+
+The AI will recognize this as a development task and start the workflow automatically.
+
+---
+
+## Workflow Overview
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                    SDS 6-Phase Pipeline                             │
+├─────────┬──────────┬──────────┬─────────┬─────────┬────────┬───────┤
+│ Phase 0 │  Phase 1 │  Phase 2 │ Phase 3 │ Phase 4 │ Phase5 │Phase6 │
+│ Context │ Brain-   │ Generate │ Write   │ Imple-  │ Verify │Archive│
+│ Aware-  │ storm    │ Artifacts│ Plans   │ ment    │        │       │
+│ ness    │          │          │         │         │        │       │
+├─────────┼──────────┼──────────┼─────────┼─────────┼────────┼───────┤
+│ codebase│ brain-   │ generate │ write-  │ apply-  │ verify-│archive│
+│ -map    │ storming │ -artifac-│ plans   │ changes │ changes│-chang-│
+│ deep-   │          │ ts       │         │ subagen-│        │ es    │
+│ explore │          │          │         │ t-dev   │        │       │
+└─────────┴──────────┴──────────┴─────────┴─────────┴────────┴───────┘
+```
+
+### Phase 0: Context Awareness
+
+**Skills**: `codebase-map`, `deep-explore`
+
+Understand the existing codebase before making changes.
+
+| Scenario | Action |
+|----------|--------|
+| **Existing project** | Scan structure, detect tech stack, map modules, identify risks |
+| **New / empty project** | **Auto-skipped** — jump directly to Phase 1 |
+| **Specific module inquiry** | Deep investigation of a targeted area |
+
+**Output**: `AGENTS.md` / `CLAUDE.md` (project map), or exploration notes.
+
+**Example prompt**: "What does this project do?" / "Analyze the auth system"
+
+---
+
+### Phase 1: Requirements Analysis
+
+**Skill**: `brainstorming`
+
+The most critical phase. The AI explores requirements through structured conversation before any code is written.
+
+```
+┌─────────────────────────────────────────────────────┐
+│               Brainstorming Flow                     │
+├─────────────────────────────────────────────────────┤
+│                                                      │
+│  1. Explore project context (files, docs, commits)   │
+│  2. Ask clarifying questions (one at a time)         │
+│  3. Propose 2-3 approaches with tradeoffs            │
+│  4. Present design section by section                │
+│  5. Write design document                            │
+│  6. Subagent spec review                             │
+│  7. User reviews written spec                        │
+│  8. Transition to Phase 2                            │
+│                                                      │
+└─────────────────────────────────────────────────────┘
+```
+
+**🚫 HARD-GATE**: No implementation code is written during or after this phase until design is approved.
+
+**Output**: `openspec/changes/<name>/brainstorming.md`
+
+**Example prompt**: "I want to implement a login feature"
+
+---
+
+### Phase 2: Generate 4 Artifacts
+
+**Skill**: `generate-artifacts`
+
+Transform approved requirements into 4 standard artifacts:
+
+| Artifact | Content | Purpose |
+|----------|---------|---------|
+| `proposal.md` | Background, goals, scope (in/out), tech stack | **What** & **Why** |
+| `design.md` | Architecture diagram, API definitions, data models, security | **How** |
+| `specs.md` | Functional specs, non-functional specs, acceptance criteria | **Definition of Done** |
+| `tasks.md` | Task list, dependency graph, time estimates | **Execution Plan** |
+
+> ⚠️ **All 4 artifacts are mandatory.** None may be skipped.
+
+**Output directory**: `openspec/changes/<name>/`
+
+---
+
+### Phase 3: Write Plans
+
+**Skill**: `write-plans`
+
+Break specs into detailed, executable implementation plans. Each task follows TDD (Red → Green → Refactor).
+
+**Plan structure**:
+
+```
+### Task N: [Component Name]
+
+**Files**:
+- Create: `path/to/file.py`
+- Modify: `path/to/existing.py:123-145`
+
+- [ ] Step 1: Write failing test
+- [ ] Step 2: Run test (expect FAIL)
+- [ ] Step 3: Write minimal implementation
+- [ ] Step 4: Run test (expect PASS)
+- [ ] Step 5: Commit
+```
+
+**No placeholders allowed** — every step must contain actual code and expected output.
+
+**Output**: `openspec/changes/<name>/plan.md`
+
+---
+
+### Phase 4: Implementation
+
+**Skills**: `apply-changes`, `subagent-development`
+
+Two execution modes:
+
+#### Mode A: Standard (Manual)
+
+Execute tasks sequentially from `plan.md`, following TDD.
+
+#### Mode B: Subagent Development (Recommended)
+
+Each task is executed by a dedicated subagent with isolated context:
+
+```
+┌─────────────┐    ┌──────────────┐    ┌──────────────────┐
+│ Implementer │───▶│ Spec Reviewer│───▶│ Code Quality     │
+│ Subagent    │    │ Subagent     │    │ Reviewer         │
+│ (TDD+code)  │    │ (compliance) │    │ Subagent         │
+└─────────────┘    └──────────────┘    └──────────────────┘
+       │                                     │
+       └────── Retry on failure ──────────────┘
+```
+
+**Benefits**:
+- Isolated context per task (no contamination)
+- 2-phase review catches issues early
+- TDD enforced automatically
+- Parallel-safe execution
+
+---
+
+### Phase 5: Quality Verification
+
+**Skill**: `verify-changes`
+
+7 mandatory checks:
+
+| # | Check | How |
+|---|-------|-----|
+| 1 | **Compilation** | `tsc --noEmit`, `go build`, etc. |
+| 2 | **Tests** | All tests pass |
+| 3 | **Spec Alignment** | All spec requirements implemented |
+| 4 | **Task Completeness** | No unfinished tasks |
+| 5 | **Code Quality** | LSP clean, no TODOs/FIXMEs, naming consistent |
+| 6 | **Documentation** | README, API docs, env vars synced |
+| 7 | **Breaking Changes** | API backward compatibility, config changes, DB migrations |
+
+All 7 checks must pass. If any fails, fix and re-run verification.
+
+**Output**: `openspec/changes/<name>/verify.md`
+
+---
+
+### Phase 6: Archive & Delivery
+
+**Skill**: `archive-changes`
+
+Archive completed changes for historical reference:
+
+```
+openspec/
+├── changes/<name>/    (active — removed after archive)
+└── archive/<date>-<name>/  (permanent record)
+```
+
+**Prerequisite**: Phase 5 must pass before archiving.
+
+---
+
+## CLI Reference
+
+```bash
+@trench-craft/sds <command> [options]
+
+Commands:
+  skills install <type>  Install skills (core | locale | all) [default: all]
+  skills verify [skill]  Verify skill installation
+  skills list            List installed skills
+
+Options:
+  --tool <tool>          Target tool: opencode | oc | claude-code | cc | claude
+                         [auto-detects from .opencode / .claude directory]
+  --verbose              Verbose output
+  -V, --version          Output version
+  -h, --help             Display help
+```
+
+### Examples
+
+```bash
+# Auto-detect and install
+npx @trench-craft/sds skills install core
+
+# Specify tool with shorthand
+npx @trench-craft/sds skills install all --tool oc
+npx @trench-craft/sds skills install core --tool cc
+
+# Install locale plugins only
+npx @trench-craft/sds skills install locale --tool opencode
+```
+
+---
+
+## Platform Support
+
+| Platform | Config File | Skills Directory | Detection |
+|----------|-------------|-----------------|-----------|
+| **OpenCode** | `AGENTS.md` | `.opencode/skills/` | `.opencode/` exists |
+| **Claude Code** | `CLAUDE.md` | `.claude/skills/` | `.claude/` exists |
+
+**Claude Code also receives**:
+- `core-engine` — File system, Git, command execution
+- `prompt-manager` — Prompt optimization
+- `subagent-dispatcher` — Subagent lifecycle management
+
+---
+
+## Uninstall
+
+```bash
+# Remove installed skills and config
+rm -rf .opencode/skills AGENTS.md   # OpenCode
+rm -rf .claude/skills CLAUDE.md     # Claude Code
+
+# Remove npm package
+npm uninstall @trench-craft/sds
+```
+
+---
+
+## Troubleshooting
+
+| Problem | Solution |
+|---------|----------|
+| **Skills not recognized** | Restart your AI coding tool after installation |
+| **"No tool detected" error** | Use `--tool opencode` or `--tool claude-code` explicitly |
+| **Skills appear with Chinese names** | Reinstall with latest version: old V1 names cached |
+| **Subagent not triggering** | Ensure `plan.md` is generated first, then call `subagent-development` |
+| **verify fails on spec alignment** | Check `specs.md` acceptance criteria match implemented features |
+| **Windows path issues** | Use forward slashes or escaped backslashes in paths |
+
+---
+
+## FAQ
+
+### What's the difference between V1 and V2?
+
+V2 (`@trench-craft/sds`) is a complete rewrite with OpenSpec workflow. See [Migrate from V1](#migrate-from-v1).
+
+### Can I use this with other AI tools?
+
+The skills are designed for Claude Code and OpenCode but can be adapted for any AI coding assistant that supports skill/plugin systems.
+
+### Do I need to install this in every project?
+
+Yes. Skills are project-local. Each project needs its own installation.
+
+### Will this slow down my AI?
+
+No. Skills only activate on matching tasks. Casual conversation, questions, and non-development topics pass through without interference.
+
+### What if I skip a phase?
+
+The workflow is designed to catch issues early. Skipping phases increases risk of rework, missed requirements, or quality issues.
+
+---
+
+## Architecture
+
+```
+@trench-craft/sds
+├── bin/sds.ts              ← CLI entry point
+├── src/
+│   ├── commands/
+│   │   ├── init.ts          ← Project init
+│   │   ├── skills-install.ts ← Skill installer (core logic)
+│   │   ├── skills.ts        ← Skills command group
+│   │   ├── config.ts        ← Configuration
+│   │   ├── project.ts       ← Project management
+│   │   └── ...              ← Other commands
+│   ├── platform/
+│   │   ├── opencode.ts      ← OpenCode adapter
+│   │   └── claude.ts        ← Claude Code adapter
+│   ├── core/
+│   │   └── engine.ts        ← SDS engine
+│   └── skills/              ← Skill loader
+├── skills/
+│   ├── core/                ← 14 core skills
+│   │   ├── brainstorming/
+│   │   ├── opsx-propose/
+│   │   ├── writing-plans/
+│   │   ├── opsx-apply/
+│   │   ├── opsx-verify/
+│   │   ├── opsx-archive/
+│   │   ├── existing-code-caveman/
+│   │   ├── opsx-explore/
+│   │   ├── subagent-driven-development/
+│   │   ├── ecc-agents-md-router/
+│   │   ├── ecc-context-injector/
+│   │   ├── claude-code-core/       (Claude Code only)
+│   │   ├── claude-code-prompt/     (Claude Code only)
+│   │   └── claude-code-subagent/   (Claude Code only)
+│   └── locale/              ← 4 locale skills (zh-CN)
+│       ├── chinese-code-review/
+│       ├── chinese-commit-conventions/
+│       ├── chinese-documentation/
+│       └── chinese-git-workflow/
+├── templates/
+│   ├── agents-md.md         ← OpenCode AGENTS.md template
+│   └── claude-md.md         ← Claude Code CLAUDE.md template
+└── package.json
+```
+
+---
+
+## Development
+
+```bash
+# Clone the monorepo
+git clone <repo-url>
+cd packages/sds
+
+# Install dependencies
+npm install
+
+# Build from source
+npm run build
+
+# Test locally
+npm link
+cd /path/to/test-project
+npm link @trench-craft/sds
+npx sds skills install core --tool opencode
+```
+
+---
+
+## Migrate from V1
+
+V2 (`@trench-craft/sds`) is a major upgrade from V1 (`trench-craft-skills`).
+
+| Aspect | V1 | V2 |
+|--------|----|----|
+| **Package** | `trench-craft-skills` | **`@trench-craft/sds`** |
+| **Workflow** | Linear process | **6-phase OpenSpec pipeline** |
+| **Artifact Path** | `docs/superpowers/` | **`openspec/changes/<name>/`** |
+| **4 Artifacts** | Not available | **proposal / design / specs / tasks** |
+| **CLI Flag** | `--platform` | **`--tool`** |
+| **Skill Names** | Chinese | **English kebab-case** |
+| **Phase 0** | Not available | **Context awareness (auto-skip empty projects)** |
+| **Plan Review** | Optional | **Mandatory subagent plan review** |
+| **Verify Phase** | Not available | **7 mandatory quality checks** |
+| **Archive Phase** | Not available | **Structured archive with history** |
+
+### Migration Steps
+
+1. Uninstall V1 skills: `rm -rf .opencode/skills .claude/skills AGENTS.md CLAUDE.md`
+2. Install V2: `npx @trench-craft/sds skills install core --tool opencode`
+3. Existing `docs/superpowers/` artifacts remain readable but new work uses `openspec/changes/`
+
+---
+
+## License
+
+MIT
+
+---
+
+*Built with ❤️ for developers who believe AI-assisted coding deserves structure.*