specdo 1.0.2

package/CHANGELOG.md

@@ -0,0 +1,139 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- `specdo init <agent>` exports **5 core workflow skill packages** into the
+  canonical skill directory of the chosen AI tool. Each package is a
+  directory with a concise `SKILL.md` plus a `references/` sub-directory
+  carrying the detailed reference material. SpecDo-specific domain and
+  protocol guidance now lives inside those workflow-local references instead
+  of shipping as parallel top-level skills, which keeps the exported surface
+  aligned with the OpenSpec core workflow paradigm while still adding richer
+  guardrails. This follows the [Agent Skills](https://agentskills.io)
+  progressive disclosure standard so agents only load the deeper content
+  when needed. Eight agents are supported, each path verified against the
+  upstream docs:
+  - `claude`   → `.claude/skills/`     (Anthropic)
+  - `qoder`    → `.qoder/skills/`      (Qoder)
+  - `cursor`   → `.cursor/skills/`     (Cursor 2.4+)
+  - `cline`    → `.cline/skills/`      (Cline experimental)
+  - `codex`    → `.codex/skills/`      (OpenAI Codex CLI)
+  - `goose`    → `.goose/skills/`      (Block Goose)
+  - `kilo`     → `.kilo/skills/`      (Kilo Code)
+  - `opencode` → `.opencode/skills/`  (OpenCode, Claude-compatible)
+
+  Multiple targets can be listed via comma separation (e.g. `claude,cursor`).
+- `specdo init universal` (escape hatch) writes into the community
+  `.agents/skills/` directory, which is picked up by Cursor / Goose / Kilo
+  Code / Roo Code via their compatibility loaders. Use this when your AI
+  tool is unsupported but understands the open Agent Skills standard. This
+  is also the non-interactive form of the unknown-agent fallback prompt.
+- Typo correction: when `init` receives a name that is not in the
+  registry, SpecDo suggests the closest canonical match using Levenshtein
+  distance ≤ 1 (e.g. `clude` → `claude`). When no candidate is close
+  enough in an interactive shell, SpecDo prompts to install the universal
+  fallback; in non-interactive shells it prints a short hint pointing at
+  `specdo init universal`.
+- `specdo init -g` (alias `--global`) installs the same skills into the
+  user-global directory (`~/.<agent>/skills/`); requires an agent and skips
+  the project skeleton.
+- New helper modules under `src/core/skill-content/`
+  (`workflow-content.ts`, `cross-domain.ts`, `protocol-examples.ts`) host
+  the hand-authored prose used by the progressive-disclosure skill packages.
+  `src/core/skill-exporter.ts` renders SKILL.md + references at runtime
+  from `DomainModule` / `Protocol` definitions and these content modules
+  — no template files, single source of truth in code.
+
+### Changed
+
+- **BREAKING**: `specdo init` now requires an agent name as a positional
+  argument (e.g. `specdo init claude`). Running `specdo init` alone exits
+  with code 2 and prints usage help. The previous `--agent <name>` flag
+  has been removed; use the positional argument instead. Migration: replace
+  `specdo init --agent claude` with `specdo init claude`.
+- **BREAKING**: removed the `specdo-init` workflow skill. `init` is a
+  bootstrap action the agent invokes once — a dedicated skill for it added
+  no recall value and duplicated `README` content. The workflow skill set
+  is now 5 (explore / propose / apply / sync / archive).
+- **BREAKING**: removed the `-y` / `--yes` flag from `specdo init`. The
+  community-fallback prompt for unknown agents is now strictly interactive;
+  in non-interactive shells, invoke `specdo init universal` explicitly
+  instead. This removes a redundant code path — the explicit positional
+  form is shorter, discoverable through `--help`, and harder to misuse.
+- **Progressive disclosure**: each exported skill is now a directory rather
+  than a single file. `SKILL.md` (≤ 80 lines) carries the metadata, trigger
+  phrases, and the most actionable snippets; `references/*.md` carries the
+  full command matrix / exit-code tables (workflow), the full checklist /
+  patterns / cross-domain notes (domain), and the full per-step workflow /
+  output contract / do-don't code examples (protocol). Agents load
+  reference material on demand, saving context window.
+- **Strict-validation guarantee**: `specdo/` is created **only** after the
+  agent argument is fully validated. A typo, unknown agent, or `'all'`
+  leaves the filesystem untouched (exit 2). Fix the command and re-run to
+  actually initialize. This replaces the brief "skeleton-first" behaviour
+  that shipped in a previous unreleased commit — the new contract is
+  cleaner because users get a single, atomic init outcome instead of a
+  partially-initialized workspace they have to reason about.
+- **Interactive universal-fallback prompt**: when an unknown agent has no
+  close Levenshtein match and stdin is a TTY, SpecDo asks `Install skills
+  to the community fallback (.agents/skills/) instead? [y/N]`. Answering
+  `y` initializes the workspace and writes universal skills in one shot.
+  Any other reply aborts cleanly with nothing on disk. Non-interactive
+  shells (CI, piped stdin, `CI=1`, `SPECDO_NON_INTERACTIVE=1`) skip the
+  prompt and exit 2 with a short hint pointing to `specdo init universal`.
+  The error text no longer asks users to retype a magic `universal` token
+  implicitly — either the prompt or the explicit positional form resolves it.
+- `specdo init <agent>` is safe to re-run on already-initialized projects:
+  it enters **refresh mode**, repairs any missing skeleton pieces in place
+  (sub-directories, `.gitkeep` files), and re-renders SKILL.md and
+  references files. `config.yaml` is preserved — user edits are never
+  overwritten.
+- `'all'` and the universal `agents` keyword are intentionally rejected.
+  Users must enumerate every IDE target explicitly so that a typo never
+  fans out across the whole machine.
+- Tools deliberately excluded after audit: Continue.dev (no directory-based
+  skill loading), Windsurf (`.windsurfrules` is rules injection, not skills),
+  Aider (no canonical directory). They may be added later if upstream
+  evolves toward a SKILL.md-style mechanism.
+
+## [1.0.1] - 2026-06-03
+
+### Added
+
+- Self-contained `specdo` CLI for spec-driven development with six built-in domains:
+  `security`, `architecture`, `operations`, `backend`, `quality`, `frontend`
+- End-to-end workflow commands: `init`, `explore`, `propose`, `apply`, `sync`,
+  `validate`, `archive`, plus inspection commands `list`, `show`, `status`,
+  `domains`, `doctor`
+- Atomic `context.json` persistence with lock file protection, `.bak` recovery,
+  and stable `--json` output contracts for automation
+- Domain overrides through `specdo/config.yaml`, including per-stage disable,
+  list extension/replacement, and pattern overrides
+- Hash-based spec promotion from `specdo/changes/<name>/specs/` into
+  `specdo/specs/`, including `--force` backups and conflict tracking
+- Repository documentation under `docs/reference/` covering commands,
+  architecture, and methodology
+- Release verification chain with lint, `tsc --noEmit`, tests, packed CLI
+  verification, and install/run smoke coverage
+
+### Fixed
+
+- Release smoke now validates generated `proposal.md`, `design.md`, `tasks.md`,
+  and `apply-brief.md` structure before switching to deterministic sync/archive fixtures
+- Packed tarballs now ship the referenced `docs/reference/` files so installed
+  `README.md` / `CHANGELOG.md` links resolve inside the package
+- `sync` clears stale `forcedConflicts` / `forcedConflictHashes` after a clean
+  run or an unresolved conflict, so `context.json.sync` reflects the current state
+
+### Security
+
+- Atomic writes and recovery snapshots reduce the chance of corrupted workflow state
+- Sync conflict backups protect canonical specs during `--force` overwrites
+- Path validation and structured workspace layout limit accidental file traversal

package/README.md

@@ -0,0 +1,308 @@
+<div align="center">
+
+# SpecDo
+
+**Turn ideas into production-ready deliverables through structured specifications, domain expertise, and evidence-backed execution.**
+
+[![npm version](https://img.shields.io/npm/v/specdo.svg)](https://www.npmjs.com/package/specdo)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Node.js](https://img.shields.io/badge/node-%E2%89%A5%2020.19-brightgreen)](https://nodejs.org)
+
+</div>
+
+> [中文](README.zh-CN.md)
+
+---
+
+<p align="center">
+  <img src="./assets/specdo-architecture.png" alt="SpecDo Architecture" width="100%">
+</p>
+
+
+## Why SpecDo?
+
+Most AI coding workflows stop at code generation.
+
+SpecDo focuses on **delivery**.
+
+Instead of asking an AI to "build something", SpecDo guides both humans and AI agents through a structured, evidence-backed workflow:
+
+```text
+Explore → Propose → Apply → Sync → Archive
+```
+
+Every step produces artifacts that can be reviewed, versioned, audited, and improved.
+
+- **Local-first** — runs on your machine, works with any AI coding tool
+- **Agent-driven discovery** — your AI agent grills you with domain-specific questions (at least 8, typically 10–30 per change) before generating proposals
+- **Full domain coverage** — all six engineering domains inject checklists at every stage, even domains you didn't explicitly discuss
+- **Evidence-backed** — tasks require proof before archival; every change leaves an audit trail
+- **Project-customizable** — override any domain stage with your team's standards via `config.yaml`
+
+
+
+---
+
+## Core Concepts
+
+SpecDo is built on three primitives.
+
+### Workflow
+
+A closed-loop pipeline that carries every change from idea to archived evidence:
+
+```text
+explore → propose → apply → sync → archive
+```
+
+Each stage produces immutable artifacts — `proposal.md`, `design.md`, `tasks.md`, `specs/`, `apply-brief.md` — that together form the **source of truth** for the change.
+
+### Domain Knowledge Engine
+
+Six built-in domain modules inject stage-appropriate expertise at every step. Under the hood, each domain is a typed `DomainModule` constant — statically compiled into TypeScript, not loaded from files at runtime.
+
+| Domain | Focus |
+|--------|-------|
+| **Security** | Threats, risks, OWASP Top 10, auth, encryption, input validation |
+| **Architecture** | System boundaries, API design, ADRs, integration patterns |
+| **Operations** | Release management, CI/CD, observability, dependency upgrades |
+| **Backend** | Data models, query optimization, migrations, error handling |
+| **Quality** | TDD, code review, debugging, performance profiling |
+| **Frontend** | Components, a11y, Core Web Vitals, responsive design |
+
+Each domain provides **4 stages of pre-authored knowledge**:
+
+```
+explore   → signals (trigger keywords) + clarifying questions
+design    → checklists + patterns + anti-patterns
+implement → focus areas + patterns + common mistakes
+verify    → verification gates before archival
+```
+
+> **Key design choice**: `--domains` controls which domains you **ask questions about** during explore. `propose` always injects **all 6 domains' checklists** into design.md and tasks.md. `apply` matches domains dynamically per task via signal scoring, falling back to the domains used during propose.
+
+### Protocols
+
+Beyond "what to focus on" (domains), SpecDo defines "how to execute" (protocols):
+
+- **review-to-solid** — a 7-step cyclic hardening workflow: scope → audit → findings → fix → re-review → converge, with P1/P2/P3 severity grading and a mandatory Delta Table output.
+
+Protocols are injected into `apply-brief.md` when the quality domain is active.
+
+---
+
+## Quick Start
+
+```bash
+# 1. Install (Node.js ≥ 20.19)
+npm install specdo -g
+
+# 2. Initialize -- creates config.yaml + exports AI agent skills
+specdo init claude
+
+# 3. Explore -- capture a change idea (use --domains to focus questions)
+specdo explore "Add rate limiting to the public API" --domains backend
+
+# 4. Propose -- generate proposal, design, tasks, and specs
+specdo propose --change add-rate-limiting-to-the-public-api
+
+# 5. Apply -- start the TDD execution loop
+specdo apply --change add-rate-limiting-to-the-public-api
+specdo apply --change add-rate-limiting-to-the-public-api --done 1.1 --evidence "middleware added, tests passing"
+
+# 6. Sync -- promote specs into the canonical library
+specdo sync --change add-rate-limiting-to-the-public-api
+
+# 7. Archive -- finalize with evidence trail
+specdo archive --change add-rate-limiting-to-the-public-api
+```
+
+---
+
+## Workflow Outputs
+
+A complete SpecDo change produces these artifacts:
+
+```text
+specdo/changes/<name>/
+├── context.json       ← single source of truth (atomic writes)
+├── proposal.md        ← why + scope + risks
+├── design.md          ← how (all 6 domain checklists injected)
+├── tasks.md           ← ordered, numbered task list (drives apply)
+├── apply-brief.md     ← TDD execution guide with domain focus areas
+└── specs/             ← change-scoped spec drafts
+```
+
+---
+
+## Project Structure
+
+```text
+specdo/
+├── config.yaml        # domain overrides + project settings
+├── changes/           # active in-flight changes
+├── specs/             # canonical specification library
+└── archive/           # completed changes with evidence trail
+```
+
+`context.json` uses write-temp → fsync → rename with `.bak` snapshots and advisory file locking — zero external dependencies.
+
+---
+
+## AI Agent Integration
+
+SpecDo exports itself as **progressive-disclosure skill packages** — 5 `SKILL.md` files with `references/` — into 8 canonical AI tools:
+
+| Agent | Project path | Global path |
+|-------|-------------|-------------|
+| `claude` | `.claude/skills/` | `~/.claude/skills/` |
+| `qoder` | `.qoder/skills/` | `~/.qoder/skills/` |
+| `cursor` | `.cursor/skills/` | `~/.cursor/skills/` |
+| `cline` | `.cline/skills/` | `~/.cline/skills/` |
+| `codex` | `.codex/skills/` | `~/.codex/skills/` |
+| `goose` | `.goose/skills/` | `~/.goose/skills/` |
+| `kilo` | `.kilo/skills/` | `~/.kilo/skills/` |
+| `opencode` | `.opencode/skills/` | `~/.opencode/skills/` |
+
+Typo correction (`clude` → `claude`) and unknown-agent fallback (`.agents/skills/`) are built in. SpecDo never touches your `AGENTS.md` or `CLAUDE.md`.
+
+### Exported skills
+
+| Skill | Purpose |
+|-------|---------|
+| `specdo-explore` | Agent-driven discovery with grill-me methodology |
+| `specdo-propose` | Render proposal / specs / design / tasks with full domain injection |
+| `specdo-apply` | TDD execution loop with per-task evidence |
+| `specdo-sync` | Promote specs into canonical `specdo/specs/` |
+| `specdo-archive` | Finalize with evidence trail and audit summary |
+
+---
+
+## Customization
+
+SpecDo ships with built-in best practices for all 6 domains. Use
+`specdo/config.yaml` to layer your team's own standards **on top** —
+no source-code changes needed.
+
+### Quick reference
+
+| Dimension | Options |
+|-----------|---------|
+| **Domain** | `security` `architecture` `backend` `quality` `frontend` `operations` |
+| **Stage** | `explore` `design` `implement` `verify` |
+| **List fields** | `questions` `checklist` `focusAreas` `antiPatterns` |
+| **Actions** | `prepend` (insert at head) `append` (append to tail) `replace` (replace entire list) |
+| **Special** | `enabled: false` (disable a stage) `patterns` (key-value map; same key overwrites, new key appends) |
+
+### Full example
+
+```yaml
+# specdo/config.yaml
+domainVersion: "1.0"
+overrides:
+  security:
+    explore:
+      questions:
+        - prepend: "[ORG] Is SOC2 compliance required?"
+        - append: "[ORG] Has the last pentest report been resolved?"
+    design:
+      checklist:
+        - prepend: "Validate against internal threat model TM-001"
+        - append: "Sign-off from #sec-review channel"
+    verify:
+      enabled: false                          # disable the entire verify stage for security
+
+  architecture:
+    design:
+      checklist:
+        - replace: "[ORG] Follow RFC-0421 micro-frontend boundary rules"
+      patterns:
+        "Modular Monolith (default)": "[ORG] Mono-first + company module boundary spec"
+        "[ORG] Event-driven CQRS": "Use Kafka + company event schema registry"
+
+  backend:
+    implement:
+      focusAreas:
+        - append: "[ORG] All migrations must use the internal db-migrate-safe tool"
+      antiPatterns:
+        - append: "[ORG] Never concatenate user input into ORM raw queries"
+
+  quality:
+    implement:
+      patterns:
+        "Property-based testing": "Use fast-check for parser fuzz"
+
+  operations:
+    verify:
+      checklist:
+        - append: "[ORG] Announce releases in #sre-release channel before deploy"
+```
+
+### Action rules
+
+| Rule | Detail |
+|------|--------|
+| One action per item | Each override item must contain exactly one of `prepend`, `append`, or `replace` |
+| No mixing in one field | A single field cannot combine `replace` with `prepend`/`append` items |
+| Unknown domain or stage | Zod schema validation fails; `specdo validate` reports the error |
+| Unknown field | Caught by `strict()` — silently rejected with no effect |
+
+### Verify your overrides
+
+```bash
+# Inspect a resolved domain after overrides are applied
+specdo domains show security
+
+# Validate config.yaml correctness
+specdo validate
+```
+
+---
+
+## All Commands
+
+### Workflow
+
+| Command | What it does |
+|---------|-------------|
+| `init <agent>[,<agent>...]` | Create workspace + `config.yaml` + export skills |
+| `explore [idea]` | Agent-driven discovery: `--domains`, `--context`, `--depth` |
+| `propose --change <n>` | Render proposal / design / tasks / `specs/<capability>/spec.md` |
+| `apply --change <n>` | Execution brief; `--done 1.1 --evidence "..."` marks progress |
+| `sync --change <n>` | Promote change specs into canonical `specdo/specs/` |
+| `archive --change <n>` | Validate completeness + move to `specdo/archive/` |
+
+### Inspection
+
+| Command | What it does |
+|---------|-------------|
+| `list [--specs\|--archived] [--json]` | List changes, specs, or archived entries |
+| `show <name> [--type spec] [--json]` | Display change details or resolve specs |
+| `status [--change <n>] [--json]` | Stage progress for one or all changes |
+| `validate [--change <n>] [--json]` | Schema + cross-reference + tasks consistency |
+| `domains list\|show <name>` | Inspect resolved domain definitions |
+| `doctor [--deep] [--json]` | Workspace health check |
+
+All inspection commands support `--json` for automation.
+
+---
+
+## Development
+
+```bash
+pnpm install
+pnpm test                # vitest (521 tests)
+pnpm run build           # TypeScript → dist/
+pnpm run release:check   # full pipeline: lint + tsc + test + pack + smoke
+```
+
+Runtime dependencies: `chalk`, `commander`, `yaml`, `zod` — nothing else.
+
+---
+
+## Acknowledgments
+
+SpecDo is adapted from [OpenSpec](https://github.com/Fission-AI/OpenSpec), a specification-driven development framework. We're grateful to the OpenSpec authors for establishing the core `changes/` → `specs/` → `archive/` workflow paradigm that SpecDo builds upon.
+
+---
+</div>