From 4dcc2145832a13cb33080a3992543120cbcf39a1 Mon Sep 17 00:00:00 2001 From: NguyenDuong Date: Mon, 23 Mar 2026 08:28:04 +0700 Subject: [PATCH] Overhaul README with badges, ToC, Quick Start, and Technical Layer MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add shields.io badges (MIT, Claude Code Plugin, Standards) - Add Table of Contents with anchor links - Add Prerequisites section (Claude Code CLI) - Add Quick Start section with a concrete 5-step first workflow - Move Philosophy section above The Basic Workflow - Add missing Technical Layer table (ARCH, COMP, DATA, SEC, INFRA, ADR) - Fix template count: 20 → 27 (technical specs were omitted) - Fix "Two layers" → "Three layers" throughout - Fix Option 3 install path ambiguity (./specforge → ../specforge) - Remove Worked Example section (docs/samples/ was git-ignored but tracked) - Remove Supporting Tools and Deterministic Validation sections - Remove docs/samples/ tracked files (not intended to be committed) Co-Authored-By: Claude Sonnet 4.6 --- README.md | 94 +++++++++++-------- docs/samples/README.md | 10 -- .../delivery/EPIC-0001_OrderCreation.md | 22 ----- .../delivery/REL-0001_OrderMVP.md | 20 ---- .../delivery/Refinement_2026-03-22.md | 21 ----- .../delivery/Sprint_01_OrderFoundation.md | 21 ----- .../delivery/US-0001_SubmitOrder.md | 26 ----- .../spec/BR0001_UniqueOrderId.md | 18 ---- .../spec/NFR0001_OrderCreateLatency.md | 19 ---- .../order_management/spec/O01_Order.md | 20 ---- .../spec/S0001_CreateOrderForm.md | 24 ----- .../spec/SRS01_OrderManagement.md | 23 ----- .../spec/UC0001_CreateOrder.md | 28 ------ 13 files changed, 56 insertions(+), 290 deletions(-) delete mode 100644 docs/samples/README.md delete mode 100644 docs/samples/order_management/delivery/EPIC-0001_OrderCreation.md delete mode 100644 docs/samples/order_management/delivery/REL-0001_OrderMVP.md delete mode 100644 docs/samples/order_management/delivery/Refinement_2026-03-22.md delete mode 100644 docs/samples/order_management/delivery/Sprint_01_OrderFoundation.md delete mode 100644 docs/samples/order_management/delivery/US-0001_SubmitOrder.md delete mode 100644 docs/samples/order_management/spec/BR0001_UniqueOrderId.md delete mode 100644 docs/samples/order_management/spec/NFR0001_OrderCreateLatency.md delete mode 100644 docs/samples/order_management/spec/O01_Order.md delete mode 100644 docs/samples/order_management/spec/S0001_CreateOrderForm.md delete mode 100644 docs/samples/order_management/spec/SRS01_OrderManagement.md delete mode 100644 docs/samples/order_management/spec/UC0001_CreateOrder.md diff --git a/README.md b/README.md index 6ef4915..6f333ac 100644 --- a/README.md +++ b/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. diff --git a/docs/samples/README.md b/docs/samples/README.md deleted file mode 100644 index 027b40d..0000000 --- a/docs/samples/README.md +++ /dev/null @@ -1,10 +0,0 @@ -# SpecForge Sample Project (Versioned) - -This directory contains a complete, versioned sample project that demonstrates a golden-path flow from specification artifacts to delivery artifacts. - -## Sample: Order Management - -- Specification artifacts: `docs/samples/order_management/spec/` -- Delivery artifacts: `docs/samples/order_management/delivery/` - -The sample is intentionally small but end-to-end, so it can be used for onboarding and regression of traceability/validation behavior. diff --git a/docs/samples/order_management/delivery/EPIC-0001_OrderCreation.md b/docs/samples/order_management/delivery/EPIC-0001_OrderCreation.md deleted file mode 100644 index dc46d16..0000000 --- a/docs/samples/order_management/delivery/EPIC-0001_OrderCreation.md +++ /dev/null @@ -1,22 +0,0 @@ -# EPIC-0001 Order Creation - -- Status: Committed - -## Goal -Deliver UC0001 as a production-ready capability. - -## Scope -Includes order form submission, validation, persistence, and confirmation. - -## Spec Traceability -- UC0001 -- O01 -- S0001 -- BR0001 -- NFR0001 - -## Story Breakdown -- US-0001 Submit Order - -## Change History -- 2026-03-22: Initial baseline. diff --git a/docs/samples/order_management/delivery/REL-0001_OrderMVP.md b/docs/samples/order_management/delivery/REL-0001_OrderMVP.md deleted file mode 100644 index 3811b82..0000000 --- a/docs/samples/order_management/delivery/REL-0001_OrderMVP.md +++ /dev/null @@ -1,20 +0,0 @@ -# REL-0001 Order MVP - -- Status: Planned - -## Goals -Launch the first release of order creation. - -## Included Epics -- EPIC-0001 - -## Scope Decisions -- Included: UC0001 flow. -- Deferred: external ERP sync integration. - -## Milestones -- Sprint 1 complete: 2026-04-03 -- Release candidate: 2026-04-10 - -## Change History -- 2026-03-22: Initial baseline. diff --git a/docs/samples/order_management/delivery/Refinement_2026-03-22.md b/docs/samples/order_management/delivery/Refinement_2026-03-22.md deleted file mode 100644 index ad38230..0000000 --- a/docs/samples/order_management/delivery/Refinement_2026-03-22.md +++ /dev/null @@ -1,21 +0,0 @@ -# Refinement 2026-03-22 - -- Status: Completed - -## Agenda -Refine UC0001 into sprint-ready stories. - -## Spec Inputs -- UC0001 -- O01 -- S0001 -- BR0001 -- NFR0001 - -## Story Decisions -- Create US-0001 for core submission behavior. -- Keep duplicate-order handling as acceptance criteria. - -## Action Items -- Confirm performance test harness for NFR0001. -- Prepare demo script for Sprint_01 review. diff --git a/docs/samples/order_management/delivery/Sprint_01_OrderFoundation.md b/docs/samples/order_management/delivery/Sprint_01_OrderFoundation.md deleted file mode 100644 index 9cb887c..0000000 --- a/docs/samples/order_management/delivery/Sprint_01_OrderFoundation.md +++ /dev/null @@ -1,21 +0,0 @@ -# Sprint_01 Order Foundation - -- Status: Complete - -## Sprint Goal -Ship the first slice of order creation. - -## Committed Stories -- US-0001 - -## Capacity -- Team capacity: 20 points -- Planned: 5 points - -## Ceremonies -- Planning: 2026-03-23 -- Review: 2026-04-03 -- Retrospective: 2026-04-03 - -## Outcome -US-0001 delivered and accepted. diff --git a/docs/samples/order_management/delivery/US-0001_SubmitOrder.md b/docs/samples/order_management/delivery/US-0001_SubmitOrder.md deleted file mode 100644 index 7eb0bb5..0000000 --- a/docs/samples/order_management/delivery/US-0001_SubmitOrder.md +++ /dev/null @@ -1,26 +0,0 @@ -# US-0001 Submit Order - -- Status: Ready - -## User Story -As a sales user, I want to submit a new order so that it can be processed. - -## Acceptance Criteria -- Given valid input, when I submit the form, then the order is saved with status Submitted. -- Given duplicate order_id, when I submit the form, then I see a duplicate error. -- Given 100 concurrent users, when orders are submitted, then p95 response is <= 2.0 seconds. - -## Spec Traceability -- EPIC-0001 -- UC0001 -- O01 -- S0001 -- BR0001 -- NFR0001 - -## Definition of Done -- Unit and integration tests pass. -- Validation rules match BR0001. - -## Change History -- 2026-03-22: Initial baseline. diff --git a/docs/samples/order_management/spec/BR0001_UniqueOrderId.md b/docs/samples/order_management/spec/BR0001_UniqueOrderId.md deleted file mode 100644 index 5abe9dc..0000000 --- a/docs/samples/order_management/spec/BR0001_UniqueOrderId.md +++ /dev/null @@ -1,18 +0,0 @@ -# BR0001 Unique Order ID - -- Status: Approved - -## Rule Statement -The system shall reject any create-order request where order_id already exists. - -## Example Scenarios -- Existing order_id ORD-1001 + new request ORD-1001 => reject with duplicate message. -- Existing order_id ORD-1001 + new request ORD-1002 => allow create. - -## Related Artifacts -- UC0001 -- O01 -- S0001 - -## Change History -- 2026-03-22: Initial baseline. diff --git a/docs/samples/order_management/spec/NFR0001_OrderCreateLatency.md b/docs/samples/order_management/spec/NFR0001_OrderCreateLatency.md deleted file mode 100644 index 6e26b52..0000000 --- a/docs/samples/order_management/spec/NFR0001_OrderCreateLatency.md +++ /dev/null @@ -1,19 +0,0 @@ -# NFR0001 Order Create Latency - -- Status: Approved - -## Quality Attribute -Performance - -## Requirement -Create-order API shall respond in <= 2.0 seconds at p95 under 100 concurrent users. - -## Measurement -Measured in pre-release load test for UC0001 scenario. - -## Related Artifacts -- UC0001 -- EPIC-0001 - -## Change History -- 2026-03-22: Initial baseline. diff --git a/docs/samples/order_management/spec/O01_Order.md b/docs/samples/order_management/spec/O01_Order.md deleted file mode 100644 index 859656b..0000000 --- a/docs/samples/order_management/spec/O01_Order.md +++ /dev/null @@ -1,20 +0,0 @@ -# O01 Order - -- Status: Approved - -## Purpose -Define the Order entity used by UC0001. - -## Fields -- order_id (string, unique) -- customer_name (string) -- total_amount (decimal) -- status (enum: Draft, Submitted) - -## Related Artifacts -- UC0001 -- S0001 -- BR0001 - -## Change History -- 2026-03-22: Initial baseline. diff --git a/docs/samples/order_management/spec/S0001_CreateOrderForm.md b/docs/samples/order_management/spec/S0001_CreateOrderForm.md deleted file mode 100644 index 77b6dfa..0000000 --- a/docs/samples/order_management/spec/S0001_CreateOrderForm.md +++ /dev/null @@ -1,24 +0,0 @@ -# S0001 Create Order Form - -- Status: Approved - -## Purpose -Define the UI for UC0001. - -## Components -- order_id input -- customer_name input -- total_amount input -- submit button - -## Validation -- order_id must be unique (BR0001). -- total_amount must be >= 0. - -## Related Artifacts -- UC0001 -- O01 -- BR0001 - -## Change History -- 2026-03-22: Initial baseline. diff --git a/docs/samples/order_management/spec/SRS01_OrderManagement.md b/docs/samples/order_management/spec/SRS01_OrderManagement.md deleted file mode 100644 index 68e582a..0000000 --- a/docs/samples/order_management/spec/SRS01_OrderManagement.md +++ /dev/null @@ -1,23 +0,0 @@ -# SRS01 Order Management Overview - -- Status: Approved -- Date: 2026-03-22 - -## Scope -Provide order capture and validation for internal sales users. - -## References -Derived from stakeholder requirement notes for order intake modernization. - -## Artifact Index -- O01 Order -- UC0001 Create Order -- S0001 Create Order Form -- BR0001 Unique Order ID -- NFR0001 Order Create Latency - -## Traceability & Coverage -UC0001 is delivered by EPIC-0001 and US-0001 in Sprint_01. - -## Change History -- 2026-03-22: Initial baseline. diff --git a/docs/samples/order_management/spec/UC0001_CreateOrder.md b/docs/samples/order_management/spec/UC0001_CreateOrder.md deleted file mode 100644 index 3dbe45f..0000000 --- a/docs/samples/order_management/spec/UC0001_CreateOrder.md +++ /dev/null @@ -1,28 +0,0 @@ -# UC0001 Create Order - -- Status: Approved - -## Goal -Allow a sales user to create and submit an order. - -## Main Flow -1. User opens S0001. -2. User enters order data. -3. System validates BR0001. -4. System stores O01 and confirms submission. - -## Exceptions -- EX-1: Duplicate order_id fails validation and returns an error. - -## Related Artifacts -- O01 -- S0001 -- BR0001 -- NFR0001 - -## Acceptance Criteria -- Given valid input, when submit is clicked, then the order is stored as Submitted. -- Given duplicate order_id, when submit is clicked, then the system rejects the request. - -## Change History -- 2026-03-22: Initial baseline.