@chongyan/autospec 1.0.1 → 1.0.2

package/README.en.md

@@ -4,87 +4,202 @@
 
 **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)
+[中文文档](./README.md) · [Quick Start](#quick-start) · [Core Principles](#core-principles) · [How It Works](#how-it-works) · [Knowledge Structure](#knowledge-structure) · [Contributing](./CONTRIBUTING.md)
 
 </div>
 
 ---
 
+## One-Sentence Value
+
 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
+## Key Features
+
+| Feature | Description |
+|---------|-------------|
+| **AI Autonomous Development** | Full pipeline from requirements to deployment |
+| **Double-Layer Validation** | Deterministic verification → AI review |
+| **Do-Review Separation** | Different AI instances, information isolation |
+| **Constitutional Safety** | 15 red lines, irreversible actions require human confirmation |
+| **Self-Evolution** | Practical experience feeds back, continuous improvement |
+
+---
+
+## Vision & Mission
+
+### Vision
+
+**Make AI a reliable development partner, unleashing human creativity.**
+
+We believe AI should not replace humans, but become humanity's most reliable collaboration partner. By taking on repetitive, deterministic R&D work, AI frees humans from tedious coding tasks, allowing us to focus on high-value work that truly requires creativity and strategic thinking.
+
+### Mission
 
-- **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.
+**Build an autonomous automated product development framework, where AI drives the complete SDLC and humans focus on high-value decisions.**
+
+AutoSpec's mission is to achieve "Human On the Loop" rather than "Human In the Loop" collaboration model:
+- **AI Responsible For**: Requirement analysis, design planning, implementation, code review, testing verification, delivery deployment
+- **Human Responsible For**: Direction decisions, safety confirmation, value judgments, exception handling
+
+### Core Values
+
+| Value | Description |
+|-------|-------------|
+| **Verification First** | Deterministic verification > AI review > AI self-review |
+| **Minimal Viable Process** | One file if possible; 5-minute onboarding |
+| **Progressive Autonomy** | From "human reviews every step" to "human only manages harness" |
+| **Safety First** | 15 constitutional red lines, irreversible actions require human confirmation |
+| **Continuous Evolution** | Three-layer self-evolution system, practical experience automatically feeds back |
+
+---
 
 ## Quick Start
 
+### 1. Installation
+
 ```bash
 # Install globally
 npm install -g @chongyan/autospec
 
-# Initialize in your project
+# Verify installation
+autospec --help
+```
+
+**Requirements**: Node.js >= 18.0.0
+
+### 2. Initialize Project
+
+```bash
 cd your-project
 autospec init
+```
+
+**Init Options:**
+
+| Option | Shorthand | Description | Values |
+|--------|-----------|-------------|--------|
+| `--workflow` | `-w` | Iteration mode | `waterfall` (default), `agile`, `experiment`, `hotfix` |
+| `--roles` | `-r` | Roles | `backend`, `frontend`, `data`, `ai`, `quality` |
+| `--domain` | `-d` | Domain (free text) | `fintech payment`, `ecommerce`... |
+
+```bash
+# Default: waterfall + generic domain
+autospec init
+
+# Hotfix workflow + backend role
+autospec init -w hotfix -r backend
+
+# Agile workflow + backend/AI roles
+autospec init -w agile -r backend,ai
+
+# Fintech domain + backend/data roles
+autospec init -d "fintech payment" -r backend,data
+```
 
-# Start full pipeline in Claude Code
+### 3. Start Full Pipeline
+
+In Claude Code:
+
+```bash
 /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.
+> **Note**: `/autospec:run` already includes the complete requirement exploration phase (CEO alignment + requirement analysis), no need to run `/autospec:explore` separately.
 
-## How It Works
+### Execution Modes
 
-### Pipeline
+| Mode | Description | Use Case |
+|------|-------------|----------|
+| **Autonomous Mode** | Full pipeline auto-execution, AI makes decisions | Automated development, unattended |
+| **Interactive Mode** | Stage-by-stage execution, human confirmation required | Learning phase, complex projects, safety-critical |
+
+**Recommendation**: Start with interactive mode for first use, switch to autonomous mode after familiarizing with the workflow.
+
+---
+
+## Core Principles
+
+### The Triangular Prism: First Principles
 
 ```
-[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]
+        Verification-First
+       /                  \
+      /                    \
+  Minimal-Viable ——— Progressive-Autonomy
 ```
 
-**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
+#### Verification-First
+
+> "Accelerate the verification loop, not wait for models to improve." — Karpathy
+
+AI outputs are **inherimately non-deterministic**. You cannot trust its "I'm done" — only trust **verifiable evidence**.
+
+AutoSpec establishes a double-layer validation system:
+- **Layer 1 (Deterministic)**: Build, test, lint, type-check — machine judgment, non-negotiable
+- **Layer 2 (AI Review)**: Independent AI instance evaluation with structured evidence
 
 Layer 1 fails → Layer 2 never runs.
 
-### Testing Stage Enhancement
+#### Minimal-Viable Process
+
+> "Users should understand the structure and start using within 5 minutes." — Design Iron Rule
+
+Minimal doesn't mean cutting corners — it means **not doing unnecessary things**:
+- One file if possible, not two
+- Markdown if possible, not code
+- One workflow doesn't fit all — choose dynamically based on complexity
+- Build high-frequency capabilities in advance, build low-frequency when needed
+
+#### Progressive Autonomy
 
-AutoSpec's testing is divided into two phases with clear responsibilities:
+> "Human On the Loop — don't inspect outputs, engineer the harness." — Kief Morris
 
-**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
+Trust is earned, not given by default:
+- **Interactive Mode**: Confirm after each stage before proceeding
+- **Autonomous Mode**: Confirm at requirements, design, delivery; autonomous in between
 
-**QA Testing Stage (Stage 05)**:
-- Cross-system integration tests
-- E2E tests
-- Acceptance tests
-- Learns existing test styles + loads environment knowledge best practices
+When unsatisfied with outputs, **change the harness, not the outputs**.
 
-**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
+### Core Design Principles
 
-**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`
+See [`knowledge/01-principles/01-first-principles.md`](knowledge/01-principles/01-first-principles.md) for complete list.
 
-### CEO Exploration (Requirement Analysis Pre-step)
+| Principle | One-Liner |
+|-----------|-----------|
+| **DP1** Double-Layer Validation | Deterministic + AI review, Layer 1 must pass before Layer 2 |
+| **DP2** Do-Review Separation | Producer and reviewer are different AI instances with information isolation |
+| **DP6** Precision Retry | Retry only failed items, not full redo |
+| **DP8** CSO Principle | Skill description only writes trigger conditions, forcing full load |
+| **DP10** Safety & Emergency Stop | Four-layer safety + stop-the-line + irreversible guard |
+| **DP16** Template-as-Constraint | Structured templates constrain output, prevention over detection |
+| **DP17** Structured Clarification | 11-dimension scan + max 5 questions + AI recommended answers |
+| **DP18** Cross-Artifact Consistency | 6-dimension check: duplicate/ambiguity/spec-gap/constitution-align/coverage/term-drift |
+
+---
+
+## How It Works
+
+### Development 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]
+```
+
+**Double-Layer Validation**:
+- **Layer 1 (Deterministic)**: Build/test/lint/type-check — machine judgment, non-negotiable
+- **Layer 2 (AI Review)**: Independent AI instance with structured evidence review
+
+Layer 1 fails → Layer 2 never runs.
+
+### CEO Exploration Mechanism
 
 Before requirement analysis, AutoSpec uses dual-agent debate to clarify requirements:
 
@@ -101,372 +216,383 @@ Before requirement analysis, AutoSpec uses dual-agent debate to clarify requirem
 |------|--------|-------------|----------|
 | **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 |
+| **Experiment** | 01→02→03 + Evaluation | Prototype + AI evaluation | Technical exploration |
 | **Hotfix** | 01→03→04→06 | Fast track with basic tests | Emergency fixes |
 
-## Slash Commands
+---
+
+## Command System
 
-All commands accept optional text arguments: `/autospec:run Build user favorites` — the text becomes context for that stage.
+### Slash Commands (AI-Driven)
 
-### Main Entry (Autonomous Mode)
+#### Autonomous Mode (Recommended)
 
 | Command | Description |
 |---------|-------------|
-| `/autospec:run` | Full pipeline autonomous execution (recommended) |
-
-Run with parameters:
-```
-/autospec:run Build user favorites --workflow=agile
-```
+| `/autospec:run` | Full pipeline autonomous execution + workflow selection |
 
 **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 |
+| Parameter | Shorthand | Description | Values |
+|-----------|-----------|-------------|--------|
+| `--workflow` | `-w` | Iteration mode | `waterfall`, `agile`, `experiment`, `hotfix` |
+| `--roles` | `-r` | Roles | `backend`, `frontend`, `data`, `ai`, `quality` |
+| `--domain` | `-d` | Domain (free text) | `fintech payment system`... |
 
-### Interactive Mode (Stage-by-Stage Commands)
+#### Interactive Mode (Stage-by-Stage)
+
+| Command | Chinese | Description |
+|---------|---------|-------------|
+| `/autospec:explore` | "我先想想" | Requirement exploration (CEO alignment + analysis) |
+| `/autospec:propose` | "就这么干" | Design planning |
+| `/autospec:apply` | "开工，按单子做" | Implementation (code + review + testing) |
+| `/autospec:archive` | "做完了，收工" | Delivery + evolution archival |
+
+#### Evolution Commands
+
+| Command | Level | Description |
+|---------|-------|-------------|
+| `/self-evolve` | L1 Framework | AutoSpec framework's own iteration and upgrade |
+| `/autospec:field-evolve` | L2 Domain | Learn and extract capabilities from实战 projects |
+| `/autospec:project-evolve` | L3 Project | Project's own code, config, documentation optimization |
+
+#### Utility Commands
 
 | Command | Description |
 |---------|-------------|
-| `/autospec:explore` | Requirement exploration |
-| `/autospec:propose` | Design planning |
-| `/autospec:apply` | Implementation (code + review + testing) |
-| `/autospec:archive` | Delivery + archival |
+| `/autospec:status` | View pipeline progress |
+| `/autospec:test` | Unified test command (validate + fix + evaluate) |
+| `/autospec:memory` | Manage project memory system |
 
-### Recommended Workflow
+### CLI Commands
 
-For better results, explore requirements first, then run:
+```bash
+# Initialize
+autospec init                              # Default: waterfall + generic domain
+autospec init -w hotfix -r backend         # Hotfix workflow + backend role
+autospec init -w agile -r backend,ai       # Agile workflow + backend/AI roles
+autospec init -d "fintech payment" -r backend,data  # Fintech domain + backend/data roles
+
+# Status and update
+autospec list                              # List all slash commands
+autospec update                            # Update framework (preserve state)
+```
 
-1. `/autospec:explore` → Clarify and explore requirements
-2. Feed exploration results → `/autospec:run <exploration context>`
+### Environment Integration Commands
 
-This ensures the AI understands the requirements accurately before autonomous execution.
+`autospec init` automatically detects middleware and components in your project. Environment knowledge management commands:
 
-**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.
+```bash
+/autospec:env                      # View environment configuration
+/autospec:env-sync                 # Sync from code + auto-activate
+/autospec:env-validate             # Validate configuration completeness
+/autospec:env-export <dir>         # Export project knowledge base
+/autospec:component                # List available components
+```
 
-### Command Output Examples
+**Auto-detection**: `autospec init` automatically scans code for MySQL, Redis, Kafka, MongoDB, Elasticsearch, RabbitMQ, PostgreSQL usage, generates knowledge configs and activates them. See [Environment Integration Protocol](knowledge/06-environment/README.md) for details.
 
-#### `/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}/                        │
-└─────────────────────────────────────────────────────────────┘
-```
+---
+
+## Self-Evolution
+
+AutoSpec improves itself through a **three-layer self-evolution system**, forming a complete closed loop from project practice to framework upgrade.
+
+### Three-Layer Evolution System
 
-#### `/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                       │
-└─────────────────────────────────────────────────────────────┘
+┌─────────────────────────────────────────────────────────────────┐
+│  L1: Self-Evolve (Framework Level)                               │
+│  /self-evolve                                                    │
+│  Goal: AutoSpec framework's own iteration and upgrade            │
+│  Output: Framework skills, methodologies, design principles      │
+└─────────────────────────────────────────────────────────────────┘
+                              ↓ Extract
+┌─────────────────────────────────────────────────────────────────┐
+│  L2: Field-Evolve (Domain Level)                                 │
+│  /autospec:field-evolve                                          │
+│  Goal: Framework learns and extracts capabilities from projects  │
+│  Output: Domain skills, best practices, benchmarks               │
+└─────────────────────────────────────────────────────────────────┘
+                              ↓ Apply
+┌─────────────────────────────────────────────────────────────────┐
+│  L3: Project-Evolve (Project Level)                              │
+│  /autospec:project-evolve                                        │
+│  Goal:实战 project's own code, config, documentation optimization│
+│  Output: Code quality improvement, test completion, docs         │
+└─────────────────────────────────────────────────────────────────┘
 ```
 
-#### Layer 1 Failure Example
+### Evolution Zones
+
+| Zone | Level | Contents | Rules |
+|------|-------|----------|-------|
+| **Frozen** | L1 Core | Constitution, evolution rules, core principles | Human-only changes, never auto-modified |
+| **Controlled** | L1/L2 Boundary | Stage definitions, universal skills, role profiles | Auto-proposed, human-approved |
+| **Free** | L2 Domain | Business skills, benchmarks, decision trees | Auto-evolved, validator-verified |
+| **Environment Knowledge** | L3 Project | Environment configs, component libraries, best practices | Project-level auto-optimization |
+
+**Core Safety Principle**: The evolution system cannot modify its own evaluation criteria (immutable harness).
+
+### Enterprise Adaptation
+
 ```
