@zhuan-ai/zhuanspec 1.3.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2024 OpenSpec Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,461 @@
+<p align="center">
+  <a href="https://github.com/Fission-AI/ZhuanSpec">
+    <picture>
+      <source srcset="assets/openspec_pixel_dark.svg" media="(prefers-color-scheme: dark)">
+      <source srcset="assets/openspec_pixel_light.svg" media="(prefers-color-scheme: light)">
+      <img src="assets/openspec_pixel_light.svg" alt="ZhuanSpec logo" height="64">
+    </picture>
+  </a>
+  
+</p>
+<p align="center">Spec-driven development for AI coding assistants.</p>
+<p align="center">
+  <a href="https://github.com/Fission-AI/ZhuanSpec/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/Fission-AI/ZhuanSpec/actions/workflows/ci.yml/badge.svg" /></a>
+  <a href="https://www.npmjs.com/package/@fission-ai/zhuanspec"><img alt="npm version" src="https://img.shields.io/npm/v/@fission-ai/zhuanspec?style=flat-square" /></a>
+  <a href="https://nodejs.org/"><img alt="node version" src="https://img.shields.io/node/v/@fission-ai/zhuanspec?style=flat-square" /></a>
+  <a href="./LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square" /></a>
+  <a href="https://conventionalcommits.org"><img alt="Conventional Commits" src="https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg?style=flat-square" /></a>
+  <a href="https://discord.gg/YctCnvvshC"><img alt="Discord" src="https://img.shields.io/badge/Discord-Join%20the%20community-5865F2?logo=discord&logoColor=white&style=flat-square" /></a>
+</p>
+
+<p align="center">
+  <img src="assets/openspec_dashboard.png" alt="ZhuanSpec dashboard preview" width="90%">
+</p>
+
+<p align="center">
+  Follow <a href="https://x.com/0xTab">@0xTab on X</a> for updates · Join the <a href="https://discord.gg/YctCnvvshC">ZhuanSpec Discord</a> for help and questions.
+</p>
+
+# ZhuanSpec
+
+ZhuanSpec aligns humans and AI coding assistants with spec-driven development so you agree on what to build before any code is written. **No API keys required.**
+
+## Why ZhuanSpec?
+
+AI coding assistants are powerful but unpredictable when requirements live in chat history. ZhuanSpec adds a lightweight specification workflow that locks intent before implementation, giving you deterministic, reviewable outputs.
+
+Key outcomes:
+- Human and AI stakeholders agree on specs before work begins.
+- Structured change folders (proposals, tasks, and spec updates) keep scope explicit and auditable.
+- Shared visibility into what's proposed, active, or archived.
+- Works with the AI tools you already use: custom slash commands where supported, context rules everywhere else.
+
+## How ZhuanSpec compares (at a glance)
+
+- **Lightweight**: simple workflow, no API keys, minimal setup.
+- **Brownfield-first**: works great beyond 0→1. ZhuanSpec separates the source of truth from proposals: `zhuanspec/specs/` (current truth) and `zhuanspec/changes/` (proposed updates). This keeps diffs explicit and manageable across features.
+- **Change tracking**: proposals, tasks, and spec deltas live together; archiving merges the approved updates back into specs.
+- **Compared to spec-kit & Kiro**: those shine for brand-new features (0→1). ZhuanSpec also excels when modifying existing behavior (1→n), especially when updates span multiple specs.
+
+See the full comparison in [How ZhuanSpec Compares](#how-zhuanspec-compares).
+
+## How It Works
+
+```
+┌────────────────────┐
+│ Draft Change       │
+│ Proposal           │
+└────────┬───────────┘
+         │ share intent with your AI
+         ▼
+┌────────────────────┐
+│ Review & Align     │
+│ (edit specs/tasks) │◀──── feedback loop ──────┐
+└────────┬───────────┘                          │
+         │ approved plan                        │
+         ▼                                      │
+┌────────────────────┐                          │
+│ Implement Tasks    │──────────────────────────┘
+│ (AI writes code)   │
+└────────┬───────────┘
+         │ ship the change
+         ▼
+┌────────────────────┐
+│ Archive & Update   │
+│ Specs (source)     │
+└────────────────────┘
+
+1. Draft a change proposal that captures the spec updates you want.
+2. Review the proposal with your AI assistant until everyone agrees.
+3. Implement tasks that reference the agreed specs.
+4. Archive the change to merge the approved updates back into the source-of-truth specs.
+```
+
+## Getting Started
+
+### Supported AI Tools
+
+<details>
+<summary><strong>Native Slash Commands</strong> (click to expand)</summary>
+
+These tools have built-in ZhuanSpec commands. Select the ZhuanSpec integration when prompted.
+
+| Tool | Commands |
+|------|----------|
+| **Amazon Q Developer** | `@zhuanspec-proposal`, `@zhuanspec-apply`, `@zhuanspec-archive` (`.amazonq/prompts/`) |
+| **Antigravity** | `/zhuanspec-proposal`, `/zhuanspec-apply`, `/zhuanspec-archive` (`.agent/workflows/`) |
+| **Auggie (Augment CLI)** | `/zhuanspec-proposal`, `/zhuanspec-apply`, `/zhuanspec-archive` (`.augment/commands/`) |
+| **Claude Code** | `/zhuanspec:proposal`, `/zhuanspec:apply`, `/zhuanspec:archive` |
+| **Cline** | Workflows in `.clinerules/workflows/` directory (`.clinerules/workflows/zhuanspec-*.md`) |
+| **CodeBuddy Code (CLI)** | `/zhuanspec:proposal`, `/zhuanspec:apply`, `/zhuanspec:archive` (`.codebuddy/commands/`) — see [docs](https://www.codebuddy.ai/cli) |
+| **Codex** | `/zhuanspec-proposal`, `/zhuanspec-apply`, `/zhuanspec-archive` (global: `~/.codex/prompts`, auto-installed) |
+| **CoStrict** | `/zhuanspec-proposal`, `/zhuanspec-apply`, `/zhuanspec-archive` (`.cospec/zhuanspec/commands/`) — see [docs](https://costrict.ai)|
+| **Crush** | `/zhuanspec-proposal`, `/zhuanspec-apply`, `/zhuanspec-archive` (`.crush/commands/zhuanspec/`) |
+| **Cursor** | `/zhuanspec-proposal`, `/zhuanspec-apply`, `/zhuanspec-archive` |
+| **Factory Droid** | `/zhuanspec-proposal`, `/zhuanspec-apply`, `/zhuanspec-archive` (`.factory/commands/`) |
+| **Gemini CLI** | `/zhuanspec:proposal`, `/zhuanspec:apply`, `/zhuanspec:archive` (`.gemini/commands/zhuanspec/`) |
+| **GitHub Copilot** | `/zhuanspec-proposal`, `/zhuanspec-apply`, `/zhuanspec-archive` (`.github/prompts/`) |
+| **iFlow (iflow-cli)** | `/zhuanspec-proposal`, `/zhuanspec-apply`, `/zhuanspec-archive` (`.iflow/commands/`) |
+| **Kilo Code** | `/zhuanspec-proposal.md`, `/zhuanspec-apply.md`, `/zhuanspec-archive.md` (`.kilocode/workflows/`) |
+| **OpenCode** | `/zhuanspec-proposal`, `/zhuanspec-apply`, `/zhuanspec-archive` |
+| **Qoder (CLI)** | `/zhuanspec:proposal`, `/zhuanspec:apply`, `/zhuanspec:archive` (`.qoder/commands/zhuanspec/`) — see [docs](https://qoder.com/cli) |
+| **Qwen Code** | `/zhuanspec-proposal`, `/zhuanspec-apply`, `/zhuanspec-archive` (`.qwen/commands/`) |
+| **RooCode** | `/zhuanspec-proposal`, `/zhuanspec-apply`, `/zhuanspec-archive` (`.roo/commands/`) |
+| **Windsurf** | `/zhuanspec-proposal`, `/zhuanspec-apply`, `/zhuanspec-archive` (`.windsurf/workflows/`) |
+
+Kilo Code discovers team workflows automatically. Save the generated files under `.kilocode/workflows/` and trigger them from the command palette with `/zhuanspec-proposal.md`, `/zhuanspec-apply.md`, or `/zhuanspec-archive.md`.
+
+</details>
+
+<details>
+<summary><strong>AGENTS.md Compatible</strong> (click to expand)</summary>
+
+These tools automatically read workflow instructions from `zhuanspec/AGENTS.md`. Ask them to follow the ZhuanSpec workflow if they need a reminder. Learn more about the [AGENTS.md convention](https://agents.md/).
+
+| Tools |
+|-------|
+| Amp • Jules • Others |
+
+</details>
+
+### Install & Initialize
+
+#### Prerequisites
+- **Node.js >= 20.19.0** - Check your version with `node --version`
+
+#### Step 1: Install the CLI globally
+
+```bash
+npm install -g @fission-ai/zhuanspec@latest
+```
+
+Or install from a local tarball (e.g. `distributions/fission-ai-zhuanspec-1.0.0.tgz`): see [Installing ZhuanSpec](#installing-zhuanspec).
+
+Verify installation:
+```bash
+zhuanspec --version
+```
+
+#### Step 2: Initialize ZhuanSpec in your project
+
+Navigate to your project directory:
+```bash
+cd my-project
+```
+
+Run the initialization:
+```bash
+zhuanspec init
+```
+
+**What happens during initialization:**
+- You'll be prompted to pick any natively supported AI tools (Claude Code, CodeBuddy, Cursor, OpenCode, Qoder,etc.); other assistants always rely on the shared `AGENTS.md` stub
+- ZhuanSpec automatically configures slash commands for the tools you choose and always writes a managed `AGENTS.md` hand-off at the project root
+- A new `zhuanspec/` directory structure is created in your project
+
+**After setup:**
+- Primary AI tools can trigger `/zhuanspec` workflows without additional configuration
+- Run `zhuanspec list` to verify the setup and view any active changes
+- If your coding assistant doesn't surface the new slash commands right away, restart it. Slash commands are loaded at startup,
+  so a fresh launch ensures they appear
+
+### Optional: Populate Project Context
+
+After `zhuanspec init` completes, you'll receive a suggested prompt to help populate your project context:
+
+```text
+Populate your project context:
+"Please read zhuanspec/project.md and help me fill it out with details about my project, tech stack, and conventions"
+```
+
+Use `zhuanspec/project.md` to define project-level conventions, standards, architectural patterns, and other guidelines that should be followed across all changes.
+
+### Create Your First Change
+
+Here's a real example showing the complete ZhuanSpec workflow. This works with any AI tool. Those with native slash commands will recognize the shortcuts automatically.
+
+#### 1. Draft the Proposal
+Start by asking your AI to create a change proposal:
+
+```text
+You: Create a ZhuanSpec change proposal for adding profile search filters by role and team
+     (Shortcut for tools with slash commands: /zhuanspec:proposal Add profile search filters)
+
+AI:  I'll create a ZhuanSpec change proposal for profile filters.
+     *Scaffolds zhuanspec/changes/add-profile-filters/ with proposal.md, tasks.md, spec deltas.*
+```
+
+#### 2. Verify & Review
+Check that the change was created correctly and review the proposal:
+
+```bash
+$ zhuanspec list                             # Confirm the change folder exists
+$ zhuanspec validate add-profile-filters     # Validate spec formatting
+$ zhuanspec show add-profile-filters         # Review proposal, tasks, and spec delta
+```
+
+#### 3. Refine the Specs
+Iterate on the specifications until they match your needs:
+
+```text
+You: Can you add acceptance criteria for the role and team filters?
+
+AI:  I'll update the spec delta with scenarios for role and team filters.
+     *Edits zhuanspec/changes/add-profile-filters/specs/profile/spec.md and tasks.md.*
+```
+
+#### 4. Implement the Change
+Once specs look good, start implementation:
+
+```text
+You: The specs look good. Let's implement this change.
+     (Shortcut for tools with slash commands: /zhuanspec:apply add-profile-filters)
+
+AI:  I'll work through the tasks in the add-profile-filters change.
+     *Implements tasks from zhuanspec/changes/add-profile-filters/tasks.md*
+     *Marks tasks complete: Task 1.1 ✓, Task 1.2 ✓, Task 2.1 ✓...*
+```
+
+#### 5. Archive the Completed Change
+After implementation is complete, archive the change:
+
+```text
+AI:  All tasks are complete. The implementation is ready.
+
+You: Please archive the change
+     (Shortcut for tools with slash commands: /zhuanspec:archive add-profile-filters)
+
+AI:  I'll archive the add-profile-filters change.
+    *Runs: zhuanspec archive add-profile-filters --yes*
+     ✓ Change archived successfully. Specs updated. Ready for the next feature!
+```
+
+Or run the command yourself in terminal:
+```bash
+$ zhuanspec archive add-profile-filters --yes  # Archive the completed change without prompts
+```
+
+**Note:** Tools with native slash commands (Claude Code, CodeBuddy, Cursor, Codex, Qoder, RooCode) can use the shortcuts shown. All other tools work with natural language requests to "create a ZhuanSpec proposal", "apply the ZhuanSpec change", or "archive the change".
+
+## Command Reference
+
+### `zhuanspec init`
+
+Initialize ZhuanSpec in your project. Creates the directory structure, template files, and configures AI tool integrations.
+
+```bash
+zhuanspec init [path] [options]
+```
+
+**Arguments:**
+
+| Argument | Description | Default |
+|----------|-------------|---------|
+| `[path]` | Target project directory | `.` (current directory) |
+
+**Options:**
+
+| Option | Description | Example |
+|--------|-------------|---------|
+| `--tools <tools>` | Configure AI tools non-interactively. Accepts `all`, `none`, or a comma-separated list of tool IDs | `--tools claude,cursor` |
+| `--business-direction <direction>` | Specify a business direction to use the corresponding microservice architecture document as `project.md` | `--business-direction oms` |
+
+**Usage examples:**
+
+```bash
+# Interactive mode (default) — prompts you to select AI tools
+zhuanspec init
+
+# Initialize a specific directory
+zhuanspec init ./my-project
+
+# Non-interactive mode — configure specific tools without prompts
+zhuanspec init --tools claude,cursor
+
+# Configure all available tools
+zhuanspec init --tools all
+
+# Initialize with a business direction — uses the architecture doc as project.md
+zhuanspec init --business-direction oms
+
+# Combine options
+zhuanspec init --tools claude --business-direction oms
+```
+
+**What `--business-direction` does:**
+
+When specified, ZhuanSpec looks for a microservice architecture document named `{direction}_project_architect.md` (e.g., `oms_project_architect.md`) and uses it to directly replace the generated `zhuanspec/project.md`. This is useful for teams that have pre-built service architecture documents and want the AI assistant to understand the full microservice topology from the start.
+
+Without this option, `project.md` is generated from the default template with placeholder sections for you to fill in.
+
+**What happens during initialization:**
+
+1. Creates the `zhuanspec/` directory structure (`specs/`, `changes/`, `changes/archive/`)
+2. Generates template files (`AGENTS.md`, `project.md`)
+3. Configures AI tool integrations and slash commands for the tools you selected
+4. Writes a managed `AGENTS.md` stub at the project root
+
+**Extend mode:** If `zhuanspec/` already exists, init runs in extend mode — it preserves existing files and only adds missing ones or refreshes tool configurations.
+
+### Other Commands
+
+```bash
+zhuanspec list               # View active change folders
+zhuanspec view               # Interactive dashboard of specs and changes
+zhuanspec show <change>      # Display change details (proposal, tasks, spec updates)
+zhuanspec validate <change>  # Check spec formatting and structure
+zhuanspec archive <change> [--yes|-y]   # Move a completed change into archive/ (non-interactive with --yes)
+```
+
+## Example: How AI Creates ZhuanSpec Files
+
+When you ask your AI assistant to "add two-factor authentication", it creates:
+
+```
+zhuanspec/
+├── specs/
+│   └── auth/
+│       └── spec.md           # Current auth spec (if exists)
+└── changes/
+    └── add-2fa/              # AI creates this entire structure
+        ├── proposal.md       # Why and what changes
+        ├── tasks.md          # Implementation checklist
+        ├── design.md         # Technical decisions (optional)
+        └── specs/
+            └── auth/
+                └── spec.md   # Delta showing additions
+```
+
+### AI-Generated Spec (created in `zhuanspec/specs/auth/spec.md`):
+
+```markdown
+# Auth Specification
+
+## Purpose
+Authentication and session management.
+
+## Requirements
+### Requirement: User Authentication
+The system SHALL issue a JWT on successful login.
+
+#### Scenario: Valid credentials
+- WHEN a user submits valid credentials
+- THEN a JWT is returned
+```
+
+### AI-Generated Change Delta (created in `zhuanspec/changes/add-2fa/specs/auth/spec.md`):
+
+```markdown
+# Delta for Auth
+
+## ADDED Requirements
+### Requirement: Two-Factor Authentication
+The system MUST require a second factor during login.
+
+#### Scenario: OTP required
+- WHEN a user submits valid credentials
+- THEN an OTP challenge is required
+```
+
+### AI-Generated Tasks (created in `zhuanspec/changes/add-2fa/tasks.md`):
+
+```markdown
+## 1. Database Setup
+- [ ] 1.1 Add OTP secret column to users table
+- [ ] 1.2 Create OTP verification logs table
+
+## 2. Backend Implementation  
+- [ ] 2.1 Add OTP generation endpoint
+- [ ] 2.2 Modify login flow to require OTP
+- [ ] 2.3 Add OTP verification endpoint
+
+## 3. Frontend Updates
+- [ ] 3.1 Create OTP input component
+- [ ] 3.2 Update login flow UI
+```
+
+**Important:** You don't create these files manually. Your AI assistant generates them based on your requirements and the existing codebase.
+
+## Understanding ZhuanSpec Files
+
+### Delta Format
+
+Deltas are "patches" that show how specs change:
+
+- **`## ADDED Requirements`** - New capabilities
+- **`## MODIFIED Requirements`** - Changed behavior (include complete updated text)
+- **`## REMOVED Requirements`** - Deprecated features
+
+**Format requirements:**
+- Use `### Requirement: <name>` for headers
+- Every requirement needs at least one `#### Scenario:` block
+- Use SHALL/MUST in requirement text
+
+## How ZhuanSpec Compares
+
+### vs. spec-kit
+ZhuanSpec’s two-folder model (`zhuanspec/specs/` for the current truth, `zhuanspec/changes/` for proposed updates) keeps state and diffs separate. This scales when you modify existing features or touch multiple specs. spec-kit is strong for greenfield/0→1 but provides less structure for cross-spec updates and evolving features.
+
+### vs. Kiro.dev
+ZhuanSpec groups every change for a feature in one folder (`zhuanspec/changes/feature-name/`), making it easy to track related specs, tasks, and designs together. Kiro spreads updates across multiple spec folders, which can make feature tracking harder.
+
+### vs. No Specs
+Without specs, AI coding assistants generate code from vague prompts, often missing requirements or adding unwanted features. ZhuanSpec brings predictability by agreeing on the desired behavior before any code is written.
+
+## Team Adoption
+
+1. **Initialize ZhuanSpec** – Run `zhuanspec init` in your repo.
+2. **Start with new features** – Ask your AI to capture upcoming work as change proposals.
+3. **Grow incrementally** – Each change archives into living specs that document your system.
+4. **Stay flexible** – Different teammates can use Claude Code, CodeBuddy, Cursor, or any AGENTS.md-compatible tool while sharing the same specs.
+
+Run `zhuanspec update` whenever someone switches tools so your agents pick up the latest instructions and slash-command bindings.
+
+## Installing ZhuanSpec
+
+### From npm (recommended)
+
+```bash
+npm install -g @fission-ai/zhuanspec@latest
+```
+
+### Local installation
+
+If you need to install from a local tarball or git repository, see [INSTALLATION.md](./INSTALLATION.md) for detailed instructions.
+
+For pre-built packages, use the `.tgz` file from the `distributions/` folder:
+
+```bash
+npm install -g ./distributions/fission-ai-zhuanspec-1.0.0.tgz
+```
+
+## Updating ZhuanSpec
+
+1. **Upgrade the package**
+   ```bash
+   npm install -g @fission-ai/zhuanspec@latest
+   ```
+2. **Refresh agent instructions**
+   - Run `zhuanspec update` inside each project to regenerate AI guidance and ensure the latest slash commands are active.
+
+## Contributing
+
+- Install dependencies: `pnpm install`
+- Build: `pnpm run build`
+- Test: `pnpm test`
+- Develop CLI locally: `pnpm run dev` or `pnpm run dev:cli`
+- Conventional commits (one-line): `type(scope): subject`
+
+## License
+
+MIT