chore(release): v1.1.0 - modular validation, new workflow skills, docs refresh

- Refactor validate into dedicated modules under src/pb_spec/validation: build, plan, parser, result, scanner, rumdl
- Add config, exceptions, git_utils, output modules
- Add pb-* workflow skills: brainstorming, dispatching-parallel-agents, finishing, improve, receiving-code-review, requesting-code-review, subagent-driven-development, systematic-debugging, test-driven-development, verification-before-completion, writing-skills
- Add using-pb-spec skill
- Update skills/pb-plan and design template
- Refresh docs/contract.md, docs/design.md, README.md
- Bump pyproject version and dev dependencies, refresh uv.lock

Author: Akagi201

README.md

@@ -14,6 +14,18 @@ pb-spec is a set of [Agent Skills Specification](https://agentskills.io) complia
 
 Compared to letting AI "just write code", pb-spec provides a hardened execution harness (guardrails). It requires context-first design, contract-based architecture, and dual-loop verification through logging and health checks.
 
+### Design Standards
+
+`design.md` artifacts conform to four industry-standard specification formats:
+
+| Standard | Purpose | pb-spec Application |
+|---|---|---|
+| **EARS Notation** | Eliminate ambiguous requirements with 5 sentence patterns (Ubiquitous, State-driven, Event-driven, Unwanted, Exception) | Every requirement in `design.md` uses EARS syntax with `[REQ-XX]` IDs |
+| **C4 Model + Mermaid** | Architecture topology in parseable text (Context, Container, Component diagrams) | Architecture sections use `` ```mermaid `` blocks with C4 hierarchy |
+| **DBML / Prisma Schema** | Structured data models with strict types, relationships, and indexes | Data model sections use DBML or Prisma Schema DSL — natural language forbidden |
+| **MADR (ADR Records)** | Architecture decision records with Context/Decision/Consequences | Every AD has `[Context]`, `[Decision]`, `[Consequences]` subsections |
+| **API-First Type Signatures** | Contracts defined before implementation (OpenAPI, Protocol, Trait) | Interface sections use type signatures — narrative descriptions forbidden |
+
 ### Best-Practice Alignment
 
 | Source | Core Idea | How pb-spec Applies It |
@@ -29,6 +41,8 @@ Compared to letting AI "just write code", pb-spec provides a hardened execution
 | [Harness Design for Long-Running Application Development](https://www.anthropic.com/engineering/harness-design-long-running-apps) | Generator/Evaluator separation; adversarial evaluation with MCP-driven live verification | `pb-build` dual-persona: Generator builds, independent Evaluator audits with fresh context; adaptive evaluation by task complexity |
 | [Stop Using /init for AGENTS.md](https://addyosmani.com/blog/agents-md/) | Keep AGENTS.md focused and maintainable | `/pb-init` updates a managed snapshot block in `AGENTS.md` while preserving all user-authored constraints outside that block |
 | [Ensuring Correctness Through the Type System](https://lindbakk.com/blog/ensuring-correctness-through-the-type-system) | Use the type system to encode invariants and catch errors early | Encode contracts as type-level assertions in `design.md` and add type checks to verification; `pb-plan` adds type guidance and `pb-build` runs the type checker when applicable |
+| [shadcn/improve](https://github.com/shadcn/improve) | Audit codebase, write self-contained plans for cheaper executors | `/pb-improve` surveys codebase, produces prioritized findings and handoff plans |
+| [Superpowers](https://github.com/obra/superpowers) | Composable skills, evidence-based claims, systematic debugging, skill auto-triggering | `using-pb-spec` bootstrap; `pb-verification-before-completion`; `pb-systematic-debugging`; supporting skills ecosystem |
 
 ## Installation
 
@@ -44,6 +58,7 @@ npx skills add longcipher/pb-spec
 npx skills add longcipher/pb-spec --skill pb-init
 npx skills add longcipher/pb-spec --skill pb-plan
 npx skills add longcipher/pb-spec --skill pb-build
+npx skills add longcipher/pb-spec --skill improve
 ```
 
 *(After installation, skills will be placed in `.agents/skills/` or the compatible local directory for your environment, and automatically indexed by your AI.)*
@@ -56,15 +71,35 @@ Invoke these skills directly in your IDE / Agent terminal:
 2. **/pb-plan "requirement description"**: For example `/pb-plan Add WebSocket auth`, AI will generate `design.md`, `tasks.md`, and `.feature` test specs with Architecture Decisions.
 3. **/pb-build "feature-name"**: Automatically reads `tasks.md`, starts the outer BDD and inner TDD dual-loop with Subagents, closing and verifying each task one by one.
 4. **/pb-refine "feature-name"**: *(Optional)* When encountering design blocks (Build Blocked) or architectural flaws, iteratively modify specs based on feedback.
+5. **/pb-improve**: Audit the codebase and generate prioritized implementation plans for other agents to execute.
 
 ## Skills Overview
 
+### Workflow Skills
+
 | Skill | Trigger | Output | Description |
 |---|---|---|---|
 | `pb-init` | `/pb-init` | `AGENTS.md` | Audit repo and safely update/append a managed snapshot block without rewriting user-authored constraints |
 | `pb-plan` | `/pb-plan <requirement>` | `specs/<spec-dir>/design.md` + `tasks.md` + `features/*.feature` | Design proposal + Gherkin scenarios + ordered task breakdown |
 | `pb-refine` | `/pb-refine <feature>` | Revised spec files | Apply feedback or Design Change Requests |
 | `pb-build` | `/pb-build <feature-name>` | Code + tests | BDD+TDD via Generator (builds) + Evaluator (adversarial review) dual-persona workflow |
+| `pb-improve` | `/pb-improve` | `plans/*.md` | Codebase audit → prioritized findings → self-contained handoff plans |
+
+### Supporting Skills
+
+| Skill | Trigger | Description |
+|---|---|---|
+| `using-pb-spec` | Session start | Bootstrap: establishes skill invocation discipline |
+| `pb-brainstorming` | Before creative work | Explores intent, requirements, and design before implementation |
+| `pb-test-driven-development` | Before writing code | Red → Green → Refactor cycle, non-negotiable TDD |
+| `pb-systematic-debugging` | Any bug or failure | Find root cause before attempting fixes |
+| `pb-verification-before-completion` | Before claiming done | Evidence before assertions, always |
+| `pb-requesting-code-review` | Before merge | Dispatch independent reviewer subagent |
+| `pb-receiving-code-review` | Processing feedback | Technical evaluation, not performative agreement |
+| `pb-dispatching-parallel-agents` | Multiple independent tasks | One agent per problem domain, concurrent execution |
+| `pb-subagent-driven-development` | Executing plans | Fresh context per task, two-stage review |
+| `pb-finishing-a-development-branch` | Work complete | Verify tests → Present options → Execute choice |
+| `pb-writing-skills` | Creating/editing skills | Skills are code, not prose — test them |
 
 ## Supported AI Tools
 
@@ -79,12 +114,24 @@ This skill library uses the standard `SKILL.md` specification. Fully compatible
 
 ## Workflow
 
-Four agent skills that chain together:
+Five agent skills that chain together:
 
 ```text
 /pb-init → /pb-plan → [/pb-refine] → /pb-build
+                    ↘
+                    /pb-improve → plans/ → any executor
 ```
 
+Supporting skills activate automatically during the workflow:
+
+- `pb-brainstorming` — before `/pb-plan` when requirements are unclear
+- `pb-test-driven-development` — during `/pb-build` for every task
+- `pb-systematic-debugging` — when tasks fail repeatedly
+- `pb-verification-before-completion` — before marking any task DONE
+- `pb-requesting-code-review` / `pb-receiving-code-review` — review cycles
+- `pb-dispatching-parallel-agents` — parallel audit in `/pb-improve`
+- `pb-finishing-a-development-branch` — finalization after `/pb-build`
+
 ### 1. `/pb-init` — AGENTS.md Snapshot & Safe Merge
 
 Audits your project and writes a `pb-init` snapshot into `AGENTS.md` using managed markers:
@@ -113,7 +160,11 @@ specs/<YYYY-MM-DD-NO-feature-name>/
 
 Key capabilities:
 
-- **Architecture Decisions**: Explicit `Architecture Decisions` section with SRP, DIP, and pattern evaluation
+- **EARS Requirements**: All acceptance criteria use 5 sentence patterns for machine-checkable verification
+- **C4 + Mermaid Architecture**: Architecture diagrams in parseable Mermaid syntax
+- **MADR Decisions**: Architecture decisions with Context/Decision/Consequences
+- **DBML Data Models**: Structured data models in DSL (natural language forbidden)
+- **API-First Contracts**: Type signatures before implementation (OpenAPI, Protocol, Trait)
 - **Risk-based testing**: Property tests by default for broad input domains; fuzzing and benchmarks conditional
 - **Template identity alignment**: Renames generic scaffold names to project-matching identifiers
 - **Source requirement normalization**: Converts arbitrary-format input into a structured requirement ledger
@@ -146,9 +197,35 @@ Key principles:
 - **Architecture decisions are binding**: Executes the approved design; does not invent a different architecture
 - **Escalation over thrashing**: 3 consecutive failures → suspend task + DCR packet to `/pb-refine`
 
+### 5. `/pb-improve` — Codebase Audit & Plan Generation
+
+Audits any codebase and writes self-contained implementation plans for other agents to execute. The skill never modifies source code — only produces plans under `plans/`.
+
+```text
+/pb-improve                        full audit → prioritized findings → plans
+/pb-improve quick                  cheap pass: hotspots, top findings only
+/pb-improve deep                   exhaustive: every package, every category
+/pb-improve security               focused audit (also: perf, tests, bugs, ...)
+/pb-improve branch                 audit only what the current branch changes
+/pb-improve next                   feature suggestions — where to take the project
+/pb-improve plan <description>     skip the audit, spec one thing
+/pb-improve review-plan <file>     critique and tighten an existing plan
+/pb-improve execute <plan>         dispatch a cheaper executor, review its work
+/pb-improve reconcile              refresh the backlog: verify, unblock, retire
+/pb-improve ... --issues           also publish plans as GitHub issues
+```
+
+How it works:
+
+1. **Recon** — Maps the repo: stack, conventions, build/test/lint commands (verification gates).
+2. **Audit** — Fans out parallel subagents across 9 categories: correctness, security, performance, test coverage, tech debt, dependencies, DX, docs, direction.
+3. **Vet** — Re-reads every cited location to drop false positives and correct mis-attributions.
+4. **Prioritize** — Findings ordered by leverage (impact ÷ effort, weighted by confidence).
+5. **Plan** — One file per selected finding in `plans/` with self-contained context, verification gates, and STOP conditions.
+
 ## Design Philosophy: Agent Harness
 
-pb-spec's design is inspired by Anthropic's research on [Effective Harnesses for Long-Running Agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents). Core idea: place AI agents inside a strict, observable, recoverable execution environment.
+pb-spec's design is inspired by Anthropic's research on [Effective Harnesses for Long-Running Agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) and the [Superpowers](https://github.com/obra/superpowers) methodology. Core idea: place AI agents inside a strict, observable, recoverable execution environment.
 
 | Principle | How pb-spec Implements It |
 |---|---|
@@ -161,6 +238,9 @@ pb-spec's design is inspired by Anthropic's research on [Effective Harnesses for
 | **Observability as Context** | Task verification includes runtime signals (logs/health) |
 | **Escalation Loop** | 3 consecutive failures → DCR handoff to `pb-refine` |
 | **Generator/Evaluator Isolation** | Generator builds; Evaluator judges with fresh context |
+| **Evidence Before Claims** | `pb-verification-before-completion`: no success claims without fresh verification |
+| **Systematic Debugging** | `pb-systematic-debugging`: root cause before fixes, scientific method |
+| **Skill Auto-Triggering** | `using-pb-spec` bootstrap ensures skills activate at the right moments |
 
 ## License
 

docs/contract.md

@@ -105,11 +105,14 @@ Note: Complexity levels (lightweight, medium, high) are orthogonal to mode. Both
 The following sections are required for a build-eligible full-mode `design.md`:
 
 1. `Executive Summary`
-2. `Requirements & Goals`
-3. `Architecture Overview`
-4. `Detailed Design`
-5. `Verification & Testing Strategy`
-6. `Implementation Plan`
+2. `Requirements & Goals` — must use **EARS (Easy Approach to Requirements Syntax)** notation with 5 sentence patterns (Ubiquitous, State-driven, Event-driven, Unwanted, Exception)
+3. `Architecture Overview` — must use **C4 Model** rendered in **Mermaid.js** syntax (Context, Container, Component diagrams)
+4. `Architecture Decisions` — must use **MADR (Markdown Any Decision Records)** format with `[Context]`, `[Decision]`, `[Consequences]`
+5. `Data Models` — must use **DBML** or **Prisma Schema** DSL (natural language table descriptions forbidden)
+6. `Interface Contracts` — must use **API-First** type signatures (OpenAPI YAML for external APIs, language-native type syntax for internal modules)
+7. `Detailed Design`
+8. `Verification & Testing Strategy`
+9. `Implementation Plan`
 
 ### 6.3 Conditional Sections for Full Mode
 
@@ -131,7 +134,7 @@ A lightweight `design.md` must still include:
 
 1. `Summary`
 2. `Approach`
-3. `Architecture Decisions`
+3. `Architecture Decisions` — must use **MADR** format even in lightweight mode
 4. `BDD/TDD Strategy`
 5. `Code Simplification Constraints`
 6. `BDD Scenario Inventory`
@@ -140,6 +143,8 @@ A lightweight `design.md` must still include:
 
 Lightweight mode may omit the full-mode `Detailed Design` and `Implementation Plan` sections as standalone top-level sections if the same information is captured compactly in the required lightweight sections.
 
+Lightweight mode may also omit C4 diagrams, DBML/Prisma schemas, and full API contracts when the change is too small to warrant them — but Architecture Decisions must still use MADR format.
+
 ### 6.5 Lightweight-to-Full Mapping
 
 For validation purposes, lightweight mode satisfies the full contract through the following mapping:
@@ -166,6 +171,14 @@ For validation purposes:
 - a section may satisfy a conditional requirement by explicitly stating why it is `N/A`
 - repo-specific standards must be grounded in actual repo docs or code, not generic boilerplate
 
+**Format-specific validation rules:**
+
+- **EARS Requirements:** Each requirement must use one of the 5 EARS patterns (Ubiquitous, State-driven, Event-driven, Unwanted, Exception). Requirements written as vague goals ("the system should be fast") are invalid.
+- **C4/Mermaid Architecture:** Architecture sections must contain at least one ````mermaid` code block. Natural language architecture descriptions alone do not satisfy the Architecture Overview requirement.
+- **MADR Decisions:** Each Architecture Decision must have `Context`, `Decision`, and `Consequences` subsections. Decisions without consequences are incomplete.
+- **DBML/Prisma Data Models:** Data model sections must use DBML or Prisma Schema syntax inside a fenced code block. Natural language table descriptions ("users table has an id and name") are invalid.
+- **API-First Contracts:** Interface sections must use type signatures (OpenAPI YAML, TypeScript interfaces, Python Protocols, Rust traits). Narrative API descriptions without type definitions are invalid.
+
 ## 7. `tasks.md` Contract
 
 ### 7.1 Task File Structure