-┌─────────────────────────────────────────────────────────────┐
-│  Layer 1 Validation FAILED                                 │
-├─────────────────────────────────────────────────────────────┤
-│  ✗ npm run build    → Exit code 1                         │
-│  ✗ npm test        → 3 tests failed                       │
-│                                                                     │
-│  BLOCKED: Fix above issues before proceeding to Layer 2   │
-└─────────────────────────────────────────────────────────────┘
+┌─────────────────────────────────┐
+│     Enterprise Overlay          │  ← Org-specific (not upstreamed)
+│  org-constitution.md            │
+│  org-skills/ + domain-knowledge │
+├─────────────────────────────────┤
+│     AutoSpec Core Framework     │  ← npm install (upgradeable)
+│  constitution.md                │
+│  process/ guides/ agents/ ...   │
+└─────────────────────────────────┘
 ```
 
-### Utilities
+Configure domain overlay via `autospec init --domain <domain>`. The overlay adds domain-specific rules and skills **without forking** the core framework.
 
-| Command | Description |
-|---------|-------------|
-| `/autospec:status` | Pipeline progress and state |
-| `/autospec:validate` | Run Layer 1 validation (build/test/lint) |
-| `/evolve` | Trigger self-evolution cycle |
+---
 
-## CLI Commands
+## Safety & Quality
 
-```bash
-autospec init [options]    # Initialize framework + slash commands
-autospec status            # Check pipeline state
-autospec update            # Update framework (preserve state)
-```
+### Five-Layer Safety Protection
 
-**Init options:**
-```bash
-# Default: waterfall mode + generic domain
-autospec init
+1. **Constitutional Gate** — 15 inviolable red lines
+2. **Permission Control** — Each agent only uses its authorized tools
+3. **Stop-the-Line** — Security vulnerability / data loss / 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 Guard** — DB migrations, deployments, external APIs → require human confirmation
+5. **Immutable Harness** — Evolution system cannot modify its own evaluation criteria and constitution
 
