@chongyan/autospec 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AutoSpec 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.en.md

@@ -0,0 +1,472 @@
+<div align="center">
+
+# AutoSpec
+
+**Autonomous Software Development Pipeline — AI drives the full cycle, humans stay on the loop.**
+
+[中文文档](./README.md) · [Quick Start](#quick-start) · [How It Works](#how-it-works) · [Contributing](./CONTRIBUTING.md)
+
+</div>
+
+---
+
+AutoSpec is an AI-driven development pipeline that automates the entire software delivery process — from requirement analysis to deployment. Instead of replacing developers, it structures the AI's work through a rigorous, verifiable pipeline with constitutional safety guards.
+
+**Not "AI writes code faster" — but "AI autonomously completes the full SDLC with human oversight at key decision points."**
+
+## Key Principles
+
+- **Verification over trust** — Deterministic validation (build/test/lint) before AI review. Never skip, never fake.
+- **Do-review separation** — Producer and reviewer are different AI instances with information isolation.
+- **Constitutional safety** — 13 inviolable red lines. Irreversible actions always require human confirmation.
+- **Progressive autonomy** — Start with interactive mode, earn trust, scale to autonomous mode.
+
+## Quick Start
+
+```bash
+# Install globally
+npm install -g @chongyan/autospec
+
+# Initialize in your project
+cd your-project
+autospec init
+
+# Start full pipeline in Claude Code
+/autospec:run
+/autospec:run Build a user favorites feature with category filtering
+```
+
+That's it. AutoSpec copies the knowledge to `.autospec/knowledge/`, generates Claude Code slash commands (8), Skills (9, auto-triggered), Agents (8, do-review separation + CEO debate + autonomous gates), and Hooks (8, deterministic guards + quality monitoring + scope sentinel + AI validation) — ready to use.
+
+## How It Works
+
+### Pipeline
+
+```
+[Stage 0]  →  Requirement  →  Design  →  Implementation  →  Review  →  Testing  →  Delivery
+ Env Check     Analysis       Planning   (+ quick test)      (isolated)   QA         Deploy
+                  ↓              ↓            ↓                ↓          ↓           ↓
+              [Layer 1]     [Layer 1]    [Layer 1]         [Layer 1]  [Layer 1]   [Layer 1]
+              [Layer 2]     [Layer 2]    [Layer 2]         [Layer 2]  [Layer 2]   [Layer 2]
+```
+
+**Every stage** passes through double-layer validation:
+- **Layer 1** (Deterministic): Build, test, lint, type-check — machine judgment, non-negotiable
+- **Layer 2** (AI Review): Independent AI instance evaluates with structured evidence
+
+Layer 1 fails → Layer 2 never runs.
+
+### Testing Stage Enhancement
+
+AutoSpec's testing is divided into two phases with clear responsibilities:
+
+**Implementation Stage (Stage 03) - Self-testing**:
+- Unit tests: Core logic paths + boundary conditions
+- Module-level integration tests: Inter-module interactions
+- Learns existing test styles, reuses test infrastructure
+- Generates test report
+
+**QA Testing Stage (Stage 05)**:
+- Cross-system integration tests
+- E2E tests
+- Acceptance tests
+- Learns existing test styles + loads environment knowledge best practices
+
+**Test Style Learning**:
+1. Detects test frameworks (Jest, pytest, JUnit, etc.)
+2. Analyzes assertion styles and organization
+3. Extracts test infrastructure (setup/teardown, fixtures, mocks)
+4. Loads integration test best practices from environment knowledge
+
+**Environment Knowledge for Testing**:
+- Test knowledge stored in `knowledge/environment/overview.md`
+- Free Markdown format (not structured YAML) for flexibility
+- Self-evolution via skill-distiller: learns from test execution patterns
+- Import organization knowledge via `autospec env:import`
+
+### CEO Exploration (Requirement Analysis Pre-step)
+
+Before requirement analysis, AutoSpec uses dual-agent debate to clarify requirements:
+
+- **ceo**: Explores from CEO/strategy perspective (business value, strategic alignment)
+- **product-owner**: Challenges from product feasibility angle (UX, scope, data-driven decisions)
+
+**Autonomous mode**: Agents debate automatically → consensus becomes requirement, disagreements marked for clarification
+
+**Interactive mode**: AI asks 5 strategic questions with recommended answers → user confirms
+
+### Iteration Modes
+
+| Mode | Stages | Description | Use Case |
+|------|--------|-------------|----------|
+| **Waterfall** | 01→02→03→04→05→06 | Full 6-stage pipeline | New features, major changes |
+| **Agile** | 01 + [02→03→04]×N + 05→06 | Story-driven cycles | Iterative development |
+| **Experiment** | 01→02→03 + Evaluation | Prototype + AI/ML evaluation | Technical exploration |
+| **Hotfix** | 01→03→04→06 | Fast track with basic tests | Emergency fixes |
+
+## Slash Commands
+
+All commands accept optional text arguments: `/autospec:run Build user favorites` — the text becomes context for that stage.
+
+### Main Entry (Autonomous Mode)
+
+| Command | Description |
+|---------|-------------|
+| `/autospec:run` | Full pipeline autonomous execution (recommended) |
+
+Run with parameters:
+```
+/autospec:run Build user favorites --workflow=agile
+```
+
+**Parameters:**
+| Parameter | Shorthand | Description |
+|-----------|-----------|-------------|
+| `--workflow` | `-w` | Iteration mode: waterfall/agile/experiment/hotfix |
+| `--roles` | `-r` | Roles (comma-separated): backend,frontend,data,ai,quality |
+| `--domain` | `-d` | Business domain (free text): e.g., "fintech payment system" |
+| `--skip-workflow` | `-s` | Skip workflow selection, use default |
+| `--help` | `-h` | Show help |
+
+### Interactive Mode (Stage-by-Stage Commands)
+
+| Command | Description |
+|---------|-------------|
+| `/autospec:explore` | Requirement exploration |
+| `/autospec:propose` | Design planning |
+| `/autospec:apply` | Implementation (code + review + testing) |
+| `/autospec:archive` | Delivery + archival |
+
+### Recommended Workflow
+
+For better results, explore requirements first, then run:
+
+1. `/autospec:explore` → Clarify and explore requirements
+2. Feed exploration results → `/autospec:run <exploration context>`
+
+This ensures the AI understands the requirements accurately before autonomous execution.
+
+**Direct run is also supported**: Running `/autospec:run` directly — the AI will use internal agent debate to clarify requirements automatically, though results may be less precise than exploring first.
+
+### Command Output Examples
+
+#### `/autospec:run` Output Flow
+```
+┌─────────────────────────────────────────────────────────────┐
+│  AutoSpec Pipeline                                          │
+├─────────────────────────────────────────────────────────────┤
+│  ✓ Stage 01: Requirement Analysis     [Layer 1 ✓] [Layer 2 ✓] │
+│  ✓ Stage 02: Design Planning          [Layer 1 ✓] [Layer 2 ✓] │
+│  ✓ Stage 03: Implementation           [Layer 1 ✓] [Layer 2 ✓] │
+│  ✓ Stage 04: Code Review              [Layer 1 ✓] [Layer 2 ✓] │
+│  ✓ Stage 05: QA Testing               [Layer 1 ✓] [Layer 2 ✓] │
+│  ✓ Stage 06: Delivery                 [Layer 1 ✓] [Layer 2 ✓] │
+├─────────────────────────────────────────────────────────────┤
+│  Pipeline completed successfully!                           │
+│  Output: .autospec/specs/{feature}/                        │
+└─────────────────────────────────────────────────────────────┘
+```
+
+#### `/autospec:status` Output
+```
+┌─────────────────────────────────────────────────────────────┐
+│  AutoSpec Status                                           │
+├─────────────────────────────────────────────────────────────┤
+│  Current Stage: Stage 03 (Implementation)                 │
+│  Progress: 3/6 stages completed                          │
+│  Workflow: waterfall                                      │
+│  Last updated: 2024-01-15 10:30:00                       │
+└─────────────────────────────────────────────────────────────┘
+```
+
+#### Layer 1 Failure Example
+```
+┌─────────────────────────────────────────────────────────────┐
+│  Layer 1 Validation FAILED                                 │
+├─────────────────────────────────────────────────────────────┤
+│  ✗ npm run build    → Exit code 1                         │
+│  ✗ npm test        → 3 tests failed                       │
+│                                                                     │
+│  BLOCKED: Fix above issues before proceeding to Layer 2   │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Utilities
+
+| Command | Description |
+|---------|-------------|
+| `/autospec:status` | Pipeline progress and state |
+| `/autospec:validate` | Run Layer 1 validation (build/test/lint) |
+| `/evolve` | Trigger self-evolution cycle |
+
+## CLI Commands
+
+```bash
+autospec init [options]    # Initialize framework + slash commands
+autospec status            # Check pipeline state
+autospec update            # Update framework (preserve state)
+```
+
+**Init options:**
+```bash
+# Default: waterfall mode + generic domain
+autospec init
+
+# Specify iteration mode and roles
+autospec init -w hotfix -r backend        # Hotfix mode, backend role
+autospec init -w agile -r backend,frontend  # Agile mode, multi-role
+
+# Specify domain
+autospec init -d fintech -r backend,data  # Fintech domain, backend + data roles
+
+# Full options
+autospec init -w experiment -d ai -r backend,ai  # AI project
+```
+
+**Options:**
+| Option | Shorthand | Description | Values |
+|--------|-----------|-------------|--------|
+| `--workflow` | `-w` | Iteration mode | `waterfall`, `agile`, `experiment`, `hotfix` |
+| `--domain` | `-d` | Business domain (free text) | e.g., "fintech", "ecommerce", "healthcare" |
+| `--roles` | `-r` | Project roles | Comma-separated: `backend`, `frontend`, `data`, `ai`, `quality` |
+
+### Environment Integration Commands
+
+AutoSpec automatically detects middleware and components during `init`. Manage environment knowledge with:
+
+```bash
+autospec env                      # Show environment configuration
+autospec env:sync                 # Sync from code + auto-activate
+autospec env:validate             # Validate configuration
+autospec env:import --git <url>   # Import org knowledge from Git
+autospec env:import --npm <pkg>   # Import org knowledge from npm
+autospec env:export <dir>         # Export project knowledge
+autospec component                # List available components
+autospec component:add <name>     # Add component knowledge
+```
+
+**Auto-detection**: `autospec init` automatically scans code for MySQL, Redis, Kafka, MongoDB, Elasticsearch, RabbitMQ, PostgreSQL usage and generates knowledge configs. See [Environment Integration](knowledge/environment/overview.md) for details.
+
+## Self-Evolution
+
+AutoSpec improves itself through a controlled evolution loop.
+
+### Two-Layer Evolution
+
+AutoSpec's self-evolution happens on two levels simultaneously:
+
+#### Outward Evolution (Project Evolution)
+
+When using AutoSpec to drive **other projects**, practical experience automatically feeds back:
+
+```
+Project A development → practice-log → distiller extracts new skill → framework improves
+Project B development → practice-log → extractor extracts methodology → framework improves
+Project C development → domain skill accumulation → skills/domain/ expands
+        ↓
+Every project's experience makes the next project smoother
+```
+
+- Each project's practice-log can optionally contribute back to AutoSpec main repo (via PR)
+- Domain-specific skills stay in enterprise overlay (not upstreamed)
+- General improvements (pipeline optimization, skill improvements) contribute back to core framework
+
+#### Inward Evolution (Framework Evolution)
+
+When iterating on AutoSpec **itself**, the framework uses its own process to improve (dogfooding):
+
+```
+AutoSpec improvement需求 → Run AutoSpec pipeline → practice-log → framework evolves
+                                              ↓
+                          Same iteration is both output and evolution signal
+```
+
+- AutoSpec's own development follows startup gate and double-layer validation
+- Framework file changes must be validated through the framework's own review process
+- The framework gets better with use, forming a flywheel effect
+
+### Evolution Zones
+
+| Zone | Contents | Rule |
+|------|----------|------|
+| **Frozen** | Constitution, evolution rules, core principles | Human-only changes. Never auto-modified. |
+| **Controlled** | Pipeline stages, universal skills, role profiles | Auto-proposed, human-approved. |
+| **Free** | Domain skills, decision trees, benchmarks | Auto-evolved, validator-verified. |
+
+**Test knowledge evolution**: Test knowledge in `environment/integration/testing/` evolves via skill-distiller — learns from test execution patterns, generates proposals for human approval.
+
+**Key safety principle**: The evolution system cannot modify its own evaluation criteria (immutable harness).
+
+### Evolution Loop
+
+```
+Execute Pipeline → Collect Signals → Analyze Patterns → Propose Changes → Validate → Accept/Reject
+                                                                              ↓
+                                                           Regression? → Auto-rollback
+```
+
+**Fitness function**: Layer 1+2 pass rate, retry count, human intervention rate, delivery success rate. Any safety metric regression → change rejected even if other metrics improve.
+
+### Enterprise Adaptation
+
+```
+┌─────────────────────────────────┐
+│     Enterprise Overlay          │  ← Org-specific (not upstreamed)
+│  org-constitution.md            │     Additional red lines
+│  org-skills/                    │     Domain-specific skills
+│  domain-knowledge/              │     Industry knowledge
+├─────────────────────────────────┤
+│     AutoSpec Core Framework     │  ← npm install (upgradeable)
+│  constitution.md                │
+│  pipeline/ skills/ roles/ ...   │
+└─────────────────────────────────┘
+```
+
+Customize via `autospec init --domain <domain>`. The overlay adds domain-specific rules, checklists, and skills **without forking** the core framework.
+
+## Project Structure
+
+```
+your-project/
+├── .autospec/
+│   ├── knowledge/          # Core knowledge (copied from npm)
+│   ├── runtime/            # Current pipeline state
+│   │   ├── config.json     # Project configuration
+│   │   ├── state.json      # Pipeline state tracking
+│   │   └── metrics.json    # Quality metrics (auto-collected)
+│   ├── environment/        # Environment integration layer
+│   │   ├── env-knowledge/  # Middleware knowledge (mysql.yaml, redis.yaml)
+│   │   ├── component-lib/  # Organization components
+│   │   ├── integration/    # CI/CD, testing, deployment configs
+│   │   └── registry.json   # Knowledge registry
+│   ├── specs/              # Pipeline artifacts (persistent)
+│   │   └── {feature}/      # Per-feature outputs
+│   │       ├── requirement.md
+│   │       ├── design.md
+│   │       ├── contracts/
+│   │       ├── reviews/
+│   │       └── tests/
+│   ├── archives/           # Archived pipeline runs
+│   └── evolution/          # Self-evolution data
+│       ├── proposals/      # Evolution proposals (human-approved)
+│       ├── practice-log/   # Practice logs
+│       └── evolution-log.json  # Evolution audit trail
+└── .claude/
+    ├── commands/
+    │   └── autospec/       # 8 slash commands (auto-generated)
+    │       ├── run.md      # Main entry with mode picker
+    │       ├── explore.md  # Big-phase: exploration
+    │       ├── propose.md  # Big-phase: design
+    │       ├── apply.md    # Big-phase: implementation
+    │       ├── archive.md  # Big-phase: delivery
+    │       ├── status.md   # Utility: state view
+    │       ├── validate.md # Utility: Layer 1 validation
+    │       └── evolve.md   # Utility: self-evolution
+    ├── skills/             # Auto-triggered skills
+    ├── agents/             # Isolated agents (reviewer/test-reviewer/...)
+    └── settings.json       # Hooks configuration
+```
+
+**AutoSpec source:**
+```
+autospec/
+├── knowledge/              # The core knowledge
+│   ├── constitution.md     # 13 constitutional red lines
+│   ├── evolution.md        # Self-evolution mechanism
+│   ├── pipeline/           # 6-stage process definitions
+│   ├── methodology/        # Design principles + checklists + cognitive enhancement
+│   ├── skills/             # Executable AI skills (do + review)
+│   ├── roles/              # Role profiles (backend/frontend/data/ai/quality)
+│   ├── environment/        # Environment integration protocol
+│   ├── config/             # Configuration files (validation patterns, team triggers)
+│   └── hooks/              # Hook scripts (deterministic guards)
+├── src/                    # CLI tool source
+│   └── core/
+│       ├── environment/    # Environment detection & knowledge management
+│       ├── generators/     # Code generators (commands, skills, agents, hooks)
+│       ├── templates/      # Template files (moved from root templates/)
+│       └── test/           # Test infrastructure
+├── bin/                    # CLI entry point
+└── docs/                   # Package documentation
+```
+
+## Safety Model
+
+AutoSpec enforces safety through four layers:
+
+1. **Constitutional Gate** — 13 red lines that cannot be violated (see `knowledge/principles/constitution.md`)
+2. **Permission Control** — Each agent only accesses its authorized tools
+3. **Stop-the-Line** — Security vulnerability, data loss risk, or 3 failed retries → immediate halt
+   - **Precision Retry**: Level 1 (inline retry) → Level 2 (fix loop, max 3 times) → Level 3 (escalate to human)
+4. **Irreversible Action Guard** — DB migrations, deployments, external API calls → require human confirmation
+
+Evolution adds a fifth layer:
+
+5. **Immutable Harness** — The evolution system cannot modify its own evaluation criteria, constitution, or evolution rules
+
+## Quality Monitoring
+
+AutoSpec automatically tracks quality metrics during pipeline execution via deterministic hooks:
+
+| Metric | Source | Purpose |
+|--------|--------|---------|
+| Layer 1 pass/fail rate | `layer1-validator` hook | Code quality baseline |
+| Retry count per stage | `layer1-validator` hook | Process smoothness |
+| Human intervention count | `layer1-validator` hook | Autonomy capability |
+| Scope deviation events | `scope-sentinel` hook | Implementation discipline |
+| Error patterns | `layer1-validator` hook | Evolution priority |
+
+Metrics are stored in `.autospec/runtime/metrics.json` and automatically fed into practice-log at delivery.
+
+## Cognitive Enhancement
+
+AutoSpec injects 10 cognitive enhancement principles ([`knowledge/principles/principles.md`](knowledge/principles/principles.md)) into each pipeline stage:
+
+| Principle | Stage Application |
+|-----------|------------------|
+| **CP1** Partner mode — challenge assumptions, flag blind spots | Requirement, Review, Test |
+| **CP3** Ask before act — structured uncertainty management | Requirement, Design |
+| **CP4** Complete logic chain — no conclusion without derivation | Design, Review |
+| **CP5** Confidence labeling — mark uncertain judgments | All stages |
+| **CP6** Error as signal — every retry/correction drives evolution | Test, Evolve |
+| **CP8** Deviation detection — graduated 3-level alerts | Implementation, Delivery |
+| **CP9** Just enough — resist overengineering | Design, Implementation |
+| **CP10** Self-check before output | Implementation, Test, Delivery |
+
+## Documentation
+
+| Document | Description |
+|----------|-------------|
+| [Design Philosophy](docs/design-philosophy.md) | Why AutoSpec exists, core principles, design decisions |
+| [Architecture](docs/architecture.md) | How it works — pipeline, validation, integration, evolution |
+| [Getting Started](docs/getting-started.md) | Practical guide from install to first full pipeline run |
+| [Comparisons](docs/comparisons.md) | Detailed comparison with OpenSpec, Spec Kit, autoresearch, Claude Code |
+| [Environment Integration](knowledge/environment/overview.md) | Middleware detection, knowledge management, org knowledge import |
+
+## Design Philosophy
+
+See [`knowledge/principles/design-philosophy.md`](knowledge/principles/design-philosophy.md) for the complete 18 design principles (DP1–DP18), including:
+
+- **DP1** Double-layer verification
+- **DP2** Do-review separation
+- **DP6** Precision retry (not full redo)
+- **DP7** Anti-pattern inoculation
+- **DP8** CSO principle (force full skill loading)
+- **DP10** Safety & emergency stop
+- **DP12** Taming non-determinism
+- **DP16** Template-as-Constraint (shift-left quality)
+- **DP17** Structured clarification protocol
+- **DP18** Cross-artifact consistency analysis
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md). We welcome contributions to:
+- Framework pipeline and skill definitions
+- Role profiles for new domains
+- CLI tooling improvements
+- Practice log entries from real usage
+- Documentation and translations
+
+## License
+
+[MIT](./LICENSE)