Overhaul README: badges, ToC, Quick Start, Technical Layer

README.md

@@ -1,9 +1,27 @@
 # SpecForge
 
+![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)
+![Claude Code Plugin](https://img.shields.io/badge/Claude_Code-Plugin-blue)
+![Standards](https://img.shields.io/badge/Standards-IEEE_830_%7C_ISO_29148_%7C_BABOK-green)
+
 A spec-driven development toolkit for AI coding agents. SpecForge provides structured templates, automated workflows, and Claude Code skills that turn requirements into sprint-ready work — from stakeholder meeting to deployed feature.
 
 Adaptable to any enterprise software project. Clone, start writing specs — domain context is discovered automatically from your existing specifications.
 
+## Contents
+
+- [Prerequisites](#prerequisites)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Philosophy](#philosophy)
+- [The Basic Workflow](#the-basic-workflow)
+- [What's Inside](#whats-inside)
+- [License](#license)
+
+## Prerequisites
+
+- [Claude Code](https://claude.ai/code) CLI installed and authenticated
+
 ## Installation
 
 SpecForge is a **Claude Code plugin**. Install it once and it's available in every project.
@@ -29,7 +47,8 @@ This installs SpecForge only for the current project (added to `.claude/plugins/
 
 ```bash
 git clone https://github.com/nguyendlp/specforge.git
-claude plugin add ./specforge
+cd your-project
+claude plugin add ../specforge
 ```
 
 ### Verify installation
@@ -38,29 +57,44 @@ claude plugin add ./specforge
 claude plugin list
 ```
 
-You should see `specforge` in the output. Then start using it:
+You should see `specforge` in the output.
+
+No dependencies to install. SpecForge is a pure markdown plugin — templates, skills, and agents are all markdown files that Claude Code reads directly.
+
+## Quick Start
+
+Once installed, open a Claude Code session in any project and run your first spec workflow:
 
 ```
+# Step 1: Capture a stakeholder meeting
+/meeting-note "Initial Requirements Session"
+
+# Step 2: Create your first use case spec (auto-numbered, placed in docs/)
 /new-spec usecase CreateOrder
+
+# Step 3: Review quality against IEEE 830 / ISO 29148
+/review-spec UC0001
+
+# Step 4: Decompose into an epic with story suggestions
 /new-epic UC0001
+
+# Step 5: Verify all artifacts trace to specs
 /check-traceability
 ```
 
-No dependencies to install. SpecForge is a pure markdown plugin — templates, skills, and agents are all markdown files that Claude Code reads directly.
+## Philosophy
 
-## Deterministic Validation
+**Specs are the source of truth, not code.** In spec-driven development, the specification defines intent. Code implements it. When requirements change, the spec changes first — then delivery artifacts and code follow.
 
-SpecForge includes a deterministic validator for artifact quality gates:
+**Three layers, one system.** The specification layer (what to build), the technical layer (how to build it), and the delivery layer (when to ship) are separate but linked. Specs are stable and change through formal review. Stories are disposable and can be re-split, re-estimated, or thrown away without losing any requirement.
 
-```bash
-python3 scripts/validate_spec_docs.py --paths docs/spec docs/samples
-```
+**Every story traces to a spec.** No orphan stories. If a user story doesn't link back to a use case, object, screen, or business rule, either the spec is missing or the story is out of scope. The traceability checker enforces this.
 
-Checks performed:
-- Broken artifact references
-- Naming convention compliance
-- Required section presence
-- Unresolved placeholders
+**Refinement is the bridge.** Backlog refinement sessions are where specs get decomposed into stories. They also surface spec gaps — ambiguities or missing details that need to be fixed before coding. The two layers evolve together through this feedback loop.
+
+**Standards over opinions.** Templates are grounded in IEEE 830, ISO 29148, ISO 25010, and BABOK. Quality checks enforce testable language ("shall" not "should be fast"), banned vague words, and measurable acceptance criteria.
+
+**AI-native workflow.** SpecForge is designed for AI coding agents, not just humans. Skills auto-trigger with domain knowledge. Commands generate artifacts with traceability pre-filled. Agents handle complex multi-step tasks autonomously. The human focuses on decisions; the agent handles structure.
 
 ## The Basic Workflow
 
@@ -83,7 +117,7 @@ SpecForge follows a five-phase BA workflow that bridges waterfall-style specific
 
 **Step 1 — Elicit:** Capture stakeholder meetings with `/meeting-note`. Extract user requirements (URs) into a structured table.
 
-**Step 2 — Specify:** Write formal specs using `/new-spec`. Choose from 14 spec types (object, use case, screen, business rule, etc.). Each spec gets auto-numbered, placed in the right directory, and validated against IEEE 830 / ISO 29148 quality standards.
+**Step 2 — Specify:** Write formal specs using `/new-spec`. Choose from 27 spec types (object, use case, screen, business rule, architecture, etc.). Each spec gets auto-numbered, placed in the right directory, and validated against IEEE 830 / ISO 29148 quality standards.
 
 **Step 3 — Decompose:** Convert specs into delivery artifacts. `/new-epic` reads a use case and generates an epic with suggested story breakdown. `/new-story` creates stories with acceptance criteria derived from spec business rules and exception flows.
 
@@ -95,7 +129,7 @@ At any point, run `/check-traceability` to verify that every spec has a delivery
 
 ## What's Inside
 
-### Templates (20 types)
+### Templates (27 types)
 
 **Specification Layer** — what to build:
 
@@ -107,13 +141,19 @@ At any point, run `/check-traceability` to verify that every spec has a delivery
 | Non-Functional Requirements | NFR (ISO 25010 quality model) |
 | Input Management | Meeting Note, Change Request, Impact Analysis, Phase Delta, Change Management Rules |
 
+**Technical Layer** — how to build it:
+
+| Category | Templates |
+|---|---|
+| Technical Spec | Architecture Overview (Arc42 + C4 L1–L2), Component Design (C4 L3), Data Architecture, Security Design (STRIDE), Infrastructure & Deployment, ADR |
+
 **Delivery Layer** — when to ship:
 
 | Category | Templates |
 |---|---|
 | Agile Delivery | Epic, User Story, Sprint, Release Plan, Backlog Refinement |
 
-See [`templates/README.md`](templates/README.md) for the full guide on how the two layers connect.
+See [`templates/README.md`](templates/README.md) for the full guide on how the three layers connect.
 
 ### Skills (3 auto-triggered)
 
@@ -152,28 +192,6 @@ Skills auto-activate based on context — no manual invocation needed.
 | `traceability-agent` | Builds the full Requirements Traceability Matrix across all artifacts |
 | `change-impact-agent` | Autonomous blast-radius analysis for change requests with risk rating |
 
-### Worked Example
-
-`docs/samples/` contains a versioned end-to-end example showing how a feature flows through both layers:
-
-- **6 specification artifacts**: SRS Overview, Object, Use Case, Screen, Business Rule, NFR
-- **5 delivery artifacts**: Release Plan, Epic, User Story, Sprint, Backlog Refinement
-- **Cross-referenced links** between spec and delivery artifacts for validation/regression
-
-## Philosophy
-
-**Specs are the source of truth, not code.** In spec-driven development, the specification defines intent. Code implements it. When requirements change, the spec changes first — then delivery artifacts and code follow.
-
-**Two layers, one system.** The specification layer (what to build) and the delivery layer (when to ship) are separate but linked. Specs are stable and change through formal review. Stories are disposable and can be re-split, re-estimated, or thrown away without losing any requirement.
-
-**Every story traces to a spec.** No orphan stories. If a user story doesn't link back to a use case, object, screen, or business rule, either the spec is missing or the story is out of scope. The traceability checker enforces this.
-
-**Refinement is the bridge.** Backlog refinement sessions are where specs get decomposed into stories. They also surface spec gaps — ambiguities or missing details that need to be fixed before coding. The two layers evolve together through this feedback loop.
-
-**Standards over opinions.** Templates are grounded in IEEE 830, ISO 29148, ISO 25010, and BABOK. Quality checks enforce testable language ("shall" not "should be fast"), banned vague words, and measurable acceptance criteria.
-
-**AI-native workflow.** SpecForge is designed for AI coding agents, not just humans. Skills auto-trigger with domain knowledge. Commands generate artifacts with traceability pre-filled. Agents handle complex multi-step tasks autonomously. The human focuses on decisions; the agent handles structure.
-
 ## License
 
 MIT License — see [LICENSE](LICENSE) for details.