-# 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
+### Quality Monitoring
 
-# Specify domain
-autospec init -d fintech -r backend,data  # Fintech domain, backend + data roles
+AutoSpec automatically collects pipeline quality metrics via deterministic hooks:
 
-# Full options
-autospec init -w experiment -d ai -r backend,ai  # AI project
-```
+| Metric | Collection | Purpose |
+|--------|------------|---------|
+| Layer 1 pass rate | `layer1-validator` | Code quality baseline |
+| Retry count | `layer1-validator` | Process smoothness |
+| Human intervention count | `layer1-validator` | Autonomy capability |
+| Scope deviation events | `scope-sentinel` | Implementation discipline |
+| Error patterns | `layer1-validator` | Evolution priority |
 
-**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` |
+Metrics stored in `.autospec/runtime/metrics.json`, automatically merged into practice-log at delivery.
 
-### Environment Integration Commands
+---
 
-AutoSpec automatically detects middleware and components during `init`. Manage environment knowledge with:
+## Knowledge Structure
 
-```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
-```
+AutoSpec's knowledge layer is divided into 9 modules by priority, each independently maintained with detailed README navigation files in the `knowledge/` directory.
 
-**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.
+### Overview
 
-## Self-Evolution
+| No. | Module | Evolution Zone | Description |
+|-----|--------|----------------|-------------|
+| **01** | [principles/](knowledge/01-principles/README.md) | 🔴 Frozen | Principles — Constitution, evolution rules, core principles, design philosophy (4-layer system L1-L4) |
+| **02** | [process/](knowledge/02-process/README.md) | 🟡 Controlled | Process — 6-stage execution flow + 4 workflows (waterfall/agile/experiment/hotfix) |
+| **03** | [guides/](knowledge/03-guides/README.md) | 🟡/🟢 Mixed | Capability guides — 51 skill files (stage execution + review + testing + evolution + AI specialization) |
+| **04** | [checklists/](knowledge/04-checklists/README.md) | 🟡 Controlled | Checklists — Stage-specific checklists (requirement/design/code/test/release) |
+| **05** | [config/](knowledge/05-config/README.md) | 🟡 Controlled | Configuration — Validation patterns, team triggers, role configs (with dynamic decision tree) |
+| **06** | [environment/](knowledge/06-environment/README.md) | 🔵 Environment | Environment knowledge — Middleware, components, integration protocols (auto-detection + knowledge feedback) |
+| **07** | [standards/](knowledge/07-standards/README.md) | 🟡 Controlled | Standards — Coding/review/data consistency/document versioning/risk detection |
+| **08** | [organization/](knowledge/08-organization/README.md) | 🟢 Free | Organization — Vision/Mission, AI Native culture, team metrics, governance committee |
+| **09** | [templates/](knowledge/09-templates/README.md) | 🟡 Controlled | Templates — Standardized document templates (architecture/API/database/product/test/evaluation) |
 
-AutoSpec improves itself through a controlled evolution loop.
+### 01-principles/ — Principles Layer (Constitutional Level)
 
-### Two-Layer Evolution
+> See: [knowledge/01-principles/README.md](knowledge/01-principles/README.md)
 
-AutoSpec's self-evolution happens on two levels simultaneously:
+The principles layer is AutoSpec's highest guiding principles, containing 4 levels (L1→L2→L3→L4):
 
-#### Outward Evolution (Project Evolution)
+| File | Description |
+|------|-------------|
+| [00-principles-hierarchy.md](knowledge/01-principles/00-principles-hierarchy.md) | Principles hierarchy (L1 First Principles→L2 Strategic→L3 Tactical→L4 Operational complete traceability) |
+| [01-first-principles.md](knowledge/01-principles/01-first-principles.md) | L1 First Principles (Triangular Prism: Verification-First, Minimal-Viable, Progressive-Autonomy) |
+| [02-strategic-principles.md](knowledge/01-principles/02-strategic-principles.md) | L2 Strategic Principles (S1 Double-Layer Validation, S2 Do-Review Separation, S3 Harness Engineering, S4 Informed Guessing) |
+| [03-tactical-principles.md](knowledge/01-principles/03-tactical-principles.md) | L3 Tactical Principles (T1-T6: Task Decomposition, Context Management, Precision Retry, etc.) |
+| [04-operational-principles.md](knowledge/01-principles/04-operational-principles.md) | L4 Operational Principles (O1-O4: Coding standard level) |
+| [09-constitution.md](knowledge/01-principles/09-constitution.md) | Project Constitution (15 Red Lines: Safety/Process/Decision/Data/Operations) |
+| [10-evolution-mechanism.md](knowledge/01-principles/10-evolution-mechanism.md) | Self-Evolution Mechanism (Three-Layer Evolution System + Evolution Zones + Auto-Fix) |
 
-When using AutoSpec to drive **other projects**, practical experience automatically feeds back:
+### 02-process/ — Process Layer
 
-```
-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
-```
+> See: [knowledge/02-process/README.md](knowledge/02-process/README.md)
 
-- 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
+The process layer defines AutoSpec's 6-stage execution flow and 4 workflows:
 
-#### Inward Evolution (Framework Evolution)
+| File | Description |
+|------|-------------|
+| [00-overview.md](knowledge/02-process/00-overview.md) | Process overview, startup gate, execution modes |
+| [01-requirement.md](knowledge/02-process/01-requirement.md) | Requirement Analysis Stage |
+| [02-design.md](knowledge/02-process/02-design.md) | Design Planning Stage |
+| [03-implementation.md](knowledge/02-process/03-implementation.md) | Implementation Stage |
+| [04-review.md](knowledge/02-process/04-review.md) | Code Review Stage |
+| [05-testing.md](knowledge/02-process/05-testing.md) | QA Testing Stage |
+| [06-delivery.md](knowledge/02-process/06-delivery.md) | Delivery Stage |
 
-When iterating on AutoSpec **itself**, the framework uses its own process to improve (dogfooding):
+### 03-guides/ — Capability Guides
 
-```
-AutoSpec improvement需求 → Run AutoSpec pipeline → practice-log → framework evolves
-                                              ↓
-                          Same iteration is both output and evolution signal
-```
+> See: [knowledge/03-guides/README.md](knowledge/03-guides/README.md)
 
-- 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
+Capability guides contain 51 skill files, covering core protocols, stage execution, review skills, testing execution, evolution support, AI specializations:
 
-### Evolution Zones
+| Category | No. Range | Files |
+|----------|-----------|-------|
+| Core Protocols | 00-01 | 2 |
+| Stage Execution | 02-08 | 7 |
+| Review Skills | 09-14 | 6 |
+| Testing Execution | 15-17 | 3 |
+| Evolution Support | 18-22 | 5 |
+| Context/Environment | 23-29 | 7 |
+| AI Specializations | 30-41 | 12 |
+| Domain Methodologies | 50-57 | 8 |
 
-| 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. |
+### 04-checklists/ — Checklists
 
-**Test knowledge evolution**: Test knowledge in `environment/integration/testing/` evolves via skill-distiller — learns from test execution patterns, generates proposals for human approval.
+> See: [knowledge/04-checklists/README.md](knowledge/04-checklists/README.md)
 
-**Key safety principle**: The evolution system cannot modify its own evaluation criteria (immutable harness).
+Checklists for each stage, ensuring quality shift-left:
 
-### Evolution Loop
+| File | Description |
+|------|-------------|
+| [00-requirement.md](knowledge/04-checklists/00-requirement.md) | Requirement Checklist |
+| [01-design.md](knowledge/04-checklists/01-design.md) | Design Checklist |
+| [02-code.md](knowledge/04-checklists/02-code.md) | Code Checklist |
+| [03-test.md](knowledge/04-checklists/03-test.md) | Testing Checklist |
+| [04-release.md](knowledge/04-checklists/04-release.md) | Release Checklist |
 
-```
-Execute Pipeline → Collect Signals → Analyze Patterns → Propose Changes → Validate → Accept/Reject
-                                                                              ↓
-                                                           Regression? → Auto-rollback
-```
+### 05-config/ — Configuration Files
 
-**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.
+> See: [knowledge/05-config/README.md](knowledge/05-config/README.md)
 
-### Enterprise Adaptation
+Validation patterns, team triggers, role configurations:
 
-```
-┌─────────────────────────────────┐
-│     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/ ...   │
-└─────────────────────────────────┘
-```
+| File | Description |
+|------|-------------|
+| [00-validation-patterns.yaml](knowledge/05-config/00-validation-patterns.yaml) | Validation Patterns Configuration |
+| [01-team-stage.yaml](knowledge/05-config/01-team-stage.yaml) | Team Stage Configuration (with triggers) |
+| [02-team-tasks.yaml](knowledge/05-config/02-team-tasks.yaml) | Team Tasks Configuration |
+| [03-role-composition.yaml](knowledge/05-config/03-role-composition.yaml) | Role Composition Configuration (with decision tree) |
 
-Customize via `autospec init --domain <domain>`. The overlay adds domain-specific rules, checklists, and skills **without forking** the core framework.
+### 06-environment/ — Environment Knowledge
 
-## Project Structure
+> See: [knowledge/06-environment/README.md](knowledge/06-environment/README.md)
 
-```
-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
-```
+Environment integration protocol, enabling AutoSpec to seamlessly integrate with different organizations' middleware, components, custom frameworks:
 
-**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
-```
+| File | Description |
+|------|-------------|
+| [00-template-registry.md](knowledge/06-environment/00-template-registry.md) | Template Registry |
+| [01-detection-patterns.yaml](knowledge/06-environment/01-detection-patterns.yaml) | Detection Patterns Configuration |
 
-## Safety Model
+Template Resources (integrated into 09-templates):
 
-AutoSpec enforces safety through four layers:
+| File | Description |
+|------|-------------|
+| [13-middleware-knowledge.md](knowledge/09-templates/13-middleware-knowledge.md) | Middleware Knowledge Template |
+| [10-component-knowledge.md](knowledge/09-templates/10-component-knowledge.md) | Component Knowledge Template |
 
-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
+### 07-standards/ — Standards
 
-Evolution adds a fifth layer:
+> See: [knowledge/07-standards/README.md](knowledge/07-standards/README.md)
 
-5. **Immutable Harness** — The evolution system cannot modify its own evaluation criteria, constitution, or evolution rules
+Coding, review, data consistency standards:
 
-## Quality Monitoring
+| File | Description |
+|------|-------------|
+| [00-coding-style.md](knowledge/07-standards/00-coding-style.md) | Coding Style Guide |
+| [01-code-review.md](knowledge/07-standards/01-code-review.md) | Code Review Standard |
+| [02-data-consistency.md](knowledge/07-standards/02-data-consistency.md) | Data Consistency Standard |
+| [03-document-versioning.md](knowledge/07-standards/03-document-versioning.md) | Document Versioning Standard |
+| [04-risk-detection.md](knowledge/07-standards/04-risk-detection.md) | Risk Detection Standard |
 
-AutoSpec automatically tracks quality metrics during pipeline execution via deterministic hooks:
+### 08-organization/ — Organization Knowledge
 
-| 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 |
+> See: [knowledge/08-organization/README.md](knowledge/08-organization/README.md)
 
-Metrics are stored in `.autospec/runtime/metrics.json` and automatically fed into practice-log at delivery.
+AI Native team culture, vision, governance:
 
-## Cognitive Enhancement
+| File | Description |
+|------|-------------|
+| [00-vision-mission.md](knowledge/08-organization/00-vision-mission.md) | Vision, Mission, Core Values (Verification-First, Minimal-Viable, Progressive-Autonomy, Safety-First, Continuous-Evolution) |
+| [01-ai-native-culture.md](knowledge/08-organization/01-ai-native-culture.md) | AI Native Team Culture Handbook (Four Principles, Work Modes, Role Transition) |
+| [02-team-metrics.md](knowledge/08-organization/02-team-metrics.md) | Team Metrics System (AI Capability, Process Efficiency, Quality, Team Health) |
+| [03-committee-structure.md](knowledge/08-organization/03-committee-structure.md) | Governance Committee Structure (Technical/Quality/Strategy Committees + Governance Agents) |
+| [04-governance-metrics.md](knowledge/08-organization/04-governance-metrics.md) | Governance Metrics (DORA/Layer1/Layer2/Benchmarks Pass Rate) |
+| [05-improvement-process.md](knowledge/08-organization/05-improvement-process.md) | Improvement Process (Improvement Sources/Process/Classification/Integration with Self-Evolution) |
 
-AutoSpec injects 10 cognitive enhancement principles ([`knowledge/principles/principles.md`](knowledge/principles/principles.md)) into each pipeline stage:
+### 09-templates/ — Document Templates
 
-| 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 |
+> See: [knowledge/09-templates/README.md](knowledge/09-templates/README.md)
 
-## Documentation
+Standardized document template library (sorted by priority):
 
-| 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 |
+| File | Description |
+|------|-------------|
+| [01-architecture-design.md](knowledge/09-templates/01-architecture-design.md) | Architecture Design Template |
+| [02-api-design.md](knowledge/09-templates/02-api-design.md) | API Design Template |
+| [03-database-design.md](knowledge/09-templates/03-database-design.md) | Database Design Template |
+| [04-product-design.md](knowledge/09-templates/04-product-design.md) | Product Design Template |
+| [05-business-glossary.md](knowledge/09-templates/05-business-glossary.md) | Business Glossary Template |
+| [06-business-rules.md](knowledge/09-templates/06-business-rules.md) | Business Rules Template |
+| [07-business-flows.md](knowledge/09-templates/07-business-flows.md) | Business Flows Template |
+| [08-test-design.md](knowledge/09-templates/08-test-design.md) | Test Design Template |
+| [09-evaluation-design.md](knowledge/09-templates/09-evaluation-design.md) | Evaluation Design (AI/Model) |
+| [10-component-knowledge.md](knowledge/09-templates/10-component-knowledge.md) | Component Knowledge Template |
+| [11-best-practices.md](knowledge/09-templates/11-best-practices.md) | Best Practices Template |
+| [12-domain-model.md](knowledge/09-templates/12-domain-model.md) | Domain Model Template |
 
-## Design Philosophy
+---
 
-See [`knowledge/principles/design-philosophy.md`](knowledge/principles/design-philosophy.md) for the complete 18 design principles (DP1–DP18), including:
+## Plugins Structure
 
-- **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
+```
+plugins/               # Plugins layer (commands, agents, skills, hooks)
+├── commands/           # Slash command templates
+├── agents/             # Agent definitions (roles + support)
+│   ├── roles/          # Startup team roles (CEO, Product Owner, Engineer, etc.)
+│   └── support/        # Support agents (reviewers, evaluators, stage-gate, etc.)
+├── skills/             # Skill triggers
+│   ├── *-stage/        # Stage skills (requirement/design/implementation/testing/delivery)
+│   ├── *-iteration/    # Iteration skills (waterfall/agile/experiment/hotfix)
+│   ├── field-evolve-*/ # Field evolution skills (scanner/executor/analyzer/fixer/verifier/learner/distiller)
+│   ├── project-evolve-*/ # Project evolution skills (scanner/generator/analyzer/fixer/reviewer/verifier/learner)
+│   └── benchmark-*/    # Benchmark-related skills
+└── hooks/              # Lifecycle hooks (frozen-zone-guard/scope-sentinel/layer1-validator/execution-tracker/environment-manager)
+```
+
+### Latest Skills
+
+**Field Evolution Skills (L2 Field-Evolve)**:
+- `field-evolve-scanner` - Scan practice logs, identify patterns
+- `field-evolve-executor` - Execute evolution workflow
+- `field-evolve-analyzer` - Analyze evolution effectiveness
+- `field-evolve-fixer` - Fix evolution issues
+- `field-evolve-verifier` - Verify evolution results
+- `field-evolve-learner` - Learn from evolution experience
+- `field-evolve-distiller` - Distill universal skills
+
+**Project Evolution Skills (L3 Project-Evolve)**:
+- `project-evolve-scanner` - Scan project code quality
+- `project-evolve-generator` - Generate optimization plans
+- `project-evolve-analyzer` - Analyze project issues
+- `project-evolve-fixer` - Fix project issues
+- `project-evolve-reviewer` - Review fix results
+- `project-evolve-verifier` - Verify fix effectiveness
+- `project-evolve-learner` - Learn from project experience
+
+---
 
 ## Contributing
 
-See [CONTRIBUTING.md](./CONTRIBUTING.md). We welcome contributions to:
-- Framework pipeline and skill definitions
+We welcome contributions to:
+- Framework pipeline and skill definition improvements
 - Role profiles for new domains
-- CLI tooling improvements
+- CLI tooling enhancements
 - Practice log entries from real usage
+- Enterprise adaptation experience
 - Documentation and translations
 
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for details.
+
 ## License
 
-[MIT](./LICENSE)
+[MIT](./LICENSE)